From 58af04dff742b6b49fae3de585bdea8c77b62ddc Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 19 Oct 2016 13:44:37 +0300 Subject: Documentation/sphinx: rename kernel-doc.py to kerneldoc.py Python module names should not have hyphens per [PEP 8]. Drop the hyphen from kernel-doc.py. The extension directive remains unchanged. [PEP 8] https://www.python.org/dev/peps/pep-0008/#package-and-module-names Reported-by: Markus Heiser Signed-off-by: Jani Nikula Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 2 +- Documentation/sphinx/kernel-doc.py | 149 ------------------------------------- Documentation/sphinx/kerneldoc.py | 149 +++++++++++++++++++++++++++++++++++++ 3 files changed, 150 insertions(+), 150 deletions(-) delete mode 100644 Documentation/sphinx/kernel-doc.py create mode 100644 Documentation/sphinx/kerneldoc.py diff --git a/Documentation/conf.py b/Documentation/conf.py index bf6f310e5170..4db1993658ea 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -34,7 +34,7 @@ from load_config import loadConfig # 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', 'kernel_include', 'cdomain'] +extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain'] # The name of the math extension changed on Sphinx 1.4 if minor > 3: diff --git a/Documentation/sphinx/kernel-doc.py b/Documentation/sphinx/kernel-doc.py deleted file mode 100644 index d15e07f36881..000000000000 --- a/Documentation/sphinx/kernel-doc.py +++ /dev/null @@ -1,149 +0,0 @@ -# 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 -# -# 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 - -__version__ = '1.0' - -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) - - return dict( - version = __version__, - parallel_read_safe = True, - parallel_write_safe = True - ) diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py new file mode 100644 index 000000000000..d15e07f36881 --- /dev/null +++ b/Documentation/sphinx/kerneldoc.py @@ -0,0 +1,149 @@ +# 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 +# +# 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 + +__version__ = '1.0' + +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) + + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) -- cgit v1.2.3 From 7058763b3f1ca6086d2be8f23a6c2a7c645077f2 Mon Sep 17 00:00:00 2001 From: Marcin Nowakowski Date: Thu, 6 Oct 2016 09:52:12 +0200 Subject: Documentation/trace/uprobetracer.txt: fix incorrect examples Current uprobetracer examples don't work as they use an incorrect syntax - if no event name is specified then 'p/r' must not be followed by a colon - if no event name is specified then the default event name will have a 'p_' prefix, so use that in the '-' example as well Signed-off-by: Marcin Nowakowski Signed-off-by: Jonathan Corbet --- Documentation/trace/uprobetracer.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/trace/uprobetracer.txt b/Documentation/trace/uprobetracer.txt index 94b6b4581763..fa7b680ee8a0 100644 --- a/Documentation/trace/uprobetracer.txt +++ b/Documentation/trace/uprobetracer.txt @@ -76,15 +76,15 @@ Usage examples * Add a probe as a new uprobe event, write a new definition to uprobe_events as below: (sets a uprobe at an offset of 0x4245c0 in the executable /bin/bash) - echo 'p: /bin/bash:0x4245c0' > /sys/kernel/debug/tracing/uprobe_events + echo 'p /bin/bash:0x4245c0' > /sys/kernel/debug/tracing/uprobe_events * Add a probe as a new uretprobe event: - echo 'r: /bin/bash:0x4245c0' > /sys/kernel/debug/tracing/uprobe_events + echo 'r /bin/bash:0x4245c0' > /sys/kernel/debug/tracing/uprobe_events * Unset registered event: - echo '-:bash_0x4245c0' >> /sys/kernel/debug/tracing/uprobe_events + echo '-:p_bash_0x4245c0' >> /sys/kernel/debug/tracing/uprobe_events * Print out the events that are registered: -- cgit v1.2.3 From 5ac9baf47a571d74c995529b2f7ded8348389e10 Mon Sep 17 00:00:00 2001 From: Masanari Iida Date: Mon, 17 Oct 2016 21:17:10 +0900 Subject: Doc: dm raid: Fix typo in dm-raid.txt This patch fix spelling typos in Documentation/device-mapper/dm-raid.txt. Signed-off-by: Masanari Iida Signed-off-by: Jonathan Corbet --- Documentation/device-mapper/dm-raid.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/device-mapper/dm-raid.txt b/Documentation/device-mapper/dm-raid.txt index e5b6497116f4..89ecc8021178 100644 --- a/Documentation/device-mapper/dm-raid.txt +++ b/Documentation/device-mapper/dm-raid.txt @@ -17,7 +17,7 @@ The target is named "raid" and it accepts the following parameters: raid0 RAID0 striping (no resilience) raid1 RAID1 mirroring raid4 RAID4 with dedicated last parity disk - raid5_n RAID5 with dedicated last parity disk suporting takeover + raid5_n RAID5 with dedicated last parity disk supporting takeover Same as raid4 -Transitory layout raid5_la RAID5 left asymmetric @@ -36,7 +36,7 @@ The target is named "raid" and it accepts the following parameters: - rotating parity N (right-to-left) with data continuation raid6_n_6 RAID6 with dedicate parity disks - parity and Q-syndrome on the last 2 disks; - laylout for takeover from/to raid4/raid5_n + layout for takeover from/to raid4/raid5_n raid6_la_6 Same as "raid_la" plus dedicated last Q-syndrome disk - layout for takeover from raid5_la from/to raid6 raid6_ra_6 Same as "raid5_ra" dedicated last Q-syndrome disk @@ -137,8 +137,8 @@ The target is named "raid" and it accepts the following parameters: device removal (negative value) or device addition (positive value) to any reshape supporting raid levels 4/5/6 and 10. RAID levels 4/5/6 allow for addition of devices (metadata - and data device tupel), raid10_near and raid10_offset only - allow for device addtion. raid10_far does not support any + and data device tuple), raid10_near and raid10_offset only + allow for device addition. raid10_far does not support any reshaping at all. A minimum of devices have to be kept to enforce resilience, which is 3 devices for raid4/5 and 4 devices for raid6. -- cgit v1.2.3 From a164a8a6635469b653fa132a3ec283df6bc147f4 Mon Sep 17 00:00:00 2001 From: Stephen Hemminger Date: Mon, 17 Oct 2016 12:33:19 -0700 Subject: doc: add documentation for uio-hv-generic Update UIO documentation to include basic information about uio_hv_generic. Signed-off-by: Stephen Hemminger Signed-off-by: Jonathan Corbet --- Documentation/DocBook/uio-howto.tmpl | 62 ++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index cd0e452dfed5..5210f8a577c6 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -45,6 +45,13 @@ GPL version 2. + + 0.10 + 2016-10-17 + sch + Added generic hyperv driver + + 0.9 2009-07-16 @@ -1033,6 +1040,61 @@ int main() + + +Generic Hyper-V UIO driver + + The generic driver is a kernel module named uio_hv_generic. + It supports devices on the Hyper-V VMBus similar to uio_pci_generic + on PCI bus. + + + +Making the driver recognize the device + +Since the driver does not declare any device GUID's, it will not get loaded +automatically and will not automatically bind to any devices, you must load it +and allocate id to the driver yourself. For example, to use the network device +GUID: + + modprobe uio_hv_generic + echo "f8615163-df3e-46c5-913f-f2d2f965ed0e" > /sys/bus/vmbus/drivers/uio_hv_generic/new_id + + + +If there already is a hardware specific kernel driver for the device, the +generic driver still won't bind to it, in this case if you want to use the +generic driver (why would you?) you'll have to manually unbind the hardware +specific driver and bind the generic driver, like this: + + echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/hv_netvsc/unbind + echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 > /sys/bus/vmbus/drivers/uio_hv_generic/bind + + + +You can verify that the device has been bound to the driver +by looking for it in sysfs, for example like the following: + + ls -l /sys/bus/vmbus/devices/vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver + +Which if successful should print + + .../vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver -> ../../../bus/vmbus/drivers/uio_hv_generic + + + + + +Things to know about uio_hv_generic + +On each interrupt, uio_hv_generic sets the Interrupt Disable bit. +This prevents the device from generating further interrupts +until the bit is cleared. The userspace driver should clear this +bit before blocking and waiting for more interrupts. + + + + Further information -- cgit v1.2.3 From 5d812b47a668f539f763a9e95167fd2bdf488a7a Mon Sep 17 00:00:00 2001 From: Masanari Iida Date: Fri, 21 Oct 2016 04:59:32 +0900 Subject: Doc: cciss: Fix a typo in cciss.txt This patch fix a spelling typo in cciss.txt Signed-off-by: Masanari Iida Acked-by: Don Brace Signed-off-by: Jonathan Corbet --- Documentation/blockdev/cciss.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/blockdev/cciss.txt b/Documentation/blockdev/cciss.txt index b79d0a13e7cd..3a5477cc456e 100644 --- a/Documentation/blockdev/cciss.txt +++ b/Documentation/blockdev/cciss.txt @@ -184,7 +184,7 @@ infrequently used and the primary purpose of Smart Array controllers is to act as a RAID controller for disk drives, so the vast majority of commands are allocated for disk devices. However, if you have more than a few tape drives attached to a smart array, the default number of commands may not be -enought (for example, if you have 8 tape drives, you could only rewind 6 +enough (for example, if you have 8 tape drives, you could only rewind 6 at one time with the default number of commands.) The cciss_tape_cmds module parameter allows more commands (up to 16 more) to be allocated for use by tape drives. For example: -- cgit v1.2.3 From 75a163c4a3ee8235072f0e1bd4875dd2443cdb8e Mon Sep 17 00:00:00 2001 From: Martyn Welch Date: Fri, 21 Oct 2016 22:15:27 +0100 Subject: vme: Convert documentation to reStructuredText, move under driver APIs Perform a relatively simple conversion of vme_api.txt to reStructuredText and move under driver-api, which seems the most logical place for this documentation. Signed-off-by: Martyn Welch Signed-off-by: Jonathan Corbet --- Documentation/driver-api/index.rst | 1 + Documentation/driver-api/vme.rst | 474 +++++++++++++++++++++++++++++++++++++ Documentation/vme_api.txt | 413 -------------------------------- MAINTAINERS | 2 +- 4 files changed, 476 insertions(+), 414 deletions(-) create mode 100644 Documentation/driver-api/vme.rst delete mode 100644 Documentation/vme_api.txt diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 8e259c5d0322..b567907db350 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -24,3 +24,4 @@ available subsections can be seen below. i2c hsi miscellaneous + vme diff --git a/Documentation/driver-api/vme.rst b/Documentation/driver-api/vme.rst new file mode 100644 index 000000000000..89776fb3c8bd --- /dev/null +++ b/Documentation/driver-api/vme.rst @@ -0,0 +1,474 @@ +VME Device Drivers +================== + +Driver registration +------------------- + +As with other subsystems within the Linux kernel, VME device drivers register +with the VME subsystem, typically called from the devices init routine. This is +achieved via a call to the following function: + +.. code-block:: c + + int vme_register_driver (struct vme_driver *driver, unsigned int ndevs); + +If driver registration is successful this function returns zero, if an error +occurred a negative error code will be returned. + +A pointer to a structure of type 'vme_driver' must be provided to the +registration function. Along with ndevs, which is the number of devices your +driver is able to support. The structure is as follows: + +.. code-block:: c + + struct vme_driver { + struct list_head node; + const char *name; + int (*match)(struct vme_dev *); + int (*probe)(struct vme_dev *); + int (*remove)(struct vme_dev *); + void (*shutdown)(void); + struct device_driver driver; + struct list_head devices; + unsigned int ndev; + }; + +At the minimum, the '.name', '.match' and '.probe' elements of this structure +should be correctly set. The '.name' element is a pointer to a string holding +the device driver's name. + +The '.match' function allows control over which VME devices should be registered +with the driver. The match function should return 1 if a device should be +probed and 0 otherwise. This example match function (from vme_user.c) limits +the number of devices probed to one: + +.. code-block:: c + + #define USER_BUS_MAX 1 + ... + static int vme_user_match(struct vme_dev *vdev) + { + if (vdev->id.num >= USER_BUS_MAX) + return 0; + return 1; + } + +The '.probe' element should contain a pointer to the probe routine. The +probe routine is passed a 'struct vme_dev' pointer as an argument. The +'struct vme_dev' structure looks like the following: + +.. code-block:: c + + struct vme_dev { + int num; + struct vme_bridge *bridge; + struct device dev; + struct list_head drv_list; + struct list_head bridge_list; + }; + +Here, the 'num' field refers to the sequential device ID for this specific +driver. The bridge number (or bus number) can be accessed using +dev->bridge->num. + +A function is also provided to unregister the driver from the VME core and is +usually called from the device driver's exit routine: + +.. code-block:: c + + void vme_unregister_driver (struct vme_driver *driver); + + +Resource management +------------------- + +Once a driver has registered with the VME core the provided match routine will +be called the number of times specified during the registration. If a match +succeeds, a non-zero value should be returned. A zero return value indicates +failure. For all successful matches, the probe routine of the corresponding +driver is called. The probe routine is passed a pointer to the devices +device structure. This pointer should be saved, it will be required for +requesting VME resources. + +The driver can request ownership of one or more master windows, slave windows +and/or dma channels. Rather than allowing the device driver to request a +specific window or DMA channel (which may be used by a different driver) this +driver allows a resource to be assigned based on the required attributes of the +driver in question: + +.. code-block:: c + + struct vme_resource * vme_master_request(struct vme_dev *dev, + u32 aspace, u32 cycle, u32 width); + + struct vme_resource * vme_slave_request(struct vme_dev *dev, u32 aspace, + u32 cycle); + + struct vme_resource *vme_dma_request(struct vme_dev *dev, u32 route); + +For slave windows these attributes are split into the VME address spaces that +need to be accessed in 'aspace' and VME bus cycle types required in 'cycle'. +Master windows add a further set of attributes in 'width' specifying the +required data transfer widths. These attributes are defined as bitmasks and as +such any combination of the attributes can be requested for a single window, +the core will assign a window that meets the requirements, returning a pointer +of type vme_resource that should be used to identify the allocated resource +when it is used. For DMA controllers, the request function requires the +potential direction of any transfers to be provided in the route attributes. +This is typically VME-to-MEM and/or MEM-to-VME, though some hardware can +support VME-to-VME and MEM-to-MEM transfers as well as test pattern generation. +If an unallocated window fitting the requirements can not be found a NULL +pointer will be returned. + +Functions are also provided to free window allocations once they are no longer +required. These functions should be passed the pointer to the resource provided +during resource allocation: + +.. code-block:: c + + void vme_master_free(struct vme_resource *res); + + void vme_slave_free(struct vme_resource *res); + + void vme_dma_free(struct vme_resource *res); + + +Master windows +-------------- + +Master windows provide access from the local processor[s] out onto the VME bus. +The number of windows available and the available access modes is dependent on +the underlying chipset. A window must be configured before it can be used. + + +Master window configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once a master window has been assigned the following functions can be used to +configure it and retrieve the current settings: + +.. code-block:: c + + int vme_master_set (struct vme_resource *res, int enabled, + unsigned long long base, unsigned long long size, u32 aspace, + u32 cycle, u32 width); + + int vme_master_get (struct vme_resource *res, int *enabled, + unsigned long long *base, unsigned long long *size, u32 *aspace, + u32 *cycle, u32 *width); + +The address spaces, transfer widths and cycle types are the same as described +under resource management, however some of the options are mutually exclusive. +For example, only one address space may be specified. + +These functions return 0 on success or an error code should the call fail. + + +Master window access +~~~~~~~~~~~~~~~~~~~~ + +The following functions can be used to read from and write to configured master +windows. These functions return the number of bytes copied: + +.. code-block:: c + + ssize_t vme_master_read(struct vme_resource *res, void *buf, + size_t count, loff_t offset); + + ssize_t vme_master_write(struct vme_resource *res, void *buf, + size_t count, loff_t offset); + +In addition to simple reads and writes, a function is provided to do a +read-modify-write transaction. This function returns the original value of the +VME bus location : + +.. code-block:: c + + unsigned int vme_master_rmw (struct vme_resource *res, + unsigned int mask, unsigned int compare, unsigned int swap, + loff_t offset); + +This functions by reading the offset, applying the mask. If the bits selected in +the mask match with the values of the corresponding bits in the compare field, +the value of swap is written the specified offset. + +Parts of a VME window can be mapped into user space memory using the following +function: + +.. code-block:: c + + int vme_master_mmap(struct vme_resource *resource, + struct vm_area_struct *vma) + + +Slave windows +------------- + +Slave windows provide devices on the VME bus access into mapped portions of the +local memory. The number of windows available and the access modes that can be +used is dependent on the underlying chipset. A window must be configured before +it can be used. + + +Slave window configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once a slave window has been assigned the following functions can be used to +configure it and retrieve the current settings: + +.. code-block:: c + + int vme_slave_set (struct vme_resource *res, int enabled, + unsigned long long base, unsigned long long size, + dma_addr_t mem, u32 aspace, u32 cycle); + + int vme_slave_get (struct vme_resource *res, int *enabled, + unsigned long long *base, unsigned long long *size, + dma_addr_t *mem, u32 *aspace, u32 *cycle); + +The address spaces, transfer widths and cycle types are the same as described +under resource management, however some of the options are mutually exclusive. +For example, only one address space may be specified. + +These functions return 0 on success or an error code should the call fail. + + +Slave window buffer allocation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Functions are provided to allow the user to allocate and free a contiguous +buffers which will be accessible by the VME bridge. These functions do not have +to be used, other methods can be used to allocate a buffer, though care must be +taken to ensure that they are contiguous and accessible by the VME bridge: + +.. code-block:: c + + void * vme_alloc_consistent(struct vme_resource *res, size_t size, + dma_addr_t *mem); + + void vme_free_consistent(struct vme_resource *res, size_t size, + void *virt, dma_addr_t mem); + + +Slave window access +~~~~~~~~~~~~~~~~~~~ + +Slave windows map local memory onto the VME bus, the standard methods for +accessing memory should be used. + + +DMA channels +------------ + +The VME DMA transfer provides the ability to run link-list DMA transfers. The +API introduces the concept of DMA lists. Each DMA list is a link-list which can +be passed to a DMA controller. Multiple lists can be created, extended, +executed, reused and destroyed. + + +List Management +~~~~~~~~~~~~~~~ + +The following functions are provided to create and destroy DMA lists. Execution +of a list will not automatically destroy the list, thus enabling a list to be +reused for repetitive tasks: + +.. code-block:: c + + struct vme_dma_list *vme_new_dma_list(struct vme_resource *res); + + int vme_dma_list_free(struct vme_dma_list *list); + + +List Population +~~~~~~~~~~~~~~~ + +An item can be added to a list using the following function ( the source and +destination attributes need to be created before calling this function, this is +covered under "Transfer Attributes"): + +.. code-block:: c + + int vme_dma_list_add(struct vme_dma_list *list, + struct vme_dma_attr *src, struct vme_dma_attr *dest, + size_t count); + +.. note:: + + The detailed attributes of the transfers source and destination + are not checked until an entry is added to a DMA list, the request + for a DMA channel purely checks the directions in which the + controller is expected to transfer data. As a result it is + possible for this call to return an error, for example if the + source or destination is in an unsupported VME address space. + +Transfer Attributes +~~~~~~~~~~~~~~~~~~~ + +The attributes for the source and destination are handled separately from adding +an item to a list. This is due to the diverse attributes required for each type +of source and destination. There are functions to create attributes for PCI, VME +and pattern sources and destinations (where appropriate): + +Pattern source: + +.. code-block:: c + + struct vme_dma_attr *vme_dma_pattern_attribute(u32 pattern, u32 type); + +PCI source or destination: + +.. code-block:: c + + struct vme_dma_attr *vme_dma_pci_attribute(dma_addr_t mem); + +VME source or destination: + +.. code-block:: c + + struct vme_dma_attr *vme_dma_vme_attribute(unsigned long long base, + u32 aspace, u32 cycle, u32 width); + +The following function should be used to free an attribute: + +.. code-block:: c + + void vme_dma_free_attribute(struct vme_dma_attr *attr); + + +List Execution +~~~~~~~~~~~~~~ + +The following function queues a list for execution. The function will return +once the list has been executed: + +.. code-block:: c + + int vme_dma_list_exec(struct vme_dma_list *list); + + +Interrupts +---------- + +The VME API provides functions to attach and detach callbacks to specific VME +level and status ID combinations and for the generation of VME interrupts with +specific VME level and status IDs. + + +Attaching Interrupt Handlers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following functions can be used to attach and free a specific VME level and +status ID combination. Any given combination can only be assigned a single +callback function. A void pointer parameter is provided, the value of which is +passed to the callback function, the use of this pointer is user undefined: + +.. code-block:: c + + int vme_irq_request(struct vme_dev *dev, int level, int statid, + void (*callback)(int, int, void *), void *priv); + + void vme_irq_free(struct vme_dev *dev, int level, int statid); + +The callback parameters are as follows. Care must be taken in writing a callback +function, callback functions run in interrupt context: + +.. code-block:: c + + void callback(int level, int statid, void *priv); + + +Interrupt Generation +~~~~~~~~~~~~~~~~~~~~ + +The following function can be used to generate a VME interrupt at a given VME +level and VME status ID: + +.. code-block:: c + + int vme_irq_generate(struct vme_dev *dev, int level, int statid); + + +Location monitors +----------------- + +The VME API provides the following functionality to configure the location +monitor. + + +Location Monitor Management +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following functions are provided to request the use of a block of location +monitors and to free them after they are no longer required: + +.. code-block:: c + + struct vme_resource * vme_lm_request(struct vme_dev *dev); + + void vme_lm_free(struct vme_resource * res); + +Each block may provide a number of location monitors, monitoring adjacent +locations. The following function can be used to determine how many locations +are provided: + +.. code-block:: c + + int vme_lm_count(struct vme_resource * res); + + +Location Monitor Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Once a bank of location monitors has been allocated, the following functions +are provided to configure the location and mode of the location monitor: + +.. code-block:: c + + int vme_lm_set(struct vme_resource *res, unsigned long long base, + u32 aspace, u32 cycle); + + int vme_lm_get(struct vme_resource *res, unsigned long long *base, + u32 *aspace, u32 *cycle); + + +Location Monitor Use +~~~~~~~~~~~~~~~~~~~~ + +The following functions allow a callback to be attached and detached from each +location monitor location. Each location monitor can monitor a number of +adjacent locations: + +.. code-block:: c + + int vme_lm_attach(struct vme_resource *res, int num, + void (*callback)(void *)); + + int vme_lm_detach(struct vme_resource *res, int num); + +The callback function is declared as follows. + +.. code-block:: c + + void callback(void *data); + + +Slot Detection +-------------- + +This function returns the slot ID of the provided bridge. + +.. code-block:: c + + int vme_slot_num(struct vme_dev *dev); + + +Bus Detection +------------- + +This function returns the bus ID of the provided bridge. + +.. code-block:: c + + int vme_bus_num(struct vme_dev *dev); + diff --git a/Documentation/vme_api.txt b/Documentation/vme_api.txt deleted file mode 100644 index 90006550f485..000000000000 --- a/Documentation/vme_api.txt +++ /dev/null @@ -1,413 +0,0 @@ - VME Device Driver API - ===================== - -Driver registration -=================== - -As with other subsystems within the Linux kernel, VME device drivers register -with the VME subsystem, typically called from the devices init routine. This is -achieved via a call to the following function: - - int vme_register_driver (struct vme_driver *driver, unsigned int ndevs); - -If driver registration is successful this function returns zero, if an error -occurred a negative error code will be returned. - -A pointer to a structure of type 'vme_driver' must be provided to the -registration function. Along with ndevs, which is the number of devices your -driver is able to support. The structure is as follows: - - struct vme_driver { - struct list_head node; - const char *name; - int (*match)(struct vme_dev *); - int (*probe)(struct vme_dev *); - int (*remove)(struct vme_dev *); - void (*shutdown)(void); - struct device_driver driver; - struct list_head devices; - unsigned int ndev; - }; - -At the minimum, the '.name', '.match' and '.probe' elements of this structure -should be correctly set. The '.name' element is a pointer to a string holding -the device driver's name. - -The '.match' function allows control over which VME devices should be registered -with the driver. The match function should return 1 if a device should be -probed and 0 otherwise. This example match function (from vme_user.c) limits -the number of devices probed to one: - - #define USER_BUS_MAX 1 - ... - static int vme_user_match(struct vme_dev *vdev) - { - if (vdev->id.num >= USER_BUS_MAX) - return 0; - return 1; - } - -The '.probe' element should contain a pointer to the probe routine. The -probe routine is passed a 'struct vme_dev' pointer as an argument. The -'struct vme_dev' structure looks like the following: - - struct vme_dev { - int num; - struct vme_bridge *bridge; - struct device dev; - struct list_head drv_list; - struct list_head bridge_list; - }; - -Here, the 'num' field refers to the sequential device ID for this specific -driver. The bridge number (or bus number) can be accessed using -dev->bridge->num. - -A function is also provided to unregister the driver from the VME core and is -usually called from the device driver's exit routine: - - void vme_unregister_driver (struct vme_driver *driver); - - -Resource management -=================== - -Once a driver has registered with the VME core the provided match routine will -be called the number of times specified during the registration. If a match -succeeds, a non-zero value should be returned. A zero return value indicates -failure. For all successful matches, the probe routine of the corresponding -driver is called. The probe routine is passed a pointer to the devices -device structure. This pointer should be saved, it will be required for -requesting VME resources. - -The driver can request ownership of one or more master windows, slave windows -and/or dma channels. Rather than allowing the device driver to request a -specific window or DMA channel (which may be used by a different driver) this -driver allows a resource to be assigned based on the required attributes of the -driver in question: - - struct vme_resource * vme_master_request(struct vme_dev *dev, - u32 aspace, u32 cycle, u32 width); - - struct vme_resource * vme_slave_request(struct vme_dev *dev, u32 aspace, - u32 cycle); - - struct vme_resource *vme_dma_request(struct vme_dev *dev, u32 route); - -For slave windows these attributes are split into the VME address spaces that -need to be accessed in 'aspace' and VME bus cycle types required in 'cycle'. -Master windows add a further set of attributes in 'width' specifying the -required data transfer widths. These attributes are defined as bitmasks and as -such any combination of the attributes can be requested for a single window, -the core will assign a window that meets the requirements, returning a pointer -of type vme_resource that should be used to identify the allocated resource -when it is used. For DMA controllers, the request function requires the -potential direction of any transfers to be provided in the route attributes. -This is typically VME-to-MEM and/or MEM-to-VME, though some hardware can -support VME-to-VME and MEM-to-MEM transfers as well as test pattern generation. -If an unallocated window fitting the requirements can not be found a NULL -pointer will be returned. - -Functions are also provided to free window allocations once they are no longer -required. These functions should be passed the pointer to the resource provided -during resource allocation: - - void vme_master_free(struct vme_resource *res); - - void vme_slave_free(struct vme_resource *res); - - void vme_dma_free(struct vme_resource *res); - - -Master windows -============== - -Master windows provide access from the local processor[s] out onto the VME bus. -The number of windows available and the available access modes is dependent on -the underlying chipset. A window must be configured before it can be used. - - -Master window configuration ---------------------------- - -Once a master window has been assigned the following functions can be used to -configure it and retrieve the current settings: - - int vme_master_set (struct vme_resource *res, int enabled, - unsigned long long base, unsigned long long size, u32 aspace, - u32 cycle, u32 width); - - int vme_master_get (struct vme_resource *res, int *enabled, - unsigned long long *base, unsigned long long *size, u32 *aspace, - u32 *cycle, u32 *width); - -The address spaces, transfer widths and cycle types are the same as described -under resource management, however some of the options are mutually exclusive. -For example, only one address space may be specified. - -These functions return 0 on success or an error code should the call fail. - - -Master window access --------------------- - -The following functions can be used to read from and write to configured master -windows. These functions return the number of bytes copied: - - ssize_t vme_master_read(struct vme_resource *res, void *buf, - size_t count, loff_t offset); - - ssize_t vme_master_write(struct vme_resource *res, void *buf, - size_t count, loff_t offset); - -In addition to simple reads and writes, a function is provided to do a -read-modify-write transaction. This function returns the original value of the -VME bus location : - - unsigned int vme_master_rmw (struct vme_resource *res, - unsigned int mask, unsigned int compare, unsigned int swap, - loff_t offset); - -This functions by reading the offset, applying the mask. If the bits selected in -the mask match with the values of the corresponding bits in the compare field, -the value of swap is written the specified offset. - -Parts of a VME window can be mapped into user space memory using the following -function: - - int vme_master_mmap(struct vme_resource *resource, - struct vm_area_struct *vma) - - -Slave windows -============= - -Slave windows provide devices on the VME bus access into mapped portions of the -local memory. The number of windows available and the access modes that can be -used is dependent on the underlying chipset. A window must be configured before -it can be used. - - -Slave window configuration --------------------------- - -Once a slave window has been assigned the following functions can be used to -configure it and retrieve the current settings: - - int vme_slave_set (struct vme_resource *res, int enabled, - unsigned long long base, unsigned long long size, - dma_addr_t mem, u32 aspace, u32 cycle); - - int vme_slave_get (struct vme_resource *res, int *enabled, - unsigned long long *base, unsigned long long *size, - dma_addr_t *mem, u32 *aspace, u32 *cycle); - -The address spaces, transfer widths and cycle types are the same as described -under resource management, however some of the options are mutually exclusive. -For example, only one address space may be specified. - -These functions return 0 on success or an error code should the call fail. - - -Slave window buffer allocation ------------------------------- - -Functions are provided to allow the user to allocate and free a contiguous -buffers which will be accessible by the VME bridge. These functions do not have -to be used, other methods can be used to allocate a buffer, though care must be -taken to ensure that they are contiguous and accessible by the VME bridge: - - void * vme_alloc_consistent(struct vme_resource *res, size_t size, - dma_addr_t *mem); - - void vme_free_consistent(struct vme_resource *res, size_t size, - void *virt, dma_addr_t mem); - - -Slave window access -------------------- - -Slave windows map local memory onto the VME bus, the standard methods for -accessing memory should be used. - - -DMA channels -============ - -The VME DMA transfer provides the ability to run link-list DMA transfers. The -API introduces the concept of DMA lists. Each DMA list is a link-list which can -be passed to a DMA controller. Multiple lists can be created, extended, -executed, reused and destroyed. - - -List Management ---------------- - -The following functions are provided to create and destroy DMA lists. Execution -of a list will not automatically destroy the list, thus enabling a list to be -reused for repetitive tasks: - - struct vme_dma_list *vme_new_dma_list(struct vme_resource *res); - - int vme_dma_list_free(struct vme_dma_list *list); - - -List Population ---------------- - -An item can be added to a list using the following function ( the source and -destination attributes need to be created before calling this function, this is -covered under "Transfer Attributes"): - - int vme_dma_list_add(struct vme_dma_list *list, - struct vme_dma_attr *src, struct vme_dma_attr *dest, - size_t count); - -NOTE: The detailed attributes of the transfers source and destination - are not checked until an entry is added to a DMA list, the request - for a DMA channel purely checks the directions in which the - controller is expected to transfer data. As a result it is - possible for this call to return an error, for example if the - source or destination is in an unsupported VME address space. - -Transfer Attributes -------------------- - -The attributes for the source and destination are handled separately from adding -an item to a list. This is due to the diverse attributes required for each type -of source and destination. There are functions to create attributes for PCI, VME -and pattern sources and destinations (where appropriate): - -Pattern source: - - struct vme_dma_attr *vme_dma_pattern_attribute(u32 pattern, u32 type); - -PCI source or destination: - - struct vme_dma_attr *vme_dma_pci_attribute(dma_addr_t mem); - -VME source or destination: - - struct vme_dma_attr *vme_dma_vme_attribute(unsigned long long base, - u32 aspace, u32 cycle, u32 width); - -The following function should be used to free an attribute: - - void vme_dma_free_attribute(struct vme_dma_attr *attr); - - -List Execution --------------- - -The following function queues a list for execution. The function will return -once the list has been executed: - - int vme_dma_list_exec(struct vme_dma_list *list); - - -Interrupts -========== - -The VME API provides functions to attach and detach callbacks to specific VME -level and status ID combinations and for the generation of VME interrupts with -specific VME level and status IDs. - - -Attaching Interrupt Handlers ----------------------------- - -The following functions can be used to attach and free a specific VME level and -status ID combination. Any given combination can only be assigned a single -callback function. A void pointer parameter is provided, the value of which is -passed to the callback function, the use of this pointer is user undefined: - - int vme_irq_request(struct vme_dev *dev, int level, int statid, - void (*callback)(int, int, void *), void *priv); - - void vme_irq_free(struct vme_dev *dev, int level, int statid); - -The callback parameters are as follows. Care must be taken in writing a callback -function, callback functions run in interrupt context: - - void callback(int level, int statid, void *priv); - - -Interrupt Generation --------------------- - -The following function can be used to generate a VME interrupt at a given VME -level and VME status ID: - - int vme_irq_generate(struct vme_dev *dev, int level, int statid); - - -Location monitors -================= - -The VME API provides the following functionality to configure the location -monitor. - - -Location Monitor Management ---------------------------- - -The following functions are provided to request the use of a block of location -monitors and to free them after they are no longer required: - - struct vme_resource * vme_lm_request(struct vme_dev *dev); - - void vme_lm_free(struct vme_resource * res); - -Each block may provide a number of location monitors, monitoring adjacent -locations. The following function can be used to determine how many locations -are provided: - - int vme_lm_count(struct vme_resource * res); - - -Location Monitor Configuration ------------------------------- - -Once a bank of location monitors has been allocated, the following functions -are provided to configure the location and mode of the location monitor: - - int vme_lm_set(struct vme_resource *res, unsigned long long base, - u32 aspace, u32 cycle); - - int vme_lm_get(struct vme_resource *res, unsigned long long *base, - u32 *aspace, u32 *cycle); - - -Location Monitor Use --------------------- - -The following functions allow a callback to be attached and detached from each -location monitor location. Each location monitor can monitor a number of -adjacent locations: - - int vme_lm_attach(struct vme_resource *res, int num, - void (*callback)(void *)); - - int vme_lm_detach(struct vme_resource *res, int num); - -The callback function is declared as follows. - - void callback(void *data); - - -Slot Detection -============== - -This function returns the slot ID of the provided bridge. - - int vme_slot_num(struct vme_dev *dev); - - -Bus Detection -============= - -This function returns the bus ID of the provided bridge. - - int vme_bus_num(struct vme_dev *dev); - - diff --git a/MAINTAINERS b/MAINTAINERS index 1cd38a7e0064..de0451df542f 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -12877,7 +12877,7 @@ M: Greg Kroah-Hartman L: devel@driverdev.osuosl.org S: Maintained T: git git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-core.git -F: Documentation/vme_api.txt +F: Documentation/driver-api/vme.rst F: drivers/staging/vme/ F: drivers/vme/ F: include/linux/vme* -- cgit v1.2.3 From 3a61baddcec3e7873b49deb5804d3d6f39b92def Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 10:04:16 -0300 Subject: Documentation/applying-patches.txt: fix a bad external link We can't use :ref: for external links. Signed-off-by: Mauro Carvalho Chehab --- Documentation/applying-patches.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/applying-patches.txt b/Documentation/applying-patches.txt index 02ce4924468e..3395da13d415 100644 --- a/Documentation/applying-patches.txt +++ b/Documentation/applying-patches.txt @@ -427,7 +427,7 @@ The -mm patches are experimental patches released by Andrew Morton. In the past, -mm tree were used to also test subsystem patches, but this function is now done via the -:ref:`linux-next ` +`linux-next ` tree. The Subsystem maintainers push their patches first to linux-next, and, during the merge window, sends them directly to Linus. -- cgit v1.2.3 From 12983bcd822f5c13a0f350cc97bc9fb781cae944 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 13:14:35 -0300 Subject: Documentation/adding-syscalls.txt: convert it to ReST markup Convert adding-syscalls.txt to ReST markup and add it to the development-process book: - add extra lines to make Sphinx to correctly parse paragraphs; - use quote blocks for examples; - use monotonic font for dirs, function calls, etc; - mark manpage pages using the right markup; - add cross-reference to SubmittingPatches. Signed-off-by: Mauro Carvalho Chehab --- Documentation/adding-syscalls.txt | 527 ------------------------------------ Documentation/adding-syscals.txt | 542 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 542 insertions(+), 527 deletions(-) delete mode 100644 Documentation/adding-syscalls.txt create mode 100644 Documentation/adding-syscals.txt diff --git a/Documentation/adding-syscalls.txt b/Documentation/adding-syscalls.txt deleted file mode 100644 index bbb31e091b28..000000000000 --- a/Documentation/adding-syscalls.txt +++ /dev/null @@ -1,527 +0,0 @@ -Adding a New System Call -======================== - -This document describes what's involved in adding a new system call to the -Linux kernel, over and above the normal submission advice in -Documentation/SubmittingPatches. - - -System Call Alternatives ------------------------- - -The first thing to consider when adding a new system call is whether one of -the alternatives might be suitable instead. Although system calls are the -most traditional and most obvious interaction points between userspace and the -kernel, there are other possibilities -- choose what fits best for your -interface. - - - If the operations involved can be made to look like a filesystem-like - object, it may make more sense to create a new filesystem or device. This - also makes it easier to encapsulate the new functionality in a kernel module - rather than requiring it to be built into the main kernel. - - If the new functionality involves operations where the kernel notifies - userspace that something has happened, then returning a new file - descriptor for the relevant object allows userspace to use - poll/select/epoll to receive that notification. - - However, operations that don't map to read(2)/write(2)-like operations - have to be implemented as ioctl(2) requests, which can lead to a - somewhat opaque API. - - If you're just exposing runtime system information, a new node in sysfs - (see Documentation/filesystems/sysfs.txt) or the /proc filesystem may be - more appropriate. However, access to these mechanisms requires that the - relevant filesystem is mounted, which might not always be the case (e.g. - in a namespaced/sandboxed/chrooted environment). Avoid adding any API to - debugfs, as this is not considered a 'production' interface to userspace. - - If the operation is specific to a particular file or file descriptor, then - an additional fcntl(2) command option may be more appropriate. However, - fcntl(2) is a multiplexing system call that hides a lot of complexity, so - this option is best for when the new function is closely analogous to - existing fcntl(2) functionality, or the new functionality is very simple - (for example, getting/setting a simple flag related to a file descriptor). - - If the operation is specific to a particular task or process, then an - additional prctl(2) command option may be more appropriate. As with - fcntl(2), this system call is a complicated multiplexor so is best reserved - for near-analogs of existing prctl() commands or getting/setting a simple - flag related to a process. - - -Designing the API: Planning for Extension ------------------------------------------ - -A new system call forms part of the API of the kernel, and has to be supported -indefinitely. As such, it's a very good idea to explicitly discuss the -interface on the kernel mailing list, and it's important to plan for future -extensions of the interface. - -(The syscall table is littered with historical examples where this wasn't done, -together with the corresponding follow-up system calls -- eventfd/eventfd2, -dup2/dup3, inotify_init/inotify_init1, pipe/pipe2, renameat/renameat2 -- so -learn from the history of the kernel and plan for extensions from the start.) - -For simpler system calls that only take a couple of arguments, the preferred -way to allow for future extensibility is to include a flags argument to the -system call. To make sure that userspace programs can safely use flags -between kernel versions, check whether the flags value holds any unknown -flags, and reject the system call (with EINVAL) if it does: - - if (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3)) - return -EINVAL; - -(If no flags values are used yet, check that the flags argument is zero.) - -For more sophisticated system calls that involve a larger number of arguments, -it's preferred to encapsulate the majority of the arguments into a structure -that is passed in by pointer. Such a structure can cope with future extension -by including a size argument in the structure: - - struct xyzzy_params { - u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */ - u32 param_1; - u64 param_2; - u64 param_3; - }; - -As long as any subsequently added field, say param_4, is designed so that a -zero value gives the previous behaviour, then this allows both directions of -version mismatch: - - - To cope with a later userspace program calling an older kernel, the kernel - code should check that any memory beyond the size of the structure that it - expects is zero (effectively checking that param_4 == 0). - - To cope with an older userspace program calling a newer kernel, the kernel - code can zero-extend a smaller instance of the structure (effectively - setting param_4 = 0). - -See perf_event_open(2) and the perf_copy_attr() function (in -kernel/events/core.c) for an example of this approach. - - -Designing the API: Other Considerations ---------------------------------------- - -If your new system call allows userspace to refer to a kernel object, it -should use a file descriptor as the handle for that object -- don't invent a -new type of userspace object handle when the kernel already has mechanisms and -well-defined semantics for using file descriptors. - -If your new xyzzy(2) system call does return a new file descriptor, then the -flags argument should include a value that is equivalent to setting O_CLOEXEC -on the new FD. This makes it possible for userspace to close the timing -window between xyzzy() and calling fcntl(fd, F_SETFD, FD_CLOEXEC), where an -unexpected fork() and execve() in another thread could leak a descriptor to -the exec'ed program. (However, resist the temptation to re-use the actual value -of the O_CLOEXEC constant, as it is architecture-specific and is part of a -numbering space of O_* flags that is fairly full.) - -If your system call returns a new file descriptor, you should also consider -what it means to use the poll(2) family of system calls on that file -descriptor. Making a file descriptor ready for reading or writing is the -normal way for the kernel to indicate to userspace that an event has -occurred on the corresponding kernel object. - -If your new xyzzy(2) system call involves a filename argument: - - int sys_xyzzy(const char __user *path, ..., unsigned int flags); - -you should also consider whether an xyzzyat(2) version is more appropriate: - - int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags); - -This allows more flexibility for how userspace specifies the file in question; -in particular it allows userspace to request the functionality for an -already-opened file descriptor using the AT_EMPTY_PATH flag, effectively giving -an fxyzzy(3) operation for free: - - - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...) - - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...) - -(For more details on the rationale of the *at() calls, see the openat(2) man -page; for an example of AT_EMPTY_PATH, see the fstatat(2) man page.) - -If your new xyzzy(2) system call involves a parameter describing an offset -within a file, make its type loff_t so that 64-bit offsets can be supported -even on 32-bit architectures. - -If your new xyzzy(2) system call involves privileged functionality, it needs -to be governed by the appropriate Linux capability bit (checked with a call to -capable()), as described in the capabilities(7) man page. Choose an existing -capability bit that governs related functionality, but try to avoid combining -lots of only vaguely related functions together under the same bit, as this -goes against capabilities' purpose of splitting the power of root. In -particular, avoid adding new uses of the already overly-general CAP_SYS_ADMIN -capability. - -If your new xyzzy(2) system call manipulates a process other than the calling -process, it should be restricted (using a call to ptrace_may_access()) so that -only a calling process with the same permissions as the target process, or -with the necessary capabilities, can manipulate the target process. - -Finally, be aware that some non-x86 architectures have an easier time if -system call parameters that are explicitly 64-bit fall on odd-numbered -arguments (i.e. parameter 1, 3, 5), to allow use of contiguous pairs of 32-bit -registers. (This concern does not apply if the arguments are part of a -structure that's passed in by pointer.) - - -Proposing the API ------------------ - -To make new system calls easy to review, it's best to divide up the patchset -into separate chunks. These should include at least the following items as -distinct commits (each of which is described further below): - - - The core implementation of the system call, together with prototypes, - generic numbering, Kconfig changes and fallback stub implementation. - - Wiring up of the new system call for one particular architecture, usually - x86 (including all of x86_64, x86_32 and x32). - - A demonstration of the use of the new system call in userspace via a - selftest in tools/testing/selftests/. - - A draft man-page for the new system call, either as plain text in the - cover letter, or as a patch to the (separate) man-pages repository. - -New system call proposals, like any change to the kernel's API, should always -be cc'ed to linux-api@vger.kernel.org. - - -Generic System Call Implementation ----------------------------------- - -The main entry point for your new xyzzy(2) system call will be called -sys_xyzzy(), but you add this entry point with the appropriate -SYSCALL_DEFINEn() macro rather than explicitly. The 'n' indicates the number -of arguments to the system call, and the macro takes the system call name -followed by the (type, name) pairs for the parameters as arguments. Using -this macro allows metadata about the new system call to be made available for -other tools. - -The new entry point also needs a corresponding function prototype, in -include/linux/syscalls.h, marked as asmlinkage to match the way that system -calls are invoked: - - asmlinkage long sys_xyzzy(...); - -Some architectures (e.g. x86) have their own architecture-specific syscall -tables, but several other architectures share a generic syscall table. Add your -new system call to the generic list by adding an entry to the list in -include/uapi/asm-generic/unistd.h: - - #define __NR_xyzzy 292 - __SYSCALL(__NR_xyzzy, sys_xyzzy) - -Also update the __NR_syscalls count to reflect the additional system call, and -note that if multiple new system calls are added in the same merge window, -your new syscall number may get adjusted to resolve conflicts. - -The file kernel/sys_ni.c provides a fallback stub implementation of each system -call, returning -ENOSYS. Add your new system call here too: - - cond_syscall(sys_xyzzy); - -Your new kernel functionality, and the system call that controls it, should -normally be optional, so add a CONFIG option (typically to init/Kconfig) for -it. As usual for new CONFIG options: - - - Include a description of the new functionality and system call controlled - by the option. - - Make the option depend on EXPERT if it should be hidden from normal users. - - Make any new source files implementing the function dependent on the CONFIG - option in the Makefile (e.g. "obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.c"). - - Double check that the kernel still builds with the new CONFIG option turned - off. - -To summarize, you need a commit that includes: - - - CONFIG option for the new function, normally in init/Kconfig - - SYSCALL_DEFINEn(xyzzy, ...) for the entry point - - corresponding prototype in include/linux/syscalls.h - - generic table entry in include/uapi/asm-generic/unistd.h - - fallback stub in kernel/sys_ni.c - - -x86 System Call Implementation ------------------------------- - -To wire up your new system call for x86 platforms, you need to update the -master syscall tables. Assuming your new system call isn't special in some -way (see below), this involves a "common" entry (for x86_64 and x32) in -arch/x86/entry/syscalls/syscall_64.tbl: - - 333 common xyzzy sys_xyzzy - -and an "i386" entry in arch/x86/entry/syscalls/syscall_32.tbl: - - 380 i386 xyzzy sys_xyzzy - -Again, these numbers are liable to be changed if there are conflicts in the -relevant merge window. - - -Compatibility System Calls (Generic) ------------------------------------- - -For most system calls the same 64-bit implementation can be invoked even when -the userspace program is itself 32-bit; even if the system call's parameters -include an explicit pointer, this is handled transparently. - -However, there are a couple of situations where a compatibility layer is -needed to cope with size differences between 32-bit and 64-bit. - -The first is if the 64-bit kernel also supports 32-bit userspace programs, and -so needs to parse areas of (__user) memory that could hold either 32-bit or -64-bit values. In particular, this is needed whenever a system call argument -is: - - - a pointer to a pointer - - a pointer to a struct containing a pointer (e.g. struct iovec __user *) - - a pointer to a varying sized integral type (time_t, off_t, long, ...) - - a pointer to a struct containing a varying sized integral type. - -The second situation that requires a compatibility layer is if one of the -system call's arguments has a type that is explicitly 64-bit even on a 32-bit -architecture, for example loff_t or __u64. In this case, a value that arrives -at a 64-bit kernel from a 32-bit application will be split into two 32-bit -values, which then need to be re-assembled in the compatibility layer. - -(Note that a system call argument that's a pointer to an explicit 64-bit type -does *not* need a compatibility layer; for example, splice(2)'s arguments of -type loff_t __user * do not trigger the need for a compat_ system call.) - -The compatibility version of the system call is called compat_sys_xyzzy(), and -is added with the COMPAT_SYSCALL_DEFINEn() macro, analogously to -SYSCALL_DEFINEn. This version of the implementation runs as part of a 64-bit -kernel, but expects to receive 32-bit parameter values and does whatever is -needed to deal with them. (Typically, the compat_sys_ version converts the -values to 64-bit versions and either calls on to the sys_ version, or both of -them call a common inner implementation function.) - -The compat entry point also needs a corresponding function prototype, in -include/linux/compat.h, marked as asmlinkage to match the way that system -calls are invoked: - - asmlinkage long compat_sys_xyzzy(...); - -If the system call involves a structure that is laid out differently on 32-bit -and 64-bit systems, say struct xyzzy_args, then the include/linux/compat.h -header file should also include a compat version of the structure (struct -compat_xyzzy_args) where each variable-size field has the appropriate compat_ -type that corresponds to the type in struct xyzzy_args. The -compat_sys_xyzzy() routine can then use this compat_ structure to parse the -arguments from a 32-bit invocation. - -For example, if there are fields: - - struct xyzzy_args { - const char __user *ptr; - __kernel_long_t varying_val; - u64 fixed_val; - /* ... */ - }; - -in struct xyzzy_args, then struct compat_xyzzy_args would have: - - struct compat_xyzzy_args { - compat_uptr_t ptr; - compat_long_t varying_val; - u64 fixed_val; - /* ... */ - }; - -The generic system call list also needs adjusting to allow for the compat -version; the entry in include/uapi/asm-generic/unistd.h should use -__SC_COMP rather than __SYSCALL: - - #define __NR_xyzzy 292 - __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy) - -To summarize, you need: - - - a COMPAT_SYSCALL_DEFINEn(xyzzy, ...) for the compat entry point - - corresponding prototype in include/linux/compat.h - - (if needed) 32-bit mapping struct in include/linux/compat.h - - instance of __SC_COMP not __SYSCALL in include/uapi/asm-generic/unistd.h - - -Compatibility System Calls (x86) --------------------------------- - -To wire up the x86 architecture of a system call with a compatibility version, -the entries in the syscall tables need to be adjusted. - -First, the entry in arch/x86/entry/syscalls/syscall_32.tbl gets an extra -column to indicate that a 32-bit userspace program running on a 64-bit kernel -should hit the compat entry point: - - 380 i386 xyzzy sys_xyzzy compat_sys_xyzzy - -Second, you need to figure out what should happen for the x32 ABI version of -the new system call. There's a choice here: the layout of the arguments -should either match the 64-bit version or the 32-bit version. - -If there's a pointer-to-a-pointer involved, the decision is easy: x32 is -ILP32, so the layout should match the 32-bit version, and the entry in -arch/x86/entry/syscalls/syscall_64.tbl is split so that x32 programs hit the -compatibility wrapper: - - 333 64 xyzzy sys_xyzzy - ... - 555 x32 xyzzy compat_sys_xyzzy - -If no pointers are involved, then it is preferable to re-use the 64-bit system -call for the x32 ABI (and consequently the entry in -arch/x86/entry/syscalls/syscall_64.tbl is unchanged). - -In either case, you should check that the types involved in your argument -layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or -64-bit (-m64) equivalents. - - -System Calls Returning Elsewhere --------------------------------- - -For most system calls, once the system call is complete the user program -continues exactly where it left off -- at the next instruction, with the -stack the same and most of the registers the same as before the system call, -and with the same virtual memory space. - -However, a few system calls do things differently. They might return to a -different location (rt_sigreturn) or change the memory space (fork/vfork/clone) -or even architecture (execve/execveat) of the program. - -To allow for this, the kernel implementation of the system call may need to -save and restore additional registers to the kernel stack, allowing complete -control of where and how execution continues after the system call. - -This is arch-specific, but typically involves defining assembly entry points -that save/restore additional registers and invoke the real system call entry -point. - -For x86_64, this is implemented as a stub_xyzzy entry point in -arch/x86/entry/entry_64.S, and the entry in the syscall table -(arch/x86/entry/syscalls/syscall_64.tbl) is adjusted to match: - - 333 common xyzzy stub_xyzzy - -The equivalent for 32-bit programs running on a 64-bit kernel is normally -called stub32_xyzzy and implemented in arch/x86/entry/entry_64_compat.S, -with the corresponding syscall table adjustment in -arch/x86/entry/syscalls/syscall_32.tbl: - - 380 i386 xyzzy sys_xyzzy stub32_xyzzy - -If the system call needs a compatibility layer (as in the previous section) -then the stub32_ version needs to call on to the compat_sys_ version of the -system call rather than the native 64-bit version. Also, if the x32 ABI -implementation is not common with the x86_64 version, then its syscall -table will also need to invoke a stub that calls on to the compat_sys_ -version. - -For completeness, it's also nice to set up a mapping so that user-mode Linux -still works -- its syscall table will reference stub_xyzzy, but the UML build -doesn't include arch/x86/entry/entry_64.S implementation (because UML -simulates registers etc). Fixing this is as simple as adding a #define to -arch/x86/um/sys_call_table_64.c: - - #define stub_xyzzy sys_xyzzy - - -Other Details -------------- - -Most of the kernel treats system calls in a generic way, but there is the -occasional exception that may need updating for your particular system call. - -The audit subsystem is one such special case; it includes (arch-specific) -functions that classify some special types of system call -- specifically -file open (open/openat), program execution (execve/exeveat) or socket -multiplexor (socketcall) operations. If your new system call is analogous to -one of these, then the audit system should be updated. - -More generally, if there is an existing system call that is analogous to your -new system call, it's worth doing a kernel-wide grep for the existing system -call to check there are no other special cases. - - -Testing -------- - -A new system call should obviously be tested; it is also useful to provide -reviewers with a demonstration of how user space programs will use the system -call. A good way to combine these aims is to include a simple self-test -program in a new directory under tools/testing/selftests/. - -For a new system call, there will obviously be no libc wrapper function and so -the test will need to invoke it using syscall(); also, if the system call -involves a new userspace-visible structure, the corresponding header will need -to be installed to compile the test. - -Make sure the selftest runs successfully on all supported architectures. For -example, check that it works when compiled as an x86_64 (-m64), x86_32 (-m32) -and x32 (-mx32) ABI program. - -For more extensive and thorough testing of new functionality, you should also -consider adding tests to the Linux Test Project, or to the xfstests project -for filesystem-related changes. - - https://linux-test-project.github.io/ - - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git - - -Man Page --------- - -All new system calls should come with a complete man page, ideally using groff -markup, but plain text will do. If groff is used, it's helpful to include a -pre-rendered ASCII version of the man page in the cover email for the -patchset, for the convenience of reviewers. - -The man page should be cc'ed to linux-man@vger.kernel.org -For more details, see https://www.kernel.org/doc/man-pages/patches.html - -References and Sources ----------------------- - - - LWN article from Michael Kerrisk on use of flags argument in system calls: - https://lwn.net/Articles/585415/ - - LWN article from Michael Kerrisk on how to handle unknown flags in a system - call: https://lwn.net/Articles/588444/ - - LWN article from Jake Edge describing constraints on 64-bit system call - arguments: https://lwn.net/Articles/311630/ - - Pair of LWN articles from David Drysdale that describe the system call - implementation paths in detail for v3.14: - - https://lwn.net/Articles/604287/ - - https://lwn.net/Articles/604515/ - - Architecture-specific requirements for system calls are discussed in the - syscall(2) man-page: - http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES - - Collated emails from Linus Torvalds discussing the problems with ioctl(): - http://yarchive.net/comp/linux/ioctl.html - - "How to not invent kernel interfaces", Arnd Bergmann, - http://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf - - LWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN: - https://lwn.net/Articles/486306/ - - Recommendation from Andrew Morton that all related information for a new - system call should come in the same email thread: - https://lkml.org/lkml/2014/7/24/641 - - Recommendation from Michael Kerrisk that a new system call should come with - a man page: https://lkml.org/lkml/2014/6/13/309 - - Suggestion from Thomas Gleixner that x86 wire-up should be in a separate - commit: https://lkml.org/lkml/2014/11/19/254 - - Suggestion from Greg Kroah-Hartman that it's good for new system calls to - come with a man-page & selftest: https://lkml.org/lkml/2014/3/19/710 - - Discussion from Michael Kerrisk of new system call vs. prctl(2) extension: - https://lkml.org/lkml/2014/6/3/411 - - Suggestion from Ingo Molnar that system calls that involve multiple - arguments should encapsulate those arguments in a struct, which includes a - size field for future extensibility: https://lkml.org/lkml/2015/7/30/117 - - Numbering oddities arising from (re-)use of O_* numbering space flags: - - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness - check") - - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc - conflict") - - commit bb458c644a59 ("Safer ABI for O_TMPFILE") - - Discussion from Matthew Wilcox about restrictions on 64-bit arguments: - https://lkml.org/lkml/2008/12/12/187 - - Recommendation from Greg Kroah-Hartman that unknown flags should be - policed: https://lkml.org/lkml/2014/7/17/577 - - Recommendation from Linus Torvalds that x32 system calls should prefer - compatibility with 64-bit versions rather than 32-bit versions: - https://lkml.org/lkml/2011/8/31/244 diff --git a/Documentation/adding-syscals.txt b/Documentation/adding-syscals.txt new file mode 100644 index 000000000000..f5b5b1aa51b3 --- /dev/null +++ b/Documentation/adding-syscals.txt @@ -0,0 +1,542 @@ +Adding a New System Call +======================== + +This document describes what's involved in adding a new system call to the +Linux kernel, over and above the normal submission advice in +:ref:`Documentation/SubmittingPatches `. + + +System Call Alternatives +------------------------ + +The first thing to consider when adding a new system call is whether one of +the alternatives might be suitable instead. Although system calls are the +most traditional and most obvious interaction points between userspace and the +kernel, there are other possibilities -- choose what fits best for your +interface. + + - If the operations involved can be made to look like a filesystem-like + object, it may make more sense to create a new filesystem or device. This + also makes it easier to encapsulate the new functionality in a kernel module + rather than requiring it to be built into the main kernel. + + - If the new functionality involves operations where the kernel notifies + userspace that something has happened, then returning a new file + descriptor for the relevant object allows userspace to use + ``poll``/``select``/``epoll`` to receive that notification. + - However, operations that don't map to + :manpage:`read(2)`/:manpage:`write(2)`-like operations + have to be implemented as :manpage:`ioctl(2)` requests, which can lead + to a somewhat opaque API. + + - If you're just exposing runtime system information, a new node in sysfs + (see ``Documentation/filesystems/sysfs.txt``) or the ``/proc`` filesystem may + be more appropriate. However, access to these mechanisms requires that the + relevant filesystem is mounted, which might not always be the case (e.g. + in a namespaced/sandboxed/chrooted environment). Avoid adding any API to + debugfs, as this is not considered a 'production' interface to userspace. + - If the operation is specific to a particular file or file descriptor, then + an additional :manpage:`fcntl(2)` command option may be more appropriate. However, + :manpage:`fcntl(2)` is a multiplexing system call that hides a lot of complexity, so + this option is best for when the new function is closely analogous to + existing :manpage:`fcntl(2)` functionality, or the new functionality is very simple + (for example, getting/setting a simple flag related to a file descriptor). + - If the operation is specific to a particular task or process, then an + additional :manpage:`prctl(2)` command option may be more appropriate. As + with :manpage:`fcntl(2)`, this system call is a complicated multiplexor so + is best reserved for near-analogs of existing ``prctl()`` commands or + getting/setting a simple flag related to a process. + + +Designing the API: Planning for Extension +----------------------------------------- + +A new system call forms part of the API of the kernel, and has to be supported +indefinitely. As such, it's a very good idea to explicitly discuss the +interface on the kernel mailing list, and it's important to plan for future +extensions of the interface. + +(The syscall table is littered with historical examples where this wasn't done, +together with the corresponding follow-up system calls -- +``eventfd``/``eventfd2``, ``dup2``/``dup3``, ``inotify_init``/``inotify_init1``, +``pipe``/``pipe2``, ``renameat``/``renameat2`` -- so +learn from the history of the kernel and plan for extensions from the start.) + +For simpler system calls that only take a couple of arguments, the preferred +way to allow for future extensibility is to include a flags argument to the +system call. To make sure that userspace programs can safely use flags +between kernel versions, check whether the flags value holds any unknown +flags, and reject the system call (with ``EINVAL``) if it does:: + + if (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3)) + return -EINVAL; + +(If no flags values are used yet, check that the flags argument is zero.) + +For more sophisticated system calls that involve a larger number of arguments, +it's preferred to encapsulate the majority of the arguments into a structure +that is passed in by pointer. Such a structure can cope with future extension +by including a size argument in the structure:: + + struct xyzzy_params { + u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */ + u32 param_1; + u64 param_2; + u64 param_3; + }; + +As long as any subsequently added field, say ``param_4``, is designed so that a +zero value gives the previous behaviour, then this allows both directions of +version mismatch: + + - To cope with a later userspace program calling an older kernel, the kernel + code should check that any memory beyond the size of the structure that it + expects is zero (effectively checking that ``param_4 == 0``). + - To cope with an older userspace program calling a newer kernel, the kernel + code can zero-extend a smaller instance of the structure (effectively + setting ``param_4 = 0``). + +See :manpage:`perf_event_open(2)` and the ``perf_copy_attr()`` function (in +``kernel/events/core.c``) for an example of this approach. + + +Designing the API: Other Considerations +--------------------------------------- + +If your new system call allows userspace to refer to a kernel object, it +should use a file descriptor as the handle for that object -- don't invent a +new type of userspace object handle when the kernel already has mechanisms and +well-defined semantics for using file descriptors. + +If your new :manpage:`xyzzy(2)` system call does return a new file descriptor, +then the flags argument should include a value that is equivalent to setting +``O_CLOEXEC`` on the new FD. This makes it possible for userspace to close +the timing window between ``xyzzy()`` and calling +``fcntl(fd, F_SETFD, FD_CLOEXEC)``, where an unexpected ``fork()`` and +``execve()`` in another thread could leak a descriptor to +the exec'ed program. (However, resist the temptation to re-use the actual value +of the ``O_CLOEXEC`` constant, as it is architecture-specific and is part of a +numbering space of ``O_*`` flags that is fairly full.) + +If your system call returns a new file descriptor, you should also consider +what it means to use the :manpage:`poll(2)` family of system calls on that file +descriptor. Making a file descriptor ready for reading or writing is the +normal way for the kernel to indicate to userspace that an event has +occurred on the corresponding kernel object. + +If your new :manpage:`xyzzy(2)` system call involves a filename argument:: + + int sys_xyzzy(const char __user *path, ..., unsigned int flags); + +you should also consider whether an :manpage:`xyzzyat(2)` version is more appropriate:: + + int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags); + +This allows more flexibility for how userspace specifies the file in question; +in particular it allows userspace to request the functionality for an +already-opened file descriptor using the ``AT_EMPTY_PATH`` flag, effectively +giving an :manpage:`fxyzzy(3)` operation for free:: + + - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...) + - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...) + +(For more details on the rationale of the \*at() calls, see the +:manpage:`openat(2)` man page; for an example of AT_EMPTY_PATH, see the +:manpage:`fstatat(2)` man page.) + +If your new :manpage:`xyzzy(2)` system call involves a parameter describing an +offset within a file, make its type ``loff_t`` so that 64-bit offsets can be +supported even on 32-bit architectures. + +If your new :manpage:`xyzzy(2)` system call involves privileged functionality, +it needs to be governed by the appropriate Linux capability bit (checked with +a call to ``capable()``), as described in the :manpage:`capabilities(7)` man +page. Choose an existing capability bit that governs related functionality, +but try to avoid combining lots of only vaguely related functions together +under the same bit, as this goes against capabilities' purpose of splitting +the power of root. In particular, avoid adding new uses of the already +overly-general ``CAP_SYS_ADMIN`` capability. + +If your new :manpage:`xyzzy(2)` system call manipulates a process other than +the calling process, it should be restricted (using a call to +``ptrace_may_access()``) so that only a calling process with the same +permissions as the target process, or with the necessary capabilities, can +manipulate the target process. + +Finally, be aware that some non-x86 architectures have an easier time if +system call parameters that are explicitly 64-bit fall on odd-numbered +arguments (i.e. parameter 1, 3, 5), to allow use of contiguous pairs of 32-bit +registers. (This concern does not apply if the arguments are part of a +structure that's passed in by pointer.) + + +Proposing the API +----------------- + +To make new system calls easy to review, it's best to divide up the patchset +into separate chunks. These should include at least the following items as +distinct commits (each of which is described further below): + + - The core implementation of the system call, together with prototypes, + generic numbering, Kconfig changes and fallback stub implementation. + - Wiring up of the new system call for one particular architecture, usually + x86 (including all of x86_64, x86_32 and x32). + - A demonstration of the use of the new system call in userspace via a + selftest in ``tools/testing/selftests/``. + - A draft man-page for the new system call, either as plain text in the + cover letter, or as a patch to the (separate) man-pages repository. + +New system call proposals, like any change to the kernel's API, should always +be cc'ed to linux-api@vger.kernel.org. + + +Generic System Call Implementation +---------------------------------- + +The main entry point for your new :manpage:`xyzzy(2)` system call will be called +``sys_xyzzy()``, but you add this entry point with the appropriate +``SYSCALL_DEFINEn()`` macro rather than explicitly. The 'n' indicates the +number of arguments to the system call, and the macro takes the system call name +followed by the (type, name) pairs for the parameters as arguments. Using +this macro allows metadata about the new system call to be made available for +other tools. + +The new entry point also needs a corresponding function prototype, in +``include/linux/syscalls.h``, marked as asmlinkage to match the way that system +calls are invoked:: + + asmlinkage long sys_xyzzy(...); + +Some architectures (e.g. x86) have their own architecture-specific syscall +tables, but several other architectures share a generic syscall table. Add your +new system call to the generic list by adding an entry to the list in +``include/uapi/asm-generic/unistd.h``:: + + #define __NR_xyzzy 292 + __SYSCALL(__NR_xyzzy, sys_xyzzy) + +Also update the __NR_syscalls count to reflect the additional system call, and +note that if multiple new system calls are added in the same merge window, +your new syscall number may get adjusted to resolve conflicts. + +The file ``kernel/sys_ni.c`` provides a fallback stub implementation of each +system call, returning ``-ENOSYS``. Add your new system call here too:: + + cond_syscall(sys_xyzzy); + +Your new kernel functionality, and the system call that controls it, should +normally be optional, so add a ``CONFIG`` option (typically to +``init/Kconfig``) for it. As usual for new ``CONFIG`` options: + + - Include a description of the new functionality and system call controlled + by the option. + - Make the option depend on EXPERT if it should be hidden from normal users. + - Make any new source files implementing the function dependent on the CONFIG + option in the Makefile (e.g. ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.c``). + - Double check that the kernel still builds with the new CONFIG option turned + off. + +To summarize, you need a commit that includes: + + - ``CONFIG`` option for the new function, normally in ``init/Kconfig`` + - ``SYSCALL_DEFINEn(xyzzy, ...)`` for the entry point + - corresponding prototype in ``include/linux/syscalls.h`` + - generic table entry in ``include/uapi/asm-generic/unistd.h`` + - fallback stub in ``kernel/sys_ni.c`` + + +x86 System Call Implementation +------------------------------ + +To wire up your new system call for x86 platforms, you need to update the +master syscall tables. Assuming your new system call isn't special in some +way (see below), this involves a "common" entry (for x86_64 and x32) in +arch/x86/entry/syscalls/syscall_64.tbl:: + + 333 common xyzzy sys_xyzzy + +and an "i386" entry in ``arch/x86/entry/syscalls/syscall_32.tbl``:: + + 380 i386 xyzzy sys_xyzzy + +Again, these numbers are liable to be changed if there are conflicts in the +relevant merge window. + + +Compatibility System Calls (Generic) +------------------------------------ + +For most system calls the same 64-bit implementation can be invoked even when +the userspace program is itself 32-bit; even if the system call's parameters +include an explicit pointer, this is handled transparently. + +However, there are a couple of situations where a compatibility layer is +needed to cope with size differences between 32-bit and 64-bit. + +The first is if the 64-bit kernel also supports 32-bit userspace programs, and +so needs to parse areas of (``__user``) memory that could hold either 32-bit or +64-bit values. In particular, this is needed whenever a system call argument +is: + + - a pointer to a pointer + - a pointer to a struct containing a pointer (e.g. ``struct iovec __user *``) + - a pointer to a varying sized integral type (``time_t``, ``off_t``, + ``long``, ...) + - a pointer to a struct containing a varying sized integral type. + +The second situation that requires a compatibility layer is if one of the +system call's arguments has a type that is explicitly 64-bit even on a 32-bit +architecture, for example ``loff_t`` or ``__u64``. In this case, a value that +arrives at a 64-bit kernel from a 32-bit application will be split into two +32-bit values, which then need to be re-assembled in the compatibility layer. + +(Note that a system call argument that's a pointer to an explicit 64-bit type +does **not** need a compatibility layer; for example, :manpage:`splice(2)`'s arguments of +type ``loff_t __user *`` do not trigger the need for a ``compat_`` system call.) + +The compatibility version of the system call is called ``compat_sys_xyzzy()``, +and is added with the ``COMPAT_SYSCALL_DEFINEn()`` macro, analogously to +SYSCALL_DEFINEn. This version of the implementation runs as part of a 64-bit +kernel, but expects to receive 32-bit parameter values and does whatever is +needed to deal with them. (Typically, the ``compat_sys_`` version converts the +values to 64-bit versions and either calls on to the ``sys_`` version, or both of +them call a common inner implementation function.) + +The compat entry point also needs a corresponding function prototype, in +``include/linux/compat.h``, marked as asmlinkage to match the way that system +calls are invoked:: + + asmlinkage long compat_sys_xyzzy(...); + +If the system call involves a structure that is laid out differently on 32-bit +and 64-bit systems, say ``struct xyzzy_args``, then the include/linux/compat.h +header file should also include a compat version of the structure (``struct +compat_xyzzy_args``) where each variable-size field has the appropriate +``compat_`` type that corresponds to the type in ``struct xyzzy_args``. The +``compat_sys_xyzzy()`` routine can then use this ``compat_`` structure to +parse the arguments from a 32-bit invocation. + +For example, if there are fields:: + + struct xyzzy_args { + const char __user *ptr; + __kernel_long_t varying_val; + u64 fixed_val; + /* ... */ + }; + +in struct xyzzy_args, then struct compat_xyzzy_args would have:: + + struct compat_xyzzy_args { + compat_uptr_t ptr; + compat_long_t varying_val; + u64 fixed_val; + /* ... */ + }; + +The generic system call list also needs adjusting to allow for the compat +version; the entry in ``include/uapi/asm-generic/unistd.h`` should use +``__SC_COMP`` rather than ``__SYSCALL``:: + + #define __NR_xyzzy 292 + __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy) + +To summarize, you need: + + - a ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` for the compat entry point + - corresponding prototype in ``include/linux/compat.h`` + - (if needed) 32-bit mapping struct in ``include/linux/compat.h`` + - instance of ``__SC_COMP`` not ``__SYSCALL`` in + ``include/uapi/asm-generic/unistd.h`` + + +Compatibility System Calls (x86) +-------------------------------- + +To wire up the x86 architecture of a system call with a compatibility version, +the entries in the syscall tables need to be adjusted. + +First, the entry in ``arch/x86/entry/syscalls/syscall_32.tbl`` gets an extra +column to indicate that a 32-bit userspace program running on a 64-bit kernel +should hit the compat entry point:: + + 380 i386 xyzzy sys_xyzzy compat_sys_xyzzy + +Second, you need to figure out what should happen for the x32 ABI version of +the new system call. There's a choice here: the layout of the arguments +should either match the 64-bit version or the 32-bit version. + +If there's a pointer-to-a-pointer involved, the decision is easy: x32 is +ILP32, so the layout should match the 32-bit version, and the entry in +``arch/x86/entry/syscalls/syscall_64.tbl`` is split so that x32 programs hit +the compatibility wrapper:: + + 333 64 xyzzy sys_xyzzy + ... + 555 x32 xyzzy compat_sys_xyzzy + +If no pointers are involved, then it is preferable to re-use the 64-bit system +call for the x32 ABI (and consequently the entry in +arch/x86/entry/syscalls/syscall_64.tbl is unchanged). + +In either case, you should check that the types involved in your argument +layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or +64-bit (-m64) equivalents. + + +System Calls Returning Elsewhere +-------------------------------- + +For most system calls, once the system call is complete the user program +continues exactly where it left off -- at the next instruction, with the +stack the same and most of the registers the same as before the system call, +and with the same virtual memory space. + +However, a few system calls do things differently. They might return to a +different location (``rt_sigreturn``) or change the memory space +(``fork``/``vfork``/``clone``) or even architecture (``execve``/``execveat``) +of the program. + +To allow for this, the kernel implementation of the system call may need to +save and restore additional registers to the kernel stack, allowing complete +control of where and how execution continues after the system call. + +This is arch-specific, but typically involves defining assembly entry points +that save/restore additional registers and invoke the real system call entry +point. + +For x86_64, this is implemented as a ``stub_xyzzy`` entry point in +``arch/x86/entry/entry_64.S``, and the entry in the syscall table +(``arch/x86/entry/syscalls/syscall_64.tbl``) is adjusted to match:: + + 333 common xyzzy stub_xyzzy + +The equivalent for 32-bit programs running on a 64-bit kernel is normally +called ``stub32_xyzzy`` and implemented in ``arch/x86/entry/entry_64_compat.S``, +with the corresponding syscall table adjustment in +``arch/x86/entry/syscalls/syscall_32.tbl``:: + + 380 i386 xyzzy sys_xyzzy stub32_xyzzy + +If the system call needs a compatibility layer (as in the previous section) +then the ``stub32_`` version needs to call on to the ``compat_sys_`` version +of the system call rather than the native 64-bit version. Also, if the x32 ABI +implementation is not common with the x86_64 version, then its syscall +table will also need to invoke a stub that calls on to the ``compat_sys_`` +version. + +For completeness, it's also nice to set up a mapping so that user-mode Linux +still works -- its syscall table will reference stub_xyzzy, but the UML build +doesn't include ``arch/x86/entry/entry_64.S`` implementation (because UML +simulates registers etc). Fixing this is as simple as adding a #define to +``arch/x86/um/sys_call_table_64.c``:: + + #define stub_xyzzy sys_xyzzy + + +Other Details +------------- + +Most of the kernel treats system calls in a generic way, but there is the +occasional exception that may need updating for your particular system call. + +The audit subsystem is one such special case; it includes (arch-specific) +functions that classify some special types of system call -- specifically +file open (``open``/``openat``), program execution (``execve``/``exeveat``) or +socket multiplexor (``socketcall``) operations. If your new system call is +analogous to one of these, then the audit system should be updated. + +More generally, if there is an existing system call that is analogous to your +new system call, it's worth doing a kernel-wide grep for the existing system +call to check there are no other special cases. + + +Testing +------- + +A new system call should obviously be tested; it is also useful to provide +reviewers with a demonstration of how user space programs will use the system +call. A good way to combine these aims is to include a simple self-test +program in a new directory under ``tools/testing/selftests/``. + +For a new system call, there will obviously be no libc wrapper function and so +the test will need to invoke it using ``syscall()``; also, if the system call +involves a new userspace-visible structure, the corresponding header will need +to be installed to compile the test. + +Make sure the selftest runs successfully on all supported architectures. For +example, check that it works when compiled as an x86_64 (-m64), x86_32 (-m32) +and x32 (-mx32) ABI program. + +For more extensive and thorough testing of new functionality, you should also +consider adding tests to the Linux Test Project, or to the xfstests project +for filesystem-related changes. + + - https://linux-test-project.github.io/ + - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git + + +Man Page +-------- + +All new system calls should come with a complete man page, ideally using groff +markup, but plain text will do. If groff is used, it's helpful to include a +pre-rendered ASCII version of the man page in the cover email for the +patchset, for the convenience of reviewers. + +The man page should be cc'ed to linux-man@vger.kernel.org +For more details, see https://www.kernel.org/doc/man-pages/patches.html + +References and Sources +---------------------- + + - LWN article from Michael Kerrisk on use of flags argument in system calls: + https://lwn.net/Articles/585415/ + - LWN article from Michael Kerrisk on how to handle unknown flags in a system + call: https://lwn.net/Articles/588444/ + - LWN article from Jake Edge describing constraints on 64-bit system call + arguments: https://lwn.net/Articles/311630/ + - Pair of LWN articles from David Drysdale that describe the system call + implementation paths in detail for v3.14: + + - https://lwn.net/Articles/604287/ + - https://lwn.net/Articles/604515/ + + - Architecture-specific requirements for system calls are discussed in the + :manpage:`syscall(2)` man-page: + http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES + - Collated emails from Linus Torvalds discussing the problems with ``ioctl()``: + http://yarchive.net/comp/linux/ioctl.html + - "How to not invent kernel interfaces", Arnd Bergmann, + http://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf + - LWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN: + https://lwn.net/Articles/486306/ + - Recommendation from Andrew Morton that all related information for a new + system call should come in the same email thread: + https://lkml.org/lkml/2014/7/24/641 + - Recommendation from Michael Kerrisk that a new system call should come with + a man page: https://lkml.org/lkml/2014/6/13/309 + - Suggestion from Thomas Gleixner that x86 wire-up should be in a separate + commit: https://lkml.org/lkml/2014/11/19/254 + - Suggestion from Greg Kroah-Hartman that it's good for new system calls to + come with a man-page & selftest: https://lkml.org/lkml/2014/3/19/710 + - Discussion from Michael Kerrisk of new system call vs. :manpage:`prctl(2)` extension: + https://lkml.org/lkml/2014/6/3/411 + - Suggestion from Ingo Molnar that system calls that involve multiple + arguments should encapsulate those arguments in a struct, which includes a + size field for future extensibility: https://lkml.org/lkml/2015/7/30/117 + - Numbering oddities arising from (re-)use of O_* numbering space flags: + + - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness + check") + - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc + conflict") + - commit bb458c644a59 ("Safer ABI for O_TMPFILE") + + - Discussion from Matthew Wilcox about restrictions on 64-bit arguments: + https://lkml.org/lkml/2008/12/12/187 + - Recommendation from Greg Kroah-Hartman that unknown flags should be + policed: https://lkml.org/lkml/2014/7/17/577 + - Recommendation from Linus Torvalds that x32 system calls should prefer + compatibility with 64-bit versions rather than 32-bit versions: + https://lkml.org/lkml/2011/8/31/244 -- cgit v1.2.3 From 684adc0aa3d482228d0727ee9a9a7b8deec62ca5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 09:48:55 -0300 Subject: Documentation/kernel-parameters.txt: convert to ReST markup Adjust the file for it to be parsed by Sphinx: - adjust the document title to be parsed; - use :: for quote blocks; - fix the horizontal bar markup; - lower case the TODO title. Signed-off-by: Mauro Carvalho Chehab --- Documentation/kernel-parameters.txt | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 37babf91f2cb..b0804273b6e3 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -1,5 +1,5 @@ - Kernel Parameters - ~~~~~~~~~~~~~~~~~ +Kernel Parameters +~~~~~~~~~~~~~~~~~ The following is a consolidated list of the kernel parameters as implemented by the __setup(), core_param() and module_param() macros @@ -14,7 +14,7 @@ environment, others are passed as command line arguments to init. Everything after "--" is passed as an argument to init. Module parameters can be specified in two ways: via the kernel command -line with a module name prefix, or via modprobe, e.g.: +line with a module name prefix, or via modprobe, e.g.:: (kernel command line) usbcore.blinkenlights=1 (modprobe command line) modprobe usbcore blinkenlights=1 @@ -25,12 +25,16 @@ kernel command line (/proc/cmdline) and collects module parameters when it loads a module, so the kernel command line can be used for loadable modules too. -Hyphens (dashes) and underscores are equivalent in parameter names, so +Hyphens (dashes) and underscores are equivalent in parameter names, so:: + log_buf_len=1M print-fatal-signals=1 -can also be entered as + +can also be entered as:: + log-buf-len=1M print_fatal_signals=1 -Double-quotes can be used to protect spaces in values, e.g.: +Double-quotes can be used to protect spaces in values, e.g.:: + param="spaces in here" cpu lists: @@ -69,12 +73,12 @@ This document may not be entirely up to date and comprehensive. The command module. Loadable modules, after being loaded into the running kernel, also reveal their parameters in /sys/module/${modulename}/parameters/. Some of these parameters may be changed at runtime by the command -"echo -n ${value} > /sys/module/${modulename}/parameters/${parm}". +``echo -n ${value} > /sys/module/${modulename}/parameters/${parm}``. The parameters listed below are only valid if certain kernel build options were enabled and if respective hardware is present. The text in square brackets at the beginning of each description states the restrictions within which a -parameter is applicable: +parameter is applicable:: ACPI ACPI support is enabled. AGP AGP (Accelerated Graphics Port) is enabled. @@ -165,7 +169,7 @@ parameter is applicable: X86_UV SGI UV support is enabled. XEN Xen support is enabled -In addition, the following text indicates that the option: +In addition, the following text indicates that the option:: BUGS= Relates to possible processor bugs on the said processor. KNL Is a kernel start-up parameter. @@ -194,7 +198,7 @@ and is between 256 and 4096 characters. It is defined in the file Finally, the [KMG] suffix is commonly described after a number of kernel parameter values. These 'K', 'M', and 'G' letters represent the _binary_ multipliers 'Kilo', 'Mega', and 'Giga', equalling 2^10, 2^20, and 2^30 -bytes respectively. Such letter suffixes can also be entirely omitted. +bytes respectively. Such letter suffixes can also be entirely omitted:: acpi= [HW,ACPI,X86,ARM64] @@ -2545,7 +2549,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. will be sent. The default is to send the implementation identification information. - + nfs.recover_lost_locks = [NFSv4] Attempt to recover locks that were lost due to a lease timeout on the server. Please note that @@ -4197,7 +4201,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted. See also Documentation/input/joystick-parport.txt udbg-immortal [PPC] When debugging early kernel crashes that - happen after console_init() and before a proper + happen after console_init() and before a proper console driver takes over, this boot options might help "seeing" what's going on. @@ -4565,8 +4569,9 @@ bytes respectively. Such letter suffixes can also be entirely omitted. Format: ,,,,,[,[,[,]]] -______________________________________________________________________ +------------------------ -TODO: +Todo +---- Add more DRM drivers. -- cgit v1.2.3 From d078a815196bc4b3d8fe728a0dbd83c07b928a47 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 13:24:12 -0300 Subject: Documentation/bad_memory.txt: convert it to ReST markup - promote the section level of the document name; - add/remove spaces/new lines where needed to format the output; - use quote blocks. - add it to the user book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/bad_memory.txt | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/Documentation/bad_memory.txt b/Documentation/bad_memory.txt index df8416213202..5cac93e27a97 100644 --- a/Documentation/bad_memory.txt +++ b/Documentation/bad_memory.txt @@ -1,9 +1,10 @@ +How to deal with bad memory e.g. reported by memtest86+ ? +========================================================= + March 2008 Jan-Simon Moeller, dl9pf@gmx.de -How to deal with bad memory e.g. reported by memtest86+ ? -######################################################### There are three possibilities I know of: @@ -19,6 +20,7 @@ This Howto is about number 3) . BadRAM ###### + BadRAM is the actively developed and available as kernel-patch here: http://rick.vanrein.org/linux/badram/ @@ -31,15 +33,19 @@ memmap is already in the kernel and usable as kernel-parameter at boot-time. Its syntax is slightly strange and you may need to calculate the values by yourself! -Syntax to exclude a memory area (see kernel-parameters.txt for details): -memmap=$
+Syntax to exclude a memory area (see kernel-parameters.txt for details):: + + memmap=$
Example: memtest86+ reported here errors at address 0x18691458, 0x18698424 and - some others. All had 0x1869xxxx in common, so I chose a pattern of - 0x18690000,0xffff0000. +some others. All had 0x1869xxxx in common, so I chose a pattern of +0x18690000,0xffff0000. + +With the numbers of the example above:: + + memmap=64K$0x18690000 + +or:: -With the numbers of the example above: -memmap=64K$0x18690000 - or -memmap=0x10000$0x18690000 + memmap=0x10000$0x18690000 -- cgit v1.2.3 From 3bdb5971ffc6e87362787c770353eb3e54b7af30 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 13:38:38 -0300 Subject: Documentation/basic_profiling.rst: convert to ReST markup Convert it to ReST markup and add it to the user book: - Add a title to the document; - touch spaces/new lines to fix Sphinx format; - use ``foo`` for commands; - use quote blocks where needed; - add it to the user book; Signed-off-by: Mauro Carvalho Chehab --- Documentation/basic_profiling.txt | 59 ++++++++++++++++++++++++--------------- 1 file changed, 36 insertions(+), 23 deletions(-) diff --git a/Documentation/basic_profiling.txt b/Documentation/basic_profiling.txt index 8764e9f70821..15a49dbd0189 100644 --- a/Documentation/basic_profiling.txt +++ b/Documentation/basic_profiling.txt @@ -1,56 +1,69 @@ +Basic kernel profiling +====================== + + These instructions are deliberately very basic. If you want something clever, -go read the real docs ;-) Please don't add more stuff, but feel free to +go read the real docs ;-) + +Please don't add more stuff, but feel free to correct my mistakes ;-) (mbligh@aracnet.com) + Thanks to John Levon, Dave Hansen, et al. for help writing this. - is the thing you're trying to measure. -Make sure you have the correct System.map / vmlinux referenced! +```` is the thing you're trying to measure. +Make sure you have the correct ``System.map`` / ``vmlinux`` referenced! -It is probably easiest to use "make install" for linux and hack -/sbin/installkernel to copy vmlinux to /boot, in addition to vmlinuz, -config, System.map, which are usually installed by default. +It is probably easiest to use ``make install`` for linux and hack +``/sbin/installkernel`` to copy ``vmlinux`` to ``/boot``, in addition to +``vmlinuz``, ``config``, ``System.map``, which are usually installed by default. Readprofile ----------- -A recent readprofile command is needed for 2.6, such as found in util-linux + +A recent ``readprofile`` command is needed for 2.6, such as found in util-linux 2.12a, which can be downloaded from: -http://www.kernel.org/pub/linux/utils/util-linux/ + http://www.kernel.org/pub/linux/utils/util-linux/ Most distributions will ship it already. -Add "profile=2" to the kernel command line. +Add ``profile=2`` to the kernel command line. -clear readprofile -r - -dump output readprofile -m /boot/System.map > captured_profile +Some ``readprofile`` commands:: + + clear readprofile -r + + dump output readprofile -m /boot/System.map > captured_profile Oprofile -------- Get the source (see Changes for required version) from -http://oprofile.sourceforge.net/ and add "idle=poll" to the kernel command +http://oprofile.sourceforge.net/ and add ``idle=poll`` to the kernel command line. -Configure with CONFIG_PROFILING=y and CONFIG_OPROFILE=y & reboot on new kernel +Configure with ``CONFIG_PROFILING=y`` and ``CONFIG_OPROFILE=y`` & reboot on new kernel:: -./configure --with-kernel-support -make install + ./configure --with-kernel-support + make install For superior results, be sure to enable the local APIC. If opreport sees a 0Hz CPU, APIC was not on. Be aware that idle=poll may mean a performance penalty. -One time setup: - opcontrol --setup --vmlinux=/boot/vmlinux +One time setup:: + + opcontrol --setup --vmlinux=/boot/vmlinux + +Some ``opcontrol`` commands:: -clear opcontrol --reset -start opcontrol --start + clear opcontrol --reset + start opcontrol --start -stop opcontrol --stop -dump output opreport > output_file + stop opcontrol --stop + dump output opreport > output_file -To only report on the kernel, run opreport -l /boot/vmlinux > output_file +To only report on the kernel, run ``opreport -l /boot/vmlinux > output_file`` A reset is needed to clear old statistics, which survive a reboot. -- cgit v1.2.3 From 5902981bce634dc218f0f8884649efebca7b8bcc Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 13:56:19 -0300 Subject: Documentation/binfmt_misc.txt: convert it to ReST markup - Fix identation for the document title; - use monotonic fonts for commands, paths, etc; - use quote blocks where needed; - adjust spaces to properly format paragraphs; - add it to the user book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/binfmt_misc.txt | 134 ++++++++++++++++++++++++------------------ 1 file changed, 77 insertions(+), 57 deletions(-) diff --git a/Documentation/binfmt_misc.txt b/Documentation/binfmt_misc.txt index ec83bbce547a..9c5ff8f260bf 100644 --- a/Documentation/binfmt_misc.txt +++ b/Documentation/binfmt_misc.txt @@ -1,5 +1,5 @@ - Kernel Support for miscellaneous (your favourite) Binary Formats v1.1 - ===================================================================== +Kernel Support for miscellaneous (your favourite) Binary Formats v1.1 +===================================================================== This Kernel feature allows you to invoke almost (for restrictions see below) every program by simply typing its name in the shell. @@ -9,122 +9,142 @@ To achieve this you must tell binfmt_misc which interpreter has to be invoked with which binary. Binfmt_misc recognises the binary-type by matching some bytes at the beginning of the file with a magic byte sequence (masking out specified bits) you have supplied. Binfmt_misc can also recognise a filename extension -aka '.com' or '.exe'. +aka ``.com`` or ``.exe``. -First you must mount binfmt_misc: - mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc +First you must mount binfmt_misc:: + + mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc To actually register a new binary type, you have to set up a string looking like -:name:type:offset:magic:mask:interpreter:flags (where you can choose the ':' -upon your needs) and echo it to /proc/sys/fs/binfmt_misc/register. +``:name:type:offset:magic:mask:interpreter:flags`` (where you can choose the +``:`` upon your needs) and echo it to ``/proc/sys/fs/binfmt_misc/register``. Here is what the fields mean: - - 'name' is an identifier string. A new /proc file will be created with this - name below /proc/sys/fs/binfmt_misc; cannot contain slashes '/' for obvious - reasons. - - 'type' is the type of recognition. Give 'M' for magic and 'E' for extension. - - 'offset' is the offset of the magic/mask in the file, counted in bytes. This - defaults to 0 if you omit it (i.e. you write ':name:type::magic...'). Ignored - when using filename extension matching. - - 'magic' is the byte sequence binfmt_misc is matching for. The magic string - may contain hex-encoded characters like \x0a or \xA4. Note that you must - escape any NUL bytes; parsing halts at the first one. In a shell environment - you might have to write \\x0a to prevent the shell from eating your \. + +- ``name`` + is an identifier string. A new /proc file will be created with this + ``name below /proc/sys/fs/binfmt_misc``; cannot contain slashes ``/`` for + obvious reasons. +- ``type`` + is the type of recognition. Give ``M`` for magic and ``E`` for extension. +- ``offset`` + is the offset of the magic/mask in the file, counted in bytes. This + defaults to 0 if you omit it (i.e. you write ``:name:type::magic...``). + Ignored when using filename extension matching. +- ``magic`` + is the byte sequence binfmt_misc is matching for. The magic string + may contain hex-encoded characters like ``\x0a`` or ``\xA4``. Note that you + must escape any NUL bytes; parsing halts at the first one. In a shell + environment you might have to write ``\\x0a`` to prevent the shell from + eating your ``\``. If you chose filename extension matching, this is the extension to be - recognised (without the '.', the \x0a specials are not allowed). Extension - matching is case sensitive, and slashes '/' are not allowed! - - 'mask' is an (optional, defaults to all 0xff) mask. You can mask out some + recognised (without the ``.``, the ``\x0a`` specials are not allowed). + Extension matching is case sensitive, and slashes ``/`` are not allowed! +- ``mask`` + is an (optional, defaults to all 0xff) mask. You can mask out some bits from matching by supplying a string like magic and as long as magic. The mask is anded with the byte sequence of the file. Note that you must escape any NUL bytes; parsing halts at the first one. Ignored when using filename extension matching. - - 'interpreter' is the program that should be invoked with the binary as first +- ``interpreter`` + is the program that should be invoked with the binary as first argument (specify the full path) - - 'flags' is an optional field that controls several aspects of the invocation +- ``flags`` + is an optional field that controls several aspects of the invocation of the interpreter. It is a string of capital letters, each controls a - certain aspect. The following flags are supported - - 'P' - preserve-argv[0]. Legacy behavior of binfmt_misc is to overwrite + certain aspect. The following flags are supported: + + ``P`` - preserve-argv[0] + Legacy behavior of binfmt_misc is to overwrite the original argv[0] with the full path to the binary. When this flag is included, binfmt_misc will add an argument to the argument - vector for this purpose, thus preserving the original argv[0]. - e.g. If your interp is set to /bin/foo and you run `blah` (which is - in /usr/local/bin), then the kernel will execute /bin/foo with - argv[] set to ["/bin/foo", "/usr/local/bin/blah", "blah"]. The - interp has to be aware of this so it can execute /usr/local/bin/blah - with argv[] set to ["blah"]. - 'O' - open-binary. Legacy behavior of binfmt_misc is to pass the full path + vector for this purpose, thus preserving the original ``argv[0]``. + e.g. If your interp is set to ``/bin/foo`` and you run ``blah`` + (which is in ``/usr/local/bin``), then the kernel will execute + ``/bin/foo`` with ``argv[]`` set to ``["/bin/foo", "/usr/local/bin/blah", "blah"]``. The interp has to be aware of this so it can + execute ``/usr/local/bin/blah`` + with ``argv[]`` set to ``["blah"]``. + ``O`` - open-binary + Legacy behavior of binfmt_misc is to pass the full path of the binary to the interpreter as an argument. When this flag is included, binfmt_misc will open the file for reading and pass its descriptor as an argument, instead of the full path, thus allowing the interpreter to execute non-readable binaries. This feature should be used with care - the interpreter has to be trusted not to emit the contents of the non-readable binary. - 'C' - credentials. Currently, the behavior of binfmt_misc is to calculate + ``C`` - credentials + Currently, the behavior of binfmt_misc is to calculate the credentials and security token of the new process according to the interpreter. When this flag is included, these attributes are - calculated according to the binary. It also implies the 'O' flag. + calculated according to the binary. It also implies the ``O`` flag. This feature should be used with care as the interpreter will run with root permissions when a setuid binary owned by root is run with binfmt_misc. - 'F' - fix binary. The usual behaviour of binfmt_misc is to spawn the - binary lazily when the misc format file is invoked. However, - this doesn't work very well in the face of mount namespaces and - changeroots, so the F mode opens the binary as soon as the + ``F`` - fix binary + The usual behaviour of binfmt_misc is to spawn the + binary lazily when the misc format file is invoked. However, + this doesn``t work very well in the face of mount namespaces and + changeroots, so the ``F`` mode opens the binary as soon as the emulation is installed and uses the opened image to spawn the emulator, meaning it is always available once installed, regardless of how the environment changes. There are some restrictions: + - the whole register string may not exceed 1920 characters - the magic must reside in the first 128 bytes of the file, i.e. offset+size(magic) has to be less than 128 - the interpreter string may not exceed 127 characters To use binfmt_misc you have to mount it first. You can mount it with -"mount -t binfmt_misc none /proc/sys/fs/binfmt_misc" command, or you can add -a line "none /proc/sys/fs/binfmt_misc binfmt_misc defaults 0 0" to your -/etc/fstab so it auto mounts on boot. +``mount -t binfmt_misc none /proc/sys/fs/binfmt_misc`` command, or you can add +a line ``none /proc/sys/fs/binfmt_misc binfmt_misc defaults 0 0`` to your +``/etc/fstab`` so it auto mounts on boot. -You may want to add the binary formats in one of your /etc/rc scripts during +You may want to add the binary formats in one of your ``/etc/rc`` scripts during boot-up. Read the manual of your init program to figure out how to do this right. Think about the order of adding entries! Later added entries are matched first! -A few examples (assumed you are in /proc/sys/fs/binfmt_misc): +A few examples (assumed you are in ``/proc/sys/fs/binfmt_misc``): + +- enable support for em86 (like binfmt_em86, for Alpha AXP only):: + + echo ':i386:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x03:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register + echo ':i486:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x06:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register + +- enable support for packed DOS applications (pre-configured dosemu hdimages):: -- enable support for em86 (like binfmt_em86, for Alpha AXP only): - echo ':i386:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x03:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register - echo ':i486:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x06:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register + echo ':DEXE:M::\x0eDEX::/usr/bin/dosexec:' > register -- enable support for packed DOS applications (pre-configured dosemu hdimages): - echo ':DEXE:M::\x0eDEX::/usr/bin/dosexec:' > register +- enable support for Windows executables using wine:: -- enable support for Windows executables using wine: - echo ':DOSWin:M::MZ::/usr/local/bin/wine:' > register + echo ':DOSWin:M::MZ::/usr/local/bin/wine:' > register For java support see Documentation/java.txt You can enable/disable binfmt_misc or one binary type by echoing 0 (to disable) -or 1 (to enable) to /proc/sys/fs/binfmt_misc/status or /proc/.../the_name. -Catting the file tells you the current status of binfmt_misc/the entry. +or 1 (to enable) to ``/proc/sys/fs/binfmt_misc/status`` or +``/proc/.../the_name``. +Catting the file tells you the current status of ``binfmt_misc/the_entry``. -You can remove one entry or all entries by echoing -1 to /proc/.../the_name -or /proc/sys/fs/binfmt_misc/status. +You can remove one entry or all entries by echoing -1 to ``/proc/.../the_name`` +or ``/proc/sys/fs/binfmt_misc/status``. -HINTS: -====== +Hints +----- If you want to pass special arguments to your interpreter, you can write a wrapper script for it. See Documentation/java.txt for an example. Your interpreter should NOT look in the PATH for the filename; the kernel -passes it the full filename (or the file descriptor) to use. Using $PATH can +passes it the full filename (or the file descriptor) to use. Using ``$PATH`` can cause unexpected behaviour and can be a security hazard. -- cgit v1.2.3 From c2ffd5dafa9dfbc48d5198c6d355617a756d2690 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 14:08:10 -0300 Subject: Documentation/serial-console.txt: convert it to ReST markup - Fix identation for the document title; - use monotonic fonts for paths; - use quote blocks where needed; - adjust spaces to properly format paragraphs; - use :menuselection: for the menu item; - add it to the user book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/serial-console.txt | 66 +++++++++++++++++++++------------------- 1 file changed, 35 insertions(+), 31 deletions(-) diff --git a/Documentation/serial-console.txt b/Documentation/serial-console.txt index 9a7bc8b3f479..1d9a3e48e929 100644 --- a/Documentation/serial-console.txt +++ b/Documentation/serial-console.txt @@ -1,15 +1,19 @@ - Linux Serial Console +Linux Serial Console +==================== To use a serial port as console you need to compile the support into your kernel - by default it is not compiled in. For PC style serial ports -it's the config option next to "Standard/generic (dumb) serial support". +it's the config option next to menu option: + +:menuselection:`Character devices --> Serial drivers --> 8250/16550 and compatible serial support --> Console on 8250/16550 and compatible serial port` + You must compile serial support into the kernel and not as a module. It is possible to specify multiple devices for console output. You can define a new kernel command line option to select which device(s) to use for console output. -The format of this option is: +The format of this option is:: console=device,options @@ -28,11 +32,11 @@ The format of this option is: You can specify multiple console= options on the kernel command line. Output will appear on all of them. The last device will be used when -you open /dev/console. So, for example: +you open ``/dev/console``. So, for example:: console=ttyS1,9600 console=tty0 -defines that opening /dev/console will get you the current foreground +defines that opening ``/dev/console`` will get you the current foreground virtual console, and kernel messages will appear on both the VGA console and the 2nd serial port (ttyS1 or COM2) at 9600 baud. @@ -44,61 +48,61 @@ first looks for a VGA card and then for a serial port. So if you don't have a VGA card in your system the first serial port will automatically become the console. -You will need to create a new device to use /dev/console. The official -/dev/console is now character device 5,1. +You will need to create a new device to use ``/dev/console``. The official +``/dev/console`` is now character device 5,1. (You can also use a network device as a console. See -Documentation/networking/netconsole.txt for information on that.) +``Documentation/networking/netconsole.txt`` for information on that.) -Here's an example that will use /dev/ttyS1 (COM2) as the console. +Here's an example that will use ``/dev/ttyS1`` (COM2) as the console. Replace the sample values as needed. -1. Create /dev/console (real console) and /dev/tty0 (master virtual - console): +1. Create ``/dev/console`` (real console) and ``/dev/tty0`` (master virtual + console):: - cd /dev - rm -f console tty0 - mknod -m 622 console c 5 1 - mknod -m 622 tty0 c 4 0 + cd /dev + rm -f console tty0 + mknod -m 622 console c 5 1 + mknod -m 622 tty0 c 4 0 2. LILO can also take input from a serial device. This is a very useful option. To tell LILO to use the serial port: - In lilo.conf (global section): + In lilo.conf (global section):: - serial = 1,9600n8 (ttyS1, 9600 bd, no parity, 8 bits) + serial = 1,9600n8 (ttyS1, 9600 bd, no parity, 8 bits) 3. Adjust to kernel flags for the new kernel, - again in lilo.conf (kernel section) + again in lilo.conf (kernel section):: - append = "console=ttyS1,9600" + append = "console=ttyS1,9600" 4. Make sure a getty runs on the serial port so that you can login to it once the system is done booting. This is done by adding a line - like this to /etc/inittab (exact syntax depends on your getty): + like this to ``/etc/inittab`` (exact syntax depends on your getty):: - S1:23:respawn:/sbin/getty -L ttyS1 9600 vt100 + S1:23:respawn:/sbin/getty -L ttyS1 9600 vt100 -5. Init and /etc/ioctl.save +5. Init and ``/etc/ioctl.save`` - Sysvinit remembers its stty settings in a file in /etc, called - `/etc/ioctl.save'. REMOVE THIS FILE before using the serial + Sysvinit remembers its stty settings in a file in ``/etc``, called + ``/etc/ioctl.save``. REMOVE THIS FILE before using the serial console for the first time, because otherwise init will probably set the baudrate to 38400 (baudrate of the virtual console). -6. /dev/console and X +6. ``/dev/console`` and X Programs that want to do something with the virtual console usually - open /dev/console. If you have created the new /dev/console device, + open ``/dev/console``. If you have created the new ``/dev/console`` device, and your console is NOT the virtual console some programs will fail. Those are programs that want to access the VT interface, and use - /dev/console instead of /dev/tty0. Some of those programs are: + ``/dev/console instead of /dev/tty0``. Some of those programs are:: - Xfree86, svgalib, gpm, SVGATextMode + Xfree86, svgalib, gpm, SVGATextMode It should be fixed in modern versions of these programs though. - Note that if you boot without a console= option (or with - console=/dev/tty0), /dev/console is the same as /dev/tty0. In that - case everything will still work. + Note that if you boot without a ``console=`` option (or with + ``console=/dev/tty0``), ``/dev/console`` is the same as ``/dev/tty0``. + In that case everything will still work. 7. Thanks -- cgit v1.2.3 From 8e7fbec662554b25ac832116cfe2d47db635d33c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 14:44:59 -0300 Subject: Documentation/braille-console: convert it to ReST markup - Fix identation for the document title; - use monotonic fonts for paths; - use quote blocks where needed; - adjust spaces to properly format paragraphs; - use :menuselection: and :kbd: for the menu item and keys; - point too the right item at the menu; - add it to the user book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/braille-console.txt | 30 +++++++++++++++++------------- Documentation/serial-console.txt | 2 ++ 2 files changed, 19 insertions(+), 13 deletions(-) diff --git a/Documentation/braille-console.txt b/Documentation/braille-console.txt index d0d042c2fd5e..fa3702dc04ab 100644 --- a/Documentation/braille-console.txt +++ b/Documentation/braille-console.txt @@ -1,33 +1,37 @@ - Linux Braille Console +Linux Braille Console +===================== To get early boot messages on a braille device (before userspace screen readers can start), you first need to compile the support for the usual serial -console (see serial-console.txt), and for braille device (in Device Drivers - -Accessibility). +console (see :ref:`Documentation/serial-console.txt `), and +for braille device +(in :menuselection:`Device Drivers --> Accessibility support --> Console on braille device`). -Then you need to specify a console=brl, option on the kernel command line, the -format is: +Then you need to specify a ``console=brl``, option on the kernel command line, the +format is:: console=brl,serial_options... -where serial_options... are the same as described in serial-console.txt +where ``serial_options...`` are the same as described in +:ref:`Documentation/serial-console.txt `. -So for instance you can use console=brl,ttyS0 if the braille device is connected -to the first serial port, and console=brl,ttyS0,115200 to override the baud rate -to 115200, etc. +So for instance you can use ``console=brl,ttyS0`` if the braille device is connected to the first serial port, and ``console=brl,ttyS0,115200`` to +override the baud rate to 115200, etc. By default, the braille device will just show the last kernel message (console mode). To review previous messages, press the Insert key to switch to the VT review mode. In review mode, the arrow keys permit to browse in the VT content, -page up/down keys go at the top/bottom of the screen, and the home key goes back +:kbd:`PAGE-UP`/:kbd:`PAGE-DOWN` keys go at the top/bottom of the screen, and +the :kbd:`HOME` key goes back to the cursor, hence providing very basic screen reviewing facility. -Sound feedback can be obtained by adding the braille_console.sound=1 kernel +Sound feedback can be obtained by adding the ``braille_console.sound=1`` kernel parameter. For simplicity, only one braille console can be enabled, other uses of -console=brl,... will be discarded. Also note that it does not interfere with -the console selection mechanism described in serial-console.txt +``console=brl,...`` will be discarded. Also note that it does not interfere with +the console selection mechanism described in +:ref:`Documentation/serial-console.txt `. For now, only the VisioBraille device is supported. diff --git a/Documentation/serial-console.txt b/Documentation/serial-console.txt index 1d9a3e48e929..a8d1e36b627a 100644 --- a/Documentation/serial-console.txt +++ b/Documentation/serial-console.txt @@ -1,3 +1,5 @@ +.. _serial_console: + Linux Serial Console ==================== -- cgit v1.2.3 From 953ab835a98166529e971e91d20d78c2ce2c7f7d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 15:16:45 -0300 Subject: Documentation/BUG-HUNTING: convert to ReST markup - Add a document title and remove its own index; - use monotonic fonts for paths; - use quote blocks where needed; - adjust/use spaces to properly format paragraphs; - add it to the user book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/BUG-HUNTING | 164 +++++++++++++++++++++++----------------------- 1 file changed, 83 insertions(+), 81 deletions(-) diff --git a/Documentation/BUG-HUNTING b/Documentation/BUG-HUNTING index 65022a87bf17..a8ef794aadae 100644 --- a/Documentation/BUG-HUNTING +++ b/Documentation/BUG-HUNTING @@ -1,18 +1,8 @@ -Table of contents -================= +Bug hunting ++++++++++++ Last updated: 20 December 2005 -Contents -======== - -- Introduction -- Devices not appearing -- Finding patch that caused a bug --- Finding using git-bisect --- Finding it the old way -- Fixing the bug - Introduction ============ @@ -24,7 +14,8 @@ Finding bugs is not always easy. Have a go though. If you can't find it don't give up. Report as much as you have found to the relevant maintainer. See MAINTAINERS for who that is for the subsystem you have worked on. -Before you submit a bug report read REPORTING-BUGS. +Before you submit a bug report read +:ref:`Documentation/REPORTING-BUGS `. Devices not appearing ===================== @@ -37,15 +28,16 @@ Finding patch that caused a bug -Finding using git-bisect ------------------------- +Finding using ``git-bisect`` +---------------------------- -Using the provided tools with git makes finding bugs easy provided the bug is -reproducible. +Using the provided tools with ``git`` makes finding bugs easy provided the bug +is reproducible. Steps to do it: + - start using git for the kernel source -- read the man page for git-bisect +- read the man page for ``git-bisect`` - have fun Finding it the old way @@ -58,22 +50,22 @@ It's a brute force approach but it works pretty well. You need: - . A reproducible bug - it has to happen predictably (sorry) - . All the kernel tar files from a revision that worked to the + - A reproducible bug - it has to happen predictably (sorry) + - All the kernel tar files from a revision that worked to the revision that doesn't You will then do: - . Rebuild a revision that you believe works, install, and verify that. - . Do a binary search over the kernels to figure out which one + - Rebuild a revision that you believe works, install, and verify that. + - Do a binary search over the kernels to figure out which one introduced the bug. I.e., suppose 1.3.28 didn't have the bug, but you know that 1.3.69 does. Pick a kernel in the middle and build that, like 1.3.50. Build & test; if it works, pick the mid point between .50 and .69, else the mid point between .28 and .50. - . You'll narrow it down to the kernel that introduced the bug. You + - You'll narrow it down to the kernel that introduced the bug. You can probably do better than this but it gets tricky. - . Narrow it down to a subdirectory + - Narrow it down to a subdirectory - Copy kernel that works into "test". Let's say that 3.62 works, but 3.63 doesn't. So you diff -r those two kernels and come @@ -83,7 +75,7 @@ You will then do: Copy the non-working directory next to the working directory as "dir.63". One directory at time, try moving the working directory to - "dir.62" and mv dir.63 dir"time, try + "dir.62" and mv dir.63 dir"time, try:: mv dir dir.62 mv dir.63 dir @@ -97,15 +89,15 @@ You will then do: found in my case that they were self explanatory - you may or may not want to give up when that happens. - . Narrow it down to a file + - Narrow it down to a file - You can apply the same technique to each file in the directory, hoping that the changes in that file are self contained. - . Narrow it down to a routine + - Narrow it down to a routine - You can take the old file and the new file and manually create - a merged file that has + a merged file that has:: #ifdef VER62 routine() @@ -120,7 +112,7 @@ You will then do: #endif And then walk through that file, one routine at a time and - prefix it with + prefix it with:: #define VER62 /* both routines here */ @@ -153,94 +145,104 @@ To debug a kernel, use objdump and look for the hex offset from the crash output to find the valid line of code/assembler. Without debug symbols, you will see the assembler code for the routine shown, but if your kernel has debug symbols the C code will also be available. (Debug symbols can be enabled -in the kernel hacking menu of the menu configuration.) For example: +in the kernel hacking menu of the menu configuration.) For example:: objdump -r -S -l --disassemble net/dccp/ipv4.o -NB.: you need to be at the top level of the kernel tree for this to pick up -your C files. +.. note:: + + You need to be at the top level of the kernel tree for this to pick up + your C files. If you don't have access to the code you can also debug on some crash dumps -e.g. crash dump output as shown by Dave Miller. - -> EIP is at ip_queue_xmit+0x14/0x4c0 -> ... -> Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00 -> 00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08 -> <8b> 83 3c 01 00 00 89 44 24 14 8b 45 28 85 c0 89 44 24 18 0f 85 -> -> Put the bytes into a "foo.s" file like this: -> -> .text -> .globl foo -> foo: -> .byte .... /* bytes from Code: part of OOPS dump */ -> -> Compile it with "gcc -c -o foo.o foo.s" then look at the output of -> "objdump --disassemble foo.o". -> -> Output: -> -> ip_queue_xmit: -> push %ebp -> push %edi -> push %esi -> push %ebx -> sub $0xbc, %esp -> mov 0xd0(%esp), %ebp ! %ebp = arg0 (skb) -> mov 0x8(%ebp), %ebx ! %ebx = skb->sk -> mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt +e.g. crash dump output as shown by Dave Miller:: + + EIP is at ip_queue_xmit+0x14/0x4c0 + ... + Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00 + 00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08 + <8b> 83 3c 01 00 00 89 44 24 14 8b 45 28 85 c0 89 44 24 18 0f 85 + + Put the bytes into a "foo.s" file like this: + + .text + .globl foo + foo: + .byte .... /* bytes from Code: part of OOPS dump */ + + Compile it with "gcc -c -o foo.o foo.s" then look at the output of + "objdump --disassemble foo.o". + + Output: + + ip_queue_xmit: + push %ebp + push %edi + push %esi + push %ebx + sub $0xbc, %esp + mov 0xd0(%esp), %ebp ! %ebp = arg0 (skb) + mov 0x8(%ebp), %ebx ! %ebx = skb->sk + mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt In addition, you can use GDB to figure out the exact file and line -number of the OOPS from the vmlinux file. If you have -CONFIG_DEBUG_INFO enabled, you can simply copy the EIP value from the -OOPS: +number of the OOPS from the ``vmlinux`` file. If you have +``CONFIG_DEBUG_INFO`` enabled, you can simply copy the EIP value from the +OOPS:: EIP: 0060:[] Not tainted VLI -And use GDB to translate that to human-readable form: +And use GDB to translate that to human-readable form:: gdb vmlinux (gdb) l *0xc021e50e -If you don't have CONFIG_DEBUG_INFO enabled, you use the function -offset from the OOPS: +If you don't have ``CONFIG_DEBUG_INFO`` enabled, you use the function +offset from the OOPS:: EIP is at vt_ioctl+0xda8/0x1482 -And recompile the kernel with CONFIG_DEBUG_INFO enabled: +And recompile the kernel with ``CONFIG_DEBUG_INFO`` enabled:: make vmlinux gdb vmlinux (gdb) p vt_ioctl (gdb) l *(0x
+ 0xda8) -or, as one command + +or, as one command:: + (gdb) l *(vt_ioctl + 0xda8) -If you have a call trace, such as :- ->Call Trace: -> [] :jbd:log_wait_commit+0xa3/0xf5 -> [] autoremove_wake_function+0x0/0x2e -> [] :jbd:journal_stop+0x1be/0x1ee -> ... +If you have a call trace, such as:: + + Call Trace: + [] :jbd:log_wait_commit+0xa3/0xf5 + [] autoremove_wake_function+0x0/0x2e + [] :jbd:journal_stop+0x1be/0x1ee + ... + this shows the problem in the :jbd: module. You can load that module in gdb -and list the relevant code. +and list the relevant code:: + gdb fs/jbd/jbd.ko (gdb) p log_wait_commit (gdb) l *(0x
+ 0xa3) -or + +or:: + (gdb) l *(log_wait_commit + 0xa3) Another very useful option of the Kernel Hacking section in menuconfig is Debug memory allocations. This will help you see whether data has been initialised and not set before use etc. To see the values that get assigned -with this look at mm/slab.c and search for POISON_INUSE. When using this an -Oops will often show the poisoned data instead of zero which is the default. +with this look at ``mm/slab.c`` and search for ``POISON_INUSE``. When using +this an Oops will often show the poisoned data instead of zero which is the +default. Once you have worked out a fix please submit it upstream. After all open source is about sharing what you do and don't you want to be recognised for your genius? -Please do read Documentation/SubmittingPatches though to help your code get -accepted. +Please do read :ref:`Documentation/SubmittingPatches ` +though to help your code get accepted. -- cgit v1.2.3 From d9f92f9f9d0e6e6ea98cd5c52cfd474cff20af22 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 15:47:58 -0300 Subject: Documentation/devices.rst: convert it to ReST markup - use a quote block for the big device major/minor list; - use tables for the other device tables; - fix the chapter/section/subsection markups; - use ``foo`` for monotonic; - use .. attention:: for the attention note to developers; - use cross-references where needed; - cleanup whitespaces; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/devices.txt | 1090 +++++++++++++++++++++++---------------------- 1 file changed, 558 insertions(+), 532 deletions(-) diff --git a/Documentation/devices.txt b/Documentation/devices.txt index 4035eca87144..17b365331f23 100644 --- a/Documentation/devices.txt +++ b/Documentation/devices.txt @@ -1,14 +1,16 @@ - LINUX ALLOCATED DEVICES (4.x+ version) +Linux allocated devices (4.x+ version) +====================================== This list is the Linux Device List, the official registry of allocated -device numbers and /dev directory nodes for the Linux operating +device numbers and ``/dev`` directory nodes for the Linux operating system. The LaTeX version of this document is no longer maintained, nor is the document that used to reside at lanana.org. This version in the mainline Linux kernel is the master document. Updates shall be sent -as patches to the kernel maintainers (see the SubmittingPatches document). +as patches to the kernel maintainers (see the +:ref:`Documentation/SubmittingPatches ` document). Specifically explore the sections titled "CHAR and MISC DRIVERS", and "BLOCK LAYER" in the MAINTAINERS file to find the right maintainers to involve for character and block devices. @@ -26,38 +28,41 @@ permission of the authors, assuming the authors can be contacted without an unreasonable effort. - **** DEVICE DRIVERS AUTHORS PLEASE READ THIS **** +.. attention:: -Linux now has extensive support for dynamic allocation of device numbering -and can use sysfs and udev (systemd) to handle the naming needs. There are -still some exceptions in the serial and boot device area. Before asking -for a device number make sure you actually need one. + DEVICE DRIVERS AUTHORS PLEASE READ THIS -To have a major number allocated, or a minor number in situations -where that applies (e.g. busmice), please submit a patch and send to -the authors as indicated above. + Linux now has extensive support for dynamic allocation of device numbering + and can use ``sysfs`` and ``udev`` (``systemd``) to handle the naming needs. + There are still some exceptions in the serial and boot device area. Before + asking for a device number make sure you actually need one. -Keep the description of the device *in the same format -as this list*. The reason for this is that it is the only way we have -found to ensure we have all the requisite information to publish your -device and avoid conflicts. + To have a major number allocated, or a minor number in situations + where that applies (e.g. busmice), please submit a patch and send to + the authors as indicated above. -Finally, sometimes we have to play "namespace police." Please don't be -offended. We often get submissions for /dev names that would be bound -to cause conflicts down the road. We are trying to avoid getting in a -situation where we would have to suffer an incompatible forward -change. Therefore, please consult with us *before* you make your -device names and numbers in any way public, at least to the point -where it would be at all difficult to get them changed. + Keep the description of the device *in the same format + as this list*. The reason for this is that it is the only way we have + found to ensure we have all the requisite information to publish your + device and avoid conflicts. -Your cooperation is appreciated. + Finally, sometimes we have to play "namespace police." Please don't be + offended. We often get submissions for ``/dev`` names that would be bound + to cause conflicts down the road. We are trying to avoid getting in a + situation where we would have to suffer an incompatible forward + change. Therefore, please consult with us **before** you make your + device names and numbers in any way public, at least to the point + where it would be at all difficult to get them changed. + Your cooperation is appreciated. - 0 Unnamed devices (e.g. non-device mounts) +:: + + 0 Unnamed devices (e.g. non-device mounts) 0 = reserved as null device number See block major 144, 145, 146 for expansion areas. - 1 char Memory devices + 1 char Memory devices 1 = /dev/mem Physical memory access 2 = /dev/kmem Kernel virtual memory access 3 = /dev/null Null device @@ -72,7 +77,7 @@ Your cooperation is appreciated. export the buffered printk records. 12 = /dev/oldmem OBSOLETE - replaced by /proc/vmcore - 1 block RAM disk + 1 block RAM disk 0 = /dev/ram0 First RAM disk 1 = /dev/ram1 Second RAM disk ... @@ -83,7 +88,7 @@ Your cooperation is appreciated. by the boot loader; newer kernels use /dev/ram0 for the initrd. - 2 char Pseudo-TTY masters + 2 char Pseudo-TTY masters 0 = /dev/ptyp0 First PTY master 1 = /dev/ptyp1 Second PTY master ... @@ -101,7 +106,7 @@ Your cooperation is appreciated. master multiplex (/dev/ptmx) to acquire a PTY on demand. - 2 block Floppy disks + 2 block Floppy disks 0 = /dev/fd0 Controller 0, drive 0, autodetect 1 = /dev/fd1 Controller 0, drive 1, autodetect 2 = /dev/fd2 Controller 0, drive 2, autodetect @@ -158,7 +163,7 @@ Your cooperation is appreciated. and E for the 3.5" models have been deprecated, since the drive type is insignificant for these devices. - 3 char Pseudo-TTY slaves + 3 char Pseudo-TTY slaves 0 = /dev/ttyp0 First PTY slave 1 = /dev/ttyp1 Second PTY slave ... @@ -167,7 +172,7 @@ Your cooperation is appreciated. These are the old-style (BSD) PTY devices; Unix98 devices are on major 136 and above. - 3 block First MFM, RLL and IDE hard disk/CD-ROM interface + 3 block First MFM, RLL and IDE hard disk/CD-ROM interface 0 = /dev/hda Master: whole disk (or CD-ROM) 64 = /dev/hdb Slave: whole disk (or CD-ROM) @@ -183,7 +188,7 @@ Your cooperation is appreciated. Other versions of Linux use partitioning schemes appropriate to their respective architectures. - 4 char TTY devices + 4 char TTY devices 0 = /dev/tty0 Current virtual console 1 = /dev/tty1 First virtual console @@ -199,13 +204,13 @@ Your cooperation is appreciated. number for BSD PTY devices. As of Linux 2.1.115, this is no longer supported. Use major numbers 2 and 3. - 4 block Aliases for dynamically allocated major devices to be used + 4 block Aliases for dynamically allocated major devices to be used when its not possible to create the real device nodes because the root filesystem is mounted read-only. - 0 = /dev/root + 0 = /dev/root - 5 char Alternate TTY devices + 5 char Alternate TTY devices 0 = /dev/tty Current TTY device 1 = /dev/console System console 2 = /dev/ptmx PTY master multiplex @@ -218,7 +223,7 @@ Your cooperation is appreciated. the section on terminal devices for more information on /dev/console. - 6 char Parallel printer devices + 6 char Parallel printer devices 0 = /dev/lp0 Parallel printer on parport0 1 = /dev/lp1 Parallel printer on parport1 ... @@ -227,7 +232,7 @@ Your cooperation is appreciated. between parallel ports and I/O addresses. Instead, they are redirected through the parport multiplex layer. - 7 char Virtual console capture devices + 7 char Virtual console capture devices 0 = /dev/vcs Current vc text contents 1 = /dev/vcs1 tty1 text contents ... @@ -239,7 +244,7 @@ Your cooperation is appreciated. NOTE: These devices permit both read and write access. - 7 block Loopback devices + 7 block Loopback devices 0 = /dev/loop0 First loop device 1 = /dev/loop1 Second loop device ... @@ -248,7 +253,7 @@ Your cooperation is appreciated. associated with block devices. The binding to the loop devices is handled by mount(8) or losetup(8). - 8 block SCSI disk devices (0-15) + 8 block SCSI disk devices (0-15) 0 = /dev/sda First SCSI disk whole disk 16 = /dev/sdb Second SCSI disk whole disk 32 = /dev/sdc Third SCSI disk whole disk @@ -259,7 +264,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 9 char SCSI tape devices + 9 char SCSI tape devices 0 = /dev/st0 First SCSI tape, mode 0 1 = /dev/st1 Second SCSI tape, mode 0 ... @@ -290,7 +295,7 @@ Your cooperation is appreciated. ioctl()'s can be used to rewind the tape regardless of the device used to access it. - 9 block Metadisk (RAID) devices + 9 block Metadisk (RAID) devices 0 = /dev/md0 First metadisk group 1 = /dev/md1 Second metadisk group ... @@ -298,7 +303,7 @@ Your cooperation is appreciated. The metadisk driver is used to span a filesystem across multiple physical disks. - 10 char Non-serial mice, misc features + 10 char Non-serial mice, misc features 0 = /dev/logibm Logitech bus mouse 1 = /dev/psaux PS/2-style mouse port 2 = /dev/inportbm Microsoft Inport bus mouse @@ -428,22 +433,22 @@ Your cooperation is appreciated. 240-254 Reserved for local use 255 Reserved for MISC_DYNAMIC_MINOR - 11 char Raw keyboard device (Linux/SPARC only) + 11 char Raw keyboard device (Linux/SPARC only) 0 = /dev/kbd Raw keyboard device - 11 char Serial Mux device (Linux/PA-RISC only) + 11 char Serial Mux device (Linux/PA-RISC only) 0 = /dev/ttyB0 First mux port 1 = /dev/ttyB1 Second mux port ... - 11 block SCSI CD-ROM devices + 11 block SCSI CD-ROM devices 0 = /dev/scd0 First SCSI CD-ROM 1 = /dev/scd1 Second SCSI CD-ROM ... The prefix /dev/sr (instead of /dev/scd) has been deprecated. - 12 char QIC-02 tape + 12 char QIC-02 tape 2 = /dev/ntpqic11 QIC-11, no rewind-on-close 3 = /dev/tpqic11 QIC-11, rewind-on-close 4 = /dev/ntpqic24 QIC-24, no rewind-on-close @@ -456,9 +461,9 @@ Your cooperation is appreciated. The device names specified are proposed -- if there are "standard" names for these devices, please let me know. - 12 block + 12 block - 13 char Input core + 13 char Input core 0 = /dev/input/js0 First joystick 1 = /dev/input/js1 Second joystick ... @@ -472,10 +477,10 @@ Your cooperation is appreciated. Each device type has 5 bits (32 minors). - 13 block Previously used for the XT disk (/dev/xdN) + 13 block Previously used for the XT disk (/dev/xdN) Deleted in kernel v3.9. - 14 char Open Sound System (OSS) + 14 char Open Sound System (OSS) 0 = /dev/mixer Mixer control 1 = /dev/sequencer Audio sequencer 2 = /dev/midi00 First MIDI port @@ -493,44 +498,44 @@ Your cooperation is appreciated. 34 = /dev/midi02 Third MIDI port 50 = /dev/midi03 Fourth MIDI port - 14 block + 14 block - 15 char Joystick + 15 char Joystick 0 = /dev/js0 First analog joystick 1 = /dev/js1 Second analog joystick ... 128 = /dev/djs0 First digital joystick 129 = /dev/djs1 Second digital joystick ... - 15 block Sony CDU-31A/CDU-33A CD-ROM + 15 block Sony CDU-31A/CDU-33A CD-ROM 0 = /dev/sonycd Sony CDU-31a CD-ROM - 16 char Non-SCSI scanners + 16 char Non-SCSI scanners 0 = /dev/gs4500 Genius 4500 handheld scanner - 16 block GoldStar CD-ROM + 16 block GoldStar CD-ROM 0 = /dev/gscd GoldStar CD-ROM - 17 char OBSOLETE (was Chase serial card) + 17 char OBSOLETE (was Chase serial card) 0 = /dev/ttyH0 First Chase port 1 = /dev/ttyH1 Second Chase port ... - 17 block Optics Storage CD-ROM + 17 block Optics Storage CD-ROM 0 = /dev/optcd Optics Storage CD-ROM - 18 char OBSOLETE (was Chase serial card - alternate devices) + 18 char OBSOLETE (was Chase serial card - alternate devices) 0 = /dev/cuh0 Callout device for ttyH0 1 = /dev/cuh1 Callout device for ttyH1 ... - 18 block Sanyo CD-ROM + 18 block Sanyo CD-ROM 0 = /dev/sjcd Sanyo CD-ROM - 19 char Cyclades serial card + 19 char Cyclades serial card 0 = /dev/ttyC0 First Cyclades port ... 31 = /dev/ttyC31 32nd Cyclades port - 19 block "Double" compressed disk + 19 block "Double" compressed disk 0 = /dev/double0 First compressed disk ... 7 = /dev/double7 Eighth compressed disk @@ -541,15 +546,15 @@ Your cooperation is appreciated. See the Double documentation for the meaning of the mirror devices. - 20 char Cyclades serial card - alternate devices + 20 char Cyclades serial card - alternate devices 0 = /dev/cub0 Callout device for ttyC0 ... 31 = /dev/cub31 Callout device for ttyC31 - 20 block Hitachi CD-ROM (under development) + 20 block Hitachi CD-ROM (under development) 0 = /dev/hitcd Hitachi CD-ROM - 21 char Generic SCSI access + 21 char Generic SCSI access 0 = /dev/sg0 First generic SCSI device 1 = /dev/sg1 Second generic SCSI device ... @@ -559,7 +564,7 @@ Your cooperation is appreciated. the system and is counter to standard Linux device-naming practice. - 21 block Acorn MFM hard drive interface + 21 block Acorn MFM hard drive interface 0 = /dev/mfma First MFM drive whole disk 64 = /dev/mfmb Second MFM drive whole disk @@ -567,25 +572,25 @@ Your cooperation is appreciated. Partitions are handled the same way as for IDE disks (see major number 3). - 22 char Digiboard serial card + 22 char Digiboard serial card 0 = /dev/ttyD0 First Digiboard port 1 = /dev/ttyD1 Second Digiboard port ... - 22 block Second IDE hard disk/CD-ROM interface + 22 block Second IDE hard disk/CD-ROM interface 0 = /dev/hdc Master: whole disk (or CD-ROM) 64 = /dev/hdd Slave: whole disk (or CD-ROM) Partitions are handled the same way as for the first interface (see major number 3). - 23 char Digiboard serial card - alternate devices + 23 char Digiboard serial card - alternate devices 0 = /dev/cud0 Callout device for ttyD0 1 = /dev/cud1 Callout device for ttyD1 ... - 23 block Mitsumi proprietary CD-ROM + 23 block Mitsumi proprietary CD-ROM 0 = /dev/mcd Mitsumi CD-ROM - 24 char Stallion serial card + 24 char Stallion serial card 0 = /dev/ttyE0 Stallion port 0 card 0 1 = /dev/ttyE1 Stallion port 1 card 0 ... @@ -598,10 +603,10 @@ Your cooperation is appreciated. 192 = /dev/ttyE192 Stallion port 0 card 3 193 = /dev/ttyE193 Stallion port 1 card 3 ... - 24 block Sony CDU-535 CD-ROM + 24 block Sony CDU-535 CD-ROM 0 = /dev/cdu535 Sony CDU-535 CD-ROM - 25 char Stallion serial card - alternate devices + 25 char Stallion serial card - alternate devices 0 = /dev/cue0 Callout device for ttyE0 1 = /dev/cue1 Callout device for ttyE1 ... @@ -614,21 +619,21 @@ Your cooperation is appreciated. 192 = /dev/cue192 Callout device for ttyE192 193 = /dev/cue193 Callout device for ttyE193 ... - 25 block First Matsushita (Panasonic/SoundBlaster) CD-ROM + 25 block First Matsushita (Panasonic/SoundBlaster) CD-ROM 0 = /dev/sbpcd0 Panasonic CD-ROM controller 0 unit 0 1 = /dev/sbpcd1 Panasonic CD-ROM controller 0 unit 1 2 = /dev/sbpcd2 Panasonic CD-ROM controller 0 unit 2 3 = /dev/sbpcd3 Panasonic CD-ROM controller 0 unit 3 - 26 char + 26 char - 26 block Second Matsushita (Panasonic/SoundBlaster) CD-ROM + 26 block Second Matsushita (Panasonic/SoundBlaster) CD-ROM 0 = /dev/sbpcd4 Panasonic CD-ROM controller 1 unit 0 1 = /dev/sbpcd5 Panasonic CD-ROM controller 1 unit 1 2 = /dev/sbpcd6 Panasonic CD-ROM controller 1 unit 2 3 = /dev/sbpcd7 Panasonic CD-ROM controller 1 unit 3 - 27 char QIC-117 tape + 27 char QIC-117 tape 0 = /dev/qft0 Unit 0, rewind-on-close 1 = /dev/qft1 Unit 1, rewind-on-close 2 = /dev/qft2 Unit 2, rewind-on-close @@ -654,29 +659,29 @@ Your cooperation is appreciated. 38 = /dev/nrawqft2 Unit 2, no rewind-on-close, no file marks 39 = /dev/nrawqft3 Unit 3, no rewind-on-close, no file marks - 27 block Third Matsushita (Panasonic/SoundBlaster) CD-ROM + 27 block Third Matsushita (Panasonic/SoundBlaster) CD-ROM 0 = /dev/sbpcd8 Panasonic CD-ROM controller 2 unit 0 1 = /dev/sbpcd9 Panasonic CD-ROM controller 2 unit 1 2 = /dev/sbpcd10 Panasonic CD-ROM controller 2 unit 2 3 = /dev/sbpcd11 Panasonic CD-ROM controller 2 unit 3 - 28 char Stallion serial card - card programming + 28 char Stallion serial card - card programming 0 = /dev/staliomem0 First Stallion card I/O memory 1 = /dev/staliomem1 Second Stallion card I/O memory 2 = /dev/staliomem2 Third Stallion card I/O memory 3 = /dev/staliomem3 Fourth Stallion card I/O memory - 28 char Atari SLM ACSI laser printer (68k/Atari) + 28 char Atari SLM ACSI laser printer (68k/Atari) 0 = /dev/slm0 First SLM laser printer 1 = /dev/slm1 Second SLM laser printer ... - 28 block Fourth Matsushita (Panasonic/SoundBlaster) CD-ROM + 28 block Fourth Matsushita (Panasonic/SoundBlaster) CD-ROM 0 = /dev/sbpcd12 Panasonic CD-ROM controller 3 unit 0 1 = /dev/sbpcd13 Panasonic CD-ROM controller 3 unit 1 2 = /dev/sbpcd14 Panasonic CD-ROM controller 3 unit 2 3 = /dev/sbpcd15 Panasonic CD-ROM controller 3 unit 3 - 28 block ACSI disk (68k/Atari) + 28 block ACSI disk (68k/Atari) 0 = /dev/ada First ACSI disk whole disk 16 = /dev/adb Second ACSI disk whole disk 32 = /dev/adc Third ACSI disk whole disk @@ -687,16 +692,16 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15, like SCSI. - 29 char Universal frame buffer + 29 char Universal frame buffer 0 = /dev/fb0 First frame buffer 1 = /dev/fb1 Second frame buffer ... 31 = /dev/fb31 32nd frame buffer - 29 block Aztech/Orchid/Okano/Wearnes CD-ROM + 29 block Aztech/Orchid/Okano/Wearnes CD-ROM 0 = /dev/aztcd Aztech CD-ROM - 30 char iBCS-2 compatibility devices + 30 char iBCS-2 compatibility devices 0 = /dev/socksys Socket access 1 = /dev/spx SVR3 local X interface 32 = /dev/inet/ip Network access @@ -727,17 +732,17 @@ Your cooperation is appreciated. /dev/nfsd -> /dev/socksys /dev/X0R -> /dev/null (? apparently not required ?) - 30 block Philips LMS CM-205 CD-ROM + 30 block Philips LMS CM-205 CD-ROM 0 = /dev/cm205cd Philips LMS CM-205 CD-ROM /dev/lmscd is an older name for this device. This driver does not work with the CM-205MS CD-ROM. - 31 char MPU-401 MIDI + 31 char MPU-401 MIDI 0 = /dev/mpu401data MPU-401 data port 1 = /dev/mpu401stat MPU-401 status port - 31 block ROM/flash memory card + 31 block ROM/flash memory card 0 = /dev/rom0 First ROM card (rw) ... 7 = /dev/rom7 Eighth ROM card (rw) @@ -756,25 +761,25 @@ Your cooperation is appreciated. devices. The read-only devices (ro) support reading only. - 32 char Specialix serial card + 32 char Specialix serial card 0 = /dev/ttyX0 First Specialix port 1 = /dev/ttyX1 Second Specialix port ... - 32 block Philips LMS CM-206 CD-ROM + 32 block Philips LMS CM-206 CD-ROM 0 = /dev/cm206cd Philips LMS CM-206 CD-ROM - 33 char Specialix serial card - alternate devices + 33 char Specialix serial card - alternate devices 0 = /dev/cux0 Callout device for ttyX0 1 = /dev/cux1 Callout device for ttyX1 ... - 33 block Third IDE hard disk/CD-ROM interface + 33 block Third IDE hard disk/CD-ROM interface 0 = /dev/hde Master: whole disk (or CD-ROM) 64 = /dev/hdf Slave: whole disk (or CD-ROM) Partitions are handled the same way as for the first interface (see major number 3). - 34 char Z8530 HDLC driver + 34 char Z8530 HDLC driver 0 = /dev/scc0 First Z8530, first port 1 = /dev/scc1 First Z8530, second port 2 = /dev/scc2 Second Z8530, first port @@ -785,14 +790,14 @@ Your cooperation is appreciated. /dev/sc1 for /dev/scc0, /dev/sc2 for /dev/scc1, and so on. - 34 block Fourth IDE hard disk/CD-ROM interface + 34 block Fourth IDE hard disk/CD-ROM interface 0 = /dev/hdg Master: whole disk (or CD-ROM) 64 = /dev/hdh Slave: whole disk (or CD-ROM) Partitions are handled the same way as for the first interface (see major number 3). - 35 char tclmidi MIDI driver + 35 char tclmidi MIDI driver 0 = /dev/midi0 First MIDI port, kernel timed 1 = /dev/midi1 Second MIDI port, kernel timed 2 = /dev/midi2 Third MIDI port, kernel timed @@ -806,10 +811,10 @@ Your cooperation is appreciated. 130 = /dev/smpte2 Third MIDI port, SMPTE timed 131 = /dev/smpte3 Fourth MIDI port, SMPTE timed - 35 block Slow memory ramdisk + 35 block Slow memory ramdisk 0 = /dev/slram Slow memory ramdisk - 36 char Netlink support + 36 char Netlink support 0 = /dev/route Routing, device updates, kernel to user 1 = /dev/skip enSKIP security cache control 3 = /dev/fwmonitor Firewall packet copies @@ -817,9 +822,9 @@ Your cooperation is appreciated. ... 31 = /dev/tap15 16th Ethertap device - 36 block OBSOLETE (was MCA ESDI hard disk) + 36 block OBSOLETE (was MCA ESDI hard disk) - 37 char IDE tape + 37 char IDE tape 0 = /dev/ht0 First IDE tape 1 = /dev/ht1 Second IDE tape ... @@ -829,10 +834,10 @@ Your cooperation is appreciated. Currently, only one IDE tape drive is supported. - 37 block Zorro II ramdisk + 37 block Zorro II ramdisk 0 = /dev/z2ram Zorro II ramdisk - 38 char Myricom PCI Myrinet board + 38 char Myricom PCI Myrinet board 0 = /dev/mlanai0 First Myrinet board 1 = /dev/mlanai1 Second Myrinet board ... @@ -841,9 +846,9 @@ Your cooperation is appreciated. and "user level packet I/O." This board is also accessible as a standard networking "eth" device. - 38 block OBSOLETE (was Linux/AP+) + 38 block OBSOLETE (was Linux/AP+) - 39 char ML-16P experimental I/O board + 39 char ML-16P experimental I/O board 0 = /dev/ml16pa-a0 First card, first analog channel 1 = /dev/ml16pa-a1 First card, second analog channel ... @@ -861,20 +866,20 @@ Your cooperation is appreciated. 50 = /dev/ml16pb-c1 Second card, second counter/timer 51 = /dev/ml16pb-c2 Second card, third counter/timer ... - 39 block + 39 block - 40 char + 40 char - 40 block + 40 block - 41 char Yet Another Micro Monitor + 41 char Yet Another Micro Monitor 0 = /dev/yamm Yet Another Micro Monitor - 41 block + 41 block - 42 char Demo/sample use + 42 char Demo/sample use - 42 block Demo/sample use + 42 block Demo/sample use This number is intended for use in sample code, as well as a general "example" device number. It @@ -887,12 +892,12 @@ Your cooperation is appreciated. IN PARTICULAR, ANY DISTRIBUTION WHICH CONTAINS A DEVICE DRIVER USING MAJOR NUMBER 42 IS NONCOMPLIANT. - 43 char isdn4linux virtual modem + 43 char isdn4linux virtual modem 0 = /dev/ttyI0 First virtual modem ... 63 = /dev/ttyI63 64th virtual modem - 43 block Network block devices + 43 block Network block devices 0 = /dev/nb0 First network block device 1 = /dev/nb1 Second network block device ... @@ -904,12 +909,12 @@ Your cooperation is appreciated. to mounting filesystems over the net, swapping over the net, implementing block device in userland etc. - 44 char isdn4linux virtual modem - alternate devices + 44 char isdn4linux virtual modem - alternate devices 0 = /dev/cui0 Callout device for ttyI0 ... 63 = /dev/cui63 Callout device for ttyI63 - 44 block Flash Translation Layer (FTL) filesystems + 44 block Flash Translation Layer (FTL) filesystems 0 = /dev/ftla FTL on first Memory Technology Device 16 = /dev/ftlb FTL on second Memory Technology Device 32 = /dev/ftlc FTL on third Memory Technology Device @@ -920,7 +925,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the partition limit is 15 rather than 63 per disk (same as SCSI.) - 45 char isdn4linux ISDN BRI driver + 45 char isdn4linux ISDN BRI driver 0 = /dev/isdn0 First virtual B channel raw data ... 63 = /dev/isdn63 64th virtual B channel raw data @@ -934,7 +939,7 @@ Your cooperation is appreciated. 255 = /dev/isdninfo ISDN monitor interface - 45 block Parallel port IDE disk devices + 45 block Parallel port IDE disk devices 0 = /dev/pda First parallel port IDE disk 16 = /dev/pdb Second parallel port IDE disk 32 = /dev/pdc Third parallel port IDE disk @@ -944,21 +949,21 @@ Your cooperation is appreciated. disks (see major number 3) except that the partition limit is 15 rather than 63 per disk. - 46 char Comtrol Rocketport serial card + 46 char Comtrol Rocketport serial card 0 = /dev/ttyR0 First Rocketport port 1 = /dev/ttyR1 Second Rocketport port ... - 46 block Parallel port ATAPI CD-ROM devices + 46 block Parallel port ATAPI CD-ROM devices 0 = /dev/pcd0 First parallel port ATAPI CD-ROM 1 = /dev/pcd1 Second parallel port ATAPI CD-ROM 2 = /dev/pcd2 Third parallel port ATAPI CD-ROM 3 = /dev/pcd3 Fourth parallel port ATAPI CD-ROM - 47 char Comtrol Rocketport serial card - alternate devices + 47 char Comtrol Rocketport serial card - alternate devices 0 = /dev/cur0 Callout device for ttyR0 1 = /dev/cur1 Callout device for ttyR1 ... - 47 block Parallel port ATAPI disk devices + 47 block Parallel port ATAPI disk devices 0 = /dev/pf0 First parallel port ATAPI disk 1 = /dev/pf1 Second parallel port ATAPI disk 2 = /dev/pf2 Third parallel port ATAPI disk @@ -967,11 +972,11 @@ Your cooperation is appreciated. This driver is intended for floppy disks and similar devices and hence does not support partitioning. - 48 char SDL RISCom serial card + 48 char SDL RISCom serial card 0 = /dev/ttyL0 First RISCom port 1 = /dev/ttyL1 Second RISCom port ... - 48 block Mylex DAC960 PCI RAID controller; first controller + 48 block Mylex DAC960 PCI RAID controller; first controller 0 = /dev/rd/c0d0 First disk, whole disk 8 = /dev/rd/c0d1 Second disk, whole disk ... @@ -983,11 +988,11 @@ Your cooperation is appreciated. ... 7 = /dev/rd/c?d?p7 Seventh partition - 49 char SDL RISCom serial card - alternate devices + 49 char SDL RISCom serial card - alternate devices 0 = /dev/cul0 Callout device for ttyL0 1 = /dev/cul1 Callout device for ttyL1 ... - 49 block Mylex DAC960 PCI RAID controller; second controller + 49 block Mylex DAC960 PCI RAID controller; second controller 0 = /dev/rd/c1d0 First disk, whole disk 8 = /dev/rd/c1d1 Second disk, whole disk ... @@ -995,19 +1000,19 @@ Your cooperation is appreciated. Partitions are handled as for major 48. - 50 char Reserved for GLINT + 50 char Reserved for GLINT - 50 block Mylex DAC960 PCI RAID controller; third controller + 50 block Mylex DAC960 PCI RAID controller; third controller 0 = /dev/rd/c2d0 First disk, whole disk 8 = /dev/rd/c2d1 Second disk, whole disk ... 248 = /dev/rd/c2d31 32nd disk, whole disk - 51 char Baycom radio modem OR Radio Tech BIM-XXX-RS232 radio modem + 51 char Baycom radio modem OR Radio Tech BIM-XXX-RS232 radio modem 0 = /dev/bc0 First Baycom radio modem 1 = /dev/bc1 Second Baycom radio modem ... - 51 block Mylex DAC960 PCI RAID controller; fourth controller + 51 block Mylex DAC960 PCI RAID controller; fourth controller 0 = /dev/rd/c3d0 First disk, whole disk 8 = /dev/rd/c3d1 Second disk, whole disk ... @@ -1015,13 +1020,13 @@ Your cooperation is appreciated. Partitions are handled as for major 48. - 52 char Spellcaster DataComm/BRI ISDN card + 52 char Spellcaster DataComm/BRI ISDN card 0 = /dev/dcbri0 First DataComm card 1 = /dev/dcbri1 Second DataComm card 2 = /dev/dcbri2 Third DataComm card 3 = /dev/dcbri3 Fourth DataComm card - 52 block Mylex DAC960 PCI RAID controller; fifth controller + 52 block Mylex DAC960 PCI RAID controller; fifth controller 0 = /dev/rd/c4d0 First disk, whole disk 8 = /dev/rd/c4d1 Second disk, whole disk ... @@ -1029,7 +1034,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. - 53 char BDM interface for remote debugging MC683xx microcontrollers + 53 char BDM interface for remote debugging MC683xx microcontrollers 0 = /dev/pd_bdm0 PD BDM interface on lp0 1 = /dev/pd_bdm1 PD BDM interface on lp1 2 = /dev/pd_bdm2 PD BDM interface on lp2 @@ -1043,7 +1048,7 @@ Your cooperation is appreciated. Domain Interface and ICD is the commercial interface by P&E. - 53 block Mylex DAC960 PCI RAID controller; sixth controller + 53 block Mylex DAC960 PCI RAID controller; sixth controller 0 = /dev/rd/c5d0 First disk, whole disk 8 = /dev/rd/c5d1 Second disk, whole disk ... @@ -1051,7 +1056,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. - 54 char Electrocardiognosis Holter serial card + 54 char Electrocardiognosis Holter serial card 0 = /dev/holter0 First Holter port 1 = /dev/holter1 Second Holter port 2 = /dev/holter2 Third Holter port @@ -1060,7 +1065,7 @@ Your cooperation is appreciated. to transfer data from Holter 24-hour heart monitoring equipment. - 54 block Mylex DAC960 PCI RAID controller; seventh controller + 54 block Mylex DAC960 PCI RAID controller; seventh controller 0 = /dev/rd/c6d0 First disk, whole disk 8 = /dev/rd/c6d1 Second disk, whole disk ... @@ -1068,10 +1073,10 @@ Your cooperation is appreciated. Partitions are handled as for major 48. - 55 char DSP56001 digital signal processor + 55 char DSP56001 digital signal processor 0 = /dev/dsp56k First DSP56001 - 55 block Mylex DAC960 PCI RAID controller; eighth controller + 55 block Mylex DAC960 PCI RAID controller; eighth controller 0 = /dev/rd/c7d0 First disk, whole disk 8 = /dev/rd/c7d1 Second disk, whole disk ... @@ -1079,42 +1084,42 @@ Your cooperation is appreciated. Partitions are handled as for major 48. - 56 char Apple Desktop Bus + 56 char Apple Desktop Bus 0 = /dev/adb ADB bus control Additional devices will be added to this number, all starting with /dev/adb. - 56 block Fifth IDE hard disk/CD-ROM interface + 56 block Fifth IDE hard disk/CD-ROM interface 0 = /dev/hdi Master: whole disk (or CD-ROM) 64 = /dev/hdj Slave: whole disk (or CD-ROM) Partitions are handled the same way as for the first interface (see major number 3). - 57 char Hayes ESP serial card + 57 char Hayes ESP serial card 0 = /dev/ttyP0 First ESP port 1 = /dev/ttyP1 Second ESP port ... - 57 block Sixth IDE hard disk/CD-ROM interface + 57 block Sixth IDE hard disk/CD-ROM interface 0 = /dev/hdk Master: whole disk (or CD-ROM) 64 = /dev/hdl Slave: whole disk (or CD-ROM) Partitions are handled the same way as for the first interface (see major number 3). - 58 char Hayes ESP serial card - alternate devices + 58 char Hayes ESP serial card - alternate devices 0 = /dev/cup0 Callout device for ttyP0 1 = /dev/cup1 Callout device for ttyP1 ... - 58 block Reserved for logical volume manager + 58 block Reserved for logical volume manager - 59 char sf firewall package + 59 char sf firewall package 0 = /dev/firewall Communication with sf kernel module - 59 block Generic PDA filesystem device + 59 block Generic PDA filesystem device 0 = /dev/pda0 First PDA device 1 = /dev/pda1 Second PDA device ... @@ -1127,17 +1132,17 @@ Your cooperation is appreciated. NAMING CONFLICT -- PROPOSED REVISED NAME /dev/rpda0 etc - 60-63 char LOCAL/EXPERIMENTAL USE + 60-63 char LOCAL/EXPERIMENTAL USE - 60-63 block LOCAL/EXPERIMENTAL USE + 60-63 block LOCAL/EXPERIMENTAL USE Allocated for local/experimental use. For devices not assigned official numbers, these ranges should be used in order to avoid conflicting with future assignments. - 64 char ENskip kernel encryption package + 64 char ENskip kernel encryption package 0 = /dev/enskip Communication with ENskip kernel module - 64 block Scramdisk/DriveCrypt encrypted devices + 64 block Scramdisk/DriveCrypt encrypted devices 0 = /dev/scramdisk/master Master node for ioctls 1 = /dev/scramdisk/1 First encrypted device 2 = /dev/scramdisk/2 Second encrypted device @@ -1152,7 +1157,7 @@ Your cooperation is appreciated. Requested by: andy@scramdisklinux.org - 65 char Sundance "plink" Transputer boards (obsolete, unused) + 65 char Sundance "plink" Transputer boards (obsolete, unused) 0 = /dev/plink0 First plink device 1 = /dev/plink1 Second plink device 2 = /dev/plink2 Third plink device @@ -1173,7 +1178,7 @@ Your cooperation is appreciated. This is a commercial driver; contact James Howes for information. - 65 block SCSI disk devices (16-31) + 65 block SCSI disk devices (16-31) 0 = /dev/sdq 17th SCSI disk whole disk 16 = /dev/sdr 18th SCSI disk whole disk 32 = /dev/sds 19th SCSI disk whole disk @@ -1184,12 +1189,12 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 66 char YARC PowerPC PCI coprocessor card + 66 char YARC PowerPC PCI coprocessor card 0 = /dev/yppcpci0 First YARC card 1 = /dev/yppcpci1 Second YARC card ... - 66 block SCSI disk devices (32-47) + 66 block SCSI disk devices (32-47) 0 = /dev/sdag 33th SCSI disk whole disk 16 = /dev/sdah 34th SCSI disk whole disk 32 = /dev/sdai 35th SCSI disk whole disk @@ -1200,12 +1205,12 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 67 char Coda network file system + 67 char Coda network file system 0 = /dev/cfs0 Coda cache manager See http://www.coda.cs.cmu.edu for information about Coda. - 67 block SCSI disk devices (48-63) + 67 block SCSI disk devices (48-63) 0 = /dev/sdaw 49th SCSI disk whole disk 16 = /dev/sdax 50th SCSI disk whole disk 32 = /dev/sday 51st SCSI disk whole disk @@ -1216,7 +1221,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 68 char CAPI 2.0 interface + 68 char CAPI 2.0 interface 0 = /dev/capi20 Control device 1 = /dev/capi20.00 First CAPI 2.0 application 2 = /dev/capi20.01 Second CAPI 2.0 application @@ -1226,7 +1231,7 @@ Your cooperation is appreciated. ISDN CAPI 2.0 driver for use with CAPI 2.0 applications; currently supports the AVM B1 card. - 68 block SCSI disk devices (64-79) + 68 block SCSI disk devices (64-79) 0 = /dev/sdbm 65th SCSI disk whole disk 16 = /dev/sdbn 66th SCSI disk whole disk 32 = /dev/sdbo 67th SCSI disk whole disk @@ -1237,10 +1242,10 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 69 char MA16 numeric accelerator card + 69 char MA16 numeric accelerator card 0 = /dev/ma16 Board memory access - 69 block SCSI disk devices (80-95) + 69 block SCSI disk devices (80-95) 0 = /dev/sdcc 81st SCSI disk whole disk 16 = /dev/sdcd 82nd SCSI disk whole disk 32 = /dev/sdce 83th SCSI disk whole disk @@ -1251,7 +1256,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 70 char SpellCaster Protocol Services Interface + 70 char SpellCaster Protocol Services Interface 0 = /dev/apscfg Configuration interface 1 = /dev/apsauth Authentication interface 2 = /dev/apslog Logging interface @@ -1260,7 +1265,7 @@ Your cooperation is appreciated. 65 = /dev/apsasync Async command interface 128 = /dev/apsmon Monitor interface - 70 block SCSI disk devices (96-111) + 70 block SCSI disk devices (96-111) 0 = /dev/sdcs 97th SCSI disk whole disk 16 = /dev/sdct 98th SCSI disk whole disk 32 = /dev/sdcu 99th SCSI disk whole disk @@ -1271,7 +1276,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 71 char Computone IntelliPort II serial card + 71 char Computone IntelliPort II serial card 0 = /dev/ttyF0 IntelliPort II board 0, port 0 1 = /dev/ttyF1 IntelliPort II board 0, port 1 ... @@ -1289,7 +1294,7 @@ Your cooperation is appreciated. ... 255 = /dev/ttyF255 IntelliPort II board 3, port 63 - 71 block SCSI disk devices (112-127) + 71 block SCSI disk devices (112-127) 0 = /dev/sddi 113th SCSI disk whole disk 16 = /dev/sddj 114th SCSI disk whole disk 32 = /dev/sddk 115th SCSI disk whole disk @@ -1300,7 +1305,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 72 char Computone IntelliPort II serial card - alternate devices + 72 char Computone IntelliPort II serial card - alternate devices 0 = /dev/cuf0 Callout device for ttyF0 1 = /dev/cuf1 Callout device for ttyF1 ... @@ -1318,7 +1323,7 @@ Your cooperation is appreciated. ... 255 = /dev/cuf255 Callout device for ttyF255 - 72 block Compaq Intelligent Drive Array, first controller + 72 block Compaq Intelligent Drive Array, first controller 0 = /dev/ida/c0d0 First logical drive whole disk 16 = /dev/ida/c0d1 Second logical drive whole disk ... @@ -1328,7 +1333,7 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. - 73 char Computone IntelliPort II serial card - control devices + 73 char Computone IntelliPort II serial card - control devices 0 = /dev/ip2ipl0 Loadware device for board 0 1 = /dev/ip2stat0 Status device for board 0 4 = /dev/ip2ipl1 Loadware device for board 1 @@ -1338,7 +1343,7 @@ Your cooperation is appreciated. 12 = /dev/ip2ipl3 Loadware device for board 3 13 = /dev/ip2stat3 Status device for board 3 - 73 block Compaq Intelligent Drive Array, second controller + 73 block Compaq Intelligent Drive Array, second controller 0 = /dev/ida/c1d0 First logical drive whole disk 16 = /dev/ida/c1d1 Second logical drive whole disk ... @@ -1348,7 +1353,7 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. - 74 char SCI bridge + 74 char SCI bridge 0 = /dev/SCI/0 SCI device 0 1 = /dev/SCI/1 SCI device 1 ... @@ -1356,7 +1361,7 @@ Your cooperation is appreciated. Currently for Dolphin Interconnect Solutions' PCI-SCI bridge. - 74 block Compaq Intelligent Drive Array, third controller + 74 block Compaq Intelligent Drive Array, third controller 0 = /dev/ida/c2d0 First logical drive whole disk 16 = /dev/ida/c2d1 Second logical drive whole disk ... @@ -1366,14 +1371,14 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. - 75 char Specialix IO8+ serial card + 75 char Specialix IO8+ serial card 0 = /dev/ttyW0 First IO8+ port, first card 1 = /dev/ttyW1 Second IO8+ port, first card ... 8 = /dev/ttyW8 First IO8+ port, second card ... - 75 block Compaq Intelligent Drive Array, fourth controller + 75 block Compaq Intelligent Drive Array, fourth controller 0 = /dev/ida/c3d0 First logical drive whole disk 16 = /dev/ida/c3d1 Second logical drive whole disk ... @@ -1383,14 +1388,14 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. - 76 char Specialix IO8+ serial card - alternate devices + 76 char Specialix IO8+ serial card - alternate devices 0 = /dev/cuw0 Callout device for ttyW0 1 = /dev/cuw1 Callout device for ttyW1 ... 8 = /dev/cuw8 Callout device for ttyW8 ... - 76 block Compaq Intelligent Drive Array, fifth controller + 76 block Compaq Intelligent Drive Array, fifth controller 0 = /dev/ida/c4d0 First logical drive whole disk 16 = /dev/ida/c4d1 Second logical drive whole disk ... @@ -1401,10 +1406,10 @@ Your cooperation is appreciated. partitions is 15. - 77 char ComScire Quantum Noise Generator + 77 char ComScire Quantum Noise Generator 0 = /dev/qng ComScire Quantum Noise Generator - 77 block Compaq Intelligent Drive Array, sixth controller + 77 block Compaq Intelligent Drive Array, sixth controller 0 = /dev/ida/c5d0 First logical drive whole disk 16 = /dev/ida/c5d1 Second logical drive whole disk ... @@ -1414,12 +1419,12 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. - 78 char PAM Software's multimodem boards + 78 char PAM Software's multimodem boards 0 = /dev/ttyM0 First PAM modem 1 = /dev/ttyM1 Second PAM modem ... - 78 block Compaq Intelligent Drive Array, seventh controller + 78 block Compaq Intelligent Drive Array, seventh controller 0 = /dev/ida/c6d0 First logical drive whole disk 16 = /dev/ida/c6d1 Second logical drive whole disk ... @@ -1429,12 +1434,12 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. - 79 char PAM Software's multimodem boards - alternate devices + 79 char PAM Software's multimodem boards - alternate devices 0 = /dev/cum0 Callout device for ttyM0 1 = /dev/cum1 Callout device for ttyM1 ... - 79 block Compaq Intelligent Drive Array, eighth controller + 79 block Compaq Intelligent Drive Array, eighth controller 0 = /dev/ida/c7d0 First logical drive whole disk 16 = /dev/ida/c7d1 Second logical drive whole disk ... @@ -1444,10 +1449,10 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. - 80 char Photometrics AT200 CCD camera + 80 char Photometrics AT200 CCD camera 0 = /dev/at200 Photometrics AT200 CCD camera - 80 block I2O hard disk + 80 block I2O hard disk 0 = /dev/i2o/hda First I2O hard disk, whole disk 16 = /dev/i2o/hdb Second I2O hard disk, whole disk ... @@ -1457,7 +1462,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 81 char video4linux + 81 char video4linux 0 = /dev/video0 Video capture/overlay device ... 63 = /dev/video63 Video capture/overlay device @@ -1475,7 +1480,7 @@ Your cooperation is appreciated. CONFIG_VIDEO_FIXED_MINOR_RANGES (default n) configuration option is set. - 81 block I2O hard disk + 81 block I2O hard disk 0 = /dev/i2o/hdq 17th I2O hard disk, whole disk 16 = /dev/i2o/hdr 18th I2O hard disk, whole disk ... @@ -1485,7 +1490,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 82 char WiNRADiO communications receiver card + 82 char WiNRADiO communications receiver card 0 = /dev/winradio0 First WiNRADiO card 1 = /dev/winradio1 Second WiNRADiO card ... @@ -1493,7 +1498,7 @@ Your cooperation is appreciated. The driver and documentation may be obtained from http://www.winradio.com/ - 82 block I2O hard disk + 82 block I2O hard disk 0 = /dev/i2o/hdag 33rd I2O hard disk, whole disk 16 = /dev/i2o/hdah 34th I2O hard disk, whole disk ... @@ -1503,14 +1508,14 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 83 char Matrox mga_vid video driver - 0 = /dev/mga_vid0 1st video card + 83 char Matrox mga_vid video driver + 0 = /dev/mga_vid0 1st video card 1 = /dev/mga_vid1 2nd video card 2 = /dev/mga_vid2 3rd video card ... - 15 = /dev/mga_vid15 16th video card + 15 = /dev/mga_vid15 16th video card - 83 block I2O hard disk + 83 block I2O hard disk 0 = /dev/i2o/hdaw 49th I2O hard disk, whole disk 16 = /dev/i2o/hdax 50th I2O hard disk, whole disk ... @@ -1520,11 +1525,11 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 84 char Ikon 1011[57] Versatec Greensheet Interface + 84 char Ikon 1011[57] Versatec Greensheet Interface 0 = /dev/ihcp0 First Greensheet port 1 = /dev/ihcp1 Second Greensheet port - 84 block I2O hard disk + 84 block I2O hard disk 0 = /dev/i2o/hdbm 65th I2O hard disk, whole disk 16 = /dev/i2o/hdbn 66th I2O hard disk, whole disk ... @@ -1534,13 +1539,13 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 85 char Linux/SGI shared memory input queue + 85 char Linux/SGI shared memory input queue 0 = /dev/shmiq Master shared input queue 1 = /dev/qcntl0 First device pushed 2 = /dev/qcntl1 Second device pushed ... - 85 block I2O hard disk + 85 block I2O hard disk 0 = /dev/i2o/hdcc 81st I2O hard disk, whole disk 16 = /dev/i2o/hdcd 82nd I2O hard disk, whole disk ... @@ -1550,12 +1555,12 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 86 char SCSI media changer + 86 char SCSI media changer 0 = /dev/sch0 First SCSI media changer 1 = /dev/sch1 Second SCSI media changer ... - 86 block I2O hard disk + 86 block I2O hard disk 0 = /dev/i2o/hdcs 97th I2O hard disk, whole disk 16 = /dev/i2o/hdct 98th I2O hard disk, whole disk ... @@ -1565,12 +1570,12 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 87 char Sony Control-A1 stereo control bus + 87 char Sony Control-A1 stereo control bus 0 = /dev/controla0 First device on chain 1 = /dev/controla1 Second device on chain ... - 87 block I2O hard disk + 87 block I2O hard disk 0 = /dev/i2o/hddi 113rd I2O hard disk, whole disk 16 = /dev/i2o/hddj 114th I2O hard disk, whole disk ... @@ -1580,59 +1585,59 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 88 char COMX synchronous serial card + 88 char COMX synchronous serial card 0 = /dev/comx0 COMX channel 0 1 = /dev/comx1 COMX channel 1 ... - 88 block Seventh IDE hard disk/CD-ROM interface + 88 block Seventh IDE hard disk/CD-ROM interface 0 = /dev/hdm Master: whole disk (or CD-ROM) 64 = /dev/hdn Slave: whole disk (or CD-ROM) Partitions are handled the same way as for the first interface (see major number 3). - 89 char I2C bus interface + 89 char I2C bus interface 0 = /dev/i2c-0 First I2C adapter 1 = /dev/i2c-1 Second I2C adapter ... - 89 block Eighth IDE hard disk/CD-ROM interface + 89 block Eighth IDE hard disk/CD-ROM interface 0 = /dev/hdo Master: whole disk (or CD-ROM) 64 = /dev/hdp Slave: whole disk (or CD-ROM) Partitions are handled the same way as for the first interface (see major number 3). - 90 char Memory Technology Device (RAM, ROM, Flash) + 90 char Memory Technology Device (RAM, ROM, Flash) 0 = /dev/mtd0 First MTD (rw) 1 = /dev/mtdr0 First MTD (ro) ... 30 = /dev/mtd15 16th MTD (rw) 31 = /dev/mtdr15 16th MTD (ro) - 90 block Ninth IDE hard disk/CD-ROM interface + 90 block Ninth IDE hard disk/CD-ROM interface 0 = /dev/hdq Master: whole disk (or CD-ROM) 64 = /dev/hdr Slave: whole disk (or CD-ROM) Partitions are handled the same way as for the first interface (see major number 3). - 91 char CAN-Bus devices + 91 char CAN-Bus devices 0 = /dev/can0 First CAN-Bus controller 1 = /dev/can1 Second CAN-Bus controller ... - 91 block Tenth IDE hard disk/CD-ROM interface + 91 block Tenth IDE hard disk/CD-ROM interface 0 = /dev/hds Master: whole disk (or CD-ROM) 64 = /dev/hdt Slave: whole disk (or CD-ROM) Partitions are handled the same way as for the first interface (see major number 3). - 92 char Reserved for ith Kommunikationstechnik MIC ISDN card + 92 char Reserved for ith Kommunikationstechnik MIC ISDN card - 92 block PPDD encrypted disk driver + 92 block PPDD encrypted disk driver 0 = /dev/ppdd0 First encrypted disk 1 = /dev/ppdd1 Second encrypted disk ... @@ -1641,35 +1646,35 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. - 93 char + 93 char - 93 block NAND Flash Translation Layer filesystem + 93 block NAND Flash Translation Layer filesystem 0 = /dev/nftla First NFTL layer 16 = /dev/nftlb Second NFTL layer ... 240 = /dev/nftlp 16th NTFL layer - 94 char + 94 char - 94 block IBM S/390 DASD block storage - 0 = /dev/dasda First DASD device, major - 1 = /dev/dasda1 First DASD device, block 1 - 2 = /dev/dasda2 First DASD device, block 2 - 3 = /dev/dasda3 First DASD device, block 3 - 4 = /dev/dasdb Second DASD device, major - 5 = /dev/dasdb1 Second DASD device, block 1 - 6 = /dev/dasdb2 Second DASD device, block 2 - 7 = /dev/dasdb3 Second DASD device, block 3 + 94 block IBM S/390 DASD block storage + 0 = /dev/dasda First DASD device, major + 1 = /dev/dasda1 First DASD device, block 1 + 2 = /dev/dasda2 First DASD device, block 2 + 3 = /dev/dasda3 First DASD device, block 3 + 4 = /dev/dasdb Second DASD device, major + 5 = /dev/dasdb1 Second DASD device, block 1 + 6 = /dev/dasdb2 Second DASD device, block 2 + 7 = /dev/dasdb3 Second DASD device, block 3 ... - 95 char IP filter + 95 char IP filter 0 = /dev/ipl Filter control device/log file 1 = /dev/ipnat NAT control device/log file 2 = /dev/ipstate State information log file 3 = /dev/ipauth Authentication control device/log file ... - 96 char Parallel port ATAPI tape devices + 96 char Parallel port ATAPI tape devices 0 = /dev/pt0 First parallel port ATAPI tape 1 = /dev/pt1 Second parallel port ATAPI tape ... @@ -1677,13 +1682,13 @@ Your cooperation is appreciated. 129 = /dev/npt1 Second p.p. ATAPI tape, no rewind ... - 96 block Inverse NAND Flash Translation Layer + 96 block Inverse NAND Flash Translation Layer 0 = /dev/inftla First INFTL layer 16 = /dev/inftlb Second INFTL layer ... 240 = /dev/inftlp 16th INTFL layer - 97 char Parallel port generic ATAPI interface + 97 char Parallel port generic ATAPI interface 0 = /dev/pg0 First parallel port ATAPI device 1 = /dev/pg1 Second parallel port ATAPI device 2 = /dev/pg2 Third parallel port ATAPI device @@ -1692,14 +1697,14 @@ Your cooperation is appreciated. These devices support the same API as the generic SCSI devices. - 98 char Control and Measurement Device (comedi) + 98 char Control and Measurement Device (comedi) 0 = /dev/comedi0 First comedi device 1 = /dev/comedi1 Second comedi device ... See http://stm.lbl.gov/comedi. - 98 block User-mode virtual block device + 98 block User-mode virtual block device 0 = /dev/ubda First user-mode block device 16 = /dev/udbb Second user-mode block device ... @@ -1710,26 +1715,26 @@ Your cooperation is appreciated. This device is used by the user-mode virtual kernel port. - 99 char Raw parallel ports + 99 char Raw parallel ports 0 = /dev/parport0 First parallel port 1 = /dev/parport1 Second parallel port ... - 99 block JavaStation flash disk + 99 block JavaStation flash disk 0 = /dev/jsfd JavaStation flash disk -100 char Telephony for Linux + 100 char Telephony for Linux 0 = /dev/phone0 First telephony device 1 = /dev/phone1 Second telephony device ... -101 char Motorola DSP 56xxx board + 101 char Motorola DSP 56xxx board 0 = /dev/mdspstat Status information 1 = /dev/mdsp1 First DSP board I/O controls ... 16 = /dev/mdsp16 16th DSP board I/O controls -101 block AMI HyperDisk RAID controller + 101 block AMI HyperDisk RAID controller 0 = /dev/amiraid/ar0 First array whole disk 16 = /dev/amiraid/ar1 Second array whole disk ... @@ -1742,9 +1747,9 @@ Your cooperation is appreciated. ... 15 = /dev/amiraid/ar?p15 15th partition -102 char + 102 char -102 block Compressed block device + 102 block Compressed block device 0 = /dev/cbd/a First compressed block device, whole device 16 = /dev/cbd/b Second compressed block device, whole device ... @@ -1754,7 +1759,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. -103 char Arla network file system + 103 char Arla network file system 0 = /dev/nnpfs0 First NNPFS device 1 = /dev/nnpfs1 Second NNPFS device @@ -1765,12 +1770,12 @@ Your cooperation is appreciated. write to or see http://www.stacken.kth.se/project/arla/ -103 block Audit device + 103 block Audit device 0 = /dev/audit Audit device -104 char Flash BIOS support + 104 char Flash BIOS support -104 block Compaq Next Generation Drive Array, first controller + 104 block Compaq Next Generation Drive Array, first controller 0 = /dev/cciss/c0d0 First logical drive, whole disk 16 = /dev/cciss/c0d1 Second logical drive, whole disk ... @@ -1780,12 +1785,12 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. -105 char Comtrol VS-1000 serial controller + 105 char Comtrol VS-1000 serial controller 0 = /dev/ttyV0 First VS-1000 port 1 = /dev/ttyV1 Second VS-1000 port ... -105 block Compaq Next Generation Drive Array, second controller + 105 block Compaq Next Generation Drive Array, second controller 0 = /dev/cciss/c1d0 First logical drive, whole disk 16 = /dev/cciss/c1d1 Second logical drive, whole disk ... @@ -1795,12 +1800,12 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. -106 char Comtrol VS-1000 serial controller - alternate devices + 106 char Comtrol VS-1000 serial controller - alternate devices 0 = /dev/cuv0 First VS-1000 port 1 = /dev/cuv1 Second VS-1000 port ... -106 block Compaq Next Generation Drive Array, third controller + 106 block Compaq Next Generation Drive Array, third controller 0 = /dev/cciss/c2d0 First logical drive, whole disk 16 = /dev/cciss/c2d1 Second logical drive, whole disk ... @@ -1810,10 +1815,10 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. -107 char 3Dfx Voodoo Graphics device + 107 char 3Dfx Voodoo Graphics device 0 = /dev/3dfx Primary 3Dfx graphics device -107 block Compaq Next Generation Drive Array, fourth controller + 107 block Compaq Next Generation Drive Array, fourth controller 0 = /dev/cciss/c3d0 First logical drive, whole disk 16 = /dev/cciss/c3d1 Second logical drive, whole disk ... @@ -1823,10 +1828,10 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. -108 char Device independent PPP interface + 108 char Device independent PPP interface 0 = /dev/ppp Device independent PPP interface -108 block Compaq Next Generation Drive Array, fifth controller + 108 block Compaq Next Generation Drive Array, fifth controller 0 = /dev/cciss/c4d0 First logical drive, whole disk 16 = /dev/cciss/c4d1 Second logical drive, whole disk ... @@ -1836,9 +1841,9 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. -109 char Reserved for logical volume manager + 109 char Reserved for logical volume manager -109 block Compaq Next Generation Drive Array, sixth controller + 109 block Compaq Next Generation Drive Array, sixth controller 0 = /dev/cciss/c5d0 First logical drive, whole disk 16 = /dev/cciss/c5d1 Second logical drive, whole disk ... @@ -1848,12 +1853,12 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. -110 char miroMEDIA Surround board + 110 char miroMEDIA Surround board 0 = /dev/srnd0 First miroMEDIA Surround board 1 = /dev/srnd1 Second miroMEDIA Surround board ... -110 block Compaq Next Generation Drive Array, seventh controller + 110 block Compaq Next Generation Drive Array, seventh controller 0 = /dev/cciss/c6d0 First logical drive, whole disk 16 = /dev/cciss/c6d1 Second logical drive, whole disk ... @@ -1863,9 +1868,9 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. -111 char + 111 char -111 block Compaq Next Generation Drive Array, eighth controller + 111 block Compaq Next Generation Drive Array, eighth controller 0 = /dev/cciss/c7d0 First logical drive, whole disk 16 = /dev/cciss/c7d1 Second logical drive, whole disk ... @@ -1875,7 +1880,7 @@ Your cooperation is appreciated. DAC960 (see major number 48) except that the limit on partitions is 15. -112 char ISI serial card + 112 char ISI serial card 0 = /dev/ttyM0 First ISI port 1 = /dev/ttyM1 Second ISI port ... @@ -1883,7 +1888,7 @@ Your cooperation is appreciated. There is currently a device-naming conflict between these and PAM multimodems (major 78). -112 block IBM iSeries virtual disk + 112 block IBM iSeries virtual disk 0 = /dev/iseries/vda First virtual disk, whole disk 8 = /dev/iseries/vdb Second virtual disk, whole disk ... @@ -1896,17 +1901,17 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 7. -113 char ISI serial card - alternate devices + 113 char ISI serial card - alternate devices 0 = /dev/cum0 Callout device for ttyM0 1 = /dev/cum1 Callout device for ttyM1 ... -113 block IBM iSeries virtual CD-ROM + 113 block IBM iSeries virtual CD-ROM 0 = /dev/iseries/vcda First virtual CD-ROM 1 = /dev/iseries/vcdb Second virtual CD-ROM ... -114 char Picture Elements ISE board + 114 char Picture Elements ISE board 0 = /dev/ise0 First ISE board 1 = /dev/ise1 Second ISE board ... @@ -1919,24 +1924,24 @@ Your cooperation is appreciated. I/O access to the board, the /dev/isex0 nodes command nodes used to control the board. -114 block IDE BIOS powered software RAID interfaces such as the - Promise Fastrak + 114 block IDE BIOS powered software RAID interfaces such as the + Promise Fastrak - 0 = /dev/ataraid/d0 - 1 = /dev/ataraid/d0p1 - 2 = /dev/ataraid/d0p2 - ... - 16 = /dev/ataraid/d1 - 17 = /dev/ataraid/d1p1 - 18 = /dev/ataraid/d1p2 - ... - 255 = /dev/ataraid/d15p15 + 0 = /dev/ataraid/d0 + 1 = /dev/ataraid/d0p1 + 2 = /dev/ataraid/d0p2 + ... + 16 = /dev/ataraid/d1 + 17 = /dev/ataraid/d1p1 + 18 = /dev/ataraid/d1p2 + ... + 255 = /dev/ataraid/d15p15 Partitions are handled in the same way as for IDE disks (see major number 3) except that the limit on partitions is 15. -115 char TI link cable devices (115 was formerly the console driver speaker) + 115 char TI link cable devices (115 was formerly the console driver speaker) 0 = /dev/tipar0 Parallel cable on first parallel port ... 7 = /dev/tipar7 Parallel cable on seventh parallel port @@ -1949,28 +1954,28 @@ Your cooperation is appreciated. ... 47 = /dev/tiusb31 32nd USB cable -115 block NetWare (NWFS) Devices (0-255) + 115 block NetWare (NWFS) Devices (0-255) - The NWFS (NetWare) devices are used to present a - collection of NetWare Mirror Groups or NetWare - Partitions as a logical storage segment for - use in mounting NetWare volumes. A maximum of - 256 NetWare volumes can be supported in a single - machine. + The NWFS (NetWare) devices are used to present a + collection of NetWare Mirror Groups or NetWare + Partitions as a logical storage segment for + use in mounting NetWare volumes. A maximum of + 256 NetWare volumes can be supported in a single + machine. - http://cgfa.telepac.pt/ftp2/kernel.org/linux/kernel/people/jmerkey/nwfs/ + http://cgfa.telepac.pt/ftp2/kernel.org/linux/kernel/people/jmerkey/nwfs/ - 0 = /dev/nwfs/v0 First NetWare (NWFS) Logical Volume - 1 = /dev/nwfs/v1 Second NetWare (NWFS) Logical Volume - 2 = /dev/nwfs/v2 Third NetWare (NWFS) Logical Volume - ... - 255 = /dev/nwfs/v255 Last NetWare (NWFS) Logical Volume + 0 = /dev/nwfs/v0 First NetWare (NWFS) Logical Volume + 1 = /dev/nwfs/v1 Second NetWare (NWFS) Logical Volume + 2 = /dev/nwfs/v2 Third NetWare (NWFS) Logical Volume + ... + 255 = /dev/nwfs/v255 Last NetWare (NWFS) Logical Volume -116 char Advanced Linux Sound Driver (ALSA) + 116 char Advanced Linux Sound Driver (ALSA) -116 block MicroMemory battery backed RAM adapter (NVRAM) - Supports 16 boards, 15 partitions each. - Requested by neilb at cse.unsw.edu.au. + 116 block MicroMemory battery backed RAM adapter (NVRAM) + Supports 16 boards, 15 partitions each. + Requested by neilb at cse.unsw.edu.au. 0 = /dev/umem/d0 Whole of first board 1 = /dev/umem/d0p1 First partition of first board @@ -1982,7 +1987,7 @@ Your cooperation is appreciated. ... 255= /dev/umem/d15p15 15th partition of 16th board. -117 char COSA/SRP synchronous serial card + 117 char COSA/SRP synchronous serial card 0 = /dev/cosa0c0 1st board, 1st channel 1 = /dev/cosa0c1 1st board, 2nd channel ... @@ -1990,147 +1995,147 @@ Your cooperation is appreciated. 17 = /dev/cosa1c1 2nd board, 2nd channel ... -117 block Enterprise Volume Management System (EVMS) + 117 block Enterprise Volume Management System (EVMS) - The EVMS driver uses a layered, plug-in model to provide - unparalleled flexibility and extensibility in managing - storage. This allows for easy expansion or customization - of various levels of volume management. Requested by - Mark Peloquin (peloquin at us.ibm.com). + The EVMS driver uses a layered, plug-in model to provide + unparalleled flexibility and extensibility in managing + storage. This allows for easy expansion or customization + of various levels of volume management. Requested by + Mark Peloquin (peloquin at us.ibm.com). - Note: EVMS populates and manages all the devnodes in - /dev/evms. + Note: EVMS populates and manages all the devnodes in + /dev/evms. - http://sf.net/projects/evms + http://sf.net/projects/evms - 0 = /dev/evms/block_device EVMS block device - 1 = /dev/evms/legacyname1 First EVMS legacy device - 2 = /dev/evms/legacyname2 Second EVMS legacy device - ... - Both ranges can grow (down or up) until they meet. - ... - 254 = /dev/evms/EVMSname2 Second EVMS native device - 255 = /dev/evms/EVMSname1 First EVMS native device + 0 = /dev/evms/block_device EVMS block device + 1 = /dev/evms/legacyname1 First EVMS legacy device + 2 = /dev/evms/legacyname2 Second EVMS legacy device + ... + Both ranges can grow (down or up) until they meet. + ... + 254 = /dev/evms/EVMSname2 Second EVMS native device + 255 = /dev/evms/EVMSname1 First EVMS native device - Note: legacyname(s) are derived from the normal legacy - device names. For example, /dev/hda5 would become - /dev/evms/hda5. + Note: legacyname(s) are derived from the normal legacy + device names. For example, /dev/hda5 would become + /dev/evms/hda5. -118 char IBM Cryptographic Accelerator + 118 char IBM Cryptographic Accelerator 0 = /dev/ica Virtual interface to all IBM Crypto Accelerators 1 = /dev/ica0 IBMCA Device 0 2 = /dev/ica1 IBMCA Device 1 ... -119 char VMware virtual network control + 119 char VMware virtual network control 0 = /dev/vnet0 1st virtual network 1 = /dev/vnet1 2nd virtual network ... -120-127 char LOCAL/EXPERIMENTAL USE + 120-127 char LOCAL/EXPERIMENTAL USE -120-127 block LOCAL/EXPERIMENTAL USE + 120-127 block LOCAL/EXPERIMENTAL USE Allocated for local/experimental use. For devices not assigned official numbers, these ranges should be used in order to avoid conflicting with future assignments. -128-135 char Unix98 PTY masters + 128-135 char Unix98 PTY masters These devices should not have corresponding device nodes; instead they should be accessed through the /dev/ptmx cloning interface. -128 block SCSI disk devices (128-143) - 0 = /dev/sddy 129th SCSI disk whole disk - 16 = /dev/sddz 130th SCSI disk whole disk - 32 = /dev/sdea 131th SCSI disk whole disk - ... - 240 = /dev/sden 144th SCSI disk whole disk + 128 block SCSI disk devices (128-143) + 0 = /dev/sddy 129th SCSI disk whole disk + 16 = /dev/sddz 130th SCSI disk whole disk + 32 = /dev/sdea 131th SCSI disk whole disk + ... + 240 = /dev/sden 144th SCSI disk whole disk Partitions are handled in the same way as for IDE disks (see major number 3) except that the limit on partitions is 15. -129 block SCSI disk devices (144-159) - 0 = /dev/sdeo 145th SCSI disk whole disk - 16 = /dev/sdep 146th SCSI disk whole disk - 32 = /dev/sdeq 147th SCSI disk whole disk - ... - 240 = /dev/sdfd 160th SCSI disk whole disk + 129 block SCSI disk devices (144-159) + 0 = /dev/sdeo 145th SCSI disk whole disk + 16 = /dev/sdep 146th SCSI disk whole disk + 32 = /dev/sdeq 147th SCSI disk whole disk + ... + 240 = /dev/sdfd 160th SCSI disk whole disk Partitions are handled in the same way as for IDE disks (see major number 3) except that the limit on partitions is 15. -130 char (Misc devices) + 130 char (Misc devices) -130 block SCSI disk devices (160-175) - 0 = /dev/sdfe 161st SCSI disk whole disk - 16 = /dev/sdff 162nd SCSI disk whole disk - 32 = /dev/sdfg 163rd SCSI disk whole disk - ... - 240 = /dev/sdft 176th SCSI disk whole disk + 130 block SCSI disk devices (160-175) + 0 = /dev/sdfe 161st SCSI disk whole disk + 16 = /dev/sdff 162nd SCSI disk whole disk + 32 = /dev/sdfg 163rd SCSI disk whole disk + ... + 240 = /dev/sdft 176th SCSI disk whole disk Partitions are handled in the same way as for IDE disks (see major number 3) except that the limit on partitions is 15. -131 block SCSI disk devices (176-191) - 0 = /dev/sdfu 177th SCSI disk whole disk - 16 = /dev/sdfv 178th SCSI disk whole disk - 32 = /dev/sdfw 179th SCSI disk whole disk - ... - 240 = /dev/sdgj 192nd SCSI disk whole disk + 131 block SCSI disk devices (176-191) + 0 = /dev/sdfu 177th SCSI disk whole disk + 16 = /dev/sdfv 178th SCSI disk whole disk + 32 = /dev/sdfw 179th SCSI disk whole disk + ... + 240 = /dev/sdgj 192nd SCSI disk whole disk Partitions are handled in the same way as for IDE disks (see major number 3) except that the limit on partitions is 15. -132 block SCSI disk devices (192-207) - 0 = /dev/sdgk 193rd SCSI disk whole disk - 16 = /dev/sdgl 194th SCSI disk whole disk - 32 = /dev/sdgm 195th SCSI disk whole disk - ... - 240 = /dev/sdgz 208th SCSI disk whole disk + 132 block SCSI disk devices (192-207) + 0 = /dev/sdgk 193rd SCSI disk whole disk + 16 = /dev/sdgl 194th SCSI disk whole disk + 32 = /dev/sdgm 195th SCSI disk whole disk + ... + 240 = /dev/sdgz 208th SCSI disk whole disk Partitions are handled in the same way as for IDE disks (see major number 3) except that the limit on partitions is 15. -133 block SCSI disk devices (208-223) - 0 = /dev/sdha 209th SCSI disk whole disk - 16 = /dev/sdhb 210th SCSI disk whole disk - 32 = /dev/sdhc 211th SCSI disk whole disk - ... - 240 = /dev/sdhp 224th SCSI disk whole disk + 133 block SCSI disk devices (208-223) + 0 = /dev/sdha 209th SCSI disk whole disk + 16 = /dev/sdhb 210th SCSI disk whole disk + 32 = /dev/sdhc 211th SCSI disk whole disk + ... + 240 = /dev/sdhp 224th SCSI disk whole disk Partitions are handled in the same way as for IDE disks (see major number 3) except that the limit on partitions is 15. -134 block SCSI disk devices (224-239) - 0 = /dev/sdhq 225th SCSI disk whole disk - 16 = /dev/sdhr 226th SCSI disk whole disk - 32 = /dev/sdhs 227th SCSI disk whole disk - ... - 240 = /dev/sdif 240th SCSI disk whole disk + 134 block SCSI disk devices (224-239) + 0 = /dev/sdhq 225th SCSI disk whole disk + 16 = /dev/sdhr 226th SCSI disk whole disk + 32 = /dev/sdhs 227th SCSI disk whole disk + ... + 240 = /dev/sdif 240th SCSI disk whole disk Partitions are handled in the same way as for IDE disks (see major number 3) except that the limit on partitions is 15. -135 block SCSI disk devices (240-255) - 0 = /dev/sdig 241st SCSI disk whole disk - 16 = /dev/sdih 242nd SCSI disk whole disk - 32 = /dev/sdih 243rd SCSI disk whole disk - ... - 240 = /dev/sdiv 256th SCSI disk whole disk + 135 block SCSI disk devices (240-255) + 0 = /dev/sdig 241st SCSI disk whole disk + 16 = /dev/sdih 242nd SCSI disk whole disk + 32 = /dev/sdih 243rd SCSI disk whole disk + ... + 240 = /dev/sdiv 256th SCSI disk whole disk Partitions are handled in the same way as for IDE disks (see major number 3) except that the limit on partitions is 15. -136-143 char Unix98 PTY slaves + 136-143 char Unix98 PTY slaves 0 = /dev/pts/0 First Unix98 pseudo-TTY 1 = /dev/pts/1 Second Unix98 pseudo-TTY ... @@ -2142,7 +2147,7 @@ Your cooperation is appreciated. *most* distributions the appropriate options are "mode=0620,gid=".) -136 block Mylex DAC960 PCI RAID controller; ninth controller + 136 block Mylex DAC960 PCI RAID controller; ninth controller 0 = /dev/rd/c8d0 First disk, whole disk 8 = /dev/rd/c8d1 Second disk, whole disk ... @@ -2150,7 +2155,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. -137 block Mylex DAC960 PCI RAID controller; tenth controller + 137 block Mylex DAC960 PCI RAID controller; tenth controller 0 = /dev/rd/c9d0 First disk, whole disk 8 = /dev/rd/c9d1 Second disk, whole disk ... @@ -2158,7 +2163,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. -138 block Mylex DAC960 PCI RAID controller; eleventh controller + 138 block Mylex DAC960 PCI RAID controller; eleventh controller 0 = /dev/rd/c10d0 First disk, whole disk 8 = /dev/rd/c10d1 Second disk, whole disk ... @@ -2166,7 +2171,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. -139 block Mylex DAC960 PCI RAID controller; twelfth controller + 139 block Mylex DAC960 PCI RAID controller; twelfth controller 0 = /dev/rd/c11d0 First disk, whole disk 8 = /dev/rd/c11d1 Second disk, whole disk ... @@ -2174,7 +2179,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. -140 block Mylex DAC960 PCI RAID controller; thirteenth controller + 140 block Mylex DAC960 PCI RAID controller; thirteenth controller 0 = /dev/rd/c12d0 First disk, whole disk 8 = /dev/rd/c12d1 Second disk, whole disk ... @@ -2182,7 +2187,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. -141 block Mylex DAC960 PCI RAID controller; fourteenth controller + 141 block Mylex DAC960 PCI RAID controller; fourteenth controller 0 = /dev/rd/c13d0 First disk, whole disk 8 = /dev/rd/c13d1 Second disk, whole disk ... @@ -2190,7 +2195,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. -142 block Mylex DAC960 PCI RAID controller; fifteenth controller + 142 block Mylex DAC960 PCI RAID controller; fifteenth controller 0 = /dev/rd/c14d0 First disk, whole disk 8 = /dev/rd/c14d1 Second disk, whole disk ... @@ -2198,7 +2203,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. -143 block Mylex DAC960 PCI RAID controller; sixteenth controller + 143 block Mylex DAC960 PCI RAID controller; sixteenth controller 0 = /dev/rd/c15d0 First disk, whole disk 8 = /dev/rd/c15d1 Second disk, whole disk ... @@ -2206,7 +2211,7 @@ Your cooperation is appreciated. Partitions are handled as for major 48. -144 char Encapsulated PPP + 144 char Encapsulated PPP 0 = /dev/pppox0 First PPP over Ethernet ... 63 = /dev/pppox63 64th PPP over Ethernet @@ -2216,11 +2221,11 @@ Your cooperation is appreciated. The SST 5136-DN DeviceNet interface driver has been relocated to major 183 due to an unfortunate conflict. -144 block Expansion Area #1 for more non-device (e.g. NFS) mounts + 144 block Expansion Area #1 for more non-device (e.g. NFS) mounts 0 = mounted device 256 255 = mounted device 511 -145 char SAM9407-based soundcard + 145 char SAM9407-based soundcard 0 = /dev/sam0_mixer 1 = /dev/sam0_sequencer 2 = /dev/sam0_midi00 @@ -2241,66 +2246,66 @@ Your cooperation is appreciated. addons, which are sam9407 specific. OSS can be operated simultaneously, taking care of the codec. -145 block Expansion Area #2 for more non-device (e.g. NFS) mounts + 145 block Expansion Area #2 for more non-device (e.g. NFS) mounts 0 = mounted device 512 255 = mounted device 767 -146 char SYSTRAM SCRAMNet mirrored-memory network + 146 char SYSTRAM SCRAMNet mirrored-memory network 0 = /dev/scramnet0 First SCRAMNet device 1 = /dev/scramnet1 Second SCRAMNet device ... -146 block Expansion Area #3 for more non-device (e.g. NFS) mounts + 146 block Expansion Area #3 for more non-device (e.g. NFS) mounts 0 = mounted device 768 255 = mounted device 1023 -147 char Aureal Semiconductor Vortex Audio device + 147 char Aureal Semiconductor Vortex Audio device 0 = /dev/aureal0 First Aureal Vortex 1 = /dev/aureal1 Second Aureal Vortex ... -147 block Distributed Replicated Block Device (DRBD) + 147 block Distributed Replicated Block Device (DRBD) 0 = /dev/drbd0 First DRBD device 1 = /dev/drbd1 Second DRBD device ... -148 char Technology Concepts serial card + 148 char Technology Concepts serial card 0 = /dev/ttyT0 First TCL port 1 = /dev/ttyT1 Second TCL port ... -149 char Technology Concepts serial card - alternate devices + 149 char Technology Concepts serial card - alternate devices 0 = /dev/cut0 Callout device for ttyT0 1 = /dev/cut0 Callout device for ttyT1 ... -150 char Real-Time Linux FIFOs + 150 char Real-Time Linux FIFOs 0 = /dev/rtf0 First RTLinux FIFO 1 = /dev/rtf1 Second RTLinux FIFO ... -151 char DPT I2O SmartRaid V controller + 151 char DPT I2O SmartRaid V controller 0 = /dev/dpti0 First DPT I2O adapter 1 = /dev/dpti1 Second DPT I2O adapter ... -152 char EtherDrive Control Device + 152 char EtherDrive Control Device 0 = /dev/etherd/ctl Connect/Disconnect an EtherDrive 1 = /dev/etherd/err Monitor errors 2 = /dev/etherd/raw Raw AoE packet monitor -152 block EtherDrive Block Devices + 152 block EtherDrive Block Devices 0 = /dev/etherd/0 EtherDrive 0 ... 255 = /dev/etherd/255 EtherDrive 255 -153 char SPI Bus Interface (sometimes referred to as MicroWire) + 153 char SPI Bus Interface (sometimes referred to as MicroWire) 0 = /dev/spi0 First SPI device on the bus 1 = /dev/spi1 Second SPI device on the bus ... 15 = /dev/spi15 Sixteenth SPI device on the bus -153 block Enhanced Metadisk RAID (EMD) storage units + 153 block Enhanced Metadisk RAID (EMD) storage units 0 = /dev/emd/0 First unit 1 = /dev/emd/0p1 Partition 1 on First unit 2 = /dev/emd/0p2 Partition 2 on First unit @@ -2316,41 +2321,41 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 15. -154 char Specialix RIO serial card + 154 char Specialix RIO serial card 0 = /dev/ttySR0 First RIO port ... 255 = /dev/ttySR255 256th RIO port -155 char Specialix RIO serial card - alternate devices + 155 char Specialix RIO serial card - alternate devices 0 = /dev/cusr0 Callout device for ttySR0 ... 255 = /dev/cusr255 Callout device for ttySR255 -156 char Specialix RIO serial card + 156 char Specialix RIO serial card 0 = /dev/ttySR256 257th RIO port ... 255 = /dev/ttySR511 512th RIO port -157 char Specialix RIO serial card - alternate devices + 157 char Specialix RIO serial card - alternate devices 0 = /dev/cusr256 Callout device for ttySR256 ... 255 = /dev/cusr511 Callout device for ttySR511 -158 char Dialogic GammaLink fax driver + 158 char Dialogic GammaLink fax driver 0 = /dev/gfax0 GammaLink channel 0 1 = /dev/gfax1 GammaLink channel 1 ... -159 char RESERVED + 159 char RESERVED -159 block RESERVED + 159 block RESERVED -160 char General Purpose Instrument Bus (GPIB) + 160 char General Purpose Instrument Bus (GPIB) 0 = /dev/gpib0 First GPIB bus 1 = /dev/gpib1 Second GPIB bus ... -160 block Carmel 8-port SATA Disks on First Controller + 160 block Carmel 8-port SATA Disks on First Controller 0 = /dev/carmel/0 SATA disk 0 whole disk 1 = /dev/carmel/0p1 SATA disk 0 partition 1 ... @@ -2365,7 +2370,7 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 31. -161 char IrCOMM devices (IrDA serial/parallel emulation) + 161 char IrCOMM devices (IrDA serial/parallel emulation) 0 = /dev/ircomm0 First IrCOMM device 1 = /dev/ircomm1 Second IrCOMM device ... @@ -2373,7 +2378,7 @@ Your cooperation is appreciated. 17 = /dev/irlpt1 Second IrLPT device ... -161 block Carmel 8-port SATA Disks on Second Controller + 161 block Carmel 8-port SATA Disks on Second Controller 0 = /dev/carmel/8 SATA disk 8 whole disk 1 = /dev/carmel/8p1 SATA disk 8 partition 1 ... @@ -2388,17 +2393,17 @@ Your cooperation is appreciated. disks (see major number 3) except that the limit on partitions is 31. -162 char Raw block device interface + 162 char Raw block device interface 0 = /dev/rawctl Raw I/O control device 1 = /dev/raw/raw1 First raw I/O device 2 = /dev/raw/raw2 Second raw I/O device ... - max minor number of raw device is set by kernel config - MAX_RAW_DEVS or raw module parameter 'max_raw_devs' + max minor number of raw device is set by kernel config + MAX_RAW_DEVS or raw module parameter 'max_raw_devs' -163 char + 163 char -164 char Chase Research AT/PCI-Fast serial card + 164 char Chase Research AT/PCI-Fast serial card 0 = /dev/ttyCH0 AT/PCI-Fast board 0, port 0 ... 15 = /dev/ttyCH15 AT/PCI-Fast board 0, port 15 @@ -2412,67 +2417,67 @@ Your cooperation is appreciated. ... 63 = /dev/ttyCH63 AT/PCI-Fast board 3, port 15 -165 char Chase Research AT/PCI-Fast serial card - alternate devices + 165 char Chase Research AT/PCI-Fast serial card - alternate devices 0 = /dev/cuch0 Callout device for ttyCH0 ... 63 = /dev/cuch63 Callout device for ttyCH63 -166 char ACM USB modems + 166 char ACM USB modems 0 = /dev/ttyACM0 First ACM modem 1 = /dev/ttyACM1 Second ACM modem ... -167 char ACM USB modems - alternate devices + 167 char ACM USB modems - alternate devices 0 = /dev/cuacm0 Callout device for ttyACM0 1 = /dev/cuacm1 Callout device for ttyACM1 ... -168 char Eracom CSA7000 PCI encryption adaptor + 168 char Eracom CSA7000 PCI encryption adaptor 0 = /dev/ecsa0 First CSA7000 1 = /dev/ecsa1 Second CSA7000 ... -169 char Eracom CSA8000 PCI encryption adaptor + 169 char Eracom CSA8000 PCI encryption adaptor 0 = /dev/ecsa8-0 First CSA8000 1 = /dev/ecsa8-1 Second CSA8000 ... -170 char AMI MegaRAC remote access controller + 170 char AMI MegaRAC remote access controller 0 = /dev/megarac0 First MegaRAC card 1 = /dev/megarac1 Second MegaRAC card ... -171 char Reserved for IEEE 1394 (Firewire) + 171 char Reserved for IEEE 1394 (Firewire) -172 char Moxa Intellio serial card + 172 char Moxa Intellio serial card 0 = /dev/ttyMX0 First Moxa port 1 = /dev/ttyMX1 Second Moxa port ... 127 = /dev/ttyMX127 128th Moxa port 128 = /dev/moxactl Moxa control port -173 char Moxa Intellio serial card - alternate devices + 173 char Moxa Intellio serial card - alternate devices 0 = /dev/cumx0 Callout device for ttyMX0 1 = /dev/cumx1 Callout device for ttyMX1 ... 127 = /dev/cumx127 Callout device for ttyMX127 -174 char SmartIO serial card + 174 char SmartIO serial card 0 = /dev/ttySI0 First SmartIO port 1 = /dev/ttySI1 Second SmartIO port ... -175 char SmartIO serial card - alternate devices + 175 char SmartIO serial card - alternate devices 0 = /dev/cusi0 Callout device for ttySI0 1 = /dev/cusi1 Callout device for ttySI1 ... -176 char nCipher nFast PCI crypto accelerator + 176 char nCipher nFast PCI crypto accelerator 0 = /dev/nfastpci0 First nFast PCI device 1 = /dev/nfastpci1 First nFast PCI device ... -177 char TI PCILynx memory spaces + 177 char TI PCILynx memory spaces 0 = /dev/pcilynx/aux0 AUX space of first PCILynx card ... 15 = /dev/pcilynx/aux15 AUX space of 16th PCILynx card @@ -2483,12 +2488,12 @@ Your cooperation is appreciated. ... 47 = /dev/pcilynx/ram15 RAM space of 16th PCILynx card -178 char Giganet cLAN1xxx virtual interface adapter + 178 char Giganet cLAN1xxx virtual interface adapter 0 = /dev/clanvi0 First cLAN adapter 1 = /dev/clanvi1 Second cLAN adapter ... -179 block MMC block devices + 179 block MMC block devices 0 = /dev/mmcblk0 First SD/MMC card 1 = /dev/mmcblk0p1 First partition on first MMC card 8 = /dev/mmcblk1 Second SD/MMC card @@ -2500,12 +2505,12 @@ Your cooperation is appreciated. bump the offset between each card to be the configured value instead of the default 8. -179 char CCube DVXChip-based PCI products + 179 char CCube DVXChip-based PCI products 0 = /dev/dvxirq0 First DVX device 1 = /dev/dvxirq1 Second DVX device ... -180 char USB devices + 180 char USB devices 0 = /dev/usb/lp0 First USB printer ... 15 = /dev/usb/lp15 16th USB printer @@ -2539,23 +2544,23 @@ Your cooperation is appreciated. ... 209 = /dev/usb/yurex16 16th USB Yurex device -180 block USB block devices + 180 block USB block devices 0 = /dev/uba First USB block device 8 = /dev/ubb Second USB block device 16 = /dev/ubc Third USB block device - ... + ... -181 char Conrad Electronic parallel port radio clocks + 181 char Conrad Electronic parallel port radio clocks 0 = /dev/pcfclock0 First Conrad radio clock 1 = /dev/pcfclock1 Second Conrad radio clock ... -182 char Picture Elements THR2 binarizer + 182 char Picture Elements THR2 binarizer 0 = /dev/pethr0 First THR2 board 1 = /dev/pethr1 Second THR2 board ... -183 char SST 5136-DN DeviceNet interface + 183 char SST 5136-DN DeviceNet interface 0 = /dev/ss5136dn0 First DeviceNet interface 1 = /dev/ss5136dn1 Second DeviceNet interface ... @@ -2563,12 +2568,12 @@ Your cooperation is appreciated. This device used to be assigned to major number 144. It had to be moved due to an unfortunate conflict. -184 char Picture Elements' video simulator/sender + 184 char Picture Elements' video simulator/sender 0 = /dev/pevss0 First sender board 1 = /dev/pevss1 Second sender board ... -185 char InterMezzo high availability file system + 185 char InterMezzo high availability file system 0 = /dev/intermezzo0 First cache manager 1 = /dev/intermezzo1 Second cache manager ... @@ -2576,48 +2581,48 @@ Your cooperation is appreciated. See http://web.archive.org/web/20080115195241/ http://inter-mezzo.org/index.html -186 char Object-based storage control device + 186 char Object-based storage control device 0 = /dev/obd0 First obd control device 1 = /dev/obd1 Second obd control device ... See ftp://ftp.lustre.org/pub/obd for code and information. -187 char DESkey hardware encryption device + 187 char DESkey hardware encryption device 0 = /dev/deskey0 First DES key 1 = /dev/deskey1 Second DES key ... -188 char USB serial converters + 188 char USB serial converters 0 = /dev/ttyUSB0 First USB serial converter 1 = /dev/ttyUSB1 Second USB serial converter ... -189 char USB serial converters - alternate devices + 189 char USB serial converters - alternate devices 0 = /dev/cuusb0 Callout device for ttyUSB0 1 = /dev/cuusb1 Callout device for ttyUSB1 ... -190 char Kansas City tracker/tuner card + 190 char Kansas City tracker/tuner card 0 = /dev/kctt0 First KCT/T card 1 = /dev/kctt1 Second KCT/T card ... -191 char Reserved for PCMCIA + 191 char Reserved for PCMCIA -192 char Kernel profiling interface + 192 char Kernel profiling interface 0 = /dev/profile Profiling control device 1 = /dev/profile0 Profiling device for CPU 0 2 = /dev/profile1 Profiling device for CPU 1 ... -193 char Kernel event-tracing interface + 193 char Kernel event-tracing interface 0 = /dev/trace Tracing control device 1 = /dev/trace0 Tracing device for CPU 0 2 = /dev/trace1 Tracing device for CPU 1 ... -194 char linVideoStreams (LINVS) + 194 char linVideoStreams (LINVS) 0 = /dev/mvideo/status0 Video compression status 1 = /dev/mvideo/stream0 Video stream 2 = /dev/mvideo/frame0 Single compressed frame @@ -2633,13 +2638,13 @@ Your cooperation is appreciated. 240 = /dev/mvideo/status15 16th device ... -195 char Nvidia graphics devices + 195 char Nvidia graphics devices 0 = /dev/nvidia0 First Nvidia card 1 = /dev/nvidia1 Second Nvidia card ... 255 = /dev/nvidiactl Nvidia card control device -196 char Tormenta T1 card + 196 char Tormenta T1 card 0 = /dev/tor/0 Master control channel for all cards 1 = /dev/tor/1 First DS0 2 = /dev/tor/2 Second DS0 @@ -2649,24 +2654,24 @@ Your cooperation is appreciated. 50 = /dev/tor/50 Second pseudo-channel ... -197 char OpenTNF tracing facility + 197 char OpenTNF tracing facility 0 = /dev/tnf/t0 Trace 0 data extraction 1 = /dev/tnf/t1 Trace 1 data extraction ... 128 = /dev/tnf/status Tracing facility status 130 = /dev/tnf/trace Tracing device -198 char Total Impact TPMP2 quad coprocessor PCI card + 198 char Total Impact TPMP2 quad coprocessor PCI card 0 = /dev/tpmp2/0 First card 1 = /dev/tpmp2/1 Second card ... -199 char Veritas volume manager (VxVM) volumes + 199 char Veritas volume manager (VxVM) volumes 0 = /dev/vx/rdsk/*/* First volume 1 = /dev/vx/rdsk/*/* Second volume ... -199 block Veritas volume manager (VxVM) volumes + 199 block Veritas volume manager (VxVM) volumes 0 = /dev/vx/dsk/*/* First volume 1 = /dev/vx/dsk/*/* Second volume ... @@ -2674,19 +2679,19 @@ Your cooperation is appreciated. The namespace in these directories is maintained by the user space VxVM software. -200 char Veritas VxVM configuration interface - 0 = /dev/vx/config Configuration access node - 1 = /dev/vx/trace Volume i/o trace access node - 2 = /dev/vx/iod Volume i/o daemon access node - 3 = /dev/vx/info Volume information access node - 4 = /dev/vx/task Volume tasks access node - 5 = /dev/vx/taskmon Volume tasks monitor daemon + 200 char Veritas VxVM configuration interface + 0 = /dev/vx/config Configuration access node + 1 = /dev/vx/trace Volume i/o trace access node + 2 = /dev/vx/iod Volume i/o daemon access node + 3 = /dev/vx/info Volume information access node + 4 = /dev/vx/task Volume tasks access node + 5 = /dev/vx/taskmon Volume tasks monitor daemon -201 char Veritas VxVM dynamic multipathing driver + 201 char Veritas VxVM dynamic multipathing driver 0 = /dev/vx/rdmp/* First multipath device 1 = /dev/vx/rdmp/* Second multipath device ... -201 block Veritas VxVM dynamic multipathing driver + 201 block Veritas VxVM dynamic multipathing driver 0 = /dev/vx/dmp/* First multipath device 1 = /dev/vx/dmp/* Second multipath device ... @@ -2694,28 +2699,28 @@ Your cooperation is appreciated. The namespace in these directories is maintained by the user space VxVM software. -202 char CPU model-specific registers + 202 char CPU model-specific registers 0 = /dev/cpu/0/msr MSRs on CPU 0 1 = /dev/cpu/1/msr MSRs on CPU 1 ... -202 block Xen Virtual Block Device + 202 block Xen Virtual Block Device 0 = /dev/xvda First Xen VBD whole disk 16 = /dev/xvdb Second Xen VBD whole disk 32 = /dev/xvdc Third Xen VBD whole disk ... 240 = /dev/xvdp Sixteenth Xen VBD whole disk - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. -203 char CPU CPUID information + 203 char CPU CPUID information 0 = /dev/cpu/0/cpuid CPUID on CPU 0 1 = /dev/cpu/1/cpuid CPUID on CPU 1 ... -204 char Low-density serial ports + 204 char Low-density serial ports 0 = /dev/ttyLU0 LinkUp Systems L72xx UART - port 0 1 = /dev/ttyLU1 LinkUp Systems L72xx UART - port 1 2 = /dev/ttyLU2 LinkUp Systems L72xx UART - port 2 @@ -2787,7 +2792,7 @@ Your cooperation is appreciated. 211 = /dev/ttyMAX2 MAX3100 serial port 2 212 = /dev/ttyMAX3 MAX3100 serial port 3 -205 char Low-density serial ports (alternate device) + 205 char Low-density serial ports (alternate device) 0 = /dev/culu0 Callout device for ttyLU0 1 = /dev/culu1 Callout device for ttyLU1 2 = /dev/culu2 Callout device for ttyLU2 @@ -2823,7 +2828,7 @@ Your cooperation is appreciated. 82 = /dev/cuvr0 Callout device for ttyVR0 83 = /dev/cuvr1 Callout device for ttyVR1 -206 char OnStream SC-x0 tape devices + 206 char OnStream SC-x0 tape devices 0 = /dev/osst0 First OnStream SCSI tape, mode 0 1 = /dev/osst1 Second OnStream SCSI tape, mode 0 ... @@ -2857,7 +2862,7 @@ Your cooperation is appreciated. driver as well. The ADR-x0 drives are QIC-157 compliant and don't need osst. -207 char Compaq ProLiant health feature indicate + 207 char Compaq ProLiant health feature indicate 0 = /dev/cpqhealth/cpqw Redirector interface 1 = /dev/cpqhealth/crom EISA CROM 2 = /dev/cpqhealth/cdt Data Table @@ -2871,17 +2876,17 @@ Your cooperation is appreciated. 10 = /dev/cpqhealth/cram CMOS interface 11 = /dev/cpqhealth/cpci PCI IRQ interface -208 char User space serial ports + 208 char User space serial ports 0 = /dev/ttyU0 First user space serial port 1 = /dev/ttyU1 Second user space serial port ... -209 char User space serial ports (alternate devices) + 209 char User space serial ports (alternate devices) 0 = /dev/cuu0 Callout device for ttyU0 1 = /dev/cuu1 Callout device for ttyU1 ... -210 char SBE, Inc. sync/async serial card + 210 char SBE, Inc. sync/async serial card 0 = /dev/sbei/wxcfg0 Configuration device for board 0 1 = /dev/sbei/dld0 Download device for board 0 2 = /dev/sbei/wan00 WAN device, port 0, board 0 @@ -2906,12 +2911,12 @@ Your cooperation is appreciated. Yes, each board is really spaced 10 (decimal) apart. -211 char Addinum CPCI1500 digital I/O card + 211 char Addinum CPCI1500 digital I/O card 0 = /dev/addinum/cpci1500/0 First CPCI1500 card 1 = /dev/addinum/cpci1500/1 Second CPCI1500 card ... -212 char LinuxTV.org DVB driver subsystem + 212 char LinuxTV.org DVB driver subsystem 0 = /dev/dvb/adapter0/video0 first video decoder of first card 1 = /dev/dvb/adapter0/audio0 first audio decoder of first card 2 = /dev/dvb/adapter0/sec0 (obsolete/unused) @@ -2929,34 +2934,34 @@ Your cooperation is appreciated. ... 196 = /dev/dvb/adapter3/video0 first video decoder of fourth card -216 char Bluetooth RFCOMM TTY devices + 216 char Bluetooth RFCOMM TTY devices 0 = /dev/rfcomm0 First Bluetooth RFCOMM TTY device 1 = /dev/rfcomm1 Second Bluetooth RFCOMM TTY device ... -217 char Bluetooth RFCOMM TTY devices (alternate devices) + 217 char Bluetooth RFCOMM TTY devices (alternate devices) 0 = /dev/curf0 Callout device for rfcomm0 1 = /dev/curf1 Callout device for rfcomm1 ... -218 char The Logical Company bus Unibus/Qbus adapters + 218 char The Logical Company bus Unibus/Qbus adapters 0 = /dev/logicalco/bci/0 First bus adapter 1 = /dev/logicalco/bci/1 First bus adapter ... -219 char The Logical Company DCI-1300 digital I/O card + 219 char The Logical Company DCI-1300 digital I/O card 0 = /dev/logicalco/dci1300/0 First DCI-1300 card 1 = /dev/logicalco/dci1300/1 Second DCI-1300 card ... -220 char Myricom Myrinet "GM" board + 220 char Myricom Myrinet "GM" board 0 = /dev/myricom/gm0 First Myrinet GM board 1 = /dev/myricom/gmp0 First board "root access" 2 = /dev/myricom/gm1 Second Myrinet GM board 3 = /dev/myricom/gmp1 Second board "root access" ... -221 char VME bus + 221 char VME bus 0 = /dev/bus/vme/m0 First master image 1 = /dev/bus/vme/m1 Second master image 2 = /dev/bus/vme/m2 Third master image @@ -2971,38 +2976,38 @@ Your cooperation is appreciated. same interface. For interface documentation see http://www.vmelinux.org/. -224 char A2232 serial card + 224 char A2232 serial card 0 = /dev/ttyY0 First A2232 port 1 = /dev/ttyY1 Second A2232 port ... -225 char A2232 serial card (alternate devices) + 225 char A2232 serial card (alternate devices) 0 = /dev/cuy0 Callout device for ttyY0 1 = /dev/cuy1 Callout device for ttyY1 ... -226 char Direct Rendering Infrastructure (DRI) + 226 char Direct Rendering Infrastructure (DRI) 0 = /dev/dri/card0 First graphics card 1 = /dev/dri/card1 Second graphics card ... -227 char IBM 3270 terminal Unix tty access + 227 char IBM 3270 terminal Unix tty access 1 = /dev/3270/tty1 First 3270 terminal 2 = /dev/3270/tty2 Seconds 3270 terminal ... -228 char IBM 3270 terminal block-mode access + 228 char IBM 3270 terminal block-mode access 0 = /dev/3270/tub Controlling interface 1 = /dev/3270/tub1 First 3270 terminal 2 = /dev/3270/tub2 Second 3270 terminal ... -229 char IBM iSeries/pSeries virtual console + 229 char IBM iSeries/pSeries virtual console 0 = /dev/hvc0 First console port 1 = /dev/hvc1 Second console port ... -230 char IBM iSeries virtual tape + 230 char IBM iSeries virtual tape 0 = /dev/iseries/vt0 First virtual tape, mode 0 1 = /dev/iseries/vt1 Second virtual tape, mode 0 ... @@ -3033,7 +3038,7 @@ Your cooperation is appreciated. ioctl()'s can be used to rewind the tape regardless of the device used to access it. -231 char InfiniBand + 231 char InfiniBand 0 = /dev/infiniband/umad0 1 = /dev/infiniband/umad1 ... @@ -3047,7 +3052,7 @@ Your cooperation is appreciated. ... 159 = /dev/infiniband/uverbs31 31st InfiniBand verbs device -232 char Biometric Devices + 232 char Biometric Devices 0 = /dev/biometric/sensor0/fingerprint first fingerprint sensor on first device 1 = /dev/biometric/sensor0/iris first iris sensor on first device 2 = /dev/biometric/sensor0/retina first retina sensor on first device @@ -3060,7 +3065,7 @@ Your cooperation is appreciated. 20 = /dev/biometric/sensor2/fingerprint first fingerprint sensor on third device ... -233 char PathScale InfiniPath interconnect + 233 char PathScale InfiniPath interconnect 0 = /dev/ipath Primary device for programs (any unit) 1 = /dev/ipath0 Access specifically to unit 0 2 = /dev/ipath1 Access specifically to unit 1 @@ -3069,18 +3074,18 @@ Your cooperation is appreciated. 129 = /dev/ipath_sma Device used by Subnet Management Agent 130 = /dev/ipath_diag Device used by diagnostics programs -234-254 char RESERVED FOR DYNAMIC ASSIGNMENT + 234-254 char RESERVED FOR DYNAMIC ASSIGNMENT Character devices that request a dynamic allocation of major number will take numbers starting from 254 and downward. -240-254 block LOCAL/EXPERIMENTAL USE + 240-254 block LOCAL/EXPERIMENTAL USE Allocated for local/experimental use. For devices not assigned official numbers, these ranges should be used in order to avoid conflicting with future assignments. -255 char RESERVED + 255 char RESERVED -255 block RESERVED + 255 block RESERVED This major is reserved to assist the expansion to a larger number space. No device nodes with this major @@ -3088,25 +3093,25 @@ Your cooperation is appreciated. (This is probably not true anymore, but I'll leave it for now /Torben) ----LARGE MAJORS!!!!!--- + ---LARGE MAJORS!!!!!--- -256 char Equinox SST multi-port serial boards + 256 char Equinox SST multi-port serial boards 0 = /dev/ttyEQ0 First serial port on first Equinox SST board 127 = /dev/ttyEQ127 Last serial port on first Equinox SST board 128 = /dev/ttyEQ128 First serial port on second Equinox SST board ... 1027 = /dev/ttyEQ1027 Last serial port on eighth Equinox SST board -256 block Resident Flash Disk Flash Translation Layer + 256 block Resident Flash Disk Flash Translation Layer 0 = /dev/rfda First RFD FTL layer 16 = /dev/rfdb Second RFD FTL layer ... 240 = /dev/rfdp 16th RFD FTL layer -257 char Phoenix Technologies Cryptographic Services Driver + 257 char Phoenix Technologies Cryptographic Services Driver 0 = /dev/ptlsec Crypto Services Driver -257 block SSFDC Flash Translation Layer filesystem + 257 block SSFDC Flash Translation Layer filesystem 0 = /dev/ssfdca First SSFDC layer 8 = /dev/ssfdcb Second SSFDC layer 16 = /dev/ssfdcc Third SSFDC layer @@ -3116,26 +3121,28 @@ Your cooperation is appreciated. 48 = /dev/ssfdcg 7th SSFDC layer 56 = /dev/ssfdch 8th SSFDC layer -258 block ROM/Flash read-only translation layer + 258 block ROM/Flash read-only translation layer 0 = /dev/blockrom0 First ROM card's translation layer interface 1 = /dev/blockrom1 Second ROM card's translation layer interface ... -259 block Block Extended Major + 259 block Block Extended Major Used dynamically to hold additional partition minor numbers and allow large numbers of partitions per device -259 char FPGA configuration interfaces + 259 char FPGA configuration interfaces 0 = /dev/icap0 First Xilinx internal configuration 1 = /dev/icap1 Second Xilinx internal configuration -260 char OSD (Object-based-device) SCSI Device + 260 char OSD (Object-based-device) SCSI Device 0 = /dev/osd0 First OSD Device 1 = /dev/osd1 Second OSD Device ... 255 = /dev/osd255 256th OSD Device - **** ADDITIONAL /dev DIRECTORY ENTRIES + +Additional ``/dev/`` directory entries +-------------------------------------- This section details additional entries that should or may exist in the /dev directory. It is preferred that symbolic links use the same @@ -3143,24 +3150,29 @@ form (absolute or relative) as is indicated here. Links are classified as "hard" or "symbolic" depending on the preferred type of link; if possible, the indicated type of link should be used. - - Compulsory links +Compulsory links +++++++++++++++++ These links should exist on all systems: +=============== =============== =============== =============================== /dev/fd /proc/self/fd symbolic File descriptors /dev/stdin fd/0 symbolic stdin file descriptor /dev/stdout fd/1 symbolic stdout file descriptor /dev/stderr fd/2 symbolic stderr file descriptor /dev/nfsd socksys symbolic Required by iBCS-2 /dev/X0R null symbolic Required by iBCS-2 +=============== =============== =============== =============================== -Note: /dev/X0R is --. +Note: ``/dev/X0R`` is --. - Recommended links +Recommended links ++++++++++++++++++ It is recommended that these links exist on all systems: + +=============== =============== =============== =============================== /dev/core /proc/kcore symbolic Backward compatibility /dev/ramdisk ram0 symbolic Backward compatibility /dev/ftape qft0 symbolic Backward compatibility @@ -3168,14 +3180,17 @@ It is recommended that these links exist on all systems: /dev/radio radio0 symbolic Backward compatibility /dev/i2o* /dev/i2o/* symbolic Backward compatibility /dev/scd? sr? hard Alternate SCSI CD-ROM name +=============== =============== =============== =============================== - Locally defined links +Locally defined links ++++++++++++++++++++++ The following links may be established locally to conform to the configuration of the system. This is merely a tabulation of existing practice, and does not constitute a recommendation. However, if they exist, they should have the following uses. +=============== =============== =============== =============================== /dev/mouse mouse port symbolic Current mouse device /dev/tape tape device symbolic Current tape device /dev/cdrom CD-ROM device symbolic Current CD-ROM device @@ -3184,38 +3199,46 @@ exist, they should have the following uses. /dev/modem modem port symbolic Current dialout device /dev/root root device symbolic Current root filesystem /dev/swap swap device symbolic Current swap device +=============== =============== =============== =============================== -/dev/modem should not be used for a modem which supports dialin as +``/dev/modem`` should not be used for a modem which supports dialin as well as dialout, as it tends to cause lock file problems. If it -exists, /dev/modem should point to the appropriate primary TTY device +exists, ``/dev/modem`` should point to the appropriate primary TTY device (the use of the alternate callout devices is deprecated). -For SCSI devices, /dev/tape and /dev/cdrom should point to the -``cooked'' devices (/dev/st* and /dev/sr*, respectively), whereas -/dev/cdwriter and /dev/scanner should point to the appropriate generic +For SCSI devices, ``/dev/tape`` and ``/dev/cdrom`` should point to the +*cooked* devices (``/dev/st*`` and ``/dev/sr*``, respectively), whereas +``/dev/cdwriter`` and /dev/scanner should point to the appropriate generic SCSI devices (/dev/sg*). -/dev/mouse may point to a primary serial TTY device, a hardware mouse -device, or a socket for a mouse driver program (e.g. /dev/gpmdata). +``/dev/mouse`` may point to a primary serial TTY device, a hardware mouse +device, or a socket for a mouse driver program (e.g. ``/dev/gpmdata``). - Sockets and pipes +Sockets and pipes ++++++++++++++++++ Non-transient sockets and named pipes may exist in /dev. Common entries are: +=============== =============== =============================================== /dev/printer socket lpd local socket /dev/log socket syslog local socket /dev/gpmdata socket gpm mouse multiplexer +=============== =============== =============================================== - Mount points +Mount points +++++++++++++ The following names are reserved for mounting special filesystems under /dev. These special filesystems provide kernel interfaces that cannot be provided with standard device nodes. +=============== =============== =============================================== /dev/pts devpts PTY slave filesystem /dev/shm tmpfs POSIX shared memory maintenance access +=============== =============== =============================================== - **** TERMINAL DEVICES +Terminal devices +---------------- Terminal, or TTY devices are a special class of character devices. A terminal device is any device that could act as a controlling terminal @@ -3232,42 +3255,44 @@ conventions include several historical warts; some of these are Linux-specific, some were inherited from other systems, and some reflect Linux outgrowing a borrowed convention. -A hash mark (#) in a device name is used here to indicate a decimal +A hash mark (``#``) in a device name is used here to indicate a decimal number without leading zeroes. - Virtual consoles and the console device +Virtual consoles and the console device ++++++++++++++++++++++++++++++++++++++++ Virtual consoles are full-screen terminal displays on the system video -monitor. Virtual consoles are named /dev/tty#, with numbering -starting at /dev/tty1; /dev/tty0 is the current virtual console. -/dev/tty0 is the device that should be used to access the system video +monitor. Virtual consoles are named ``/dev/tty#``, with numbering +starting at ``/dev/tty1``; ``/dev/tty0`` is the current virtual console. +``/dev/tty0`` is the device that should be used to access the system video card on those architectures for which the frame buffer devices -(/dev/fb*) are not applicable. Do not use /dev/console +(``/dev/fb*``) are not applicable. Do not use ``/dev/console`` for this purpose. -The console device, /dev/console, is the device to which system +The console device, ``/dev/console``, is the device to which system messages should be sent, and on which logins should be permitted in -single-user mode. Starting with Linux 2.1.71, /dev/console is managed +single-user mode. Starting with Linux 2.1.71, ``/dev/console`` is managed by the kernel; for previous versions it should be a symbolic link to -either /dev/tty0, a specific virtual console such as /dev/tty1, or to -a serial port primary (tty*, not cu*) device, depending on the +either ``/dev/tty0``, a specific virtual console such as ``/dev/tty1``, or to +a serial port primary (``tty*``, not ``cu*``) device, depending on the configuration of the system. - Serial ports +Serial ports +++++++++++++ Serial ports are RS-232 serial ports and any device which simulates one, either in hardware (such as internal modems) or in software (such as the ISDN driver.) Under Linux, each serial ports has two device names, the primary or callin device and the alternate or callout one. Each kind of device is indicated by a different letter. For any -letter X, the names of the devices are /dev/ttyX# and /dev/cux#, -respectively; for historical reasons, /dev/ttyS# and /dev/ttyC# -correspond to /dev/cua# and /dev/cub#. In the future, it should be +letter X, the names of the devices are ``/dev/ttyX#`` and ``/dev/cux#``, +respectively; for historical reasons, ``/dev/ttyS#`` and ``/dev/ttyC#`` +correspond to ``/dev/cua#`` and ``/dev/cub#``. In the future, it should be expected that multiple letters will be used; all letters will be upper -case for the "tty" device (e.g. /dev/ttyDP#) and lower case for the -"cu" device (e.g. /dev/cudp#). +case for the "tty" device (e.g. ``/dev/ttyDP#``) and lower case for the +"cu" device (e.g. ``/dev/cudp#``). -The names /dev/ttyQ# and /dev/cuq# are reserved for local use. +The names ``/dev/ttyQ#`` and ``/dev/cuq#`` are reserved for local use. The alternate devices provide for kernel-based exclusion and somewhat different defaults than the primary devices. Their main purpose is to @@ -3276,7 +3301,7 @@ support for serial ports. Their use is deprecated, and they may be removed from a future version of Linux. Arbitration of serial ports is provided by the use of lock files with -the names /var/lock/LCK..ttyX#. The contents of the lock file should +the names ``/var/lock/LCK..ttyX#``. The contents of the lock file should be the PID of the locking process as an ASCII number. It is common practice to install links such as /dev/modem @@ -3287,9 +3312,9 @@ that a lock file be installed with the corresponding alternate device. In order to avoid deadlocks, it is recommended that the locks are acquired in the following order, and released in the reverse: - 1. The symbolic link name, if any (/var/lock/LCK..modem) - 2. The "tty" name (/var/lock/LCK..ttyS2) - 3. The alternate device name (/var/lock/LCK..cua2) + 1. The symbolic link name, if any (``/var/lock/LCK..modem``) + 2. The "tty" name (``/var/lock/LCK..ttyS2``) + 3. The alternate device name (``/var/lock/LCK..cua2``) In the case of nested symbolic links, the lock files should be installed in the order the symlinks are resolved. @@ -3300,13 +3325,14 @@ to create lock files for the corresponding alternate device names should take into account the possibility of being used on a non-serial port TTY, for which no alternate device would exist. - Pseudoterminals (PTYs) +Pseudoterminals (PTYs) +++++++++++++++++++++++ Pseudoterminals, or PTYs, are used to create login sessions or provide other capabilities requiring a TTY line discipline (including SLIP or PPP capability) to arbitrary data-generation processes. Each PTY has -a master side, named /dev/pty[p-za-e][0-9a-f], and a slave side, named -/dev/tty[p-za-e][0-9a-f]. The kernel arbitrates the use of PTYs by +a master side, named ``/dev/pty[p-za-e][0-9a-f]``, and a slave side, named +``/dev/tty[p-za-e][0-9a-f]``. The kernel arbitrates the use of PTYs by allowing each master side to be opened only once. Once the master side has been opened, the corresponding slave device @@ -3316,9 +3342,9 @@ of a bidirectional pipe with TTY capabilities. Recent versions of the Linux kernels and GNU libc contain support for the System V/Unix98 naming scheme for PTYs, which assigns a common -device, /dev/ptmx, to all the masters (opening it will automatically -give you a previously unassigned PTY) and a subdirectory, /dev/pts, -for the slaves; the slaves are named with decimal integers (/dev/pts/# +device, ``/dev/ptmx``, to all the masters (opening it will automatically +give you a previously unassigned PTY) and a subdirectory, ``/dev/pts``, +for the slaves; the slaves are named with decimal integers (``/dev/pts/#`` in our notation). This removes the problem of exhausting the namespace and enables the kernel to automatically create the device nodes for the slaves on demand using the "devpts" filesystem. -- cgit v1.2.3 From 7d4e3517bdc2972e0dd35be34e07832841fc036a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 16:32:00 -0300 Subject: Documentation/dynamic-debug-howto.txt: convert it to ReST markup - use a quote blocks where needed; - fix the chapter/section/subsection markups; - use ``foo`` for monotonic; - use .. note:: for the line-range note; - cleanup whitespaces; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/dynamic-debug-howto.txt | 297 ++++++++++++++++++---------------- 1 file changed, 155 insertions(+), 142 deletions(-) diff --git a/Documentation/dynamic-debug-howto.txt b/Documentation/dynamic-debug-howto.txt index 9417871b8758..88adcfdf5b2b 100644 --- a/Documentation/dynamic-debug-howto.txt +++ b/Documentation/dynamic-debug-howto.txt @@ -1,3 +1,6 @@ +Dynamic debug ++++++++++++++ + Introduction ============ @@ -6,16 +9,16 @@ This document describes how to use the dynamic debug (dyndbg) feature. Dynamic debug is designed to allow you to dynamically enable/disable kernel code to obtain additional kernel information. Currently, if -CONFIG_DYNAMIC_DEBUG is set, then all pr_debug()/dev_dbg() and -print_hex_dump_debug()/print_hex_dump_bytes() calls can be dynamically +``CONFIG_DYNAMIC_DEBUG`` is set, then all ``pr_debug()``/``dev_dbg()`` and +``print_hex_dump_debug()``/``print_hex_dump_bytes()`` calls can be dynamically enabled per-callsite. -If CONFIG_DYNAMIC_DEBUG is not set, print_hex_dump_debug() is just -shortcut for print_hex_dump(KERN_DEBUG). +If ``CONFIG_DYNAMIC_DEBUG`` is not set, ``print_hex_dump_debug()`` is just +shortcut for ``print_hex_dump(KERN_DEBUG)``. -For print_hex_dump_debug()/print_hex_dump_bytes(), format string is -its 'prefix_str' argument, if it is constant string; or "hexdump" -in case 'prefix_str' is build dynamically. +For ``print_hex_dump_debug()``/``print_hex_dump_bytes()``, format string is +its ``prefix_str`` argument, if it is constant string; or ``hexdump`` +in case ``prefix_str`` is build dynamically. Dynamic debug has even more useful features: @@ -28,96 +31,95 @@ Dynamic debug has even more useful features: - module name - format string - * Provides a debugfs control file: /dynamic_debug/control + * Provides a debugfs control file: ``/dynamic_debug/control`` which can be read to display the complete list of known debug statements, to help guide you Controlling dynamic debug Behaviour =================================== -The behaviour of pr_debug()/dev_dbg()s are controlled via writing to a +The behaviour of ``pr_debug()``/``dev_dbg()`` are controlled via writing to a control file in the 'debugfs' filesystem. Thus, you must first mount the debugfs filesystem, in order to make use of this feature. Subsequently, we refer to the control file as: -/dynamic_debug/control. For example, if you want to enable -printing from source file 'svcsock.c', line 1603 you simply do: +``/dynamic_debug/control``. For example, if you want to enable +printing from source file ``svcsock.c``, line 1603 you simply do:: -nullarbor:~ # echo 'file svcsock.c line 1603 +p' > + nullarbor:~ # echo 'file svcsock.c line 1603 +p' > /dynamic_debug/control -If you make a mistake with the syntax, the write will fail thus: +If you make a mistake with the syntax, the write will fail thus:: -nullarbor:~ # echo 'file svcsock.c wtf 1 +p' > + nullarbor:~ # echo 'file svcsock.c wtf 1 +p' > /dynamic_debug/control --bash: echo: write error: Invalid argument + -bash: echo: write error: Invalid argument Viewing Dynamic Debug Behaviour -=========================== +=============================== You can view the currently configured behaviour of all the debug -statements via: +statements via:: -nullarbor:~ # cat /dynamic_debug/control -# filename:lineno [module]function flags format -/usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:323 [svcxprt_rdma]svc_rdma_cleanup =_ "SVCRDMA Module Removed, deregister RPC RDMA transport\012" -/usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:341 [svcxprt_rdma]svc_rdma_init =_ "\011max_inline : %d\012" -/usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:340 [svcxprt_rdma]svc_rdma_init =_ "\011sq_depth : %d\012" -/usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:338 [svcxprt_rdma]svc_rdma_init =_ "\011max_requests : %d\012" -... + nullarbor:~ # cat /dynamic_debug/control + # filename:lineno [module]function flags format + /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:323 [svcxprt_rdma]svc_rdma_cleanup =_ "SVCRDMA Module Removed, deregister RPC RDMA transport\012" + /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:341 [svcxprt_rdma]svc_rdma_init =_ "\011max_inline : %d\012" + /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:340 [svcxprt_rdma]svc_rdma_init =_ "\011sq_depth : %d\012" + /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:338 [svcxprt_rdma]svc_rdma_init =_ "\011max_requests : %d\012" + ... You can also apply standard Unix text manipulation filters to this -data, e.g. +data, e.g.:: -nullarbor:~ # grep -i rdma /dynamic_debug/control | wc -l -62 + nullarbor:~ # grep -i rdma /dynamic_debug/control | wc -l + 62 -nullarbor:~ # grep -i tcp /dynamic_debug/control | wc -l -42 + nullarbor:~ # grep -i tcp /dynamic_debug/control | wc -l + 42 The third column shows the currently enabled flags for each debug statement callsite (see below for definitions of the flags). The -default value, with no flags enabled, is "=_". So you can view all -the debug statement callsites with any non-default flags: - -nullarbor:~ # awk '$3 != "=_"' /dynamic_debug/control -# filename:lineno [module]function flags format -/usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svcsock.c:1603 [sunrpc]svc_send p "svc_process: st_sendto returned %d\012" +default value, with no flags enabled, is ``=_``. So you can view all +the debug statement callsites with any non-default flags:: + nullarbor:~ # awk '$3 != "=_"' /dynamic_debug/control + # filename:lineno [module]function flags format + /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svcsock.c:1603 [sunrpc]svc_send p "svc_process: st_sendto returned %d\012" Command Language Reference ========================== At the lexical level, a command comprises a sequence of words separated -by spaces or tabs. So these are all equivalent: +by spaces or tabs. So these are all equivalent:: -nullarbor:~ # echo -c 'file svcsock.c line 1603 +p' > + nullarbor:~ # echo -c 'file svcsock.c line 1603 +p' > /dynamic_debug/control -nullarbor:~ # echo -c ' file svcsock.c line 1603 +p ' > + nullarbor:~ # echo -c ' file svcsock.c line 1603 +p ' > /dynamic_debug/control -nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' > + nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' > /dynamic_debug/control Command submissions are bounded by a write() system call. -Multiple commands can be written together, separated by ';' or '\n'. +Multiple commands can be written together, separated by ``;`` or ``\n``:: ~# echo "func pnpacpi_get_resources +p; func pnp_assign_mem +p" \ > /dynamic_debug/control -If your query set is big, you can batch them too: +If your query set is big, you can batch them too:: ~# cat query-batch-file > /dynamic_debug/control -A another way is to use wildcard. The match rule support '*' (matches -zero or more characters) and '?' (matches exactly one character).For -example, you can match all usb drivers: +A another way is to use wildcard. The match rule support ``*`` (matches +zero or more characters) and ``?`` (matches exactly one character).For +example, you can match all usb drivers:: ~# echo "file drivers/usb/* +p" > /dynamic_debug/control At the syntactical level, a command comprises a sequence of match -specifications, followed by a flags change specification. +specifications, followed by a flags change specification:: -command ::= match-spec* flags-spec + command ::= match-spec* flags-spec The match-spec's are used to choose a subset of the known pr_debug() callsites to which to apply the flags-spec. Think of them as a query @@ -126,88 +128,92 @@ match-specs will select all debug statement callsites. A match specification comprises a keyword, which controls the attribute of the callsite to be compared, and a value to compare -against. Possible keywords are: +against. Possible keywords are::: + + match-spec ::= 'func' string | + 'file' string | + 'module' string | + 'format' string | + 'line' line-range -match-spec ::= 'func' string | - 'file' string | - 'module' string | - 'format' string | - 'line' line-range + line-range ::= lineno | + '-'lineno | + lineno'-' | + lineno'-'lineno -line-range ::= lineno | - '-'lineno | - lineno'-' | - lineno'-'lineno -// Note: line-range cannot contain space, e.g. -// "1-30" is valid range but "1 - 30" is not. + lineno ::= unsigned-int + +.. note:: + + ``line-range`` cannot contain space, e.g. + "1-30" is valid range but "1 - 30" is not. -lineno ::= unsigned-int The meanings of each keyword are: func The given string is compared against the function name - of each callsite. Example: + of each callsite. Example:: - func svc_tcp_accept + func svc_tcp_accept file The given string is compared against either the full pathname, the src-root relative pathname, or the basename of the source file of - each callsite. Examples: + each callsite. Examples:: - file svcsock.c - file kernel/freezer.c - file /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svcsock.c + file svcsock.c + file kernel/freezer.c + file /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svcsock.c module The given string is compared against the module name of each callsite. The module name is the string as - seen in "lsmod", i.e. without the directory or the .ko - suffix and with '-' changed to '_'. Examples: + seen in ``lsmod``, i.e. without the directory or the ``.ko`` + suffix and with ``-`` changed to ``_``. Examples:: - module sunrpc - module nfsd + module sunrpc + module nfsd format The given string is searched for in the dynamic debug format string. Note that the string does not need to match the entire format, only some part. Whitespace and other special characters can be escaped using C octal character - escape \ooo notation, e.g. the space character is \040. + escape ``\ooo`` notation, e.g. the space character is ``\040``. Alternatively, the string can be enclosed in double quote - characters (") or single quote characters ('). - Examples: + characters (``"``) or single quote characters (``'``). + Examples:: - format svcrdma: // many of the NFS/RDMA server pr_debugs - format readahead // some pr_debugs in the readahead cache - format nfsd:\040SETATTR // one way to match a format with whitespace - format "nfsd: SETATTR" // a neater way to match a format with whitespace - format 'nfsd: SETATTR' // yet another way to match a format with whitespace + format svcrdma: // many of the NFS/RDMA server pr_debugs + format readahead // some pr_debugs in the readahead cache + format nfsd:\040SETATTR // one way to match a format with whitespace + format "nfsd: SETATTR" // a neater way to match a format with whitespace + format 'nfsd: SETATTR' // yet another way to match a format with whitespace line The given line number or range of line numbers is compared - against the line number of each pr_debug() callsite. A single + against the line number of each ``pr_debug()`` callsite. A single line number matches the callsite line number exactly. A range of line numbers matches any callsite between the first and last line number inclusive. An empty first number means the first line in the file, an empty line number means the - last number in the file. Examples: + last number in the file. Examples:: - line 1603 // exactly line 1603 - line 1600-1605 // the six lines from line 1600 to line 1605 - line -1605 // the 1605 lines from line 1 to line 1605 - line 1600- // all lines from line 1600 to the end of the file + line 1603 // exactly line 1603 + line 1600-1605 // the six lines from line 1600 to line 1605 + line -1605 // the 1605 lines from line 1 to line 1605 + line 1600- // all lines from line 1600 to the end of the file The flags specification comprises a change operation followed by one or more flag characters. The change operation is one -of the characters: +of the characters:: - remove the given flags + add the given flags = set the flags to the given flags -The flags are: +The flags are:: p enables the pr_debug() callsite. f Include the function name in the printed message @@ -216,14 +222,14 @@ The flags are: t Include thread ID in messages not generated from interrupt context _ No flags are set. (Or'd with others on input) -For print_hex_dump_debug() and print_hex_dump_bytes(), only 'p' flag +For ``print_hex_dump_debug()`` and ``print_hex_dump_bytes()``, only ``p`` flag have meaning, other flags ignored. -For display, the flags are preceded by '=' +For display, the flags are preceded by ``=`` (mnemonic: what the flags are currently equal to). -Note the regexp ^[-+=][flmpt_]+$ matches a flags specification. -To clear all flags at once, use "=_" or "-flmpt". +Note the regexp ``^[-+=][flmpt_]+$`` matches a flags specification. +To clear all flags at once, use ``=_`` or ``-flmpt``. Debug messages during Boot Process @@ -231,110 +237,117 @@ Debug messages during Boot Process To activate debug messages for core code and built-in modules during the boot process, even before userspace and debugfs exists, use -dyndbg="QUERY", module.dyndbg="QUERY", or ddebug_query="QUERY" -(ddebug_query is obsoleted by dyndbg, and deprecated). QUERY follows +``dyndbg="QUERY"``, ``module.dyndbg="QUERY"``, or ``ddebug_query="QUERY"`` +(``ddebug_query`` is obsoleted by ``dyndbg``, and deprecated). QUERY follows the syntax described above, but must not exceed 1023 characters. Your bootloader may impose lower limits. -These dyndbg params are processed just after the ddebug tables are +These ``dyndbg`` params are processed just after the ddebug tables are processed, as part of the arch_initcall. Thus you can enable debug messages in all code run after this arch_initcall via this boot parameter. -On an x86 system for example ACPI enablement is a subsys_initcall and +On an x86 system for example ACPI enablement is a subsys_initcall and:: + dyndbg="file ec.c +p" + will show early Embedded Controller transactions during ACPI setup if your machine (typically a laptop) has an Embedded Controller. PCI (or other devices) initialization also is a hot candidate for using this boot parameter for debugging purposes. -If foo module is not built-in, foo.dyndbg will still be processed at +If ``foo`` module is not built-in, ``foo.dyndbg`` will still be processed at boot time, without effect, but will be reprocessed when module is -loaded later. dyndbg_query= and bare dyndbg= are only processed at +loaded later. ``dyndbg_query=`` and bare ``dyndbg=`` are only processed at boot. Debug Messages at Module Initialization Time ============================================ -When "modprobe foo" is called, modprobe scans /proc/cmdline for -foo.params, strips "foo.", and passes them to the kernel along with -params given in modprobe args or /etc/modprob.d/*.conf files, +When ``modprobe foo`` is called, modprobe scans ``/proc/cmdline`` for +``foo.params``, strips ``foo.``, and passes them to the kernel along with +params given in modprobe args or ``/etc/modprob.d/*.conf`` files, in the following order: -1. # parameters given via /etc/modprobe.d/*.conf - options foo dyndbg=+pt - options foo dyndbg # defaults to +p +1. parameters given via ``/etc/modprobe.d/*.conf``:: + + options foo dyndbg=+pt + options foo dyndbg # defaults to +p + +2. ``foo.dyndbg`` as given in boot args, ``foo.`` is stripped and passed:: -2. # foo.dyndbg as given in boot args, "foo." is stripped and passed - foo.dyndbg=" func bar +p; func buz +mp" + foo.dyndbg=" func bar +p; func buz +mp" -3. # args to modprobe - modprobe foo dyndbg==pmf # override previous settings +3. args to modprobe:: -These dyndbg queries are applied in order, with last having final say. -This allows boot args to override or modify those from /etc/modprobe.d + modprobe foo dyndbg==pmf # override previous settings + +These ``dyndbg`` queries are applied in order, with last having final say. +This allows boot args to override or modify those from ``/etc/modprobe.d`` (sensible, since 1 is system wide, 2 is kernel or boot specific), and modprobe args to override both. -In the foo.dyndbg="QUERY" form, the query must exclude "module foo". -"foo" is extracted from the param-name, and applied to each query in -"QUERY", and only 1 match-spec of each type is allowed. +In the ``foo.dyndbg="QUERY"`` form, the query must exclude ``module foo``. +``foo`` is extracted from the param-name, and applied to each query in +``QUERY``, and only 1 match-spec of each type is allowed. -The dyndbg option is a "fake" module parameter, which means: +The ``dyndbg`` option is a "fake" module parameter, which means: - modules do not need to define it explicitly - every module gets it tacitly, whether they use pr_debug or not -- it doesn't appear in /sys/module/$module/parameters/ - To see it, grep the control file, or inspect /proc/cmdline. +- it doesn't appear in ``/sys/module/$module/parameters/`` + To see it, grep the control file, or inspect ``/proc/cmdline.`` -For CONFIG_DYNAMIC_DEBUG kernels, any settings given at boot-time (or -enabled by -DDEBUG flag during compilation) can be disabled later via -the sysfs interface if the debug messages are no longer needed: +For ``CONFIG_DYNAMIC_DEBUG`` kernels, any settings given at boot-time (or +enabled by ``-DDEBUG`` flag during compilation) can be disabled later via +the sysfs interface if the debug messages are no longer needed:: echo "module module_name -p" > /dynamic_debug/control Examples ======== -// enable the message at line 1603 of file svcsock.c -nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' > +:: + + // enable the message at line 1603 of file svcsock.c + nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' > /dynamic_debug/control -// enable all the messages in file svcsock.c -nullarbor:~ # echo -n 'file svcsock.c +p' > + // enable all the messages in file svcsock.c + nullarbor:~ # echo -n 'file svcsock.c +p' > /dynamic_debug/control -// enable all the messages in the NFS server module -nullarbor:~ # echo -n 'module nfsd +p' > + // enable all the messages in the NFS server module + nullarbor:~ # echo -n 'module nfsd +p' > /dynamic_debug/control -// enable all 12 messages in the function svc_process() -nullarbor:~ # echo -n 'func svc_process +p' > + // enable all 12 messages in the function svc_process() + nullarbor:~ # echo -n 'func svc_process +p' > /dynamic_debug/control -// disable all 12 messages in the function svc_process() -nullarbor:~ # echo -n 'func svc_process -p' > + // disable all 12 messages in the function svc_process() + nullarbor:~ # echo -n 'func svc_process -p' > /dynamic_debug/control -// enable messages for NFS calls READ, READLINK, READDIR and READDIR+. -nullarbor:~ # echo -n 'format "nfsd: READ" +p' > + // enable messages for NFS calls READ, READLINK, READDIR and READDIR+. + nullarbor:~ # echo -n 'format "nfsd: READ" +p' > /dynamic_debug/control -// enable messages in files of which the paths include string "usb" -nullarbor:~ # echo -n '*usb* +p' > /dynamic_debug/control + // enable messages in files of which the paths include string "usb" + nullarbor:~ # echo -n '*usb* +p' > /dynamic_debug/control -// enable all messages -nullarbor:~ # echo -n '+p' > /dynamic_debug/control + // enable all messages + nullarbor:~ # echo -n '+p' > /dynamic_debug/control -// add module, function to all enabled messages -nullarbor:~ # echo -n '+mf' > /dynamic_debug/control + // add module, function to all enabled messages + nullarbor:~ # echo -n '+mf' > /dynamic_debug/control -// boot-args example, with newlines and comments for readability -Kernel command line: ... - // see whats going on in dyndbg=value processing - dynamic_debug.verbose=1 - // enable pr_debugs in 2 builtins, #cmt is stripped - dyndbg="module params +p #cmt ; module sys +p" - // enable pr_debugs in 2 functions in a module loaded later - pc87360.dyndbg="func pc87360_init_device +p; func pc87360_find +p" + // boot-args example, with newlines and comments for readability + Kernel command line: ... + // see whats going on in dyndbg=value processing + dynamic_debug.verbose=1 + // enable pr_debugs in 2 builtins, #cmt is stripped + dyndbg="module params +p #cmt ; module sys +p" + // enable pr_debugs in 2 functions in a module loaded later + pc87360.dyndbg="func pc87360_init_device +p; func pc87360_find +p" -- cgit v1.2.3 From 5d0ad553783f408f9c79d23e06fdfe9c4bc6c0a9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 16:52:26 -0300 Subject: Documentation/initrd.txt: convert to ReST markup - use a quote blocks where needed; - fix the chapter/section/subsection markups; - use ``foo`` for monotonic; - use .. note:: for /sbin/init file permissions; - adjust whitespaces and blank lines; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/initrd.txt | 199 +++++++++++++++++++++++++---------------------- 1 file changed, 108 insertions(+), 91 deletions(-) diff --git a/Documentation/initrd.txt b/Documentation/initrd.txt index 4e1839ccb555..a03dabaaf3a3 100644 --- a/Documentation/initrd.txt +++ b/Documentation/initrd.txt @@ -2,7 +2,7 @@ Using the initial RAM disk (initrd) =================================== Written 1996,2000 by Werner Almesberger and - Hans Lermen +Hans Lermen initrd provides the capability to load a RAM disk by the boot loader. @@ -16,7 +16,7 @@ where the kernel comes up with a minimum set of compiled-in drivers, and where additional modules are loaded from initrd. This document gives a brief overview of the use of initrd. A more detailed -discussion of the boot process can be found in [1]. +discussion of the boot process can be found in [#f1]_. Operation @@ -27,10 +27,10 @@ When using initrd, the system typically boots as follows: 1) the boot loader loads the kernel and the initial RAM disk 2) the kernel converts initrd into a "normal" RAM disk and frees the memory used by initrd - 3) if the root device is not /dev/ram0, the old (deprecated) + 3) if the root device is not ``/dev/ram0``, the old (deprecated) change_root procedure is followed. see the "Obsolete root change mechanism" section below. - 4) root device is mounted. if it is /dev/ram0, the initrd image is + 4) root device is mounted. if it is ``/dev/ram0``, the initrd image is then mounted as root 5) /sbin/init is executed (this can be any valid executable, including shell scripts; it is run with uid 0 and can do basically everything @@ -38,7 +38,7 @@ When using initrd, the system typically boots as follows: 6) init mounts the "real" root file system 7) init places the root file system at the root directory using the pivot_root system call - 8) init execs the /sbin/init on the new root filesystem, performing + 8) init execs the ``/sbin/init`` on the new root filesystem, performing the usual boot sequence 9) the initrd file system is removed @@ -51,7 +51,7 @@ be accessible. Boot command-line options ------------------------- -initrd adds the following new options: +initrd adds the following new options:: initrd= (e.g. LOADLIN) @@ -83,36 +83,36 @@ Recent kernels have support for populating a ramdisk from a compressed cpio archive. On such systems, the creation of a ramdisk image doesn't need to involve special block devices or loopbacks; you merely create a directory on disk with the desired initrd content, cd to that directory, and run (as an -example): +example):: -find . | cpio --quiet -H newc -o | gzip -9 -n > /boot/imagefile.img + find . | cpio --quiet -H newc -o | gzip -9 -n > /boot/imagefile.img -Examining the contents of an existing image file is just as simple: +Examining the contents of an existing image file is just as simple:: -mkdir /tmp/imagefile -cd /tmp/imagefile -gzip -cd /boot/imagefile.img | cpio -imd --quiet + mkdir /tmp/imagefile + cd /tmp/imagefile + gzip -cd /boot/imagefile.img | cpio -imd --quiet Installation ------------ First, a directory for the initrd file system has to be created on the -"normal" root file system, e.g. +"normal" root file system, e.g.:: -# mkdir /initrd + # mkdir /initrd -The name is not relevant. More details can be found on the pivot_root(2) -man page. +The name is not relevant. More details can be found on the +:manpage:`pivot_root(2)` man page. If the root file system is created during the boot procedure (i.e. if you're building an install floppy), the root file system creation -procedure should create the /initrd directory. +procedure should create the ``/initrd`` directory. If initrd will not be mounted in some cases, its content is still -accessible if the following device has been created: +accessible if the following device has been created:: -# mknod /dev/initrd b 1 250 -# chmod 400 /dev/initrd + # mknod /dev/initrd b 1 250 + # chmod 400 /dev/initrd Second, the kernel has to be compiled with RAM disk support and with support for the initial RAM disk enabled. Also, at least all components @@ -131,60 +131,76 @@ kernels, at least three types of devices are suitable for that: We'll describe the loopback device method: 1) make sure loopback block devices are configured into the kernel - 2) create an empty file system of the appropriate size, e.g. - # dd if=/dev/zero of=initrd bs=300k count=1 - # mke2fs -F -m0 initrd + 2) create an empty file system of the appropriate size, e.g.:: + + # dd if=/dev/zero of=initrd bs=300k count=1 + # mke2fs -F -m0 initrd + (if space is critical, you may want to use the Minix FS instead of Ext2) - 3) mount the file system, e.g. - # mount -t ext2 -o loop initrd /mnt - 4) create the console device: + 3) mount the file system, e.g.:: + + # mount -t ext2 -o loop initrd /mnt + + 4) create the console device:: + # mkdir /mnt/dev # mknod /mnt/dev/console c 5 1 + 5) copy all the files that are needed to properly use the initrd - environment. Don't forget the most important file, /sbin/init - Note that /sbin/init's permissions must include "x" (execute). + environment. Don't forget the most important file, ``/sbin/init`` + + .. note:: ``/sbin/init`` permissions must include "x" (execute). + 6) correct operation the initrd environment can frequently be tested - even without rebooting with the command - # chroot /mnt /sbin/init + even without rebooting with the command:: + + # chroot /mnt /sbin/init + This is of course limited to initrds that do not interfere with the general system state (e.g. by reconfiguring network interfaces, overwriting mounted devices, trying to start already running demons, etc. Note however that it is usually possible to use pivot_root in such a chroot'ed initrd environment.) - 7) unmount the file system - # umount /mnt + 7) unmount the file system:: + + # umount /mnt + 8) the initrd is now in the file "initrd". Optionally, it can now be - compressed - # gzip -9 initrd + compressed:: + + # gzip -9 initrd For experimenting with initrd, you may want to take a rescue floppy and -only add a symbolic link from /sbin/init to /bin/sh. Alternatively, you -can try the experimental newlib environment [2] to create a small +only add a symbolic link from ``/sbin/init`` to ``/bin/sh``. Alternatively, you +can try the experimental newlib environment [#f2]_ to create a small initrd. Finally, you have to boot the kernel and load initrd. Almost all Linux boot loaders support initrd. Since the boot process is still compatible with an older mechanism, the following boot command line parameters -have to be given: +have to be given:: root=/dev/ram0 rw (rw is only necessary if writing to the initrd file system.) -With LOADLIN, you simply execute +With LOADLIN, you simply execute:: LOADLIN initrd= -e.g. LOADLIN C:\LINUX\BZIMAGE initrd=C:\LINUX\INITRD.GZ root=/dev/ram0 rw -With LILO, you add the option INITRD= to either the global section -or to the section of the respective kernel in /etc/lilo.conf, and pass -the options using APPEND, e.g. +e.g.:: + + LOADLIN C:\LINUX\BZIMAGE initrd=C:\LINUX\INITRD.GZ root=/dev/ram0 rw + +With LILO, you add the option ``INITRD=`` to either the global section +or to the section of the respective kernel in ``/etc/lilo.conf``, and pass +the options using APPEND, e.g.:: image = /bzImage initrd = /boot/initrd.gz append = "root=/dev/ram0 rw" -and run /sbin/lilo +and run ``/sbin/lilo`` For other boot loaders, please refer to the respective documentation. @@ -204,33 +220,33 @@ The procedure involves the following steps: - unmounting the initrd file system and de-allocating the RAM disk Mounting the new root file system is easy: it just needs to be mounted on -a directory under the current root. Example: +a directory under the current root. Example:: -# mkdir /new-root -# mount -o ro /dev/hda1 /new-root + # mkdir /new-root + # mount -o ro /dev/hda1 /new-root The root change is accomplished with the pivot_root system call, which -is also available via the pivot_root utility (see pivot_root(8) man -page; pivot_root is distributed with util-linux version 2.10h or higher -[3]). pivot_root moves the current root to a directory under the new +is also available via the ``pivot_root`` utility (see :manpage:`pivot_root(8)` +man page; ``pivot_root`` is distributed with util-linux version 2.10h or higher +[#f3]_). ``pivot_root`` moves the current root to a directory under the new root, and puts the new root at its place. The directory for the old root -must exist before calling pivot_root. Example: +must exist before calling ``pivot_root``. Example:: -# cd /new-root -# mkdir initrd -# pivot_root . initrd + # cd /new-root + # mkdir initrd + # pivot_root . initrd Now, the init process may still access the old root via its executable, shared libraries, standard input/output/error, and its current root directory. All these references are dropped by the -following command: +following command:: -# exec chroot . what-follows dev/console 2>&1 + # exec chroot . what-follows dev/console 2>&1 -Where what-follows is a program under the new root, e.g. /sbin/init +Where what-follows is a program under the new root, e.g. ``/sbin/init`` If the new root file system will be used with udev and has no valid -/dev directory, udev must be initialized before invoking chroot in order -to provide /dev/console. +``/dev`` directory, udev must be initialized before invoking chroot in order +to provide ``/dev/console``. Note: implementation details of pivot_root may change with time. In order to ensure compatibility, the following points should be observed: @@ -244,13 +260,13 @@ to ensure compatibility, the following points should be observed: - use relative paths for dev/console in the exec command Now, the initrd can be unmounted and the memory allocated by the RAM -disk can be freed: +disk can be freed:: -# umount /initrd -# blockdev --flushbufs /dev/ram0 + # umount /initrd + # blockdev --flushbufs /dev/ram0 It is also possible to use initrd with an NFS-mounted root, see the -pivot_root(8) man page for details. +:manpage:`pivot_root(8)` man page for details. Usage scenarios @@ -263,21 +279,21 @@ as follows: 1) system boots from floppy or other media with a minimal kernel (e.g. support for RAM disks, initrd, a.out, and the Ext2 FS) and loads initrd - 2) /sbin/init determines what is needed to (1) mount the "real" root FS + 2) ``/sbin/init`` determines what is needed to (1) mount the "real" root FS (i.e. device type, device drivers, file system) and (2) the distribution media (e.g. CD-ROM, network, tape, ...). This can be done by asking the user, by auto-probing, or by using a hybrid approach. - 3) /sbin/init loads the necessary kernel modules - 4) /sbin/init creates and populates the root file system (this doesn't + 3) ``/sbin/init`` loads the necessary kernel modules + 4) ``/sbin/init`` creates and populates the root file system (this doesn't have to be a very usable system yet) - 5) /sbin/init invokes pivot_root to change the root file system and + 5) ``/sbin/init`` invokes ``pivot_root`` to change the root file system and execs - via chroot - a program that continues the installation 6) the boot loader is installed 7) the boot loader is configured to load an initrd with the set of - modules that was used to bring up the system (e.g. /initrd can be + modules that was used to bring up the system (e.g. ``/initrd`` can be modified, then unmounted, and finally, the image is written from - /dev/ram0 or /dev/rd/0 to a file) + ``/dev/ram0`` or ``/dev/rd/0`` to a file) 8) now the system is bootable and additional installation tasks can be performed @@ -290,7 +306,7 @@ different hardware configurations in a single administrative domain. In such cases, it is desirable to generate only a small set of kernels (ideally only one) and to keep the system-specific part of configuration information as small as possible. In this case, a common initrd could be -generated with all the necessary modules. Then, only /sbin/init or a file +generated with all the necessary modules. Then, only ``/sbin/init`` or a file read by it would have to be different. A third scenario is more convenient recovery disks, because information @@ -301,9 +317,9 @@ auto-detection). Last not least, CD-ROM distributors may use it for better installation from CD, e.g. by using a boot floppy and bootstrapping a bigger RAM disk -via initrd from CD; or by booting via a loader like LOADLIN or directly +via initrd from CD; or by booting via a loader like ``LOADLIN`` or directly from the CD-ROM, and loading the RAM disk from CD without need of -floppies. +floppies. Obsolete root change mechanism @@ -316,51 +332,52 @@ continued availability. It works by mounting the "real" root device (i.e. the one set with rdev in the kernel image or with root=... at the boot command line) as the root file system when linuxrc exits. The initrd file system is then -unmounted, or, if it is still busy, moved to a directory /initrd, if +unmounted, or, if it is still busy, moved to a directory ``/initrd``, if such a directory exists on the new root file system. In order to use this mechanism, you do not have to specify the boot command options root, init, or rw. (If specified, they will affect the real root file system, not the initrd environment.) - + If /proc is mounted, the "real" root device can be changed from within linuxrc by writing the number of the new root FS device to the special -file /proc/sys/kernel/real-root-dev, e.g. +file /proc/sys/kernel/real-root-dev, e.g.:: # echo 0x301 >/proc/sys/kernel/real-root-dev Note that the mechanism is incompatible with NFS and similar file systems. -This old, deprecated mechanism is commonly called "change_root", while -the new, supported mechanism is called "pivot_root". +This old, deprecated mechanism is commonly called ``change_root``, while +the new, supported mechanism is called ``pivot_root``. Mixed change_root and pivot_root mechanism ------------------------------------------ -In case you did not want to use root=/dev/ram0 to trigger the pivot_root -mechanism, you may create both /linuxrc and /sbin/init in your initrd image. +In case you did not want to use ``root=/dev/ram0`` to trigger the pivot_root +mechanism, you may create both ``/linuxrc`` and ``/sbin/init`` in your initrd +image. -/linuxrc would contain only the following: +``/linuxrc`` would contain only the following:: -#! /bin/sh -mount -n -t proc proc /proc -echo 0x0100 >/proc/sys/kernel/real-root-dev -umount -n /proc + #! /bin/sh + mount -n -t proc proc /proc + echo 0x0100 >/proc/sys/kernel/real-root-dev + umount -n /proc Once linuxrc exited, the kernel would mount again your initrd as root, -this time executing /sbin/init. Again, it would be the duty of this init -to build the right environment (maybe using the root= device passed on -the cmdline) before the final execution of the real /sbin/init. +this time executing ``/sbin/init``. Again, it would be the duty of this init +to build the right environment (maybe using the ``root= device`` passed on +the cmdline) before the final execution of the real ``/sbin/init``. Resources --------- -[1] Almesberger, Werner; "Booting Linux: The History and the Future" +.. [#f1] Almesberger, Werner; "Booting Linux: The History and the Future" http://www.almesberger.net/cv/papers/ols2k-9.ps.gz -[2] newlib package (experimental), with initrd example - http://sources.redhat.com/newlib/ -[3] util-linux: Miscellaneous utilities for Linux - http://www.kernel.org/pub/linux/utils/util-linux/ +.. [#f2] newlib package (experimental), with initrd example + https://www.sourceware.org/newlib/ +.. [#f3] util-linux: Miscellaneous utilities for Linux + https://www.kernel.org/pub/linux/utils/util-linux/ -- cgit v1.2.3 From 8887addef55f1298b967bcf67285f4a43c9db85c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 16:59:42 -0300 Subject: Documentation/init.txt: convert to ReST markup - use a quote blocks where needed; - use ``foo`` for monotonic; - adjust whitespaces and blank lines; - fix the second list (that starts with 0, instead of A) - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/init.txt | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/Documentation/init.txt b/Documentation/init.txt index 535ad5e82b98..e89d97f31eaf 100644 --- a/Documentation/init.txt +++ b/Documentation/init.txt @@ -5,6 +5,7 @@ OK, so you've got this pretty unintuitive message (currently located in init/main.c) and are wondering what the H*** went wrong. Some high-level reasons for failure (listed roughly in order of execution) to load the init binary are: + A) Unable to mount root FS B) init binary doesn't exist on rootfs C) broken console device @@ -12,37 +13,39 @@ D) binary exists but dependencies not available E) binary cannot be loaded Detailed explanations: -0) Set "debug" kernel parameter (in bootloader config file or CONFIG_CMDLINE) + +A) Set "debug" kernel parameter (in bootloader config file or CONFIG_CMDLINE) to get more detailed kernel messages. -A) make sure you have the correct root FS type - (and root= kernel parameter points to the correct partition), +B) make sure you have the correct root FS type + (and ``root=`` kernel parameter points to the correct partition), required drivers such as storage hardware (such as SCSI or USB!) and filesystem (ext3, jffs2 etc.) are builtin (alternatively as modules, to be pre-loaded by an initrd) -C) Possibly a conflict in console= setup --> initial console unavailable. +C) Possibly a conflict in ``console= setup`` --> initial console unavailable. E.g. some serial consoles are unreliable due to serial IRQ issues (e.g. missing interrupt-based configuration). - Try using a different console= device or e.g. netconsole= . + Try using a different ``console= device`` or e.g. ``netconsole=``. D) e.g. required library dependencies of the init binary such as - /lib/ld-linux.so.2 missing or broken. Use readelf -d |grep NEEDED - to find out which libraries are required. + ``/lib/ld-linux.so.2`` missing or broken. Use + ``readelf -d |grep NEEDED`` to find out which libraries are required. E) make sure the binary's architecture matches your hardware. E.g. i386 vs. x86_64 mismatch, or trying to load x86 on ARM hardware. In case you tried loading a non-binary file here (shell script?), you should make sure that the script specifies an interpreter in its shebang - header line (#!/...) that is fully working (including its library + header line (``#!/...``) that is fully working (including its library dependencies). And before tackling scripts, better first test a simple - non-script binary such as /bin/sh and confirm its successful execution. - To find out more, add code to init/main.c to display kernel_execve()s + non-script binary such as ``/bin/sh`` and confirm its successful execution. + To find out more, add code ``to init/main.c`` to display kernel_execve()s return values. Please extend this explanation whenever you find new failure causes (after all loading the init binary is a CRITICAL and hard transition step which needs to be made as painless as possible), then submit patch to LKML. Further TODOs: -- Implement the various run_init_process() invocations via a struct array - which can then store the kernel_execve() result value and on failure - log it all by iterating over _all_ results (very important usability fix). + +- Implement the various ``run_init_process()`` invocations via a struct array + which can then store the ``kernel_execve()`` result value and on failure + log it all by iterating over **all** results (very important usability fix). - try to make the implementation itself more helpful in general, e.g. by providing additional error messages at affected places. -- cgit v1.2.3 From 9a11e15381b3503e51c4bbab4f9dad7c001f7c94 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 17:18:36 -0300 Subject: Documentation/magic-number.txt: convert it to ReST markup - add a title for the document; - convert the table; - use quote block for the changelog; - use monotonic fonts for file names; - adjust whitespaces and blank lines; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/magic-number.txt | 216 +++++++++++++++++++++-------------------- 1 file changed, 111 insertions(+), 105 deletions(-) diff --git a/Documentation/magic-number.txt b/Documentation/magic-number.txt index 28befed9f610..c74199f60c6c 100644 --- a/Documentation/magic-number.txt +++ b/Documentation/magic-number.txt @@ -1,9 +1,12 @@ +Linux magic numbers +=================== + This file is a registry of magic numbers which are in use. When you add a magic number to a structure, you should also add it to this file, since it is best if the magic numbers used by various structures are unique. -It is a *very* good idea to protect kernel data structures with magic +It is a **very** good idea to protect kernel data structures with magic numbers. This allows you to check at run time whether (a) a structure has been clobbered, or (b) you've passed the wrong structure to a routine. This last is especially useful --- particularly when you are @@ -12,12 +15,12 @@ for example, does this frequently to pass driver-specific and line discipline-specific structures back and forth. The way to use magic numbers is to declare then at the beginning of -the structure, like so: +the structure, like so:: -struct tty_ldisc { - int magic; - ... -}; + struct tty_ldisc { + int magic; + ... + }; Please follow this discipline when you are adding future enhancements to the kernel! It has saved me countless hours of debugging, @@ -25,134 +28,137 @@ especially in the screwy cases where an array has been overrun and structures following the array have been overwritten. Using this discipline, these cases get detected quickly and safely. +Changelog:: + Theodore Ts'o 31 Mar 94 -The magic table is current to Linux 2.1.55. + The magic table is current to Linux 2.1.55. Michael Chastain 22 Sep 1997 -Now it should be up to date with Linux 2.1.112. Because -we are in feature freeze time it is very unlikely that -something will change before 2.2.x. The entries are -sorted by number field. + Now it should be up to date with Linux 2.1.112. Because + we are in feature freeze time it is very unlikely that + something will change before 2.2.x. The entries are + sorted by number field. Krzysztof G. Baranowski 29 Jul 1998 -Updated the magic table to Linux 2.5.45. Right over the feature freeze, -but it is possible that some new magic numbers will sneak into the -kernel before 2.6.x yet. + Updated the magic table to Linux 2.5.45. Right over the feature freeze, + but it is possible that some new magic numbers will sneak into the + kernel before 2.6.x yet. Petr Baudis 03 Nov 2002 -Updated the magic table to Linux 2.5.74. + Updated the magic table to Linux 2.5.74. Fabian Frederick 09 Jul 2003 -Magic Name Number Structure File -=========================================================================== -PG_MAGIC 'P' pg_{read,write}_hdr include/linux/pg.h -CMAGIC 0x0111 user include/linux/a.out.h -MKISS_DRIVER_MAGIC 0x04bf mkiss_channel drivers/net/mkiss.h -HDLC_MAGIC 0x239e n_hdlc drivers/char/n_hdlc.c -APM_BIOS_MAGIC 0x4101 apm_user arch/x86/kernel/apm_32.c -CYCLADES_MAGIC 0x4359 cyclades_port include/linux/cyclades.h -DB_MAGIC 0x4442 fc_info drivers/net/iph5526_novram.c -DL_MAGIC 0x444d fc_info drivers/net/iph5526_novram.c -FASYNC_MAGIC 0x4601 fasync_struct include/linux/fs.h -FF_MAGIC 0x4646 fc_info drivers/net/iph5526_novram.c -ISICOM_MAGIC 0x4d54 isi_port include/linux/isicom.h -PTY_MAGIC 0x5001 drivers/char/pty.c -PPP_MAGIC 0x5002 ppp include/linux/if_pppvar.h -SERIAL_MAGIC 0x5301 async_struct include/linux/serial.h -SSTATE_MAGIC 0x5302 serial_state include/linux/serial.h -SLIP_MAGIC 0x5302 slip drivers/net/slip.h -STRIP_MAGIC 0x5303 strip drivers/net/strip.c -X25_ASY_MAGIC 0x5303 x25_asy drivers/net/x25_asy.h -SIXPACK_MAGIC 0x5304 sixpack drivers/net/hamradio/6pack.h -AX25_MAGIC 0x5316 ax_disp drivers/net/mkiss.h -TTY_MAGIC 0x5401 tty_struct include/linux/tty.h -MGSL_MAGIC 0x5401 mgsl_info drivers/char/synclink.c -TTY_DRIVER_MAGIC 0x5402 tty_driver include/linux/tty_driver.h -MGSLPC_MAGIC 0x5402 mgslpc_info drivers/char/pcmcia/synclink_cs.c -TTY_LDISC_MAGIC 0x5403 tty_ldisc include/linux/tty_ldisc.h -USB_SERIAL_MAGIC 0x6702 usb_serial drivers/usb/serial/usb-serial.h -FULL_DUPLEX_MAGIC 0x6969 drivers/net/ethernet/dec/tulip/de2104x.c -USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth drivers/usb/class/bluetty.c -RFCOMM_TTY_MAGIC 0x6d02 net/bluetooth/rfcomm/tty.c -USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port drivers/usb/serial/usb-serial.h -CG_MAGIC 0x00090255 ufs_cylinder_group include/linux/ufs_fs.h -RPORT_MAGIC 0x00525001 r_port drivers/char/rocket_int.h -LSEMAGIC 0x05091998 lse drivers/fc4/fc.c -GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str drivers/scsi/gdth_ioctl.h -RIEBL_MAGIC 0x09051990 drivers/net/atarilance.c -NBD_REQUEST_MAGIC 0x12560953 nbd_request include/linux/nbd.h -RED_MAGIC2 0x170fc2a5 (any) mm/slab.c -BAYCOM_MAGIC 0x19730510 baycom_state drivers/net/baycom_epp.c -ISDN_X25IFACE_MAGIC 0x1e75a2b9 isdn_x25iface_proto_data - drivers/isdn/isdn_x25iface.h -ECP_MAGIC 0x21504345 cdkecpsig include/linux/cdk.h -LSOMAGIC 0x27091997 lso drivers/fc4/fc.c -LSMAGIC 0x2a3b4d2a ls drivers/fc4/fc.c -WANPIPE_MAGIC 0x414C4453 sdla_{dump,exec} include/linux/wanpipe.h -CS_CARD_MAGIC 0x43525553 cs_card sound/oss/cs46xx.c -LABELCL_MAGIC 0x4857434c labelcl_info_s include/asm/ia64/sn/labelcl.h -ISDN_ASYNC_MAGIC 0x49344C01 modem_info include/linux/isdn.h -CTC_ASYNC_MAGIC 0x49344C01 ctc_tty_info drivers/s390/net/ctctty.c -ISDN_NET_MAGIC 0x49344C02 isdn_net_local_s drivers/isdn/i4l/isdn_net_lib.h -SAVEKMSG_MAGIC2 0x4B4D5347 savekmsg arch/*/amiga/config.c -CS_STATE_MAGIC 0x4c4f4749 cs_state sound/oss/cs46xx.c -SLAB_C_MAGIC 0x4f17a36d kmem_cache mm/slab.c -COW_MAGIC 0x4f4f4f4d cow_header_v1 arch/um/drivers/ubd_user.c -I810_CARD_MAGIC 0x5072696E i810_card sound/oss/i810_audio.c -TRIDENT_CARD_MAGIC 0x5072696E trident_card sound/oss/trident.c -ROUTER_MAGIC 0x524d4157 wan_device [in wanrouter.h pre 3.9] -SAVEKMSG_MAGIC1 0x53415645 savekmsg arch/*/amiga/config.c -GDA_MAGIC 0x58464552 gda arch/mips/include/asm/sn/gda.h -RED_MAGIC1 0x5a2cf071 (any) mm/slab.c -EEPROM_MAGIC_VALUE 0x5ab478d2 lanai_dev drivers/atm/lanai.c -HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state include/linux/hdlcdrv.h -PCXX_MAGIC 0x5c6df104 channel drivers/char/pcxx.h -KV_MAGIC 0x5f4b565f kernel_vars_s arch/mips/include/asm/sn/klkernvars.h -I810_STATE_MAGIC 0x63657373 i810_state sound/oss/i810_audio.c -TRIDENT_STATE_MAGIC 0x63657373 trient_state sound/oss/trident.c -M3_CARD_MAGIC 0x646e6f50 m3_card sound/oss/maestro3.c -FW_HEADER_MAGIC 0x65726F66 fw_header drivers/atm/fore200e.h -SLOT_MAGIC 0x67267321 slot drivers/hotplug/cpqphp.h -SLOT_MAGIC 0x67267322 slot drivers/hotplug/acpiphp.h -LO_MAGIC 0x68797548 nbd_device include/linux/nbd.h -OPROFILE_MAGIC 0x6f70726f super_block drivers/oprofile/oprofilefs.h -M3_STATE_MAGIC 0x734d724d m3_state sound/oss/maestro3.c -VMALLOC_MAGIC 0x87654320 snd_alloc_track sound/core/memory.c -KMALLOC_MAGIC 0x87654321 snd_alloc_track sound/core/memory.c -PWC_MAGIC 0x89DC10AB pwc_device drivers/usb/media/pwc.h -NBD_REPLY_MAGIC 0x96744668 nbd_reply include/linux/nbd.h -ENI155_MAGIC 0xa54b872d midway_eprom drivers/atm/eni.h -CODA_MAGIC 0xC0DAC0DA coda_file_info fs/coda/coda_fs_i.h -DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram drivers/scsi/gdth.h -YAM_MAGIC 0xF10A7654 yam_port drivers/net/hamradio/yam.c -CCB_MAGIC 0xf2691ad2 ccb drivers/scsi/ncr53c8xx.c -QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry drivers/scsi/arm/queue.c -QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry drivers/scsi/arm/queue.c -HTB_CMAGIC 0xFEFAFEF1 htb_class net/sched/sch_htb.c -NMI_MAGIC 0x48414d4d455201 nmi_s arch/mips/include/asm/sn/nmi.h +===================== ================ ======================== ========================================== +Magic Name Number Structure File +===================== ================ ======================== ========================================== +PG_MAGIC 'P' pg_{read,write}_hdr ``include/linux/pg.h`` +CMAGIC 0x0111 user ``include/linux/a.out.h`` +MKISS_DRIVER_MAGIC 0x04bf mkiss_channel ``drivers/net/mkiss.h`` +HDLC_MAGIC 0x239e n_hdlc ``drivers/char/n_hdlc.c`` +APM_BIOS_MAGIC 0x4101 apm_user ``arch/x86/kernel/apm_32.c`` +CYCLADES_MAGIC 0x4359 cyclades_port ``include/linux/cyclades.h`` +DB_MAGIC 0x4442 fc_info ``drivers/net/iph5526_novram.c`` +DL_MAGIC 0x444d fc_info ``drivers/net/iph5526_novram.c`` +FASYNC_MAGIC 0x4601 fasync_struct ``include/linux/fs.h`` +FF_MAGIC 0x4646 fc_info ``drivers/net/iph5526_novram.c`` +ISICOM_MAGIC 0x4d54 isi_port ``include/linux/isicom.h`` +PTY_MAGIC 0x5001 ``drivers/char/pty.c`` +PPP_MAGIC 0x5002 ppp ``include/linux/if_pppvar.h`` +SERIAL_MAGIC 0x5301 async_struct ``include/linux/serial.h`` +SSTATE_MAGIC 0x5302 serial_state ``include/linux/serial.h`` +SLIP_MAGIC 0x5302 slip ``drivers/net/slip.h`` +STRIP_MAGIC 0x5303 strip ``drivers/net/strip.c`` +X25_ASY_MAGIC 0x5303 x25_asy ``drivers/net/x25_asy.h`` +SIXPACK_MAGIC 0x5304 sixpack ``drivers/net/hamradio/6pack.h`` +AX25_MAGIC 0x5316 ax_disp ``drivers/net/mkiss.h`` +TTY_MAGIC 0x5401 tty_struct ``include/linux/tty.h`` +MGSL_MAGIC 0x5401 mgsl_info ``drivers/char/synclink.c`` +TTY_DRIVER_MAGIC 0x5402 tty_driver ``include/linux/tty_driver.h`` +MGSLPC_MAGIC 0x5402 mgslpc_info ``drivers/char/pcmcia/synclink_cs.c`` +TTY_LDISC_MAGIC 0x5403 tty_ldisc ``include/linux/tty_ldisc.h`` +USB_SERIAL_MAGIC 0x6702 usb_serial ``drivers/usb/serial/usb-serial.h`` +FULL_DUPLEX_MAGIC 0x6969 ``drivers/net/ethernet/dec/tulip/de2104x.c`` +USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth ``drivers/usb/class/bluetty.c`` +RFCOMM_TTY_MAGIC 0x6d02 ``net/bluetooth/rfcomm/tty.c`` +USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port ``drivers/usb/serial/usb-serial.h`` +CG_MAGIC 0x00090255 ufs_cylinder_group ``include/linux/ufs_fs.h`` +RPORT_MAGIC 0x00525001 r_port ``drivers/char/rocket_int.h`` +LSEMAGIC 0x05091998 lse ``drivers/fc4/fc.c`` +GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str ``drivers/scsi/gdth_ioctl.h`` +RIEBL_MAGIC 0x09051990 ``drivers/net/atarilance.c`` +NBD_REQUEST_MAGIC 0x12560953 nbd_request ``include/linux/nbd.h`` +RED_MAGIC2 0x170fc2a5 (any) ``mm/slab.c`` +BAYCOM_MAGIC 0x19730510 baycom_state ``drivers/net/baycom_epp.c`` +ISDN_X25IFACE_MAGIC 0x1e75a2b9 isdn_x25iface_proto_data ``drivers/isdn/isdn_x25iface.h`` +ECP_MAGIC 0x21504345 cdkecpsig ``include/linux/cdk.h`` +LSOMAGIC 0x27091997 lso ``drivers/fc4/fc.c`` +LSMAGIC 0x2a3b4d2a ls ``drivers/fc4/fc.c`` +WANPIPE_MAGIC 0x414C4453 sdla_{dump,exec} ``include/linux/wanpipe.h`` +CS_CARD_MAGIC 0x43525553 cs_card ``sound/oss/cs46xx.c`` +LABELCL_MAGIC 0x4857434c labelcl_info_s ``include/asm/ia64/sn/labelcl.h`` +ISDN_ASYNC_MAGIC 0x49344C01 modem_info ``include/linux/isdn.h`` +CTC_ASYNC_MAGIC 0x49344C01 ctc_tty_info ``drivers/s390/net/ctctty.c`` +ISDN_NET_MAGIC 0x49344C02 isdn_net_local_s ``drivers/isdn/i4l/isdn_net_lib.h`` +SAVEKMSG_MAGIC2 0x4B4D5347 savekmsg ``arch/*/amiga/config.c`` +CS_STATE_MAGIC 0x4c4f4749 cs_state ``sound/oss/cs46xx.c`` +SLAB_C_MAGIC 0x4f17a36d kmem_cache ``mm/slab.c`` +COW_MAGIC 0x4f4f4f4d cow_header_v1 ``arch/um/drivers/ubd_user.c`` +I810_CARD_MAGIC 0x5072696E i810_card ``sound/oss/i810_audio.c`` +TRIDENT_CARD_MAGIC 0x5072696E trident_card ``sound/oss/trident.c`` +ROUTER_MAGIC 0x524d4157 wan_device [in ``wanrouter.h`` pre 3.9] +SAVEKMSG_MAGIC1 0x53415645 savekmsg ``arch/*/amiga/config.c`` +GDA_MAGIC 0x58464552 gda ``arch/mips/include/asm/sn/gda.h`` +RED_MAGIC1 0x5a2cf071 (any) ``mm/slab.c`` +EEPROM_MAGIC_VALUE 0x5ab478d2 lanai_dev ``drivers/atm/lanai.c`` +HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state ``include/linux/hdlcdrv.h`` +PCXX_MAGIC 0x5c6df104 channel ``drivers/char/pcxx.h`` +KV_MAGIC 0x5f4b565f kernel_vars_s ``arch/mips/include/asm/sn/klkernvars.h`` +I810_STATE_MAGIC 0x63657373 i810_state ``sound/oss/i810_audio.c`` +TRIDENT_STATE_MAGIC 0x63657373 trient_state ``sound/oss/trident.c`` +M3_CARD_MAGIC 0x646e6f50 m3_card ``sound/oss/maestro3.c`` +FW_HEADER_MAGIC 0x65726F66 fw_header ``drivers/atm/fore200e.h`` +SLOT_MAGIC 0x67267321 slot ``drivers/hotplug/cpqphp.h`` +SLOT_MAGIC 0x67267322 slot ``drivers/hotplug/acpiphp.h`` +LO_MAGIC 0x68797548 nbd_device ``include/linux/nbd.h`` +OPROFILE_MAGIC 0x6f70726f super_block ``drivers/oprofile/oprofilefs.h`` +M3_STATE_MAGIC 0x734d724d m3_state ``sound/oss/maestro3.c`` +VMALLOC_MAGIC 0x87654320 snd_alloc_track ``sound/core/memory.c`` +KMALLOC_MAGIC 0x87654321 snd_alloc_track ``sound/core/memory.c`` +PWC_MAGIC 0x89DC10AB pwc_device ``drivers/usb/media/pwc.h`` +NBD_REPLY_MAGIC 0x96744668 nbd_reply ``include/linux/nbd.h`` +ENI155_MAGIC 0xa54b872d midway_eprom ``drivers/atm/eni.h`` +CODA_MAGIC 0xC0DAC0DA coda_file_info ``fs/coda/coda_fs_i.h`` +DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram ``drivers/scsi/gdth.h`` +YAM_MAGIC 0xF10A7654 yam_port ``drivers/net/hamradio/yam.c`` +CCB_MAGIC 0xf2691ad2 ccb ``drivers/scsi/ncr53c8xx.c`` +QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry ``drivers/scsi/arm/queue.c`` +QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry ``drivers/scsi/arm/queue.c`` +HTB_CMAGIC 0xFEFAFEF1 htb_class ``net/sched/sch_htb.c`` +NMI_MAGIC 0x48414d4d455201 nmi_s ``arch/mips/include/asm/sn/nmi.h`` +===================== ================ ======================== ========================================== Note that there are also defined special per-driver magic numbers in sound -memory management. See include/sound/sndmagic.h for complete list of them. Many +memory management. See ``include/sound/sndmagic.h`` for complete list of them. Many OSS sound drivers have their magic numbers constructed from the soundcard PCI ID - these are not listed here as well. IrDA subsystem also uses large number of own magic numbers, see -include/net/irda/irda.h for a complete list of them. +``include/net/irda/irda.h`` for a complete list of them. HFS is another larger user of magic numbers - you can find them in -fs/hfs/hfs.h. +``fs/hfs/hfs.h``. -- cgit v1.2.3 From aeb04e52f1145308c013b2ec7ea660309857a1f1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 13:22:41 -0300 Subject: Documentation/md.txt: Convert to ReST markup - add a title for the document; - convert some parameters to tables; - use quote blocks where needed; - use monotonic fonts for parameters; - adjust whitespaces and blank lines; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/md.txt | 528 +++++++++++++++++++++++++++++++-------------------- 1 file changed, 321 insertions(+), 207 deletions(-) diff --git a/Documentation/md.txt b/Documentation/md.txt index d6e2fcf27337..e449fb5f277c 100644 --- a/Documentation/md.txt +++ b/Documentation/md.txt @@ -1,42 +1,77 @@ -Tools that manage md devices can be found at - http://www.kernel.org/pub/linux/utils/raid/ - +RAID arrays +=========== Boot time assembly of RAID arrays --------------------------------- +Tools that manage md devices can be found at + http://www.kernel.org/pub/linux/utils/raid/ + + You can boot with your md device with the following kernel command lines: -for old raid arrays without persistent superblocks: +for old raid arrays without persistent superblocks:: + md=,,,,dev0,dev1,...,devn -for raid arrays with persistent superblocks +for raid arrays with persistent superblocks:: + md=,dev0,dev1,...,devn -or, to assemble a partitionable array: + +or, to assemble a partitionable array:: + md=d,dev0,dev1,...,devn - -md device no. = the number of the md device ... - 0 means md0, - 1 md1, - 2 md2, - 3 md3, - 4 md4 - -raid level = -1 linear mode - 0 striped mode - other modes are only supported with persistent super blocks - -chunk size factor = (raid-0 and raid-1 only) - Set the chunk size as 4k << n. - -fault level = totally ignored - -dev0-devn: e.g. /dev/hda1,/dev/hdc1,/dev/sda1,/dev/sdb1 - -A possible loadlin line (Harald Hoyer ) looks like this: - -e:\loadlin\loadlin e:\zimage root=/dev/md0 md=0,0,4,0,/dev/hdb2,/dev/hdc3 ro + +``md device no.`` ++++++++++++++++++ + +The number of the md device + +================= ========= +``md device no.`` device +================= ========= + 0 md0 + 1 md1 + 2 md2 + 3 md3 + 4 md4 +================= ========= + +``raid level`` +++++++++++++++ + +level of the RAID array + +=============== ============= +``raid level`` level +=============== ============= +-1 linear mode +0 striped mode +=============== ============= + +other modes are only supported with persistent super blocks + +``chunk size factor`` ++++++++++++++++++++++ + +(raid-0 and raid-1 only) + +Set the chunk size as 4k << n. + +``fault level`` ++++++++++++++++ + +Totally ignored + +``dev0`` to ``devn`` +++++++++++++++++++++ + +e.g. ``/dev/hda1``, ``/dev/hdc1``, ``/dev/sda1``, ``/dev/sdb1`` + +A possible loadlin line (Harald Hoyer ) looks like this:: + + e:\loadlin\loadlin e:\zimage root=/dev/md0 md=0,0,4,0,/dev/hdb2,/dev/hdc3 ro Boot time autodetection of RAID arrays @@ -45,10 +80,10 @@ Boot time autodetection of RAID arrays When md is compiled into the kernel (not as module), partitions of type 0xfd are scanned and automatically assembled into RAID arrays. This autodetection may be suppressed with the kernel parameter -"raid=noautodetect". As of kernel 2.6.9, only drives with a type 0 +``raid=noautodetect``. As of kernel 2.6.9, only drives with a type 0 superblock can be autodetected and run at boot time. -The kernel parameter "raid=partitionable" (or "raid=part") means +The kernel parameter ``raid=partitionable`` (or ``raid=part``) means that all auto-detected arrays are assembled as partitionable. Boot time assembly of degraded/dirty arrays @@ -56,22 +91,23 @@ Boot time assembly of degraded/dirty arrays If a raid5 or raid6 array is both dirty and degraded, it could have undetectable data corruption. This is because the fact that it is -'dirty' means that the parity cannot be trusted, and the fact that it +``dirty`` means that the parity cannot be trusted, and the fact that it is degraded means that some datablocks are missing and cannot reliably be reconstructed (due to no parity). For this reason, md will normally refuse to start such an array. This requires the sysadmin to take action to explicitly start the array -despite possible corruption. This is normally done with +despite possible corruption. This is normally done with:: + mdadm --assemble --force .... This option is not really available if the array has the root filesystem on it. In order to support this booting from such an -array, md supports a module parameter "start_dirty_degraded" which, +array, md supports a module parameter ``start_dirty_degraded`` which, when set to 1, bypassed the checks and will allows dirty degraded arrays to be started. -So, to boot with a root filesystem of a dirty degraded raid[56], use +So, to boot with a root filesystem of a dirty degraded raid 5 or 6, use:: md-mod.start_dirty_degraded=1 @@ -80,30 +116,30 @@ Superblock formats ------------------ The md driver can support a variety of different superblock formats. -Currently, it supports superblock formats "0.90.0" and the "md-1" format +Currently, it supports superblock formats ``0.90.0`` and the ``md-1`` format introduced in the 2.5 development series. The kernel will autodetect which format superblock is being used. -Superblock format '0' is treated differently to others for legacy +Superblock format ``0`` is treated differently to others for legacy reasons - it is the original superblock format. General Rules - apply for all superblock formats ------------------------------------------------ -An array is 'created' by writing appropriate superblocks to all +An array is ``created`` by writing appropriate superblocks to all devices. -It is 'assembled' by associating each of these devices with an +It is ``assembled`` by associating each of these devices with an particular md virtual device. Once it is completely assembled, it can be accessed. An array should be created by a user-space tool. This will write superblocks to all devices. It will usually mark the array as -'unclean', or with some devices missing so that the kernel md driver -can create appropriate redundancy (copying in raid1, parity -calculation in raid4/5). +``unclean``, or with some devices missing so that the kernel md driver +can create appropriate redundancy (copying in raid 1, parity +calculation in raid 4/5). When an array is assembled, it is first initialized with the SET_ARRAY_INFO ioctl. This contains, in particular, a major and minor @@ -126,13 +162,12 @@ Devices that have failed or are not yet active can be detached from an array using HOT_REMOVE_DISK. -Specific Rules that apply to format-0 super block arrays, and - arrays with no superblock (non-persistent). -------------------------------------------------------------- +Specific Rules that apply to format-0 super block arrays, and arrays with no superblock (non-persistent) +-------------------------------------------------------------------------------------------------------- -An array can be 'created' by describing the array (level, chunksize -etc) in a SET_ARRAY_INFO ioctl. This must have major_version==0 and -raid_disks != 0. +An array can be ``created`` by describing the array (level, chunksize +etc) in a SET_ARRAY_INFO ioctl. This must have ``major_version==0`` and +``raid_disks != 0``. Then uninitialized devices can be added with ADD_NEW_DISK. The structure passed to ADD_NEW_DISK must specify the state of the device @@ -142,24 +177,26 @@ Once started with RUN_ARRAY, uninitialized spares can be added with HOT_ADD_DISK. - MD devices in sysfs ------------------- -md devices appear in sysfs (/sys) as regular block devices, -e.g. + +md devices appear in sysfs (``/sys``) as regular block devices, +e.g.:: + /sys/block/md0 -Each 'md' device will contain a subdirectory called 'md' which +Each ``md`` device will contain a subdirectory called ``md`` which contains further md-specific information about the device. All md devices contain: + level - a text file indicating the 'raid level'. e.g. raid0, raid1, + a text file indicating the ``raid level``. e.g. raid0, raid1, raid5, linear, multipath, faulty. If no raid level has been set yet (array is still being assembled), the value will reflect whatever has been written to it, which may be a name like the above, or may be a number - such as '0', '5', etc. + such as ``0``, ``5``, etc. raid_disks a text file with a simple number indicating the number of devices @@ -172,10 +209,10 @@ All md devices contain: A change to this attribute will not be permitted if it would reduce the size of the array. To reduce the number of drives in an e.g. raid5, the array size must first be reduced by - setting the 'array_size' attribute. + setting the ``array_size`` attribute. chunk_size - This is the size in bytes for 'chunks' and is only relevant to + This is the size in bytes for ``chunks`` and is only relevant to raid levels that involve striping (0,4,5,6,10). The address space of the array is conceptually divided into chunks and consecutive chunks are striped onto neighbouring devices. @@ -183,7 +220,7 @@ All md devices contain: of 2. This can only be set while assembling an array layout - The "layout" for the array for the particular level. This is + The ``layout`` for the array for the particular level. This is simply a number that is interpretted differently by different levels. It can be written while assembling an array. @@ -193,22 +230,24 @@ All md devices contain: devices. Writing a number (in Kilobytes) which is less than the available size will set the size. Any reconfiguration of the array (e.g. adding devices) will not cause the size to change. - Writing the word 'default' will cause the effective size of the + Writing the word ``default`` will cause the effective size of the array to be whatever size is actually available based on - 'level', 'chunk_size' and 'component_size'. + ``level``, ``chunk_size`` and ``component_size``. This can be used to reduce the size of the array before reducing the number of devices in a raid4/5/6, or to support external metadata formats which mandate such clipping. reshape_position - This is either "none" or a sector number within the devices of - the array where "reshape" is up to. If this is set, the three + This is either ``none`` or a sector number within the devices of + the array where ``reshape`` is up to. If this is set, the three attributes mentioned above (raid_disks, chunk_size, layout) can potentially have 2 values, an old and a new value. If these - values differ, reading the attribute returns + values differ, reading the attribute returns:: + new (old) - and writing will effect the 'new' value, leaving the 'old' + + and writing will effect the ``new`` value, leaving the ``old`` unchanged. component_size @@ -223,9 +262,9 @@ All md devices contain: metadata_version This indicates the format that is being used to record metadata about the array. It can be 0.90 (traditional format), 1.0, 1.1, - 1.2 (newer format in varying locations) or "none" indicating that + 1.2 (newer format in varying locations) or ``none`` indicating that the kernel isn't managing metadata at all. - Alternately it can be "external:" followed by a string which + Alternately it can be ``external:`` followed by a string which is set by user-space. This indicates that metadata is managed by a user-space program. Any device failure or other event that requires a metadata update will cause array activity to be @@ -233,9 +272,9 @@ All md devices contain: resync_start The point at which resync should start. If no resync is needed, - this will be a very large number (or 'none' since 2.6.30-rc1). At + this will be a very large number (or ``none`` since 2.6.30-rc1). At array creation it will default to 0, though starting the array as - 'clean' will set it much larger. + ``clean`` will set it much larger. new_dev This file can be written but not read. The value written should @@ -246,10 +285,10 @@ All md devices contain: safe_mode_delay When an md array has seen no write requests for a certain period - of time, it will be marked as 'clean'. When another write - request arrives, the array is marked as 'dirty' before the write - commences. This is known as 'safe_mode'. - The 'certain period' is controlled by this file which stores the + of time, it will be marked as ``clean``. When another write + request arrives, the array is marked as ``dirty`` before the write + commences. This is known as ``safe_mode``. + The ``certain period`` is controlled by this file which stores the period as a number of seconds. The default is 200msec (0.200). Writing a value of 0 disables safemode. @@ -260,38 +299,50 @@ All md devices contain: cannot be explicitly set, and some transitions are not allowed. Select/poll works on this file. All changes except between - active_idle and active (which can be frequent and are not - very interesting) are notified. active->active_idle is - reported if the metadata is externally managed. + Active_idle and active (which can be frequent and are not + very interesting) are notified. active->active_idle is + reported if the metadata is externally managed. clear No devices, no size, no level + Writing is equivalent to STOP_ARRAY ioctl + inactive May have some settings, but array is not active - all IO results in error + all IO results in error + When written, doesn't tear down array, but just stops it + suspended (not supported yet) All IO requests will block. The array can be reconfigured. + Writing this, if accepted, will block until array is quiessent + readonly no resync can happen. no superblocks get written. - write requests fail + + Write requests fail + read-auto - like readonly, but behaves like 'clean' on a write request. + like readonly, but behaves like ``clean`` on a write request. + + clean + no pending writes, but otherwise active. - clean - no pending writes, but otherwise active. When written to inactive array, starts without resync + If a write request arrives then - if metadata is known, mark 'dirty' and switch to 'active'. - if not known, block and switch to write-pending + if metadata is known, mark ``dirty`` and switch to ``active``. + if not known, block and switch to write-pending + If written to an active array that has pending writes, then fails. active fully active: IO and resync can be happening. When written to inactive array, starts with resync write-pending - clean, but writes are blocked waiting for 'active' to be written. + clean, but writes are blocked waiting for ``active`` to be written. active-idle like active, but no writes have been seen for a while (safe_mode_delay). @@ -299,57 +350,71 @@ All md devices contain: bitmap/location This indicates where the write-intent bitmap for the array is stored. - It can be one of "none", "file" or "[+-]N". - "file" may later be extended to "file:/file/name" - "[+-]N" means that many sectors from the start of the metadata. - This is replicated on all devices. For arrays with externally - managed metadata, the offset is from the beginning of the - device. + + It can be one of ``none``, ``file`` or ``[+-]N``. + ``file`` may later be extended to ``file:/file/name`` + ``[+-]N`` means that many sectors from the start of the metadata. + + This is replicated on all devices. For arrays with externally + managed metadata, the offset is from the beginning of the + device. + bitmap/chunksize The size, in bytes, of the chunk which will be represented by a single bit. For RAID456, it is a portion of an individual device. For RAID10, it is a portion of the array. For RAID1, it is both (they come to the same thing). + bitmap/time_base The time, in seconds, between looking for bits in the bitmap to be cleared. In the current implementation, a bit will be cleared - between 2 and 3 times "time_base" after all the covered blocks + between 2 and 3 times ``time_base`` after all the covered blocks are known to be in-sync. + bitmap/backlog When write-mostly devices are active in a RAID1, write requests to those devices proceed in the background - the filesystem (or other user of the device) does not have to wait for them. - 'backlog' sets a limit on the number of concurrent background + ``backlog`` sets a limit on the number of concurrent background writes. If there are more than this, new writes will by synchronous. + bitmap/metadata - This can be either 'internal' or 'external'. - 'internal' is the default and means the metadata for the bitmap - is stored in the first 256 bytes of the allocated space and is - managed by the md module. - 'external' means that bitmap metadata is managed externally to - the kernel (i.e. by some userspace program) + This can be either ``internal`` or ``external``. + + ``internal`` + is the default and means the metadata for the bitmap + is stored in the first 256 bytes of the allocated space and is + managed by the md module. + + ``external`` + means that bitmap metadata is managed externally to + the kernel (i.e. by some userspace program) + bitmap/can_clear - This is either 'true' or 'false'. If 'true', then bits in the + This is either ``true`` or ``false``. If ``true``, then bits in the bitmap will be cleared when the corresponding blocks are thought - to be in-sync. If 'false', bits will never be cleared. - This is automatically set to 'false' if a write happens on a + to be in-sync. If ``false``, bits will never be cleared. + This is automatically set to ``false`` if a write happens on a degraded array, or if the array becomes degraded during a write. When metadata is managed externally, it should be set to true once the array becomes non-degraded, and this fact has been recorded in the metadata. - - - -As component devices are added to an md array, they appear in the 'md' -directory as new directories named + + + +As component devices are added to an md array, they appear in the ``md`` +directory as new directories named:: + dev-XXX -where XXX is a name that the kernel knows for the device, e.g. hdb1. + +where ``XXX`` is a name that the kernel knows for the device, e.g. hdb1. Each directory contains: block - a symlink to the block device in /sys/block, e.g. + a symlink to the block device in /sys/block, e.g.:: + /sys/block/md0/md/dev-hdb1/block -> ../../../../block/hdb/hdb1 super @@ -358,51 +423,83 @@ Each directory contains: state A file recording the current state of the device in the array - which can be a comma separated list of - faulty - device has been kicked from active use due to - a detected fault, or it has unacknowledged bad - blocks - in_sync - device is a fully in-sync member of the array - writemostly - device will only be subject to read - requests if there are no other options. - This applies only to raid1 arrays. - blocked - device has failed, and the failure hasn't been - acknowledged yet by the metadata handler. - Writes that would write to this device if - it were not faulty are blocked. - spare - device is working, but not a full member. - This includes spares that are in the process - of being recovered to - write_error - device has ever seen a write error. - want_replacement - device is (mostly) working but probably - should be replaced, either due to errors or - due to user request. - replacement - device is a replacement for another active - device with same raid_disk. + which can be a comma separated list of: + + faulty + device has been kicked from active use due to + a detected fault, or it has unacknowledged bad + blocks + + in_sync + device is a fully in-sync member of the array + + writemostly + device will only be subject to read + requests if there are no other options. + + This applies only to raid1 arrays. + + blocked + device has failed, and the failure hasn't been + acknowledged yet by the metadata handler. + + Writes that would write to this device if + it were not faulty are blocked. + + spare + device is working, but not a full member. + + This includes spares that are in the process + of being recovered to + + write_error + device has ever seen a write error. + + want_replacement + device is (mostly) working but probably + should be replaced, either due to errors or + due to user request. + + replacement + device is a replacement for another active + device with same raid_disk. This list may grow in future. + This can be written to. - Writing "faulty" simulates a failure on the device. - Writing "remove" removes the device from the array. - Writing "writemostly" sets the writemostly flag. - Writing "-writemostly" clears the writemostly flag. - Writing "blocked" sets the "blocked" flag. - Writing "-blocked" clears the "blocked" flags and allows writes - to complete and possibly simulates an error. - Writing "in_sync" sets the in_sync flag. - Writing "write_error" sets writeerrorseen flag. - Writing "-write_error" clears writeerrorseen flag. - Writing "want_replacement" is allowed at any time except to a - replacement device or a spare. It sets the flag. - Writing "-want_replacement" is allowed at any time. It clears - the flag. - Writing "replacement" or "-replacement" is only allowed before - starting the array. It sets or clears the flag. - - - This file responds to select/poll. Any change to 'faulty' - or 'blocked' causes an event. + + Writing ``faulty`` simulates a failure on the device. + + Writing ``remove`` removes the device from the array. + + Writing ``writemostly`` sets the writemostly flag. + + Writing ``-writemostly`` clears the writemostly flag. + + Writing ``blocked`` sets the ``blocked`` flag. + + Writing ``-blocked`` clears the ``blocked`` flags and allows writes + to complete and possibly simulates an error. + + Writing ``in_sync`` sets the in_sync flag. + + Writing ``write_error`` sets writeerrorseen flag. + + Writing ``-write_error`` clears writeerrorseen flag. + + Writing ``want_replacement`` is allowed at any time except to a + replacement device or a spare. It sets the flag. + + Writing ``-want_replacement`` is allowed at any time. It clears + the flag. + + Writing ``replacement`` or ``-replacement`` is only allowed before + starting the array. It sets or clears the flag. + + + This file responds to select/poll. Any change to ``faulty`` + or ``blocked`` causes an event. errors An approximate count of read errors that have been detected on @@ -417,9 +514,9 @@ Each directory contains: slot This gives the role that the device has in the array. It will - either be 'none' if the device is not active in the array + either be ``none`` if the device is not active in the array (i.e. is a spare or has failed) or an integer less than the - 'raid_disks' number for the array indicating which position + ``raid_disks`` number for the array indicating which position it currently fills. This can only be set while assembling an array. A device for which this is set is assumed to be working. @@ -437,7 +534,7 @@ Each directory contains: written, it will be rejected. recovery_start - When the device is not 'in_sync', this records the number of + When the device is not ``in_sync``, this records the number of sectors from the start of the device which are known to be correct. This is normally zero, but during a recovery operation it will steadily increase, and if the recovery is @@ -447,21 +544,21 @@ Each directory contains: This can be set whenever the device is not an active member of the array, either before the array is activated, or before - the 'slot' is set. + the ``slot`` is set. + + Setting this to ``none`` is equivalent to setting ``in_sync``. + Setting to any other value also clears the ``in_sync`` flag. - Setting this to 'none' is equivalent to setting 'in_sync'. - Setting to any other value also clears the 'in_sync' flag. - bad_blocks This gives the list of all known bad blocks in the form of start address and length (in sectors respectively). If output is too big to fit in a page, it will be truncated. Writing - "sector length" to this file adds new acknowledged (i.e. + ``sector length`` to this file adds new acknowledged (i.e. recorded to disk safely) bad blocks. unacknowledged_bad_blocks This gives the list of known-but-not-yet-saved-to-disk bad - blocks in the same form of 'bad_blocks'. If output is too big + blocks in the same form of ``bad_blocks``. If output is too big to fit in a page, it will be truncated. Writing to this file adds bad blocks without acknowledging them. This is largely for testing. @@ -469,16 +566,18 @@ Each directory contains: An active md device will also contain an entry for each active device -in the array. These are named +in the array. These are named:: rdNN -where 'NN' is the position in the array, starting from 0. +where ``NN`` is the position in the array, starting from 0. So for a 3 drive array there will be rd0, rd1, rd2. -These are symbolic links to the appropriate 'dev-XXX' entry. -Thus, for example, +These are symbolic links to the appropriate ``dev-XXX`` entry. +Thus, for example:: + cat /sys/block/md*/md/rd*/state -will show 'in_sync' on every line. + +will show ``in_sync`` on every line. @@ -488,50 +587,62 @@ also have sync_action a text file that can be used to monitor and control the rebuild process. It contains one word which can be one of: - resync - redundancy is being recalculated after unclean - shutdown or creation - recover - a hot spare is being built to replace a - failed/missing device - idle - nothing is happening - check - A full check of redundancy was requested and is - happening. This reads all blocks and checks - them. A repair may also happen for some raid - levels. - repair - A full check and repair is happening. This is - similar to 'resync', but was requested by the - user, and the write-intent bitmap is NOT used to - optimise the process. + + resync + redundancy is being recalculated after unclean + shutdown or creation + + recover + a hot spare is being built to replace a + failed/missing device + + idle + nothing is happening + check + A full check of redundancy was requested and is + happening. This reads all blocks and checks + them. A repair may also happen for some raid + levels. + + repair + A full check and repair is happening. This is + similar to ``resync``, but was requested by the + user, and the write-intent bitmap is NOT used to + optimise the process. This file is writable, and each of the strings that could be read are meaningful for writing. - 'idle' will stop an active resync/recovery etc. There is no - guarantee that another resync/recovery may not be automatically - started again, though some event will be needed to trigger - this. - 'resync' or 'recovery' can be used to restart the - corresponding operation if it was stopped with 'idle'. - 'check' and 'repair' will start the appropriate process - providing the current state is 'idle'. + ``idle`` will stop an active resync/recovery etc. There is no + guarantee that another resync/recovery may not be automatically + started again, though some event will be needed to trigger + this. + + ``resync`` or ``recovery`` can be used to restart the + corresponding operation if it was stopped with ``idle``. + + ``check`` and ``repair`` will start the appropriate process + providing the current state is ``idle``. This file responds to select/poll. Any important change in the value triggers a poll event. Sometimes the value will briefly be - "recover" if a recovery seems to be needed, but cannot be - achieved. In that case, the transition to "recover" isn't + ``recover`` if a recovery seems to be needed, but cannot be + achieved. In that case, the transition to ``recover`` isn't notified, but the transition away is. degraded This contains a count of the number of devices by which the - arrays is degraded. So an optimal array will show '0'. A - single failed/missing drive will show '1', etc. + arrays is degraded. So an optimal array will show ``0``. A + single failed/missing drive will show ``1``, etc. + This file responds to select/poll, any increase or decrease in the count of missing devices will trigger an event. mismatch_count - When performing 'check' and 'repair', and possibly when - performing 'resync', md will count the number of errors that are - found. The count in 'mismatch_cnt' is the number of sectors - that were re-written, or (for 'check') would have been + When performing ``check`` and ``repair``, and possibly when + performing ``resync``, md will count the number of errors that are + found. The count in ``mismatch_cnt`` is the number of sectors + that were re-written, or (for ``check``) would have been re-written. As most raid levels work in units of pages rather than sectors, this may be larger than the number of actual errors by a factor of the number of sectors in a page. @@ -542,27 +653,30 @@ also have would need to check the corresponding blocks. Either individual numbers or start-end pairs can be written. Multiple numbers can be separated by a space. - Note that the numbers are 'bit' numbers, not 'block' numbers. + + Note that the numbers are ``bit`` numbers, not ``block`` numbers. They should be scaled by the bitmap_chunksize. - sync_speed_min - sync_speed_max - This are similar to /proc/sys/dev/raid/speed_limit_{min,max} + sync_speed_min, sync_speed_max + This are similar to ``/proc/sys/dev/raid/speed_limit_{min,max}`` however they only apply to the particular array. - If no value has been written to these, or if the word 'system' + + If no value has been written to these, or if the word ``system`` is written, then the system-wide value is used. If a value, in kibibytes-per-second is written, then it is used. + When the files are read, they show the currently active value - followed by "(local)" or "(system)" depending on whether it is + followed by ``(local)`` or ``(system)`` depending on whether it is a locally set or system-wide value. sync_completed This shows the number of sectors that have been completed of whatever the current sync_action is, followed by the number of sectors in total that could need to be processed. The two - numbers are separated by a '/' thus effectively showing one + numbers are separated by a ``/`` thus effectively showing one value, a fraction of the process that is complete. - A 'select' on this attribute will return when resync completes, + + A ``select`` on this attribute will return when resync completes, when it reaches the current sync_max (below) and possibly at other times. @@ -570,26 +684,24 @@ also have This shows the current actual speed, in K/sec, of the current sync_action. It is averaged over the last 30 seconds. - suspend_lo - suspend_hi + suspend_lo, suspend_hi The two values, given as numbers of sectors, indicate a range within the array where IO will be blocked. This is currently only supported for raid4/5/6. - sync_min - sync_max + sync_min, sync_max The two values, given as numbers of sectors, indicate a range - within the array where 'check'/'repair' will operate. Must be - a multiple of chunk_size. When it reaches "sync_max" it will + within the array where ``check``/``repair`` will operate. Must be + a multiple of chunk_size. When it reaches ``sync_max`` it will pause, rather than complete. - You can use 'select' or 'poll' on "sync_completed" to wait for + You can use ``select`` or ``poll`` on ``sync_completed`` to wait for that number to reach sync_max. Then you can either increase - "sync_max", or can write 'idle' to "sync_action". + ``sync_max``, or can write ``idle`` to ``sync_action``. - The value of 'max' for "sync_max" effectively disables the limit. + The value of ``max`` for ``sync_max`` effectively disables the limit. When a resync is active, the value can only ever be increased, never decreased. - The value of '0' is the minimum for "sync_min". + The value of ``0`` is the minimum for ``sync_min``. @@ -598,13 +710,15 @@ personality module that manages it. These are specific to the implementation of the module and could change substantially if the implementation changes. -These currently include +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, 17). Default is 256. + strip_cache_active (currently raid5 only) number of active entries in the stripe cache + preread_bypass_threshold (currently raid5 only) number of times a stripe requiring preread will be bypassed by a stripe that does not require preread. For fairness defaults -- cgit v1.2.3 From 94e980cc45f2b21afceff0cb1866a1af32d20325 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 13:44:24 -0300 Subject: Documentation/module-signing.txt: convert to ReST markup - Fix identatio for the document title; - remove its index; - create a table for hash algorithm to be used; - use quote blocks where needed; - use monotonic fonts for parameters; - adjust whitespaces and blank lines; - Fix case on section titles; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/admin-guide/module-signing.rst | 285 +++++++++++++++++++++++++++ Documentation/module-signing.txt | 279 -------------------------- 2 files changed, 285 insertions(+), 279 deletions(-) create mode 100644 Documentation/admin-guide/module-signing.rst delete mode 100644 Documentation/module-signing.txt diff --git a/Documentation/admin-guide/module-signing.rst b/Documentation/admin-guide/module-signing.rst new file mode 100644 index 000000000000..27e59498b487 --- /dev/null +++ b/Documentation/admin-guide/module-signing.rst @@ -0,0 +1,285 @@ +Kernel module signing facility +------------------------------ + +.. CONTENTS +.. +.. - Overview. +.. - Configuring module signing. +.. - Generating signing keys. +.. - Public keys in the kernel. +.. - Manually signing modules. +.. - Signed modules and stripping. +.. - Loading signed modules. +.. - Non-valid signatures and unsigned modules. +.. - Administering/protecting the private key. + + +======== +Overview +======== + +The kernel module signing facility cryptographically signs modules during +installation and then checks the signature upon loading the module. This +allows increased kernel security by disallowing the loading of unsigned modules +or modules signed with an invalid key. Module signing increases security by +making it harder to load a malicious module into the kernel. The module +signature checking is done by the kernel so that it is not necessary to have +trusted userspace bits. + +This facility uses X.509 ITU-T standard certificates to encode the public keys +involved. The signatures are not themselves encoded in any industrial standard +type. The facility currently only supports the RSA public key encryption +standard (though it is pluggable and permits others to be used). The possible +hash algorithms that can be used are SHA-1, SHA-224, SHA-256, SHA-384, and +SHA-512 (the algorithm is selected by data in the signature). + + +========================== +Configuring module signing +========================== + +The module signing facility is enabled by going to the +:menuselection:`Enable Loadable Module Support` section of +the kernel configuration and turning on:: + + CONFIG_MODULE_SIG "Module signature verification" + +This has a number of options available: + + (1) :menuselection:`Require modules to be validly signed` + (``CONFIG_MODULE_SIG_FORCE``) + + This specifies how the kernel should deal with a module that has a + signature for which the key is not known or a module that is unsigned. + + If this is off (ie. "permissive"), then modules for which the key is not + available and modules that are unsigned are permitted, but the kernel will + be marked as being tainted, and the concerned modules will be marked as + tainted, shown with the character 'E'. + + If this is on (ie. "restrictive"), only modules that have a valid + signature that can be verified by a public key in the kernel's possession + will be loaded. All other modules will generate an error. + + Irrespective of the setting here, if the module has a signature block that + cannot be parsed, it will be rejected out of hand. + + + (2) :menuselection:`Automatically sign all modules` + (``CONFIG_MODULE_SIG_ALL``) + + If this is on then modules will be automatically signed during the + modules_install phase of a build. If this is off, then the modules must + be signed manually using:: + + scripts/sign-file + + + (3) :menuselection:`Which hash algorithm should modules be signed with?` + + This presents a choice of which hash algorithm the installation phase will + sign the modules with: + + =============================== ========================================== + ``CONFIG_MODULE_SIG_SHA1`` :menuselection:`Sign modules with SHA-1` + ``CONFIG_MODULE_SIG_SHA224`` :menuselection:`Sign modules with SHA-224` + ``CONFIG_MODULE_SIG_SHA256`` :menuselection:`Sign modules with SHA-256` + ``CONFIG_MODULE_SIG_SHA384`` :menuselection:`Sign modules with SHA-384` + ``CONFIG_MODULE_SIG_SHA512`` :menuselection:`Sign modules with SHA-512` + =============================== ========================================== + + The algorithm selected here will also be built into the kernel (rather + than being a module) so that modules signed with that algorithm can have + their signatures checked without causing a dependency loop. + + + (4) :menuselection:`File name or PKCS#11 URI of module signing key` + (``CONFIG_MODULE_SIG_KEY``) + + Setting this option to something other than its default of + ``certs/signing_key.pem`` will disable the autogeneration of signing keys + and allow the kernel modules to be signed with a key of your choosing. + The string provided should identify a file containing both a private key + and its corresponding X.509 certificate in PEM form, or — on systems where + the OpenSSL ENGINE_pkcs11 is functional — a PKCS#11 URI as defined by + RFC7512. In the latter case, the PKCS#11 URI should reference both a + certificate and a private key. + + If the PEM file containing the private key is encrypted, or if the + PKCS#11 token requries a PIN, this can be provided at build time by + means of the ``KBUILD_SIGN_PIN`` variable. + + + (5) :menuselection:`Additional X.509 keys for default system keyring` + (``CONFIG_SYSTEM_TRUSTED_KEYS``) + + This option can be set to the filename of a PEM-encoded file containing + additional certificates which will be included in the system keyring by + default. + +Note that enabling module signing adds a dependency on the OpenSSL devel +packages to the kernel build processes for the tool that does the signing. + + +======================= +Generating signing keys +======================= + +Cryptographic keypairs are required to generate and check signatures. A +private key is used to generate a signature and the corresponding public key is +used to check it. The private key is only needed during the build, after which +it can be deleted or stored securely. The public key gets built into the +kernel so that it can be used to check the signatures as the modules are +loaded. + +Under normal conditions, when ``CONFIG_MODULE_SIG_KEY`` is unchanged from its +default, the kernel build will automatically generate a new keypair using +openssl if one does not exist in the file:: + + certs/signing_key.pem + +during the building of vmlinux (the public part of the key needs to be built +into vmlinux) using parameters in the:: + + certs/x509.genkey + +file (which is also generated if it does not already exist). + +It is strongly recommended that you provide your own x509.genkey file. + +Most notably, in the x509.genkey file, the req_distinguished_name section +should be altered from the default:: + + [ req_distinguished_name ] + #O = Unspecified company + CN = Build time autogenerated kernel key + #emailAddress = unspecified.user@unspecified.company + +The generated RSA key size can also be set with:: + + [ req ] + default_bits = 4096 + + +It is also possible to manually generate the key private/public files using the +x509.genkey key generation configuration file in the root node of the Linux +kernel sources tree and the openssl command. The following is an example to +generate the public/private key files:: + + openssl req -new -nodes -utf8 -sha256 -days 36500 -batch -x509 \ + -config x509.genkey -outform PEM -out kernel_key.pem \ + -keyout kernel_key.pem + +The full pathname for the resulting kernel_key.pem file can then be specified +in the ``CONFIG_MODULE_SIG_KEY`` option, and the certificate and key therein will +be used instead of an autogenerated keypair. + + +========================= +Public keys in the kernel +========================= + +The kernel contains a ring of public keys that can be viewed by root. They're +in a keyring called ".system_keyring" that can be seen by:: + + [root@deneb ~]# cat /proc/keys + ... + 223c7853 I------ 1 perm 1f030000 0 0 keyring .system_keyring: 1 + 302d2d52 I------ 1 perm 1f010000 0 0 asymmetri Fedora kernel signing key: d69a84e6bce3d216b979e9505b3e3ef9a7118079: X509.RSA a7118079 [] + ... + +Beyond the public key generated specifically for module signing, additional +trusted certificates can be provided in a PEM-encoded file referenced by the +``CONFIG_SYSTEM_TRUSTED_KEYS`` configuration option. + +Further, the architecture code may take public keys from a hardware store and +add those in also (e.g. from the UEFI key database). + +Finally, it is possible to add additional public keys by doing:: + + keyctl padd asymmetric "" [.system_keyring-ID] <[key-file] + +e.g.:: + + keyctl padd asymmetric "" 0x223c7853 Date: Fri, 23 Sep 2016 13:52:05 -0300 Subject: Documentation/mono.txt: convert to ReST markup - Fix document title; - use quote blocks where needed; - use .. note:: for notes; - use monotonic fonts for config options and file names; - adjust whitespaces and blank lines; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/mono.txt | 44 +++++++++++++++++++++++--------------------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/Documentation/mono.txt b/Documentation/mono.txt index d01ac6052194..9a9744ca0cf3 100644 --- a/Documentation/mono.txt +++ b/Documentation/mono.txt @@ -1,5 +1,5 @@ - Mono(tm) Binary Kernel Support for Linux - ----------------------------------------- +Mono(tm) Binary Kernel Support for Linux +----------------------------------------- To configure Linux to automatically execute Mono-based .NET binaries (in the form of .exe files) without the need to use the mono CLR @@ -19,22 +19,22 @@ other program after you have done the following: http://www.go-mono.com/compiling.html Once the Mono CLR support has been installed, just check that - /usr/bin/mono (which could be located elsewhere, for example - /usr/local/bin/mono) is working. + ``/usr/bin/mono`` (which could be located elsewhere, for example + ``/usr/local/bin/mono``) is working. 2) You have to compile BINFMT_MISC either as a module or into - the kernel (CONFIG_BINFMT_MISC) and set it up properly. + the kernel (``CONFIG_BINFMT_MISC``) and set it up properly. If you choose to compile it as a module, you will have to insert it manually with modprobe/insmod, as kmod - cannot be easily supported with binfmt_misc. - Read the file 'binfmt_misc.txt' in this directory to know + cannot be easily supported with binfmt_misc. + Read the file ``binfmt_misc.txt`` in this directory to know more about the configuration process. -3) Add the following entries to /etc/rc.local or similar script - to be run at system startup: +3) Add the following entries to ``/etc/rc.local`` or similar script + to be run at system startup:: -# Insert BINFMT_MISC module into the kernel -if [ ! -e /proc/sys/fs/binfmt_misc/register ]; then + # Insert BINFMT_MISC module into the kernel + if [ ! -e /proc/sys/fs/binfmt_misc/register ]; then /sbin/modprobe binfmt_misc # Some distributions, like Fedora Core, perform # the following command automatically when the @@ -43,24 +43,26 @@ if [ ! -e /proc/sys/fs/binfmt_misc/register ]; then # Thus, it is possible that the following line # is not needed at all. mount -t binfmt_misc none /proc/sys/fs/binfmt_misc -fi + fi -# Register support for .NET CLR binaries -if [ -e /proc/sys/fs/binfmt_misc/register ]; then + # Register support for .NET CLR binaries + if [ -e /proc/sys/fs/binfmt_misc/register ]; then # Replace /usr/bin/mono with the correct pathname to # the Mono CLR runtime (usually /usr/local/bin/mono # when compiling from sources or CVS). echo ':CLR:M::MZ::/usr/bin/mono:' > /proc/sys/fs/binfmt_misc/register -else + else echo "No binfmt_misc support" exit 1 -fi + fi -4) Check that .exe binaries can be ran without the need of a - wrapper script, simply by launching the .exe file directly - from a command prompt, for example: +4) Check that ``.exe`` binaries can be ran without the need of a + wrapper script, simply by launching the ``.exe`` file directly + from a command prompt, for example:: /usr/bin/xsd.exe - NOTE: If this fails with a permission denied error, check - that the .exe file has execute permissions. + .. note:: + + If this fails with a permission denied error, check + that the ``.exe`` file has execute permissions. -- cgit v1.2.3 From 503c5bf9fa4622195bef0b46ebcc0ab6afeefed8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 14:02:36 -0300 Subject: Documentation/java.txt: convert to ReST markup - Fix document title; - use quote blocks where needed; - use monotonic fonts for config options and file names; - adjust whitespaces and blank lines; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/java.txt | 244 ++++++++++++++++++++++++++----------------------- 1 file changed, 129 insertions(+), 115 deletions(-) diff --git a/Documentation/java.txt b/Documentation/java.txt index 418020584ccc..ae33d959638c 100644 --- a/Documentation/java.txt +++ b/Documentation/java.txt @@ -1,5 +1,5 @@ - Java(tm) Binary Kernel Support for Linux v1.03 - ---------------------------------------------- +Java(tm) Binary Kernel Support for Linux v1.03 +---------------------------------------------- Linux beats them ALL! While all other OS's are TALKING about direct support of Java Binaries in the OS, Linux is doing it! @@ -19,70 +19,80 @@ other program after you have done the following: as the application itself). 2) You have to compile BINFMT_MISC either as a module or into - the kernel (CONFIG_BINFMT_MISC) and set it up properly. + the kernel (``CONFIG_BINFMT_MISC``) and set it up properly. If you choose to compile it as a module, you will have to insert it manually with modprobe/insmod, as kmod - cannot easily be supported with binfmt_misc. + cannot easily be supported with binfmt_misc. Read the file 'binfmt_misc.txt' in this directory to know more about the configuration process. 3) Add the following configuration items to binfmt_misc - (you should really have read binfmt_misc.txt now): - support for Java applications: + (you should really have read ``binfmt_misc.txt`` now): + support for Java applications:: + ':Java:M::\xca\xfe\xba\xbe::/usr/local/bin/javawrapper:' - support for executable Jar files: + + support for executable Jar files:: + ':ExecutableJAR:E::jar::/usr/local/bin/jarwrapper:' - support for Java Applets: + + support for Java Applets:: + ':Applet:E::html::/usr/bin/appletviewer:' - or the following, if you want to be more selective: + + or the following, if you want to be more selective:: + ':Applet:M:: in the first line - ('<' has to be the first character!) to let this work! + existing html-files to contain ```` in the first line + (``<`` has to be the first character!) to let this work! For the compiled Java programs you need a wrapper script like the following (this is because Java is broken in case of the filename handling), again fix the path names, both in the script and in the above given configuration string. - You, too, need the little program after the script. Compile like - gcc -O2 -o javaclassname javaclassname.c - and stick it to /usr/local/bin. + You, too, need the little program after the script. Compile like:: + + gcc -O2 -o javaclassname javaclassname.c + + and stick it to ``/usr/local/bin``. Both the javawrapper shellscript and the javaclassname program were supplied by Colin J. Watson . -====================== Cut here =================== -#!/bin/bash -# /usr/local/bin/javawrapper - the wrapper for binfmt_misc/java +Javawrapper shell script:: + + #!/bin/bash + # /usr/local/bin/javawrapper - the wrapper for binfmt_misc/java -if [ -z "$1" ]; then + if [ -z "$1" ]; then exec 1>&2 echo Usage: $0 class-file exit 1 -fi + fi -CLASS=$1 -FQCLASS=`/usr/local/bin/javaclassname $1` -FQCLASSN=`echo $FQCLASS | sed -e 's/^.*\.\([^.]*\)$/\1/'` -FQCLASSP=`echo $FQCLASS | sed -e 's-\.-/-g' -e 's-^[^/]*$--' -e 's-/[^/]*$--'` + CLASS=$1 + FQCLASS=`/usr/local/bin/javaclassname $1` + FQCLASSN=`echo $FQCLASS | sed -e 's/^.*\.\([^.]*\)$/\1/'` + FQCLASSP=`echo $FQCLASS | sed -e 's-\.-/-g' -e 's-^[^/]*$--' -e 's-/[^/]*$--'` -# for example: -# CLASS=Test.class -# FQCLASS=foo.bar.Test -# FQCLASSN=Test -# FQCLASSP=foo/bar + # for example: + # CLASS=Test.class + # FQCLASS=foo.bar.Test + # FQCLASSN=Test + # FQCLASSP=foo/bar -unset CLASSBASE + unset CLASSBASE -declare -i LINKLEVEL=0 + declare -i LINKLEVEL=0 -while :; do + while :; do if [ "`basename $CLASS .class`" == "$FQCLASSN" ]; then # See if this directory works straight off cd -L `dirname $CLASS` @@ -119,9 +129,9 @@ while :; do exit 1 fi CLASS=`ls --color=no -l $CLASS | sed -e 's/^.* \([^ ]*\)$/\1/'` -done + done -if [ -z "$CLASSBASE" ]; then + if [ -z "$CLASSBASE" ]; then if [ -z "$FQCLASSP" ]; then GOODNAME=$FQCLASSN.class else @@ -131,24 +141,23 @@ if [ -z "$CLASSBASE" ]; then echo $0: echo " $FQCLASS should be in a file called $GOODNAME" exit 1 -fi + fi -if ! echo $CLASSPATH | grep -q "^\(.*:\)*$CLASSBASE\(:.*\)*"; then + if ! echo $CLASSPATH | grep -q "^\(.*:\)*$CLASSBASE\(:.*\)*"; then # class is not in CLASSPATH, so prepend dir of class to CLASSPATH if [ -z "${CLASSPATH}" ] ; then export CLASSPATH=$CLASSBASE else export CLASSPATH=$CLASSBASE:$CLASSPATH fi -fi + fi -shift -/usr/bin/java $FQCLASS "$@" -====================== Cut here =================== + shift + /usr/bin/java $FQCLASS "$@" +javaclassname.c:: -====================== Cut here =================== -/* javaclassname.c + /* javaclassname.c * * Extracts the class name from a Java class file; intended for use in a Java * wrapper of the type supported by the binfmt_misc option in the Linux kernel. @@ -170,57 +179,57 @@ shift * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ -#include -#include -#include -#include - -/* From Sun's Java VM Specification, as tag entries in the constant pool. */ - -#define CP_UTF8 1 -#define CP_INTEGER 3 -#define CP_FLOAT 4 -#define CP_LONG 5 -#define CP_DOUBLE 6 -#define CP_CLASS 7 -#define CP_STRING 8 -#define CP_FIELDREF 9 -#define CP_METHODREF 10 -#define CP_INTERFACEMETHODREF 11 -#define CP_NAMEANDTYPE 12 -#define CP_METHODHANDLE 15 -#define CP_METHODTYPE 16 -#define CP_INVOKEDYNAMIC 18 - -/* Define some commonly used error messages */ - -#define seek_error() error("%s: Cannot seek\n", program) -#define corrupt_error() error("%s: Class file corrupt\n", program) -#define eof_error() error("%s: Unexpected end of file\n", program) -#define utf8_error() error("%s: Only ASCII 1-255 supported\n", program); - -char *program; - -long *pool; - -u_int8_t read_8(FILE *classfile); -u_int16_t read_16(FILE *classfile); -void skip_constant(FILE *classfile, u_int16_t *cur); -void error(const char *format, ...); -int main(int argc, char **argv); - -/* Reads in an unsigned 8-bit integer. */ -u_int8_t read_8(FILE *classfile) -{ + #include + #include + #include + #include + + /* From Sun's Java VM Specification, as tag entries in the constant pool. */ + + #define CP_UTF8 1 + #define CP_INTEGER 3 + #define CP_FLOAT 4 + #define CP_LONG 5 + #define CP_DOUBLE 6 + #define CP_CLASS 7 + #define CP_STRING 8 + #define CP_FIELDREF 9 + #define CP_METHODREF 10 + #define CP_INTERFACEMETHODREF 11 + #define CP_NAMEANDTYPE 12 + #define CP_METHODHANDLE 15 + #define CP_METHODTYPE 16 + #define CP_INVOKEDYNAMIC 18 + + /* Define some commonly used error messages */ + + #define seek_error() error("%s: Cannot seek\n", program) + #define corrupt_error() error("%s: Class file corrupt\n", program) + #define eof_error() error("%s: Unexpected end of file\n", program) + #define utf8_error() error("%s: Only ASCII 1-255 supported\n", program); + + char *program; + + long *pool; + + u_int8_t read_8(FILE *classfile); + u_int16_t read_16(FILE *classfile); + void skip_constant(FILE *classfile, u_int16_t *cur); + void error(const char *format, ...); + int main(int argc, char **argv); + + /* Reads in an unsigned 8-bit integer. */ + u_int8_t read_8(FILE *classfile) + { int b = fgetc(classfile); if(b == EOF) eof_error(); return (u_int8_t)b; -} + } -/* Reads in an unsigned 16-bit integer. */ -u_int16_t read_16(FILE *classfile) -{ + /* Reads in an unsigned 16-bit integer. */ + u_int16_t read_16(FILE *classfile) + { int b1, b2; b1 = fgetc(classfile); if(b1 == EOF) @@ -229,11 +238,11 @@ u_int16_t read_16(FILE *classfile) if(b2 == EOF) eof_error(); return (u_int16_t)((b1 << 8) | b2); -} + } -/* Reads in a value from the constant pool. */ -void skip_constant(FILE *classfile, u_int16_t *cur) -{ + /* Reads in a value from the constant pool. */ + void skip_constant(FILE *classfile, u_int16_t *cur) + { u_int16_t len; int seekerr = 1; pool[*cur] = ftell(classfile); @@ -270,19 +279,19 @@ void skip_constant(FILE *classfile, u_int16_t *cur) } if(seekerr) seek_error(); -} + } -void error(const char *format, ...) -{ + void error(const char *format, ...) + { va_list ap; va_start(ap, format); vfprintf(stderr, format, ap); va_end(ap); exit(1); -} + } -int main(int argc, char **argv) -{ + int main(int argc, char **argv) + { FILE *classfile; u_int16_t cp_count, i, this_class, classinfo_ptr; u_int8_t length; @@ -349,19 +358,19 @@ int main(int argc, char **argv) free(pool); fclose(classfile); return 0; -} -====================== Cut here =================== + } +jarwrapper:: -====================== Cut here =================== -#!/bin/bash -# /usr/local/java/bin/jarwrapper - the wrapper for binfmt_misc/jar + #!/bin/bash + # /usr/local/java/bin/jarwrapper - the wrapper for binfmt_misc/jar -java -jar $1 -====================== Cut here =================== + java -jar $1 -Now simply chmod +x the .class, .jar and/or .html files you want to execute. +Now simply ``chmod +x`` the ``.class``, ``.jar`` and/or ``.html`` files you +want to execute. + To add a Java program to your path best put a symbolic link to the main .class file into /usr/bin (or another place you like) omitting the .class extension. The directory containing the original .class file will be @@ -369,7 +378,7 @@ added to your CLASSPATH during execution. To test your new setup, enter in the following simple Java app, and name -it "HelloWorld.java": +it "HelloWorld.java":: class HelloWorld { public static void main(String args[]) { @@ -377,23 +386,28 @@ it "HelloWorld.java": } } -Now compile the application with: +Now compile the application with:: + javac HelloWorld.java -Set the executable permissions of the binary file, with: +Set the executable permissions of the binary file, with:: + chmod 755 HelloWorld.class -And then execute it: +And then execute it:: + ./HelloWorld.class -To execute Java Jar files, simple chmod the *.jar files to include -the execution bit, then just do +To execute Java Jar files, simple chmod the ``*.jar`` files to include +the execution bit, then just do:: + ./Application.jar -To execute Java Applets, simple chmod the *.html files to include -the execution bit, then just do +To execute Java Applets, simple chmod the ``*.html`` files to include +the execution bit, then just do:: + ./Applet.html -- cgit v1.2.3 From 9f4b9ec63cff0048aae43b0119e64f10a7887836 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 14:40:40 -0300 Subject: Documentation/oops-tracing.txt: convert to ReST markup - Add a document title; - use .. note:: markup; - use quote blocks where needed; - use monotonic fonts for config options and file names; - adjust whitespaces and blank lines; - replace _foo_ by **foo**; - while here, remove whitespaces at the end of paragraph; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/oops-tracing.txt | 255 ++++++++++++++++++++++------------------- 1 file changed, 138 insertions(+), 117 deletions(-) diff --git a/Documentation/oops-tracing.txt b/Documentation/oops-tracing.txt index f3ac05cc23e4..3e25ea7349ee 100644 --- a/Documentation/oops-tracing.txt +++ b/Documentation/oops-tracing.txt @@ -1,7 +1,13 @@ -NOTE: ksymoops is useless on 2.6. Please use the Oops in its original format -(from dmesg, etc). Ignore any references in this or other docs to "decoding -the Oops" or "running it through ksymoops". If you post an Oops from 2.6 that -has been run through ksymoops, people will just tell you to repost it. +OOPS tracing +============ + +.. note:: + + ``ksymoops`` is useless on 2.6 or upper. Please use the Oops in its original + format (from ``dmesg``, etc). Ignore any references in this or other docs to + "decoding the Oops" or "running it through ksymoops". + If you post an Oops from 2.6+ that has been run through ``ksymoops``, + people will just tell you to repost it. Quick Summary ------------- @@ -12,7 +18,7 @@ If you are unsure send it to the person responsible for the code relevant to what you were doing. If it occurs repeatably try and describe how to recreate it. That's worth even more than the oops. -If you are totally stumped as to whom to send the report, send it to +If you are totally stumped as to whom to send the report, send it to linux-kernel@vger.kernel.org. Thanks for your help in making Linux as stable as humanly possible. @@ -20,24 +26,25 @@ Where is the Oops? ---------------------- Normally the Oops text is read from the kernel buffers by klogd and -handed to syslogd which writes it to a syslog file, typically -/var/log/messages (depends on /etc/syslog.conf). Sometimes klogd dies, -in which case you can run dmesg > file to read the data from the kernel -buffers and save it. Or you can cat /proc/kmsg > file, however you -have to break in to stop the transfer, kmsg is a "never ending file". +handed to ``syslogd`` which writes it to a syslog file, typically +``/var/log/messages`` (depends on ``/etc/syslog.conf``). Sometimes ``klogd`` +dies, in which case you can run ``dmesg > file`` to read the data from the +kernel buffers and save it. Or you can ``cat /proc/kmsg > file``, however you +have to break in to stop the transfer, ``kmsg`` is a "never ending file". If the machine has crashed so badly that you cannot enter commands or -the disk is not available then you have three options :- +the disk is not available then you have three options : (1) Hand copy the text from the screen and type it in after the machine has restarted. Messy but it is the only option if you have not planned for a crash. Alternatively, you can take a picture of the screen with a digital camera - not nice, but better than nothing. If the messages scroll off the top of the console, you - may find that booting with a higher resolution (eg, vga=791) - will allow you to read more of the text. (Caveat: This needs vesafb, + may find that booting with a higher resolution (eg, ``vga=791``) + will allow you to read more of the text. (Caveat: This needs ``vesafb``, so won't help for 'early' oopses) -(2) Boot with a serial console (see Documentation/serial-console.txt), +(2) Boot with a serial console (see + :ref:`Documentation/serial-console.txt `), run a null modem to a second machine and capture the output there using your favourite communication program. Minicom works well. @@ -49,117 +56,126 @@ the disk is not available then you have three options :- Full Information ---------------- -NOTE: the message from Linus below applies to 2.4 kernel. I have preserved it -for historical reasons, and because some of the information in it still -applies. Especially, please ignore any references to ksymoops. +.. note:: + + the message from Linus below applies to 2.4 kernel. I have preserved it + for historical reasons, and because some of the information in it still + applies. Especially, please ignore any references to ksymoops. -From: Linus Torvalds + :: -How to track down an Oops.. [originally a mail to linux-kernel] + From: Linus Torvalds -The main trick is having 5 years of experience with those pesky oops -messages ;-) + How to track down an Oops.. [originally a mail to linux-kernel] -Actually, there are things you can do that make this easier. I have two -separate approaches: + The main trick is having 5 years of experience with those pesky oops + messages ;-) + +Actually, there are things you can do that make this easier. I have two +separate approaches:: gdb /usr/src/linux/vmlinux gdb> disassemble -That's the easy way to find the problem, at least if the bug-report is -well made (like this one was - run through ksymoops to get the -information of which function and the offset in the function that it +That's the easy way to find the problem, at least if the bug-report is +well made (like this one was - run through ``ksymoops`` to get the +information of which function and the offset in the function that it happened in). -Oh, it helps if the report happens on a kernel that is compiled with the +Oh, it helps if the report happens on a kernel that is compiled with the same compiler and similar setups. -The other thing to do is disassemble the "Code:" part of the bug report: +The other thing to do is disassemble the "Code:" part of the bug report: ksymoops will do this too with the correct tools, but if you don't have -the tools you can just do a silly program: +the tools you can just do a silly program:: char str[] = "\xXX\xXX\xXX..."; main(){} -and compile it with gcc -g and then do "disassemble str" (where the "XX" -stuff are the values reported by the Oops - you can just cut-and-paste -and do a replace of spaces to "\x" - that's what I do, as I'm too lazy +and compile it with ``gcc -g`` and then do ``disassemble str`` (where the ``XX`` +stuff are the values reported by the Oops - you can just cut-and-paste +and do a replace of spaces to ``\x`` - that's what I do, as I'm too lazy to write a program to automate this all). -Alternatively, you can use the shell script in scripts/decodecode. -Its usage is: decodecode < oops.txt +Alternatively, you can use the shell script in ``scripts/decodecode``. +Its usage is:: + + decodecode < oops.txt The hex bytes that follow "Code:" may (in some architectures) have a series of bytes that precede the current instruction pointer as well as bytes at and following the current instruction pointer. In some cases, one instruction -byte or word is surrounded by <> or (), as in "<86>" or "(f00d)". These -<> or () markings indicate the current instruction pointer. Example from -i386, split into multiple lines for readability: +byte or word is surrounded by ``<>`` or ``()``, as in ``<86>`` or ``(f00d)``. +These ``<>`` or ``()`` markings indicate the current instruction pointer. + +Example from i386, split into multiple lines for readability:: -Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1 -64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54 -7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0 + Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1 + 64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54 + 7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0 -Finally, if you want to see where the code comes from, you can do +Finally, if you want to see where the code comes from, you can do:: cd /usr/src/linux make fs/buffer.s # or whatever file the bug happened in -and then you get a better idea of what happens than with the gdb +and then you get a better idea of what happens than with the gdb disassembly. -Now, the trick is just then to combine all the data you have: the C -sources (and general knowledge of what it _should_ do), the assembly -listing and the code disassembly (and additionally the register dump you -also get from the "oops" message - that can be useful to see _what_ the -corrupted pointers were, and when you have the assembler listing you can -also match the other registers to whatever C expressions they were used +Now, the trick is just then to combine all the data you have: the C +sources (and general knowledge of what it **should** do), the assembly +listing and the code disassembly (and additionally the register dump you +also get from the "oops" message - that can be useful to see **what** the +corrupted pointers were, and when you have the assembler listing you can +also match the other registers to whatever C expressions they were used for). -Essentially, you just look at what doesn't match (in this case it was the -"Code" disassembly that didn't match with what the compiler generated). -Then you need to find out _why_ they don't match. Often it's simple - you -see that the code uses a NULL pointer and then you look at the code and -wonder how the NULL pointer got there, and if it's a valid thing to do +Essentially, you just look at what doesn't match (in this case it was the +"Code" disassembly that didn't match with what the compiler generated). +Then you need to find out **why** they don't match. Often it's simple - you +see that the code uses a NULL pointer and then you look at the code and +wonder how the NULL pointer got there, and if it's a valid thing to do you just check against it.. -Now, if somebody gets the idea that this is time-consuming and requires -some small amount of concentration, you're right. Which is why I will -mostly just ignore any panic reports that don't have the symbol table -info etc looked up: it simply gets too hard to look it up (I have some -programs to search for specific patterns in the kernel code segment, and -sometimes I have been able to look up those kinds of panics too, but -that really requires pretty good knowledge of the kernel just to be able +Now, if somebody gets the idea that this is time-consuming and requires +some small amount of concentration, you're right. Which is why I will +mostly just ignore any panic reports that don't have the symbol table +info etc looked up: it simply gets too hard to look it up (I have some +programs to search for specific patterns in the kernel code segment, and +sometimes I have been able to look up those kinds of panics too, but +that really requires pretty good knowledge of the kernel just to be able to pick out the right sequences etc..) -_Sometimes_ it happens that I just see the disassembled code sequence -from the panic, and I know immediately where it's coming from. That's when +**Sometimes** it happens that I just see the disassembled code sequence +from the panic, and I know immediately where it's coming from. That's when I get worried that I've been doing this for too long ;-) Linus --------------------------------------------------------------------------- -Notes on Oops tracing with klogd: + +Notes on Oops tracing with ``klogd`` +------------------------------------ In order to help Linus and the other kernel developers there has been -substantial support incorporated into klogd for processing protection +substantial support incorporated into ``klogd`` for processing protection faults. In order to have full support for address resolution at least -version 1.3-pl3 of the sysklogd package should be used. +version 1.3-pl3 of the ``sysklogd`` package should be used. -When a protection fault occurs the klogd daemon automatically +When a protection fault occurs the ``klogd`` daemon automatically translates important addresses in the kernel log messages to their symbolic equivalents. This translated kernel message is then -forwarded through whatever reporting mechanism klogd is using. The +forwarded through whatever reporting mechanism ``klogd`` is using. The protection fault message can be simply cut out of the message files and forwarded to the kernel developers. -Two types of address resolution are performed by klogd. The first is +Two types of address resolution are performed by ``klogd``. The first is static translation and the second is dynamic translation. Static translation uses the System.map file in much the same manner that -ksymoops does. In order to do static translation the klogd daemon +ksymoops does. In order to do static translation the ``klogd`` daemon must be able to find a system map file at daemon initialization time. -See the klogd man page for information on how klogd searches for map +See the klogd man page for information on how ``klogd`` searches for map files. Dynamic address translation is important when kernel loadable modules @@ -178,101 +194,106 @@ information available if the developer of the loadable module chose to export symbol information from the module. Since the kernel module environment can be dynamic there must be a -mechanism for notifying the klogd daemon when a change in module +mechanism for notifying the ``klogd`` daemon when a change in module environment occurs. There are command line options available which allow klogd to signal the currently executing daemon that symbol -information should be refreshed. See the klogd manual page for more +information should be refreshed. See the ``klogd`` manual page for more information. A patch is included with the sysklogd distribution which modifies the -modules-2.0.0 package to automatically signal klogd whenever a module +``modules-2.0.0`` package to automatically signal klogd whenever a module is loaded or unloaded. Applying this patch provides essentially seamless support for debugging protection faults which occur with kernel loadable modules. The following is an example of a protection fault in a loadable module -processed by klogd: ---------------------------------------------------------------------------- -Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc -Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 -Aug 29 09:51:01 blizard kernel: *pde = 00000000 -Aug 29 09:51:01 blizard kernel: Oops: 0002 -Aug 29 09:51:01 blizard kernel: CPU: 0 -Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] -Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 -Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c -Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c -Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 -Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) -Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 -Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 -Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 -Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] -Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 +processed by ``klogd``:: + + Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc + Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 + Aug 29 09:51:01 blizard kernel: *pde = 00000000 + Aug 29 09:51:01 blizard kernel: Oops: 0002 + Aug 29 09:51:01 blizard kernel: CPU: 0 + Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] + Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 + Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c + Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c + Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 + Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) + Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 + Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 + Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 + Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] + Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 + --------------------------------------------------------------------------- -Dr. G.W. Wettstein Oncology Research Div. Computing Facility -Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com -820 4th St. N. -Fargo, ND 58122 -Phone: 701-234-7556 +:: + + Dr. G.W. Wettstein Oncology Research Div. Computing Facility + Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com + 820 4th St. N. + Fargo, ND 58122 + Phone: 701-234-7556 --------------------------------------------------------------------------- -Tainted kernels: -Some oops reports contain the string 'Tainted: ' after the program +Tainted kernels +--------------- + +Some oops reports contain the string **'Tainted: '** after the program counter. This indicates that the kernel has been tainted by some mechanism. The string is followed by a series of position-sensitive characters, each representing a particular tainted value. - 1: 'G' if all modules loaded have a GPL or compatible license, 'P' if + 1) 'G' if all modules loaded have a GPL or compatible license, 'P' if any proprietary module has been loaded. Modules without a MODULE_LICENSE or with a MODULE_LICENSE that is not recognised by insmod as GPL compatible are assumed to be proprietary. - 2: 'F' if any module was force loaded by "insmod -f", ' ' if all + 2) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all modules were loaded normally. - 3: 'S' if the oops occurred on an SMP kernel running on hardware that + 3) ``S`` if the oops occurred on an SMP kernel running on hardware that hasn't been certified as safe to run multiprocessor. Currently this occurs only on various Athlons that are not SMP capable. - 4: 'R' if a module was force unloaded by "rmmod -f", ' ' if all + 4) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all modules were unloaded normally. - 5: 'M' if any processor has reported a Machine Check Exception, - ' ' if no Machine Check Exceptions have occurred. + 5) ``M`` if any processor has reported a Machine Check Exception, + ``' '`` if no Machine Check Exceptions have occurred. - 6: 'B' if a page-release function has found a bad page reference or + 6) ``B`` if a page-release function has found a bad page reference or some unexpected page flags. - 7: 'U' if a user or user application specifically requested that the - Tainted flag be set, ' ' otherwise. + 7) ``U`` if a user or user application specifically requested that the + Tainted flag be set, ``' '`` otherwise. - 8: 'D' if the kernel has died recently, i.e. there was an OOPS or BUG. + 8) ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG. - 9: 'A' if the ACPI table has been overridden. + 9) ``A`` if the ACPI table has been overridden. - 10: 'W' if a warning has previously been issued by the kernel. + 10) ``W`` if a warning has previously been issued by the kernel. (Though some warnings may set more specific taint flags.) - 11: 'C' if a staging driver has been loaded. + 11) ``C`` if a staging driver has been loaded. - 12: 'I' if the kernel is working around a severe bug in the platform + 12) ``I`` if the kernel is working around a severe bug in the platform firmware (BIOS or similar). - 13: 'O' if an externally-built ("out-of-tree") module has been loaded. + 13) ``O`` if an externally-built ("out-of-tree") module has been loaded. - 14: 'E' if an unsigned module has been loaded in a kernel supporting + 14) ``E`` if an unsigned module has been loaded in a kernel supporting module signature. - 15: 'L' if a soft lockup has previously occurred on the system. + 15) ``L`` if a soft lockup has previously occurred on the system. - 16: 'K' if the kernel has been live patched. + 16) ``K`` if the kernel has been live patched. -The primary reason for the 'Tainted: ' string is to tell kernel +The primary reason for the **'Tainted: '** string is to tell kernel debuggers if this is a clean kernel or if anything unusual has occurred. Tainting is permanent: even if an offending module is unloaded, the tainted value remains to indicate that the kernel is not -- cgit v1.2.3 From e095f0711b49269e34941098b9bd60a87eb50866 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 15:07:00 -0300 Subject: Documentation/parport.txt: convert to ReST markup - Add a document title; - use quote blocks where needed; - convert parameters to a nested table; - use monotonic fonts for config options and file names; - adjust whitespaces and blank lines; - replace _foo_ by **foo**; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/parport.txt | 294 ++++++++++++++++++++++++---------------------- 1 file changed, 151 insertions(+), 143 deletions(-) diff --git a/Documentation/parport.txt b/Documentation/parport.txt index c208e4366c03..3273ce79f9e3 100644 --- a/Documentation/parport.txt +++ b/Documentation/parport.txt @@ -1,15 +1,18 @@ -The `parport' code provides parallel-port support under Linux. This +Parport ++++++++ + +The ``parport`` code provides parallel-port support under Linux. This includes the ability to share one port between multiple device drivers. -You can pass parameters to the parport code to override its automatic +You can pass parameters to the ``parport`` code to override its automatic detection of your hardware. This is particularly useful if you want to use IRQs, since in general these can't be autoprobed successfully. -By default IRQs are not used even if they _can_ be probed. This is +By default IRQs are not used even if they **can** be probed. This is because there are a lot of people using the same IRQ for their parallel port and a sound card or network card. -The parport code is split into two parts: generic (which deals with +The ``parport`` code is split into two parts: generic (which deals with port-sharing) and architecture-dependent (which deals with actually using the port). @@ -17,21 +20,21 @@ using the port). Parport as modules ================== -If you load the parport code as a module, say +If you load the `parport`` code as a module, say:: # insmod parport -to load the generic parport code. You then must load the -architecture-dependent code with (for example): +to load the generic ``parport`` code. You then must load the +architecture-dependent code with (for example):: # insmod parport_pc io=0x3bc,0x378,0x278 irq=none,7,auto -to tell the parport code that you want three PC-style ports, one at +to tell the ``parport`` code that you want three PC-style ports, one at 0x3bc with no IRQ, one at 0x378 using IRQ 7, and one at 0x278 with an -auto-detected IRQ. Currently, PC-style (parport_pc), Sun `bpp', +auto-detected IRQ. Currently, PC-style (``parport_pc``), Sun ``bpp``, Amiga, Atari, and MFC3 hardware is supported. -PCI parallel I/O card support comes from parport_pc. Base I/O +PCI parallel I/O card support comes from ``parport_pc``. Base I/O addresses should not be specified for supported PCI cards since they are automatically detected. @@ -40,151 +43,154 @@ modprobe -------- If you use modprobe , you will find it useful to add lines as below to a -configuration file in /etc/modprobe.d/ directory:. +configuration file in /etc/modprobe.d/ directory:: alias parport_lowlevel parport_pc options parport_pc io=0x378,0x278 irq=7,auto -modprobe will load parport_pc (with the options "io=0x378,0x278 irq=7,auto") -whenever a parallel port device driver (such as lp) is loaded. +modprobe will load ``parport_pc`` (with the options ``io=0x378,0x278 irq=7,auto``) +whenever a parallel port device driver (such as ``lp``) is loaded. Note that these are example lines only! You shouldn't in general need -to specify any options to parport_pc in order to be able to use a +to specify any options to ``parport_pc`` in order to be able to use a parallel port. Parport probe [optional] -------------- +------------------------ -In 2.2 kernels there was a module called parport_probe, which was used +In 2.2 kernels there was a module called ``parport_probe``, which was used for collecting IEEE 1284 device ID information. This has now been enhanced and now lives with the IEEE 1284 support. When a parallel port is detected, the devices that are connected to it are analysed, -and information is logged like this: +and information is logged like this:: parport0: Printer, BJC-210 (Canon) -The probe information is available from files in /proc/sys/dev/parport/. +The probe information is available from files in ``/proc/sys/dev/parport/``. Parport linked into the kernel statically ========================================= -If you compile the parport code into the kernel, then you can use +If you compile the ``parport`` code into the kernel, then you can use kernel boot parameters to get the same effect. Add something like the -following to your LILO command line: +following to your LILO command line:: parport=0x3bc parport=0x378,7 parport=0x278,auto,nofifo -You can have many `parport=...' statements, one for each port you want -to add. Adding `parport=0' to the kernel command-line will disable -parport support entirely. Adding `parport=auto' to the kernel -command-line will make parport use any IRQ lines or DMA channels that +You can have many ``parport=...`` statements, one for each port you want +to add. Adding ``parport=0`` to the kernel command-line will disable +parport support entirely. Adding ``parport=auto`` to the kernel +command-line will make ``parport`` use any IRQ lines or DMA channels that it auto-detects. Files in /proc ============== -If you have configured the /proc filesystem into your kernel, you will -see a new directory entry: /proc/sys/dev/parport. In there will be a +If you have configured the ``/proc`` filesystem into your kernel, you will +see a new directory entry: ``/proc/sys/dev/parport``. In there will be a directory entry for each parallel port for which parport is configured. In each of those directories are a collection of files describing that parallel port. -The /proc/sys/dev/parport directory tree looks like: - -parport -|-- default -| |-- spintime -| `-- timeslice -|-- parport0 -| |-- autoprobe -| |-- autoprobe0 -| |-- autoprobe1 -| |-- autoprobe2 -| |-- autoprobe3 -| |-- devices -| | |-- active -| | `-- lp -| | `-- timeslice -| |-- base-addr -| |-- irq -| |-- dma -| |-- modes -| `-- spintime -`-- parport1 - |-- autoprobe - |-- autoprobe0 - |-- autoprobe1 - |-- autoprobe2 - |-- autoprobe3 - |-- devices - | |-- active - | `-- ppa - | `-- timeslice - |-- base-addr - |-- irq - |-- dma - |-- modes - `-- spintime - - -File: Contents: - -devices/active A list of the device drivers using that port. A "+" - will appear by the name of the device currently using - the port (it might not appear against any). The - string "none" means that there are no device drivers - using that port. - -base-addr Parallel port's base address, or addresses if the port - has more than one in which case they are separated - with tabs. These values might not have any sensible - meaning for some ports. - -irq Parallel port's IRQ, or -1 if none is being used. - -dma Parallel port's DMA channel, or -1 if none is being - used. - -modes Parallel port's hardware modes, comma-separated, - meaning: - - PCSPP PC-style SPP registers are available. - TRISTATE Port is bidirectional. - COMPAT Hardware acceleration for printers is - available and will be used. - EPP Hardware acceleration for EPP protocol - is available and will be used. - ECP Hardware acceleration for ECP protocol - is available and will be used. - DMA DMA is available and will be used. - - Note that the current implementation will only take - advantage of COMPAT and ECP modes if it has an IRQ - line to use. - -autoprobe Any IEEE-1284 device ID information that has been - acquired from the (non-IEEE 1284.3) device. - -autoprobe[0-3] IEEE 1284 device ID information retrieved from - daisy-chain devices that conform to IEEE 1284.3. - -spintime The number of microseconds to busy-loop while waiting - for the peripheral to respond. You might find that - adjusting this improves performance, depending on your - peripherals. This is a port-wide setting, i.e. it - applies to all devices on a particular port. - -timeslice The number of milliseconds that a device driver is - allowed to keep a port claimed for. This is advisory, - and driver can ignore it if it must. - -default/* The defaults for spintime and timeslice. When a new - port is registered, it picks up the default spintime. - When a new device is registered, it picks up the - default timeslice. +The ``/proc/sys/dev/parport`` directory tree looks like:: + + parport + |-- default + | |-- spintime + | `-- timeslice + |-- parport0 + | |-- autoprobe + | |-- autoprobe0 + | |-- autoprobe1 + | |-- autoprobe2 + | |-- autoprobe3 + | |-- devices + | | |-- active + | | `-- lp + | | `-- timeslice + | |-- base-addr + | |-- irq + | |-- dma + | |-- modes + | `-- spintime + `-- parport1 + |-- autoprobe + |-- autoprobe0 + |-- autoprobe1 + |-- autoprobe2 + |-- autoprobe3 + |-- devices + | |-- active + | `-- ppa + | `-- timeslice + |-- base-addr + |-- irq + |-- dma + |-- modes + `-- spintime + +======================= ======================================================= +File Contents +======================= ======================================================= +``devices/active`` A list of the device drivers using that port. A "+" + will appear by the name of the device currently using + the port (it might not appear against any). The + string "none" means that there are no device drivers + using that port. + +``base-addr`` Parallel port's base address, or addresses if the port + has more than one in which case they are separated + with tabs. These values might not have any sensible + meaning for some ports. + +``irq`` Parallel port's IRQ, or -1 if none is being used. + +``dma`` Parallel port's DMA channel, or -1 if none is being + used. + +``modes`` Parallel port's hardware modes, comma-separated, + meaning: + + =============== ======================================= + PCSPP PC-style SPP registers are available. + TRISTATE Port is bidirectional. + COMPAT Hardware acceleration for printers is + available and will be used. + EPP Hardware acceleration for EPP protocol + is available and will be used. + ECP Hardware acceleration for ECP protocol + is available and will be used. + DMA DMA is available and will be used. + =============== ======================================= + + Note that the current implementation will only take + advantage of COMPAT and ECP modes if it has an IRQ + line to use. + +``autoprobe`` Any IEEE-1284 device ID information that has been + acquired from the (non-IEEE 1284.3) device. + +``autoprobe[0-3]`` IEEE 1284 device ID information retrieved from + daisy-chain devices that conform to IEEE 1284.3. + +``spintime`` The number of microseconds to busy-loop while waiting + for the peripheral to respond. You might find that + adjusting this improves performance, depending on your + peripherals. This is a port-wide setting, i.e. it + applies to all devices on a particular port. + +``timeslice`` The number of milliseconds that a device driver is + allowed to keep a port claimed for. This is advisory, + and driver can ignore it if it must. + +``default/*`` The defaults for spintime and timeslice. When a new + port is registered, it picks up the default spintime. + When a new device is registered, it picks up the + default timeslice. +======================= ======================================================= Device drivers ============== @@ -193,31 +199,31 @@ Once the parport code is initialised, you can attach device drivers to specific ports. Normally this happens automatically; if the lp driver is loaded it will create one lp device for each port found. You can override this, though, by using parameters either when you load the lp -driver: +driver:: # insmod lp parport=0,2 -or on the LILO command line: +or on the LILO command line:: lp=parport0 lp=parport2 -Both the above examples would inform lp that you want /dev/lp0 to be -the first parallel port, and /dev/lp1 to be the _third_ parallel port, +Both the above examples would inform lp that you want ``/dev/lp0`` to be +the first parallel port, and /dev/lp1 to be the **third** parallel port, with no lp device associated with the second port (parport1). Note that this is different to the way older kernels worked; there used to be a static association between the I/O port address and the device -name, so /dev/lp0 was always the port at 0x3bc. This is no longer the -case - if you only have one port, it will default to being /dev/lp0, +name, so ``/dev/lp0`` was always the port at 0x3bc. This is no longer the +case - if you only have one port, it will default to being ``/dev/lp0``, regardless of base address. Also: * If you selected the IEEE 1284 support at compile time, you can say - `lp=auto' on the kernel command line, and lp will create devices + ``lp=auto`` on the kernel command line, and lp will create devices only for those ports that seem to have printers attached. - * If you give PLIP the `timid' parameter, either with `plip=timid' on - the command line, or with `insmod plip timid=1' when using modules, + * If you give PLIP the ``timid`` parameter, either with ``plip=timid`` on + the command line, or with ``insmod plip timid=1`` when using modules, it will avoid any ports that seem to be in use by other devices. * IRQ autoprobing works only for a few port types at the moment. @@ -229,39 +235,41 @@ If you are having problems printing, please go through these steps to try to narrow down where the problem area is. When reporting problems with parport, really you need to give all of -the messages that parport_pc spits out when it initialises. There are +the messages that ``parport_pc`` spits out when it initialises. There are several code paths: -o polling -o interrupt-driven, protocol in software -o interrupt-driven, protocol in hardware using PIO -o interrupt-driven, protocol in hardware using DMA +- polling +- interrupt-driven, protocol in software +- interrupt-driven, protocol in hardware using PIO +- interrupt-driven, protocol in hardware using DMA -The kernel messages that parport_pc logs give an indication of which +The kernel messages that ``parport_pc`` logs give an indication of which code path is being used. (They could be a lot better actually..) For normal printer protocol, having IEEE 1284 modes enabled or not should not make a difference. To turn off the 'protocol in hardware' code paths, disable -CONFIG_PARPORT_PC_FIFO. Note that when they are enabled they are not -necessarily _used_; it depends on whether the hardware is available, +``CONFIG_PARPORT_PC_FIFO``. Note that when they are enabled they are not +necessarily **used**; it depends on whether the hardware is available, enabled by the BIOS, and detected by the driver. -So, to start with, disable CONFIG_PARPORT_PC_FIFO, and load parport_pc -with 'irq=none'. See if printing works then. It really should, +So, to start with, disable ``CONFIG_PARPORT_PC_FIFO``, and load ``parport_pc`` +with ``irq=none``. See if printing works then. It really should, because this is the simplest code path. -If that works fine, try with 'io=0x378 irq=7' (adjust for your +If that works fine, try with ``io=0x378 irq=7`` (adjust for your hardware), to make it use interrupt-driven in-software protocol. -If _that_ works fine, then one of the hardware modes isn't working -right. Enable CONFIG_PARPORT_PC_FIFO (no, it isn't a module option, +If **that** works fine, then one of the hardware modes isn't working +right. Enable ``CONFIG_FIFO`` (no, it isn't a module option, and yes, it should be), set the port to ECP mode in the BIOS and note -the DMA channel, and try with: +the DMA channel, and try with:: io=0x378 irq=7 dma=none (for PIO) io=0x378 irq=7 dma=3 (for DMA) --- + +---------- + philb@gnu.org tim@cyberelk.net -- cgit v1.2.3 From b2777b650c5073010adea8ec2bb38eaad1cf800a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 15:24:07 -0300 Subject: Documentation/ramoops.txt: convert it to ReST format - Fix document title; - use quote blocks where needed; - use monotonic fonts for config options and file names; - adjust whitespaces and blank lines; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/ramoops.txt | 88 ++++++++++++++++++++++++++--------------------- 1 file changed, 48 insertions(+), 40 deletions(-) diff --git a/Documentation/ramoops.txt b/Documentation/ramoops.txt index 26b9f31cf65a..7eaf1e71c083 100644 --- a/Documentation/ramoops.txt +++ b/Documentation/ramoops.txt @@ -5,34 +5,37 @@ Sergiu Iordache Updated: 17 November 2011 -0. Introduction +Introduction +------------ Ramoops is an oops/panic logger that writes its logs to RAM before the system crashes. It works by logging oopses and panics in a circular buffer. Ramoops needs a system with persistent RAM so that the content of that area can survive after a restart. -1. Ramoops concepts +Ramoops concepts +---------------- Ramoops uses a predefined memory area to store the dump. The start and size and type of the memory area are set using three variables: - * "mem_address" for the start - * "mem_size" for the size. The memory size will be rounded down to a - power of two. - * "mem_type" to specifiy if the memory type (default is pgprot_writecombine). - -Typically the default value of mem_type=0 should be used as that sets the pstore -mapping to pgprot_writecombine. Setting mem_type=1 attempts to use -pgprot_noncached, which only works on some platforms. This is because pstore + + * ``mem_address`` for the start + * ``mem_size`` for the size. The memory size will be rounded down to a + power of two. + * ``mem_type`` to specifiy if the memory type (default is pgprot_writecombine). + +Typically the default value of ``mem_type=0`` should be used as that sets the pstore +mapping to pgprot_writecombine. Setting ``mem_type=1`` attempts to use +``pgprot_noncached``, which only works on some platforms. This is because pstore depends on atomic operations. At least on ARM, pgprot_noncached causes the memory to be mapped strongly ordered, and atomic operations on strongly ordered memory are implementation defined, and won't work on many ARMs such as omaps. -The memory area is divided into "record_size" chunks (also rounded down to -power of two) and each oops/panic writes a "record_size" chunk of +The memory area is divided into ``record_size`` chunks (also rounded down to +power of two) and each oops/panic writes a ``record_size`` chunk of information. -Dumping both oopses and panics can be done by setting 1 in the "dump_oops" +Dumping both oopses and panics can be done by setting 1 in the ``dump_oops`` variable while setting 0 in that variable dumps only the panics. The module uses a counter to record multiple dumps but the counter gets reset @@ -43,7 +46,8 @@ This might be useful when a hardware reset was used to bring the machine back to life (i.e. a watchdog triggered). In such cases, RAM may be somewhat corrupt, but usually it is restorable. -2. Setting the parameters +Setting the parameters +---------------------- Setting the ramoops parameters can be done in several different manners: @@ -52,12 +56,13 @@ Setting the ramoops parameters can be done in several different manners: boot and then use the reserved memory for ramoops. For example, assuming a machine with > 128 MB of memory, the following kernel command line will tell the kernel to use only the first 128 MB of memory, and place ECC-protected - ramoops region at 128 MB boundary: - "mem=128M ramoops.mem_address=0x8000000 ramoops.ecc=1" + ramoops region at 128 MB boundary:: + + mem=128M ramoops.mem_address=0x8000000 ramoops.ecc=1 B. Use Device Tree bindings, as described in - Documentation/device-tree/bindings/reserved-memory/ramoops.txt. - For example: + ``Documentation/device-tree/bindings/reserved-memory/ramoops.txt``. + For example:: reserved-memory { #address-cells = <2>; @@ -73,60 +78,63 @@ Setting the ramoops parameters can be done in several different manners: }; C. Use a platform device and set the platform data. The parameters can then - be set through that platform data. An example of doing that is: + be set through that platform data. An example of doing that is:: -#include -[...] + #include + [...] -static struct ramoops_platform_data ramoops_data = { + static struct ramoops_platform_data ramoops_data = { .mem_size = <...>, .mem_address = <...>, .mem_type = <...>, .record_size = <...>, .dump_oops = <...>, .ecc = <...>, -}; + }; -static struct platform_device ramoops_dev = { + static struct platform_device ramoops_dev = { .name = "ramoops", .dev = { .platform_data = &ramoops_data, }, -}; + }; -[... inside a function ...] -int ret; + [... inside a function ...] + int ret; -ret = platform_device_register(&ramoops_dev); -if (ret) { + ret = platform_device_register(&ramoops_dev); + if (ret) { printk(KERN_ERR "unable to register platform device\n"); return ret; -} + } You can specify either RAM memory or peripheral devices' memory. However, when specifying RAM, be sure to reserve the memory by issuing memblock_reserve() -very early in the architecture code, e.g.: +very early in the architecture code, e.g.:: -#include + #include -memblock_reserve(ramoops_data.mem_address, ramoops_data.mem_size); + memblock_reserve(ramoops_data.mem_address, ramoops_data.mem_size); -3. Dump format +Dump format +----------- -The data dump begins with a header, currently defined as "====" followed by a +The data dump begins with a header, currently defined as ``====`` followed by a timestamp and a new line. The dump then continues with the actual data. -4. Reading the data +Reading the data +---------------- The dump data can be read from the pstore filesystem. The format for these -files is "dmesg-ramoops-N", where N is the record number in memory. To delete +files is ``dmesg-ramoops-N``, where N is the record number in memory. To delete a stored record from RAM, simply unlink the respective pstore file. -5. Persistent function tracing +Persistent function tracing +--------------------------- Persistent function tracing might be useful for debugging software or hardware -related hangs. The functions call chain log is stored in a "ftrace-ramoops" -file. Here is an example of usage: +related hangs. The functions call chain log is stored in a ``ftrace-ramoops`` +file. Here is an example of usage:: # mount -t debugfs debugfs /sys/kernel/debug/ # echo 1 > /sys/kernel/debug/pstore/record_ftrace -- cgit v1.2.3 From 3177ae4a1034482efe2c3eef5ab9988d050c5b4f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 15:44:01 -0300 Subject: Documentation/sysfs-rules.txt: convert it to ReST markup - Fix document title; - use quote blocks where needed; - use monotonic fonts for config options and file names; - adjust whitespaces and blank lines; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sysfs-rules.txt | 230 ++++++++++++++++++++++-------------------- 1 file changed, 119 insertions(+), 111 deletions(-) diff --git a/Documentation/sysfs-rules.txt b/Documentation/sysfs-rules.txt index ce60ffa94d2d..04bdd52cba1d 100644 --- a/Documentation/sysfs-rules.txt +++ b/Documentation/sysfs-rules.txt @@ -1,4 +1,5 @@ Rules on how to access information in the Linux kernel sysfs +============================================================ The kernel-exported sysfs exports internal kernel implementation details and depends on internal kernel structures and layout. It is agreed upon @@ -18,36 +19,38 @@ the following rules and then your programs should work with future versions of the sysfs interface. - Do not use libsysfs - It makes assumptions about sysfs which are not true. Its API does not - offer any abstraction, it exposes all the kernel driver-core - implementation details in its own API. Therefore it is not better than - reading directories and opening the files yourself. - Also, it is not actively maintained, in the sense of reflecting the - current kernel development. The goal of providing a stable interface - to sysfs has failed; it causes more problems than it solves. It - violates many of the rules in this document. - -- sysfs is always at /sys - Parsing /proc/mounts is a waste of time. Other mount points are a - system configuration bug you should not try to solve. For test cases, - possibly support a SYSFS_PATH environment variable to overwrite the - application's behavior, but never try to search for sysfs. Never try - to mount it, if you are not an early boot script. + It makes assumptions about sysfs which are not true. Its API does not + offer any abstraction, it exposes all the kernel driver-core + implementation details in its own API. Therefore it is not better than + reading directories and opening the files yourself. + Also, it is not actively maintained, in the sense of reflecting the + current kernel development. The goal of providing a stable interface + to sysfs has failed; it causes more problems than it solves. It + violates many of the rules in this document. + +- sysfs is always at ``/sys`` + Parsing ``/proc/mounts`` is a waste of time. Other mount points are a + system configuration bug you should not try to solve. For test cases, + possibly support a ``SYSFS_PATH`` environment variable to overwrite the + application's behavior, but never try to search for sysfs. Never try + to mount it, if you are not an early boot script. - devices are only "devices" - There is no such thing like class-, bus-, physical devices, - interfaces, and such that you can rely on in userspace. Everything is - just simply a "device". Class-, bus-, physical, ... types are just - kernel implementation details which should not be expected by - applications that look for devices in sysfs. - - The properties of a device are: - o devpath (/devices/pci0000:00/0000:00:1d.1/usb2/2-2/2-2:1.0) + There is no such thing like class-, bus-, physical devices, + interfaces, and such that you can rely on in userspace. Everything is + just simply a "device". Class-, bus-, physical, ... types are just + kernel implementation details which should not be expected by + applications that look for devices in sysfs. + + The properties of a device are: + + - devpath (``/devices/pci0000:00/0000:00:1d.1/usb2/2-2/2-2:1.0``) + - identical to the DEVPATH value in the event sent from the kernel at device creation and removal - the unique key to the device at that point in time - the kernel's path to the device directory without the leading - /sys, and always starting with a slash + ``/sys``, and always starting with a slash - all elements of a devpath must be real directories. Symlinks pointing to /sys/devices must always be resolved to their real target and the target path must be used to access the device. @@ -56,17 +59,20 @@ versions of the sysfs interface. - using or exposing symlink values as elements in a devpath string is a bug in the application - o kernel name (sda, tty, 0000:00:1f.2, ...) + - kernel name (``sda``, ``tty``, ``0000:00:1f.2``, ...) + - a directory name, identical to the last element of the devpath - - applications need to handle spaces and characters like '!' in + - applications need to handle spaces and characters like ``!`` in the name - o subsystem (block, tty, pci, ...) + - subsystem (``block``, ``tty``, ``pci``, ...) + - simple string, never a path or a link - retrieved by reading the "subsystem"-link and using only the last element of the target path - o driver (tg3, ata_piix, uhci_hcd) + - driver (``tg3``, ``ata_piix``, ``uhci_hcd``) + - a simple string, which may contain spaces, never a path or a link - it is retrieved by reading the "driver"-link and using only the @@ -75,110 +81,112 @@ versions of the sysfs interface. driver; copying the driver value in a child device context is a bug in the application - o attributes + - attributes + - the files in the device directory or files below subdirectories of the same device directory - accessing attributes reached by a symlink pointing to another device, like the "device"-link, is a bug in the application - Everything else is just a kernel driver-core implementation detail - that should not be assumed to be stable across kernel releases. + Everything else is just a kernel driver-core implementation detail + that should not be assumed to be stable across kernel releases. - Properties of parent devices never belong into a child device. - Always look at the parent devices themselves for determining device - context properties. If the device 'eth0' or 'sda' does not have a - "driver"-link, then this device does not have a driver. Its value is empty. - Never copy any property of the parent-device into a child-device. Parent - device properties may change dynamically without any notice to the - child device. + Always look at the parent devices themselves for determining device + context properties. If the device ``eth0`` or ``sda`` does not have a + "driver"-link, then this device does not have a driver. Its value is empty. + Never copy any property of the parent-device into a child-device. Parent + device properties may change dynamically without any notice to the + child device. - Hierarchy in a single device tree - There is only one valid place in sysfs where hierarchy can be examined - and this is below: /sys/devices. - It is planned that all device directories will end up in the tree - below this directory. + There is only one valid place in sysfs where hierarchy can be examined + and this is below: ``/sys/devices.`` + It is planned that all device directories will end up in the tree + below this directory. - Classification by subsystem - There are currently three places for classification of devices: - /sys/block, /sys/class and /sys/bus. It is planned that these will - not contain any device directories themselves, but only flat lists of - symlinks pointing to the unified /sys/devices tree. - All three places have completely different rules on how to access - device information. It is planned to merge all three - classification directories into one place at /sys/subsystem, - following the layout of the bus directories. All buses and - classes, including the converted block subsystem, will show up - there. - The devices belonging to a subsystem will create a symlink in the - "devices" directory at /sys/subsystem//devices. - - If /sys/subsystem exists, /sys/bus, /sys/class and /sys/block can be - ignored. If it does not exist, you always have to scan all three - places, as the kernel is free to move a subsystem from one place to - the other, as long as the devices are still reachable by the same - subsystem name. - - Assuming /sys/class/ and /sys/bus/, or - /sys/block and /sys/class/block are not interchangeable is a bug in - the application. + There are currently three places for classification of devices: + ``/sys/block,`` ``/sys/class`` and ``/sys/bus.`` It is planned that these will + not contain any device directories themselves, but only flat lists of + symlinks pointing to the unified ``/sys/devices`` tree. + All three places have completely different rules on how to access + device information. It is planned to merge all three + classification directories into one place at ``/sys/subsystem``, + following the layout of the bus directories. All buses and + classes, including the converted block subsystem, will show up + there. + The devices belonging to a subsystem will create a symlink in the + "devices" directory at ``/sys/subsystem//devices``, + + If ``/sys/subsystem`` exists, ``/sys/bus``, ``/sys/class`` and ``/sys/block`` + can be ignored. If it does not exist, you always have to scan all three + places, as the kernel is free to move a subsystem from one place to + the other, as long as the devices are still reachable by the same + subsystem name. + + Assuming ``/sys/class/`` and ``/sys/bus/``, or + ``/sys/block`` and ``/sys/class/block`` are not interchangeable is a bug in + the application. - Block - The converted block subsystem at /sys/class/block or - /sys/subsystem/block will contain the links for disks and partitions - at the same level, never in a hierarchy. Assuming the block subsystem to - contain only disks and not partition devices in the same flat list is - a bug in the application. + The converted block subsystem at ``/sys/class/block`` or + ``/sys/subsystem/block`` will contain the links for disks and partitions + at the same level, never in a hierarchy. Assuming the block subsystem to + contain only disks and not partition devices in the same flat list is + a bug in the application. - "device"-link and :-links - Never depend on the "device"-link. The "device"-link is a workaround - for the old layout, where class devices are not created in - /sys/devices/ like the bus devices. If the link-resolving of a - device directory does not end in /sys/devices/, you can use the - "device"-link to find the parent devices in /sys/devices/. That is the - single valid use of the "device"-link; it must never appear in any - path as an element. Assuming the existence of the "device"-link for - a device in /sys/devices/ is a bug in the application. - Accessing /sys/class/net/eth0/device is a bug in the application. - - Never depend on the class-specific links back to the /sys/class - directory. These links are also a workaround for the design mistake - that class devices are not created in /sys/devices. If a device - directory does not contain directories for child devices, these links - may be used to find the child devices in /sys/class. That is the single - valid use of these links; they must never appear in any path as an - element. Assuming the existence of these links for devices which are - real child device directories in the /sys/devices tree is a bug in - the application. - - It is planned to remove all these links when all class device - directories live in /sys/devices. + Never depend on the "device"-link. The "device"-link is a workaround + for the old layout, where class devices are not created in + ``/sys/devices/`` like the bus devices. If the link-resolving of a + device directory does not end in ``/sys/devices/``, you can use the + "device"-link to find the parent devices in ``/sys/devices/``, That is the + single valid use of the "device"-link; it must never appear in any + path as an element. Assuming the existence of the "device"-link for + a device in ``/sys/devices/`` is a bug in the application. + Accessing ``/sys/class/net/eth0/device`` is a bug in the application. + + Never depend on the class-specific links back to the ``/sys/class`` + directory. These links are also a workaround for the design mistake + that class devices are not created in ``/sys/devices.`` If a device + directory does not contain directories for child devices, these links + may be used to find the child devices in ``/sys/class.`` That is the single + valid use of these links; they must never appear in any path as an + element. Assuming the existence of these links for devices which are + real child device directories in the ``/sys/devices`` tree is a bug in + the application. + + It is planned to remove all these links when all class device + directories live in ``/sys/devices.`` - Position of devices along device chain can change. - Never depend on a specific parent device position in the devpath, - or the chain of parent devices. The kernel is free to insert devices into - the chain. You must always request the parent device you are looking for - by its subsystem value. You need to walk up the chain until you find - the device that matches the expected subsystem. Depending on a specific - position of a parent device or exposing relative paths using "../" to - access the chain of parents is a bug in the application. + Never depend on a specific parent device position in the devpath, + or the chain of parent devices. The kernel is free to insert devices into + the chain. You must always request the parent device you are looking for + by its subsystem value. You need to walk up the chain until you find + the device that matches the expected subsystem. Depending on a specific + position of a parent device or exposing relative paths using ``../`` to + access the chain of parents is a bug in the application. - When reading and writing sysfs device attribute files, avoid dependency - on specific error codes wherever possible. This minimizes coupling to - the error handling implementation within the kernel. + on specific error codes wherever possible. This minimizes coupling to + the error handling implementation within the kernel. - In general, failures to read or write sysfs device attributes shall - propagate errors wherever possible. Common errors include, but are not - limited to: + In general, failures to read or write sysfs device attributes shall + propagate errors wherever possible. Common errors include, but are not + limited to: - -EIO: The read or store operation is not supported, typically returned by - the sysfs system itself if the read or store pointer is NULL. + ``-EIO``: The read or store operation is not supported, typically + returned by the sysfs system itself if the read or store pointer + is ``NULL``. - -ENXIO: The read or store operation failed + ``-ENXIO``: The read or store operation failed - Error codes will not be changed without good reason, and should a change - to error codes result in user-space breakage, it will be fixed, or the - the offending change will be reverted. + Error codes will not be changed without good reason, and should a change + to error codes result in user-space breakage, it will be fixed, or the + the offending change will be reverted. - Userspace applications can, however, expect the format and contents of - the attribute files to remain consistent in the absence of a version - attribute change in the context of a given attribute. + Userspace applications can, however, expect the format and contents of + the attribute files to remain consistent in the absence of a version + attribute change in the context of a given attribute. -- cgit v1.2.3 From c8956bb7dd9525bba4155bf5a09022f036224b3c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 16:07:08 -0300 Subject: Documentation/sysrq.txt: convert to ReST markup - Fix document title; - use a table for the valid commands; - use quote blocks where needed; - use monotonic fonts for config options and file names; - adjust whitespaces and blank lines; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/sysrq.txt | 266 +++++++++++++++++++++++++++--------------------- 1 file changed, 149 insertions(+), 117 deletions(-) diff --git a/Documentation/sysrq.txt b/Documentation/sysrq.txt index 3a3b30ac2a75..d1712ea2d314 100644 --- a/Documentation/sysrq.txt +++ b/Documentation/sysrq.txt @@ -1,23 +1,29 @@ Linux Magic System Request Key Hacks +==================================== + Documentation for sysrq.c -* What is the magic SysRq key? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +What is the magic SysRq key? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + It is a 'magical' key combo you can hit which the kernel will respond to regardless of whatever else it is doing, unless it is completely locked up. -* How do I enable the magic SysRq key? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +How do I enable the magic SysRq key? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + You need to say "yes" to 'Magic SysRq key (CONFIG_MAGIC_SYSRQ)' when configuring the kernel. When running a kernel with SysRq compiled in, /proc/sys/kernel/sysrq controls the functions allowed to be invoked via the SysRq key. The default value in this file is set by the CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE config symbol, which itself defaults to 1. Here is the list of possible values in /proc/sys/kernel/sysrq: - 0 - disable sysrq completely - 1 - enable all functions of sysrq - >1 - bitmask of allowed sysrq functions (see below for detailed function - description): + + - 0 - disable sysrq completely + - 1 - enable all functions of sysrq + - >1 - bitmask of allowed sysrq functions (see below for detailed function + description):: + 2 = 0x2 - enable control of console logging level 4 = 0x4 - enable control of keyboard (SAK, unraw) 8 = 0x8 - enable debugging dumps of processes etc. @@ -27,112 +33,126 @@ to 1. Here is the list of possible values in /proc/sys/kernel/sysrq: 128 = 0x80 - allow reboot/poweroff 256 = 0x100 - allow nicing of all RT tasks -You can set the value in the file by the following command: +You can set the value in the file by the following command:: + echo "number" >/proc/sys/kernel/sysrq The number may be written here either as decimal or as hexadecimal with the 0x prefix. CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE must always be written in hexadecimal. -Note that the value of /proc/sys/kernel/sysrq influences only the invocation -via a keyboard. Invocation of any operation via /proc/sysrq-trigger is always -allowed (by a user with admin privileges). +Note that the value of ``/proc/sys/kernel/sysrq`` influences only the invocation +via a keyboard. Invocation of any operation via ``/proc/sysrq-trigger`` is +always allowed (by a user with admin privileges). -* How do I use the magic SysRq key? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -On x86 - You press the key combo 'ALT-SysRq-'. Note - Some +How do I use the magic SysRq key? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +On x86 - You press the key combo :kbd:`ALT-SysRq-`. + +.. note:: + Some keyboards may not have a key labeled 'SysRq'. The 'SysRq' key is also known as the 'Print Screen' key. Also some keyboards cannot handle so many keys being pressed at the same time, so you might - have better luck with "press Alt", "press SysRq", "release SysRq", - "press ", release everything. + have better luck with press :kbd:`Alt`, press :kbd:`SysRq`, + release :kbd:`SysRq`, press :kbd:``, release everything. -On SPARC - You press 'ALT-STOP-', I believe. +On SPARC - You press :kbd:`ALT-STOP-`, I believe. -On the serial console (PC style standard serial ports only) - - You send a BREAK, then within 5 seconds a command key. Sending - BREAK twice is interpreted as a normal BREAK. +On the serial console (PC style standard serial ports only) + You send a ``BREAK``, then within 5 seconds a command key. Sending + ``BREAK`` twice is interpreted as a normal BREAK. -On PowerPC - Press 'ALT - Print Screen (or F13) - , - Print Screen (or F13) - may suffice. +On PowerPC + Press :kbd:`ALT - Print Screen` (or :kbd:`F13`) - :kbd:``, + :kbd:`Print Screen` (or :kbd:`F13`) - :kbd:`` may suffice. -On other - If you know of the key combos for other architectures, please - let me know so I can add them to this section. +On other + If you know of the key combos for other architectures, please + let me know so I can add them to this section. -On all - write a character to /proc/sysrq-trigger. e.g.: +On all + write a character to /proc/sysrq-trigger. e.g.:: echo t > /proc/sysrq-trigger -* What are the 'command' keys? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -'b' - Will immediately reboot the system without syncing or unmounting - your disks. +What are the 'command' keys? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -'c' - Will perform a system crash by a NULL pointer dereference. - A crashdump will be taken if configured. +=========== =================================================================== +Command Function +=========== =================================================================== +``b`` Will immediately reboot the system without syncing or unmounting + your disks. -'d' - Shows all locks that are held. +``c`` Will perform a system crash by a NULL pointer dereference. + A crashdump will be taken if configured. -'e' - Send a SIGTERM to all processes, except for init. +``d`` Shows all locks that are held. -'f' - Will call the oom killer to kill a memory hog process, but do not - panic if nothing can be killed. +``e`` Send a SIGTERM to all processes, except for init. -'g' - Used by kgdb (kernel debugger) +``f`` Will call the oom killer to kill a memory hog process, but do not + panic if nothing can be killed. -'h' - Will display help (actually any other key than those listed - here will display help. but 'h' is easy to remember :-) +``g`` Used by kgdb (kernel debugger) -'i' - Send a SIGKILL to all processes, except for init. +``h`` Will display help (actually any other key than those listed + here will display help. but ``h`` is easy to remember :-) -'j' - Forcibly "Just thaw it" - filesystems frozen by the FIFREEZE ioctl. +``i`` Send a SIGKILL to all processes, except for init. -'k' - Secure Access Key (SAK) Kills all programs on the current virtual - console. NOTE: See important comments below in SAK section. +``j`` Forcibly "Just thaw it" - filesystems frozen by the FIFREEZE ioctl. -'l' - Shows a stack backtrace for all active CPUs. +``k`` Secure Access Key (SAK) Kills all programs on the current virtual + console. NOTE: See important comments below in SAK section. -'m' - Will dump current memory info to your console. +``l`` Shows a stack backtrace for all active CPUs. -'n' - Used to make RT tasks nice-able +``m`` Will dump current memory info to your console. -'o' - Will shut your system off (if configured and supported). +``n`` Used to make RT tasks nice-able -'p' - Will dump the current registers and flags to your console. +``o`` Will shut your system off (if configured and supported). -'q' - Will dump per CPU lists of all armed hrtimers (but NOT regular - timer_list timers) and detailed information about all - clockevent devices. +``p`` Will dump the current registers and flags to your console. -'r' - Turns off keyboard raw mode and sets it to XLATE. +``q`` Will dump per CPU lists of all armed hrtimers (but NOT regular + timer_list timers) and detailed information about all + clockevent devices. -'s' - Will attempt to sync all mounted filesystems. +``r`` Turns off keyboard raw mode and sets it to XLATE. -'t' - Will dump a list of current tasks and their information to your - console. +``s`` Will attempt to sync all mounted filesystems. -'u' - Will attempt to remount all mounted filesystems read-only. +``t`` Will dump a list of current tasks and their information to your + console. -'v' - Forcefully restores framebuffer console -'v' - Causes ETM buffer dump [ARM-specific] +``u`` Will attempt to remount all mounted filesystems read-only. -'w' - Dumps tasks that are in uninterruptable (blocked) state. +``v`` Forcefully restores framebuffer console +``v`` Causes ETM buffer dump [ARM-specific] -'x' - Used by xmon interface on ppc/powerpc platforms. - Show global PMU Registers on sparc64. - Dump all TLB entries on MIPS. +``w`` Dumps tasks that are in uninterruptable (blocked) state. -'y' - Show global CPU Registers [SPARC-64 specific] +``x`` Used by xmon interface on ppc/powerpc platforms. + Show global PMU Registers on sparc64. + Dump all TLB entries on MIPS. -'z' - Dump the ftrace buffer +``y`` Show global CPU Registers [SPARC-64 specific] -'0'-'9' - Sets the console log level, controlling which kernel messages - will be printed to your console. ('0', for example would make - it so that only emergency messages like PANICs or OOPSes would - make it to your console.) +``z`` Dump the ftrace buffer + +``0``-``9`` Sets the console log level, controlling which kernel messages + will be printed to your console. (``0``, for example would make + it so that only emergency messages like PANICs or OOPSes would + make it to your console.) +=========== =================================================================== + +Okay, so what can I use them for? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* Okay, so what can I use them for? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Well, unraw(r) is very handy when your X server or a svgalib program crashes. sak(k) (Secure Access Key) is useful when you want to be sure there is no @@ -140,73 +160,80 @@ trojan program running at console which could grab your password when you would try to login. It will kill all programs on given console, thus letting you make sure that the login prompt you see is actually the one from init, not some trojan program. -IMPORTANT: In its true form it is not a true SAK like the one in a :IMPORTANT -IMPORTANT: c2 compliant system, and it should not be mistaken as :IMPORTANT -IMPORTANT: such. :IMPORTANT - It seems others find it useful as (System Attention Key) which is + +.. important:: + + In its true form it is not a true SAK like the one in a + c2 compliant system, and it should not be mistaken as + such. + +It seems others find it useful as (System Attention Key) which is useful when you want to exit a program that will not let you switch consoles. (For example, X or a svgalib program.) -reboot(b) is good when you're unable to shut down. But you should also -sync(s) and umount(u) first. +``reboot(b)`` is good when you're unable to shut down. But you should also +``sync(s)`` and ``umount(u)`` first. -crash(c) can be used to manually trigger a crashdump when the system is hung. +``crash(c)`` can be used to manually trigger a crashdump when the system is hung. Note that this just triggers a crash if there is no dump mechanism available. -sync(s) is great when your system is locked up, it allows you to sync your +``sync(s)`` is great when your system is locked up, it allows you to sync your disks and will certainly lessen the chance of data loss and fscking. Note that the sync hasn't taken place until you see the "OK" and "Done" appear on the screen. (If the kernel is really in strife, you may not ever get the OK or Done message...) -umount(u) is basically useful in the same ways as sync(s). I generally sync(s), -umount(u), then reboot(b) when my system locks. It's saved me many a fsck. -Again, the unmount (remount read-only) hasn't taken place until you see the -"OK" and "Done" message appear on the screen. +``umount(u)`` is basically useful in the same ways as ``sync(s)``. I generally +``sync(s)``, ``umount(u)``, then ``reboot(b)`` when my system locks. It's saved +me many a fsck. Again, the unmount (remount read-only) hasn't taken place until +you see the "OK" and "Done" message appear on the screen. -The loglevels '0'-'9' are useful when your console is being flooded with -kernel messages you do not want to see. Selecting '0' will prevent all but +The loglevels ``0``-``9`` are useful when your console is being flooded with +kernel messages you do not want to see. Selecting ``0`` will prevent all but the most urgent kernel messages from reaching your console. (They will still be logged if syslogd/klogd are alive, though.) -term(e) and kill(i) are useful if you have some sort of runaway process you -are unable to kill any other way, especially if it's spawning other +``term(e)`` and ``kill(i)`` are useful if you have some sort of runaway process +you are unable to kill any other way, especially if it's spawning other processes. -"just thaw it(j)" is useful if your system becomes unresponsive due to a frozen -(probably root) filesystem via the FIFREEZE ioctl. +"just thaw ``it(j)``" is useful if your system becomes unresponsive due to a +frozen (probably root) filesystem via the FIFREEZE ioctl. + +Sometimes SysRq seems to get 'stuck' after using it, what can I do? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* Sometimes SysRq seems to get 'stuck' after using it, what can I do? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ That happens to me, also. I've found that tapping shift, alt, and control on both sides of the keyboard, and hitting an invalid sysrq sequence again -will fix the problem. (i.e., something like alt-sysrq-z). Switching to another -virtual console (ALT+Fn) and then back again should also help. +will fix the problem. (i.e., something like :kbd:`alt-sysrq-z`). Switching to +another virtual console (:kbd:`ALT+Fn`) and then back again should also help. + +I hit SysRq, but nothing seems to happen, what's wrong? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* I hit SysRq, but nothing seems to happen, what's wrong? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There are some keyboards that produce a different keycode for SysRq than the -pre-defined value of 99 (see KEY_SYSRQ in include/linux/input.h), or which -don't have a SysRq key at all. In these cases, run 'showkey -s' to find an -appropriate scancode sequence, and use 'setkeycodes 99' to map -this sequence to the usual SysRq code (e.g., 'setkeycodes e05b 99'). It's +pre-defined value of 99 (see ``KEY_SYSRQ`` in ``include/linux/input.h``), or +which don't have a SysRq key at all. In these cases, run ``showkey -s`` to find +an appropriate scancode sequence, and use ``setkeycodes 99`` to map +this sequence to the usual SysRq code (e.g., ``setkeycodes e05b 99``). It's probably best to put this command in a boot script. Oh, and by the way, you -exit 'showkey' by not typing anything for ten seconds. +exit ``showkey`` by not typing anything for ten seconds. + +I want to add SysRQ key events to a module, how does it work? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* I want to add SysRQ key events to a module, how does it work? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In order to register a basic function with the table, you must first include -the header 'include/linux/sysrq.h', this will define everything else you need. -Next, you must create a sysrq_key_op struct, and populate it with A) the key +the header ``include/linux/sysrq.h``, this will define everything else you need. +Next, you must create a ``sysrq_key_op`` struct, and populate it with A) the key handler function you will use, B) a help_msg string, that will print when SysRQ prints help, and C) an action_msg string, that will print right before your handler is called. Your handler must conform to the prototype in 'sysrq.h'. -After the sysrq_key_op is created, you can call the kernel function -register_sysrq_key(int key, struct sysrq_key_op *op_p); this will -register the operation pointed to by 'op_p' at table key 'key', +After the ``sysrq_key_op`` is created, you can call the kernel function +``register_sysrq_key(int key, struct sysrq_key_op *op_p);`` this will +register the operation pointed to by ``op_p`` at table key 'key', if that slot in the table is blank. At module unload time, you must call -the function unregister_sysrq_key(int key, struct sysrq_key_op *op_p), which +the function ``unregister_sysrq_key(int key, struct sysrq_key_op *op_p)``, which will remove the key op pointed to by 'op_p' from the key 'key', if and only if it is currently registered in that slot. This is in case the slot has been overwritten since you registered it. @@ -214,8 +241,10 @@ overwritten since you registered it. The Magic SysRQ system works by registering key operations against a key op lookup table, which is defined in 'drivers/tty/sysrq.c'. This key table has a number of operations registered into it at compile time, but is mutable, -and 2 functions are exported for interface to it: +and 2 functions are exported for interface to it:: + register_sysrq_key and unregister_sysrq_key. + Of course, never ever leave an invalid pointer in the table. I.e., when your module that called register_sysrq_key() exits, it must call unregister_sysrq_key() to clean up the sysrq key table entry that it used. @@ -224,33 +253,36 @@ Null pointers in the table are always safe. :) If for some reason you feel the need to call the handle_sysrq function from within a function called by handle_sysrq, you must be aware that you are in a lock (you are also in an interrupt handler, which means don't sleep!), so -you must call __handle_sysrq_nolock instead. +you must call ``__handle_sysrq_nolock`` instead. + +When I hit a SysRq key combination only the header appears on the console? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -* When I hit a SysRq key combination only the header appears on the console? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Sysrq output is subject to the same console loglevel control as all other console output. This means that if the kernel was booted 'quiet' as is common on distro kernels the output may not appear on the actual console, even though it will appear in the dmesg buffer, and be accessible -via the dmesg command and to the consumers of /proc/kmsg. As a specific +via the dmesg command and to the consumers of ``/proc/kmsg``. As a specific exception the header line from the sysrq command is passed to all console consumers as if the current loglevel was maximum. If only the header is emitted it is almost certain that the kernel loglevel is too low. Should you require the output on the console channel then you will need -to temporarily up the console loglevel using alt-sysrq-8 or: +to temporarily up the console loglevel using :kbd:`alt-sysrq-8` or:: echo 8 > /proc/sysrq-trigger Remember to return the loglevel to normal after triggering the sysrq command you are interested in. -* I have more questions, who can I ask? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +I have more questions, who can I ask? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Just ask them on the linux-kernel mailing list: linux-kernel@vger.kernel.org -* Credits -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Credits +~~~~~~~ + Written by Mydraal Updated by Adam Sulmicki Updated by Jeremy M. Dolan 2001/01/28 10:15:59 -- cgit v1.2.3 From 77514391ee1af3adaa33219109d2ca81fc09e30e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 16:14:29 -0300 Subject: Documentation/unicode.txt: convert it to ReST markup Probably, unicode is something that we might remove from the docs, as all modern systems support it. Yet, this chapter is fun, as it mentions support for the Klington fictional charset ;) On the other hand, I bet all other OS user manuals explicit mention unicode support. So, convert it to ReST and include it at the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/unicode.txt | 22 ++++++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/Documentation/unicode.txt b/Documentation/unicode.txt index 4a33f81cadb1..012e8e895842 100644 --- a/Documentation/unicode.txt +++ b/Documentation/unicode.txt @@ -1,3 +1,6 @@ +Unicode support +=============== + Last update: 2005-01-17, version 1.4 This file is maintained by H. Peter Anvin as part @@ -6,7 +9,8 @@ The current version can be found at: http://www.lanana.org/docs/unicode/unicode.txt - ------------------------ +Introdution +----------- The Linux kernel code has been rewritten to use Unicode to map characters to fonts. By downloading a single Unicode-to-font table, @@ -16,12 +20,14 @@ the font as indicated. This changes the semantics of the eight-bit character tables subtly. The four character tables are now: +=============== =============================== ================ Map symbol Map name Escape code (G0) - +=============== =============================== ================ LAT1_MAP Latin-1 (ISO 8859-1) ESC ( B GRAF_MAP DEC VT100 pseudographics ESC ( 0 IBMPC_MAP IBM code page 437 ESC ( U USER_MAP User defined ESC ( K +=============== =============================== ================ In particular, ESC ( U is no longer "straight to font", since the font might be completely different than the IBM character set. This @@ -55,10 +61,12 @@ In addition, the following characters not present in Unicode 1.1.4 have been defined; these are used by the DEC VT graphics map. [v1.2] THIS USE IS OBSOLETE AND SHOULD NO LONGER BE USED; PLEASE SEE BELOW. +====== ====================================== U+F800 DEC VT GRAPHICS HORIZONTAL LINE SCAN 1 U+F801 DEC VT GRAPHICS HORIZONTAL LINE SCAN 3 U+F803 DEC VT GRAPHICS HORIZONTAL LINE SCAN 7 U+F804 DEC VT GRAPHICS HORIZONTAL LINE SCAN 9 +====== ====================================== The DEC VT220 uses a 6x10 character matrix, and these characters form a smooth progression in the DEC VT graphics character set. I have @@ -74,10 +82,12 @@ keyboard symbols that are unlikely to ever be added to Unicode proper since they are horribly vendor-specific. This, of course, is an excellent example of horrible design. +====== ====================================== U+F810 KEYBOARD SYMBOL FLYING FLAG U+F811 KEYBOARD SYMBOL PULLDOWN MENU U+F812 KEYBOARD SYMBOL OPEN APPLE U+F813 KEYBOARD SYMBOL SOLID APPLE +====== ====================================== Klingon language support ------------------------ @@ -99,8 +109,10 @@ of the dingbats/symbols/forms type and this is a language, I have located it at the end, on a 16-cell boundary in keeping with standard Unicode practice. -NOTE: This range is now officially managed by the ConScript Unicode -Registry. The normative reference is at: +.. note:: + + This range is now officially managed by the ConScript Unicode + Registry. The normative reference is at: http://www.evertype.com/standards/csur/klingon.html @@ -112,6 +124,7 @@ However, since the set of symbols appear to be consistent throughout, with only the actual shapes being different, in keeping with standard Unicode practice these differences are considered font variants. +====== ======================================================= U+F8D0 KLINGON LETTER A U+F8D1 KLINGON LETTER B U+F8D2 KLINGON LETTER CH @@ -155,6 +168,7 @@ U+F8F9 KLINGON DIGIT NINE U+F8FD KLINGON COMMA U+F8FE KLINGON FULL STOP U+F8FF KLINGON SYMBOL FOR EMPIRE +====== ======================================================= Other Fictional and Artificial Scripts -------------------------------------- -- cgit v1.2.3 From 27641b953c54643acfd28fcd9ebbe03cdc724605 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 16:26:03 -0300 Subject: Documentation/VGA-softcursor.txt: convert to ReST markup - Fix document title; - use quote blocks where needed; - use monotonic fonts for config options and file names; - adjust whitespaces and blank lines; - add it to the user's book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/VGA-softcursor.txt | 73 +++++++++++++++++++++++++++------------- 1 file changed, 50 insertions(+), 23 deletions(-) diff --git a/Documentation/VGA-softcursor.txt b/Documentation/VGA-softcursor.txt index 70acfbf399eb..9eac6744b3a1 100644 --- a/Documentation/VGA-softcursor.txt +++ b/Documentation/VGA-softcursor.txt @@ -1,39 +1,66 @@ -Software cursor for VGA by Pavel Machek -======================= and Martin Mares +Software cursor for VGA +======================= - Linux now has some ability to manipulate cursor appearance. Normally, you +by Pavel Machek +and Martin Mares + +Linux now has some ability to manipulate cursor appearance. Normally, you can set the size of hardware cursor (and also work around some ugly bugs in -those miserable Trident cards--see #define TRIDENT_GLITCH in drivers/video/ -vgacon.c). You can now play a few new tricks: you can make your cursor look +those miserable Trident cards [#f1]_. You can now play a few new tricks: +you can make your cursor look + like a non-blinking red block, make it inverse background of the character it's over or to highlight that character and still choose whether the original hardware cursor should remain visible or not. There may be other things I have never thought of. - The cursor appearance is controlled by a "[?1;2;3c" escape sequence +The cursor appearance is controlled by a ``[?1;2;3c`` escape sequence where 1, 2 and 3 are parameters described below. If you omit any of them, they will default to zeroes. - Parameter 1 specifies cursor size (0=default, 1=invisible, 2=underline, ..., -8=full block) + 16 if you want the software cursor to be applied + 32 if you -want to always change the background color + 64 if you dislike having the -background the same as the foreground. Highlights are ignored for the last two -flags. +first Parameter + specifies cursor size:: + + 0=default + 1=invisible + 2=underline, + ... + 8=full block + + 16 if you want the software cursor to be applied + + 32 if you want to always change the background color + + 64 if you dislike having the background the same as the + foreground. + + Highlights are ignored for the last two flags. + +second parameter + selects character attribute bits you want to change + (by simply XORing them with the value of this parameter). On standard + VGA, the high four bits specify background and the low four the + foreground. In both groups, low three bits set color (as in normal + color codes used by the console) and the most significant one turns + on highlight (or sometimes blinking -- it depends on the configuration + of your VGA). + +third parameter + consists of character attribute bits you want to set. - The second parameter selects character attribute bits you want to change -(by simply XORing them with the value of this parameter). On standard VGA, -the high four bits specify background and the low four the foreground. In both -groups, low three bits set color (as in normal color codes used by the console) -and the most significant one turns on highlight (or sometimes blinking--it -depends on the configuration of your VGA). + Bit setting takes place before bit toggling, so you can simply clear a + bit by including it in both the set mask and the toggle mask. - The third parameter consists of character attribute bits you want to set. -Bit setting takes place before bit toggling, so you can simply clear a bit by -including it in both the set mask and the toggle mask. +.. [#f1] see ``#define TRIDENT_GLITCH`` in ``drivers/video/vgacon.c``. Examples: ========= -To get normal blinking underline, use: echo -e '\033[?2c' -To get blinking block, use: echo -e '\033[?6c' -To get red non-blinking block, use: echo -e '\033[?17;0;64c' +To get normal blinking underline, use:: + + echo -e '\033[?2c' + +To get blinking block, use:: + + echo -e '\033[?6c' + +To get red non-blinking block, use:: + + echo -e '\033[?17;0;64c' -- cgit v1.2.3 From 9c27d77d999491d6c80c570887dc95d32908cae5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 16:33:27 -0300 Subject: Documentation/volatile-considered-harmful.txt: convert to ReST markup - Fix document section markups; - use quote blocks where needed; - adjust spaces and blank lines; - add it to the development-processs book. Signed-off-by: Mauro Carvalho Chehab --- Documentation/volatile-considered-harmful.txt | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/Documentation/volatile-considered-harmful.txt b/Documentation/volatile-considered-harmful.txt index db0cb228d64a..e0d042af386c 100644 --- a/Documentation/volatile-considered-harmful.txt +++ b/Documentation/volatile-considered-harmful.txt @@ -22,7 +22,7 @@ need to use volatile as well. If volatile is still necessary, there is almost certainly a bug in the code somewhere. In properly-written kernel code, volatile can only serve to slow things down. -Consider a typical block of kernel code: +Consider a typical block of kernel code:: spin_lock(&the_lock); do_something_on(&shared_data); @@ -57,7 +57,7 @@ optimization, so, once again, volatile is unnecessary. Another situation where one might be tempted to use volatile is when the processor is busy-waiting on the value of a variable. The right -way to perform a busy wait is: +way to perform a busy wait is:: while (my_variable != what_i_want) cpu_relax(); @@ -103,17 +103,20 @@ they come with a justification which shows that the concurrency issues have been properly thought through. -NOTES ------ +References +========== [1] http://lwn.net/Articles/233481/ + [2] http://lwn.net/Articles/233482/ -CREDITS -------- +Credits +======= Original impetus and research by Randy Dunlap + Written by Jonathan Corbet + Improvements via comments from Satyam Sharma, Johannes Stezenbach, Jesper - Juhl, Heikki Orsila, H. Peter Anvin, Philipp Hahn, and Stefan - Richter. +Juhl, Heikki Orsila, H. Peter Anvin, Philipp Hahn, and Stefan +Richter. -- cgit v1.2.3 From 35a1beb9c45d62d1e22e5d4274a220dfa6246cce Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 17:22:55 -0300 Subject: Documentation/parport.txt: fix table to show on LaTeX Sphinx doesn't like nested tables on the LaTex output. So, change the table there to be displayed properly at the PDF output. Signed-off-by: Mauro Carvalho Chehab --- Documentation/parport.txt | 33 ++++++++++++++++++++++----------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/Documentation/parport.txt b/Documentation/parport.txt index 3273ce79f9e3..ad3f9b8a11e1 100644 --- a/Documentation/parport.txt +++ b/Documentation/parport.txt @@ -132,6 +132,8 @@ The ``/proc/sys/dev/parport`` directory tree looks like:: |-- modes `-- spintime +.. tabularcolumns:: |p{4.0cm}|p{13.5cm}| + ======================= ======================================================= File Contents ======================= ======================================================= @@ -154,17 +156,26 @@ File Contents ``modes`` Parallel port's hardware modes, comma-separated, meaning: - =============== ======================================= - PCSPP PC-style SPP registers are available. - TRISTATE Port is bidirectional. - COMPAT Hardware acceleration for printers is - available and will be used. - EPP Hardware acceleration for EPP protocol - is available and will be used. - ECP Hardware acceleration for ECP protocol - is available and will be used. - DMA DMA is available and will be used. - =============== ======================================= + - PCSPP + PC-style SPP registers are available. + + - TRISTATE + Port is bidirectional. + + - COMPAT + Hardware acceleration for printers is + available and will be used. + + - EPP + Hardware acceleration for EPP protocol + is available and will be used. + + - ECP + Hardware acceleration for ECP protocol + is available and will be used. + + - DMA + DMA is available and will be used. Note that the current implementation will only take advantage of COMPAT and ECP modes if it has an IRQ -- cgit v1.2.3 From 8c287de37b2cd4ae9ef95a9e83d7e0da3d60aa1f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 11:57:16 -0200 Subject: Documentation/CodeOfConflict: convert to ReST Fix ReST notation for a bullet item Signed-off-by: Mauro Carvalho Chehab --- Documentation/CodeOfConflict | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/CodeOfConflict b/Documentation/CodeOfConflict index 49a8ecc157a2..47b6de763203 100644 --- a/Documentation/CodeOfConflict +++ b/Documentation/CodeOfConflict @@ -19,7 +19,8 @@ please contact the Linux Foundation's Technical Advisory Board at will work to resolve the issue to the best of their ability. For more information on who is on the Technical Advisory Board and what their role is, please see: - http://www.linuxfoundation.org/projects/linux/tab + + - http://www.linuxfoundation.org/projects/linux/tab As a reviewer of code, please strive to keep things civil and focused on the technical issues involved. We are all humans, and frustrations can -- cgit v1.2.3 From afeb000e1a0596e89174a85c96e890f4f0e802e0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 09:27:00 -0300 Subject: REPORTING-BUGS: convert to ReST markup - add a title to the document; - use :: before verbatim blocks; - add blank lines where required; - use protocol for URL references; - use a verbatim block for the bugs template; - add cross references to SecurityBugs. Signed-off-by: Mauro Carvalho Chehab --- REPORTING-BUGS | 68 ++++++++++++++++++++++++++++++++-------------------------- 1 file changed, 38 insertions(+), 30 deletions(-) diff --git a/REPORTING-BUGS b/REPORTING-BUGS index 914baf9cf5fa..05c53ac7fa76 100644 --- a/REPORTING-BUGS +++ b/REPORTING-BUGS @@ -1,3 +1,8 @@ +.. _reportingbugs: + +Reporting bugs +++++++++++++++ + Background ========== @@ -50,12 +55,13 @@ maintainer replies to you, make sure to 'Reply-all' in order to keep the public mailing list(s) in the email thread. If you know which driver is causing issues, you can pass one of the driver -files to the get_maintainer.pl script: +files to the get_maintainer.pl script:: + perl scripts/get_maintainer.pl -f If it is a security bug, please copy the Security Contact listed in the MAINTAINERS file. They can help coordinate bugfix and disclosure. See -Documentation/SecurityBugs for more information. +:ref:`Documentation/SecurityBugs ` for more information. If you can't figure out which subsystem caused the issue, you should file a bug in kernel.org bugzilla and send email to @@ -69,8 +75,9 @@ Tips for reporting bugs If you haven't reported a bug before, please read: -http://www.chiark.greenend.org.uk/~sgtatham/bugs.html -http://www.catb.org/esr/faqs/smart-questions.html + http://www.chiark.greenend.org.uk/~sgtatham/bugs.html + + http://www.catb.org/esr/faqs/smart-questions.html It's REALLY important to report bugs that seem unrelated as separate email threads or separate bugzilla entries. If you report several unrelated @@ -99,34 +106,34 @@ relevant to your bug, feel free to exclude it. First run the ver_linux script included as scripts/ver_linux, which reports the version of some important subsystems. Run this script with -the command "sh scripts/ver_linux". +the command ``sh scripts/ver_linux``. Use that information to fill in all fields of the bug report form, and post it to the mailing list with a subject of "PROBLEM: " for easy identification by the developers. - -[1.] One line summary of the problem: -[2.] Full description of the problem/report: -[3.] Keywords (i.e., modules, networking, kernel): -[4.] Kernel information -[4.1.] Kernel version (from /proc/version): -[4.2.] Kernel .config file: -[5.] Most recent kernel version which did not have the bug: -[6.] Output of Oops.. message (if applicable) with symbolic information - resolved (see Documentation/oops-tracing.txt) -[7.] A small shell script or example program which triggers the - problem (if possible) -[8.] Environment -[8.1.] Software (add the output of the ver_linux script here) -[8.2.] Processor information (from /proc/cpuinfo): -[8.3.] Module information (from /proc/modules): -[8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem) -[8.5.] PCI information ('lspci -vvv' as root) -[8.6.] SCSI information (from /proc/scsi/scsi) -[8.7.] Other information that might be relevant to the problem - (please look in /proc and include all information that you - think to be relevant): -[X.] Other notes, patches, fixes, workarounds: +summary from [1.]>" for easy identification by the developers:: + + [1.] One line summary of the problem: + [2.] Full description of the problem/report: + [3.] Keywords (i.e., modules, networking, kernel): + [4.] Kernel information + [4.1.] Kernel version (from /proc/version): + [4.2.] Kernel .config file: + [5.] Most recent kernel version which did not have the bug: + [6.] Output of Oops.. message (if applicable) with symbolic information + resolved (see Documentation/oops-tracing.txt) + [7.] A small shell script or example program which triggers the + problem (if possible) + [8.] Environment + [8.1.] Software (add the output of the ver_linux script here) + [8.2.] Processor information (from /proc/cpuinfo): + [8.3.] Module information (from /proc/modules): + [8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem) + [8.5.] PCI information ('lspci -vvv' as root) + [8.6.] SCSI information (from /proc/scsi/scsi) + [8.7.] Other information that might be relevant to the problem + (please look in /proc and include all information that you + think to be relevant): + [X.] Other notes, patches, fixes, workarounds: Follow up @@ -153,7 +160,8 @@ Expectations for kernel maintainers Linux kernel maintainers are busy, overworked human beings. Some times they may not be able to address your bug in a day, a week, or two weeks. If they don't answer your email, they may be on vacation, or at a Linux -conference. Check the conference schedule at LWN.net for more info: +conference. Check the conference schedule at https://LWN.net for more info: + https://lwn.net/Calendar/ In general, kernel maintainers take 1 to 5 business days to respond to -- cgit v1.2.3 From 44b10006a97ec50874634ba5325a6499ead7db66 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 09:09:49 -0300 Subject: README: convert it to ReST markup Adjust the readme file for it to use the ReST markup: - add chapter/section markups; - use ``foo`` for commands; - use :: for verbatim and script blocks; - replace unsupported markup _foo_ by **foo**; - add cross-references to other ReST files; - use lower case on the section titles, to match other ReST files. Signed-off-by: Mauro Carvalho Chehab --- README | 105 ++++++++++++++++++++++++++++++++++++----------------------------- 1 file changed, 58 insertions(+), 47 deletions(-) diff --git a/README b/README index 09f34f78f2bb..3335b3b2973a 100644 --- a/README +++ b/README @@ -1,10 +1,12 @@ - Linux kernel release 4.x +Linux kernel release 4.x +============================================= These are the release notes for Linux version 4. Read them carefully, as they tell you what this is all about, explain how to install the kernel, and what to do if something goes wrong. -WHAT IS LINUX? +What is Linux? +-------------- Linux is a clone of the operating system Unix, written from scratch by Linus Torvalds with assistance from a loosely-knit team of hackers across @@ -18,7 +20,8 @@ WHAT IS LINUX? It is distributed under the GNU General Public License - see the accompanying COPYING file for more details. -ON WHAT HARDWARE DOES IT RUN? +On what hardware does it run? +----------------------------- Although originally developed first for 32-bit x86-based PCs (386 or higher), today Linux also runs on (at least) the Compaq Alpha AXP, Sun SPARC and @@ -34,7 +37,8 @@ ON WHAT HARDWARE DOES IT RUN? Linux has also been ported to itself. You can now run the kernel as a userspace application - this is called UserMode Linux (UML). -DOCUMENTATION: +Documentation +------------- - There is a lot of documentation available both in electronic form on the Internet and in books, both Linux-specific and pertaining to @@ -53,14 +57,15 @@ DOCUMENTATION: - The Documentation/DocBook/ subdirectory contains several guides for kernel developers and users. These guides can be rendered in a number of formats: PostScript (.ps), PDF, HTML, & man-pages, among others. - After installation, "make psdocs", "make pdfdocs", "make htmldocs", - or "make mandocs" will render the documentation in the requested format. + After installation, ``make psdocs``, ``make pdfdocs``, ``make htmldocs``, + or ``make mandocs`` will render the documentation in the requested format. -INSTALLING the kernel source: +Installing the kernel source +---------------------------- - If you install the full sources, put the kernel tarball in a directory where you have permissions (e.g. your home directory) and - unpack it: + unpack it:: xz -cd linux-4.X.tar.xz | tar xvf - @@ -74,12 +79,12 @@ INSTALLING the kernel source: - You can also upgrade between 4.x releases by patching. Patches are distributed in the xz format. To install by patching, get all the newer patch files, enter the top level directory of the kernel source - (linux-4.X) and execute: + (linux-4.X) and execute:: xz -cd ../patch-4.x.xz | patch -p1 Replace "x" for all versions bigger than the version "X" of your current - source tree, _in_order_, and you should be ok. You may want to remove + source tree, **in_order**, and you should be ok. You may want to remove the backup files (some-file-name~ or some-file-name.orig), and make sure that there are no failed patches (some-file-name# or some-file-name.rej). If there are, either you or I have made a mistake. @@ -90,12 +95,12 @@ INSTALLING the kernel source: and you want to apply the 4.0.3 patch, you must not first apply the 4.0.1 and 4.0.2 patches. Similarly, if you are running kernel version 4.0.2 and want to jump to 4.0.3, you must first reverse the 4.0.2 patch (that is, - patch -R) _before_ applying the 4.0.3 patch. You can read more on this in - Documentation/applying-patches.txt + patch -R) **before** applying the 4.0.3 patch. You can read more on this in + :ref:`Documentation/applying-patches.txt `. Alternatively, the script patch-kernel can be used to automate this process. It determines the current kernel version and applies any - patches found. + patches found:: linux/scripts/patch-kernel linux @@ -103,55 +108,58 @@ INSTALLING the kernel source: kernel source. Patches are applied from the current directory, but an alternative directory can be specified as the second argument. - - Make sure you have no stale .o files and dependencies lying around: + - Make sure you have no stale .o files and dependencies lying around:: cd linux make mrproper You should now have the sources correctly installed. -SOFTWARE REQUIREMENTS +Software requirements +--------------------- Compiling and running the 4.x kernels requires up-to-date versions of various software packages. Consult - Documentation/Changes for the minimum version numbers required - and how to get updates for these packages. Beware that using + :ref:`Documentation/Changes ` for the minimum version numbers + required and how to get updates for these packages. Beware that using excessively old versions of these packages can cause indirect errors that are very difficult to track down, so don't assume that you can just update packages when obvious problems arise during build or operation. -BUILD directory for the kernel: +Build directory for the kernel +------------------------------ When compiling the kernel, all output files will per default be stored together with the kernel source code. - Using the option "make O=output/dir" allows you to specify an alternate + Using the option ``make O=output/dir`` allows you to specify an alternate place for the output files (including .config). - Example: + Example:: kernel source code: /usr/src/linux-4.X build directory: /home/name/build/kernel - To configure and build the kernel, use: + To configure and build the kernel, use:: cd /usr/src/linux-4.X make O=/home/name/build/kernel menuconfig make O=/home/name/build/kernel sudo make O=/home/name/build/kernel modules_install install - Please note: If the 'O=output/dir' option is used, then it must be + Please note: If the ``O=output/dir`` option is used, then it must be used for all invocations of make. -CONFIGURING the kernel: +Configuring the kernel +---------------------- Do not skip this step even if you are only upgrading one minor version. New configuration options are added in each release, and odd problems will turn up if the configuration files are not set up as expected. If you want to carry your existing configuration to a - new version with minimal work, use "make oldconfig", which will + new version with minimal work, use ``make oldconfig``, which will only ask you for the answers to new questions. - - Alternative configuration commands are: + - Alternative configuration commands are:: "make config" Plain text interface. @@ -223,7 +231,7 @@ CONFIGURING the kernel: You can find more information on using the Linux kernel config tools in Documentation/kbuild/kconfig.txt. - - NOTES on "make config": + - NOTES on ``make config``: - Having unnecessary drivers will make the kernel bigger, and can under some circumstances lead to problems: probing for a @@ -242,22 +250,23 @@ CONFIGURING the kernel: should probably answer 'n' to the questions for "development", "experimental", or "debugging" features. -COMPILING the kernel: +Compiling the kernel +-------------------- - Make sure you have at least gcc 3.2 available. - For more information, refer to Documentation/Changes. + For more information, refer to :ref:`Documentation/Changes `. Please note that you can still run a.out user programs with this kernel. - - Do a "make" to create a compressed kernel image. It is also - possible to do "make install" if you have lilo installed to suit the + - Do a ``make`` to create a compressed kernel image. It is also + possible to do ``make install`` if you have lilo installed to suit the kernel makefiles, but you may want to check your particular lilo setup first. To do the actual install, you have to be root, but none of the normal build should require that. Don't take the name of root in vain. - - If you configured any of the parts of the kernel as `modules', you - will also have to do "make modules_install". + - If you configured any of the parts of the kernel as ``modules``, you + will also have to do ``make modules_install``. - Verbose kernel compile/build output: @@ -265,12 +274,12 @@ COMPILING the kernel: totally silent). However, sometimes you or other kernel developers need to see compile, link, or other commands exactly as they are executed. For this, use "verbose" build mode. This is done by passing - "V=1" to the "make" command, e.g. + ``V=1`` to the ``make`` command, e.g.:: make V=1 all To have the build system also tell the reason for the rebuild of each - target, use "V=2". The default is "V=0". + target, use ``V=2``. The default is ``V=0``. - Keep a backup kernel handy in case something goes wrong. This is especially true for the development releases, since each new release @@ -278,7 +287,7 @@ COMPILING the kernel: backup of the modules corresponding to that kernel, as well. If you are installing a new kernel with the same version number as your working kernel, make a backup of your modules directory before you - do a "make modules_install". + do a ``make modules_install``. Alternatively, before compiling, use the kernel config option "LOCALVERSION" to append a unique suffix to the regular kernel version. @@ -308,13 +317,14 @@ COMPILING the kernel: reboot, and enjoy! If you ever need to change the default root device, video mode, - ramdisk size, etc. in the kernel image, use the 'rdev' program (or + ramdisk size, etc. in the kernel image, use the ``rdev`` program (or alternatively the LILO boot options when appropriate). No need to recompile the kernel to change these parameters. - Reboot with the new kernel and enjoy. -IF SOMETHING GOES WRONG: +If something goes wrong +----------------------- - If you have problems that seem to be due to kernel bugs, please check the file MAINTAINERS to see if there is a particular person associated @@ -328,7 +338,7 @@ IF SOMETHING GOES WRONG: sense). If the problem is new, tell me so, and if the problem is old, please try to tell me when you first noticed it. - - If the bug results in a message like + - If the bug results in a message like:: unable to handle kernel paging request at address C0000010 Oops: 0002 @@ -348,7 +358,7 @@ IF SOMETHING GOES WRONG: on making sense of the dump is in Documentation/oops-tracing.txt - If you compiled the kernel with CONFIG_KALLSYMS you can send the dump - as is, otherwise you will have to use the "ksymoops" program to make + as is, otherwise you will have to use the ``ksymoops`` program to make sense of the dump (but compiling with CONFIG_KALLSYMS is usually preferred). This utility can be downloaded from ftp://ftp..kernel.org/pub/linux/utils/kernel/ksymoops/ . @@ -358,13 +368,13 @@ IF SOMETHING GOES WRONG: look up what the EIP value means. The hex value as such doesn't help me or anybody else very much: it will depend on your particular kernel setup. What you should do is take the hex value from the EIP - line (ignore the "0010:"), and look it up in the kernel namelist to + line (ignore the ``0010:``), and look it up in the kernel namelist to see which kernel function contains the offending address. To find out the kernel function name, you'll need to find the system binary associated with the kernel that exhibited the symptom. This is the file 'linux/vmlinux'. To extract the namelist and match it against - the EIP from the kernel crash, do: + the EIP from the kernel crash, do:: nm vmlinux | sort | less @@ -383,18 +393,19 @@ IF SOMETHING GOES WRONG: If you for some reason cannot do the above (you have a pre-compiled kernel image or similar), telling me as much about your setup as - possible will help. Please read the REPORTING-BUGS document for details. + possible will help. Please read the :ref:`REPORTING-BUGS ` + document for details. - Alternatively, you can use gdb on a running kernel. (read-only; i.e. you cannot change values or set break points.) To do this, first compile the - kernel with -g; edit arch/x86/Makefile appropriately, then do a "make - clean". You'll also need to enable CONFIG_PROC_FS (via "make config"). + kernel with -g; edit arch/x86/Makefile appropriately, then do a ``make + clean``. You'll also need to enable CONFIG_PROC_FS (via ``make config``). - After you've rebooted with the new kernel, do "gdb vmlinux /proc/kcore". + After you've rebooted with the new kernel, do ``gdb vmlinux /proc/kcore``. You can now use all the usual gdb commands. The command to look up the - point where your system crashed is "l *0xXXXXXXXX". (Replace the XXXes + point where your system crashed is ``l *0xXXXXXXXX``. (Replace the XXXes with the EIP value.) - gdb'ing a non-running kernel currently fails because gdb (wrongly) + gdb'ing a non-running kernel currently fails because ``gdb`` (wrongly) disregards the starting offset for which the kernel is compiled. -- cgit v1.2.3 From 0e4f07a65f53e7b3afab71925e56fe6aaa07d696 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 09:05:32 -0200 Subject: docs: rename development-process/ to process/ As we'll type this a lot, after adding CodingStyle & friends, let's rename the directory name to a shorter one. Signed-off-by: Mauro Carvalho Chehab --- Documentation/00-INDEX | 2 +- Documentation/SubmittingPatches | 2 +- Documentation/conf.py | 2 +- Documentation/development-process/1.Intro.rst | 266 ----------- Documentation/development-process/2.Process.rst | 497 --------------------- .../development-process/3.Early-stage.rst | 222 --------- Documentation/development-process/4.Coding.rst | 413 ----------------- Documentation/development-process/5.Posting.rst | 321 ------------- .../development-process/6.Followthrough.rst | 212 --------- .../development-process/7.AdvancedTopics.rst | 180 -------- Documentation/development-process/8.Conclusion.rst | 74 --- Documentation/development-process/conf.py | 10 - .../development-process/development-process.rst | 29 -- Documentation/development-process/index.rst | 9 - Documentation/index.rst | 2 +- Documentation/process/1.Intro.rst | 266 +++++++++++ Documentation/process/2.Process.rst | 497 +++++++++++++++++++++ Documentation/process/3.Early-stage.rst | 222 +++++++++ Documentation/process/4.Coding.rst | 413 +++++++++++++++++ Documentation/process/5.Posting.rst | 321 +++++++++++++ Documentation/process/6.Followthrough.rst | 212 +++++++++ Documentation/process/7.AdvancedTopics.rst | 178 ++++++++ Documentation/process/8.Conclusion.rst | 74 +++ Documentation/process/conf.py | 10 + Documentation/process/development-process.rst | 28 ++ Documentation/process/index.rst | 9 + 26 files changed, 2234 insertions(+), 2237 deletions(-) delete mode 100644 Documentation/development-process/1.Intro.rst delete mode 100644 Documentation/development-process/2.Process.rst delete mode 100644 Documentation/development-process/3.Early-stage.rst delete mode 100644 Documentation/development-process/4.Coding.rst delete mode 100644 Documentation/development-process/5.Posting.rst delete mode 100644 Documentation/development-process/6.Followthrough.rst delete mode 100644 Documentation/development-process/7.AdvancedTopics.rst delete mode 100644 Documentation/development-process/8.Conclusion.rst delete mode 100644 Documentation/development-process/conf.py delete mode 100644 Documentation/development-process/development-process.rst delete mode 100644 Documentation/development-process/index.rst create mode 100644 Documentation/process/1.Intro.rst create mode 100644 Documentation/process/2.Process.rst create mode 100644 Documentation/process/3.Early-stage.rst create mode 100644 Documentation/process/4.Coding.rst create mode 100644 Documentation/process/5.Posting.rst create mode 100644 Documentation/process/6.Followthrough.rst create mode 100644 Documentation/process/7.AdvancedTopics.rst create mode 100644 Documentation/process/8.Conclusion.rst create mode 100644 Documentation/process/conf.py create mode 100644 Documentation/process/development-process.rst create mode 100644 Documentation/process/index.rst diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 3acc4f1a6f84..d07575a8499e 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -150,7 +150,7 @@ debugging-via-ohci1394.txt - how to use firewire like a hardware debugger memory reader. dell_rbu.txt - document demonstrating the use of the Dell Remote BIOS Update driver. -development-process/ +process/ - how to work with the mainline kernel development process. device-mapper/ - directory with info on Device Mapper. diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 36f1dedc944c..e62ddcdcaf5d 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -10,7 +10,7 @@ can greatly increase the chances of your change being accepted. This document contains a large number of suggestions in a relatively terse format. For detailed information on how the kernel development process -works, see :ref:`Documentation/development-process `. +works, see :ref:`Documentation/process `. Also, read :ref:`Documentation/SubmitChecklist ` for a list of items to check before submitting code. If you are submitting a driver, also read diff --git a/Documentation/conf.py b/Documentation/conf.py index 4db1993658ea..b08e0c9b73b7 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -338,7 +338,7 @@ latex_elements = { latex_documents = [ ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation', 'The kernel development community', 'manual'), - ('development-process/index', 'development-process.tex', 'Linux Kernel Development Documentation', + ('process/index', 'development-process.tex', 'Linux Kernel Development Documentation', 'The kernel development community', 'manual'), ('gpu/index', 'gpu.tex', 'Linux GPU Driver Developer\'s Guide', 'The kernel development community', 'manual'), diff --git a/Documentation/development-process/1.Intro.rst b/Documentation/development-process/1.Intro.rst deleted file mode 100644 index 22642b3fe903..000000000000 --- a/Documentation/development-process/1.Intro.rst +++ /dev/null @@ -1,266 +0,0 @@ -Introdution -=========== - -Executive summary ------------------ - -The rest of this section covers the scope of the kernel development process -and the kinds of frustrations that developers and their employers can -encounter there. There are a great many reasons why kernel code should be -merged into the official ("mainline") kernel, including automatic -availability to users, community support in many forms, and the ability to -influence the direction of kernel development. Code contributed to the -Linux kernel must be made available under a GPL-compatible license. - -:ref:`development_process` introduces the development process, the kernel -release cycle, and the mechanics of the merge window. The various phases in -the patch development, review, and merging cycle are covered. There is some -discussion of tools and mailing lists. Developers wanting to get started -with kernel development are encouraged to track down and fix bugs as an -initial exercise. - -:ref:`development_early_stage` covers early-stage project planning, with an -emphasis on involving the development community as soon as possible. - -:ref:`development_coding` is about the coding process; several pitfalls which -have been encountered by other developers are discussed. Some requirements for -patches are covered, and there is an introduction to some of the tools -which can help to ensure that kernel patches are correct. - -:ref:`development_posting` talks about the process of posting patches for -review. To be taken seriously by the development community, patches must be -properly formatted and described, and they must be sent to the right place. -Following the advice in this section should help to ensure the best -possible reception for your work. - -:ref:`development_followthrough` covers what happens after posting patches; the -job is far from done at that point. Working with reviewers is a crucial part -of the development process; this section offers a number of tips on how to -avoid problems at this important stage. Developers are cautioned against -assuming that the job is done when a patch is merged into the mainline. - -:ref:`development_advancedtopics` introduces a couple of "advanced" topics: -managing patches with git and reviewing patches posted by others. - -:ref:`development_conclusion` concludes the document with pointers to sources -for more information on kernel development. - -What this document is about ---------------------------- - -The Linux kernel, at over 8 million lines of code and well over 1000 -contributors to each release, is one of the largest and most active free -software projects in existence. Since its humble beginning in 1991, this -kernel has evolved into a best-of-breed operating system component which -runs on pocket-sized digital music players, desktop PCs, the largest -supercomputers in existence, and all types of systems in between. It is a -robust, efficient, and scalable solution for almost any situation. - -With the growth of Linux has come an increase in the number of developers -(and companies) wishing to participate in its development. Hardware -vendors want to ensure that Linux supports their products well, making -those products attractive to Linux users. Embedded systems vendors, who -use Linux as a component in an integrated product, want Linux to be as -capable and well-suited to the task at hand as possible. Distributors and -other software vendors who base their products on Linux have a clear -interest in the capabilities, performance, and reliability of the Linux -kernel. And end users, too, will often wish to change Linux to make it -better suit their needs. - -One of the most compelling features of Linux is that it is accessible to -these developers; anybody with the requisite skills can improve Linux and -influence the direction of its development. Proprietary products cannot -offer this kind of openness, which is a characteristic of the free software -process. But, if anything, the kernel is even more open than most other -free software projects. A typical three-month kernel development cycle can -involve over 1000 developers working for more than 100 different companies -(or for no company at all). - -Working with the kernel development community is not especially hard. But, -that notwithstanding, many potential contributors have experienced -difficulties when trying to do kernel work. The kernel community has -evolved its own distinct ways of operating which allow it to function -smoothly (and produce a high-quality product) in an environment where -thousands of lines of code are being changed every day. So it is not -surprising that Linux kernel development process differs greatly from -proprietary development methods. - -The kernel's development process may come across as strange and -intimidating to new developers, but there are good reasons and solid -experience behind it. A developer who does not understand the kernel -community's ways (or, worse, who tries to flout or circumvent them) will -have a frustrating experience in store. The development community, while -being helpful to those who are trying to learn, has little time for those -who will not listen or who do not care about the development process. - -It is hoped that those who read this document will be able to avoid that -frustrating experience. There is a lot of material here, but the effort -involved in reading it will be repaid in short order. The development -community is always in need of developers who will help to make the kernel -better; the following text should help you - or those who work for you - -join our community. - -Credits -------- - -This document was written by Jonathan Corbet, corbet@lwn.net. It has been -improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland -Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, -Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and -Jochen Voß. - -This work was supported by the Linux Foundation; thanks especially to -Amanda McPherson, who saw the value of this effort and made it all happen. - -The importance of getting code into the mainline ------------------------------------------------- - -Some companies and developers occasionally wonder why they should bother -learning how to work with the kernel community and get their code into the -mainline kernel (the "mainline" being the kernel maintained by Linus -Torvalds and used as a base by Linux distributors). In the short term, -contributing code can look like an avoidable expense; it seems easier to -just keep the code separate and support users directly. The truth of the -matter is that keeping code separate ("out of tree") is a false economy. - -As a way of illustrating the costs of out-of-tree code, here are a few -relevant aspects of the kernel development process; most of these will be -discussed in greater detail later in this document. Consider: - -- Code which has been merged into the mainline kernel is available to all - Linux users. It will automatically be present on all distributions which - enable it. There is no need for driver disks, downloads, or the hassles - of supporting multiple versions of multiple distributions; it all just - works, for the developer and for the user. Incorporation into the - mainline solves a large number of distribution and support problems. - -- While kernel developers strive to maintain a stable interface to user - space, the internal kernel API is in constant flux. The lack of a stable - internal interface is a deliberate design decision; it allows fundamental - improvements to be made at any time and results in higher-quality code. - But one result of that policy is that any out-of-tree code requires - constant upkeep if it is to work with new kernels. Maintaining - out-of-tree code requires significant amounts of work just to keep that - code working. - - Code which is in the mainline, instead, does not require this work as the - result of a simple rule requiring any developer who makes an API change - to also fix any code that breaks as the result of that change. So code - which has been merged into the mainline has significantly lower - maintenance costs. - -- Beyond that, code which is in the kernel will often be improved by other - developers. Surprising results can come from empowering your user - community and customers to improve your product. - -- Kernel code is subjected to review, both before and after merging into - the mainline. No matter how strong the original developer's skills are, - this review process invariably finds ways in which the code can be - improved. Often review finds severe bugs and security problems. This is - especially true for code which has been developed in a closed - environment; such code benefits strongly from review by outside - developers. Out-of-tree code is lower-quality code. - -- Participation in the development process is your way to influence the - direction of kernel development. Users who complain from the sidelines - are heard, but active developers have a stronger voice - and the ability - to implement changes which make the kernel work better for their needs. - -- When code is maintained separately, the possibility that a third party - will contribute a different implementation of a similar feature always - exists. Should that happen, getting your code merged will become much - harder - to the point of impossibility. Then you will be faced with the - unpleasant alternatives of either (1) maintaining a nonstandard feature - out of tree indefinitely, or (2) abandoning your code and migrating your - users over to the in-tree version. - -- Contribution of code is the fundamental action which makes the whole - process work. By contributing your code you can add new functionality to - the kernel and provide capabilities and examples which are of use to - other kernel developers. If you have developed code for Linux (or are - thinking about doing so), you clearly have an interest in the continued - success of this platform; contributing code is one of the best ways to - help ensure that success. - -All of the reasoning above applies to any out-of-tree kernel code, -including code which is distributed in proprietary, binary-only form. -There are, however, additional factors which should be taken into account -before considering any sort of binary-only kernel code distribution. These -include: - -- The legal issues around the distribution of proprietary kernel modules - are cloudy at best; quite a few kernel copyright holders believe that - most binary-only modules are derived products of the kernel and that, as - a result, their distribution is a violation of the GNU General Public - license (about which more will be said below). Your author is not a - lawyer, and nothing in this document can possibly be considered to be - legal advice. The true legal status of closed-source modules can only be - determined by the courts. But the uncertainty which haunts those modules - is there regardless. - -- Binary modules greatly increase the difficulty of debugging kernel - problems, to the point that most kernel developers will not even try. So - the distribution of binary-only modules will make it harder for your - users to get support from the community. - -- Support is also harder for distributors of binary-only modules, who must - provide a version of the module for every distribution and every kernel - version they wish to support. Dozens of builds of a single module can - be required to provide reasonably comprehensive coverage, and your users - will have to upgrade your module separately every time they upgrade their - kernel. - -- Everything that was said above about code review applies doubly to - closed-source code. Since this code is not available at all, it cannot - have been reviewed by the community and will, beyond doubt, have serious - problems. - -Makers of embedded systems, in particular, may be tempted to disregard much -of what has been said in this section in the belief that they are shipping -a self-contained product which uses a frozen kernel version and requires no -more development after its release. This argument misses the value of -widespread code review and the value of allowing your users to add -capabilities to your product. But these products, too, have a limited -commercial life, after which a new version must be released. At that -point, vendors whose code is in the mainline and well maintained will be -much better positioned to get the new product ready for market quickly. - -Licensing ---------- - -Code is contributed to the Linux kernel under a number of licenses, but all -code must be compatible with version 2 of the GNU General Public License -(GPLv2), which is the license covering the kernel distribution as a whole. -In practice, that means that all code contributions are covered either by -GPLv2 (with, optionally, language allowing distribution under later -versions of the GPL) or the three-clause BSD license. Any contributions -which are not covered by a compatible license will not be accepted into the -kernel. - -Copyright assignments are not required (or requested) for code contributed -to the kernel. All code merged into the mainline kernel retains its -original ownership; as a result, the kernel now has thousands of owners. - -One implication of this ownership structure is that any attempt to change -the licensing of the kernel is doomed to almost certain failure. There are -few practical scenarios where the agreement of all copyright holders could -be obtained (or their code removed from the kernel). So, in particular, -there is no prospect of a migration to version 3 of the GPL in the -foreseeable future. - -It is imperative that all code contributed to the kernel be legitimately -free software. For that reason, code from anonymous (or pseudonymous) -contributors will not be accepted. All contributors are required to "sign -off" on their code, stating that the code can be distributed with the -kernel under the GPL. Code which has not been licensed as free software by -its owner, or which risks creating copyright-related problems for the -kernel (such as code which derives from reverse-engineering efforts lacking -proper safeguards) cannot be contributed. - -Questions about copyright-related issues are common on Linux development -mailing lists. Such questions will normally receive no shortage of -answers, but one should bear in mind that the people answering those -questions are not lawyers and cannot provide legal advice. If you have -legal questions relating to Linux source code, there is no substitute for -talking with a lawyer who understands this field. Relying on answers -obtained on technical mailing lists is a risky affair. diff --git a/Documentation/development-process/2.Process.rst b/Documentation/development-process/2.Process.rst deleted file mode 100644 index ce5561bb3f8e..000000000000 --- a/Documentation/development-process/2.Process.rst +++ /dev/null @@ -1,497 +0,0 @@ -.. _development_process: - -How the development process works -================================= - -Linux kernel development in the early 1990's was a pretty loose affair, -with relatively small numbers of users and developers involved. With a -user base in the millions and with some 2,000 developers involved over the -course of one year, the kernel has since had to evolve a number of -processes to keep development happening smoothly. A solid understanding of -how the process works is required in order to be an effective part of it. - -The big picture ---------------- - -The kernel developers use a loosely time-based release process, with a new -major kernel release happening every two or three months. The recent -release history looks like this: - - ====== ================= - 2.6.38 March 14, 2011 - 2.6.37 January 4, 2011 - 2.6.36 October 20, 2010 - 2.6.35 August 1, 2010 - 2.6.34 May 15, 2010 - 2.6.33 February 24, 2010 - ====== ================= - -Every 2.6.x release is a major kernel release with new features, internal -API changes, and more. A typical 2.6 release can contain nearly 10,000 -changesets with changes to several hundred thousand lines of code. 2.6 is -thus the leading edge of Linux kernel development; the kernel uses a -rolling development model which is continually integrating major changes. - -A relatively straightforward discipline is followed with regard to the -merging of patches for each release. At the beginning of each development -cycle, the "merge window" is said to be open. At that time, code which is -deemed to be sufficiently stable (and which is accepted by the development -community) is merged into the mainline kernel. The bulk of changes for a -new development cycle (and all of the major changes) will be merged during -this time, at a rate approaching 1,000 changes ("patches," or "changesets") -per day. - -(As an aside, it is worth noting that the changes integrated during the -merge window do not come out of thin air; they have been collected, tested, -and staged ahead of time. How that process works will be described in -detail later on). - -The merge window lasts for approximately two weeks. At the end of this -time, Linus Torvalds will declare that the window is closed and release the -first of the "rc" kernels. For the kernel which is destined to be 2.6.40, -for example, the release which happens at the end of the merge window will -be called 2.6.40-rc1. The -rc1 release is the signal that the time to -merge new features has passed, and that the time to stabilize the next -kernel has begun. - -Over the next six to ten weeks, only patches which fix problems should be -submitted to the mainline. On occasion a more significant change will be -allowed, but such occasions are rare; developers who try to merge new -features outside of the merge window tend to get an unfriendly reception. -As a general rule, if you miss the merge window for a given feature, the -best thing to do is to wait for the next development cycle. (An occasional -exception is made for drivers for previously-unsupported hardware; if they -touch no in-tree code, they cannot cause regressions and should be safe to -add at any time). - -As fixes make their way into the mainline, the patch rate will slow over -time. Linus releases new -rc kernels about once a week; a normal series -will get up to somewhere between -rc6 and -rc9 before the kernel is -considered to be sufficiently stable and the final 2.6.x release is made. -At that point the whole process starts over again. - -As an example, here is how the 2.6.38 development cycle went (all dates in -2011): - - ============== =============================== - January 4 2.6.37 stable release - January 18 2.6.38-rc1, merge window closes - January 21 2.6.38-rc2 - February 1 2.6.38-rc3 - February 7 2.6.38-rc4 - February 15 2.6.38-rc5 - February 21 2.6.38-rc6 - March 1 2.6.38-rc7 - March 7 2.6.38-rc8 - March 14 2.6.38 stable release - ============== =============================== - -How do the developers decide when to close the development cycle and create -the stable release? The most significant metric used is the list of -regressions from previous releases. No bugs are welcome, but those which -break systems which worked in the past are considered to be especially -serious. For this reason, patches which cause regressions are looked upon -unfavorably and are quite likely to be reverted during the stabilization -period. - -The developers' goal is to fix all known regressions before the stable -release is made. In the real world, this kind of perfection is hard to -achieve; there are just too many variables in a project of this size. -There comes a point where delaying the final release just makes the problem -worse; the pile of changes waiting for the next merge window will grow -larger, creating even more regressions the next time around. So most 2.6.x -kernels go out with a handful of known regressions though, hopefully, none -of them are serious. - -Once a stable release is made, its ongoing maintenance is passed off to the -"stable team," currently consisting of Greg Kroah-Hartman. The stable team -will release occasional updates to the stable release using the 2.6.x.y -numbering scheme. To be considered for an update release, a patch must (1) -fix a significant bug, and (2) already be merged into the mainline for the -next development kernel. Kernels will typically receive stable updates for -a little more than one development cycle past their initial release. So, -for example, the 2.6.36 kernel's history looked like: - - ============== =============================== - October 10 2.6.36 stable release - November 22 2.6.36.1 - December 9 2.6.36.2 - January 7 2.6.36.3 - February 17 2.6.36.4 - ============== =============================== - -2.6.36.4 was the final stable update for the 2.6.36 release. - -Some kernels are designated "long term" kernels; they will receive support -for a longer period. As of this writing, the current long term kernels -and their maintainers are: - - ====== ====================== =========================== - 2.6.27 Willy Tarreau (Deep-frozen stable kernel) - 2.6.32 Greg Kroah-Hartman - 2.6.35 Andi Kleen (Embedded flag kernel) - ====== ====================== =========================== - -The selection of a kernel for long-term support is purely a matter of a -maintainer having the need and the time to maintain that release. There -are no known plans for long-term support for any specific upcoming -release. - - -The lifecycle of a patch ------------------------- - -Patches do not go directly from the developer's keyboard into the mainline -kernel. There is, instead, a somewhat involved (if somewhat informal) -process designed to ensure that each patch is reviewed for quality and that -each patch implements a change which is desirable to have in the mainline. -This process can happen quickly for minor fixes, or, in the case of large -and controversial changes, go on for years. Much developer frustration -comes from a lack of understanding of this process or from attempts to -circumvent it. - -In the hopes of reducing that frustration, this document will describe how -a patch gets into the kernel. What follows below is an introduction which -describes the process in a somewhat idealized way. A much more detailed -treatment will come in later sections. - -The stages that a patch goes through are, generally: - - - Design. This is where the real requirements for the patch - and the way - those requirements will be met - are laid out. Design work is often - done without involving the community, but it is better to do this work - in the open if at all possible; it can save a lot of time redesigning - things later. - - - Early review. Patches are posted to the relevant mailing list, and - developers on that list reply with any comments they may have. This - process should turn up any major problems with a patch if all goes - well. - - - Wider review. When the patch is getting close to ready for mainline - inclusion, it should be accepted by a relevant subsystem maintainer - - though this acceptance is not a guarantee that the patch will make it - all the way to the mainline. The patch will show up in the maintainer's - subsystem tree and into the -next trees (described below). When the - process works, this step leads to more extensive review of the patch and - the discovery of any problems resulting from the integration of this - patch with work being done by others. - -- Please note that most maintainers also have day jobs, so merging - your patch may not be their highest priority. If your patch is - getting feedback about changes that are needed, you should either - make those changes or justify why they should not be made. If your - patch has no review complaints but is not being merged by its - appropriate subsystem or driver maintainer, you should be persistent - in updating the patch to the current kernel so that it applies cleanly - and keep sending it for review and merging. - - - Merging into the mainline. Eventually, a successful patch will be - merged into the mainline repository managed by Linus Torvalds. More - comments and/or problems may surface at this time; it is important that - the developer be responsive to these and fix any issues which arise. - - - Stable release. The number of users potentially affected by the patch - is now large, so, once again, new problems may arise. - - - Long-term maintenance. While it is certainly possible for a developer - to forget about code after merging it, that sort of behavior tends to - leave a poor impression in the development community. Merging code - eliminates some of the maintenance burden, in that others will fix - problems caused by API changes. But the original developer should - continue to take responsibility for the code if it is to remain useful - in the longer term. - -One of the largest mistakes made by kernel developers (or their employers) -is to try to cut the process down to a single "merging into the mainline" -step. This approach invariably leads to frustration for everybody -involved. - -How patches get into the Kernel -------------------------------- - -There is exactly one person who can merge patches into the mainline kernel -repository: Linus Torvalds. But, of the over 9,500 patches which went -into the 2.6.38 kernel, only 112 (around 1.3%) were directly chosen by Linus -himself. The kernel project has long since grown to a size where no single -developer could possibly inspect and select every patch unassisted. The -way the kernel developers have addressed this growth is through the use of -a lieutenant system built around a chain of trust. - -The kernel code base is logically broken down into a set of subsystems: -networking, specific architecture support, memory management, video -devices, etc. Most subsystems have a designated maintainer, a developer -who has overall responsibility for the code within that subsystem. These -subsystem maintainers are the gatekeepers (in a loose way) for the portion -of the kernel they manage; they are the ones who will (usually) accept a -patch for inclusion into the mainline kernel. - -Subsystem maintainers each manage their own version of the kernel source -tree, usually (but certainly not always) using the git source management -tool. Tools like git (and related tools like quilt or mercurial) allow -maintainers to track a list of patches, including authorship information -and other metadata. At any given time, the maintainer can identify which -patches in his or her repository are not found in the mainline. - -When the merge window opens, top-level maintainers will ask Linus to "pull" -the patches they have selected for merging from their repositories. If -Linus agrees, the stream of patches will flow up into his repository, -becoming part of the mainline kernel. The amount of attention that Linus -pays to specific patches received in a pull operation varies. It is clear -that, sometimes, he looks quite closely. But, as a general rule, Linus -trusts the subsystem maintainers to not send bad patches upstream. - -Subsystem maintainers, in turn, can pull patches from other maintainers. -For example, the networking tree is built from patches which accumulated -first in trees dedicated to network device drivers, wireless networking, -etc. This chain of repositories can be arbitrarily long, though it rarely -exceeds two or three links. Since each maintainer in the chain trusts -those managing lower-level trees, this process is known as the "chain of -trust." - -Clearly, in a system like this, getting patches into the kernel depends on -finding the right maintainer. Sending patches directly to Linus is not -normally the right way to go. - - -Next trees ----------- - -The chain of subsystem trees guides the flow of patches into the kernel, -but it also raises an interesting question: what if somebody wants to look -at all of the patches which are being prepared for the next merge window? -Developers will be interested in what other changes are pending to see -whether there are any conflicts to worry about; a patch which changes a -core kernel function prototype, for example, will conflict with any other -patches which use the older form of that function. Reviewers and testers -want access to the changes in their integrated form before all of those -changes land in the mainline kernel. One could pull changes from all of -the interesting subsystem trees, but that would be a big and error-prone -job. - -The answer comes in the form of -next trees, where subsystem trees are -collected for testing and review. The older of these trees, maintained by -Andrew Morton, is called "-mm" (for memory management, which is how it got -started). The -mm tree integrates patches from a long list of subsystem -trees; it also has some patches aimed at helping with debugging. - -Beyond that, -mm contains a significant collection of patches which have -been selected by Andrew directly. These patches may have been posted on a -mailing list, or they may apply to a part of the kernel for which there is -no designated subsystem tree. As a result, -mm operates as a sort of -subsystem tree of last resort; if there is no other obvious path for a -patch into the mainline, it is likely to end up in -mm. Miscellaneous -patches which accumulate in -mm will eventually either be forwarded on to -an appropriate subsystem tree or be sent directly to Linus. In a typical -development cycle, approximately 5-10% of the patches going into the -mainline get there via -mm. - -The current -mm patch is available in the "mmotm" (-mm of the moment) -directory at: - - http://www.ozlabs.org/~akpm/mmotm/ - -Use of the MMOTM tree is likely to be a frustrating experience, though; -there is a definite chance that it will not even compile. - -The primary tree for next-cycle patch merging is linux-next, maintained by -Stephen Rothwell. The linux-next tree is, by design, a snapshot of what -the mainline is expected to look like after the next merge window closes. -Linux-next trees are announced on the linux-kernel and linux-next mailing -lists when they are assembled; they can be downloaded from: - - http://www.kernel.org/pub/linux/kernel/next/ - -Linux-next has become an integral part of the kernel development process; -all patches merged during a given merge window should really have found -their way into linux-next some time before the merge window opens. - - -Staging trees -------------- - -The kernel source tree contains the drivers/staging/ directory, where -many sub-directories for drivers or filesystems that are on their way to -being added to the kernel tree live. They remain in drivers/staging while -they still need more work; once complete, they can be moved into the -kernel proper. This is a way to keep track of drivers that aren't -up to Linux kernel coding or quality standards, but people may want to use -them and track development. - -Greg Kroah-Hartman currently maintains the staging tree. Drivers that -still need work are sent to him, with each driver having its own -subdirectory in drivers/staging/. Along with the driver source files, a -TODO file should be present in the directory as well. The TODO file lists -the pending work that the driver needs for acceptance into the kernel -proper, as well as a list of people that should be Cc'd for any patches to -the driver. Current rules require that drivers contributed to staging -must, at a minimum, compile properly. - -Staging can be a relatively easy way to get new drivers into the mainline -where, with luck, they will come to the attention of other developers and -improve quickly. Entry into staging is not the end of the story, though; -code in staging which is not seeing regular progress will eventually be -removed. Distributors also tend to be relatively reluctant to enable -staging drivers. So staging is, at best, a stop on the way toward becoming -a proper mainline driver. - - -Tools ------ - -As can be seen from the above text, the kernel development process depends -heavily on the ability to herd collections of patches in various -directions. The whole thing would not work anywhere near as well as it -does without suitably powerful tools. Tutorials on how to use these tools -are well beyond the scope of this document, but there is space for a few -pointers. - -By far the dominant source code management system used by the kernel -community is git. Git is one of a number of distributed version control -systems being developed in the free software community. It is well tuned -for kernel development, in that it performs quite well when dealing with -large repositories and large numbers of patches. It also has a reputation -for being difficult to learn and use, though it has gotten better over -time. Some sort of familiarity with git is almost a requirement for kernel -developers; even if they do not use it for their own work, they'll need git -to keep up with what other developers (and the mainline) are doing. - -Git is now packaged by almost all Linux distributions. There is a home -page at: - - http://git-scm.com/ - -That page has pointers to documentation and tutorials. - -Among the kernel developers who do not use git, the most popular choice is -almost certainly Mercurial: - - http://www.selenic.com/mercurial/ - -Mercurial shares many features with git, but it provides an interface which -many find easier to use. - -The other tool worth knowing about is Quilt: - - http://savannah.nongnu.org/projects/quilt/ - -Quilt is a patch management system, rather than a source code management -system. It does not track history over time; it is, instead, oriented -toward tracking a specific set of changes against an evolving code base. -Some major subsystem maintainers use quilt to manage patches intended to go -upstream. For the management of certain kinds of trees (-mm, for example), -quilt is the best tool for the job. - - -Mailing lists -------------- - -A great deal of Linux kernel development work is done by way of mailing -lists. It is hard to be a fully-functioning member of the community -without joining at least one list somewhere. But Linux mailing lists also -represent a potential hazard to developers, who risk getting buried under a -load of electronic mail, running afoul of the conventions used on the Linux -lists, or both. - -Most kernel mailing lists are run on vger.kernel.org; the master list can -be found at: - - http://vger.kernel.org/vger-lists.html - -There are lists hosted elsewhere, though; a number of them are at -lists.redhat.com. - -The core mailing list for kernel development is, of course, linux-kernel. -This list is an intimidating place to be; volume can reach 500 messages per -day, the amount of noise is high, the conversation can be severely -technical, and participants are not always concerned with showing a high -degree of politeness. But there is no other place where the kernel -development community comes together as a whole; developers who avoid this -list will miss important information. - -There are a few hints which can help with linux-kernel survival: - -- Have the list delivered to a separate folder, rather than your main - mailbox. One must be able to ignore the stream for sustained periods of - time. - -- Do not try to follow every conversation - nobody else does. It is - important to filter on both the topic of interest (though note that - long-running conversations can drift away from the original subject - without changing the email subject line) and the people who are - participating. - -- Do not feed the trolls. If somebody is trying to stir up an angry - response, ignore them. - -- When responding to linux-kernel email (or that on other lists) preserve - the Cc: header for all involved. In the absence of a strong reason (such - as an explicit request), you should never remove recipients. Always make - sure that the person you are responding to is in the Cc: list. This - convention also makes it unnecessary to explicitly ask to be copied on - replies to your postings. - -- Search the list archives (and the net as a whole) before asking - questions. Some developers can get impatient with people who clearly - have not done their homework. - -- Avoid top-posting (the practice of putting your answer above the quoted - text you are responding to). It makes your response harder to read and - makes a poor impression. - -- Ask on the correct mailing list. Linux-kernel may be the general meeting - point, but it is not the best place to find developers from all - subsystems. - -The last point - finding the correct mailing list - is a common place for -beginning developers to go wrong. Somebody who asks a networking-related -question on linux-kernel will almost certainly receive a polite suggestion -to ask on the netdev list instead, as that is the list frequented by most -networking developers. Other lists exist for the SCSI, video4linux, IDE, -filesystem, etc. subsystems. The best place to look for mailing lists is -in the MAINTAINERS file packaged with the kernel source. - - -Getting started with Kernel development ---------------------------------------- - -Questions about how to get started with the kernel development process are -common - from both individuals and companies. Equally common are missteps -which make the beginning of the relationship harder than it has to be. - -Companies often look to hire well-known developers to get a development -group started. This can, in fact, be an effective technique. But it also -tends to be expensive and does not do much to grow the pool of experienced -kernel developers. It is possible to bring in-house developers up to speed -on Linux kernel development, given the investment of a bit of time. Taking -this time can endow an employer with a group of developers who understand -the kernel and the company both, and who can help to train others as well. -Over the medium term, this is often the more profitable approach. - -Individual developers are often, understandably, at a loss for a place to -start. Beginning with a large project can be intimidating; one often wants -to test the waters with something smaller first. This is the point where -some developers jump into the creation of patches fixing spelling errors or -minor coding style issues. Unfortunately, such patches create a level of -noise which is distracting for the development community as a whole, so, -increasingly, they are looked down upon. New developers wishing to -introduce themselves to the community will not get the sort of reception -they wish for by these means. - -Andrew Morton gives this advice for aspiring kernel developers - -:: - - The #1 project for all kernel beginners should surely be "make sure - that the kernel runs perfectly at all times on all machines which - you can lay your hands on". Usually the way to do this is to work - with others on getting things fixed up (this can require - persistence!) but that's fine - it's a part of kernel development. - -(http://lwn.net/Articles/283982/). - -In the absence of obvious problems to fix, developers are advised to look -at the current lists of regressions and open bugs in general. There is -never any shortage of issues in need of fixing; by addressing these issues, -developers will gain experience with the process while, at the same time, -building respect with the rest of the development community. diff --git a/Documentation/development-process/3.Early-stage.rst b/Documentation/development-process/3.Early-stage.rst deleted file mode 100644 index af2c0af931d6..000000000000 --- a/Documentation/development-process/3.Early-stage.rst +++ /dev/null @@ -1,222 +0,0 @@ -.. _development_early_stage: - -Early-stage planning -==================== - -When contemplating a Linux kernel development project, it can be tempting -to jump right in and start coding. As with any significant project, -though, much of the groundwork for success is best laid before the first -line of code is written. Some time spent in early planning and -communication can save far more time later on. - - -Specifying the problem ----------------------- - -Like any engineering project, a successful kernel enhancement starts with a -clear description of the problem to be solved. In some cases, this step is -easy: when a driver is needed for a specific piece of hardware, for -example. In others, though, it is tempting to confuse the real problem -with the proposed solution, and that can lead to difficulties. - -Consider an example: some years ago, developers working with Linux audio -sought a way to run applications without dropouts or other artifacts caused -by excessive latency in the system. The solution they arrived at was a -kernel module intended to hook into the Linux Security Module (LSM) -framework; this module could be configured to give specific applications -access to the realtime scheduler. This module was implemented and sent to -the linux-kernel mailing list, where it immediately ran into problems. - -To the audio developers, this security module was sufficient to solve their -immediate problem. To the wider kernel community, though, it was seen as a -misuse of the LSM framework (which is not intended to confer privileges -onto processes which they would not otherwise have) and a risk to system -stability. Their preferred solutions involved realtime scheduling access -via the rlimit mechanism for the short term, and ongoing latency reduction -work in the long term. - -The audio community, however, could not see past the particular solution -they had implemented; they were unwilling to accept alternatives. The -resulting disagreement left those developers feeling disillusioned with the -entire kernel development process; one of them went back to an audio list -and posted this: - - There are a number of very good Linux kernel developers, but they - tend to get outshouted by a large crowd of arrogant fools. Trying - to communicate user requirements to these people is a waste of - time. They are much too "intelligent" to listen to lesser mortals. - -(http://lwn.net/Articles/131776/). - -The reality of the situation was different; the kernel developers were far -more concerned about system stability, long-term maintenance, and finding -the right solution to the problem than they were with a specific module. -The moral of the story is to focus on the problem - not a specific solution -- and to discuss it with the development community before investing in the -creation of a body of code. - -So, when contemplating a kernel development project, one should obtain -answers to a short set of questions: - - - What, exactly, is the problem which needs to be solved? - - - Who are the users affected by this problem? Which use cases should the - solution address? - - - How does the kernel fall short in addressing that problem now? - -Only then does it make sense to start considering possible solutions. - - -Early discussion ----------------- - -When planning a kernel development project, it makes great sense to hold -discussions with the community before launching into implementation. Early -communication can save time and trouble in a number of ways: - - - It may well be that the problem is addressed by the kernel in ways which - you have not understood. The Linux kernel is large and has a number of - features and capabilities which are not immediately obvious. Not all - kernel capabilities are documented as well as one might like, and it is - easy to miss things. Your author has seen the posting of a complete - driver which duplicated an existing driver that the new author had been - unaware of. Code which reinvents existing wheels is not only wasteful; - it will also not be accepted into the mainline kernel. - - - There may be elements of the proposed solution which will not be - acceptable for mainline merging. It is better to find out about - problems like this before writing the code. - - - It's entirely possible that other developers have thought about the - problem; they may have ideas for a better solution, and may be willing - to help in the creation of that solution. - -Years of experience with the kernel development community have taught a -clear lesson: kernel code which is designed and developed behind closed -doors invariably has problems which are only revealed when the code is -released into the community. Sometimes these problems are severe, -requiring months or years of effort before the code can be brought up to -the kernel community's standards. Some examples include: - - - The Devicescape network stack was designed and implemented for - single-processor systems. It could not be merged into the mainline - until it was made suitable for multiprocessor systems. Retrofitting - locking and such into code is a difficult task; as a result, the merging - of this code (now called mac80211) was delayed for over a year. - - - The Reiser4 filesystem included a number of capabilities which, in the - core kernel developers' opinion, should have been implemented in the - virtual filesystem layer instead. It also included features which could - not easily be implemented without exposing the system to user-caused - deadlocks. The late revelation of these problems - and refusal to - address some of them - has caused Reiser4 to stay out of the mainline - kernel. - - - The AppArmor security module made use of internal virtual filesystem - data structures in ways which were considered to be unsafe and - unreliable. This concern (among others) kept AppArmor out of the - mainline for years. - -In each of these cases, a great deal of pain and extra work could have been -avoided with some early discussion with the kernel developers. - - -Who do you talk to? -------------------- - -When developers decide to take their plans public, the next question will -be: where do we start? The answer is to find the right mailing list(s) and -the right maintainer. For mailing lists, the best approach is to look in -the MAINTAINERS file for a relevant place to post. If there is a suitable -subsystem list, posting there is often preferable to posting on -linux-kernel; you are more likely to reach developers with expertise in the -relevant subsystem and the environment may be more supportive. - -Finding maintainers can be a bit harder. Again, the MAINTAINERS file is -the place to start. That file tends to not always be up to date, though, -and not all subsystems are represented there. The person listed in the -MAINTAINERS file may, in fact, not be the person who is actually acting in -that role currently. So, when there is doubt about who to contact, a -useful trick is to use git (and "git log" in particular) to see who is -currently active within the subsystem of interest. Look at who is writing -patches, and who, if anybody, is attaching Signed-off-by lines to those -patches. Those are the people who will be best placed to help with a new -development project. - -The task of finding the right maintainer is sometimes challenging enough -that the kernel developers have added a script to ease the process: - -:: - - .../scripts/get_maintainer.pl - -This script will return the current maintainer(s) for a given file or -directory when given the "-f" option. If passed a patch on the -command line, it will list the maintainers who should probably receive -copies of the patch. There are a number of options regulating how hard -get_maintainer.pl will search for maintainers; please be careful about -using the more aggressive options as you may end up including developers -who have no real interest in the code you are modifying. - -If all else fails, talking to Andrew Morton can be an effective way to -track down a maintainer for a specific piece of code. - - -When to post? -------------- - -If possible, posting your plans during the early stages can only be -helpful. Describe the problem being solved and any plans that have been -made on how the implementation will be done. Any information you can -provide can help the development community provide useful input on the -project. - -One discouraging thing which can happen at this stage is not a hostile -reaction, but, instead, little or no reaction at all. The sad truth of the -matter is (1) kernel developers tend to be busy, (2) there is no shortage -of people with grand plans and little code (or even prospect of code) to -back them up, and (3) nobody is obligated to review or comment on ideas -posted by others. Beyond that, high-level designs often hide problems -which are only reviewed when somebody actually tries to implement those -designs; for that reason, kernel developers would rather see the code. - -If a request-for-comments posting yields little in the way of comments, do -not assume that it means there is no interest in the project. -Unfortunately, you also cannot assume that there are no problems with your -idea. The best thing to do in this situation is to proceed, keeping the -community informed as you go. - - -Getting official buy-in ------------------------ - -If your work is being done in a corporate environment - as most Linux -kernel work is - you must, obviously, have permission from suitably -empowered managers before you can post your company's plans or code to a -public mailing list. The posting of code which has not been cleared for -release under a GPL-compatible license can be especially problematic; the -sooner that a company's management and legal staff can agree on the posting -of a kernel development project, the better off everybody involved will be. - -Some readers may be thinking at this point that their kernel work is -intended to support a product which does not yet have an officially -acknowledged existence. Revealing their employer's plans on a public -mailing list may not be a viable option. In cases like this, it is worth -considering whether the secrecy is really necessary; there is often no real -need to keep development plans behind closed doors. - -That said, there are also cases where a company legitimately cannot -disclose its plans early in the development process. Companies with -experienced kernel developers may choose to proceed in an open-loop manner -on the assumption that they will be able to avoid serious integration -problems later. For companies without that sort of in-house expertise, the -best option is often to hire an outside developer to review the plans under -a non-disclosure agreement. The Linux Foundation operates an NDA program -designed to help with this sort of situation; more information can be found -at: - - http://www.linuxfoundation.org/en/NDA_program - -This kind of review is often enough to avoid serious problems later on -without requiring public disclosure of the project. diff --git a/Documentation/development-process/4.Coding.rst b/Documentation/development-process/4.Coding.rst deleted file mode 100644 index 9d5cef996f7f..000000000000 --- a/Documentation/development-process/4.Coding.rst +++ /dev/null @@ -1,413 +0,0 @@ -.. _development_coding: - -Getting the code right -====================== - -While there is much to be said for a solid and community-oriented design -process, the proof of any kernel development project is in the resulting -code. It is the code which will be examined by other developers and merged -(or not) into the mainline tree. So it is the quality of this code which -will determine the ultimate success of the project. - -This section will examine the coding process. We'll start with a look at a -number of ways in which kernel developers can go wrong. Then the focus -will shift toward doing things right and the tools which can help in that -quest. - - -Pitfalls ---------- - -Coding style -************ - -The kernel has long had a standard coding style, described in -Documentation/CodingStyle. For much of that time, the policies described -in that file were taken as being, at most, advisory. As a result, there is -a substantial amount of code in the kernel which does not meet the coding -style guidelines. The presence of that code leads to two independent -hazards for kernel developers. - -The first of these is to believe that the kernel coding standards do not -matter and are not enforced. The truth of the matter is that adding new -code to the kernel is very difficult if that code is not coded according to -the standard; many developers will request that the code be reformatted -before they will even review it. A code base as large as the kernel -requires some uniformity of code to make it possible for developers to -quickly understand any part of it. So there is no longer room for -strangely-formatted code. - -Occasionally, the kernel's coding style will run into conflict with an -employer's mandated style. In such cases, the kernel's style will have to -win before the code can be merged. Putting code into the kernel means -giving up a degree of control in a number of ways - including control over -how the code is formatted. - -The other trap is to assume that code which is already in the kernel is -urgently in need of coding style fixes. Developers may start to generate -reformatting patches as a way of gaining familiarity with the process, or -as a way of getting their name into the kernel changelogs - or both. But -pure coding style fixes are seen as noise by the development community; -they tend to get a chilly reception. So this type of patch is best -avoided. It is natural to fix the style of a piece of code while working -on it for other reasons, but coding style changes should not be made for -their own sake. - -The coding style document also should not be read as an absolute law which -can never be transgressed. If there is a good reason to go against the -style (a line which becomes far less readable if split to fit within the -80-column limit, for example), just do it. - - -Abstraction layers -****************** - -Computer Science professors teach students to make extensive use of -abstraction layers in the name of flexibility and information hiding. -Certainly the kernel makes extensive use of abstraction; no project -involving several million lines of code could do otherwise and survive. -But experience has shown that excessive or premature abstraction can be -just as harmful as premature optimization. Abstraction should be used to -the level required and no further. - -At a simple level, consider a function which has an argument which is -always passed as zero by all callers. One could retain that argument just -in case somebody eventually needs to use the extra flexibility that it -provides. By that time, though, chances are good that the code which -implements this extra argument has been broken in some subtle way which was -never noticed - because it has never been used. Or, when the need for -extra flexibility arises, it does not do so in a way which matches the -programmer's early expectation. Kernel developers will routinely submit -patches to remove unused arguments; they should, in general, not be added -in the first place. - -Abstraction layers which hide access to hardware - often to allow the bulk -of a driver to be used with multiple operating systems - are especially -frowned upon. Such layers obscure the code and may impose a performance -penalty; they do not belong in the Linux kernel. - -On the other hand, if you find yourself copying significant amounts of code -from another kernel subsystem, it is time to ask whether it would, in fact, -make sense to pull out some of that code into a separate library or to -implement that functionality at a higher level. There is no value in -replicating the same code throughout the kernel. - - -#ifdef and preprocessor use in general -************************************** - -The C preprocessor seems to present a powerful temptation to some C -programmers, who see it as a way to efficiently encode a great deal of -flexibility into a source file. But the preprocessor is not C, and heavy -use of it results in code which is much harder for others to read and -harder for the compiler to check for correctness. Heavy preprocessor use -is almost always a sign of code which needs some cleanup work. - -Conditional compilation with #ifdef is, indeed, a powerful feature, and it -is used within the kernel. But there is little desire to see code which is -sprinkled liberally with #ifdef blocks. As a general rule, #ifdef use -should be confined to header files whenever possible. -Conditionally-compiled code can be confined to functions which, if the code -is not to be present, simply become empty. The compiler will then quietly -optimize out the call to the empty function. The result is far cleaner -code which is easier to follow. - -C preprocessor macros present a number of hazards, including possible -multiple evaluation of expressions with side effects and no type safety. -If you are tempted to define a macro, consider creating an inline function -instead. The code which results will be the same, but inline functions are -easier to read, do not evaluate their arguments multiple times, and allow -the compiler to perform type checking on the arguments and return value. - - -Inline functions -**************** - -Inline functions present a hazard of their own, though. Programmers can -become enamored of the perceived efficiency inherent in avoiding a function -call and fill a source file with inline functions. Those functions, -however, can actually reduce performance. Since their code is replicated -at each call site, they end up bloating the size of the compiled kernel. -That, in turn, creates pressure on the processor's memory caches, which can -slow execution dramatically. Inline functions, as a rule, should be quite -small and relatively rare. The cost of a function call, after all, is not -that high; the creation of large numbers of inline functions is a classic -example of premature optimization. - -In general, kernel programmers ignore cache effects at their peril. The -classic time/space tradeoff taught in beginning data structures classes -often does not apply to contemporary hardware. Space *is* time, in that a -larger program will run slower than one which is more compact. - -More recent compilers take an increasingly active role in deciding whether -a given function should actually be inlined or not. So the liberal -placement of "inline" keywords may not just be excessive; it could also be -irrelevant. - - -Locking -******* - -In May, 2006, the "Devicescape" networking stack was, with great -fanfare, released under the GPL and made available for inclusion in the -mainline kernel. This donation was welcome news; support for wireless -networking in Linux was considered substandard at best, and the Devicescape -stack offered the promise of fixing that situation. Yet, this code did not -actually make it into the mainline until June, 2007 (2.6.22). What -happened? - -This code showed a number of signs of having been developed behind -corporate doors. But one large problem in particular was that it was not -designed to work on multiprocessor systems. Before this networking stack -(now called mac80211) could be merged, a locking scheme needed to be -retrofitted onto it. - -Once upon a time, Linux kernel code could be developed without thinking -about the concurrency issues presented by multiprocessor systems. Now, -however, this document is being written on a dual-core laptop. Even on -single-processor systems, work being done to improve responsiveness will -raise the level of concurrency within the kernel. The days when kernel -code could be written without thinking about locking are long past. - -Any resource (data structures, hardware registers, etc.) which could be -accessed concurrently by more than one thread must be protected by a lock. -New code should be written with this requirement in mind; retrofitting -locking after the fact is a rather more difficult task. Kernel developers -should take the time to understand the available locking primitives well -enough to pick the right tool for the job. Code which shows a lack of -attention to concurrency will have a difficult path into the mainline. - - -Regressions -*********** - -One final hazard worth mentioning is this: it can be tempting to make a -change (which may bring big improvements) which causes something to break -for existing users. This kind of change is called a "regression," and -regressions have become most unwelcome in the mainline kernel. With few -exceptions, changes which cause regressions will be backed out if the -regression cannot be fixed in a timely manner. Far better to avoid the -regression in the first place. - -It is often argued that a regression can be justified if it causes things -to work for more people than it creates problems for. Why not make a -change if it brings new functionality to ten systems for each one it -breaks? The best answer to this question was expressed by Linus in July, -2007: - -:: - - So we don't fix bugs by introducing new problems. That way lies - madness, and nobody ever knows if you actually make any real - progress at all. Is it two steps forwards, one step back, or one - step forward and two steps back? - -(http://lwn.net/Articles/243460/). - -An especially unwelcome type of regression is any sort of change to the -user-space ABI. Once an interface has been exported to user space, it must -be supported indefinitely. This fact makes the creation of user-space -interfaces particularly challenging: since they cannot be changed in -incompatible ways, they must be done right the first time. For this -reason, a great deal of thought, clear documentation, and wide review for -user-space interfaces is always required. - - -Code checking tools -------------------- - -For now, at least, the writing of error-free code remains an ideal that few -of us can reach. What we can hope to do, though, is to catch and fix as -many of those errors as possible before our code goes into the mainline -kernel. To that end, the kernel developers have put together an impressive -array of tools which can catch a wide variety of obscure problems in an -automated way. Any problem caught by the computer is a problem which will -not afflict a user later on, so it stands to reason that the automated -tools should be used whenever possible. - -The first step is simply to heed the warnings produced by the compiler. -Contemporary versions of gcc can detect (and warn about) a large number of -potential errors. Quite often, these warnings point to real problems. -Code submitted for review should, as a rule, not produce any compiler -warnings. When silencing warnings, take care to understand the real cause -and try to avoid "fixes" which make the warning go away without addressing -its cause. - -Note that not all compiler warnings are enabled by default. Build the -kernel with "make EXTRA_CFLAGS=-W" to get the full set. - -The kernel provides several configuration options which turn on debugging -features; most of these are found in the "kernel hacking" submenu. Several -of these options should be turned on for any kernel used for development or -testing purposes. In particular, you should turn on: - - - ENABLE_WARN_DEPRECATED, ENABLE_MUST_CHECK, and FRAME_WARN to get an - extra set of warnings for problems like the use of deprecated interfaces - or ignoring an important return value from a function. The output - generated by these warnings can be verbose, but one need not worry about - warnings from other parts of the kernel. - - - DEBUG_OBJECTS will add code to track the lifetime of various objects - created by the kernel and warn when things are done out of order. If - you are adding a subsystem which creates (and exports) complex objects - of its own, consider adding support for the object debugging - infrastructure. - - - DEBUG_SLAB can find a variety of memory allocation and use errors; it - should be used on most development kernels. - - - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP, and DEBUG_MUTEXES will find a - number of common locking errors. - -There are quite a few other debugging options, some of which will be -discussed below. Some of them have a significant performance impact and -should not be used all of the time. But some time spent learning the -available options will likely be paid back many times over in short order. - -One of the heavier debugging tools is the locking checker, or "lockdep." -This tool will track the acquisition and release of every lock (spinlock or -mutex) in the system, the order in which locks are acquired relative to -each other, the current interrupt environment, and more. It can then -ensure that locks are always acquired in the same order, that the same -interrupt assumptions apply in all situations, and so on. In other words, -lockdep can find a number of scenarios in which the system could, on rare -occasion, deadlock. This kind of problem can be painful (for both -developers and users) in a deployed system; lockdep allows them to be found -in an automated manner ahead of time. Code with any sort of non-trivial -locking should be run with lockdep enabled before being submitted for -inclusion. - -As a diligent kernel programmer, you will, beyond doubt, check the return -status of any operation (such as a memory allocation) which can fail. The -fact of the matter, though, is that the resulting failure recovery paths -are, probably, completely untested. Untested code tends to be broken code; -you could be much more confident of your code if all those error-handling -paths had been exercised a few times. - -The kernel provides a fault injection framework which can do exactly that, -especially where memory allocations are involved. With fault injection -enabled, a configurable percentage of memory allocations will be made to -fail; these failures can be restricted to a specific range of code. -Running with fault injection enabled allows the programmer to see how the -code responds when things go badly. See -Documentation/fault-injection/fault-injection.txt for more information on -how to use this facility. - -Other kinds of errors can be found with the "sparse" static analysis tool. -With sparse, the programmer can be warned about confusion between -user-space and kernel-space addresses, mixture of big-endian and -small-endian quantities, the passing of integer values where a set of bit -flags is expected, and so on. Sparse must be installed separately (it can -be found at https://sparse.wiki.kernel.org/index.php/Main_Page if your -distributor does not package it); it can then be run on the code by adding -"C=1" to your make command. - -The "Coccinelle" tool (http://coccinelle.lip6.fr/) is able to find a wide -variety of potential coding problems; it can also propose fixes for those -problems. Quite a few "semantic patches" for the kernel have been packaged -under the scripts/coccinelle directory; running "make coccicheck" will run -through those semantic patches and report on any problems found. See -Documentation/coccinelle.txt for more information. - -Other kinds of portability errors are best found by compiling your code for -other architectures. If you do not happen to have an S/390 system or a -Blackfin development board handy, you can still perform the compilation -step. A large set of cross compilers for x86 systems can be found at - - http://www.kernel.org/pub/tools/crosstool/ - -Some time spent installing and using these compilers will help avoid -embarrassment later. - - -Documentation -------------- - -Documentation has often been more the exception than the rule with kernel -development. Even so, adequate documentation will help to ease the merging -of new code into the kernel, make life easier for other developers, and -will be helpful for your users. In many cases, the addition of -documentation has become essentially mandatory. - -The first piece of documentation for any patch is its associated -changelog. Log entries should describe the problem being solved, the form -of the solution, the people who worked on the patch, any relevant -effects on performance, and anything else that might be needed to -understand the patch. Be sure that the changelog says *why* the patch is -worth applying; a surprising number of developers fail to provide that -information. - -Any code which adds a new user-space interface - including new sysfs or -/proc files - should include documentation of that interface which enables -user-space developers to know what they are working with. See -Documentation/ABI/README for a description of how this documentation should -be formatted and what information needs to be provided. - -The file Documentation/kernel-parameters.txt describes all of the kernel's -boot-time parameters. Any patch which adds new parameters should add the -appropriate entries to this file. - -Any new configuration options must be accompanied by help text which -clearly explains the options and when the user might want to select them. - -Internal API information for many subsystems is documented by way of -specially-formatted comments; these comments can be extracted and formatted -in a number of ways by the "kernel-doc" script. If you are working within -a subsystem which has kerneldoc comments, you should maintain them and add -them, as appropriate, for externally-available functions. Even in areas -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-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, -the expectations for new code are higher than they were in the past; -merging uncommented code will be harder. That said, there is little desire -for verbosely-commented code. The code should, itself, be readable, with -comments explaining the more subtle aspects. - -Certain things should always be commented. Uses of memory barriers should -be accompanied by a line explaining why the barrier is necessary. The -locking rules for data structures generally need to be explained somewhere. -Major data structures need comprehensive documentation in general. -Non-obvious dependencies between separate bits of code should be pointed -out. Anything which might tempt a code janitor to make an incorrect -"cleanup" needs a comment saying why it is done the way it is. And so on. - - -Internal API changes --------------------- - -The binary interface provided by the kernel to user space cannot be broken -except under the most severe circumstances. The kernel's internal -programming interfaces, instead, are highly fluid and can be changed when -the need arises. If you find yourself having to work around a kernel API, -or simply not using a specific functionality because it does not meet your -needs, that may be a sign that the API needs to change. As a kernel -developer, you are empowered to make such changes. - -There are, of course, some catches. API changes can be made, but they need -to be well justified. So any patch making an internal API change should be -accompanied by a description of what the change is and why it is -necessary. This kind of change should also be broken out into a separate -patch, rather than buried within a larger patch. - -The other catch is that a developer who changes an internal API is -generally charged with the task of fixing any code within the kernel tree -which is broken by the change. For a widely-used function, this duty can -lead to literally hundreds or thousands of changes - many of which are -likely to conflict with work being done by other developers. Needless to -say, this can be a large job, so it is best to be sure that the -justification is solid. Note that the Coccinelle tool can help with -wide-ranging API changes. - -When making an incompatible API change, one should, whenever possible, -ensure that code which has not been updated is caught by the compiler. -This will help you to be sure that you have found all in-tree uses of that -interface. It will also alert developers of out-of-tree code that there is -a change that they need to respond to. Supporting out-of-tree code is not -something that kernel developers need to be worried about, but we also do -not have to make life harder for out-of-tree developers than it needs to -be. diff --git a/Documentation/development-process/5.Posting.rst b/Documentation/development-process/5.Posting.rst deleted file mode 100644 index b511ddf7e82a..000000000000 --- a/Documentation/development-process/5.Posting.rst +++ /dev/null @@ -1,321 +0,0 @@ -.. _development_posting: - -Posting patches -=============== - -Sooner or later, the time comes when your work is ready to be presented to -the community for review and, eventually, inclusion into the mainline -kernel. Unsurprisingly, the kernel development community has evolved a set -of conventions and procedures which are used in the posting of patches; -following them will make life much easier for everybody involved. This -document will attempt to cover these expectations in reasonable detail; -more information can also be found in the files SubmittingPatches, -SubmittingDrivers, and SubmitChecklist in the kernel documentation -directory. - - -When to post ------------- - -There is a constant temptation to avoid posting patches before they are -completely "ready." For simple patches, that is not a problem. If the -work being done is complex, though, there is a lot to be gained by getting -feedback from the community before the work is complete. So you should -consider posting in-progress work, or even making a git tree available so -that interested developers can catch up with your work at any time. - -When posting code which is not yet considered ready for inclusion, it is a -good idea to say so in the posting itself. Also mention any major work -which remains to be done and any known problems. Fewer people will look at -patches which are known to be half-baked, but those who do will come in -with the idea that they can help you drive the work in the right direction. - - -Before creating patches ------------------------ - -There are a number of things which should be done before you consider -sending patches to the development community. These include: - - - Test the code to the extent that you can. Make use of the kernel's - debugging tools, ensure that the kernel will build with all reasonable - combinations of configuration options, use cross-compilers to build for - different architectures, etc. - - - Make sure your code is compliant with the kernel coding style - guidelines. - - - Does your change have performance implications? If so, you should run - benchmarks showing what the impact (or benefit) of your change is; a - summary of the results should be included with the patch. - - - Be sure that you have the right to post the code. If this work was done - for an employer, the employer likely has a right to the work and must be - agreeable with its release under the GPL. - -As a general rule, putting in some extra thought before posting code almost -always pays back the effort in short order. - - -Patch preparation ------------------ - -The preparation of patches for posting can be a surprising amount of work, -but, once again, attempting to save time here is not generally advisable -even in the short term. - -Patches must be prepared against a specific version of the kernel. As a -general rule, a patch should be based on the current mainline as found in -Linus's git tree. When basing on mainline, start with a well-known release -point - a stable or -rc release - rather than branching off the mainline at -an arbitrary spot. - -It may become necessary to make versions against -mm, linux-next, or a -subsystem tree, though, to facilitate wider testing and review. Depending -on the area of your patch and what is going on elsewhere, basing a patch -against these other trees can require a significant amount of work -resolving conflicts and dealing with API changes. - -Only the most simple changes should be formatted as a single patch; -everything else should be made as a logical series of changes. Splitting -up patches is a bit of an art; some developers spend a long time figuring -out how to do it in the way that the community expects. There are a few -rules of thumb, however, which can help considerably: - - - The patch series you post will almost certainly not be the series of - changes found in your working revision control system. Instead, the - changes you have made need to be considered in their final form, then - split apart in ways which make sense. The developers are interested in - discrete, self-contained changes, not the path you took to get to those - changes. - - - Each logically independent change should be formatted as a separate - patch. These changes can be small ("add a field to this structure") or - large (adding a significant new driver, for example), but they should be - conceptually small and amenable to a one-line description. Each patch - should make a specific change which can be reviewed on its own and - verified to do what it says it does. - - - As a way of restating the guideline above: do not mix different types of - changes in the same patch. If a single patch fixes a critical security - bug, rearranges a few structures, and reformats the code, there is a - good chance that it will be passed over and the important fix will be - lost. - - - Each patch should yield a kernel which builds and runs properly; if your - patch series is interrupted in the middle, the result should still be a - working kernel. Partial application of a patch series is a common - scenario when the "git bisect" tool is used to find regressions; if the - result is a broken kernel, you will make life harder for developers and - users who are engaging in the noble work of tracking down problems. - - - Do not overdo it, though. One developer once posted a set of edits - to a single file as 500 separate patches - an act which did not make him - the most popular person on the kernel mailing list. A single patch can - be reasonably large as long as it still contains a single *logical* - change. - - - It can be tempting to add a whole new infrastructure with a series of - patches, but to leave that infrastructure unused until the final patch - in the series enables the whole thing. This temptation should be - avoided if possible; if that series adds regressions, bisection will - finger the last patch as the one which caused the problem, even though - the real bug is elsewhere. Whenever possible, a patch which adds new - code should make that code active immediately. - -Working to create the perfect patch series can be a frustrating process -which takes quite a bit of time and thought after the "real work" has been -done. When done properly, though, it is time well spent. - - -Patch formatting and changelogs -------------------------------- - -So now you have a perfect series of patches for posting, but the work is -not done quite yet. Each patch needs to be formatted into a message which -quickly and clearly communicates its purpose to the rest of the world. To -that end, each patch will be composed of the following: - - - An optional "From" line naming the author of the patch. This line is - only necessary if you are passing on somebody else's patch via email, - but it never hurts to add it when in doubt. - - - A one-line description of what the patch does. This message should be - enough for a reader who sees it with no other context to figure out the - scope of the patch; it is the line that will show up in the "short form" - changelogs. This message is usually formatted with the relevant - subsystem name first, followed by the purpose of the patch. For - example: - - :: - - gpio: fix build on CONFIG_GPIO_SYSFS=n - - - A blank line followed by a detailed description of the contents of the - patch. This description can be as long as is required; it should say - what the patch does and why it should be applied to the kernel. - - - One or more tag lines, with, at a minimum, one Signed-off-by: line from - the author of the patch. Tags will be described in more detail below. - -The items above, together, form the changelog for the patch. Writing good -changelogs is a crucial but often-neglected art; it's worth spending -another moment discussing this issue. When writing a changelog, you should -bear in mind that a number of different people will be reading your words. -These include subsystem maintainers and reviewers who need to decide -whether the patch should be included, distributors and other maintainers -trying to decide whether a patch should be backported to other kernels, bug -hunters wondering whether the patch is responsible for a problem they are -chasing, users who want to know how the kernel has changed, and more. A -good changelog conveys the needed information to all of these people in the -most direct and concise way possible. - -To that end, the summary line should describe the effects of and motivation -for the change as well as possible given the one-line constraint. The -detailed description can then amplify on those topics and provide any -needed additional information. If the patch fixes a bug, cite the commit -which introduced the bug if possible (and please provide both the commit ID -and the title when citing commits). If a problem is associated with -specific log or compiler output, include that output to help others -searching for a solution to the same problem. If the change is meant to -support other changes coming in later patch, say so. If internal APIs are -changed, detail those changes and how other developers should respond. In -general, the more you can put yourself into the shoes of everybody who will -be reading your changelog, the better that changelog (and the kernel as a -whole) will be. - -Needless to say, the changelog should be the text used when committing the -change to a revision control system. It will be followed by: - - - The patch itself, in the unified ("-u") patch format. Using the "-p" - option to diff will associate function names with changes, making the - resulting patch easier for others to read. - -You should avoid including changes to irrelevant files (those generated by -the build process, for example, or editor backup files) in the patch. The -file "dontdiff" in the Documentation directory can help in this regard; -pass it to diff with the "-X" option. - -The tags mentioned above are used to describe how various developers have -been associated with the development of this patch. They are described in -detail in the SubmittingPatches document; what follows here is a brief -summary. Each of these lines has the format: - -:: - - tag: Full Name optional-other-stuff - -The tags in common use are: - - - Signed-off-by: this is a developer's certification that he or she has - the right to submit the patch for inclusion into the kernel. It is an - agreement to the Developer's Certificate of Origin, the full text of - which can be found in Documentation/SubmittingPatches. Code without a - proper signoff cannot be merged into the mainline. - - - Acked-by: indicates an agreement by another developer (often a - maintainer of the relevant code) that the patch is appropriate for - inclusion into the kernel. - - - Tested-by: states that the named person has tested the patch and found - it to work. - - - Reviewed-by: the named developer has reviewed the patch for correctness; - see the reviewer's statement in Documentation/SubmittingPatches for more - detail. - - - Reported-by: names a user who reported a problem which is fixed by this - patch; this tag is used to give credit to the (often underappreciated) - people who test our code and let us know when things do not work - correctly. - - - Cc: the named person received a copy of the patch and had the - opportunity to comment on it. - -Be careful in the addition of tags to your patches: only Cc: is appropriate -for addition without the explicit permission of the person named. - - -Sending the patch ------------------ - -Before you mail your patches, there are a couple of other things you should -take care of: - - - Are you sure that your mailer will not corrupt the patches? Patches - which have had gratuitous white-space changes or line wrapping performed - by the mail client will not apply at the other end, and often will not - be examined in any detail. If there is any doubt at all, mail the patch - to yourself and convince yourself that it shows up intact. - - Documentation/email-clients.txt has some helpful hints on making - specific mail clients work for sending patches. - - - Are you sure your patch is free of silly mistakes? You should always - run patches through scripts/checkpatch.pl and address the complaints it - comes up with. Please bear in mind that checkpatch.pl, while being the - embodiment of a fair amount of thought about what kernel patches should - look like, is not smarter than you. If fixing a checkpatch.pl complaint - would make the code worse, don't do it. - -Patches should always be sent as plain text. Please do not send them as -attachments; that makes it much harder for reviewers to quote sections of -the patch in their replies. Instead, just put the patch directly into your -message. - -When mailing patches, it is important to send copies to anybody who might -be interested in it. Unlike some other projects, the kernel encourages -people to err on the side of sending too many copies; don't assume that the -relevant people will see your posting on the mailing lists. In particular, -copies should go to: - - - The maintainer(s) of the affected subsystem(s). As described earlier, - the MAINTAINERS file is the first place to look for these people. - - - Other developers who have been working in the same area - especially - those who might be working there now. Using git to see who else has - modified the files you are working on can be helpful. - - - If you are responding to a bug report or a feature request, copy the - original poster as well. - - - Send a copy to the relevant mailing list, or, if nothing else applies, - the linux-kernel list. - - - If you are fixing a bug, think about whether the fix should go into the - next stable update. If so, stable@vger.kernel.org should get a copy of - the patch. Also add a "Cc: stable@vger.kernel.org" to the tags within - the patch itself; that will cause the stable team to get a notification - when your fix goes into the mainline. - -When selecting recipients for a patch, it is good to have an idea of who -you think will eventually accept the patch and get it merged. While it -is possible to send patches directly to Linus Torvalds and have him merge -them, things are not normally done that way. Linus is busy, and there are -subsystem maintainers who watch over specific parts of the kernel. Usually -you will be wanting that maintainer to merge your patches. If there is no -obvious maintainer, Andrew Morton is often the patch target of last resort. - -Patches need good subject lines. The canonical format for a patch line is -something like: - -:: - - [PATCH nn/mm] subsys: one-line description of the patch - -where "nn" is the ordinal number of the patch, "mm" is the total number of -patches in the series, and "subsys" is the name of the affected subsystem. -Clearly, nn/mm can be omitted for a single, standalone patch. - -If you have a significant series of patches, it is customary to send an -introductory description as part zero. This convention is not universally -followed though; if you use it, remember that information in the -introduction does not make it into the kernel changelogs. So please ensure -that the patches, themselves, have complete changelog information. - -In general, the second and following parts of a multi-part patch should be -sent as a reply to the first part so that they all thread together at the -receiving end. Tools like git and quilt have commands to mail out a set of -patches with the proper threading. If you have a long series, though, and -are using git, please stay away from the --chain-reply-to option to avoid -creating exceptionally deep nesting. diff --git a/Documentation/development-process/6.Followthrough.rst b/Documentation/development-process/6.Followthrough.rst deleted file mode 100644 index a173cd5f93d2..000000000000 --- a/Documentation/development-process/6.Followthrough.rst +++ /dev/null @@ -1,212 +0,0 @@ -.. _development_followthrough: - -Followthrough -============= - -At this point, you have followed the guidelines given so far and, with the -addition of your own engineering skills, have posted a perfect series of -patches. One of the biggest mistakes that even experienced kernel -developers can make is to conclude that their work is now done. In truth, -posting patches indicates a transition into the next stage of the process, -with, possibly, quite a bit of work yet to be done. - -It is a rare patch which is so good at its first posting that there is no -room for improvement. The kernel development process recognizes this fact, -and, as a result, is heavily oriented toward the improvement of posted -code. You, as the author of that code, will be expected to work with the -kernel community to ensure that your code is up to the kernel's quality -standards. A failure to participate in this process is quite likely to -prevent the inclusion of your patches into the mainline. - - -Working with reviewers ----------------------- - -A patch of any significance will result in a number of comments from other -developers as they review the code. Working with reviewers can be, for -many developers, the most intimidating part of the kernel development -process. Life can be made much easier, though, if you keep a few things in -mind: - - - If you have explained your patch well, reviewers will understand its - value and why you went to the trouble of writing it. But that value - will not keep them from asking a fundamental question: what will it be - like to maintain a kernel with this code in it five or ten years later? - Many of the changes you may be asked to make - from coding style tweaks - to substantial rewrites - come from the understanding that Linux will - still be around and under development a decade from now. - - - Code review is hard work, and it is a relatively thankless occupation; - people remember who wrote kernel code, but there is little lasting fame - for those who reviewed it. So reviewers can get grumpy, especially when - they see the same mistakes being made over and over again. If you get a - review which seems angry, insulting, or outright offensive, resist the - impulse to respond in kind. Code review is about the code, not about - the people, and code reviewers are not attacking you personally. - - - Similarly, code reviewers are not trying to promote their employers' - agendas at the expense of your own. Kernel developers often expect to - be working on the kernel years from now, but they understand that their - employer could change. They truly are, almost without exception, - working toward the creation of the best kernel they can; they are not - trying to create discomfort for their employers' competitors. - -What all of this comes down to is that, when reviewers send you comments, -you need to pay attention to the technical observations that they are -making. Do not let their form of expression or your own pride keep that -from happening. When you get review comments on a patch, take the time to -understand what the reviewer is trying to say. If possible, fix the things -that the reviewer is asking you to fix. And respond back to the reviewer: -thank them, and describe how you will answer their questions. - -Note that you do not have to agree with every change suggested by -reviewers. If you believe that the reviewer has misunderstood your code, -explain what is really going on. If you have a technical objection to a -suggested change, describe it and justify your solution to the problem. If -your explanations make sense, the reviewer will accept them. Should your -explanation not prove persuasive, though, especially if others start to -agree with the reviewer, take some time to think things over again. It can -be easy to become blinded by your own solution to a problem to the point -that you don't realize that something is fundamentally wrong or, perhaps, -you're not even solving the right problem. - -Andrew Morton has suggested that every review comment which does not result -in a code change should result in an additional code comment instead; that -can help future reviewers avoid the questions which came up the first time -around. - -One fatal mistake is to ignore review comments in the hope that they will -go away. They will not go away. If you repost code without having -responded to the comments you got the time before, you're likely to find -that your patches go nowhere. - -Speaking of reposting code: please bear in mind that reviewers are not -going to remember all the details of the code you posted the last time -around. So it is always a good idea to remind reviewers of previously -raised issues and how you dealt with them; the patch changelog is a good -place for this kind of information. Reviewers should not have to search -through list archives to familiarize themselves with what was said last -time; if you help them get a running start, they will be in a better mood -when they revisit your code. - -What if you've tried to do everything right and things still aren't going -anywhere? Most technical disagreements can be resolved through discussion, -but there are times when somebody simply has to make a decision. If you -honestly believe that this decision is going against you wrongly, you can -always try appealing to a higher power. As of this writing, that higher -power tends to be Andrew Morton. Andrew has a great deal of respect in the -kernel development community; he can often unjam a situation which seems to -be hopelessly blocked. Appealing to Andrew should not be done lightly, -though, and not before all other alternatives have been explored. And bear -in mind, of course, that he may not agree with you either. - - -What happens next ------------------ - -If a patch is considered to be a good thing to add to the kernel, and once -most of the review issues have been resolved, the next step is usually -entry into a subsystem maintainer's tree. How that works varies from one -subsystem to the next; each maintainer has his or her own way of doing -things. In particular, there may be more than one tree - one, perhaps, -dedicated to patches planned for the next merge window, and another for -longer-term work. - -For patches applying to areas for which there is no obvious subsystem tree -(memory management patches, for example), the default tree often ends up -being -mm. Patches which affect multiple subsystems can also end up going -through the -mm tree. - -Inclusion into a subsystem tree can bring a higher level of visibility to a -patch. Now other developers working with that tree will get the patch by -default. Subsystem trees typically feed linux-next as well, making their -contents visible to the development community as a whole. At this point, -there's a good chance that you will get more comments from a new set of -reviewers; these comments need to be answered as in the previous round. - -What may also happen at this point, depending on the nature of your patch, -is that conflicts with work being done by others turn up. In the worst -case, heavy patch conflicts can result in some work being put on the back -burner so that the remaining patches can be worked into shape and merged. -Other times, conflict resolution will involve working with the other -developers and, possibly, moving some patches between trees to ensure that -everything applies cleanly. This work can be a pain, but count your -blessings: before the advent of the linux-next tree, these conflicts often -only turned up during the merge window and had to be addressed in a hurry. -Now they can be resolved at leisure, before the merge window opens. - -Some day, if all goes well, you'll log on and see that your patch has been -merged into the mainline kernel. Congratulations! Once the celebration is -complete (and you have added yourself to the MAINTAINERS file), though, it -is worth remembering an important little fact: the job still is not done. -Merging into the mainline brings its own challenges. - -To begin with, the visibility of your patch has increased yet again. There -may be a new round of comments from developers who had not been aware of -the patch before. It may be tempting to ignore them, since there is no -longer any question of your code being merged. Resist that temptation, -though; you still need to be responsive to developers who have questions or -suggestions. - -More importantly, though: inclusion into the mainline puts your code into -the hands of a much larger group of testers. Even if you have contributed -a driver for hardware which is not yet available, you will be surprised by -how many people will build your code into their kernels. And, of course, -where there are testers, there will be bug reports. - -The worst sort of bug reports are regressions. If your patch causes a -regression, you'll find an uncomfortable number of eyes upon you; -regressions need to be fixed as soon as possible. If you are unwilling or -unable to fix the regression (and nobody else does it for you), your patch -will almost certainly be removed during the stabilization period. Beyond -negating all of the work you have done to get your patch into the mainline, -having a patch pulled as the result of a failure to fix a regression could -well make it harder for you to get work merged in the future. - -After any regressions have been dealt with, there may be other, ordinary -bugs to deal with. The stabilization period is your best opportunity to -fix these bugs and ensure that your code's debut in a mainline kernel -release is as solid as possible. So, please, answer bug reports, and fix -the problems if at all possible. That's what the stabilization period is -for; you can start creating cool new patches once any problems with the old -ones have been taken care of. - -And don't forget that there are other milestones which may also create bug -reports: the next mainline stable release, when prominent distributors pick -up a version of the kernel containing your patch, etc. Continuing to -respond to these reports is a matter of basic pride in your work. If that -is insufficient motivation, though, it's also worth considering that the -development community remembers developers who lose interest in their code -after it's merged. The next time you post a patch, they will be evaluating -it with the assumption that you will not be around to maintain it -afterward. - - -Other things that can happen ------------------------------ - -One day, you may open your mail client and see that somebody has mailed you -a patch to your code. That is one of the advantages of having your code -out there in the open, after all. If you agree with the patch, you can -either forward it on to the subsystem maintainer (be sure to include a -proper From: line so that the attribution is correct, and add a signoff of -your own), or send an Acked-by: response back and let the original poster -send it upward. - -If you disagree with the patch, send a polite response explaining why. If -possible, tell the author what changes need to be made to make the patch -acceptable to you. There is a certain resistance to merging patches which -are opposed by the author and maintainer of the code, but it only goes so -far. If you are seen as needlessly blocking good work, those patches will -eventually flow around you and get into the mainline anyway. In the Linux -kernel, nobody has absolute veto power over any code. Except maybe Linus. - -On very rare occasion, you may see something completely different: another -developer posts a different solution to your problem. At that point, -chances are that one of the two patches will not be merged, and "mine was -here first" is not considered to be a compelling technical argument. If -somebody else's patch displaces yours and gets into the mainline, there is -really only one way to respond: be pleased that your problem got solved and -get on with your work. Having one's work shoved aside in this manner can -be hurtful and discouraging, but the community will remember your reaction -long after they have forgotten whose patch actually got merged. diff --git a/Documentation/development-process/7.AdvancedTopics.rst b/Documentation/development-process/7.AdvancedTopics.rst deleted file mode 100644 index 81d61c5d62dd..000000000000 --- a/Documentation/development-process/7.AdvancedTopics.rst +++ /dev/null @@ -1,180 +0,0 @@ -.. _development_advancedtopics: - -Advanced topics -=============== - -At this point, hopefully, you have a handle on how the development process -works. There is still more to learn, however! This section will cover a -number of topics which can be helpful for developers wanting to become a -regular part of the Linux kernel development process. - -Managing patches with git -------------------------- - -The use of distributed version control for the kernel began in early 2002, -when Linus first started playing with the proprietary BitKeeper -application. While BitKeeper was controversial, the approach to software -version management it embodied most certainly was not. Distributed version -control enabled an immediate acceleration of the kernel development -project. In current times, there are several free alternatives to -BitKeeper. For better or for worse, the kernel project has settled on git -as its tool of choice. - -Managing patches with git can make life much easier for the developer, -especially as the volume of those patches grows. Git also has its rough -edges and poses certain hazards; it is a young and powerful tool which is -still being civilized by its developers. This document will not attempt to -teach the reader how to use git; that would be sufficient material for a -long document in its own right. Instead, the focus here will be on how git -fits into the kernel development process in particular. Developers who -wish to come up to speed with git will find more information at: - - http://git-scm.com/ - - http://www.kernel.org/pub/software/scm/git/docs/user-manual.html - -and on various tutorials found on the web. - -The first order of business is to read the above sites and get a solid -understanding of how git works before trying to use it to make patches -available to others. A git-using developer should be able to obtain a copy -of the mainline repository, explore the revision history, commit changes to -the tree, use branches, etc. An understanding of git's tools for the -rewriting of history (such as rebase) is also useful. Git comes with its -own terminology and concepts; a new user of git should know about refs, -remote branches, the index, fast-forward merges, pushes and pulls, detached -heads, etc. It can all be a little intimidating at the outset, but the -concepts are not that hard to grasp with a bit of study. - -Using git to generate patches for submission by email can be a good -exercise while coming up to speed. - -When you are ready to start putting up git trees for others to look at, you -will, of course, need a server that can be pulled from. Setting up such a -server with git-daemon is relatively straightforward if you have a system -which is accessible to the Internet. Otherwise, free, public hosting sites -(Github, for example) are starting to appear on the net. Established -developers can get an account on kernel.org, but those are not easy to come -by; see http://kernel.org/faq/ for more information. - -The normal git workflow involves the use of a lot of branches. Each line -of development can be separated into a separate "topic branch" and -maintained independently. Branches in git are cheap, there is no reason to -not make free use of them. And, in any case, you should not do your -development in any branch which you intend to ask others to pull from. -Publicly-available branches should be created with care; merge in patches -from development branches when they are in complete form and ready to go - -not before. - -Git provides some powerful tools which can allow you to rewrite your -development history. An inconvenient patch (one which breaks bisection, -say, or which has some other sort of obvious bug) can be fixed in place or -made to disappear from the history entirely. A patch series can be -rewritten as if it had been written on top of today's mainline, even though -you have been working on it for months. Changes can be transparently -shifted from one branch to another. And so on. Judicious use of git's -ability to revise history can help in the creation of clean patch sets with -fewer problems. - -Excessive use of this capability can lead to other problems, though, beyond -a simple obsession for the creation of the perfect project history. -Rewriting history will rewrite the changes contained in that history, -turning a tested (hopefully) kernel tree into an untested one. But, beyond -that, developers cannot easily collaborate if they do not have a shared -view of the project history; if you rewrite history which other developers -have pulled into their repositories, you will make life much more difficult -for those developers. So a simple rule of thumb applies here: history -which has been exported to others should generally be seen as immutable -thereafter. - -So, once you push a set of changes to your publicly-available server, those -changes should not be rewritten. Git will attempt to enforce this rule if -you try to push changes which do not result in a fast-forward merge -(i.e. changes which do not share the same history). It is possible to -override this check, and there may be times when it is necessary to rewrite -an exported tree. Moving changesets between trees to avoid conflicts in -linux-next is one example. But such actions should be rare. This is one -of the reasons why development should be done in private branches (which -can be rewritten if necessary) and only moved into public branches when -it's in a reasonably advanced state. - -As the mainline (or other tree upon which a set of changes is based) -advances, it is tempting to merge with that tree to stay on the leading -edge. For a private branch, rebasing can be an easy way to keep up with -another tree, but rebasing is not an option once a tree is exported to the -world. Once that happens, a full merge must be done. Merging occasionally -makes good sense, but overly frequent merges can clutter the history -needlessly. Suggested technique in this case is to merge infrequently, and -generally only at specific release points (such as a mainline -rc -release). If you are nervous about specific changes, you can always -perform test merges in a private branch. The git "rerere" tool can be -useful in such situations; it remembers how merge conflicts were resolved -so that you don't have to do the same work twice. - -One of the biggest recurring complaints about tools like git is this: the -mass movement of patches from one repository to another makes it easy to -slip in ill-advised changes which go into the mainline below the review -radar. Kernel developers tend to get unhappy when they see that kind of -thing happening; putting up a git tree with unreviewed or off-topic patches -can affect your ability to get trees pulled in the future. Quoting Linus: - -:: - - You can send me patches, but for me to pull a git patch from you, I - need to know that you know what you're doing, and I need to be able - to trust things *without* then having to go and check every - individual change by hand. - -(http://lwn.net/Articles/224135/). - -To avoid this kind of situation, ensure that all patches within a given -branch stick closely to the associated topic; a "driver fixes" branch -should not be making changes to the core memory management code. And, most -importantly, do not use a git tree to bypass the review process. Post an -occasional summary of the tree to the relevant list, and, when the time is -right, request that the tree be included in linux-next. - -If and when others start to send patches for inclusion into your tree, -don't forget to review them. Also ensure that you maintain the correct -authorship information; the git "am" tool does its best in this regard, but -you may have to add a "From:" line to the patch if it has been relayed to -you via a third party. - -When requesting a pull, be sure to give all the relevant information: where -your tree is, what branch to pull, and what changes will result from the -pull. The git request-pull command can be helpful in this regard; it will -format the request as other developers expect, and will also check to be -sure that you have remembered to push those changes to the public server. - - -Reviewing patches ------------------ - -Some readers will certainly object to putting this section with "advanced -topics" on the grounds that even beginning kernel developers should be -reviewing patches. It is certainly true that there is no better way to -learn how to program in the kernel environment than by looking at code -posted by others. In addition, reviewers are forever in short supply; by -looking at code you can make a significant contribution to the process as a -whole. - -Reviewing code can be an intimidating prospect, especially for a new kernel -developer who may well feel nervous about questioning code - in public - -which has been posted by those with more experience. Even code written by -the most experienced developers can be improved, though. Perhaps the best -piece of advice for reviewers (all reviewers) is this: phrase review -comments as questions rather than criticisms. Asking "how does the lock -get released in this path?" will always work better than stating "the -locking here is wrong." - -Different developers will review code from different points of view. Some -are mostly concerned with coding style and whether code lines have trailing -white space. Others will focus primarily on whether the change implemented -by the patch as a whole is a good thing for the kernel or not. Yet others -will check for problematic locking, excessive stack usage, possible -security issues, duplication of code found elsewhere, adequate -documentation, adverse effects on performance, user-space ABI changes, etc. -All types of review, if they lead to better code going into the kernel, are -welcome and worthwhile. - - diff --git a/Documentation/development-process/8.Conclusion.rst b/Documentation/development-process/8.Conclusion.rst deleted file mode 100644 index 23ec7cbc2d2b..000000000000 --- a/Documentation/development-process/8.Conclusion.rst +++ /dev/null @@ -1,74 +0,0 @@ -.. _development_conclusion: - -For more information -==================== - -There are numerous sources of information on Linux kernel development and -related topics. First among those will always be the Documentation -directory found in the kernel source distribution. The top-level HOWTO -file is an important starting point; SubmittingPatches and -SubmittingDrivers are also something which all kernel developers should -read. Many internal kernel APIs are documented using the kerneldoc -mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those -documents in HTML or PDF format (though the version of TeX shipped by some -distributions runs into internal limits and fails to process the documents -properly). - -Various web sites discuss kernel development at all levels of detail. Your -author would like to humbly suggest http://lwn.net/ as a source; -information on many specific kernel topics can be found via the LWN kernel -index at: - - http://lwn.net/Kernel/Index/ - -Beyond that, a valuable resource for kernel developers is: - - http://kernelnewbies.org/ - -And, of course, one should not forget http://kernel.org/, the definitive -location for kernel release information. - -There are a number of books on kernel development: - - Linux Device Drivers, 3rd Edition (Jonathan Corbet, Alessandro - Rubini, and Greg Kroah-Hartman). Online at - http://lwn.net/Kernel/LDD3/. - - Linux Kernel Development (Robert Love). - - Understanding the Linux Kernel (Daniel Bovet and Marco Cesati). - -All of these books suffer from a common fault, though: they tend to be -somewhat obsolete by the time they hit the shelves, and they have been on -the shelves for a while now. Still, there is quite a bit of good -information to be found there. - -Documentation for git can be found at: - - http://www.kernel.org/pub/software/scm/git/docs/ - - http://www.kernel.org/pub/software/scm/git/docs/user-manual.html - - -Conclusion -========== - -Congratulations to anybody who has made it through this long-winded -document. Hopefully it has provided a helpful understanding of how the -Linux kernel is developed and how you can participate in that process. - -In the end, it's the participation that matters. Any open source software -project is no more than the sum of what its contributors put into it. The -Linux kernel has progressed as quickly and as well as it has because it has -been helped by an impressively large group of developers, all of whom are -working to make it better. The kernel is a premier example of what can be -done when thousands of people work together toward a common goal. - -The kernel can always benefit from a larger developer base, though. There -is always more work to do. But, just as importantly, most other -participants in the Linux ecosystem can benefit through contributing to the -kernel. Getting code into the mainline is the key to higher code quality, -lower maintenance and distribution costs, a higher level of influence over -the direction of kernel development, and more. It is a situation where -everybody involved wins. Fire up your editor and come join us; you will be -more than welcome. diff --git a/Documentation/development-process/conf.py b/Documentation/development-process/conf.py deleted file mode 100644 index 4b4a12dace02..000000000000 --- a/Documentation/development-process/conf.py +++ /dev/null @@ -1,10 +0,0 @@ -# -*- coding: utf-8; mode: python -*- - -project = 'Linux Kernel Development Documentation' - -tags.add("subproject") - -latex_documents = [ - ('index', 'development-process.tex', 'Linux Kernel Development Documentation', - 'The kernel development community', 'manual'), -] diff --git a/Documentation/development-process/development-process.rst b/Documentation/development-process/development-process.rst deleted file mode 100644 index bd1399f7202a..000000000000 --- a/Documentation/development-process/development-process.rst +++ /dev/null @@ -1,29 +0,0 @@ -.. _development_process_main: - -A guide to the Kernel Development Process -========================================= - -Contents: - -.. toctree:: - :numbered: - :maxdepth: 2 - - 1.Intro - 2.Process - 3.Early-stage - 4.Coding - 5.Posting - 6.Followthrough - 7.AdvancedTopics - 8.Conclusion - -The purpose of this document is to help developers (and their managers) -work with the development community with a minimum of frustration. It is -an attempt to document how this community works in a way which is -accessible to those who are not intimately familiar with Linux kernel -development (or, indeed, free software development in general). While -there is some technical material here, this is very much a process-oriented -discussion which does not require a deep knowledge of kernel programming to -understand. - diff --git a/Documentation/development-process/index.rst b/Documentation/development-process/index.rst deleted file mode 100644 index c37475d91090..000000000000 --- a/Documentation/development-process/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -Linux Kernel Development Documentation -====================================== - -Contents: - -.. toctree:: - :maxdepth: 2 - - development-process diff --git a/Documentation/index.rst b/Documentation/index.rst index c53d089455a4..e1f18b3db6e4 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -12,7 +12,7 @@ Contents: :maxdepth: 2 kernel-documentation - development-process/index + process/index dev-tools/tools driver-api/index media/index diff --git a/Documentation/process/1.Intro.rst b/Documentation/process/1.Intro.rst new file mode 100644 index 000000000000..22642b3fe903 --- /dev/null +++ b/Documentation/process/1.Intro.rst @@ -0,0 +1,266 @@ +Introdution +=========== + +Executive summary +----------------- + +The rest of this section covers the scope of the kernel development process +and the kinds of frustrations that developers and their employers can +encounter there. There are a great many reasons why kernel code should be +merged into the official ("mainline") kernel, including automatic +availability to users, community support in many forms, and the ability to +influence the direction of kernel development. Code contributed to the +Linux kernel must be made available under a GPL-compatible license. + +:ref:`development_process` introduces the development process, the kernel +release cycle, and the mechanics of the merge window. The various phases in +the patch development, review, and merging cycle are covered. There is some +discussion of tools and mailing lists. Developers wanting to get started +with kernel development are encouraged to track down and fix bugs as an +initial exercise. + +:ref:`development_early_stage` covers early-stage project planning, with an +emphasis on involving the development community as soon as possible. + +:ref:`development_coding` is about the coding process; several pitfalls which +have been encountered by other developers are discussed. Some requirements for +patches are covered, and there is an introduction to some of the tools +which can help to ensure that kernel patches are correct. + +:ref:`development_posting` talks about the process of posting patches for +review. To be taken seriously by the development community, patches must be +properly formatted and described, and they must be sent to the right place. +Following the advice in this section should help to ensure the best +possible reception for your work. + +:ref:`development_followthrough` covers what happens after posting patches; the +job is far from done at that point. Working with reviewers is a crucial part +of the development process; this section offers a number of tips on how to +avoid problems at this important stage. Developers are cautioned against +assuming that the job is done when a patch is merged into the mainline. + +:ref:`development_advancedtopics` introduces a couple of "advanced" topics: +managing patches with git and reviewing patches posted by others. + +:ref:`development_conclusion` concludes the document with pointers to sources +for more information on kernel development. + +What this document is about +--------------------------- + +The Linux kernel, at over 8 million lines of code and well over 1000 +contributors to each release, is one of the largest and most active free +software projects in existence. Since its humble beginning in 1991, this +kernel has evolved into a best-of-breed operating system component which +runs on pocket-sized digital music players, desktop PCs, the largest +supercomputers in existence, and all types of systems in between. It is a +robust, efficient, and scalable solution for almost any situation. + +With the growth of Linux has come an increase in the number of developers +(and companies) wishing to participate in its development. Hardware +vendors want to ensure that Linux supports their products well, making +those products attractive to Linux users. Embedded systems vendors, who +use Linux as a component in an integrated product, want Linux to be as +capable and well-suited to the task at hand as possible. Distributors and +other software vendors who base their products on Linux have a clear +interest in the capabilities, performance, and reliability of the Linux +kernel. And end users, too, will often wish to change Linux to make it +better suit their needs. + +One of the most compelling features of Linux is that it is accessible to +these developers; anybody with the requisite skills can improve Linux and +influence the direction of its development. Proprietary products cannot +offer this kind of openness, which is a characteristic of the free software +process. But, if anything, the kernel is even more open than most other +free software projects. A typical three-month kernel development cycle can +involve over 1000 developers working for more than 100 different companies +(or for no company at all). + +Working with the kernel development community is not especially hard. But, +that notwithstanding, many potential contributors have experienced +difficulties when trying to do kernel work. The kernel community has +evolved its own distinct ways of operating which allow it to function +smoothly (and produce a high-quality product) in an environment where +thousands of lines of code are being changed every day. So it is not +surprising that Linux kernel development process differs greatly from +proprietary development methods. + +The kernel's development process may come across as strange and +intimidating to new developers, but there are good reasons and solid +experience behind it. A developer who does not understand the kernel +community's ways (or, worse, who tries to flout or circumvent them) will +have a frustrating experience in store. The development community, while +being helpful to those who are trying to learn, has little time for those +who will not listen or who do not care about the development process. + +It is hoped that those who read this document will be able to avoid that +frustrating experience. There is a lot of material here, but the effort +involved in reading it will be repaid in short order. The development +community is always in need of developers who will help to make the kernel +better; the following text should help you - or those who work for you - +join our community. + +Credits +------- + +This document was written by Jonathan Corbet, corbet@lwn.net. It has been +improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland +Dreier, Randy Dunlap, Jake Edge, Jiri Kosina, Matt Mackall, Arthur Marsh, +Amanda McPherson, Andrew Morton, Andrew Price, Tsugikazu Shibata, and +Jochen Voß. + +This work was supported by the Linux Foundation; thanks especially to +Amanda McPherson, who saw the value of this effort and made it all happen. + +The importance of getting code into the mainline +------------------------------------------------ + +Some companies and developers occasionally wonder why they should bother +learning how to work with the kernel community and get their code into the +mainline kernel (the "mainline" being the kernel maintained by Linus +Torvalds and used as a base by Linux distributors). In the short term, +contributing code can look like an avoidable expense; it seems easier to +just keep the code separate and support users directly. The truth of the +matter is that keeping code separate ("out of tree") is a false economy. + +As a way of illustrating the costs of out-of-tree code, here are a few +relevant aspects of the kernel development process; most of these will be +discussed in greater detail later in this document. Consider: + +- Code which has been merged into the mainline kernel is available to all + Linux users. It will automatically be present on all distributions which + enable it. There is no need for driver disks, downloads, or the hassles + of supporting multiple versions of multiple distributions; it all just + works, for the developer and for the user. Incorporation into the + mainline solves a large number of distribution and support problems. + +- While kernel developers strive to maintain a stable interface to user + space, the internal kernel API is in constant flux. The lack of a stable + internal interface is a deliberate design decision; it allows fundamental + improvements to be made at any time and results in higher-quality code. + But one result of that policy is that any out-of-tree code requires + constant upkeep if it is to work with new kernels. Maintaining + out-of-tree code requires significant amounts of work just to keep that + code working. + + Code which is in the mainline, instead, does not require this work as the + result of a simple rule requiring any developer who makes an API change + to also fix any code that breaks as the result of that change. So code + which has been merged into the mainline has significantly lower + maintenance costs. + +- Beyond that, code which is in the kernel will often be improved by other + developers. Surprising results can come from empowering your user + community and customers to improve your product. + +- Kernel code is subjected to review, both before and after merging into + the mainline. No matter how strong the original developer's skills are, + this review process invariably finds ways in which the code can be + improved. Often review finds severe bugs and security problems. This is + especially true for code which has been developed in a closed + environment; such code benefits strongly from review by outside + developers. Out-of-tree code is lower-quality code. + +- Participation in the development process is your way to influence the + direction of kernel development. Users who complain from the sidelines + are heard, but active developers have a stronger voice - and the ability + to implement changes which make the kernel work better for their needs. + +- When code is maintained separately, the possibility that a third party + will contribute a different implementation of a similar feature always + exists. Should that happen, getting your code merged will become much + harder - to the point of impossibility. Then you will be faced with the + unpleasant alternatives of either (1) maintaining a nonstandard feature + out of tree indefinitely, or (2) abandoning your code and migrating your + users over to the in-tree version. + +- Contribution of code is the fundamental action which makes the whole + process work. By contributing your code you can add new functionality to + the kernel and provide capabilities and examples which are of use to + other kernel developers. If you have developed code for Linux (or are + thinking about doing so), you clearly have an interest in the continued + success of this platform; contributing code is one of the best ways to + help ensure that success. + +All of the reasoning above applies to any out-of-tree kernel code, +including code which is distributed in proprietary, binary-only form. +There are, however, additional factors which should be taken into account +before considering any sort of binary-only kernel code distribution. These +include: + +- The legal issues around the distribution of proprietary kernel modules + are cloudy at best; quite a few kernel copyright holders believe that + most binary-only modules are derived products of the kernel and that, as + a result, their distribution is a violation of the GNU General Public + license (about which more will be said below). Your author is not a + lawyer, and nothing in this document can possibly be considered to be + legal advice. The true legal status of closed-source modules can only be + determined by the courts. But the uncertainty which haunts those modules + is there regardless. + +- Binary modules greatly increase the difficulty of debugging kernel + problems, to the point that most kernel developers will not even try. So + the distribution of binary-only modules will make it harder for your + users to get support from the community. + +- Support is also harder for distributors of binary-only modules, who must + provide a version of the module for every distribution and every kernel + version they wish to support. Dozens of builds of a single module can + be required to provide reasonably comprehensive coverage, and your users + will have to upgrade your module separately every time they upgrade their + kernel. + +- Everything that was said above about code review applies doubly to + closed-source code. Since this code is not available at all, it cannot + have been reviewed by the community and will, beyond doubt, have serious + problems. + +Makers of embedded systems, in particular, may be tempted to disregard much +of what has been said in this section in the belief that they are shipping +a self-contained product which uses a frozen kernel version and requires no +more development after its release. This argument misses the value of +widespread code review and the value of allowing your users to add +capabilities to your product. But these products, too, have a limited +commercial life, after which a new version must be released. At that +point, vendors whose code is in the mainline and well maintained will be +much better positioned to get the new product ready for market quickly. + +Licensing +--------- + +Code is contributed to the Linux kernel under a number of licenses, but all +code must be compatible with version 2 of the GNU General Public License +(GPLv2), which is the license covering the kernel distribution as a whole. +In practice, that means that all code contributions are covered either by +GPLv2 (with, optionally, language allowing distribution under later +versions of the GPL) or the three-clause BSD license. Any contributions +which are not covered by a compatible license will not be accepted into the +kernel. + +Copyright assignments are not required (or requested) for code contributed +to the kernel. All code merged into the mainline kernel retains its +original ownership; as a result, the kernel now has thousands of owners. + +One implication of this ownership structure is that any attempt to change +the licensing of the kernel is doomed to almost certain failure. There are +few practical scenarios where the agreement of all copyright holders could +be obtained (or their code removed from the kernel). So, in particular, +there is no prospect of a migration to version 3 of the GPL in the +foreseeable future. + +It is imperative that all code contributed to the kernel be legitimately +free software. For that reason, code from anonymous (or pseudonymous) +contributors will not be accepted. All contributors are required to "sign +off" on their code, stating that the code can be distributed with the +kernel under the GPL. Code which has not been licensed as free software by +its owner, or which risks creating copyright-related problems for the +kernel (such as code which derives from reverse-engineering efforts lacking +proper safeguards) cannot be contributed. + +Questions about copyright-related issues are common on Linux development +mailing lists. Such questions will normally receive no shortage of +answers, but one should bear in mind that the people answering those +questions are not lawyers and cannot provide legal advice. If you have +legal questions relating to Linux source code, there is no substitute for +talking with a lawyer who understands this field. Relying on answers +obtained on technical mailing lists is a risky affair. diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst new file mode 100644 index 000000000000..ce5561bb3f8e --- /dev/null +++ b/Documentation/process/2.Process.rst @@ -0,0 +1,497 @@ +.. _development_process: + +How the development process works +================================= + +Linux kernel development in the early 1990's was a pretty loose affair, +with relatively small numbers of users and developers involved. With a +user base in the millions and with some 2,000 developers involved over the +course of one year, the kernel has since had to evolve a number of +processes to keep development happening smoothly. A solid understanding of +how the process works is required in order to be an effective part of it. + +The big picture +--------------- + +The kernel developers use a loosely time-based release process, with a new +major kernel release happening every two or three months. The recent +release history looks like this: + + ====== ================= + 2.6.38 March 14, 2011 + 2.6.37 January 4, 2011 + 2.6.36 October 20, 2010 + 2.6.35 August 1, 2010 + 2.6.34 May 15, 2010 + 2.6.33 February 24, 2010 + ====== ================= + +Every 2.6.x release is a major kernel release with new features, internal +API changes, and more. A typical 2.6 release can contain nearly 10,000 +changesets with changes to several hundred thousand lines of code. 2.6 is +thus the leading edge of Linux kernel development; the kernel uses a +rolling development model which is continually integrating major changes. + +A relatively straightforward discipline is followed with regard to the +merging of patches for each release. At the beginning of each development +cycle, the "merge window" is said to be open. At that time, code which is +deemed to be sufficiently stable (and which is accepted by the development +community) is merged into the mainline kernel. The bulk of changes for a +new development cycle (and all of the major changes) will be merged during +this time, at a rate approaching 1,000 changes ("patches," or "changesets") +per day. + +(As an aside, it is worth noting that the changes integrated during the +merge window do not come out of thin air; they have been collected, tested, +and staged ahead of time. How that process works will be described in +detail later on). + +The merge window lasts for approximately two weeks. At the end of this +time, Linus Torvalds will declare that the window is closed and release the +first of the "rc" kernels. For the kernel which is destined to be 2.6.40, +for example, the release which happens at the end of the merge window will +be called 2.6.40-rc1. The -rc1 release is the signal that the time to +merge new features has passed, and that the time to stabilize the next +kernel has begun. + +Over the next six to ten weeks, only patches which fix problems should be +submitted to the mainline. On occasion a more significant change will be +allowed, but such occasions are rare; developers who try to merge new +features outside of the merge window tend to get an unfriendly reception. +As a general rule, if you miss the merge window for a given feature, the +best thing to do is to wait for the next development cycle. (An occasional +exception is made for drivers for previously-unsupported hardware; if they +touch no in-tree code, they cannot cause regressions and should be safe to +add at any time). + +As fixes make their way into the mainline, the patch rate will slow over +time. Linus releases new -rc kernels about once a week; a normal series +will get up to somewhere between -rc6 and -rc9 before the kernel is +considered to be sufficiently stable and the final 2.6.x release is made. +At that point the whole process starts over again. + +As an example, here is how the 2.6.38 development cycle went (all dates in +2011): + + ============== =============================== + January 4 2.6.37 stable release + January 18 2.6.38-rc1, merge window closes + January 21 2.6.38-rc2 + February 1 2.6.38-rc3 + February 7 2.6.38-rc4 + February 15 2.6.38-rc5 + February 21 2.6.38-rc6 + March 1 2.6.38-rc7 + March 7 2.6.38-rc8 + March 14 2.6.38 stable release + ============== =============================== + +How do the developers decide when to close the development cycle and create +the stable release? The most significant metric used is the list of +regressions from previous releases. No bugs are welcome, but those which +break systems which worked in the past are considered to be especially +serious. For this reason, patches which cause regressions are looked upon +unfavorably and are quite likely to be reverted during the stabilization +period. + +The developers' goal is to fix all known regressions before the stable +release is made. In the real world, this kind of perfection is hard to +achieve; there are just too many variables in a project of this size. +There comes a point where delaying the final release just makes the problem +worse; the pile of changes waiting for the next merge window will grow +larger, creating even more regressions the next time around. So most 2.6.x +kernels go out with a handful of known regressions though, hopefully, none +of them are serious. + +Once a stable release is made, its ongoing maintenance is passed off to the +"stable team," currently consisting of Greg Kroah-Hartman. The stable team +will release occasional updates to the stable release using the 2.6.x.y +numbering scheme. To be considered for an update release, a patch must (1) +fix a significant bug, and (2) already be merged into the mainline for the +next development kernel. Kernels will typically receive stable updates for +a little more than one development cycle past their initial release. So, +for example, the 2.6.36 kernel's history looked like: + + ============== =============================== + October 10 2.6.36 stable release + November 22 2.6.36.1 + December 9 2.6.36.2 + January 7 2.6.36.3 + February 17 2.6.36.4 + ============== =============================== + +2.6.36.4 was the final stable update for the 2.6.36 release. + +Some kernels are designated "long term" kernels; they will receive support +for a longer period. As of this writing, the current long term kernels +and their maintainers are: + + ====== ====================== =========================== + 2.6.27 Willy Tarreau (Deep-frozen stable kernel) + 2.6.32 Greg Kroah-Hartman + 2.6.35 Andi Kleen (Embedded flag kernel) + ====== ====================== =========================== + +The selection of a kernel for long-term support is purely a matter of a +maintainer having the need and the time to maintain that release. There +are no known plans for long-term support for any specific upcoming +release. + + +The lifecycle of a patch +------------------------ + +Patches do not go directly from the developer's keyboard into the mainline +kernel. There is, instead, a somewhat involved (if somewhat informal) +process designed to ensure that each patch is reviewed for quality and that +each patch implements a change which is desirable to have in the mainline. +This process can happen quickly for minor fixes, or, in the case of large +and controversial changes, go on for years. Much developer frustration +comes from a lack of understanding of this process or from attempts to +circumvent it. + +In the hopes of reducing that frustration, this document will describe how +a patch gets into the kernel. What follows below is an introduction which +describes the process in a somewhat idealized way. A much more detailed +treatment will come in later sections. + +The stages that a patch goes through are, generally: + + - Design. This is where the real requirements for the patch - and the way + those requirements will be met - are laid out. Design work is often + done without involving the community, but it is better to do this work + in the open if at all possible; it can save a lot of time redesigning + things later. + + - Early review. Patches are posted to the relevant mailing list, and + developers on that list reply with any comments they may have. This + process should turn up any major problems with a patch if all goes + well. + + - Wider review. When the patch is getting close to ready for mainline + inclusion, it should be accepted by a relevant subsystem maintainer - + though this acceptance is not a guarantee that the patch will make it + all the way to the mainline. The patch will show up in the maintainer's + subsystem tree and into the -next trees (described below). When the + process works, this step leads to more extensive review of the patch and + the discovery of any problems resulting from the integration of this + patch with work being done by others. + +- Please note that most maintainers also have day jobs, so merging + your patch may not be their highest priority. If your patch is + getting feedback about changes that are needed, you should either + make those changes or justify why they should not be made. If your + patch has no review complaints but is not being merged by its + appropriate subsystem or driver maintainer, you should be persistent + in updating the patch to the current kernel so that it applies cleanly + and keep sending it for review and merging. + + - Merging into the mainline. Eventually, a successful patch will be + merged into the mainline repository managed by Linus Torvalds. More + comments and/or problems may surface at this time; it is important that + the developer be responsive to these and fix any issues which arise. + + - Stable release. The number of users potentially affected by the patch + is now large, so, once again, new problems may arise. + + - Long-term maintenance. While it is certainly possible for a developer + to forget about code after merging it, that sort of behavior tends to + leave a poor impression in the development community. Merging code + eliminates some of the maintenance burden, in that others will fix + problems caused by API changes. But the original developer should + continue to take responsibility for the code if it is to remain useful + in the longer term. + +One of the largest mistakes made by kernel developers (or their employers) +is to try to cut the process down to a single "merging into the mainline" +step. This approach invariably leads to frustration for everybody +involved. + +How patches get into the Kernel +------------------------------- + +There is exactly one person who can merge patches into the mainline kernel +repository: Linus Torvalds. But, of the over 9,500 patches which went +into the 2.6.38 kernel, only 112 (around 1.3%) were directly chosen by Linus +himself. The kernel project has long since grown to a size where no single +developer could possibly inspect and select every patch unassisted. The +way the kernel developers have addressed this growth is through the use of +a lieutenant system built around a chain of trust. + +The kernel code base is logically broken down into a set of subsystems: +networking, specific architecture support, memory management, video +devices, etc. Most subsystems have a designated maintainer, a developer +who has overall responsibility for the code within that subsystem. These +subsystem maintainers are the gatekeepers (in a loose way) for the portion +of the kernel they manage; they are the ones who will (usually) accept a +patch for inclusion into the mainline kernel. + +Subsystem maintainers each manage their own version of the kernel source +tree, usually (but certainly not always) using the git source management +tool. Tools like git (and related tools like quilt or mercurial) allow +maintainers to track a list of patches, including authorship information +and other metadata. At any given time, the maintainer can identify which +patches in his or her repository are not found in the mainline. + +When the merge window opens, top-level maintainers will ask Linus to "pull" +the patches they have selected for merging from their repositories. If +Linus agrees, the stream of patches will flow up into his repository, +becoming part of the mainline kernel. The amount of attention that Linus +pays to specific patches received in a pull operation varies. It is clear +that, sometimes, he looks quite closely. But, as a general rule, Linus +trusts the subsystem maintainers to not send bad patches upstream. + +Subsystem maintainers, in turn, can pull patches from other maintainers. +For example, the networking tree is built from patches which accumulated +first in trees dedicated to network device drivers, wireless networking, +etc. This chain of repositories can be arbitrarily long, though it rarely +exceeds two or three links. Since each maintainer in the chain trusts +those managing lower-level trees, this process is known as the "chain of +trust." + +Clearly, in a system like this, getting patches into the kernel depends on +finding the right maintainer. Sending patches directly to Linus is not +normally the right way to go. + + +Next trees +---------- + +The chain of subsystem trees guides the flow of patches into the kernel, +but it also raises an interesting question: what if somebody wants to look +at all of the patches which are being prepared for the next merge window? +Developers will be interested in what other changes are pending to see +whether there are any conflicts to worry about; a patch which changes a +core kernel function prototype, for example, will conflict with any other +patches which use the older form of that function. Reviewers and testers +want access to the changes in their integrated form before all of those +changes land in the mainline kernel. One could pull changes from all of +the interesting subsystem trees, but that would be a big and error-prone +job. + +The answer comes in the form of -next trees, where subsystem trees are +collected for testing and review. The older of these trees, maintained by +Andrew Morton, is called "-mm" (for memory management, which is how it got +started). The -mm tree integrates patches from a long list of subsystem +trees; it also has some patches aimed at helping with debugging. + +Beyond that, -mm contains a significant collection of patches which have +been selected by Andrew directly. These patches may have been posted on a +mailing list, or they may apply to a part of the kernel for which there is +no designated subsystem tree. As a result, -mm operates as a sort of +subsystem tree of last resort; if there is no other obvious path for a +patch into the mainline, it is likely to end up in -mm. Miscellaneous +patches which accumulate in -mm will eventually either be forwarded on to +an appropriate subsystem tree or be sent directly to Linus. In a typical +development cycle, approximately 5-10% of the patches going into the +mainline get there via -mm. + +The current -mm patch is available in the "mmotm" (-mm of the moment) +directory at: + + http://www.ozlabs.org/~akpm/mmotm/ + +Use of the MMOTM tree is likely to be a frustrating experience, though; +there is a definite chance that it will not even compile. + +The primary tree for next-cycle patch merging is linux-next, maintained by +Stephen Rothwell. The linux-next tree is, by design, a snapshot of what +the mainline is expected to look like after the next merge window closes. +Linux-next trees are announced on the linux-kernel and linux-next mailing +lists when they are assembled; they can be downloaded from: + + http://www.kernel.org/pub/linux/kernel/next/ + +Linux-next has become an integral part of the kernel development process; +all patches merged during a given merge window should really have found +their way into linux-next some time before the merge window opens. + + +Staging trees +------------- + +The kernel source tree contains the drivers/staging/ directory, where +many sub-directories for drivers or filesystems that are on their way to +being added to the kernel tree live. They remain in drivers/staging while +they still need more work; once complete, they can be moved into the +kernel proper. This is a way to keep track of drivers that aren't +up to Linux kernel coding or quality standards, but people may want to use +them and track development. + +Greg Kroah-Hartman currently maintains the staging tree. Drivers that +still need work are sent to him, with each driver having its own +subdirectory in drivers/staging/. Along with the driver source files, a +TODO file should be present in the directory as well. The TODO file lists +the pending work that the driver needs for acceptance into the kernel +proper, as well as a list of people that should be Cc'd for any patches to +the driver. Current rules require that drivers contributed to staging +must, at a minimum, compile properly. + +Staging can be a relatively easy way to get new drivers into the mainline +where, with luck, they will come to the attention of other developers and +improve quickly. Entry into staging is not the end of the story, though; +code in staging which is not seeing regular progress will eventually be +removed. Distributors also tend to be relatively reluctant to enable +staging drivers. So staging is, at best, a stop on the way toward becoming +a proper mainline driver. + + +Tools +----- + +As can be seen from the above text, the kernel development process depends +heavily on the ability to herd collections of patches in various +directions. The whole thing would not work anywhere near as well as it +does without suitably powerful tools. Tutorials on how to use these tools +are well beyond the scope of this document, but there is space for a few +pointers. + +By far the dominant source code management system used by the kernel +community is git. Git is one of a number of distributed version control +systems being developed in the free software community. It is well tuned +for kernel development, in that it performs quite well when dealing with +large repositories and large numbers of patches. It also has a reputation +for being difficult to learn and use, though it has gotten better over +time. Some sort of familiarity with git is almost a requirement for kernel +developers; even if they do not use it for their own work, they'll need git +to keep up with what other developers (and the mainline) are doing. + +Git is now packaged by almost all Linux distributions. There is a home +page at: + + http://git-scm.com/ + +That page has pointers to documentation and tutorials. + +Among the kernel developers who do not use git, the most popular choice is +almost certainly Mercurial: + + http://www.selenic.com/mercurial/ + +Mercurial shares many features with git, but it provides an interface which +many find easier to use. + +The other tool worth knowing about is Quilt: + + http://savannah.nongnu.org/projects/quilt/ + +Quilt is a patch management system, rather than a source code management +system. It does not track history over time; it is, instead, oriented +toward tracking a specific set of changes against an evolving code base. +Some major subsystem maintainers use quilt to manage patches intended to go +upstream. For the management of certain kinds of trees (-mm, for example), +quilt is the best tool for the job. + + +Mailing lists +------------- + +A great deal of Linux kernel development work is done by way of mailing +lists. It is hard to be a fully-functioning member of the community +without joining at least one list somewhere. But Linux mailing lists also +represent a potential hazard to developers, who risk getting buried under a +load of electronic mail, running afoul of the conventions used on the Linux +lists, or both. + +Most kernel mailing lists are run on vger.kernel.org; the master list can +be found at: + + http://vger.kernel.org/vger-lists.html + +There are lists hosted elsewhere, though; a number of them are at +lists.redhat.com. + +The core mailing list for kernel development is, of course, linux-kernel. +This list is an intimidating place to be; volume can reach 500 messages per +day, the amount of noise is high, the conversation can be severely +technical, and participants are not always concerned with showing a high +degree of politeness. But there is no other place where the kernel +development community comes together as a whole; developers who avoid this +list will miss important information. + +There are a few hints which can help with linux-kernel survival: + +- Have the list delivered to a separate folder, rather than your main + mailbox. One must be able to ignore the stream for sustained periods of + time. + +- Do not try to follow every conversation - nobody else does. It is + important to filter on both the topic of interest (though note that + long-running conversations can drift away from the original subject + without changing the email subject line) and the people who are + participating. + +- Do not feed the trolls. If somebody is trying to stir up an angry + response, ignore them. + +- When responding to linux-kernel email (or that on other lists) preserve + the Cc: header for all involved. In the absence of a strong reason (such + as an explicit request), you should never remove recipients. Always make + sure that the person you are responding to is in the Cc: list. This + convention also makes it unnecessary to explicitly ask to be copied on + replies to your postings. + +- Search the list archives (and the net as a whole) before asking + questions. Some developers can get impatient with people who clearly + have not done their homework. + +- Avoid top-posting (the practice of putting your answer above the quoted + text you are responding to). It makes your response harder to read and + makes a poor impression. + +- Ask on the correct mailing list. Linux-kernel may be the general meeting + point, but it is not the best place to find developers from all + subsystems. + +The last point - finding the correct mailing list - is a common place for +beginning developers to go wrong. Somebody who asks a networking-related +question on linux-kernel will almost certainly receive a polite suggestion +to ask on the netdev list instead, as that is the list frequented by most +networking developers. Other lists exist for the SCSI, video4linux, IDE, +filesystem, etc. subsystems. The best place to look for mailing lists is +in the MAINTAINERS file packaged with the kernel source. + + +Getting started with Kernel development +--------------------------------------- + +Questions about how to get started with the kernel development process are +common - from both individuals and companies. Equally common are missteps +which make the beginning of the relationship harder than it has to be. + +Companies often look to hire well-known developers to get a development +group started. This can, in fact, be an effective technique. But it also +tends to be expensive and does not do much to grow the pool of experienced +kernel developers. It is possible to bring in-house developers up to speed +on Linux kernel development, given the investment of a bit of time. Taking +this time can endow an employer with a group of developers who understand +the kernel and the company both, and who can help to train others as well. +Over the medium term, this is often the more profitable approach. + +Individual developers are often, understandably, at a loss for a place to +start. Beginning with a large project can be intimidating; one often wants +to test the waters with something smaller first. This is the point where +some developers jump into the creation of patches fixing spelling errors or +minor coding style issues. Unfortunately, such patches create a level of +noise which is distracting for the development community as a whole, so, +increasingly, they are looked down upon. New developers wishing to +introduce themselves to the community will not get the sort of reception +they wish for by these means. + +Andrew Morton gives this advice for aspiring kernel developers + +:: + + The #1 project for all kernel beginners should surely be "make sure + that the kernel runs perfectly at all times on all machines which + you can lay your hands on". Usually the way to do this is to work + with others on getting things fixed up (this can require + persistence!) but that's fine - it's a part of kernel development. + +(http://lwn.net/Articles/283982/). + +In the absence of obvious problems to fix, developers are advised to look +at the current lists of regressions and open bugs in general. There is +never any shortage of issues in need of fixing; by addressing these issues, +developers will gain experience with the process while, at the same time, +building respect with the rest of the development community. diff --git a/Documentation/process/3.Early-stage.rst b/Documentation/process/3.Early-stage.rst new file mode 100644 index 000000000000..af2c0af931d6 --- /dev/null +++ b/Documentation/process/3.Early-stage.rst @@ -0,0 +1,222 @@ +.. _development_early_stage: + +Early-stage planning +==================== + +When contemplating a Linux kernel development project, it can be tempting +to jump right in and start coding. As with any significant project, +though, much of the groundwork for success is best laid before the first +line of code is written. Some time spent in early planning and +communication can save far more time later on. + + +Specifying the problem +---------------------- + +Like any engineering project, a successful kernel enhancement starts with a +clear description of the problem to be solved. In some cases, this step is +easy: when a driver is needed for a specific piece of hardware, for +example. In others, though, it is tempting to confuse the real problem +with the proposed solution, and that can lead to difficulties. + +Consider an example: some years ago, developers working with Linux audio +sought a way to run applications without dropouts or other artifacts caused +by excessive latency in the system. The solution they arrived at was a +kernel module intended to hook into the Linux Security Module (LSM) +framework; this module could be configured to give specific applications +access to the realtime scheduler. This module was implemented and sent to +the linux-kernel mailing list, where it immediately ran into problems. + +To the audio developers, this security module was sufficient to solve their +immediate problem. To the wider kernel community, though, it was seen as a +misuse of the LSM framework (which is not intended to confer privileges +onto processes which they would not otherwise have) and a risk to system +stability. Their preferred solutions involved realtime scheduling access +via the rlimit mechanism for the short term, and ongoing latency reduction +work in the long term. + +The audio community, however, could not see past the particular solution +they had implemented; they were unwilling to accept alternatives. The +resulting disagreement left those developers feeling disillusioned with the +entire kernel development process; one of them went back to an audio list +and posted this: + + There are a number of very good Linux kernel developers, but they + tend to get outshouted by a large crowd of arrogant fools. Trying + to communicate user requirements to these people is a waste of + time. They are much too "intelligent" to listen to lesser mortals. + +(http://lwn.net/Articles/131776/). + +The reality of the situation was different; the kernel developers were far +more concerned about system stability, long-term maintenance, and finding +the right solution to the problem than they were with a specific module. +The moral of the story is to focus on the problem - not a specific solution +- and to discuss it with the development community before investing in the +creation of a body of code. + +So, when contemplating a kernel development project, one should obtain +answers to a short set of questions: + + - What, exactly, is the problem which needs to be solved? + + - Who are the users affected by this problem? Which use cases should the + solution address? + + - How does the kernel fall short in addressing that problem now? + +Only then does it make sense to start considering possible solutions. + + +Early discussion +---------------- + +When planning a kernel development project, it makes great sense to hold +discussions with the community before launching into implementation. Early +communication can save time and trouble in a number of ways: + + - It may well be that the problem is addressed by the kernel in ways which + you have not understood. The Linux kernel is large and has a number of + features and capabilities which are not immediately obvious. Not all + kernel capabilities are documented as well as one might like, and it is + easy to miss things. Your author has seen the posting of a complete + driver which duplicated an existing driver that the new author had been + unaware of. Code which reinvents existing wheels is not only wasteful; + it will also not be accepted into the mainline kernel. + + - There may be elements of the proposed solution which will not be + acceptable for mainline merging. It is better to find out about + problems like this before writing the code. + + - It's entirely possible that other developers have thought about the + problem; they may have ideas for a better solution, and may be willing + to help in the creation of that solution. + +Years of experience with the kernel development community have taught a +clear lesson: kernel code which is designed and developed behind closed +doors invariably has problems which are only revealed when the code is +released into the community. Sometimes these problems are severe, +requiring months or years of effort before the code can be brought up to +the kernel community's standards. Some examples include: + + - The Devicescape network stack was designed and implemented for + single-processor systems. It could not be merged into the mainline + until it was made suitable for multiprocessor systems. Retrofitting + locking and such into code is a difficult task; as a result, the merging + of this code (now called mac80211) was delayed for over a year. + + - The Reiser4 filesystem included a number of capabilities which, in the + core kernel developers' opinion, should have been implemented in the + virtual filesystem layer instead. It also included features which could + not easily be implemented without exposing the system to user-caused + deadlocks. The late revelation of these problems - and refusal to + address some of them - has caused Reiser4 to stay out of the mainline + kernel. + + - The AppArmor security module made use of internal virtual filesystem + data structures in ways which were considered to be unsafe and + unreliable. This concern (among others) kept AppArmor out of the + mainline for years. + +In each of these cases, a great deal of pain and extra work could have been +avoided with some early discussion with the kernel developers. + + +Who do you talk to? +------------------- + +When developers decide to take their plans public, the next question will +be: where do we start? The answer is to find the right mailing list(s) and +the right maintainer. For mailing lists, the best approach is to look in +the MAINTAINERS file for a relevant place to post. If there is a suitable +subsystem list, posting there is often preferable to posting on +linux-kernel; you are more likely to reach developers with expertise in the +relevant subsystem and the environment may be more supportive. + +Finding maintainers can be a bit harder. Again, the MAINTAINERS file is +the place to start. That file tends to not always be up to date, though, +and not all subsystems are represented there. The person listed in the +MAINTAINERS file may, in fact, not be the person who is actually acting in +that role currently. So, when there is doubt about who to contact, a +useful trick is to use git (and "git log" in particular) to see who is +currently active within the subsystem of interest. Look at who is writing +patches, and who, if anybody, is attaching Signed-off-by lines to those +patches. Those are the people who will be best placed to help with a new +development project. + +The task of finding the right maintainer is sometimes challenging enough +that the kernel developers have added a script to ease the process: + +:: + + .../scripts/get_maintainer.pl + +This script will return the current maintainer(s) for a given file or +directory when given the "-f" option. If passed a patch on the +command line, it will list the maintainers who should probably receive +copies of the patch. There are a number of options regulating how hard +get_maintainer.pl will search for maintainers; please be careful about +using the more aggressive options as you may end up including developers +who have no real interest in the code you are modifying. + +If all else fails, talking to Andrew Morton can be an effective way to +track down a maintainer for a specific piece of code. + + +When to post? +------------- + +If possible, posting your plans during the early stages can only be +helpful. Describe the problem being solved and any plans that have been +made on how the implementation will be done. Any information you can +provide can help the development community provide useful input on the +project. + +One discouraging thing which can happen at this stage is not a hostile +reaction, but, instead, little or no reaction at all. The sad truth of the +matter is (1) kernel developers tend to be busy, (2) there is no shortage +of people with grand plans and little code (or even prospect of code) to +back them up, and (3) nobody is obligated to review or comment on ideas +posted by others. Beyond that, high-level designs often hide problems +which are only reviewed when somebody actually tries to implement those +designs; for that reason, kernel developers would rather see the code. + +If a request-for-comments posting yields little in the way of comments, do +not assume that it means there is no interest in the project. +Unfortunately, you also cannot assume that there are no problems with your +idea. The best thing to do in this situation is to proceed, keeping the +community informed as you go. + + +Getting official buy-in +----------------------- + +If your work is being done in a corporate environment - as most Linux +kernel work is - you must, obviously, have permission from suitably +empowered managers before you can post your company's plans or code to a +public mailing list. The posting of code which has not been cleared for +release under a GPL-compatible license can be especially problematic; the +sooner that a company's management and legal staff can agree on the posting +of a kernel development project, the better off everybody involved will be. + +Some readers may be thinking at this point that their kernel work is +intended to support a product which does not yet have an officially +acknowledged existence. Revealing their employer's plans on a public +mailing list may not be a viable option. In cases like this, it is worth +considering whether the secrecy is really necessary; there is often no real +need to keep development plans behind closed doors. + +That said, there are also cases where a company legitimately cannot +disclose its plans early in the development process. Companies with +experienced kernel developers may choose to proceed in an open-loop manner +on the assumption that they will be able to avoid serious integration +problems later. For companies without that sort of in-house expertise, the +best option is often to hire an outside developer to review the plans under +a non-disclosure agreement. The Linux Foundation operates an NDA program +designed to help with this sort of situation; more information can be found +at: + + http://www.linuxfoundation.org/en/NDA_program + +This kind of review is often enough to avoid serious problems later on +without requiring public disclosure of the project. diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst new file mode 100644 index 000000000000..9d5cef996f7f --- /dev/null +++ b/Documentation/process/4.Coding.rst @@ -0,0 +1,413 @@ +.. _development_coding: + +Getting the code right +====================== + +While there is much to be said for a solid and community-oriented design +process, the proof of any kernel development project is in the resulting +code. It is the code which will be examined by other developers and merged +(or not) into the mainline tree. So it is the quality of this code which +will determine the ultimate success of the project. + +This section will examine the coding process. We'll start with a look at a +number of ways in which kernel developers can go wrong. Then the focus +will shift toward doing things right and the tools which can help in that +quest. + + +Pitfalls +--------- + +Coding style +************ + +The kernel has long had a standard coding style, described in +Documentation/CodingStyle. For much of that time, the policies described +in that file were taken as being, at most, advisory. As a result, there is +a substantial amount of code in the kernel which does not meet the coding +style guidelines. The presence of that code leads to two independent +hazards for kernel developers. + +The first of these is to believe that the kernel coding standards do not +matter and are not enforced. The truth of the matter is that adding new +code to the kernel is very difficult if that code is not coded according to +the standard; many developers will request that the code be reformatted +before they will even review it. A code base as large as the kernel +requires some uniformity of code to make it possible for developers to +quickly understand any part of it. So there is no longer room for +strangely-formatted code. + +Occasionally, the kernel's coding style will run into conflict with an +employer's mandated style. In such cases, the kernel's style will have to +win before the code can be merged. Putting code into the kernel means +giving up a degree of control in a number of ways - including control over +how the code is formatted. + +The other trap is to assume that code which is already in the kernel is +urgently in need of coding style fixes. Developers may start to generate +reformatting patches as a way of gaining familiarity with the process, or +as a way of getting their name into the kernel changelogs - or both. But +pure coding style fixes are seen as noise by the development community; +they tend to get a chilly reception. So this type of patch is best +avoided. It is natural to fix the style of a piece of code while working +on it for other reasons, but coding style changes should not be made for +their own sake. + +The coding style document also should not be read as an absolute law which +can never be transgressed. If there is a good reason to go against the +style (a line which becomes far less readable if split to fit within the +80-column limit, for example), just do it. + + +Abstraction layers +****************** + +Computer Science professors teach students to make extensive use of +abstraction layers in the name of flexibility and information hiding. +Certainly the kernel makes extensive use of abstraction; no project +involving several million lines of code could do otherwise and survive. +But experience has shown that excessive or premature abstraction can be +just as harmful as premature optimization. Abstraction should be used to +the level required and no further. + +At a simple level, consider a function which has an argument which is +always passed as zero by all callers. One could retain that argument just +in case somebody eventually needs to use the extra flexibility that it +provides. By that time, though, chances are good that the code which +implements this extra argument has been broken in some subtle way which was +never noticed - because it has never been used. Or, when the need for +extra flexibility arises, it does not do so in a way which matches the +programmer's early expectation. Kernel developers will routinely submit +patches to remove unused arguments; they should, in general, not be added +in the first place. + +Abstraction layers which hide access to hardware - often to allow the bulk +of a driver to be used with multiple operating systems - are especially +frowned upon. Such layers obscure the code and may impose a performance +penalty; they do not belong in the Linux kernel. + +On the other hand, if you find yourself copying significant amounts of code +from another kernel subsystem, it is time to ask whether it would, in fact, +make sense to pull out some of that code into a separate library or to +implement that functionality at a higher level. There is no value in +replicating the same code throughout the kernel. + + +#ifdef and preprocessor use in general +************************************** + +The C preprocessor seems to present a powerful temptation to some C +programmers, who see it as a way to efficiently encode a great deal of +flexibility into a source file. But the preprocessor is not C, and heavy +use of it results in code which is much harder for others to read and +harder for the compiler to check for correctness. Heavy preprocessor use +is almost always a sign of code which needs some cleanup work. + +Conditional compilation with #ifdef is, indeed, a powerful feature, and it +is used within the kernel. But there is little desire to see code which is +sprinkled liberally with #ifdef blocks. As a general rule, #ifdef use +should be confined to header files whenever possible. +Conditionally-compiled code can be confined to functions which, if the code +is not to be present, simply become empty. The compiler will then quietly +optimize out the call to the empty function. The result is far cleaner +code which is easier to follow. + +C preprocessor macros present a number of hazards, including possible +multiple evaluation of expressions with side effects and no type safety. +If you are tempted to define a macro, consider creating an inline function +instead. The code which results will be the same, but inline functions are +easier to read, do not evaluate their arguments multiple times, and allow +the compiler to perform type checking on the arguments and return value. + + +Inline functions +**************** + +Inline functions present a hazard of their own, though. Programmers can +become enamored of the perceived efficiency inherent in avoiding a function +call and fill a source file with inline functions. Those functions, +however, can actually reduce performance. Since their code is replicated +at each call site, they end up bloating the size of the compiled kernel. +That, in turn, creates pressure on the processor's memory caches, which can +slow execution dramatically. Inline functions, as a rule, should be quite +small and relatively rare. The cost of a function call, after all, is not +that high; the creation of large numbers of inline functions is a classic +example of premature optimization. + +In general, kernel programmers ignore cache effects at their peril. The +classic time/space tradeoff taught in beginning data structures classes +often does not apply to contemporary hardware. Space *is* time, in that a +larger program will run slower than one which is more compact. + +More recent compilers take an increasingly active role in deciding whether +a given function should actually be inlined or not. So the liberal +placement of "inline" keywords may not just be excessive; it could also be +irrelevant. + + +Locking +******* + +In May, 2006, the "Devicescape" networking stack was, with great +fanfare, released under the GPL and made available for inclusion in the +mainline kernel. This donation was welcome news; support for wireless +networking in Linux was considered substandard at best, and the Devicescape +stack offered the promise of fixing that situation. Yet, this code did not +actually make it into the mainline until June, 2007 (2.6.22). What +happened? + +This code showed a number of signs of having been developed behind +corporate doors. But one large problem in particular was that it was not +designed to work on multiprocessor systems. Before this networking stack +(now called mac80211) could be merged, a locking scheme needed to be +retrofitted onto it. + +Once upon a time, Linux kernel code could be developed without thinking +about the concurrency issues presented by multiprocessor systems. Now, +however, this document is being written on a dual-core laptop. Even on +single-processor systems, work being done to improve responsiveness will +raise the level of concurrency within the kernel. The days when kernel +code could be written without thinking about locking are long past. + +Any resource (data structures, hardware registers, etc.) which could be +accessed concurrently by more than one thread must be protected by a lock. +New code should be written with this requirement in mind; retrofitting +locking after the fact is a rather more difficult task. Kernel developers +should take the time to understand the available locking primitives well +enough to pick the right tool for the job. Code which shows a lack of +attention to concurrency will have a difficult path into the mainline. + + +Regressions +*********** + +One final hazard worth mentioning is this: it can be tempting to make a +change (which may bring big improvements) which causes something to break +for existing users. This kind of change is called a "regression," and +regressions have become most unwelcome in the mainline kernel. With few +exceptions, changes which cause regressions will be backed out if the +regression cannot be fixed in a timely manner. Far better to avoid the +regression in the first place. + +It is often argued that a regression can be justified if it causes things +to work for more people than it creates problems for. Why not make a +change if it brings new functionality to ten systems for each one it +breaks? The best answer to this question was expressed by Linus in July, +2007: + +:: + + So we don't fix bugs by introducing new problems. That way lies + madness, and nobody ever knows if you actually make any real + progress at all. Is it two steps forwards, one step back, or one + step forward and two steps back? + +(http://lwn.net/Articles/243460/). + +An especially unwelcome type of regression is any sort of change to the +user-space ABI. Once an interface has been exported to user space, it must +be supported indefinitely. This fact makes the creation of user-space +interfaces particularly challenging: since they cannot be changed in +incompatible ways, they must be done right the first time. For this +reason, a great deal of thought, clear documentation, and wide review for +user-space interfaces is always required. + + +Code checking tools +------------------- + +For now, at least, the writing of error-free code remains an ideal that few +of us can reach. What we can hope to do, though, is to catch and fix as +many of those errors as possible before our code goes into the mainline +kernel. To that end, the kernel developers have put together an impressive +array of tools which can catch a wide variety of obscure problems in an +automated way. Any problem caught by the computer is a problem which will +not afflict a user later on, so it stands to reason that the automated +tools should be used whenever possible. + +The first step is simply to heed the warnings produced by the compiler. +Contemporary versions of gcc can detect (and warn about) a large number of +potential errors. Quite often, these warnings point to real problems. +Code submitted for review should, as a rule, not produce any compiler +warnings. When silencing warnings, take care to understand the real cause +and try to avoid "fixes" which make the warning go away without addressing +its cause. + +Note that not all compiler warnings are enabled by default. Build the +kernel with "make EXTRA_CFLAGS=-W" to get the full set. + +The kernel provides several configuration options which turn on debugging +features; most of these are found in the "kernel hacking" submenu. Several +of these options should be turned on for any kernel used for development or +testing purposes. In particular, you should turn on: + + - ENABLE_WARN_DEPRECATED, ENABLE_MUST_CHECK, and FRAME_WARN to get an + extra set of warnings for problems like the use of deprecated interfaces + or ignoring an important return value from a function. The output + generated by these warnings can be verbose, but one need not worry about + warnings from other parts of the kernel. + + - DEBUG_OBJECTS will add code to track the lifetime of various objects + created by the kernel and warn when things are done out of order. If + you are adding a subsystem which creates (and exports) complex objects + of its own, consider adding support for the object debugging + infrastructure. + + - DEBUG_SLAB can find a variety of memory allocation and use errors; it + should be used on most development kernels. + + - DEBUG_SPINLOCK, DEBUG_ATOMIC_SLEEP, and DEBUG_MUTEXES will find a + number of common locking errors. + +There are quite a few other debugging options, some of which will be +discussed below. Some of them have a significant performance impact and +should not be used all of the time. But some time spent learning the +available options will likely be paid back many times over in short order. + +One of the heavier debugging tools is the locking checker, or "lockdep." +This tool will track the acquisition and release of every lock (spinlock or +mutex) in the system, the order in which locks are acquired relative to +each other, the current interrupt environment, and more. It can then +ensure that locks are always acquired in the same order, that the same +interrupt assumptions apply in all situations, and so on. In other words, +lockdep can find a number of scenarios in which the system could, on rare +occasion, deadlock. This kind of problem can be painful (for both +developers and users) in a deployed system; lockdep allows them to be found +in an automated manner ahead of time. Code with any sort of non-trivial +locking should be run with lockdep enabled before being submitted for +inclusion. + +As a diligent kernel programmer, you will, beyond doubt, check the return +status of any operation (such as a memory allocation) which can fail. The +fact of the matter, though, is that the resulting failure recovery paths +are, probably, completely untested. Untested code tends to be broken code; +you could be much more confident of your code if all those error-handling +paths had been exercised a few times. + +The kernel provides a fault injection framework which can do exactly that, +especially where memory allocations are involved. With fault injection +enabled, a configurable percentage of memory allocations will be made to +fail; these failures can be restricted to a specific range of code. +Running with fault injection enabled allows the programmer to see how the +code responds when things go badly. See +Documentation/fault-injection/fault-injection.txt for more information on +how to use this facility. + +Other kinds of errors can be found with the "sparse" static analysis tool. +With sparse, the programmer can be warned about confusion between +user-space and kernel-space addresses, mixture of big-endian and +small-endian quantities, the passing of integer values where a set of bit +flags is expected, and so on. Sparse must be installed separately (it can +be found at https://sparse.wiki.kernel.org/index.php/Main_Page if your +distributor does not package it); it can then be run on the code by adding +"C=1" to your make command. + +The "Coccinelle" tool (http://coccinelle.lip6.fr/) is able to find a wide +variety of potential coding problems; it can also propose fixes for those +problems. Quite a few "semantic patches" for the kernel have been packaged +under the scripts/coccinelle directory; running "make coccicheck" will run +through those semantic patches and report on any problems found. See +Documentation/coccinelle.txt for more information. + +Other kinds of portability errors are best found by compiling your code for +other architectures. If you do not happen to have an S/390 system or a +Blackfin development board handy, you can still perform the compilation +step. A large set of cross compilers for x86 systems can be found at + + http://www.kernel.org/pub/tools/crosstool/ + +Some time spent installing and using these compilers will help avoid +embarrassment later. + + +Documentation +------------- + +Documentation has often been more the exception than the rule with kernel +development. Even so, adequate documentation will help to ease the merging +of new code into the kernel, make life easier for other developers, and +will be helpful for your users. In many cases, the addition of +documentation has become essentially mandatory. + +The first piece of documentation for any patch is its associated +changelog. Log entries should describe the problem being solved, the form +of the solution, the people who worked on the patch, any relevant +effects on performance, and anything else that might be needed to +understand the patch. Be sure that the changelog says *why* the patch is +worth applying; a surprising number of developers fail to provide that +information. + +Any code which adds a new user-space interface - including new sysfs or +/proc files - should include documentation of that interface which enables +user-space developers to know what they are working with. See +Documentation/ABI/README for a description of how this documentation should +be formatted and what information needs to be provided. + +The file Documentation/kernel-parameters.txt describes all of the kernel's +boot-time parameters. Any patch which adds new parameters should add the +appropriate entries to this file. + +Any new configuration options must be accompanied by help text which +clearly explains the options and when the user might want to select them. + +Internal API information for many subsystems is documented by way of +specially-formatted comments; these comments can be extracted and formatted +in a number of ways by the "kernel-doc" script. If you are working within +a subsystem which has kerneldoc comments, you should maintain them and add +them, as appropriate, for externally-available functions. Even in areas +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-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, +the expectations for new code are higher than they were in the past; +merging uncommented code will be harder. That said, there is little desire +for verbosely-commented code. The code should, itself, be readable, with +comments explaining the more subtle aspects. + +Certain things should always be commented. Uses of memory barriers should +be accompanied by a line explaining why the barrier is necessary. The +locking rules for data structures generally need to be explained somewhere. +Major data structures need comprehensive documentation in general. +Non-obvious dependencies between separate bits of code should be pointed +out. Anything which might tempt a code janitor to make an incorrect +"cleanup" needs a comment saying why it is done the way it is. And so on. + + +Internal API changes +-------------------- + +The binary interface provided by the kernel to user space cannot be broken +except under the most severe circumstances. The kernel's internal +programming interfaces, instead, are highly fluid and can be changed when +the need arises. If you find yourself having to work around a kernel API, +or simply not using a specific functionality because it does not meet your +needs, that may be a sign that the API needs to change. As a kernel +developer, you are empowered to make such changes. + +There are, of course, some catches. API changes can be made, but they need +to be well justified. So any patch making an internal API change should be +accompanied by a description of what the change is and why it is +necessary. This kind of change should also be broken out into a separate +patch, rather than buried within a larger patch. + +The other catch is that a developer who changes an internal API is +generally charged with the task of fixing any code within the kernel tree +which is broken by the change. For a widely-used function, this duty can +lead to literally hundreds or thousands of changes - many of which are +likely to conflict with work being done by other developers. Needless to +say, this can be a large job, so it is best to be sure that the +justification is solid. Note that the Coccinelle tool can help with +wide-ranging API changes. + +When making an incompatible API change, one should, whenever possible, +ensure that code which has not been updated is caught by the compiler. +This will help you to be sure that you have found all in-tree uses of that +interface. It will also alert developers of out-of-tree code that there is +a change that they need to respond to. Supporting out-of-tree code is not +something that kernel developers need to be worried about, but we also do +not have to make life harder for out-of-tree developers than it needs to +be. diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst new file mode 100644 index 000000000000..b511ddf7e82a --- /dev/null +++ b/Documentation/process/5.Posting.rst @@ -0,0 +1,321 @@ +.. _development_posting: + +Posting patches +=============== + +Sooner or later, the time comes when your work is ready to be presented to +the community for review and, eventually, inclusion into the mainline +kernel. Unsurprisingly, the kernel development community has evolved a set +of conventions and procedures which are used in the posting of patches; +following them will make life much easier for everybody involved. This +document will attempt to cover these expectations in reasonable detail; +more information can also be found in the files SubmittingPatches, +SubmittingDrivers, and SubmitChecklist in the kernel documentation +directory. + + +When to post +------------ + +There is a constant temptation to avoid posting patches before they are +completely "ready." For simple patches, that is not a problem. If the +work being done is complex, though, there is a lot to be gained by getting +feedback from the community before the work is complete. So you should +consider posting in-progress work, or even making a git tree available so +that interested developers can catch up with your work at any time. + +When posting code which is not yet considered ready for inclusion, it is a +good idea to say so in the posting itself. Also mention any major work +which remains to be done and any known problems. Fewer people will look at +patches which are known to be half-baked, but those who do will come in +with the idea that they can help you drive the work in the right direction. + + +Before creating patches +----------------------- + +There are a number of things which should be done before you consider +sending patches to the development community. These include: + + - Test the code to the extent that you can. Make use of the kernel's + debugging tools, ensure that the kernel will build with all reasonable + combinations of configuration options, use cross-compilers to build for + different architectures, etc. + + - Make sure your code is compliant with the kernel coding style + guidelines. + + - Does your change have performance implications? If so, you should run + benchmarks showing what the impact (or benefit) of your change is; a + summary of the results should be included with the patch. + + - Be sure that you have the right to post the code. If this work was done + for an employer, the employer likely has a right to the work and must be + agreeable with its release under the GPL. + +As a general rule, putting in some extra thought before posting code almost +always pays back the effort in short order. + + +Patch preparation +----------------- + +The preparation of patches for posting can be a surprising amount of work, +but, once again, attempting to save time here is not generally advisable +even in the short term. + +Patches must be prepared against a specific version of the kernel. As a +general rule, a patch should be based on the current mainline as found in +Linus's git tree. When basing on mainline, start with a well-known release +point - a stable or -rc release - rather than branching off the mainline at +an arbitrary spot. + +It may become necessary to make versions against -mm, linux-next, or a +subsystem tree, though, to facilitate wider testing and review. Depending +on the area of your patch and what is going on elsewhere, basing a patch +against these other trees can require a significant amount of work +resolving conflicts and dealing with API changes. + +Only the most simple changes should be formatted as a single patch; +everything else should be made as a logical series of changes. Splitting +up patches is a bit of an art; some developers spend a long time figuring +out how to do it in the way that the community expects. There are a few +rules of thumb, however, which can help considerably: + + - The patch series you post will almost certainly not be the series of + changes found in your working revision control system. Instead, the + changes you have made need to be considered in their final form, then + split apart in ways which make sense. The developers are interested in + discrete, self-contained changes, not the path you took to get to those + changes. + + - Each logically independent change should be formatted as a separate + patch. These changes can be small ("add a field to this structure") or + large (adding a significant new driver, for example), but they should be + conceptually small and amenable to a one-line description. Each patch + should make a specific change which can be reviewed on its own and + verified to do what it says it does. + + - As a way of restating the guideline above: do not mix different types of + changes in the same patch. If a single patch fixes a critical security + bug, rearranges a few structures, and reformats the code, there is a + good chance that it will be passed over and the important fix will be + lost. + + - Each patch should yield a kernel which builds and runs properly; if your + patch series is interrupted in the middle, the result should still be a + working kernel. Partial application of a patch series is a common + scenario when the "git bisect" tool is used to find regressions; if the + result is a broken kernel, you will make life harder for developers and + users who are engaging in the noble work of tracking down problems. + + - Do not overdo it, though. One developer once posted a set of edits + to a single file as 500 separate patches - an act which did not make him + the most popular person on the kernel mailing list. A single patch can + be reasonably large as long as it still contains a single *logical* + change. + + - It can be tempting to add a whole new infrastructure with a series of + patches, but to leave that infrastructure unused until the final patch + in the series enables the whole thing. This temptation should be + avoided if possible; if that series adds regressions, bisection will + finger the last patch as the one which caused the problem, even though + the real bug is elsewhere. Whenever possible, a patch which adds new + code should make that code active immediately. + +Working to create the perfect patch series can be a frustrating process +which takes quite a bit of time and thought after the "real work" has been +done. When done properly, though, it is time well spent. + + +Patch formatting and changelogs +------------------------------- + +So now you have a perfect series of patches for posting, but the work is +not done quite yet. Each patch needs to be formatted into a message which +quickly and clearly communicates its purpose to the rest of the world. To +that end, each patch will be composed of the following: + + - An optional "From" line naming the author of the patch. This line is + only necessary if you are passing on somebody else's patch via email, + but it never hurts to add it when in doubt. + + - A one-line description of what the patch does. This message should be + enough for a reader who sees it with no other context to figure out the + scope of the patch; it is the line that will show up in the "short form" + changelogs. This message is usually formatted with the relevant + subsystem name first, followed by the purpose of the patch. For + example: + + :: + + gpio: fix build on CONFIG_GPIO_SYSFS=n + + - A blank line followed by a detailed description of the contents of the + patch. This description can be as long as is required; it should say + what the patch does and why it should be applied to the kernel. + + - One or more tag lines, with, at a minimum, one Signed-off-by: line from + the author of the patch. Tags will be described in more detail below. + +The items above, together, form the changelog for the patch. Writing good +changelogs is a crucial but often-neglected art; it's worth spending +another moment discussing this issue. When writing a changelog, you should +bear in mind that a number of different people will be reading your words. +These include subsystem maintainers and reviewers who need to decide +whether the patch should be included, distributors and other maintainers +trying to decide whether a patch should be backported to other kernels, bug +hunters wondering whether the patch is responsible for a problem they are +chasing, users who want to know how the kernel has changed, and more. A +good changelog conveys the needed information to all of these people in the +most direct and concise way possible. + +To that end, the summary line should describe the effects of and motivation +for the change as well as possible given the one-line constraint. The +detailed description can then amplify on those topics and provide any +needed additional information. If the patch fixes a bug, cite the commit +which introduced the bug if possible (and please provide both the commit ID +and the title when citing commits). If a problem is associated with +specific log or compiler output, include that output to help others +searching for a solution to the same problem. If the change is meant to +support other changes coming in later patch, say so. If internal APIs are +changed, detail those changes and how other developers should respond. In +general, the more you can put yourself into the shoes of everybody who will +be reading your changelog, the better that changelog (and the kernel as a +whole) will be. + +Needless to say, the changelog should be the text used when committing the +change to a revision control system. It will be followed by: + + - The patch itself, in the unified ("-u") patch format. Using the "-p" + option to diff will associate function names with changes, making the + resulting patch easier for others to read. + +You should avoid including changes to irrelevant files (those generated by +the build process, for example, or editor backup files) in the patch. The +file "dontdiff" in the Documentation directory can help in this regard; +pass it to diff with the "-X" option. + +The tags mentioned above are used to describe how various developers have +been associated with the development of this patch. They are described in +detail in the SubmittingPatches document; what follows here is a brief +summary. Each of these lines has the format: + +:: + + tag: Full Name optional-other-stuff + +The tags in common use are: + + - Signed-off-by: this is a developer's certification that he or she has + the right to submit the patch for inclusion into the kernel. It is an + agreement to the Developer's Certificate of Origin, the full text of + which can be found in Documentation/SubmittingPatches. Code without a + proper signoff cannot be merged into the mainline. + + - Acked-by: indicates an agreement by another developer (often a + maintainer of the relevant code) that the patch is appropriate for + inclusion into the kernel. + + - Tested-by: states that the named person has tested the patch and found + it to work. + + - Reviewed-by: the named developer has reviewed the patch for correctness; + see the reviewer's statement in Documentation/SubmittingPatches for more + detail. + + - Reported-by: names a user who reported a problem which is fixed by this + patch; this tag is used to give credit to the (often underappreciated) + people who test our code and let us know when things do not work + correctly. + + - Cc: the named person received a copy of the patch and had the + opportunity to comment on it. + +Be careful in the addition of tags to your patches: only Cc: is appropriate +for addition without the explicit permission of the person named. + + +Sending the patch +----------------- + +Before you mail your patches, there are a couple of other things you should +take care of: + + - Are you sure that your mailer will not corrupt the patches? Patches + which have had gratuitous white-space changes or line wrapping performed + by the mail client will not apply at the other end, and often will not + be examined in any detail. If there is any doubt at all, mail the patch + to yourself and convince yourself that it shows up intact. + + Documentation/email-clients.txt has some helpful hints on making + specific mail clients work for sending patches. + + - Are you sure your patch is free of silly mistakes? You should always + run patches through scripts/checkpatch.pl and address the complaints it + comes up with. Please bear in mind that checkpatch.pl, while being the + embodiment of a fair amount of thought about what kernel patches should + look like, is not smarter than you. If fixing a checkpatch.pl complaint + would make the code worse, don't do it. + +Patches should always be sent as plain text. Please do not send them as +attachments; that makes it much harder for reviewers to quote sections of +the patch in their replies. Instead, just put the patch directly into your +message. + +When mailing patches, it is important to send copies to anybody who might +be interested in it. Unlike some other projects, the kernel encourages +people to err on the side of sending too many copies; don't assume that the +relevant people will see your posting on the mailing lists. In particular, +copies should go to: + + - The maintainer(s) of the affected subsystem(s). As described earlier, + the MAINTAINERS file is the first place to look for these people. + + - Other developers who have been working in the same area - especially + those who might be working there now. Using git to see who else has + modified the files you are working on can be helpful. + + - If you are responding to a bug report or a feature request, copy the + original poster as well. + + - Send a copy to the relevant mailing list, or, if nothing else applies, + the linux-kernel list. + + - If you are fixing a bug, think about whether the fix should go into the + next stable update. If so, stable@vger.kernel.org should get a copy of + the patch. Also add a "Cc: stable@vger.kernel.org" to the tags within + the patch itself; that will cause the stable team to get a notification + when your fix goes into the mainline. + +When selecting recipients for a patch, it is good to have an idea of who +you think will eventually accept the patch and get it merged. While it +is possible to send patches directly to Linus Torvalds and have him merge +them, things are not normally done that way. Linus is busy, and there are +subsystem maintainers who watch over specific parts of the kernel. Usually +you will be wanting that maintainer to merge your patches. If there is no +obvious maintainer, Andrew Morton is often the patch target of last resort. + +Patches need good subject lines. The canonical format for a patch line is +something like: + +:: + + [PATCH nn/mm] subsys: one-line description of the patch + +where "nn" is the ordinal number of the patch, "mm" is the total number of +patches in the series, and "subsys" is the name of the affected subsystem. +Clearly, nn/mm can be omitted for a single, standalone patch. + +If you have a significant series of patches, it is customary to send an +introductory description as part zero. This convention is not universally +followed though; if you use it, remember that information in the +introduction does not make it into the kernel changelogs. So please ensure +that the patches, themselves, have complete changelog information. + +In general, the second and following parts of a multi-part patch should be +sent as a reply to the first part so that they all thread together at the +receiving end. Tools like git and quilt have commands to mail out a set of +patches with the proper threading. If you have a long series, though, and +are using git, please stay away from the --chain-reply-to option to avoid +creating exceptionally deep nesting. diff --git a/Documentation/process/6.Followthrough.rst b/Documentation/process/6.Followthrough.rst new file mode 100644 index 000000000000..a173cd5f93d2 --- /dev/null +++ b/Documentation/process/6.Followthrough.rst @@ -0,0 +1,212 @@ +.. _development_followthrough: + +Followthrough +============= + +At this point, you have followed the guidelines given so far and, with the +addition of your own engineering skills, have posted a perfect series of +patches. One of the biggest mistakes that even experienced kernel +developers can make is to conclude that their work is now done. In truth, +posting patches indicates a transition into the next stage of the process, +with, possibly, quite a bit of work yet to be done. + +It is a rare patch which is so good at its first posting that there is no +room for improvement. The kernel development process recognizes this fact, +and, as a result, is heavily oriented toward the improvement of posted +code. You, as the author of that code, will be expected to work with the +kernel community to ensure that your code is up to the kernel's quality +standards. A failure to participate in this process is quite likely to +prevent the inclusion of your patches into the mainline. + + +Working with reviewers +---------------------- + +A patch of any significance will result in a number of comments from other +developers as they review the code. Working with reviewers can be, for +many developers, the most intimidating part of the kernel development +process. Life can be made much easier, though, if you keep a few things in +mind: + + - If you have explained your patch well, reviewers will understand its + value and why you went to the trouble of writing it. But that value + will not keep them from asking a fundamental question: what will it be + like to maintain a kernel with this code in it five or ten years later? + Many of the changes you may be asked to make - from coding style tweaks + to substantial rewrites - come from the understanding that Linux will + still be around and under development a decade from now. + + - Code review is hard work, and it is a relatively thankless occupation; + people remember who wrote kernel code, but there is little lasting fame + for those who reviewed it. So reviewers can get grumpy, especially when + they see the same mistakes being made over and over again. If you get a + review which seems angry, insulting, or outright offensive, resist the + impulse to respond in kind. Code review is about the code, not about + the people, and code reviewers are not attacking you personally. + + - Similarly, code reviewers are not trying to promote their employers' + agendas at the expense of your own. Kernel developers often expect to + be working on the kernel years from now, but they understand that their + employer could change. They truly are, almost without exception, + working toward the creation of the best kernel they can; they are not + trying to create discomfort for their employers' competitors. + +What all of this comes down to is that, when reviewers send you comments, +you need to pay attention to the technical observations that they are +making. Do not let their form of expression or your own pride keep that +from happening. When you get review comments on a patch, take the time to +understand what the reviewer is trying to say. If possible, fix the things +that the reviewer is asking you to fix. And respond back to the reviewer: +thank them, and describe how you will answer their questions. + +Note that you do not have to agree with every change suggested by +reviewers. If you believe that the reviewer has misunderstood your code, +explain what is really going on. If you have a technical objection to a +suggested change, describe it and justify your solution to the problem. If +your explanations make sense, the reviewer will accept them. Should your +explanation not prove persuasive, though, especially if others start to +agree with the reviewer, take some time to think things over again. It can +be easy to become blinded by your own solution to a problem to the point +that you don't realize that something is fundamentally wrong or, perhaps, +you're not even solving the right problem. + +Andrew Morton has suggested that every review comment which does not result +in a code change should result in an additional code comment instead; that +can help future reviewers avoid the questions which came up the first time +around. + +One fatal mistake is to ignore review comments in the hope that they will +go away. They will not go away. If you repost code without having +responded to the comments you got the time before, you're likely to find +that your patches go nowhere. + +Speaking of reposting code: please bear in mind that reviewers are not +going to remember all the details of the code you posted the last time +around. So it is always a good idea to remind reviewers of previously +raised issues and how you dealt with them; the patch changelog is a good +place for this kind of information. Reviewers should not have to search +through list archives to familiarize themselves with what was said last +time; if you help them get a running start, they will be in a better mood +when they revisit your code. + +What if you've tried to do everything right and things still aren't going +anywhere? Most technical disagreements can be resolved through discussion, +but there are times when somebody simply has to make a decision. If you +honestly believe that this decision is going against you wrongly, you can +always try appealing to a higher power. As of this writing, that higher +power tends to be Andrew Morton. Andrew has a great deal of respect in the +kernel development community; he can often unjam a situation which seems to +be hopelessly blocked. Appealing to Andrew should not be done lightly, +though, and not before all other alternatives have been explored. And bear +in mind, of course, that he may not agree with you either. + + +What happens next +----------------- + +If a patch is considered to be a good thing to add to the kernel, and once +most of the review issues have been resolved, the next step is usually +entry into a subsystem maintainer's tree. How that works varies from one +subsystem to the next; each maintainer has his or her own way of doing +things. In particular, there may be more than one tree - one, perhaps, +dedicated to patches planned for the next merge window, and another for +longer-term work. + +For patches applying to areas for which there is no obvious subsystem tree +(memory management patches, for example), the default tree often ends up +being -mm. Patches which affect multiple subsystems can also end up going +through the -mm tree. + +Inclusion into a subsystem tree can bring a higher level of visibility to a +patch. Now other developers working with that tree will get the patch by +default. Subsystem trees typically feed linux-next as well, making their +contents visible to the development community as a whole. At this point, +there's a good chance that you will get more comments from a new set of +reviewers; these comments need to be answered as in the previous round. + +What may also happen at this point, depending on the nature of your patch, +is that conflicts with work being done by others turn up. In the worst +case, heavy patch conflicts can result in some work being put on the back +burner so that the remaining patches can be worked into shape and merged. +Other times, conflict resolution will involve working with the other +developers and, possibly, moving some patches between trees to ensure that +everything applies cleanly. This work can be a pain, but count your +blessings: before the advent of the linux-next tree, these conflicts often +only turned up during the merge window and had to be addressed in a hurry. +Now they can be resolved at leisure, before the merge window opens. + +Some day, if all goes well, you'll log on and see that your patch has been +merged into the mainline kernel. Congratulations! Once the celebration is +complete (and you have added yourself to the MAINTAINERS file), though, it +is worth remembering an important little fact: the job still is not done. +Merging into the mainline brings its own challenges. + +To begin with, the visibility of your patch has increased yet again. There +may be a new round of comments from developers who had not been aware of +the patch before. It may be tempting to ignore them, since there is no +longer any question of your code being merged. Resist that temptation, +though; you still need to be responsive to developers who have questions or +suggestions. + +More importantly, though: inclusion into the mainline puts your code into +the hands of a much larger group of testers. Even if you have contributed +a driver for hardware which is not yet available, you will be surprised by +how many people will build your code into their kernels. And, of course, +where there are testers, there will be bug reports. + +The worst sort of bug reports are regressions. If your patch causes a +regression, you'll find an uncomfortable number of eyes upon you; +regressions need to be fixed as soon as possible. If you are unwilling or +unable to fix the regression (and nobody else does it for you), your patch +will almost certainly be removed during the stabilization period. Beyond +negating all of the work you have done to get your patch into the mainline, +having a patch pulled as the result of a failure to fix a regression could +well make it harder for you to get work merged in the future. + +After any regressions have been dealt with, there may be other, ordinary +bugs to deal with. The stabilization period is your best opportunity to +fix these bugs and ensure that your code's debut in a mainline kernel +release is as solid as possible. So, please, answer bug reports, and fix +the problems if at all possible. That's what the stabilization period is +for; you can start creating cool new patches once any problems with the old +ones have been taken care of. + +And don't forget that there are other milestones which may also create bug +reports: the next mainline stable release, when prominent distributors pick +up a version of the kernel containing your patch, etc. Continuing to +respond to these reports is a matter of basic pride in your work. If that +is insufficient motivation, though, it's also worth considering that the +development community remembers developers who lose interest in their code +after it's merged. The next time you post a patch, they will be evaluating +it with the assumption that you will not be around to maintain it +afterward. + + +Other things that can happen +----------------------------- + +One day, you may open your mail client and see that somebody has mailed you +a patch to your code. That is one of the advantages of having your code +out there in the open, after all. If you agree with the patch, you can +either forward it on to the subsystem maintainer (be sure to include a +proper From: line so that the attribution is correct, and add a signoff of +your own), or send an Acked-by: response back and let the original poster +send it upward. + +If you disagree with the patch, send a polite response explaining why. If +possible, tell the author what changes need to be made to make the patch +acceptable to you. There is a certain resistance to merging patches which +are opposed by the author and maintainer of the code, but it only goes so +far. If you are seen as needlessly blocking good work, those patches will +eventually flow around you and get into the mainline anyway. In the Linux +kernel, nobody has absolute veto power over any code. Except maybe Linus. + +On very rare occasion, you may see something completely different: another +developer posts a different solution to your problem. At that point, +chances are that one of the two patches will not be merged, and "mine was +here first" is not considered to be a compelling technical argument. If +somebody else's patch displaces yours and gets into the mainline, there is +really only one way to respond: be pleased that your problem got solved and +get on with your work. Having one's work shoved aside in this manner can +be hurtful and discouraging, but the community will remember your reaction +long after they have forgotten whose patch actually got merged. diff --git a/Documentation/process/7.AdvancedTopics.rst b/Documentation/process/7.AdvancedTopics.rst new file mode 100644 index 000000000000..172733cff097 --- /dev/null +++ b/Documentation/process/7.AdvancedTopics.rst @@ -0,0 +1,178 @@ +.. _development_advancedtopics: + +Advanced topics +=============== + +At this point, hopefully, you have a handle on how the development process +works. There is still more to learn, however! This section will cover a +number of topics which can be helpful for developers wanting to become a +regular part of the Linux kernel development process. + +Managing patches with git +------------------------- + +The use of distributed version control for the kernel began in early 2002, +when Linus first started playing with the proprietary BitKeeper +application. While BitKeeper was controversial, the approach to software +version management it embodied most certainly was not. Distributed version +control enabled an immediate acceleration of the kernel development +project. In current times, there are several free alternatives to +BitKeeper. For better or for worse, the kernel project has settled on git +as its tool of choice. + +Managing patches with git can make life much easier for the developer, +especially as the volume of those patches grows. Git also has its rough +edges and poses certain hazards; it is a young and powerful tool which is +still being civilized by its developers. This document will not attempt to +teach the reader how to use git; that would be sufficient material for a +long document in its own right. Instead, the focus here will be on how git +fits into the kernel development process in particular. Developers who +wish to come up to speed with git will find more information at: + + http://git-scm.com/ + + http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + +and on various tutorials found on the web. + +The first order of business is to read the above sites and get a solid +understanding of how git works before trying to use it to make patches +available to others. A git-using developer should be able to obtain a copy +of the mainline repository, explore the revision history, commit changes to +the tree, use branches, etc. An understanding of git's tools for the +rewriting of history (such as rebase) is also useful. Git comes with its +own terminology and concepts; a new user of git should know about refs, +remote branches, the index, fast-forward merges, pushes and pulls, detached +heads, etc. It can all be a little intimidating at the outset, but the +concepts are not that hard to grasp with a bit of study. + +Using git to generate patches for submission by email can be a good +exercise while coming up to speed. + +When you are ready to start putting up git trees for others to look at, you +will, of course, need a server that can be pulled from. Setting up such a +server with git-daemon is relatively straightforward if you have a system +which is accessible to the Internet. Otherwise, free, public hosting sites +(Github, for example) are starting to appear on the net. Established +developers can get an account on kernel.org, but those are not easy to come +by; see http://kernel.org/faq/ for more information. + +The normal git workflow involves the use of a lot of branches. Each line +of development can be separated into a separate "topic branch" and +maintained independently. Branches in git are cheap, there is no reason to +not make free use of them. And, in any case, you should not do your +development in any branch which you intend to ask others to pull from. +Publicly-available branches should be created with care; merge in patches +from development branches when they are in complete form and ready to go - +not before. + +Git provides some powerful tools which can allow you to rewrite your +development history. An inconvenient patch (one which breaks bisection, +say, or which has some other sort of obvious bug) can be fixed in place or +made to disappear from the history entirely. A patch series can be +rewritten as if it had been written on top of today's mainline, even though +you have been working on it for months. Changes can be transparently +shifted from one branch to another. And so on. Judicious use of git's +ability to revise history can help in the creation of clean patch sets with +fewer problems. + +Excessive use of this capability can lead to other problems, though, beyond +a simple obsession for the creation of the perfect project history. +Rewriting history will rewrite the changes contained in that history, +turning a tested (hopefully) kernel tree into an untested one. But, beyond +that, developers cannot easily collaborate if they do not have a shared +view of the project history; if you rewrite history which other developers +have pulled into their repositories, you will make life much more difficult +for those developers. So a simple rule of thumb applies here: history +which has been exported to others should generally be seen as immutable +thereafter. + +So, once you push a set of changes to your publicly-available server, those +changes should not be rewritten. Git will attempt to enforce this rule if +you try to push changes which do not result in a fast-forward merge +(i.e. changes which do not share the same history). It is possible to +override this check, and there may be times when it is necessary to rewrite +an exported tree. Moving changesets between trees to avoid conflicts in +linux-next is one example. But such actions should be rare. This is one +of the reasons why development should be done in private branches (which +can be rewritten if necessary) and only moved into public branches when +it's in a reasonably advanced state. + +As the mainline (or other tree upon which a set of changes is based) +advances, it is tempting to merge with that tree to stay on the leading +edge. For a private branch, rebasing can be an easy way to keep up with +another tree, but rebasing is not an option once a tree is exported to the +world. Once that happens, a full merge must be done. Merging occasionally +makes good sense, but overly frequent merges can clutter the history +needlessly. Suggested technique in this case is to merge infrequently, and +generally only at specific release points (such as a mainline -rc +release). If you are nervous about specific changes, you can always +perform test merges in a private branch. The git "rerere" tool can be +useful in such situations; it remembers how merge conflicts were resolved +so that you don't have to do the same work twice. + +One of the biggest recurring complaints about tools like git is this: the +mass movement of patches from one repository to another makes it easy to +slip in ill-advised changes which go into the mainline below the review +radar. Kernel developers tend to get unhappy when they see that kind of +thing happening; putting up a git tree with unreviewed or off-topic patches +can affect your ability to get trees pulled in the future. Quoting Linus: + +:: + + You can send me patches, but for me to pull a git patch from you, I + need to know that you know what you're doing, and I need to be able + to trust things *without* then having to go and check every + individual change by hand. + +(http://lwn.net/Articles/224135/). + +To avoid this kind of situation, ensure that all patches within a given +branch stick closely to the associated topic; a "driver fixes" branch +should not be making changes to the core memory management code. And, most +importantly, do not use a git tree to bypass the review process. Post an +occasional summary of the tree to the relevant list, and, when the time is +right, request that the tree be included in linux-next. + +If and when others start to send patches for inclusion into your tree, +don't forget to review them. Also ensure that you maintain the correct +authorship information; the git "am" tool does its best in this regard, but +you may have to add a "From:" line to the patch if it has been relayed to +you via a third party. + +When requesting a pull, be sure to give all the relevant information: where +your tree is, what branch to pull, and what changes will result from the +pull. The git request-pull command can be helpful in this regard; it will +format the request as other developers expect, and will also check to be +sure that you have remembered to push those changes to the public server. + + +Reviewing patches +----------------- + +Some readers will certainly object to putting this section with "advanced +topics" on the grounds that even beginning kernel developers should be +reviewing patches. It is certainly true that there is no better way to +learn how to program in the kernel environment than by looking at code +posted by others. In addition, reviewers are forever in short supply; by +looking at code you can make a significant contribution to the process as a +whole. + +Reviewing code can be an intimidating prospect, especially for a new kernel +developer who may well feel nervous about questioning code - in public - +which has been posted by those with more experience. Even code written by +the most experienced developers can be improved, though. Perhaps the best +piece of advice for reviewers (all reviewers) is this: phrase review +comments as questions rather than criticisms. Asking "how does the lock +get released in this path?" will always work better than stating "the +locking here is wrong." + +Different developers will review code from different points of view. Some +are mostly concerned with coding style and whether code lines have trailing +white space. Others will focus primarily on whether the change implemented +by the patch as a whole is a good thing for the kernel or not. Yet others +will check for problematic locking, excessive stack usage, possible +security issues, duplication of code found elsewhere, adequate +documentation, adverse effects on performance, user-space ABI changes, etc. +All types of review, if they lead to better code going into the kernel, are +welcome and worthwhile. diff --git a/Documentation/process/8.Conclusion.rst b/Documentation/process/8.Conclusion.rst new file mode 100644 index 000000000000..23ec7cbc2d2b --- /dev/null +++ b/Documentation/process/8.Conclusion.rst @@ -0,0 +1,74 @@ +.. _development_conclusion: + +For more information +==================== + +There are numerous sources of information on Linux kernel development and +related topics. First among those will always be the Documentation +directory found in the kernel source distribution. The top-level HOWTO +file is an important starting point; SubmittingPatches and +SubmittingDrivers are also something which all kernel developers should +read. Many internal kernel APIs are documented using the kerneldoc +mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those +documents in HTML or PDF format (though the version of TeX shipped by some +distributions runs into internal limits and fails to process the documents +properly). + +Various web sites discuss kernel development at all levels of detail. Your +author would like to humbly suggest http://lwn.net/ as a source; +information on many specific kernel topics can be found via the LWN kernel +index at: + + http://lwn.net/Kernel/Index/ + +Beyond that, a valuable resource for kernel developers is: + + http://kernelnewbies.org/ + +And, of course, one should not forget http://kernel.org/, the definitive +location for kernel release information. + +There are a number of books on kernel development: + + Linux Device Drivers, 3rd Edition (Jonathan Corbet, Alessandro + Rubini, and Greg Kroah-Hartman). Online at + http://lwn.net/Kernel/LDD3/. + + Linux Kernel Development (Robert Love). + + Understanding the Linux Kernel (Daniel Bovet and Marco Cesati). + +All of these books suffer from a common fault, though: they tend to be +somewhat obsolete by the time they hit the shelves, and they have been on +the shelves for a while now. Still, there is quite a bit of good +information to be found there. + +Documentation for git can be found at: + + http://www.kernel.org/pub/software/scm/git/docs/ + + http://www.kernel.org/pub/software/scm/git/docs/user-manual.html + + +Conclusion +========== + +Congratulations to anybody who has made it through this long-winded +document. Hopefully it has provided a helpful understanding of how the +Linux kernel is developed and how you can participate in that process. + +In the end, it's the participation that matters. Any open source software +project is no more than the sum of what its contributors put into it. The +Linux kernel has progressed as quickly and as well as it has because it has +been helped by an impressively large group of developers, all of whom are +working to make it better. The kernel is a premier example of what can be +done when thousands of people work together toward a common goal. + +The kernel can always benefit from a larger developer base, though. There +is always more work to do. But, just as importantly, most other +participants in the Linux ecosystem can benefit through contributing to the +kernel. Getting code into the mainline is the key to higher code quality, +lower maintenance and distribution costs, a higher level of influence over +the direction of kernel development, and more. It is a situation where +everybody involved wins. Fire up your editor and come join us; you will be +more than welcome. diff --git a/Documentation/process/conf.py b/Documentation/process/conf.py new file mode 100644 index 000000000000..1b01a80ad9ce --- /dev/null +++ b/Documentation/process/conf.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8; mode: python -*- + +project = 'Linux Kernel Development Documentation' + +tags.add("subproject") + +latex_documents = [ + ('index', 'process.tex', 'Linux Kernel Development Documentation', + 'The kernel development community', 'manual'), +] diff --git a/Documentation/process/development-process.rst b/Documentation/process/development-process.rst new file mode 100644 index 000000000000..61c627e41ba8 --- /dev/null +++ b/Documentation/process/development-process.rst @@ -0,0 +1,28 @@ +.. _development_process_main: + +A guide to the Kernel Development Process +========================================= + +Contents: + +.. toctree:: + :numbered: + :maxdepth: 2 + + 1.Intro + 2.Process + 3.Early-stage + 4.Coding + 5.Posting + 6.Followthrough + 7.AdvancedTopics + 8.Conclusion + +The purpose of this document is to help developers (and their managers) +work with the development community with a minimum of frustration. It is +an attempt to document how this community works in a way which is +accessible to those who are not intimately familiar with Linux kernel +development (or, indeed, free software development in general). While +there is some technical material here, this is very much a process-oriented +discussion which does not require a deep knowledge of kernel programming to +understand. diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst new file mode 100644 index 000000000000..c37475d91090 --- /dev/null +++ b/Documentation/process/index.rst @@ -0,0 +1,9 @@ +Linux Kernel Development Documentation +====================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + development-process -- cgit v1.2.3 From 186128f75392f8478ad1b32a675627d738881ca4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 08:40:21 -0300 Subject: docs-rst: add documents to development-process Add several documents to the development-process ReST book. As we don't want renames, use symlinks instead, keeping those documents on their original place. Acked-by: Greg Kroah-Hartman Signed-off-by: Mauro Carvalho Chehab --- Documentation/Changes | 485 --------- Documentation/CodeOfConflict | 28 - Documentation/CodingStyle | 1062 -------------------- Documentation/HOWTO | 652 ------------ Documentation/ManagementStyle | 288 ------ Documentation/SubmitChecklist | 120 --- Documentation/SubmittingDrivers | 183 ---- Documentation/SubmittingPatches | 841 ---------------- Documentation/adding-syscals.txt | 542 ---------- Documentation/applying-patches.txt | 465 --------- Documentation/email-clients.txt | 319 ------ Documentation/kernel-docs.txt | 652 ------------ Documentation/magic-number.txt | 164 --- Documentation/process/adding-syscalls.rst | 542 ++++++++++ Documentation/process/applying-patches.rst | 464 +++++++++ Documentation/process/changes.rst | 485 +++++++++ Documentation/process/code-of-conflict.rst | 28 + Documentation/process/coding-style.rst | 1062 ++++++++++++++++++++ Documentation/process/email-clients.rst | 319 ++++++ Documentation/process/howto.rst | 652 ++++++++++++ Documentation/process/index.rst | 23 + Documentation/process/kernel-docs.rst | 652 ++++++++++++ Documentation/process/magic-number.rst | 164 +++ Documentation/process/management-style.rst | 288 ++++++ Documentation/process/stable-api-nonsense.rst | 205 ++++ Documentation/process/stable-kernel-rules.rst | 181 ++++ Documentation/process/submit-checklist.rst | 120 +++ Documentation/process/submitting-drivers.rst | 183 ++++ Documentation/process/submitting-patches.rst | 840 ++++++++++++++++ .../process/volatile-considered-harmful.rst | 122 +++ Documentation/stable_api_nonsense.txt | 205 ---- Documentation/stable_kernel_rules.txt | 181 ---- Documentation/volatile-considered-harmful.txt | 122 --- 33 files changed, 6330 insertions(+), 6309 deletions(-) delete mode 100644 Documentation/Changes delete mode 100644 Documentation/CodeOfConflict delete mode 100644 Documentation/CodingStyle delete mode 100644 Documentation/HOWTO delete mode 100644 Documentation/ManagementStyle delete mode 100644 Documentation/SubmitChecklist delete mode 100644 Documentation/SubmittingDrivers delete mode 100644 Documentation/SubmittingPatches delete mode 100644 Documentation/adding-syscals.txt delete mode 100644 Documentation/applying-patches.txt delete mode 100644 Documentation/email-clients.txt delete mode 100644 Documentation/kernel-docs.txt delete mode 100644 Documentation/magic-number.txt create mode 100644 Documentation/process/adding-syscalls.rst create mode 100644 Documentation/process/applying-patches.rst create mode 100644 Documentation/process/changes.rst create mode 100644 Documentation/process/code-of-conflict.rst create mode 100644 Documentation/process/coding-style.rst create mode 100644 Documentation/process/email-clients.rst create mode 100644 Documentation/process/howto.rst create mode 100644 Documentation/process/kernel-docs.rst create mode 100644 Documentation/process/magic-number.rst create mode 100644 Documentation/process/management-style.rst create mode 100644 Documentation/process/stable-api-nonsense.rst create mode 100644 Documentation/process/stable-kernel-rules.rst create mode 100644 Documentation/process/submit-checklist.rst create mode 100644 Documentation/process/submitting-drivers.rst create mode 100644 Documentation/process/submitting-patches.rst create mode 100644 Documentation/process/volatile-considered-harmful.rst delete mode 100644 Documentation/stable_api_nonsense.txt delete mode 100644 Documentation/stable_kernel_rules.txt delete mode 100644 Documentation/volatile-considered-harmful.txt diff --git a/Documentation/Changes b/Documentation/Changes deleted file mode 100644 index 22797a15dc24..000000000000 --- a/Documentation/Changes +++ /dev/null @@ -1,485 +0,0 @@ -.. _changes: - -Minimal requerements to compile the Kernel -++++++++++++++++++++++++++++++++++++++++++ - -Intro -===== - -This document is designed to provide a list of the minimum levels of -software necessary to run the 4.x kernels. - -This document is originally based on my "Changes" file for 2.0.x kernels -and therefore owes credit to the same people as that file (Jared Mauch, -Axel Boldt, Alessandro Sigala, and countless other users all over the -'net). - -Current Minimal Requirements -**************************** - -Upgrade to at **least** these software revisions before thinking you've -encountered a bug! If you're unsure what version you're currently -running, the suggested command should tell you. - -Again, keep in mind that this list assumes you are already functionally -running a Linux kernel. Also, not all tools are necessary on all -systems; obviously, if you don't have any ISDN hardware, for example, -you probably needn't concern yourself with isdn4k-utils. - -====================== =============== ======================================== - Program Minimal version Command to check the version -====================== =============== ======================================== -GNU C 3.2 gcc --version -GNU make 3.80 make --version -binutils 2.12 ld -v -util-linux 2.10o fdformat --version -module-init-tools 0.9.10 depmod -V -e2fsprogs 1.41.4 e2fsck -V -jfsutils 1.1.3 fsck.jfs -V -reiserfsprogs 3.6.3 reiserfsck -V -xfsprogs 2.6.0 xfs_db -V -squashfs-tools 4.0 mksquashfs -version -btrfs-progs 0.18 btrfsck -pcmciautils 004 pccardctl -V -quota-tools 3.09 quota -V -PPP 2.4.0 pppd --version -isdn4k-utils 3.1pre1 isdnctrl 2>&1|grep version -nfs-utils 1.0.5 showmount --version -procps 3.2.0 ps --version -oprofile 0.9 oprofiled --version -udev 081 udevd --version -grub 0.93 grub --version || grub-install --version -mcelog 0.6 mcelog --version -iptables 1.4.2 iptables -V -openssl & libcrypto 1.0.0 openssl version -bc 1.06.95 bc --version -Sphinx\ [#f1]_ 1.2 sphinx-build --version -====================== =============== ======================================== - -.. [#f1] Sphinx is needed only to build the Kernel documentation - -Kernel compilation -****************** - -GCC ---- - -The gcc version requirements may vary depending on the type of CPU in your -computer. - -Make ----- - -You will need GNU make 3.80 or later to build the kernel. - -Binutils --------- - -Linux on IA-32 has recently switched from using ``as86`` to using ``gas`` for -assembling the 16-bit boot code, removing the need for ``as86`` to compile -your kernel. This change does, however, mean that you need a recent -release of binutils. - -Perl ----- - -You will need perl 5 and the following modules: ``Getopt::Long``, -``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel. - -BC --- - -You will need bc to build kernels 3.10 and higher - - -OpenSSL -------- - -Module signing and external certificate handling use the OpenSSL program and -crypto library to do key creation and signature generation. - -You will need openssl to build kernels 3.7 and higher if module signing is -enabled. You will also need openssl development packages to build kernels 4.3 -and higher. - - -System utilities -**************** - -Architectural changes ---------------------- - -DevFS has been obsoleted in favour of udev -(http://www.kernel.org/pub/linux/utils/kernel/hotplug/) - -32-bit UID support is now in place. Have fun! - -Linux documentation for functions is transitioning to inline -documentation via specially-formatted comments near their -definitions in the source. These comments can be combined with the -SGML templates in the Documentation/DocBook directory to make DocBook -files, which can then be converted by DocBook stylesheets to PostScript, -HTML, PDF files, and several other formats. In order to convert from -DocBook format to a format of your choice, you'll need to install Jade as -well as the desired DocBook stylesheets. - -Util-linux ----------- - -New versions of util-linux provide ``fdisk`` support for larger disks, -support new options to mount, recognize more supported partition -types, have a fdformat which works with 2.4 kernels, and similar goodies. -You'll probably want to upgrade. - -Ksymoops --------- - -If the unthinkable happens and your kernel oopses, you may need the -ksymoops tool to decode it, but in most cases you don't. -It is generally preferred to build the kernel with ``CONFIG_KALLSYMS`` so -that it produces readable dumps that can be used as-is (this also -produces better output than ksymoops). If for some reason your kernel -is not build with ``CONFIG_KALLSYMS`` and you have no way to rebuild and -reproduce the Oops with that option, then you can still decode that Oops -with ksymoops. - -Module-Init-Tools ------------------ - -A new module loader is now in the kernel that requires ``module-init-tools`` -to use. It is backward compatible with the 2.4.x series kernels. - -Mkinitrd --------- - -These changes to the ``/lib/modules`` file tree layout also require that -mkinitrd be upgraded. - -E2fsprogs ---------- - -The latest version of ``e2fsprogs`` fixes several bugs in fsck and -debugfs. Obviously, it's a good idea to upgrade. - -JFSutils --------- - -The ``jfsutils`` package contains the utilities for the file system. -The following utilities are available: - -- ``fsck.jfs`` - initiate replay of the transaction log, and check - and repair a JFS formatted partition. - -- ``mkfs.jfs`` - create a JFS formatted partition. - -- other file system utilities are also available in this package. - -Reiserfsprogs -------------- - -The reiserfsprogs package should be used for reiserfs-3.6.x -(Linux kernels 2.4.x). It is a combined package and contains working -versions of ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` and -``reiserfsck``. These utils work on both i386 and alpha platforms. - -Xfsprogs --------- - -The latest version of ``xfsprogs`` contains ``mkfs.xfs``, ``xfs_db``, and the -``xfs_repair`` utilities, among others, for the XFS filesystem. It is -architecture independent and any version from 2.0.0 onward should -work correctly with this version of the XFS kernel code (2.6.0 or -later is recommended, due to some significant improvements). - -PCMCIAutils ------------ - -PCMCIAutils replaces ``pcmcia-cs``. It properly sets up -PCMCIA sockets at system startup and loads the appropriate modules -for 16-bit PCMCIA devices if the kernel is modularized and the hotplug -subsystem is used. - -Quota-tools ------------ - -Support for 32 bit uid's and gid's is required if you want to use -the newer version 2 quota format. Quota-tools version 3.07 and -newer has this support. Use the recommended version or newer -from the table above. - -Intel IA32 microcode --------------------- - -A driver has been added to allow updating of Intel IA32 microcode, -accessible as a normal (misc) character device. If you are not using -udev you may need to:: - - mkdir /dev/cpu - mknod /dev/cpu/microcode c 10 184 - chmod 0644 /dev/cpu/microcode - -as root before you can use this. You'll probably also want to -get the user-space microcode_ctl utility to use with this. - -udev ----- - -``udev`` is a userspace application for populating ``/dev`` dynamically with -only entries for devices actually present. ``udev`` replaces the basic -functionality of devfs, while allowing persistent device naming for -devices. - -FUSE ----- - -Needs libfuse 2.4.0 or later. Absolute minimum is 2.3.0 but mount -options ``direct_io`` and ``kernel_cache`` won't work. - -Networking -********** - -General changes ---------------- - -If you have advanced network configuration needs, you should probably -consider using the network tools from ip-route2. - -Packet Filter / NAT -------------------- -The packet filtering and NAT code uses the same tools like the previous 2.4.x -kernel series (iptables). It still includes backwards-compatibility modules -for 2.2.x-style ipchains and 2.0.x-style ipfwadm. - -PPP ---- - -The PPP driver has been restructured to support multilink and to -enable it to operate over diverse media layers. If you use PPP, -upgrade pppd to at least 2.4.0. - -If you are not using udev, you must have the device file /dev/ppp -which can be made by:: - - mknod /dev/ppp c 108 0 - -as root. - -Isdn4k-utils ------------- - -Due to changes in the length of the phone number field, isdn4k-utils -needs to be recompiled or (preferably) upgraded. - -NFS-utils ---------- - -In ancient (2.4 and earlier) kernels, the nfs server needed to know -about any client that expected to be able to access files via NFS. This -information would be given to the kernel by ``mountd`` when the client -mounted the filesystem, or by ``exportfs`` at system startup. exportfs -would take information about active clients from ``/var/lib/nfs/rmtab``. - -This approach is quite fragile as it depends on rmtab being correct -which is not always easy, particularly when trying to implement -fail-over. Even when the system is working well, ``rmtab`` suffers from -getting lots of old entries that never get removed. - -With modern kernels we have the option of having the kernel tell mountd -when it gets a request from an unknown host, and mountd can give -appropriate export information to the kernel. This removes the -dependency on ``rmtab`` and means that the kernel only needs to know about -currently active clients. - -To enable this new functionality, you need to:: - - mount -t nfsd nfsd /proc/fs/nfsd - -before running exportfs or mountd. It is recommended that all NFS -services be protected from the internet-at-large by a firewall where -that is possible. - -mcelog ------- - -On x86 kernels the mcelog utility is needed to process and log machine check -events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors -reported by the CPU. Processing them is strongly encouraged. - -Kernel documentation -******************** - -Sphinx ------- - -The ReST markups currently used by the Documentation/ files are meant to be -built with ``Sphinx`` version 1.2 or upper. If you're desiring to build -PDF outputs, it is recommended to use version 1.4.6. - -.. note:: - - Please notice that, for PDF and LaTeX output, you'll also need ``XeLaTeX`` - version 3.14159265. Depending on the distribution, you may also need - to install a series of ``texlive`` packages that provide the minimal - set of functionalities required for ``XeLaTex`` to work. - -Other tools ------------ - -In order to produce documentation from DocBook, you'll also need ``xmlto``. -Please notice, however, that we're currently migrating all documents to use -``Sphinx``. - -Getting updated software -======================== - -Kernel compilation -****************** - -gcc ---- - -- - -Make ----- - -- - -Binutils --------- - -- - -OpenSSL -------- - -- - -System utilities -**************** - -Util-linux ----------- - -- - -Ksymoops --------- - -- - -Module-Init-Tools ------------------ - -- - -Mkinitrd --------- - -- - -E2fsprogs ---------- - -- - -JFSutils --------- - -- - -Reiserfsprogs -------------- - -- - -Xfsprogs --------- - -- - -Pcmciautils ------------ - -- - -Quota-tools ------------ - -- - -DocBook Stylesheets -------------------- - -- - -XMLTO XSLT Frontend -------------------- - -- - -Intel P6 microcode ------------------- - -- - -udev ----- - -- - -FUSE ----- - -- - -mcelog ------- - -- - -Networking -********** - -PPP ---- - -- - -Isdn4k-utils ------------- - -- - -NFS-utils ---------- - -- - -Iptables --------- - -- - -Ip-route2 ---------- - -- - -OProfile --------- - -- - -NFS-Utils ---------- - -- - -Kernel documentation -******************** - -Sphinx ------- - -- diff --git a/Documentation/CodeOfConflict b/Documentation/CodeOfConflict deleted file mode 100644 index 47b6de763203..000000000000 --- a/Documentation/CodeOfConflict +++ /dev/null @@ -1,28 +0,0 @@ -Code of Conflict ----------------- - -The Linux kernel development effort is a very personal process compared -to "traditional" ways of developing software. Your code and ideas -behind it will be carefully reviewed, often resulting in critique and -criticism. The review will almost always require improvements to the -code before it can be included in the kernel. Know that this happens -because everyone involved wants to see the best possible solution for -the overall success of Linux. This development process has been proven -to create the most robust operating system kernel ever, and we do not -want to do anything to cause the quality of submission and eventual -result to ever decrease. - -If however, anyone feels personally abused, threatened, or otherwise -uncomfortable due to this process, that is not acceptable. If so, -please contact the Linux Foundation's Technical Advisory Board at -, or the individual members, and they -will work to resolve the issue to the best of their ability. For more -information on who is on the Technical Advisory Board and what their -role is, please see: - - - http://www.linuxfoundation.org/projects/linux/tab - -As a reviewer of code, please strive to keep things civil and focused on -the technical issues involved. We are all humans, and frustrations can -be high on both sides of the process. Try to keep in mind the immortal -words of Bill and Ted, "Be excellent to each other." diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle deleted file mode 100644 index 9c61c039ccd9..000000000000 --- a/Documentation/CodingStyle +++ /dev/null @@ -1,1062 +0,0 @@ -.. _codingstyle: - -Linux kernel coding style -========================= - -This is a short document describing the preferred coding style for the -linux kernel. Coding style is very personal, and I won't **force** my -views on anybody, but this is what goes for anything that I have to be -able to maintain, and I'd prefer it for most other things too. Please -at least consider the points made here. - -First off, I'd suggest printing out a copy of the GNU coding standards, -and NOT read it. Burn them, it's a great symbolic gesture. - -Anyway, here goes: - - -1) Indentation --------------- - -Tabs are 8 characters, and thus indentations are also 8 characters. -There are heretic movements that try to make indentations 4 (or even 2!) -characters deep, and that is akin to trying to define the value of PI to -be 3. - -Rationale: The whole idea behind indentation is to clearly define where -a block of control starts and ends. Especially when you've been looking -at your screen for 20 straight hours, you'll find it a lot easier to see -how the indentation works if you have large indentations. - -Now, some people will claim that having 8-character indentations makes -the code move too far to the right, and makes it hard to read on a -80-character terminal screen. The answer to that is that if you need -more than 3 levels of indentation, you're screwed anyway, and should fix -your program. - -In short, 8-char indents make things easier to read, and have the added -benefit of warning you when you're nesting your functions too deep. -Heed that warning. - -The preferred way to ease multiple indentation levels in a switch statement is -to align the ``switch`` and its subordinate ``case`` labels in the same column -instead of ``double-indenting`` the ``case`` labels. E.g.: - -.. code-block:: c - - switch (suffix) { - case 'G': - case 'g': - mem <<= 30; - break; - case 'M': - case 'm': - mem <<= 20; - break; - case 'K': - case 'k': - mem <<= 10; - /* fall through */ - default: - break; - } - -Don't put multiple statements on a single line unless you have -something to hide: - -.. code-block:: c - - if (condition) do_this; - do_something_everytime; - -Don't put multiple assignments on a single line either. Kernel coding style -is super simple. Avoid tricky expressions. - -Outside of comments, documentation and except in Kconfig, spaces are never -used for indentation, and the above example is deliberately broken. - -Get a decent editor and don't leave whitespace at the end of lines. - - -2) Breaking long lines and strings ----------------------------------- - -Coding style is all about readability and maintainability using commonly -available tools. - -The limit on the length of lines is 80 columns and this is a strongly -preferred limit. - -Statements longer than 80 columns will be broken into sensible chunks, unless -exceeding 80 columns significantly increases readability and does not hide -information. Descendants are always substantially shorter than the parent and -are placed substantially to the right. The same applies to function headers -with a long argument list. However, never break user-visible strings such as -printk messages, because that breaks the ability to grep for them. - - -3) Placing Braces and Spaces ----------------------------- - -The other issue that always comes up in C styling is the placement of -braces. Unlike the indent size, there are few technical reasons to -choose one placement strategy over the other, but the preferred way, as -shown to us by the prophets Kernighan and Ritchie, is to put the opening -brace last on the line, and put the closing brace first, thusly: - -.. code-block:: c - - if (x is true) { - we do y - } - -This applies to all non-function statement blocks (if, switch, for, -while, do). E.g.: - -.. code-block:: c - - switch (action) { - case KOBJ_ADD: - return "add"; - case KOBJ_REMOVE: - return "remove"; - case KOBJ_CHANGE: - return "change"; - default: - return NULL; - } - -However, there is one special case, namely functions: they have the -opening brace at the beginning of the next line, thus: - -.. code-block:: c - - int function(int x) - { - body of function - } - -Heretic people all over the world have claimed that this inconsistency -is ... well ... inconsistent, but all right-thinking people know that -(a) K&R are **right** and (b) K&R are right. Besides, functions are -special anyway (you can't nest them in C). - -Note that the closing brace is empty on a line of its own, **except** in -the cases where it is followed by a continuation of the same statement, -ie a ``while`` in a do-statement or an ``else`` in an if-statement, like -this: - -.. code-block:: c - - do { - body of do-loop - } while (condition); - -and - -.. code-block:: c - - if (x == y) { - .. - } else if (x > y) { - ... - } else { - .... - } - -Rationale: K&R. - -Also, note that this brace-placement also minimizes the number of empty -(or almost empty) lines, without any loss of readability. Thus, as the -supply of new-lines on your screen is not a renewable resource (think -25-line terminal screens here), you have more empty lines to put -comments on. - -Do not unnecessarily use braces where a single statement will do. - -.. code-block:: c - - if (condition) - action(); - -and - -.. code-block:: none - - if (condition) - do_this(); - else - do_that(); - -This does not apply if only one branch of a conditional statement is a single -statement; in the latter case use braces in both branches: - -.. code-block:: c - - if (condition) { - do_this(); - do_that(); - } else { - otherwise(); - } - -3.1) Spaces -*********** - -Linux kernel style for use of spaces depends (mostly) on -function-versus-keyword usage. Use a space after (most) keywords. The -notable exceptions are sizeof, typeof, alignof, and __attribute__, which look -somewhat like functions (and are usually used with parentheses in Linux, -although they are not required in the language, as in: ``sizeof info`` after -``struct fileinfo info;`` is declared). - -So use a space after these keywords:: - - if, switch, case, for, do, while - -but not with sizeof, typeof, alignof, or __attribute__. E.g., - -.. code-block:: c - - - s = sizeof(struct file); - -Do not add spaces around (inside) parenthesized expressions. This example is -**bad**: - -.. code-block:: c - - - s = sizeof( struct file ); - -When declaring pointer data or a function that returns a pointer type, the -preferred use of ``*`` is adjacent to the data name or function name and not -adjacent to the type name. Examples: - -.. code-block:: c - - - char *linux_banner; - unsigned long long memparse(char *ptr, char **retptr); - char *match_strdup(substring_t *s); - -Use one space around (on each side of) most binary and ternary operators, -such as any of these:: - - = + - < > * / % | & ^ <= >= == != ? : - -but no space after unary operators:: - - & * + - ~ ! sizeof typeof alignof __attribute__ defined - -no space before the postfix increment & decrement unary operators:: - - ++ -- - -no space after the prefix increment & decrement unary operators:: - - ++ -- - -and no space around the ``.`` and ``->`` structure member operators. - -Do not leave trailing whitespace at the ends of lines. Some editors with -``smart`` indentation will insert whitespace at the beginning of new lines as -appropriate, so you can start typing the next line of code right away. -However, some such editors do not remove the whitespace if you end up not -putting a line of code there, such as if you leave a blank line. As a result, -you end up with lines containing trailing whitespace. - -Git will warn you about patches that introduce trailing whitespace, and can -optionally strip the trailing whitespace for you; however, if applying a series -of patches, this may make later patches in the series fail by changing their -context lines. - - -4) Naming ---------- - -C is a Spartan language, and so should your naming be. Unlike Modula-2 -and Pascal programmers, C programmers do not use cute names like -ThisVariableIsATemporaryCounter. A C programmer would call that -variable ``tmp``, which is much easier to write, and not the least more -difficult to understand. - -HOWEVER, while mixed-case names are frowned upon, descriptive names for -global variables are a must. To call a global function ``foo`` is a -shooting offense. - -GLOBAL variables (to be used only if you **really** need them) need to -have descriptive names, as do global functions. If you have a function -that counts the number of active users, you should call that -``count_active_users()`` or similar, you should **not** call it ``cntusr()``. - -Encoding the type of a function into the name (so-called Hungarian -notation) is brain damaged - the compiler knows the types anyway and can -check those, and it only confuses the programmer. No wonder MicroSoft -makes buggy programs. - -LOCAL variable names should be short, and to the point. If you have -some random integer loop counter, it should probably be called ``i``. -Calling it ``loop_counter`` is non-productive, if there is no chance of it -being mis-understood. Similarly, ``tmp`` can be just about any type of -variable that is used to hold a temporary value. - -If you are afraid to mix up your local variable names, you have another -problem, which is called the function-growth-hormone-imbalance syndrome. -See chapter 6 (Functions). - - -5) Typedefs ------------ - -Please don't use things like ``vps_t``. -It's a **mistake** to use typedef for structures and pointers. When you see a - -.. code-block:: c - - - vps_t a; - -in the source, what does it mean? -In contrast, if it says - -.. code-block:: c - - struct virtual_container *a; - -you can actually tell what ``a`` is. - -Lots of people think that typedefs ``help readability``. Not so. They are -useful only for: - - (a) totally opaque objects (where the typedef is actively used to **hide** - what the object is). - - Example: ``pte_t`` etc. opaque objects that you can only access using - the proper accessor functions. - - .. note:: - - Opaqueness and ``accessor functions`` are not good in themselves. - The reason we have them for things like pte_t etc. is that there - really is absolutely **zero** portably accessible information there. - - (b) Clear integer types, where the abstraction **helps** avoid confusion - whether it is ``int`` or ``long``. - - u8/u16/u32 are perfectly fine typedefs, although they fit into - category (d) better than here. - - .. note:: - - Again - there needs to be a **reason** for this. If something is - ``unsigned long``, then there's no reason to do - - typedef unsigned long myflags_t; - - but if there is a clear reason for why it under certain circumstances - might be an ``unsigned int`` and under other configurations might be - ``unsigned long``, then by all means go ahead and use a typedef. - - (c) when you use sparse to literally create a **new** type for - type-checking. - - (d) New types which are identical to standard C99 types, in certain - exceptional circumstances. - - Although it would only take a short amount of time for the eyes and - brain to become accustomed to the standard types like ``uint32_t``, - some people object to their use anyway. - - Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their - signed equivalents which are identical to standard types are - permitted -- although they are not mandatory in new code of your - own. - - When editing existing code which already uses one or the other set - of types, you should conform to the existing choices in that code. - - (e) Types safe for use in userspace. - - In certain structures which are visible to userspace, we cannot - require C99 types and cannot use the ``u32`` form above. Thus, we - use __u32 and similar types in all structures which are shared - with userspace. - -Maybe there are other cases too, but the rule should basically be to NEVER -EVER use a typedef unless you can clearly match one of those rules. - -In general, a pointer, or a struct that has elements that can reasonably -be directly accessed should **never** be a typedef. - - -6) Functions ------------- - -Functions should be short and sweet, and do just one thing. They should -fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, -as we all know), and do one thing and do that well. - -The maximum length of a function is inversely proportional to the -complexity and indentation level of that function. So, if you have a -conceptually simple function that is just one long (but simple) -case-statement, where you have to do lots of small things for a lot of -different cases, it's OK to have a longer function. - -However, if you have a complex function, and you suspect that a -less-than-gifted first-year high-school student might not even -understand what the function is all about, you should adhere to the -maximum limits all the more closely. Use helper functions with -descriptive names (you can ask the compiler to in-line them if you think -it's performance-critical, and it will probably do a better job of it -than you would have done). - -Another measure of the function is the number of local variables. They -shouldn't exceed 5-10, or you're doing something wrong. Re-think the -function, and split it into smaller pieces. A human brain can -generally easily keep track of about 7 different things, anything more -and it gets confused. You know you're brilliant, but maybe you'd like -to understand what you did 2 weeks from now. - -In source files, separate functions with one blank line. If the function is -exported, the **EXPORT** macro for it should follow immediately after the -closing function brace line. E.g.: - -.. code-block:: c - - int system_is_up(void) - { - return system_state == SYSTEM_RUNNING; - } - EXPORT_SYMBOL(system_is_up); - -In function prototypes, include parameter names with their data types. -Although this is not required by the C language, it is preferred in Linux -because it is a simple way to add valuable information for the reader. - - -7) Centralized exiting of functions ------------------------------------ - -Albeit deprecated by some people, the equivalent of the goto statement is -used frequently by compilers in form of the unconditional jump instruction. - -The goto statement comes in handy when a function exits from multiple -locations and some common work such as cleanup has to be done. If there is no -cleanup needed then just return directly. - -Choose label names which say what the goto does or why the goto exists. An -example of a good name could be ``out_free_buffer:`` if the goto frees ``buffer``. -Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to -renumber them if you ever add or remove exit paths, and they make correctness -difficult to verify anyway. - -The rationale for using gotos is: - -- unconditional statements are easier to understand and follow -- nesting is reduced -- errors by not updating individual exit points when making - modifications are prevented -- saves the compiler work to optimize redundant code away ;) - -.. code-block:: c - - int fun(int a) - { - int result = 0; - char *buffer; - - buffer = kmalloc(SIZE, GFP_KERNEL); - if (!buffer) - return -ENOMEM; - - if (condition1) { - while (loop1) { - ... - } - result = 1; - goto out_buffer; - } - ... - out_free_buffer: - kfree(buffer); - return result; - } - -A common type of bug to be aware of is ``one err bugs`` which look like this: - -.. code-block:: c - - err: - kfree(foo->bar); - kfree(foo); - return ret; - -The bug in this code is that on some exit paths ``foo`` is NULL. Normally the -fix for this is to split it up into two error labels ``err_free_bar:`` and -``err_free_foo:``: - -.. code-block:: c - - err_free_bar: - kfree(foo->bar); - err_free_foo: - kfree(foo); - return ret; - -Ideally you should simulate errors to test all exit paths. - - -8) Commenting -------------- - -Comments are good, but there is also a danger of over-commenting. NEVER -try to explain HOW your code works in a comment: it's much better to -write the code so that the **working** is obvious, and it's a waste of -time to explain badly written code. - -Generally, you want your comments to tell WHAT your code does, not HOW. -Also, try to avoid putting comments inside a function body: if the -function is so complex that you need to separately comment parts of it, -you should probably go back to chapter 6 for a while. You can make -small comments to note or warn about something particularly clever (or -ugly), but try to avoid excess. Instead, put the comments at the head -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-documentation.rst and scripts/kernel-doc -for details. - -The preferred style for long (multi-line) comments is: - -.. code-block:: c - - /* - * This is the preferred style for multi-line - * comments in the Linux kernel source code. - * Please use it consistently. - * - * Description: A column of asterisks on the left side, - * with beginning and ending almost-blank lines. - */ - -For files in net/ and drivers/net/ the preferred style for long (multi-line) -comments is a little different. - -.. code-block:: c - - /* 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. - */ - -It's also important to comment data, whether they are basic types or derived -types. To this end, use just one data declaration per line (no commas for -multiple data declarations). This leaves you room for a small comment on each -item, explaining its use. - - -9) You've made a mess of it ---------------------------- - -That's OK, we all do. You've probably been told by your long-time Unix -user helper that ``GNU emacs`` automatically formats the C sources for -you, and you've noticed that yes, it does do that, but the defaults it -uses are less than desirable (in fact, they are worse than random -typing - an infinite number of monkeys typing into GNU emacs would never -make a good program). - -So, you can either get rid of GNU emacs, or change it to use saner -values. To do the latter, you can stick the following in your .emacs file: - -.. code-block:: none - - (defun c-lineup-arglist-tabs-only (ignored) - "Line up argument lists by tabs, not spaces" - (let* ((anchor (c-langelem-pos c-syntactic-element)) - (column (c-langelem-2nd-pos c-syntactic-element)) - (offset (- (1+ column) anchor)) - (steps (floor offset c-basic-offset))) - (* (max steps 1) - c-basic-offset))) - - (add-hook 'c-mode-common-hook - (lambda () - ;; Add kernel style - (c-add-style - "linux-tabs-only" - '("linux" (c-offsets-alist - (arglist-cont-nonempty - c-lineup-gcc-asm-reg - c-lineup-arglist-tabs-only)))))) - - (add-hook 'c-mode-hook - (lambda () - (let ((filename (buffer-file-name))) - ;; Enable kernel mode for the appropriate files - (when (and filename - (string-match (expand-file-name "~/src/linux-trees") - filename)) - (setq indent-tabs-mode t) - (setq show-trailing-whitespace t) - (c-set-style "linux-tabs-only"))))) - -This will make emacs go better with the kernel coding style for C -files below ``~/src/linux-trees``. - -But even if you fail in getting emacs to do sane formatting, not -everything is lost: use ``indent``. - -Now, again, GNU indent has the same brain-dead settings that GNU emacs -has, which is why you need to give it a few command line options. -However, that's not too bad, because even the makers of GNU indent -recognize the authority of K&R (the GNU people aren't evil, they are -just severely misguided in this matter), so you just give indent the -options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use -``scripts/Lindent``, which indents in the latest style. - -``indent`` has a lot of options, and especially when it comes to comment -re-formatting you may want to take a look at the man page. But -remember: ``indent`` is not a fix for bad programming. - - -10) Kconfig configuration files -------------------------------- - -For all of the Kconfig* configuration files throughout the source tree, -the indentation is somewhat different. Lines under a ``config`` definition -are indented with one tab, while help text is indented an additional two -spaces. Example:: - - config AUDIT - bool "Auditing support" - depends on NET - help - Enable auditing infrastructure that can be used with another - kernel subsystem, such as SELinux (which requires this for - logging of avc messages output). Does not do system-call - auditing without CONFIG_AUDITSYSCALL. - -Seriously dangerous features (such as write support for certain -filesystems) should advertise this prominently in their prompt string:: - - config ADFS_FS_RW - bool "ADFS write support (DANGEROUS)" - depends on ADFS_FS - ... - -For full documentation on the configuration files, see the file -Documentation/kbuild/kconfig-language.txt. - - -11) Data structures -------------------- - -Data structures that have visibility outside the single-threaded -environment they are created and destroyed in should always have -reference counts. In the kernel, garbage collection doesn't exist (and -outside the kernel garbage collection is slow and inefficient), which -means that you absolutely **have** to reference count all your uses. - -Reference counting means that you can avoid locking, and allows multiple -users to have access to the data structure in parallel - and not having -to worry about the structure suddenly going away from under them just -because they slept or did something else for a while. - -Note that locking is **not** a replacement for reference counting. -Locking is used to keep data structures coherent, while reference -counting is a memory management technique. Usually both are needed, and -they are not to be confused with each other. - -Many data structures can indeed have two levels of reference counting, -when there are users of different ``classes``. The subclass count counts -the number of subclass users, and decrements the global count just once -when the subclass count goes to zero. - -Examples of this kind of ``multi-level-reference-counting`` can be found in -memory management (``struct mm_struct``: mm_users and mm_count), and in -filesystem code (``struct super_block``: s_count and s_active). - -Remember: if another thread can find your data structure, and you don't -have a reference count on it, you almost certainly have a bug. - - -12) Macros, Enums and RTL -------------------------- - -Names of macros defining constants and labels in enums are capitalized. - -.. code-block:: c - - #define CONSTANT 0x12345 - -Enums are preferred when defining several related constants. - -CAPITALIZED macro names are appreciated but macros resembling functions -may be named in lower case. - -Generally, inline functions are preferable to macros resembling functions. - -Macros with multiple statements should be enclosed in a do - while block: - -.. code-block:: c - - #define macrofun(a, b, c) \ - do { \ - if (a == 5) \ - do_this(b, c); \ - } while (0) - -Things to avoid when using macros: - -1) macros that affect control flow: - -.. code-block:: c - - #define FOO(x) \ - do { \ - if (blah(x) < 0) \ - return -EBUGGERED; \ - } while (0) - -is a **very** bad idea. It looks like a function call but exits the ``calling`` -function; don't break the internal parsers of those who will read the code. - -2) macros that depend on having a local variable with a magic name: - -.. code-block:: c - - #define FOO(val) bar(index, val) - -might look like a good thing, but it's confusing as hell when one reads the -code and it's prone to breakage from seemingly innocent changes. - -3) macros with arguments that are used as l-values: FOO(x) = y; will -bite you if somebody e.g. turns FOO into an inline function. - -4) forgetting about precedence: macros defining constants using expressions -must enclose the expression in parentheses. Beware of similar issues with -macros using parameters. - -.. code-block:: c - - #define CONSTANT 0x4000 - #define CONSTEXP (CONSTANT | 3) - -5) namespace collisions when defining local variables in macros resembling -functions: - -.. code-block:: c - - #define FOO(x) \ - ({ \ - typeof(x) ret; \ - ret = calc_ret(x); \ - (ret); \ - }) - -ret is a common name for a local variable - __foo_ret is less likely -to collide with an existing variable. - -The cpp manual deals with macros exhaustively. The gcc internals manual also -covers RTL which is used frequently with assembly language in the kernel. - - -13) Printing kernel messages ----------------------------- - -Kernel developers like to be seen as literate. Do mind the spelling -of kernel messages to make a good impression. Do not use crippled -words like ``dont``; use ``do not`` or ``don't`` instead. Make the messages -concise, clear, and unambiguous. - -Kernel messages do not have to be terminated with a period. - -Printing numbers in parentheses (%d) adds no value and should be avoided. - -There are a number of driver model diagnostic macros in -which you should use to make sure messages are matched to the right device -and driver, and are tagged with the right level: dev_err(), dev_warn(), -dev_info(), and so forth. For messages that aren't associated with a -particular device, defines pr_notice(), pr_info(), -pr_warn(), pr_err(), etc. - -Coming up with good debugging messages can be quite a challenge; and once -you have them, they can be a huge help for remote troubleshooting. However -debug message printing is handled differently than printing other non-debug -messages. While the other pr_XXX() functions print unconditionally, -pr_debug() does not; it is compiled out by default, unless either DEBUG is -defined or CONFIG_DYNAMIC_DEBUG is set. That is true for dev_dbg() also, -and a related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to -the ones already enabled by DEBUG. - -Many subsystems have Kconfig debug options to turn on -DDEBUG in the -corresponding Makefile; in other cases specific files #define DEBUG. And -when a debug message should be unconditionally printed, such as if it is -already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be -used. - - -14) Allocating memory ---------------------- - -The kernel provides the following general purpose memory allocators: -kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and -vzalloc(). Please refer to the API documentation for further information -about them. - -The preferred form for passing a size of a struct is the following: - -.. code-block:: c - - p = kmalloc(sizeof(*p), ...); - -The alternative form where struct name is spelled out hurts readability and -introduces an opportunity for a bug when the pointer variable type is changed -but the corresponding sizeof that is passed to a memory allocator is not. - -Casting the return value which is a void pointer is redundant. The conversion -from void pointer to any other pointer type is guaranteed by the C programming -language. - -The preferred form for allocating an array is the following: - -.. code-block:: c - - p = kmalloc_array(n, sizeof(...), ...); - -The preferred form for allocating a zeroed array is the following: - -.. code-block:: c - - p = kcalloc(n, sizeof(...), ...); - -Both forms check for overflow on the allocation size n * sizeof(...), -and return NULL if that occurred. - - -15) The inline disease ----------------------- - -There appears to be a common misperception that gcc has a magic "make me -faster" speedup option called ``inline``. While the use of inlines can be -appropriate (for example as a means of replacing macros, see Chapter 12), it -very often is not. Abundant use of the inline keyword leads to a much bigger -kernel, which in turn slows the system as a whole down, due to a bigger -icache footprint for the CPU and simply because there is less memory -available for the pagecache. Just think about it; a pagecache miss causes a -disk seek, which easily takes 5 milliseconds. There are a LOT of cpu cycles -that can go into these 5 milliseconds. - -A reasonable rule of thumb is to not put inline at functions that have more -than 3 lines of code in them. An exception to this rule are the cases where -a parameter is known to be a compiletime constant, and as a result of this -constantness you *know* the compiler will be able to optimize most of your -function away at compile time. For a good example of this later case, see -the kmalloc() inline function. - -Often people argue that adding inline to functions that are static and used -only once is always a win since there is no space tradeoff. While this is -technically correct, gcc is capable of inlining these automatically without -help, and the maintenance issue of removing the inline when a second user -appears outweighs the potential value of the hint that tells gcc to do -something it would have done anyway. - - -16) Function return values and names ------------------------------------- - -Functions can return values of many different kinds, and one of the -most common is a value indicating whether the function succeeded or -failed. Such a value can be represented as an error-code integer -(-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure, -non-zero = success). - -Mixing up these two sorts of representations is a fertile source of -difficult-to-find bugs. If the C language included a strong distinction -between integers and booleans then the compiler would find these mistakes -for us... but it doesn't. To help prevent such bugs, always follow this -convention:: - - If the name of a function is an action or an imperative command, - the function should return an error-code integer. If the name - is a predicate, the function should return a "succeeded" boolean. - -For example, ``add work`` is a command, and the add_work() function returns 0 -for success or -EBUSY for failure. In the same way, ``PCI device present`` is -a predicate, and the pci_dev_present() function returns 1 if it succeeds in -finding a matching device or 0 if it doesn't. - -All EXPORTed functions must respect this convention, and so should all -public functions. Private (static) functions need not, but it is -recommended that they do. - -Functions whose return value is the actual result of a computation, rather -than an indication of whether the computation succeeded, are not subject to -this rule. Generally they indicate failure by returning some out-of-range -result. Typical examples would be functions that return pointers; they use -NULL or the ERR_PTR mechanism to report failure. - - -17) Don't re-invent the kernel macros -------------------------------------- - -The header file include/linux/kernel.h contains a number of macros that -you should use, rather than explicitly coding some variant of them yourself. -For example, if you need to calculate the length of an array, take advantage -of the macro - -.. code-block:: c - - #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) - -Similarly, if you need to calculate the size of some structure member, use - -.. code-block:: c - - #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) - -There are also min() and max() macros that do strict type checking if you -need them. Feel free to peruse that header file to see what else is already -defined that you shouldn't reproduce in your code. - - -18) Editor modelines and other cruft ------------------------------------- - -Some editors can interpret configuration information embedded in source files, -indicated with special markers. For example, emacs interprets lines marked -like this: - -.. code-block:: c - - -*- mode: c -*- - -Or like this: - -.. code-block:: c - - /* - Local Variables: - compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" - End: - */ - -Vim interprets markers that look like this: - -.. code-block:: c - - /* vim:set sw=8 noet */ - -Do not include any of these in source files. People have their own personal -editor configurations, and your source files should not override them. This -includes markers for indentation and mode configuration. People may use their -own custom mode, or may have some other magic method for making indentation -work correctly. - - -19) Inline assembly -------------------- - -In architecture-specific code, you may need to use inline assembly to interface -with CPU or platform functionality. Don't hesitate to do so when necessary. -However, don't use inline assembly gratuitously when C can do the job. You can -and should poke hardware from C when possible. - -Consider writing simple helper functions that wrap common bits of inline -assembly, rather than repeatedly writing them with slight variations. Remember -that inline assembly can use C parameters. - -Large, non-trivial assembly functions should go in .S files, with corresponding -C prototypes defined in C header files. The C prototypes for assembly -functions should use ``asmlinkage``. - -You may need to mark your asm statement as volatile, to prevent GCC from -removing it if GCC doesn't notice any side effects. You don't always need to -do so, though, and doing so unnecessarily can limit optimization. - -When writing a single inline assembly statement containing multiple -instructions, put each instruction on a separate line in a separate quoted -string, and end each string except the last with \n\t to properly indent the -next instruction in the assembly output: - -.. code-block:: c - - asm ("magic %reg1, #42\n\t" - "more_magic %reg2, %reg3" - : /* outputs */ : /* inputs */ : /* clobbers */); - - -20) Conditional Compilation ---------------------------- - -Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c -files; doing so makes code harder to read and logic harder to follow. Instead, -use such conditionals in a header file defining functions for use in those .c -files, providing no-op stub versions in the #else case, and then call those -functions unconditionally from .c files. The compiler will avoid generating -any code for the stub calls, producing identical results, but the logic will -remain easy to follow. - -Prefer to compile out entire functions, rather than portions of functions or -portions of expressions. Rather than putting an ifdef in an expression, factor -out part or all of the expression into a separate helper function and apply the -conditional to that function. - -If you have a function or variable which may potentially go unused in a -particular configuration, and the compiler would warn about its definition -going unused, mark the definition as __maybe_unused rather than wrapping it in -a preprocessor conditional. (However, if a function or variable *always* goes -unused, delete it.) - -Within code, where possible, use the IS_ENABLED macro to convert a Kconfig -symbol into a C boolean expression, and use it in a normal C conditional: - -.. code-block:: c - - if (IS_ENABLED(CONFIG_SOMETHING)) { - ... - } - -The compiler will constant-fold the conditional away, and include or exclude -the block of code just as with an #ifdef, so this will not add any runtime -overhead. However, this approach still allows the C compiler to see the code -inside the block, and check it for correctness (syntax, types, symbol -references, etc). Thus, you still have to use an #ifdef if the code inside the -block references symbols that will not exist if the condition is not met. - -At the end of any non-trivial #if or #ifdef block (more than a few lines), -place a comment after the #endif on the same line, noting the conditional -expression used. For instance: - -.. code-block:: c - - #ifdef CONFIG_SOMETHING - ... - #endif /* CONFIG_SOMETHING */ - - -Appendix I) References ----------------------- - -The C Programming Language, Second Edition -by Brian W. Kernighan and Dennis M. Ritchie. -Prentice Hall, Inc., 1988. -ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback). - -The Practice of Programming -by Brian W. Kernighan and Rob Pike. -Addison-Wesley, Inc., 1999. -ISBN 0-201-61586-X. - -GNU manuals - where in compliance with K&R and this text - for cpp, gcc, -gcc internals and indent, all available from http://www.gnu.org/manual/ - -WG14 is the international standardization working group for the programming -language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ - -Kernel CodingStyle, by greg@kroah.com at OLS 2002: -http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/HOWTO b/Documentation/HOWTO deleted file mode 100644 index 5f042349f987..000000000000 --- a/Documentation/HOWTO +++ /dev/null @@ -1,652 +0,0 @@ -HOWTO do Linux kernel development -================================= - -This is the be-all, end-all document on this topic. It contains -instructions on how to become a Linux kernel developer and how to learn -to work with the Linux kernel development community. It tries to not -contain anything related to the technical aspects of kernel programming, -but will help point you in the right direction for that. - -If anything in this document becomes out of date, please send in patches -to the maintainer of this file, who is listed at the bottom of the -document. - - -Introduction ------------- - -So, you want to learn how to become a Linux kernel developer? Or you -have been told by your manager, "Go write a Linux driver for this -device." This document's goal is to teach you everything you need to -know to achieve this by describing the process you need to go through, -and hints on how to work with the community. It will also try to -explain some of the reasons why the community works like it does. - -The kernel is written mostly in C, with some architecture-dependent -parts written in assembly. A good understanding of C is required for -kernel development. Assembly (any architecture) is not required unless -you plan to do low-level development for that architecture. Though they -are not a good substitute for a solid C education and/or years of -experience, the following books are good for, if anything, reference: - - - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] - - "Practical C Programming" by Steve Oualline [O'Reilly] - - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] - -The kernel is written using GNU C and the GNU toolchain. While it -adheres to the ISO C89 standard, it uses a number of extensions that are -not featured in the standard. The kernel is a freestanding C -environment, with no reliance on the standard C library, so some -portions of the C standard are not supported. Arbitrary long long -divisions and floating point are not allowed. It can sometimes be -difficult to understand the assumptions the kernel has on the toolchain -and the extensions that it uses, and unfortunately there is no -definitive reference for them. Please check the gcc info pages (`info -gcc`) for some information on them. - -Please remember that you are trying to learn how to work with the -existing development community. It is a diverse group of people, with -high standards for coding, style and procedure. These standards have -been created over time based on what they have found to work best for -such a large and geographically dispersed team. Try to learn as much as -possible about these standards ahead of time, as they are well -documented; do not expect people to adapt to you or your company's way -of doing things. - - -Legal Issues ------------- - -The Linux kernel source code is released under the GPL. Please see the -file, COPYING, in the main directory of the source tree, for details on -the license. If you have further questions about the license, please -contact a lawyer, and do not ask on the Linux kernel mailing list. The -people on the mailing lists are not lawyers, and you should not rely on -their statements on legal matters. - -For common questions and answers about the GPL, please see: - - https://www.gnu.org/licenses/gpl-faq.html - - -Documentation -------------- - -The Linux kernel source tree has a large range of documents that are -invaluable for learning how to interact with the kernel community. When -new features are added to the kernel, it is recommended that new -documentation files are also added which explain how to use the feature. -When a kernel change causes the interface that the kernel exposes to -userspace to change, it is recommended that you send the information or -a patch to the manual pages explaining the change to the manual pages -maintainer at mtk.manpages@gmail.com, and CC the list -linux-api@vger.kernel.org. - -Here is a list of files that are in the kernel source tree that are -required reading: - - README - This file gives a short background on the Linux kernel and describes - what is necessary to do to configure and build the kernel. People - who are new to the kernel should start here. - - :ref:`Documentation/Changes ` - This file gives a list of the minimum levels of various software - packages that are necessary to build and run the kernel - successfully. - - :ref:`Documentation/CodingStyle ` - This describes the Linux kernel coding style, and some of the - rationale behind it. All new code is expected to follow the - guidelines in this document. Most maintainers will only accept - patches if these rules are followed, and many people will only - review code if it is in the proper style. - - :ref:`Documentation/SubmittingPatches ` and :ref:`Documentation/SubmittingDrivers ` - These files describe in explicit detail how to successfully create - and send a patch, including (but not limited to): - - - Email contents - - Email format - - Who to send it to - - Following these rules will not guarantee success (as all patches are - subject to scrutiny for content and style), but not following them - will almost always prevent it. - - Other excellent descriptions of how to create patches properly are: - - "The Perfect Patch" - https://www.ozlabs.org/~akpm/stuff/tpp.txt - - "Linux kernel patch submission format" - http://linux.yyz.us/patch-format.html - - :ref:`Documentation/stable_api_nonsense.txt ` - This file describes the rationale behind the conscious decision to - not have a stable API within the kernel, including things like: - - - Subsystem shim-layers (for compatibility?) - - Driver portability between Operating Systems. - - Mitigating rapid change within the kernel source tree (or - preventing rapid change) - - This document is crucial for understanding the Linux development - philosophy and is very important for people moving to Linux from - development on other Operating Systems. - - :ref:`Documentation/SecurityBugs ` - If you feel you have found a security problem in the Linux kernel, - please follow the steps in this document to help notify the kernel - developers, and help solve the issue. - - :ref:`Documentation/ManagementStyle ` - This document describes how Linux kernel maintainers operate and the - shared ethos behind their methodologies. This is important reading - for anyone new to kernel development (or anyone simply curious about - it), as it resolves a lot of common misconceptions and confusion - about the unique behavior of kernel maintainers. - - :ref:`Documentation/stable_kernel_rules.txt ` - This file describes the rules on how the stable kernel releases - happen, and what to do if you want to get a change into one of these - releases. - - :ref:`Documentation/kernel-docs.txt ` - A list of external documentation that pertains to kernel - development. Please consult this list if you do not find what you - are looking for within the in-kernel documentation. - - :ref:`Documentation/applying-patches.txt ` - A good introduction describing exactly what a patch is and how to - apply it to the different development branches of the kernel. - -The kernel also has a large number of documents that can be -automatically generated from the source code itself or from -ReStructuredText markups (ReST), like this one. This includes a -full description of the in-kernel API, and rules on how to handle -locking properly. - -All such documents can be generated as PDF or HTML by running:: - - make pdfdocs - make htmldocs - -respectively from the main kernel source directory. - -The documents that uses ReST markup will be generated at Documentation/output. -They can also be generated on LaTeX and ePub formats with:: - - make latexdocs - make epubdocs - -Currently, there are some documents written on DocBook that are in -the process of conversion to ReST. Such documents will be created in the -Documentation/DocBook/ directory and can be generated also as -Postscript or man pages by running:: - - make psdocs - make mandocs - -Becoming A Kernel Developer ---------------------------- - -If you do not know anything about Linux kernel development, you should -look at the Linux KernelNewbies project: - - https://kernelnewbies.org - -It consists of a helpful mailing list where you can ask almost any type -of basic kernel development question (make sure to search the archives -first, before asking something that has already been answered in the -past.) It also has an IRC channel that you can use to ask questions in -real-time, and a lot of helpful documentation that is useful for -learning about Linux kernel development. - -The website has basic information about code organization, subsystems, -and current projects (both in-tree and out-of-tree). It also describes -some basic logistical information, like how to compile a kernel and -apply a patch. - -If you do not know where you want to start, but you want to look for -some task to start doing to join into the kernel development community, -go to the Linux Kernel Janitor's project: - - https://kernelnewbies.org/KernelJanitors - -It is a great place to start. It describes a list of relatively simple -problems that need to be cleaned up and fixed within the Linux kernel -source tree. Working with the developers in charge of this project, you -will learn the basics of getting your patch into the Linux kernel tree, -and possibly be pointed in the direction of what to go work on next, if -you do not already have an idea. - -If you already have a chunk of code that you want to put into the kernel -tree, but need some help getting it in the proper form, the -kernel-mentors project was created to help you out with this. It is a -mailing list, and can be found at: - - https://selenic.com/mailman/listinfo/kernel-mentors - -Before making any actual modifications to the Linux kernel code, it is -imperative to understand how the code in question works. For this -purpose, nothing is better than reading through it directly (most tricky -bits are commented well), perhaps even with the help of specialized -tools. One such tool that is particularly recommended is the Linux -Cross-Reference project, which is able to present source code in a -self-referential, indexed webpage format. An excellent up-to-date -repository of the kernel code may be found at: - - http://lxr.free-electrons.com/ - - -The development process ------------------------ - -Linux kernel development process currently consists of a few different -main kernel "branches" and lots of different subsystem-specific kernel -branches. These different branches are: - - - main 4.x kernel tree - - 4.x.y -stable kernel tree - - 4.x -git kernel patches - - subsystem specific kernel trees and patches - - the 4.x -next kernel tree for integration tests - -4.x kernel tree ------------------ -4.x kernels are maintained by Linus Torvalds, and can be found on -https://kernel.org in the pub/linux/kernel/v4.x/ directory. Its development -process is as follows: - - - As soon as a new kernel is released a two weeks window is open, - during this period of time maintainers can submit big diffs to - Linus, usually the patches that have already been included in the - -next kernel for a few weeks. The preferred way to submit big changes - is using git (the kernel's source management tool, more information - can be found at https://git-scm.com/) but plain patches are also just - fine. - - After two weeks a -rc1 kernel is released it is now possible to push - only patches that do not include new features that could affect the - stability of the whole kernel. Please note that a whole new driver - (or filesystem) might be accepted after -rc1 because there is no - risk of causing regressions with such a change as long as the change - is self-contained and does not affect areas outside of the code that - is being added. git can be used to send patches to Linus after -rc1 - is released, but the patches need to also be sent to a public - mailing list for review. - - A new -rc is released whenever Linus deems the current git tree to - be in a reasonably sane state adequate for testing. The goal is to - release a new -rc kernel every week. - - Process continues until the kernel is considered "ready", the - process should last around 6 weeks. - -It is worth mentioning what Andrew Morton wrote on the linux-kernel -mailing list about kernel releases: - - *"Nobody knows when a kernel will be released, because it's - released according to perceived bug status, not according to a - preconceived timeline."* - -4.x.y -stable kernel tree -------------------------- -Kernels with 3-part versions are -stable kernels. They contain -relatively small and critical fixes for security problems or significant -regressions discovered in a given 4.x kernel. - -This is the recommended branch for users who want the most recent stable -kernel and are not interested in helping test development/experimental -versions. - -If no 4.x.y kernel is available, then the highest numbered 4.x -kernel is the current stable kernel. - -4.x.y are maintained by the "stable" team , and -are released as needs dictate. The normal release period is approximately -two weeks, but it can be longer if there are no pressing problems. A -security-related problem, instead, can cause a release to happen almost -instantly. - -The file Documentation/stable_kernel_rules.txt in the kernel tree -documents what kinds of changes are acceptable for the -stable tree, and -how the release process works. - -4.x -git patches ----------------- -These are daily snapshots of Linus' kernel tree which are managed in a -git repository (hence the name.) These patches are usually released -daily and represent the current state of Linus' tree. They are more -experimental than -rc kernels since they are generated automatically -without even a cursory glance to see if they are sane. - -Subsystem Specific kernel trees and patches -------------------------------------------- -The maintainers of the various kernel subsystems --- and also many -kernel subsystem developers --- expose their current state of -development in source repositories. That way, others can see what is -happening in the different areas of the kernel. In areas where -development is rapid, a developer may be asked to base his submissions -onto such a subsystem kernel tree so that conflicts between the -submission and other already ongoing work are avoided. - -Most of these repositories are git trees, but there are also other SCMs -in use, or patch queues being published as quilt series. Addresses of -these subsystem repositories are listed in the MAINTAINERS file. Many -of them can be browsed at https://git.kernel.org/. - -Before a proposed patch is committed to such a subsystem tree, it is -subject to review which primarily happens on mailing lists (see the -respective section below). For several kernel subsystems, this review -process is tracked with the tool patchwork. Patchwork offers a web -interface which shows patch postings, any comments on a patch or -revisions to it, and maintainers can mark patches as under review, -accepted, or rejected. Most of these patchwork sites are listed at -https://patchwork.kernel.org/. - -4.x -next kernel tree for integration tests -------------------------------------------- -Before updates from subsystem trees are merged into the mainline 4.x -tree, they need to be integration-tested. For this purpose, a special -testing repository exists into which virtually all subsystem trees are -pulled on an almost daily basis: - - https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git - -This way, the -next kernel gives a summary outlook onto what will be -expected to go into the mainline kernel at the next merge period. -Adventurous testers are very welcome to runtime-test the -next kernel. - - -Bug Reporting -------------- - -https://bugzilla.kernel.org is where the Linux kernel developers track kernel -bugs. Users are encouraged to report all bugs that they find in this -tool. For details on how to use the kernel bugzilla, please see: - - https://bugzilla.kernel.org/page.cgi?id=faq.html - -The file REPORTING-BUGS in the main kernel source directory has a good -template for how to report a possible kernel bug, and details what kind -of information is needed by the kernel developers to help track down the -problem. - - -Managing bug reports --------------------- - -One of the best ways to put into practice your hacking skills is by fixing -bugs reported by other people. Not only you will help to make the kernel -more stable, you'll learn to fix real world problems and you will improve -your skills, and other developers will be aware of your presence. Fixing -bugs is one of the best ways to get merits among other developers, because -not many people like wasting time fixing other people's bugs. - -To work in the already reported bug reports, go to https://bugzilla.kernel.org. -If you want to be advised of the future bug reports, you can subscribe to the -bugme-new mailing list (only new bug reports are mailed here) or to the -bugme-janitor mailing list (every change in the bugzilla is mailed here) - - https://lists.linux-foundation.org/mailman/listinfo/bugme-new - - https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors - - - -Mailing lists -------------- - -As some of the above documents describe, the majority of the core kernel -developers participate on the Linux Kernel Mailing list. Details on how -to subscribe and unsubscribe from the list can be found at: - - http://vger.kernel.org/vger-lists.html#linux-kernel - -There are archives of the mailing list on the web in many different -places. Use a search engine to find these archives. For example: - - http://dir.gmane.org/gmane.linux.kernel - -It is highly recommended that you search the archives about the topic -you want to bring up, before you post it to the list. A lot of things -already discussed in detail are only recorded at the mailing list -archives. - -Most of the individual kernel subsystems also have their own separate -mailing list where they do their development efforts. See the -MAINTAINERS file for a list of what these lists are for the different -groups. - -Many of the lists are hosted on kernel.org. Information on them can be -found at: - - http://vger.kernel.org/vger-lists.html - -Please remember to follow good behavioral habits when using the lists. -Though a bit cheesy, the following URL has some simple guidelines for -interacting with the list (or any list): - - http://www.albion.com/netiquette/ - -If multiple people respond to your mail, the CC: list of recipients may -get pretty large. Don't remove anybody from the CC: list without a good -reason, or don't reply only to the list address. Get used to receiving the -mail twice, one from the sender and the one from the list, and don't try -to tune that by adding fancy mail-headers, people will not like it. - -Remember to keep the context and the attribution of your replies intact, -keep the "John Kernelhacker wrote ...:" lines at the top of your reply, and -add your statements between the individual quoted sections instead of -writing at the top of the mail. - -If you add patches to your mail, make sure they are plain readable text -as stated in Documentation/SubmittingPatches. -Kernel developers don't want to deal with -attachments or compressed patches; they may want to comment on -individual lines of your patch, which works only that way. Make sure you -use a mail program that does not mangle spaces and tab characters. A -good first test is to send the mail to yourself and try to apply your -own patch by yourself. If that doesn't work, get your mail program fixed -or change it until it works. - -Above all, please remember to show respect to other subscribers. - - -Working with the community --------------------------- - -The goal of the kernel community is to provide the best possible kernel -there is. When you submit a patch for acceptance, it will be reviewed -on its technical merits and those alone. So, what should you be -expecting? - - - criticism - - comments - - requests for change - - requests for justification - - silence - -Remember, this is part of getting your patch into the kernel. You have -to be able to take criticism and comments about your patches, evaluate -them at a technical level and either rework your patches or provide -clear and concise reasoning as to why those changes should not be made. -If there are no responses to your posting, wait a few days and try -again, sometimes things get lost in the huge volume. - -What should you not do? - - - expect your patch to be accepted without question - - become defensive - - ignore comments - - resubmit the patch without making any of the requested changes - -In a community that is looking for the best technical solution possible, -there will always be differing opinions on how beneficial a patch is. -You have to be cooperative, and willing to adapt your idea to fit within -the kernel. Or at least be willing to prove your idea is worth it. -Remember, being wrong is acceptable as long as you are willing to work -toward a solution that is right. - -It is normal that the answers to your first patch might simply be a list -of a dozen things you should correct. This does **not** imply that your -patch will not be accepted, and it is **not** meant against you -personally. Simply correct all issues raised against your patch and -resend it. - - -Differences between the kernel community and corporate structures ------------------------------------------------------------------ - -The kernel community works differently than most traditional corporate -development environments. Here are a list of things that you can try to -do to avoid problems: - - Good things to say regarding your proposed changes: - - - "This solves multiple problems." - - "This deletes 2000 lines of code." - - "Here is a patch that explains what I am trying to describe." - - "I tested it on 5 different architectures..." - - "Here is a series of small patches that..." - - "This increases performance on typical machines..." - - Bad things you should avoid saying: - - - "We did it this way in AIX/ptx/Solaris, so therefore it must be - good..." - - "I've being doing this for 20 years, so..." - - "This is required for my company to make money" - - "This is for our Enterprise product line." - - "Here is my 1000 page design document that describes my idea" - - "I've been working on this for 6 months..." - - "Here's a 5000 line patch that..." - - "I rewrote all of the current mess, and here it is..." - - "I have a deadline, and this patch needs to be applied now." - -Another way the kernel community is different than most traditional -software engineering work environments is the faceless nature of -interaction. One benefit of using email and irc as the primary forms of -communication is the lack of discrimination based on gender or race. -The Linux kernel work environment is accepting of women and minorities -because all you are is an email address. The international aspect also -helps to level the playing field because you can't guess gender based on -a person's name. A man may be named Andrea and a woman may be named Pat. -Most women who have worked in the Linux kernel and have expressed an -opinion have had positive experiences. - -The language barrier can cause problems for some people who are not -comfortable with English. A good grasp of the language can be needed in -order to get ideas across properly on mailing lists, so it is -recommended that you check your emails to make sure they make sense in -English before sending them. - - -Break up your changes ---------------------- - -The Linux kernel community does not gladly accept large chunks of code -dropped on it all at once. The changes need to be properly introduced, -discussed, and broken up into tiny, individual portions. This is almost -the exact opposite of what companies are used to doing. Your proposal -should also be introduced very early in the development process, so that -you can receive feedback on what you are doing. It also lets the -community feel that you are working with them, and not simply using them -as a dumping ground for your feature. However, don't send 50 emails at -one time to a mailing list, your patch series should be smaller than -that almost all of the time. - -The reasons for breaking things up are the following: - -1) Small patches increase the likelihood that your patches will be - applied, since they don't take much time or effort to verify for - correctness. A 5 line patch can be applied by a maintainer with - barely a second glance. However, a 500 line patch may take hours to - review for correctness (the time it takes is exponentially - proportional to the size of the patch, or something). - - Small patches also make it very easy to debug when something goes - wrong. It's much easier to back out patches one by one than it is - to dissect a very large patch after it's been applied (and broken - something). - -2) It's important not only to send small patches, but also to rewrite - and simplify (or simply re-order) patches before submitting them. - -Here is an analogy from kernel developer Al Viro: - - *"Think of a teacher grading homework from a math student. The - teacher does not want to see the student's trials and errors - before they came up with the solution. They want to see the - cleanest, most elegant answer. A good student knows this, and - would never submit her intermediate work before the final - solution.* - - *The same is true of kernel development. The maintainers and - reviewers do not want to see the thought process behind the - solution to the problem one is solving. They want to see a - simple and elegant solution."* - -It may be challenging to keep the balance between presenting an elegant -solution and working together with the community and discussing your -unfinished work. Therefore it is good to get early in the process to -get feedback to improve your work, but also keep your changes in small -chunks that they may get already accepted, even when your whole task is -not ready for inclusion now. - -Also realize that it is not acceptable to send patches for inclusion -that are unfinished and will be "fixed up later." - - -Justify your change -------------------- - -Along with breaking up your patches, it is very important for you to let -the Linux community know why they should add this change. New features -must be justified as being needed and useful. - - -Document your change --------------------- - -When sending in your patches, pay special attention to what you say in -the text in your email. This information will become the ChangeLog -information for the patch, and will be preserved for everyone to see for -all time. It should describe the patch completely, containing: - - - why the change is necessary - - the overall design approach in the patch - - implementation details - - testing results - -For more details on what this should all look like, please see the -ChangeLog section of the document: - - "The Perfect Patch" - http://www.ozlabs.org/~akpm/stuff/tpp.txt - - -All of these things are sometimes very hard to do. It can take years to -perfect these practices (if at all). It's a continuous process of -improvement that requires a lot of patience and determination. But -don't give up, it's possible. Many have done it before, and each had to -start exactly where you are now. - - - - ----------- - -Thanks to Paolo Ciarrocchi who allowed the "Development Process" -(https://lwn.net/Articles/94386/) section -to be based on text he had written, and to Randy Dunlap and Gerrit -Huizenga for some of the list of things you should and should not say. -Also thanks to Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers, -Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi -Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop, -David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard for -their review, comments, and contributions. Without their help, this -document would not have been possible. - - - -Maintainer: Greg Kroah-Hartman diff --git a/Documentation/ManagementStyle b/Documentation/ManagementStyle deleted file mode 100644 index dea2e66c9a10..000000000000 --- a/Documentation/ManagementStyle +++ /dev/null @@ -1,288 +0,0 @@ -.. _managementstyle: - -Linux kernel management style -============================= - -This is a short document describing the preferred (or made up, depending -on who you ask) management style for the linux kernel. It's meant to -mirror the CodingStyle document to some degree, and mainly written to -avoid answering [#f1]_ the same (or similar) questions over and over again. - -Management style is very personal and much harder to quantify than -simple coding style rules, so this document may or may not have anything -to do with reality. It started as a lark, but that doesn't mean that it -might not actually be true. You'll have to decide for yourself. - -Btw, when talking about "kernel manager", it's all about the technical -lead persons, not the people who do traditional management inside -companies. If you sign purchase orders or you have any clue about the -budget of your group, you're almost certainly not a kernel manager. -These suggestions may or may not apply to you. - -First off, I'd suggest buying "Seven Habits of Highly Effective -People", and NOT read it. Burn it, it's a great symbolic gesture. - -.. [#f1] This document does so not so much by answering the question, but by - making it painfully obvious to the questioner that we don't have a clue - to what the answer is. - -Anyway, here goes: - -.. _decisions: - -1) Decisions ------------- - -Everybody thinks managers make decisions, and that decision-making is -important. The bigger and more painful the decision, the bigger the -manager must be to make it. That's very deep and obvious, but it's not -actually true. - -The name of the game is to **avoid** having to make a decision. In -particular, if somebody tells you "choose (a) or (b), we really need you -to decide on this", you're in trouble as a manager. The people you -manage had better know the details better than you, so if they come to -you for a technical decision, you're screwed. You're clearly not -competent to make that decision for them. - -(Corollary:if the people you manage don't know the details better than -you, you're also screwed, although for a totally different reason. -Namely that you are in the wrong job, and that **they** should be managing -your brilliance instead). - -So the name of the game is to **avoid** decisions, at least the big and -painful ones. Making small and non-consequential decisions is fine, and -makes you look like you know what you're doing, so what a kernel manager -needs to do is to turn the big and painful ones into small things where -nobody really cares. - -It helps to realize that the key difference between a big decision and a -small one is whether you can fix your decision afterwards. Any decision -can be made small by just always making sure that if you were wrong (and -you **will** be wrong), you can always undo the damage later by -backtracking. Suddenly, you get to be doubly managerial for making -**two** inconsequential decisions - the wrong one **and** the right one. - -And people will even see that as true leadership (*cough* bullshit -*cough*). - -Thus the key to avoiding big decisions becomes to just avoiding to do -things that can't be undone. Don't get ushered into a corner from which -you cannot escape. A cornered rat may be dangerous - a cornered manager -is just pitiful. - -It turns out that since nobody would be stupid enough to ever really let -a kernel manager have huge fiscal responsibility **anyway**, it's usually -fairly easy to backtrack. Since you're not going to be able to waste -huge amounts of money that you might not be able to repay, the only -thing you can backtrack on is a technical decision, and there -back-tracking is very easy: just tell everybody that you were an -incompetent nincompoop, say you're sorry, and undo all the worthless -work you had people work on for the last year. Suddenly the decision -you made a year ago wasn't a big decision after all, since it could be -easily undone. - -It turns out that some people have trouble with this approach, for two -reasons: - - - admitting you were an idiot is harder than it looks. We all like to - maintain appearances, and coming out in public to say that you were - wrong is sometimes very hard indeed. - - having somebody tell you that what you worked on for the last year - wasn't worthwhile after all can be hard on the poor lowly engineers - too, and while the actual **work** was easy enough to undo by just - deleting it, you may have irrevocably lost the trust of that - engineer. And remember: "irrevocable" was what we tried to avoid in - the first place, and your decision ended up being a big one after - all. - -Happily, both of these reasons can be mitigated effectively by just -admitting up-front that you don't have a friggin' clue, and telling -people ahead of the fact that your decision is purely preliminary, and -might be the wrong thing. You should always reserve the right to change -your mind, and make people very **aware** of that. And it's much easier -to admit that you are stupid when you haven't **yet** done the really -stupid thing. - -Then, when it really does turn out to be stupid, people just roll their -eyes and say "Oops, he did it again". - -This preemptive admission of incompetence might also make the people who -actually do the work also think twice about whether it's worth doing or -not. After all, if **they** aren't certain whether it's a good idea, you -sure as hell shouldn't encourage them by promising them that what they -work on will be included. Make them at least think twice before they -embark on a big endeavor. - -Remember: they'd better know more about the details than you do, and -they usually already think they have the answer to everything. The best -thing you can do as a manager is not to instill confidence, but rather a -healthy dose of critical thinking on what they do. - -Btw, another way to avoid a decision is to plaintively just whine "can't -we just do both?" and look pitiful. Trust me, it works. If it's not -clear which approach is better, they'll eventually figure it out. The -answer may end up being that both teams get so frustrated by the -situation that they just give up. - -That may sound like a failure, but it's usually a sign that there was -something wrong with both projects, and the reason the people involved -couldn't decide was that they were both wrong. You end up coming up -smelling like roses, and you avoided yet another decision that you could -have screwed up on. - - -2) People ---------- - -Most people are idiots, and being a manager means you'll have to deal -with it, and perhaps more importantly, that **they** have to deal with -**you**. - -It turns out that while it's easy to undo technical mistakes, it's not -as easy to undo personality disorders. You just have to live with -theirs - and yours. - -However, in order to prepare yourself as a kernel manager, it's best to -remember not to burn any bridges, bomb any innocent villagers, or -alienate too many kernel developers. It turns out that alienating people -is fairly easy, and un-alienating them is hard. Thus "alienating" -immediately falls under the heading of "not reversible", and becomes a -no-no according to :ref:`decisions`. - -There's just a few simple rules here: - - (1) don't call people d*ckheads (at least not in public) - (2) learn how to apologize when you forgot rule (1) - -The problem with #1 is that it's very easy to do, since you can say -"you're a d*ckhead" in millions of different ways [#f2]_, sometimes without -even realizing it, and almost always with a white-hot conviction that -you are right. - -And the more convinced you are that you are right (and let's face it, -you can call just about **anybody** a d*ckhead, and you often **will** be -right), the harder it ends up being to apologize afterwards. - -To solve this problem, you really only have two options: - - - get really good at apologies - - spread the "love" out so evenly that nobody really ends up feeling - like they get unfairly targeted. Make it inventive enough, and they - might even be amused. - -The option of being unfailingly polite really doesn't exist. Nobody will -trust somebody who is so clearly hiding his true character. - -.. [#f2] Paul Simon sang "Fifty Ways to Leave Your Lover", because quite - frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't - scan nearly as well. But I'm sure he thought about it. - - -3) People II - the Good Kind ----------------------------- - -While it turns out that most people are idiots, the corollary to that is -sadly that you are one too, and that while we can all bask in the secure -knowledge that we're better than the average person (let's face it, -nobody ever believes that they're average or below-average), we should -also admit that we're not the sharpest knife around, and there will be -other people that are less of an idiot than you are. - -Some people react badly to smart people. Others take advantage of them. - -Make sure that you, as a kernel maintainer, are in the second group. -Suck up to them, because they are the people who will make your job -easier. In particular, they'll be able to make your decisions for you, -which is what the game is all about. - -So when you find somebody smarter than you are, just coast along. Your -management responsibilities largely become ones of saying "Sounds like a -good idea - go wild", or "That sounds good, but what about xxx?". The -second version in particular is a great way to either learn something -new about "xxx" or seem **extra** managerial by pointing out something the -smarter person hadn't thought about. In either case, you win. - -One thing to look out for is to realize that greatness in one area does -not necessarily translate to other areas. So you might prod people in -specific directions, but let's face it, they might be good at what they -do, and suck at everything else. The good news is that people tend to -naturally gravitate back to what they are good at, so it's not like you -are doing something irreversible when you **do** prod them in some -direction, just don't push too hard. - - -4) Placing blame ----------------- - -Things will go wrong, and people want somebody to blame. Tag, you're it. - -It's not actually that hard to accept the blame, especially if people -kind of realize that it wasn't **all** your fault. Which brings us to the -best way of taking the blame: do it for another guy. You'll feel good -for taking the fall, he'll feel good about not getting blamed, and the -guy who lost his whole 36GB porn-collection because of your incompetence -will grudgingly admit that you at least didn't try to weasel out of it. - -Then make the developer who really screwed up (if you can find him) know -**in_private** that he screwed up. Not just so he can avoid it in the -future, but so that he knows he owes you one. And, perhaps even more -importantly, he's also likely the person who can fix it. Because, let's -face it, it sure ain't you. - -Taking the blame is also why you get to be manager in the first place. -It's part of what makes people trust you, and allow you the potential -glory, because you're the one who gets to say "I screwed up". And if -you've followed the previous rules, you'll be pretty good at saying that -by now. - - -5) Things to avoid ------------------- - -There's one thing people hate even more than being called "d*ckhead", -and that is being called a "d*ckhead" in a sanctimonious voice. The -first you can apologize for, the second one you won't really get the -chance. They likely will no longer be listening even if you otherwise -do a good job. - -We all think we're better than anybody else, which means that when -somebody else puts on airs, it **really** rubs us the wrong way. You may -be morally and intellectually superior to everybody around you, but -don't try to make it too obvious unless you really **intend** to irritate -somebody [#f3]_. - -Similarly, don't be too polite or subtle about things. Politeness easily -ends up going overboard and hiding the problem, and as they say, "On the -internet, nobody can hear you being subtle". Use a big blunt object to -hammer the point in, because you can't really depend on people getting -your point otherwise. - -Some humor can help pad both the bluntness and the moralizing. Going -overboard to the point of being ridiculous can drive a point home -without making it painful to the recipient, who just thinks you're being -silly. It can thus help get through the personal mental block we all -have about criticism. - -.. [#f3] Hint: internet newsgroups that are not directly related to your work - are great ways to take out your frustrations at other people. Write - insulting posts with a sneer just to get into a good flame every once in - a while, and you'll feel cleansed. Just don't crap too close to home. - - -6) Why me? ----------- - -Since your main responsibility seems to be to take the blame for other -peoples mistakes, and make it painfully obvious to everybody else that -you're incompetent, the obvious question becomes one of why do it in the -first place? - -First off, while you may or may not get screaming teenage girls (or -boys, let's not be judgmental or sexist here) knocking on your dressing -room door, you **will** get an immense feeling of personal accomplishment -for being "in charge". Never mind the fact that you're really leading -by trying to keep up with everybody else and running after them as fast -as you can. Everybody will still think you're the person in charge. - -It's a great job if you can hack it. diff --git a/Documentation/SubmitChecklist b/Documentation/SubmitChecklist deleted file mode 100644 index 894289b22b15..000000000000 --- a/Documentation/SubmitChecklist +++ /dev/null @@ -1,120 +0,0 @@ -.. _submitchecklist: - -Linux Kernel patch submission checklist -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Here are some basic things that developers should do if they want to see their -kernel patch submissions accepted more quickly. - -These are all above and beyond the documentation that is provided in -:ref:`Documentation/SubmittingPatches ` -and elsewhere regarding submitting Linux kernel patches. - - -1) If you use a facility then #include the file that defines/declares - that facility. Don't depend on other header files pulling in ones - that you use. - -2) Builds cleanly: - - a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and - ``=n``. No ``gcc`` warnings/errors, no linker warnings/errors. - - b) Passes ``allnoconfig``, ``allmodconfig`` - - c) Builds successfully when using ``O=builddir`` - -3) Builds on multiple CPU architectures by using local cross-compile tools - or some other build farm. - -4) ppc64 is a good architecture for cross-compilation checking because it - tends to use ``unsigned long`` for 64-bit quantities. - -5) Check your patch for general style as detailed in - :ref:`Documentation/CodingStyle `. - Check for trivial violations with the patch style checker prior to - submission (``scripts/checkpatch.pl``). - You should be able to justify all violations that remain in - your patch. - -6) Any new or modified ``CONFIG`` options don't muck up the config menu. - -7) All new ``Kconfig`` options have help text. - -8) Has been carefully reviewed with respect to relevant ``Kconfig`` - combinations. This is very hard to get right with testing -- brainpower - pays off here. - -9) Check cleanly with sparse. - -10) Use ``make checkstack`` and ``make namespacecheck`` and fix any problems - that they find. - - .. note:: - - ``checkstack`` does not point out problems explicitly, - but any one function that uses more than 512 bytes on the stack is a - candidate for change. - -11) Include :ref:`kernel-doc ` to document global kernel APIs. - (Not required for static functions, but OK there also.) Use - ``make htmldocs`` or ``make pdfdocs`` to check the - :ref:`kernel-doc ` and fix any issues. - -12) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, - ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, - ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, - ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` all - simultaneously enabled. - -13) Has been build- and runtime tested with and without ``CONFIG_SMP`` and - ``CONFIG_PREEMPT.`` - -14) If the patch affects IO/Disk, etc: has been tested with and without - ``CONFIG_LBDAF.`` - -15) All codepaths have been exercised with all lockdep features enabled. - -16) All new ``/proc`` entries are documented under ``Documentation/`` - -17) All new kernel boot parameters are documented in - ``Documentation/kernel-parameters.txt``. - -18) All new module parameters are documented with ``MODULE_PARM_DESC()`` - -19) All new userspace interfaces are documented in ``Documentation/ABI/``. - See ``Documentation/ABI/README`` for more information. - Patches that change userspace interfaces should be CCed to - linux-api@vger.kernel.org. - -20) Check that it all passes ``make headers_check``. - -21) Has been checked with injection of at least slab and page-allocation - failures. See ``Documentation/fault-injection/``. - - If the new code is substantial, addition of subsystem-specific fault - injection might be appropriate. - -22) Newly-added code has been compiled with ``gcc -W`` (use - ``make EXTRA_CFLAGS=-W``). This will generate lots of noise, but is good - for finding bugs like "warning: comparison between signed and unsigned". - -23) Tested after it has been merged into the -mm patchset to make sure - that it still works with all of the other queued patches and various - changes in the VM, VFS, and other subsystems. - -24) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a - comment in the source code that explains the logic of what they are doing - and why. - -25) If any ioctl's are added by the patch, then also update - ``Documentation/ioctl/ioctl-number.txt``. - -26) If your modified source code depends on or uses any of the kernel - APIs or features that are related to the following ``Kconfig`` symbols, - then test multiple builds with the related ``Kconfig`` symbols disabled - and/or ``=m`` (if that option is available) [not all of these at the - same time, just various/random combinations of them]: - - ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, - ``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``). diff --git a/Documentation/SubmittingDrivers b/Documentation/SubmittingDrivers deleted file mode 100644 index 252b77a23fad..000000000000 --- a/Documentation/SubmittingDrivers +++ /dev/null @@ -1,183 +0,0 @@ -.. _submittingdrivers: - -Submitting Drivers For The Linux Kernel -======================================= - -This document is intended to explain how to submit device drivers to the -various kernel trees. Note that if you are interested in video card drivers -you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org -(http://x.org/) instead. - -Also read the Documentation/SubmittingPatches document. - - -Allocating Device Numbers -------------------------- - -Major and minor numbers for block and character devices are allocated -by the Linux assigned name and number authority (currently this is -Torben Mathiasen). The site is http://www.lanana.org/. This -also deals with allocating numbers for devices that are not going to -be submitted to the mainstream kernel. -See Documentation/devices.txt for more information on this. - -If you don't use assigned numbers then when your device is submitted it will -be given an assigned number even if that is different from values you may -have shipped to customers before. - -Who To Submit Drivers To ------------------------- - -Linux 2.0: - No new drivers are accepted for this kernel tree. - -Linux 2.2: - No new drivers are accepted for this kernel tree. - -Linux 2.4: - If the code area has a general maintainer then please submit it to - the maintainer listed in MAINTAINERS in the kernel file. If the - maintainer does not respond or you cannot find the appropriate - maintainer then please contact Willy Tarreau . - -Linux 2.6 and upper: - The same rules apply as 2.4 except that you should follow linux-kernel - to track changes in API's. The final contact point for Linux 2.6+ - submissions is Andrew Morton. - -What Criteria Determine Acceptance ----------------------------------- - -Licensing: - The code must be released to us under the - GNU General Public License. We don't insist on any kind - of exclusive GPL licensing, and if you wish the driver - to be useful to other communities such as BSD you may well - wish to release under multiple licenses. - See accepted licenses at include/linux/module.h - -Copyright: - The copyright owner must agree to use of GPL. - It's best if the submitter and copyright owner - are the same person/entity. If not, the name of - the person/entity authorizing use of GPL should be - listed in case it's necessary to verify the will of - the copyright owner. - -Interfaces: - If your driver uses existing interfaces and behaves like - other drivers in the same class it will be much more likely - to be accepted than if it invents gratuitous new ones. - If you need to implement a common API over Linux and NT - drivers do it in userspace. - -Code: - Please use the Linux style of code formatting as documented - in :ref:`Documentation/CodingStyle `. - If you have sections of code - that need to be in other formats, for example because they - are shared with a windows driver kit and you want to - maintain them just once separate them out nicely and note - this fact. - -Portability: - Pointers are not always 32bits, not all computers are little - endian, people do not all have floating point and you - shouldn't use inline x86 assembler in your driver without - careful thought. Pure x86 drivers generally are not popular. - If you only have x86 hardware it is hard to test portability - but it is easy to make sure the code can easily be made - portable. - -Clarity: - It helps if anyone can see how to fix the driver. It helps - you because you get patches not bug reports. If you submit a - driver that intentionally obfuscates how the hardware works - it will go in the bitbucket. - -PM support: - Since Linux is used on many portable and desktop systems, your - driver is likely to be used on such a system and therefore it - should support basic power management by implementing, if - necessary, the .suspend and .resume methods used during the - system-wide suspend and resume transitions. You should verify - that your driver correctly handles the suspend and resume, but - if you are unable to ensure that, please at least define the - .suspend method returning the -ENOSYS ("Function not - implemented") error. You should also try to make sure that your - driver uses as little power as possible when it's not doing - anything. For the driver testing instructions see - Documentation/power/drivers-testing.txt and for a relatively - complete overview of the power management issues related to - drivers see Documentation/power/devices.txt . - -Control: - In general if there is active maintenance of a driver by - the author then patches will be redirected to them unless - they are totally obvious and without need of checking. - If you want to be the contact and update point for the - driver it is a good idea to state this in the comments, - and include an entry in MAINTAINERS for your driver. - -What Criteria Do Not Determine Acceptance ------------------------------------------ - -Vendor: - Being the hardware vendor and maintaining the driver is - often a good thing. If there is a stable working driver from - other people already in the tree don't expect 'we are the - vendor' to get your driver chosen. Ideally work with the - existing driver author to build a single perfect driver. - -Author: - It doesn't matter if a large Linux company wrote the driver, - or you did. Nobody has any special access to the kernel - tree. Anyone who tells you otherwise isn't telling the - whole story. - - -Resources ---------- - -Linux kernel master tree: - ftp.\ *country_code*\ .kernel.org:/pub/linux/kernel/... - - where *country_code* == your country code, such as - **us**, **uk**, **fr**, etc. - - http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git - -Linux kernel mailing list: - linux-kernel@vger.kernel.org - [mail majordomo@vger.kernel.org to subscribe] - -Linux Device Drivers, Third Edition (covers 2.6.10): - http://lwn.net/Kernel/LDD3/ (free version) - -LWN.net: - Weekly summary of kernel development activity - http://lwn.net/ - - 2.6 API changes: - - http://lwn.net/Articles/2.6-kernel-api/ - - Porting drivers from prior kernels to 2.6: - - http://lwn.net/Articles/driver-porting/ - -KernelNewbies: - Documentation and assistance for new kernel programmers - - http://kernelnewbies.org/ - -Linux USB project: - http://www.linux-usb.org/ - -How to NOT write kernel driver by Arjan van de Ven: - http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf - -Kernel Janitor: - http://kernelnewbies.org/KernelJanitors - -GIT, Fast Version Control System: - http://git-scm.com/ diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches deleted file mode 100644 index e62ddcdcaf5d..000000000000 --- a/Documentation/SubmittingPatches +++ /dev/null @@ -1,841 +0,0 @@ -.. _submittingpatches: - -How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds -========================================================================================= - -For a person or company who wishes to submit a change to the Linux -kernel, the process can sometimes be daunting if you're not familiar -with "the system." This text is a collection of suggestions which -can greatly increase the chances of your change being accepted. - -This document contains a large number of suggestions in a relatively terse -format. For detailed information on how the kernel development process -works, see :ref:`Documentation/process `. -Also, read :ref:`Documentation/SubmitChecklist ` -for a list of items to check before -submitting code. If you are submitting a driver, also read -:ref:`Documentation/SubmittingDrivers `; -for device tree binding patches, read -Documentation/devicetree/bindings/submitting-patches.txt. - -Many of these steps describe the default behavior of the ``git`` version -control system; if you use ``git`` to prepare your patches, you'll find much -of the mechanical work done for you, though you'll still need to prepare -and document a sensible set of patches. In general, use of ``git`` will make -your life as a kernel developer easier. - -Creating and Sending your Change -******************************** - - -0) Obtain a current source tree -------------------------------- - -If you do not have a repository with the current kernel source handy, use -``git`` to obtain one. You'll want to start with the mainline repository, -which can be grabbed with:: - - git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git - -Note, however, that you may not want to develop against the mainline tree -directly. Most subsystem maintainers run their own trees and want to see -patches prepared against those trees. See the **T:** entry for the subsystem -in the MAINTAINERS file to find that tree, or simply ask the maintainer if -the tree is not listed there. - -It is still possible to download kernel releases via tarballs (as described -in the next section), but that is the hard way to do kernel development. - -1) ``diff -up`` ---------------- - -If you must generate your patches by hand, use ``diff -up`` or ``diff -uprN`` -to create patches. Git generates patches in this form by default; if -you're using ``git``, you can skip this section entirely. - -All changes to the Linux kernel occur in the form of patches, as -generated by :manpage:`diff(1)`. When creating your patch, make sure to -create it in "unified diff" format, as supplied by the ``-u`` argument -to :manpage:`diff(1)`. -Also, please use the ``-p`` argument which shows which C function each -change is in - that makes the resultant ``diff`` a lot easier to read. -Patches should be based in the root kernel source directory, -not in any lower subdirectory. - -To create a patch for a single file, it is often sufficient to do:: - - SRCTREE= linux - MYFILE= drivers/net/mydriver.c - - cd $SRCTREE - cp $MYFILE $MYFILE.orig - vi $MYFILE # make your change - cd .. - diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch - -To create a patch for multiple files, you should unpack a "vanilla", -or unmodified kernel source tree, and generate a ``diff`` against your -own source tree. For example:: - - MYSRC= /devel/linux - - tar xvfz linux-3.19.tar.gz - mv linux-3.19 linux-3.19-vanilla - diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ - linux-3.19-vanilla $MYSRC > /tmp/patch - -``dontdiff`` is a list of files which are generated by the kernel during -the build process, and should be ignored in any :manpage:`diff(1)`-generated -patch. - -Make sure your patch does not include any extra files which do not -belong in a patch submission. Make sure to review your patch -after- -generating it with :manpage:`diff(1)`, to ensure accuracy. - -If your changes produce a lot of deltas, you need to split them into -individual patches which modify things in logical stages; see -:ref:`split_changes`. This will facilitate review by other kernel developers, -very important if you want your patch accepted. - -If you're using ``git``, ``git rebase -i`` can help you with this process. If -you're not using ``git``, ``quilt`` -is another popular alternative. - -.. _describe_changes: - -2) Describe your changes ------------------------- - -Describe your problem. Whether your patch is a one-line bug fix or -5000 lines of a new feature, there must be an underlying problem that -motivated you to do this work. Convince the reviewer that there is a -problem worth fixing and that it makes sense for them to read past the -first paragraph. - -Describe user-visible impact. Straight up crashes and lockups are -pretty convincing, but not all bugs are that blatant. Even if the -problem was spotted during code review, describe the impact you think -it can have on users. Keep in mind that the majority of Linux -installations run kernels from secondary stable trees or -vendor/product-specific trees that cherry-pick only specific patches -from upstream, so include anything that could help route your change -downstream: provoking circumstances, excerpts from dmesg, crash -descriptions, performance regressions, latency spikes, lockups, etc. - -Quantify optimizations and trade-offs. If you claim improvements in -performance, memory consumption, stack footprint, or binary size, -include numbers that back them up. But also describe non-obvious -costs. Optimizations usually aren't free but trade-offs between CPU, -memory, and readability; or, when it comes to heuristics, between -different workloads. Describe the expected downsides of your -optimization so that the reviewer can weigh costs against benefits. - -Once the problem is established, describe what you are actually doing -about it in technical detail. It's important to describe the change -in plain English for the reviewer to verify that the code is behaving -as you intend it to. - -The maintainer will thank you if you write your patch description in a -form which can be easily pulled into Linux's source code management -system, ``git``, as a "commit log". See :ref:`explicit_in_reply_to`. - -Solve only one problem per patch. If your description starts to get -long, that's a sign that you probably need to split up your patch. -See :ref:`split_changes`. - -When you submit or resubmit a patch or patch series, include the -complete patch description and justification for it. Don't just -say that this is version N of the patch (series). Don't expect the -subsystem maintainer to refer back to earlier patch versions or referenced -URLs to find the patch description and put that into the patch. -I.e., the patch (series) and its description should be self-contained. -This benefits both the maintainers and reviewers. Some reviewers -probably didn't even receive earlier versions of the patch. - -Describe your changes in imperative mood, e.g. "make xyzzy do frotz" -instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy -to do frotz", as if you are giving orders to the codebase to change -its behaviour. - -If the patch fixes a logged bug entry, refer to that bug entry by -number and URL. If the patch follows from a mailing list discussion, -give a URL to the mailing list archive; use the https://lkml.kernel.org/ -redirector with a ``Message-Id``, to ensure that the links cannot become -stale. - -However, try to make your explanation understandable without external -resources. In addition to giving a URL to a mailing list archive or -bug, summarize the relevant points of the discussion that led to the -patch as submitted. - -If you want to refer to a specific commit, don't just refer to the -SHA-1 ID of the commit. Please also include the oneline summary of -the commit, to make it easier for reviewers to know what it is about. -Example:: - - Commit e21d2170f36602ae2708 ("video: remove unnecessary - platform_set_drvdata()") removed the unnecessary - platform_set_drvdata(), but left the variable "dev" unused, - delete it. - -You should also be sure to use at least the first twelve characters of the -SHA-1 ID. The kernel repository holds a *lot* of objects, making -collisions with shorter IDs a real possibility. Bear in mind that, even if -there is no collision with your six-character ID now, that condition may -change five years from now. - -If your patch fixes a bug in a specific commit, e.g. you found an issue using -``git bisect``, please use the 'Fixes:' tag with the first 12 characters of -the SHA-1 ID, and the one line summary. For example:: - - Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()") - -The following ``git config`` settings can be used to add a pretty format for -outputting the above style in the ``git log`` or ``git show`` commands:: - - [core] - abbrev = 12 - [pretty] - fixes = Fixes: %h (\"%s\") - -.. _split_changes: - -3) Separate your changes ------------------------- - -Separate each **logical change** into a separate patch. - -For example, if your changes include both bug fixes and performance -enhancements for a single driver, separate those changes into two -or more patches. If your changes include an API update, and a new -driver which uses that new API, separate those into two patches. - -On the other hand, if you make a single change to numerous files, -group those changes into a single patch. Thus a single logical change -is contained within a single patch. - -The point to remember is that each patch should make an easily understood -change that can be verified by reviewers. Each patch should be justifiable -on its own merits. - -If one patch depends on another patch in order for a change to be -complete, that is OK. Simply note **"this patch depends on patch X"** -in your patch description. - -When dividing your change into a series of patches, take special care to -ensure that the kernel builds and runs properly after each patch in the -series. Developers using ``git bisect`` to track down a problem can end up -splitting your patch series at any point; they will not thank you if you -introduce bugs in the middle. - -If you cannot condense your patch set into a smaller set of patches, -then only post say 15 or so at a time and wait for review and integration. - - - -4) Style-check your changes ---------------------------- - -Check your patch for basic style violations, details of which can be -found in -:ref:`Documentation/CodingStyle `. -Failure to do so simply wastes -the reviewers time and will get your patch rejected, probably -without even being read. - -One significant exception is when moving code from one file to -another -- in this case you should not modify the moved code at all in -the same patch which moves it. This clearly delineates the act of -moving the code and your changes. This greatly aids review of the -actual differences and allows tools to better track the history of -the code itself. - -Check your patches with the patch style checker prior to submission -(scripts/checkpatch.pl). Note, though, that the style checker should be -viewed as a guide, not as a replacement for human judgment. If your code -looks better with a violation then its probably best left alone. - -The checker reports at three levels: - - ERROR: things that are very likely to be wrong - - WARNING: things requiring careful review - - CHECK: things requiring thought - -You should be able to justify all violations that remain in your -patch. - - -5) Select the recipients for your patch ---------------------------------------- - -You should always copy the appropriate subsystem maintainer(s) on any patch -to code that they maintain; look through the MAINTAINERS file and the -source code revision history to see who those maintainers are. The -script scripts/get_maintainer.pl can be very useful at this step. If you -cannot find a maintainer for the subsystem you are working on, Andrew -Morton (akpm@linux-foundation.org) serves as a maintainer of last resort. - -You should also normally choose at least one mailing list to receive a copy -of your patch set. linux-kernel@vger.kernel.org functions as a list of -last resort, but the volume on that list has caused a number of developers -to tune it out. Look in the MAINTAINERS file for a subsystem-specific -list; your patch will probably get more attention there. Please do not -spam unrelated lists, though. - -Many kernel-related lists are hosted on vger.kernel.org; you can find a -list of them at http://vger.kernel.org/vger-lists.html. There are -kernel-related lists hosted elsewhere as well, though. - -Do not send more than 15 patches at once to the vger mailing lists!!! - -Linus Torvalds is the final arbiter of all changes accepted into the -Linux kernel. His e-mail address is . -He gets a lot of e-mail, and, at this point, very few patches go through -Linus directly, so typically you should do your best to -avoid- -sending him e-mail. - -If you have a patch that fixes an exploitable security bug, send that patch -to security@kernel.org. For severe bugs, a short embargo may be considered -to allow distributors to get the patch out to users; in such cases, -obviously, the patch should not be sent to any public lists. - -Patches that fix a severe bug in a released kernel should be directed -toward the stable maintainers by putting a line like this:: - - Cc: stable@vger.kernel.org - -into the sign-off area of your patch (note, NOT an email recipient). You -should also read -:ref:`Documentation/stable_kernel_rules.txt ` -in addition to this file. - -Note, however, that some subsystem maintainers want to come to their own -conclusions on which patches should go to the stable trees. The networking -maintainer, in particular, would rather not see individual developers -adding lines like the above to their patches. - -If changes affect userland-kernel interfaces, please send the MAN-PAGES -maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at -least a notification of the change, so that some information makes its way -into the manual pages. User-space API changes should also be copied to -linux-api@vger.kernel.org. - -For small patches you may want to CC the Trivial Patch Monkey -trivial@kernel.org which collects "trivial" patches. Have a look -into the MAINTAINERS file for its current manager. - -Trivial patches must qualify for one of the following rules: - -- Spelling fixes in documentation -- Spelling fixes for errors which could break :manpage:`grep(1)` -- Warning fixes (cluttering with useless warnings is bad) -- Compilation fixes (only if they are actually correct) -- Runtime fixes (only if they actually fix things) -- Removing use of deprecated functions/macros -- Contact detail and documentation fixes -- Non-portable code replaced by portable code (even in arch-specific, - since people copy, as long as it's trivial) -- Any fix by the author/maintainer of the file (ie. patch monkey - in re-transmission mode) - - - -6) No MIME, no links, no compression, no attachments. Just plain text ----------------------------------------------------------------------- - -Linus and other kernel developers need to be able to read and comment -on the changes you are submitting. It is important for a kernel -developer to be able to "quote" your changes, using standard e-mail -tools, so that they may comment on specific portions of your code. - -For this reason, all patches should be submitted by e-mail "inline". - -.. warning:: - - Be wary of your editor's word-wrap corrupting your patch, - if you choose to cut-n-paste your patch. - -Do not attach the patch as a MIME attachment, compressed or not. -Many popular e-mail applications will not always transmit a MIME -attachment as plain text, making it impossible to comment on your -code. A MIME attachment also takes Linus a bit more time to process, -decreasing the likelihood of your MIME-attached change being accepted. - -Exception: If your mailer is mangling patches then someone may ask -you to re-send them using MIME. - -See :ref:`Documentation/email-clients.txt ` -for hints about configuring your e-mail client so that it sends your patches -untouched. - -7) E-mail size --------------- - -Large changes are not appropriate for mailing lists, and some -maintainers. If your patch, uncompressed, exceeds 300 kB in size, -it is preferred that you store your patch on an Internet-accessible -server, and provide instead a URL (link) pointing to your patch. But note -that if your patch exceeds 300 kB, it almost certainly needs to be broken up -anyway. - -8) Respond to review comments ------------------------------ - -Your patch will almost certainly get comments from reviewers on ways in -which the patch can be improved. You must respond to those comments; -ignoring reviewers is a good way to get ignored in return. Review comments -or questions that do not lead to a code change should almost certainly -bring about a comment or changelog entry so that the next reviewer better -understands what is going on. - -Be sure to tell the reviewers what changes you are making and to thank them -for their time. Code review is a tiring and time-consuming process, and -reviewers sometimes get grumpy. Even in that case, though, respond -politely and address the problems they have pointed out. - - -9) Don't get discouraged - or impatient ---------------------------------------- - -After you have submitted your change, be patient and wait. Reviewers are -busy people and may not get to your patch right away. - -Once upon a time, patches used to disappear into the void without comment, -but the development process works more smoothly than that now. You should -receive comments within a week or so; if that does not happen, make sure -that you have sent your patches to the right place. Wait for a minimum of -one week before resubmitting or pinging reviewers - possibly longer during -busy times like merge windows. - - -10) Include PATCH in the subject --------------------------------- - -Due to high e-mail traffic to Linus, and to linux-kernel, it is common -convention to prefix your subject line with [PATCH]. This lets Linus -and other kernel developers more easily distinguish patches from other -e-mail discussions. - - - -11) Sign your work ------------------- - -To improve tracking of who did what, especially with patches that can -percolate to their final resting place in the kernel through several -layers of maintainers, we've introduced a "sign-off" procedure on -patches that are being emailed around. - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below: - -Developer's Certificate of Origin 1.1 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -By making a contribution to this project, I certify that: - - (a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - - (b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - - (c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - - (d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. - -then you just add a line saying:: - - Signed-off-by: Random J Developer - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -Some people also put extra tags at the end. They'll just be ignored for -now, but you can do this to mark internal company procedures or just -point out some special detail about the sign-off. - -If you are a subsystem or branch maintainer, sometimes you need to slightly -modify patches you receive in order to merge them, because the code is not -exactly the same in your tree and the submitters'. If you stick strictly to -rule (c), you should ask the submitter to rediff, but this is a totally -counter-productive waste of time and energy. Rule (b) allows you to adjust -the code, but then it is very impolite to change one submitter's code and -make him endorse your bugs. To solve this problem, it is recommended that -you add a line between the last Signed-off-by header and yours, indicating -the nature of your changes. While there is nothing mandatory about this, it -seems like prepending the description with your mail and/or name, all -enclosed in square brackets, is noticeable enough to make it obvious that -you are responsible for last-minute changes. Example:: - - Signed-off-by: Random J Developer - [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] - Signed-off-by: Lucky K Maintainer - -This practice is particularly helpful if you maintain a stable branch and -want at the same time to credit the author, track changes, merge the fix, -and protect the submitter from complaints. Note that under no circumstances -can you change the author's identity (the From header), as it is the one -which appears in the changelog. - -Special note to back-porters: It seems to be a common and useful practice -to insert an indication of the origin of a patch at the top of the commit -message (just after the subject line) to facilitate tracking. For instance, -here's what we see in a 3.x-stable release:: - - Date: Tue Oct 7 07:26:38 2014 -0400 - - libata: Un-break ATA blacklist - - commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. - -And here's what might appear in an older kernel once a patch is backported:: - - Date: Tue May 13 22:12:27 2008 +0200 - - wireless, airo: waitbusy() won't delay - - [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] - -Whatever the format, this information provides a valuable help to people -tracking your trees, and to people trying to troubleshoot bugs in your -tree. - - -12) When to use Acked-by: and Cc: ---------------------------------- - -The Signed-off-by: tag indicates that the signer was involved in the -development of the patch, or that he/she was in the patch's delivery path. - -If a person was not directly involved in the preparation or handling of a -patch but wishes to signify and record their approval of it then they can -ask to have an Acked-by: line added to the patch's changelog. - -Acked-by: is often used by the maintainer of the affected code when that -maintainer neither contributed to nor forwarded the patch. - -Acked-by: is not as formal as Signed-off-by:. It is a record that the acker -has at least reviewed the patch and has indicated acceptance. Hence patch -mergers will sometimes manually convert an acker's "yep, looks good to me" -into an Acked-by: (but note that it is usually better to ask for an -explicit ack). - -Acked-by: does not necessarily indicate acknowledgement of the entire patch. -For example, if a patch affects multiple subsystems and has an Acked-by: from -one subsystem maintainer then this usually indicates acknowledgement of just -the part which affects that maintainer's code. Judgement should be used here. -When in doubt people should refer to the original discussion in the mailing -list archives. - -If a person has had the opportunity to comment on a patch, but has not -provided such comments, you may optionally add a ``Cc:`` tag to the patch. -This is the only tag which might be added without an explicit action by the -person it names - but it should indicate that this person was copied on the -patch. This tag documents that potentially interested parties -have been included in the discussion. - - -13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: --------------------------------------------------------------------------- - -The Reported-by tag gives credit to people who find bugs and report them and it -hopefully inspires them to help us again in the future. Please note that if -the bug was reported in private, then ask for permission first before using the -Reported-by tag. - -A Tested-by: tag indicates that the patch has been successfully tested (in -some environment) by the person named. This tag informs maintainers that -some testing has been performed, provides a means to locate testers for -future patches, and ensures credit for the testers. - -Reviewed-by:, instead, indicates that the patch has been reviewed and found -acceptable according to the Reviewer's Statement: - -Reviewer's statement of oversight -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -By offering my Reviewed-by: tag, I state that: - - (a) I have carried out a technical review of this patch to - evaluate its appropriateness and readiness for inclusion into - the mainline kernel. - - (b) Any problems, concerns, or questions relating to the patch - have been communicated back to the submitter. I am satisfied - with the submitter's response to my comments. - - (c) While there may be things that could be improved with this - submission, I believe that it is, at this time, (1) a - worthwhile modification to the kernel, and (2) free of known - issues which would argue against its inclusion. - - (d) While I have reviewed the patch and believe it to be sound, I - do not (unless explicitly stated elsewhere) make any - warranties or guarantees that it will achieve its stated - purpose or function properly in any given situation. - -A Reviewed-by tag is a statement of opinion that the patch is an -appropriate modification of the kernel without any remaining serious -technical issues. Any interested reviewer (who has done the work) can -offer a Reviewed-by tag for a patch. This tag serves to give credit to -reviewers and to inform maintainers of the degree of review which has been -done on the patch. Reviewed-by: tags, when supplied by reviewers known to -understand the subject area and to perform thorough reviews, will normally -increase the likelihood of your patch getting into the kernel. - -A Suggested-by: tag indicates that the patch idea is suggested by the person -named and ensures credit to the person for the idea. Please note that this -tag should not be added without the reporter's permission, especially if the -idea was not posted in a public forum. That said, if we diligently credit our -idea reporters, they will, hopefully, be inspired to help us again in the -future. - -A Fixes: tag indicates that the patch fixes an issue in a previous commit. It -is used to make it easy to determine where a bug originated, which can help -review a bug fix. This tag also assists the stable kernel team in determining -which stable kernel versions should receive your fix. This is the preferred -method for indicating a bug fixed by the patch. See :ref:`describe_changes` -for more details. - - -14) The canonical patch format ------------------------------- - -This section describes how the patch itself should be formatted. Note -that, if you have your patches stored in a ``git`` repository, proper patch -formatting can be had with ``git format-patch``. The tools cannot create -the necessary text, though, so read the instructions below anyway. - -The canonical patch subject line is:: - - Subject: [PATCH 001/123] subsystem: summary phrase - -The canonical patch message body contains the following: - - - A ``from`` line specifying the patch author (only needed if the person - sending the patch is not the author). - - - An empty line. - - - The body of the explanation, line wrapped at 75 columns, which will - be copied to the permanent changelog to describe this patch. - - - The ``Signed-off-by:`` lines, described above, which will - also go in the changelog. - - - A marker line containing simply ``---``. - - - Any additional comments not suitable for the changelog. - - - The actual patch (``diff`` output). - -The Subject line format makes it very easy to sort the emails -alphabetically by subject line - pretty much any email reader will -support that - since because the sequence number is zero-padded, -the numerical and alphabetic sort is the same. - -The ``subsystem`` in the email's Subject should identify which -area or subsystem of the kernel is being patched. - -The ``summary phrase`` in the email's Subject should concisely -describe the patch which that email contains. The ``summary -phrase`` should not be a filename. Do not use the same ``summary -phrase`` for every patch in a whole patch series (where a ``patch -series`` is an ordered sequence of multiple, related patches). - -Bear in mind that the ``summary phrase`` of your email becomes a -globally-unique identifier for that patch. It propagates all the way -into the ``git`` changelog. The ``summary phrase`` may later be used in -developer discussions which refer to the patch. People will want to -google for the ``summary phrase`` to read discussion regarding that -patch. It will also be the only thing that people may quickly see -when, two or three months later, they are going through perhaps -thousands of patches using tools such as ``gitk`` or ``git log ---oneline``. - -For these reasons, the ``summary`` must be no more than 70-75 -characters, and it must describe both what the patch changes, as well -as why the patch might be necessary. It is challenging to be both -succinct and descriptive, but that is what a well-written summary -should do. - -The ``summary phrase`` may be prefixed by tags enclosed in square -brackets: "Subject: [PATCH ...] ". The tags are -not considered part of the summary phrase, but describe how the patch -should be treated. Common tags might include a version descriptor if -the multiple versions of the patch have been sent out in response to -comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for -comments. If there are four patches in a patch series the individual -patches may be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures -that developers understand the order in which the patches should be -applied and that they have reviewed or applied all of the patches in -the patch series. - -A couple of example Subjects:: - - Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching - Subject: [PATCH v2 01/27] x86: fix eflags tracking - -The ``from`` line must be the very first line in the message body, -and has the form: - - From: Original Author - -The ``from`` line specifies who will be credited as the author of the -patch in the permanent changelog. If the ``from`` line is missing, -then the ``From:`` line from the email header will be used to determine -the patch author in the changelog. - -The explanation body will be committed to the permanent source -changelog, so should make sense to a competent reader who has long -since forgotten the immediate details of the discussion that might -have led to this patch. Including symptoms of the failure which the -patch addresses (kernel log messages, oops messages, etc.) is -especially useful for people who might be searching the commit logs -looking for the applicable patch. If a patch fixes a compile failure, -it may not be necessary to include _all_ of the compile failures; just -enough that it is likely that someone searching for the patch can find -it. As in the ``summary phrase``, it is important to be both succinct as -well as descriptive. - -The ``---`` marker line serves the essential purpose of marking for patch -handling tools where the changelog message ends. - -One good use for the additional comments after the ``---`` marker is for -a ``diffstat``, to show what files have changed, and the number of -inserted and deleted lines per file. A ``diffstat`` is especially useful -on bigger patches. Other comments relevant only to the moment or the -maintainer, not suitable for the permanent changelog, should also go -here. A good example of such comments might be ``patch changelogs`` -which describe what has changed between the v1 and v2 version of the -patch. - -If you are going to include a ``diffstat`` after the ``---`` marker, please -use ``diffstat`` options ``-p 1 -w 70`` so that filenames are listed from -the top of the kernel source tree and don't use too much horizontal -space (easily fit in 80 columns, maybe with some indentation). (``git`` -generates appropriate diffstats by default.) - -See more details on the proper patch format in the following -references. - -.. _explicit_in_reply_to: - -15) Explicit In-Reply-To headers --------------------------------- - -It can be helpful to manually add In-Reply-To: headers to a patch -(e.g., when using ``git send-email``) to associate the patch with -previous relevant discussion, e.g. to link a bug fix to the email with -the bug report. However, for a multi-patch series, it is generally -best to avoid using In-Reply-To: to link to older versions of the -series. This way multiple versions of the patch don't become an -unmanageable forest of references in email clients. If a link is -helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in -the cover email text) to link to an earlier version of the patch series. - - -16) Sending ``git pull`` requests ---------------------------------- - -If you have a series of patches, it may be most convenient to have the -maintainer pull them directly into the subsystem repository with a -``git pull`` operation. Note, however, that pulling patches from a developer -requires a higher degree of trust than taking patches from a mailing list. -As a result, many subsystem maintainers are reluctant to take pull -requests, especially from new, unknown developers. If in doubt you can use -the pull request as the cover letter for a normal posting of the patch -series, giving the maintainer the option of using either. - -A pull request should have [GIT] or [PULL] in the subject line. The -request itself should include the repository name and the branch of -interest on a single line; it should look something like:: - - Please pull from - - git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus - - to get these changes: - -A pull request should also include an overall message saying what will be -included in the request, a ``git shortlog`` listing of the patches -themselves, and a ``diffstat`` showing the overall effect of the patch series. -The easiest way to get all this information together is, of course, to let -``git`` do it for you with the ``git request-pull`` command. - -Some maintainers (including Linus) want to see pull requests from signed -commits; that increases their confidence that the request actually came -from you. Linus, in particular, will not pull from public hosting sites -like GitHub in the absence of a signed tag. - -The first step toward creating such tags is to make a GNUPG key and get it -signed by one or more core kernel developers. This step can be hard for -new developers, but there is no way around it. Attending conferences can -be a good way to find developers who can sign your key. - -Once you have prepared a patch series in ``git`` that you wish to have somebody -pull, create a signed tag with ``git tag -s``. This will create a new tag -identifying the last commit in the series and containing a signature -created with your private key. You will also have the opportunity to add a -changelog-style message to the tag; this is an ideal place to describe the -effects of the pull request as a whole. - -If the tree the maintainer will be pulling from is not the repository you -are working from, don't forget to push the signed tag explicitly to the -public tree. - -When generating your pull request, use the signed tag as the target. A -command like this will do the trick:: - - git request-pull master git://my.public.tree/linux.git my-signed-tag - - -REFERENCES -********** - -Andrew Morton, "The perfect patch" (tpp). - - -Jeff Garzik, "Linux kernel patch submission format". - - -Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". - - - - - - - - - - - - -NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! - - -Kernel Documentation/CodingStyle: - :ref:`Documentation/CodingStyle ` - -Linus Torvalds's mail on the canonical patch format: - - -Andi Kleen, "On submitting kernel patches" - Some strategies to get difficult or controversial changes in. - - http://halobates.de/on-submitting-patches.pdf - diff --git a/Documentation/adding-syscals.txt b/Documentation/adding-syscals.txt deleted file mode 100644 index f5b5b1aa51b3..000000000000 --- a/Documentation/adding-syscals.txt +++ /dev/null @@ -1,542 +0,0 @@ -Adding a New System Call -======================== - -This document describes what's involved in adding a new system call to the -Linux kernel, over and above the normal submission advice in -:ref:`Documentation/SubmittingPatches `. - - -System Call Alternatives ------------------------- - -The first thing to consider when adding a new system call is whether one of -the alternatives might be suitable instead. Although system calls are the -most traditional and most obvious interaction points between userspace and the -kernel, there are other possibilities -- choose what fits best for your -interface. - - - If the operations involved can be made to look like a filesystem-like - object, it may make more sense to create a new filesystem or device. This - also makes it easier to encapsulate the new functionality in a kernel module - rather than requiring it to be built into the main kernel. - - - If the new functionality involves operations where the kernel notifies - userspace that something has happened, then returning a new file - descriptor for the relevant object allows userspace to use - ``poll``/``select``/``epoll`` to receive that notification. - - However, operations that don't map to - :manpage:`read(2)`/:manpage:`write(2)`-like operations - have to be implemented as :manpage:`ioctl(2)` requests, which can lead - to a somewhat opaque API. - - - If you're just exposing runtime system information, a new node in sysfs - (see ``Documentation/filesystems/sysfs.txt``) or the ``/proc`` filesystem may - be more appropriate. However, access to these mechanisms requires that the - relevant filesystem is mounted, which might not always be the case (e.g. - in a namespaced/sandboxed/chrooted environment). Avoid adding any API to - debugfs, as this is not considered a 'production' interface to userspace. - - If the operation is specific to a particular file or file descriptor, then - an additional :manpage:`fcntl(2)` command option may be more appropriate. However, - :manpage:`fcntl(2)` is a multiplexing system call that hides a lot of complexity, so - this option is best for when the new function is closely analogous to - existing :manpage:`fcntl(2)` functionality, or the new functionality is very simple - (for example, getting/setting a simple flag related to a file descriptor). - - If the operation is specific to a particular task or process, then an - additional :manpage:`prctl(2)` command option may be more appropriate. As - with :manpage:`fcntl(2)`, this system call is a complicated multiplexor so - is best reserved for near-analogs of existing ``prctl()`` commands or - getting/setting a simple flag related to a process. - - -Designing the API: Planning for Extension ------------------------------------------ - -A new system call forms part of the API of the kernel, and has to be supported -indefinitely. As such, it's a very good idea to explicitly discuss the -interface on the kernel mailing list, and it's important to plan for future -extensions of the interface. - -(The syscall table is littered with historical examples where this wasn't done, -together with the corresponding follow-up system calls -- -``eventfd``/``eventfd2``, ``dup2``/``dup3``, ``inotify_init``/``inotify_init1``, -``pipe``/``pipe2``, ``renameat``/``renameat2`` -- so -learn from the history of the kernel and plan for extensions from the start.) - -For simpler system calls that only take a couple of arguments, the preferred -way to allow for future extensibility is to include a flags argument to the -system call. To make sure that userspace programs can safely use flags -between kernel versions, check whether the flags value holds any unknown -flags, and reject the system call (with ``EINVAL``) if it does:: - - if (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3)) - return -EINVAL; - -(If no flags values are used yet, check that the flags argument is zero.) - -For more sophisticated system calls that involve a larger number of arguments, -it's preferred to encapsulate the majority of the arguments into a structure -that is passed in by pointer. Such a structure can cope with future extension -by including a size argument in the structure:: - - struct xyzzy_params { - u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */ - u32 param_1; - u64 param_2; - u64 param_3; - }; - -As long as any subsequently added field, say ``param_4``, is designed so that a -zero value gives the previous behaviour, then this allows both directions of -version mismatch: - - - To cope with a later userspace program calling an older kernel, the kernel - code should check that any memory beyond the size of the structure that it - expects is zero (effectively checking that ``param_4 == 0``). - - To cope with an older userspace program calling a newer kernel, the kernel - code can zero-extend a smaller instance of the structure (effectively - setting ``param_4 = 0``). - -See :manpage:`perf_event_open(2)` and the ``perf_copy_attr()`` function (in -``kernel/events/core.c``) for an example of this approach. - - -Designing the API: Other Considerations ---------------------------------------- - -If your new system call allows userspace to refer to a kernel object, it -should use a file descriptor as the handle for that object -- don't invent a -new type of userspace object handle when the kernel already has mechanisms and -well-defined semantics for using file descriptors. - -If your new :manpage:`xyzzy(2)` system call does return a new file descriptor, -then the flags argument should include a value that is equivalent to setting -``O_CLOEXEC`` on the new FD. This makes it possible for userspace to close -the timing window between ``xyzzy()`` and calling -``fcntl(fd, F_SETFD, FD_CLOEXEC)``, where an unexpected ``fork()`` and -``execve()`` in another thread could leak a descriptor to -the exec'ed program. (However, resist the temptation to re-use the actual value -of the ``O_CLOEXEC`` constant, as it is architecture-specific and is part of a -numbering space of ``O_*`` flags that is fairly full.) - -If your system call returns a new file descriptor, you should also consider -what it means to use the :manpage:`poll(2)` family of system calls on that file -descriptor. Making a file descriptor ready for reading or writing is the -normal way for the kernel to indicate to userspace that an event has -occurred on the corresponding kernel object. - -If your new :manpage:`xyzzy(2)` system call involves a filename argument:: - - int sys_xyzzy(const char __user *path, ..., unsigned int flags); - -you should also consider whether an :manpage:`xyzzyat(2)` version is more appropriate:: - - int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags); - -This allows more flexibility for how userspace specifies the file in question; -in particular it allows userspace to request the functionality for an -already-opened file descriptor using the ``AT_EMPTY_PATH`` flag, effectively -giving an :manpage:`fxyzzy(3)` operation for free:: - - - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...) - - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...) - -(For more details on the rationale of the \*at() calls, see the -:manpage:`openat(2)` man page; for an example of AT_EMPTY_PATH, see the -:manpage:`fstatat(2)` man page.) - -If your new :manpage:`xyzzy(2)` system call involves a parameter describing an -offset within a file, make its type ``loff_t`` so that 64-bit offsets can be -supported even on 32-bit architectures. - -If your new :manpage:`xyzzy(2)` system call involves privileged functionality, -it needs to be governed by the appropriate Linux capability bit (checked with -a call to ``capable()``), as described in the :manpage:`capabilities(7)` man -page. Choose an existing capability bit that governs related functionality, -but try to avoid combining lots of only vaguely related functions together -under the same bit, as this goes against capabilities' purpose of splitting -the power of root. In particular, avoid adding new uses of the already -overly-general ``CAP_SYS_ADMIN`` capability. - -If your new :manpage:`xyzzy(2)` system call manipulates a process other than -the calling process, it should be restricted (using a call to -``ptrace_may_access()``) so that only a calling process with the same -permissions as the target process, or with the necessary capabilities, can -manipulate the target process. - -Finally, be aware that some non-x86 architectures have an easier time if -system call parameters that are explicitly 64-bit fall on odd-numbered -arguments (i.e. parameter 1, 3, 5), to allow use of contiguous pairs of 32-bit -registers. (This concern does not apply if the arguments are part of a -structure that's passed in by pointer.) - - -Proposing the API ------------------ - -To make new system calls easy to review, it's best to divide up the patchset -into separate chunks. These should include at least the following items as -distinct commits (each of which is described further below): - - - The core implementation of the system call, together with prototypes, - generic numbering, Kconfig changes and fallback stub implementation. - - Wiring up of the new system call for one particular architecture, usually - x86 (including all of x86_64, x86_32 and x32). - - A demonstration of the use of the new system call in userspace via a - selftest in ``tools/testing/selftests/``. - - A draft man-page for the new system call, either as plain text in the - cover letter, or as a patch to the (separate) man-pages repository. - -New system call proposals, like any change to the kernel's API, should always -be cc'ed to linux-api@vger.kernel.org. - - -Generic System Call Implementation ----------------------------------- - -The main entry point for your new :manpage:`xyzzy(2)` system call will be called -``sys_xyzzy()``, but you add this entry point with the appropriate -``SYSCALL_DEFINEn()`` macro rather than explicitly. The 'n' indicates the -number of arguments to the system call, and the macro takes the system call name -followed by the (type, name) pairs for the parameters as arguments. Using -this macro allows metadata about the new system call to be made available for -other tools. - -The new entry point also needs a corresponding function prototype, in -``include/linux/syscalls.h``, marked as asmlinkage to match the way that system -calls are invoked:: - - asmlinkage long sys_xyzzy(...); - -Some architectures (e.g. x86) have their own architecture-specific syscall -tables, but several other architectures share a generic syscall table. Add your -new system call to the generic list by adding an entry to the list in -``include/uapi/asm-generic/unistd.h``:: - - #define __NR_xyzzy 292 - __SYSCALL(__NR_xyzzy, sys_xyzzy) - -Also update the __NR_syscalls count to reflect the additional system call, and -note that if multiple new system calls are added in the same merge window, -your new syscall number may get adjusted to resolve conflicts. - -The file ``kernel/sys_ni.c`` provides a fallback stub implementation of each -system call, returning ``-ENOSYS``. Add your new system call here too:: - - cond_syscall(sys_xyzzy); - -Your new kernel functionality, and the system call that controls it, should -normally be optional, so add a ``CONFIG`` option (typically to -``init/Kconfig``) for it. As usual for new ``CONFIG`` options: - - - Include a description of the new functionality and system call controlled - by the option. - - Make the option depend on EXPERT if it should be hidden from normal users. - - Make any new source files implementing the function dependent on the CONFIG - option in the Makefile (e.g. ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.c``). - - Double check that the kernel still builds with the new CONFIG option turned - off. - -To summarize, you need a commit that includes: - - - ``CONFIG`` option for the new function, normally in ``init/Kconfig`` - - ``SYSCALL_DEFINEn(xyzzy, ...)`` for the entry point - - corresponding prototype in ``include/linux/syscalls.h`` - - generic table entry in ``include/uapi/asm-generic/unistd.h`` - - fallback stub in ``kernel/sys_ni.c`` - - -x86 System Call Implementation ------------------------------- - -To wire up your new system call for x86 platforms, you need to update the -master syscall tables. Assuming your new system call isn't special in some -way (see below), this involves a "common" entry (for x86_64 and x32) in -arch/x86/entry/syscalls/syscall_64.tbl:: - - 333 common xyzzy sys_xyzzy - -and an "i386" entry in ``arch/x86/entry/syscalls/syscall_32.tbl``:: - - 380 i386 xyzzy sys_xyzzy - -Again, these numbers are liable to be changed if there are conflicts in the -relevant merge window. - - -Compatibility System Calls (Generic) ------------------------------------- - -For most system calls the same 64-bit implementation can be invoked even when -the userspace program is itself 32-bit; even if the system call's parameters -include an explicit pointer, this is handled transparently. - -However, there are a couple of situations where a compatibility layer is -needed to cope with size differences between 32-bit and 64-bit. - -The first is if the 64-bit kernel also supports 32-bit userspace programs, and -so needs to parse areas of (``__user``) memory that could hold either 32-bit or -64-bit values. In particular, this is needed whenever a system call argument -is: - - - a pointer to a pointer - - a pointer to a struct containing a pointer (e.g. ``struct iovec __user *``) - - a pointer to a varying sized integral type (``time_t``, ``off_t``, - ``long``, ...) - - a pointer to a struct containing a varying sized integral type. - -The second situation that requires a compatibility layer is if one of the -system call's arguments has a type that is explicitly 64-bit even on a 32-bit -architecture, for example ``loff_t`` or ``__u64``. In this case, a value that -arrives at a 64-bit kernel from a 32-bit application will be split into two -32-bit values, which then need to be re-assembled in the compatibility layer. - -(Note that a system call argument that's a pointer to an explicit 64-bit type -does **not** need a compatibility layer; for example, :manpage:`splice(2)`'s arguments of -type ``loff_t __user *`` do not trigger the need for a ``compat_`` system call.) - -The compatibility version of the system call is called ``compat_sys_xyzzy()``, -and is added with the ``COMPAT_SYSCALL_DEFINEn()`` macro, analogously to -SYSCALL_DEFINEn. This version of the implementation runs as part of a 64-bit -kernel, but expects to receive 32-bit parameter values and does whatever is -needed to deal with them. (Typically, the ``compat_sys_`` version converts the -values to 64-bit versions and either calls on to the ``sys_`` version, or both of -them call a common inner implementation function.) - -The compat entry point also needs a corresponding function prototype, in -``include/linux/compat.h``, marked as asmlinkage to match the way that system -calls are invoked:: - - asmlinkage long compat_sys_xyzzy(...); - -If the system call involves a structure that is laid out differently on 32-bit -and 64-bit systems, say ``struct xyzzy_args``, then the include/linux/compat.h -header file should also include a compat version of the structure (``struct -compat_xyzzy_args``) where each variable-size field has the appropriate -``compat_`` type that corresponds to the type in ``struct xyzzy_args``. The -``compat_sys_xyzzy()`` routine can then use this ``compat_`` structure to -parse the arguments from a 32-bit invocation. - -For example, if there are fields:: - - struct xyzzy_args { - const char __user *ptr; - __kernel_long_t varying_val; - u64 fixed_val; - /* ... */ - }; - -in struct xyzzy_args, then struct compat_xyzzy_args would have:: - - struct compat_xyzzy_args { - compat_uptr_t ptr; - compat_long_t varying_val; - u64 fixed_val; - /* ... */ - }; - -The generic system call list also needs adjusting to allow for the compat -version; the entry in ``include/uapi/asm-generic/unistd.h`` should use -``__SC_COMP`` rather than ``__SYSCALL``:: - - #define __NR_xyzzy 292 - __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy) - -To summarize, you need: - - - a ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` for the compat entry point - - corresponding prototype in ``include/linux/compat.h`` - - (if needed) 32-bit mapping struct in ``include/linux/compat.h`` - - instance of ``__SC_COMP`` not ``__SYSCALL`` in - ``include/uapi/asm-generic/unistd.h`` - - -Compatibility System Calls (x86) --------------------------------- - -To wire up the x86 architecture of a system call with a compatibility version, -the entries in the syscall tables need to be adjusted. - -First, the entry in ``arch/x86/entry/syscalls/syscall_32.tbl`` gets an extra -column to indicate that a 32-bit userspace program running on a 64-bit kernel -should hit the compat entry point:: - - 380 i386 xyzzy sys_xyzzy compat_sys_xyzzy - -Second, you need to figure out what should happen for the x32 ABI version of -the new system call. There's a choice here: the layout of the arguments -should either match the 64-bit version or the 32-bit version. - -If there's a pointer-to-a-pointer involved, the decision is easy: x32 is -ILP32, so the layout should match the 32-bit version, and the entry in -``arch/x86/entry/syscalls/syscall_64.tbl`` is split so that x32 programs hit -the compatibility wrapper:: - - 333 64 xyzzy sys_xyzzy - ... - 555 x32 xyzzy compat_sys_xyzzy - -If no pointers are involved, then it is preferable to re-use the 64-bit system -call for the x32 ABI (and consequently the entry in -arch/x86/entry/syscalls/syscall_64.tbl is unchanged). - -In either case, you should check that the types involved in your argument -layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or -64-bit (-m64) equivalents. - - -System Calls Returning Elsewhere --------------------------------- - -For most system calls, once the system call is complete the user program -continues exactly where it left off -- at the next instruction, with the -stack the same and most of the registers the same as before the system call, -and with the same virtual memory space. - -However, a few system calls do things differently. They might return to a -different location (``rt_sigreturn``) or change the memory space -(``fork``/``vfork``/``clone``) or even architecture (``execve``/``execveat``) -of the program. - -To allow for this, the kernel implementation of the system call may need to -save and restore additional registers to the kernel stack, allowing complete -control of where and how execution continues after the system call. - -This is arch-specific, but typically involves defining assembly entry points -that save/restore additional registers and invoke the real system call entry -point. - -For x86_64, this is implemented as a ``stub_xyzzy`` entry point in -``arch/x86/entry/entry_64.S``, and the entry in the syscall table -(``arch/x86/entry/syscalls/syscall_64.tbl``) is adjusted to match:: - - 333 common xyzzy stub_xyzzy - -The equivalent for 32-bit programs running on a 64-bit kernel is normally -called ``stub32_xyzzy`` and implemented in ``arch/x86/entry/entry_64_compat.S``, -with the corresponding syscall table adjustment in -``arch/x86/entry/syscalls/syscall_32.tbl``:: - - 380 i386 xyzzy sys_xyzzy stub32_xyzzy - -If the system call needs a compatibility layer (as in the previous section) -then the ``stub32_`` version needs to call on to the ``compat_sys_`` version -of the system call rather than the native 64-bit version. Also, if the x32 ABI -implementation is not common with the x86_64 version, then its syscall -table will also need to invoke a stub that calls on to the ``compat_sys_`` -version. - -For completeness, it's also nice to set up a mapping so that user-mode Linux -still works -- its syscall table will reference stub_xyzzy, but the UML build -doesn't include ``arch/x86/entry/entry_64.S`` implementation (because UML -simulates registers etc). Fixing this is as simple as adding a #define to -``arch/x86/um/sys_call_table_64.c``:: - - #define stub_xyzzy sys_xyzzy - - -Other Details -------------- - -Most of the kernel treats system calls in a generic way, but there is the -occasional exception that may need updating for your particular system call. - -The audit subsystem is one such special case; it includes (arch-specific) -functions that classify some special types of system call -- specifically -file open (``open``/``openat``), program execution (``execve``/``exeveat``) or -socket multiplexor (``socketcall``) operations. If your new system call is -analogous to one of these, then the audit system should be updated. - -More generally, if there is an existing system call that is analogous to your -new system call, it's worth doing a kernel-wide grep for the existing system -call to check there are no other special cases. - - -Testing -------- - -A new system call should obviously be tested; it is also useful to provide -reviewers with a demonstration of how user space programs will use the system -call. A good way to combine these aims is to include a simple self-test -program in a new directory under ``tools/testing/selftests/``. - -For a new system call, there will obviously be no libc wrapper function and so -the test will need to invoke it using ``syscall()``; also, if the system call -involves a new userspace-visible structure, the corresponding header will need -to be installed to compile the test. - -Make sure the selftest runs successfully on all supported architectures. For -example, check that it works when compiled as an x86_64 (-m64), x86_32 (-m32) -and x32 (-mx32) ABI program. - -For more extensive and thorough testing of new functionality, you should also -consider adding tests to the Linux Test Project, or to the xfstests project -for filesystem-related changes. - - - https://linux-test-project.github.io/ - - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git - - -Man Page --------- - -All new system calls should come with a complete man page, ideally using groff -markup, but plain text will do. If groff is used, it's helpful to include a -pre-rendered ASCII version of the man page in the cover email for the -patchset, for the convenience of reviewers. - -The man page should be cc'ed to linux-man@vger.kernel.org -For more details, see https://www.kernel.org/doc/man-pages/patches.html - -References and Sources ----------------------- - - - LWN article from Michael Kerrisk on use of flags argument in system calls: - https://lwn.net/Articles/585415/ - - LWN article from Michael Kerrisk on how to handle unknown flags in a system - call: https://lwn.net/Articles/588444/ - - LWN article from Jake Edge describing constraints on 64-bit system call - arguments: https://lwn.net/Articles/311630/ - - Pair of LWN articles from David Drysdale that describe the system call - implementation paths in detail for v3.14: - - - https://lwn.net/Articles/604287/ - - https://lwn.net/Articles/604515/ - - - Architecture-specific requirements for system calls are discussed in the - :manpage:`syscall(2)` man-page: - http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES - - Collated emails from Linus Torvalds discussing the problems with ``ioctl()``: - http://yarchive.net/comp/linux/ioctl.html - - "How to not invent kernel interfaces", Arnd Bergmann, - http://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf - - LWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN: - https://lwn.net/Articles/486306/ - - Recommendation from Andrew Morton that all related information for a new - system call should come in the same email thread: - https://lkml.org/lkml/2014/7/24/641 - - Recommendation from Michael Kerrisk that a new system call should come with - a man page: https://lkml.org/lkml/2014/6/13/309 - - Suggestion from Thomas Gleixner that x86 wire-up should be in a separate - commit: https://lkml.org/lkml/2014/11/19/254 - - Suggestion from Greg Kroah-Hartman that it's good for new system calls to - come with a man-page & selftest: https://lkml.org/lkml/2014/3/19/710 - - Discussion from Michael Kerrisk of new system call vs. :manpage:`prctl(2)` extension: - https://lkml.org/lkml/2014/6/3/411 - - Suggestion from Ingo Molnar that system calls that involve multiple - arguments should encapsulate those arguments in a struct, which includes a - size field for future extensibility: https://lkml.org/lkml/2015/7/30/117 - - Numbering oddities arising from (re-)use of O_* numbering space flags: - - - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness - check") - - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc - conflict") - - commit bb458c644a59 ("Safer ABI for O_TMPFILE") - - - Discussion from Matthew Wilcox about restrictions on 64-bit arguments: - https://lkml.org/lkml/2008/12/12/187 - - Recommendation from Greg Kroah-Hartman that unknown flags should be - policed: https://lkml.org/lkml/2014/7/17/577 - - Recommendation from Linus Torvalds that x32 system calls should prefer - compatibility with 64-bit versions rather than 32-bit versions: - https://lkml.org/lkml/2011/8/31/244 diff --git a/Documentation/applying-patches.txt b/Documentation/applying-patches.txt deleted file mode 100644 index 3395da13d415..000000000000 --- a/Documentation/applying-patches.txt +++ /dev/null @@ -1,465 +0,0 @@ -.. _applying_patches: - -Applying Patches To The Linux Kernel -++++++++++++++++++++++++++++++++++++ - -Original by: - Jesper Juhl, August 2005 - -Last update: - 2016-09-14 - - -A frequently asked question on the Linux Kernel Mailing List is how to apply -a patch to the kernel or, more specifically, what base kernel a patch for -one of the many trees/branches should be applied to. Hopefully this document -will explain this to you. - -In addition to explaining how to apply and revert patches, a brief -description of the different kernel trees (and examples of how to apply -their specific patches) is also provided. - - -What is a patch? -================ - -A patch is a small text document containing a delta of changes between two -different versions of a source tree. Patches are created with the ``diff`` -program. - -To correctly apply a patch you need to know what base it was generated from -and what new version the patch will change the source tree into. These -should both be present in the patch file metadata or be possible to deduce -from the filename. - - -How do I apply or revert a patch? -================================= - -You apply a patch with the ``patch`` program. The patch program reads a diff -(or patch) file and makes the changes to the source tree described in it. - -Patches for the Linux kernel are generated relative to the parent directory -holding the kernel source dir. - -This means that paths to files inside the patch file contain the name of the -kernel source directories it was generated against (or some other directory -names like "a/" and "b/"). - -Since this is unlikely to match the name of the kernel source dir on your -local machine (but is often useful info to see what version an otherwise -unlabeled patch was generated against) you should change into your kernel -source directory and then strip the first element of the path from filenames -in the patch file when applying it (the ``-p1`` argument to ``patch`` does -this). - -To revert a previously applied patch, use the -R argument to patch. -So, if you applied a patch like this:: - - patch -p1 < ../patch-x.y.z - -You can revert (undo) it like this:: - - patch -R -p1 < ../patch-x.y.z - - -How do I feed a patch/diff file to ``patch``? -============================================= - -This (as usual with Linux and other UNIX like operating systems) can be -done in several different ways. - -In all the examples below I feed the file (in uncompressed form) to patch -via stdin using the following syntax:: - - patch -p1 < path/to/patch-x.y.z - -If you just want to be able to follow the examples below and don't want to -know of more than one way to use patch, then you can stop reading this -section here. - -Patch can also get the name of the file to use via the -i argument, like -this:: - - patch -p1 -i path/to/patch-x.y.z - -If your patch file is compressed with gzip or xz and you don't want to -uncompress it before applying it, then you can feed it to patch like this -instead:: - - xzcat path/to/patch-x.y.z.xz | patch -p1 - bzcat path/to/patch-x.y.z.gz | patch -p1 - -If you wish to uncompress the patch file by hand first before applying it -(what I assume you've done in the examples below), then you simply run -gunzip or xz on the file -- like this:: - - gunzip patch-x.y.z.gz - xz -d patch-x.y.z.xz - -Which will leave you with a plain text patch-x.y.z file that you can feed to -patch via stdin or the ``-i`` argument, as you prefer. - -A few other nice arguments for patch are ``-s`` which causes patch to be silent -except for errors which is nice to prevent errors from scrolling out of the -screen too fast, and ``--dry-run`` which causes patch to just print a listing of -what would happen, but doesn't actually make any changes. Finally ``--verbose`` -tells patch to print more information about the work being done. - - -Common errors when patching -=========================== - -When patch applies a patch file it attempts to verify the sanity of the -file in different ways. - -Checking that the file looks like a valid patch file and checking the code -around the bits being modified matches the context provided in the patch are -just two of the basic sanity checks patch does. - -If patch encounters something that doesn't look quite right it has two -options. It can either refuse to apply the changes and abort or it can try -to find a way to make the patch apply with a few minor changes. - -One example of something that's not 'quite right' that patch will attempt to -fix up is if all the context matches, the lines being changed match, but the -line numbers are different. This can happen, for example, if the patch makes -a change in the middle of the file but for some reasons a few lines have -been added or removed near the beginning of the file. In that case -everything looks good it has just moved up or down a bit, and patch will -usually adjust the line numbers and apply the patch. - -Whenever patch applies a patch that it had to modify a bit to make it fit -it'll tell you about it by saying the patch applied with **fuzz**. -You should be wary of such changes since even though patch probably got it -right it doesn't /always/ get it right, and the result will sometimes be -wrong. - -When patch encounters a change that it can't fix up with fuzz it rejects it -outright and leaves a file with a ``.rej`` extension (a reject file). You can -read this file to see exactly what change couldn't be applied, so you can -go fix it up by hand if you wish. - -If you don't have any third-party patches applied to your kernel source, but -only patches from kernel.org and you apply the patches in the correct order, -and have made no modifications yourself to the source files, then you should -never see a fuzz or reject message from patch. If you do see such messages -anyway, then there's a high risk that either your local source tree or the -patch file is corrupted in some way. In that case you should probably try -re-downloading the patch and if things are still not OK then you'd be advised -to start with a fresh tree downloaded in full from kernel.org. - -Let's look a bit more at some of the messages patch can produce. - -If patch stops and presents a ``File to patch:`` prompt, then patch could not -find a file to be patched. Most likely you forgot to specify -p1 or you are -in the wrong directory. Less often, you'll find patches that need to be -applied with ``-p0`` instead of ``-p1`` (reading the patch file should reveal if -this is the case -- if so, then this is an error by the person who created -the patch but is not fatal). - -If you get ``Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines).`` or a -message similar to that, then it means that patch had to adjust the location -of the change (in this example it needed to move 7 lines from where it -expected to make the change to make it fit). - -The resulting file may or may not be OK, depending on the reason the file -was different than expected. - -This often happens if you try to apply a patch that was generated against a -different kernel version than the one you are trying to patch. - -If you get a message like ``Hunk #3 FAILED at 2387.``, then it means that the -patch could not be applied correctly and the patch program was unable to -fuzz its way through. This will generate a ``.rej`` file with the change that -caused the patch to fail and also a ``.orig`` file showing you the original -content that couldn't be changed. - -If you get ``Reversed (or previously applied) patch detected! Assume -R? [n]`` -then patch detected that the change contained in the patch seems to have -already been made. - -If you actually did apply this patch previously and you just re-applied it -in error, then just say [n]o and abort this patch. If you applied this patch -previously and actually intended to revert it, but forgot to specify -R, -then you can say [**y**]es here to make patch revert it for you. - -This can also happen if the creator of the patch reversed the source and -destination directories when creating the patch, and in that case reverting -the patch will in fact apply it. - -A message similar to ``patch: **** unexpected end of file in patch`` or -``patch unexpectedly ends in middle of line`` means that patch could make no -sense of the file you fed to it. Either your download is broken, you tried to -feed patch a compressed patch file without uncompressing it first, or the patch -file that you are using has been mangled by a mail client or mail transfer -agent along the way somewhere, e.g., by splitting a long line into two lines. -Often these warnings can easily be fixed by joining (concatenating) the -two lines that had been split. - -As I already mentioned above, these errors should never happen if you apply -a patch from kernel.org to the correct version of an unmodified source tree. -So if you get these errors with kernel.org patches then you should probably -assume that either your patch file or your tree is broken and I'd advise you -to start over with a fresh download of a full kernel tree and the patch you -wish to apply. - - -Are there any alternatives to ``patch``? -======================================== - - -Yes there are alternatives. - -You can use the ``interdiff`` program (http://cyberelk.net/tim/patchutils/) to -generate a patch representing the differences between two patches and then -apply the result. - -This will let you move from something like 4.7.2 to 4.7.3 in a single -step. The -z flag to interdiff will even let you feed it patches in gzip or -bzip2 compressed form directly without the use of zcat or bzcat or manual -decompression. - -Here's how you'd go from 4.7.2 to 4.7.3 in a single step:: - - interdiff -z ../patch-4.7.2.gz ../patch-4.7.3.gz | patch -p1 - -Although interdiff may save you a step or two you are generally advised to -do the additional steps since interdiff can get things wrong in some cases. - -Another alternative is ``ketchup``, which is a python script for automatic -downloading and applying of patches (http://www.selenic.com/ketchup/). - -Other nice tools are diffstat, which shows a summary of changes made by a -patch; lsdiff, which displays a short listing of affected files in a patch -file, along with (optionally) the line numbers of the start of each patch; -and grepdiff, which displays a list of the files modified by a patch where -the patch contains a given regular expression. - - -Where can I download the patches? -================================= - -The patches are available at http://kernel.org/ -Most recent patches are linked from the front page, but they also have -specific homes. - -The 4.x.y (-stable) and 4.x patches live at - - ftp://ftp.kernel.org/pub/linux/kernel/v4.x/ - -The -rc patches live at - - ftp://ftp.kernel.org/pub/linux/kernel/v4.x/testing/ - -In place of ``ftp.kernel.org`` you can use ``ftp.cc.kernel.org``, where cc is a -country code. This way you'll be downloading from a mirror site that's most -likely geographically closer to you, resulting in faster downloads for you, -less bandwidth used globally and less load on the main kernel.org servers -- -these are good things, so do use mirrors when possible. - - -The 4.x kernels -=============== - -These are the base stable releases released by Linus. The highest numbered -release is the most recent. - -If regressions or other serious flaws are found, then a -stable fix patch -will be released (see below) on top of this base. Once a new 4.x base -kernel is released, a patch is made available that is a delta between the -previous 4.x kernel and the new one. - -To apply a patch moving from 4.6 to 4.7, you'd do the following (note -that such patches do **NOT** apply on top of 4.x.y kernels but on top of the -base 4.x kernel -- if you need to move from 4.x.y to 4.x+1 you need to -first revert the 4.x.y patch). - -Here are some examples:: - - # moving from 4.6 to 4.7 - - $ cd ~/linux-4.6 # change to kernel source dir - $ patch -p1 < ../patch-4.7 # apply the 4.7 patch - $ cd .. - $ mv linux-4.6 linux-4.7 # rename source dir - - # moving from 4.6.1 to 4.7 - - $ cd ~/linux-4.6.1 # change to kernel source dir - $ patch -p1 -R < ../patch-4.6.1 # revert the 4.6.1 patch - # source dir is now 4.6 - $ patch -p1 < ../patch-4.7 # apply new 4.7 patch - $ cd .. - $ mv linux-4.6.1 linux-4.7 # rename source dir - - -The 4.x.y kernels -================= - -Kernels with 3-digit versions are -stable kernels. They contain small(ish) -critical fixes for security problems or significant regressions discovered -in a given 4.x kernel. - -This is the recommended branch for users who want the most recent stable -kernel and are not interested in helping test development/experimental -versions. - -If no 4.x.y kernel is available, then the highest numbered 4.x kernel is -the current stable kernel. - -.. note:: - - The -stable team usually do make incremental patches available as well - as patches against the latest mainline release, but I only cover the - non-incremental ones below. The incremental ones can be found at - ftp://ftp.kernel.org/pub/linux/kernel/v4.x/incr/ - -These patches are not incremental, meaning that for example the 4.7.3 -patch does not apply on top of the 4.7.2 kernel source, but rather on top -of the base 4.7 kernel source. - -So, in order to apply the 4.7.3 patch to your existing 4.7.2 kernel -source you have to first back out the 4.7.2 patch (so you are left with a -base 4.7 kernel source) and then apply the new 4.7.3 patch. - -Here's a small example:: - - $ cd ~/linux-4.7.2 # change to the kernel source dir - $ patch -p1 -R < ../patch-4.7.2 # revert the 4.7.2 patch - $ patch -p1 < ../patch-4.7.3 # apply the new 4.7.3 patch - $ cd .. - $ mv linux-4.7.2 linux-4.7.3 # rename the kernel source dir - -The -rc kernels -=============== - -These are release-candidate kernels. These are development kernels released -by Linus whenever he deems the current git (the kernel's source management -tool) tree to be in a reasonably sane state adequate for testing. - -These kernels are not stable and you should expect occasional breakage if -you intend to run them. This is however the most stable of the main -development branches and is also what will eventually turn into the next -stable kernel, so it is important that it be tested by as many people as -possible. - -This is a good branch to run for people who want to help out testing -development kernels but do not want to run some of the really experimental -stuff (such people should see the sections about -git and -mm kernels below). - -The -rc patches are not incremental, they apply to a base 4.x kernel, just -like the 4.x.y patches described above. The kernel version before the -rcN -suffix denotes the version of the kernel that this -rc kernel will eventually -turn into. - -So, 4.8-rc5 means that this is the fifth release candidate for the 4.8 -kernel and the patch should be applied on top of the 4.7 kernel source. - -Here are 3 examples of how to apply these patches:: - - # first an example of moving from 4.7 to 4.8-rc3 - - $ cd ~/linux-4.7 # change to the 4.7 source dir - $ patch -p1 < ../patch-4.8-rc3 # apply the 4.8-rc3 patch - $ cd .. - $ mv linux-4.7 linux-4.8-rc3 # rename the source dir - - # now let's move from 4.8-rc3 to 4.8-rc5 - - $ cd ~/linux-4.8-rc3 # change to the 4.8-rc3 dir - $ patch -p1 -R < ../patch-4.8-rc3 # revert the 4.8-rc3 patch - $ patch -p1 < ../patch-4.8-rc5 # apply the new 4.8-rc5 patch - $ cd .. - $ mv linux-4.8-rc3 linux-4.8-rc5 # rename the source dir - - # finally let's try and move from 4.7.3 to 4.8-rc5 - - $ cd ~/linux-4.7.3 # change to the kernel source dir - $ patch -p1 -R < ../patch-4.7.3 # revert the 4.7.3 patch - $ patch -p1 < ../patch-4.8-rc5 # apply new 4.8-rc5 patch - $ cd .. - $ mv linux-4.7.3 linux-4.8-rc5 # rename the kernel source dir - - -The -git kernels -================ - -These are daily snapshots of Linus' kernel tree (managed in a git -repository, hence the name). - -These patches are usually released daily and represent the current state of -Linus's tree. They are more experimental than -rc kernels since they are -generated automatically without even a cursory glance to see if they are -sane. - --git patches are not incremental and apply either to a base 4.x kernel or -a base 4.x-rc kernel -- you can see which from their name. -A patch named 4.7-git1 applies to the 4.7 kernel source and a patch -named 4.8-rc3-git2 applies to the source of the 4.8-rc3 kernel. - -Here are some examples of how to apply these patches:: - - # moving from 4.7 to 4.7-git1 - - $ cd ~/linux-4.7 # change to the kernel source dir - $ patch -p1 < ../patch-4.7-git1 # apply the 4.7-git1 patch - $ cd .. - $ mv linux-4.7 linux-4.7-git1 # rename the kernel source dir - - # moving from 4.7-git1 to 4.8-rc2-git3 - - $ cd ~/linux-4.7-git1 # change to the kernel source dir - $ patch -p1 -R < ../patch-4.7-git1 # revert the 4.7-git1 patch - # we now have a 4.7 kernel - $ patch -p1 < ../patch-4.8-rc2 # apply the 4.8-rc2 patch - # the kernel is now 4.8-rc2 - $ patch -p1 < ../patch-4.8-rc2-git3 # apply the 4.8-rc2-git3 patch - # the kernel is now 4.8-rc2-git3 - $ cd .. - $ mv linux-4.7-git1 linux-4.8-rc2-git3 # rename source dir - - -The -mm patches and the linux-next tree -======================================= - -The -mm patches are experimental patches released by Andrew Morton. - -In the past, -mm tree were used to also test subsystem patches, but this -function is now done via the -`linux-next ` -tree. The Subsystem maintainers push their patches first to linux-next, -and, during the merge window, sends them directly to Linus. - -The -mm patches serve as a sort of proving ground for new features and other -experimental patches that aren't merged via a subsystem tree. -Once such patches has proved its worth in -mm for a while Andrew pushes -it on to Linus for inclusion in mainline. - -The linux-next tree is daily updated, and includes the -mm patches. -Both are in constant flux and contains many experimental features, a -lot of debugging patches not appropriate for mainline etc., and is the most -experimental of the branches described in this document. - -These patches are not appropriate for use on systems that are supposed to be -stable and they are more risky to run than any of the other branches (make -sure you have up-to-date backups -- that goes for any experimental kernel but -even more so for -mm patches or using a Kernel from the linux-next tree). - -Testing of -mm patches and linux-next is greatly appreciated since the whole -point of those are to weed out regressions, crashes, data corruption bugs, -build breakage (and any other bug in general) before changes are merged into -the more stable mainline Linus tree. - -But testers of -mm and linux-next should be aware that breakages are -more common than in any other tree. - - -This concludes this list of explanations of the various kernel trees. -I hope you are now clear on how to apply the various patches and help testing -the kernel. - -Thank you's to Randy Dunlap, Rolf Eike Beer, Linus Torvalds, Bodo Eggert, -Johannes Stezenbach, Grant Coady, Pavel Machek and others that I may have -forgotten for their reviews and contributions to this document. - diff --git a/Documentation/email-clients.txt b/Documentation/email-clients.txt deleted file mode 100644 index ac892b30815e..000000000000 --- a/Documentation/email-clients.txt +++ /dev/null @@ -1,319 +0,0 @@ -.. _email_clients: - -Email clients info for Linux -============================ - -Git ---- - -These days most developers use ``git send-email`` instead of regular -email clients. The man page for this is quite good. On the receiving -end, maintainers use ``git am`` to apply the patches. - -If you are new to ``git`` then send your first patch to yourself. Save it -as raw text including all the headers. Run ``git am raw_email.txt`` and -then review the changelog with ``git log``. When that works then send -the patch to the appropriate mailing list(s). - -General Preferences -------------------- - -Patches for the Linux kernel are submitted via email, preferably as -inline text in the body of the email. Some maintainers accept -attachments, but then the attachments should have content-type -``text/plain``. However, attachments are generally frowned upon because -it makes quoting portions of the patch more difficult in the patch -review process. - -Email clients that are used for Linux kernel patches should send the -patch text untouched. For example, they should not modify or delete tabs -or spaces, even at the beginning or end of lines. - -Don't send patches with ``format=flowed``. This can cause unexpected -and unwanted line breaks. - -Don't let your email client do automatic word wrapping for you. -This can also corrupt your patch. - -Email clients should not modify the character set encoding of the text. -Emailed patches should be in ASCII or UTF-8 encoding only. -If you configure your email client to send emails with UTF-8 encoding, -you avoid some possible charset problems. - -Email clients should generate and maintain References: or In-Reply-To: -headers so that mail threading is not broken. - -Copy-and-paste (or cut-and-paste) usually does not work for patches -because tabs are converted to spaces. Using xclipboard, xclip, and/or -xcutsel may work, but it's best to test this for yourself or just avoid -copy-and-paste. - -Don't use PGP/GPG signatures in mail that contains patches. -This breaks many scripts that read and apply the patches. -(This should be fixable.) - -It's a good idea to send a patch to yourself, save the received message, -and successfully apply it with 'patch' before sending patches to Linux -mailing lists. - - -Some email client (MUA) hints ------------------------------ - -Here are some specific MUA configuration hints for editing and sending -patches for the Linux kernel. These are not meant to be complete -software package configuration summaries. - - -Legend: - -- TUI = text-based user interface -- GUI = graphical user interface - -Alpine (TUI) -************ - -Config options: - -In the :menuselection:`Sending Preferences` section: - -- :menuselection:`Do Not Send Flowed Text` must be ``enabled`` -- :menuselection:`Strip Whitespace Before Sending` must be ``disabled`` - -When composing the message, the cursor should be placed where the patch -should appear, and then pressing :kbd:`CTRL-R` let you specify the patch file -to insert into the message. - -Claws Mail (GUI) -**************** - -Works. Some people use this successfully for patches. - -To insert a patch use :menuselection:`Message-->Insert` File (:kbd:`CTRL-I`) -or an external editor. - -If the inserted patch has to be edited in the Claws composition window -"Auto wrapping" in -:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` should be -disabled. - -Evolution (GUI) -*************** - -Some people use this successfully for patches. - -When composing mail select: Preformat - from :menuselection:`Format-->Paragraph Style-->Preformatted` (:kbd:`CTRL-7`) - or the toolbar - -Then use: -:menuselection:`Insert-->Text File...` (:kbd:`ALT-N x`) -to insert the patch. - -You can also ``diff -Nru old.c new.c | xclip``, select -:menuselection:`Preformat`, then paste with the middle button. - -Kmail (GUI) -*********** - -Some people use Kmail successfully for patches. - -The default setting of not composing in HTML is appropriate; do not -enable it. - -When composing an email, under options, uncheck "word wrap". The only -disadvantage is any text you type in the email will not be word-wrapped -so you will have to manually word wrap text before the patch. The easiest -way around this is to compose your email with word wrap enabled, then save -it as a draft. Once you pull it up again from your drafts it is now hard -word-wrapped and you can uncheck "word wrap" without losing the existing -wrapping. - -At the bottom of your email, put the commonly-used patch delimiter before -inserting your patch: three hyphens (``---``). - -Then from the :menuselection:`Message` menu item, select insert file and -choose your patch. -As an added bonus you can customise the message creation toolbar menu -and put the :menuselection:`insert file` icon there. - -Make the composer window wide enough so that no lines wrap. As of -KMail 1.13.5 (KDE 4.5.4), KMail will apply word wrapping when sending -the email if the lines wrap in the composer window. Having word wrapping -disabled in the Options menu isn't enough. Thus, if your patch has very -long lines, you must make the composer window very wide before sending -the email. See: https://bugs.kde.org/show_bug.cgi?id=174034 - -You can safely GPG sign attachments, but inlined text is preferred for -patches so do not GPG sign them. Signing patches that have been inserted -as inlined text will make them tricky to extract from their 7-bit encoding. - -If you absolutely must send patches as attachments instead of inlining -them as text, right click on the attachment and select properties, and -highlight :menuselection:`Suggest automatic display` to make the attachment -inlined to make it more viewable. - -When saving patches that are sent as inlined text, select the email that -contains the patch from the message list pane, right click and select -:menuselection:`save as`. You can use the whole email unmodified as a patch -if it was properly composed. There is no option currently to save the email -when you are actually viewing it in its own window -- there has been a request -filed at kmail's bugzilla and hopefully this will be addressed. Emails are -saved as read-write for user only so you will have to chmod them to make them -group and world readable if you copy them elsewhere. - -Lotus Notes (GUI) -***************** - -Run away from it. - -Mutt (TUI) -********** - -Plenty of Linux developers use ``mutt``, so it must work pretty well. - -Mutt doesn't come with an editor, so whatever editor you use should be -used in a way that there are no automatic linebreaks. Most editors have -an :menuselection:`insert file` option that inserts the contents of a file -unaltered. - -To use ``vim`` with mutt:: - - set editor="vi" - -If using xclip, type the command:: - - :set paste - -before middle button or shift-insert or use:: - - :r filename - -if you want to include the patch inline. -(a)ttach works fine without ``set paste``. - -You can also generate patches with ``git format-patch`` and then use Mutt -to send them:: - - $ mutt -H 0001-some-bug-fix.patch - -Config options: - -It should work with default settings. -However, it's a good idea to set the ``send_charset`` to:: - - set send_charset="us-ascii:utf-8" - -Mutt is highly customizable. Here is a minimum configuration to start -using Mutt to send patches through Gmail:: - - # .muttrc - # ================ IMAP ==================== - set imap_user = 'yourusername@gmail.com' - set imap_pass = 'yourpassword' - set spoolfile = imaps://imap.gmail.com/INBOX - set folder = imaps://imap.gmail.com/ - set record="imaps://imap.gmail.com/[Gmail]/Sent Mail" - set postponed="imaps://imap.gmail.com/[Gmail]/Drafts" - set mbox="imaps://imap.gmail.com/[Gmail]/All Mail" - - # ================ SMTP ==================== - set smtp_url = "smtp://username@smtp.gmail.com:587/" - set smtp_pass = $imap_pass - set ssl_force_tls = yes # Require encrypted connection - - # ================ Composition ==================== - set editor = `echo \$EDITOR` - set edit_headers = yes # See the headers when editing - set charset = UTF-8 # value of $LANG; also fallback for send_charset - # Sender, email address, and sign-off line must match - unset use_domain # because joe@localhost is just embarrassing - set realname = "YOUR NAME" - set from = "username@gmail.com" - set use_from = yes - -The Mutt docs have lots more information: - - http://dev.mutt.org/trac/wiki/UseCases/Gmail - - http://dev.mutt.org/doc/manual.html - -Pine (TUI) -********** - -Pine has had some whitespace truncation issues in the past, but these -should all be fixed now. - -Use alpine (pine's successor) if you can. - -Config options: - -- ``quell-flowed-text`` is needed for recent versions -- the ``no-strip-whitespace-before-send`` option is needed - - -Sylpheed (GUI) -************** - -- Works well for inlining text (or using attachments). -- Allows use of an external editor. -- Is slow on large folders. -- Won't do TLS SMTP auth over a non-SSL connection. -- Has a helpful ruler bar in the compose window. -- Adding addresses to address book doesn't understand the display name - properly. - -Thunderbird (GUI) -***************** - -Thunderbird is an Outlook clone that likes to mangle text, but there are ways -to coerce it into behaving. - -- Allow use of an external editor: - The easiest thing to do with Thunderbird and patches is to use an - "external editor" extension and then just use your favorite ``$EDITOR`` - for reading/merging patches into the body text. To do this, download - and install the extension, then add a button for it using - :menuselection:`View-->Toolbars-->Customize...` and finally just click on it - when in the :menuselection:`Compose` dialog. - - Please note that "external editor" requires that your editor must not - fork, or in other words, the editor must not return before closing. - You may have to pass additional flags or change the settings of your - editor. Most notably if you are using gvim then you must pass the -f - option to gvim by putting ``/usr/bin/gvim -f`` (if the binary is in - ``/usr/bin``) to the text editor field in :menuselection:`external editor` - settings. If you are using some other editor then please read its manual - to find out how to do this. - -To beat some sense out of the internal editor, do this: - -- Edit your Thunderbird config settings so that it won't use ``format=flowed``. - Go to :menuselection:`edit-->preferences-->advanced-->config editor` to bring up - the thunderbird's registry editor. - -- Set ``mailnews.send_plaintext_flowed`` to ``false`` - -- Set ``mailnews.wraplength`` from ``72`` to ``0`` - -- :menuselection:`View-->Message Body As-->Plain Text` - -- :menuselection:`View-->Character Encoding-->Unicode (UTF-8)` - -TkRat (GUI) -*********** - -Works. Use "Insert file..." or external editor. - -Gmail (Web GUI) -*************** - -Does not work for sending patches. - -Gmail web client converts tabs to spaces automatically. - -At the same time it wraps lines every 78 chars with CRLF style line breaks -although tab2space problem can be solved with external editor. - -Another problem is that Gmail will base64-encode any message that has a -non-ASCII character. That includes things like European names. diff --git a/Documentation/kernel-docs.txt b/Documentation/kernel-docs.txt deleted file mode 100644 index 05a7857a4a83..000000000000 --- a/Documentation/kernel-docs.txt +++ /dev/null @@ -1,652 +0,0 @@ -.. _kernel_docs: - -Index of Documentation for People Interested in Writing and/or Understanding the Linux Kernel -============================================================================================= - - Juan-Mariano de Goyeneche - -The need for a document like this one became apparent in the -linux-kernel mailing list as the same questions, asking for pointers -to information, appeared again and again. - -Fortunately, as more and more people get to GNU/Linux, more and more -get interested in the Kernel. But reading the sources is not always -enough. It is easy to understand the code, but miss the concepts, the -philosophy and design decisions behind this code. - -Unfortunately, not many documents are available for beginners to -start. And, even if they exist, there was no "well-known" place which -kept track of them. These lines try to cover this lack. All documents -available on line known by the author are listed, while some reference -books are also mentioned. - -PLEASE, if you know any paper not listed here or write a new document, -send me an e-mail, and I'll include a reference to it here. Any -corrections, ideas or comments are also welcomed. - -The papers that follow are listed in no particular order. All are -cataloged with the following fields: the document's "Title", the -"Author"/s, the "URL" where they can be found, some "Keywords" helpful -when searching for specific topics, and a brief "Description" of the -Document. - -Enjoy! - -.. note:: - - The documents on each section of this document are ordered by its - published date, from the newest to the oldest. - -Docs at the Linux Kernel tree ------------------------------ - -The DocBook books should be built with ``make {htmldocs | psdocs | pdfdocs}``. -The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``. - - * Name: **linux/Documentation** - - :Author: Many. - :Location: Documentation/ - :Keywords: text files, Sphinx, DocBook. - :Description: Documentation that comes with the kernel sources, - inside the Documentation directory. Some pages from this document - (including this document itself) have been moved there, and might - be more up to date than the web version. - - * Title: **The Kernel Hacking HOWTO** - - :Author: Various Talented People, and Rusty. - :Location: Documentation/DocBook/kernel-hacking.tmpl - :Keywords: HOWTO, kernel contexts, deadlock, locking, modules, - symbols, return conventions. - :Description: From the Introduction: "Please understand that I - never wanted to write this document, being grossly underqualified, - but I always wanted to read it, and this was the only way. I - simply explain some best practices, and give reading entry-points - into the kernel sources. I avoid implementation details: that's - what the code is for, and I ignore whole tracts of useful - routines. This document assumes familiarity with C, and an - understanding of what the kernel is, and how it is used. It was - originally written for the 2.3 kernels, but nearly all of it - applies to 2.2 too; 2.0 is slightly different". - - * Title: **Linux Kernel Locking HOWTO** - - :Author: Various Talented People, and Rusty. - :Location: Documentation/DocBook/kernel-locking.tmpl - :Keywords: locks, locking, spinlock, semaphore, atomic, race - condition, bottom halves, tasklets, softirqs. - :Description: The title says it all: document describing the - locking system in the Linux Kernel either in uniprocessor or SMP - systems. - :Notes: "It was originally written for the later (>2.3.47) 2.3 - kernels, but most of it applies to 2.2 too; 2.0 is slightly - different". Freely redistributable under the conditions of the GNU - General Public License. - -On-line docs ------------- - - * Title: **Linux Kernel Mailing List Glossary** - - :Author: various - :URL: http://kernelnewbies.org/glossary/ - :Date: rolling version - :Keywords: glossary, terms, linux-kernel. - :Description: From the introduction: "This glossary is intended as - a brief description of some of the acronyms and terms you may hear - during discussion of the Linux kernel". - - * Title: **Tracing the Way of Data in a TCP Connection through the Linux Kernel** - - :Author: Richard Sailer - :URL: https://archive.org/details/linux_kernel_data_flow_short_paper - :Date: 2016 - :Keywords: Linux Kernel Networking, TCP, tracing, ftrace - :Description: A seminar paper explaining ftrace and how to use it for - understanding linux kernel internals, - illustrated at tracing the way of a TCP packet through the kernel. - :Abstract: *This short paper outlines the usage of ftrace a tracing framework - as a tool to understand a running Linux system. - Having obtained a trace-log a kernel hacker can read and understand - source code more determined and with context. - In a detailed example this approach is demonstrated in tracing - and the way of data in a TCP Connection through the kernel. - Finally this trace-log is used as base for more a exact conceptual - exploration and description of the Linux TCP/IP implementation.* - - * Title: **On submitting kernel Patches** - - :Author: Andi Kleen - :URL: http://halobates.de/on-submitting-kernel-patches.pdf - :Date: 2008 - :Keywords: patches, review process, types of submissions, basic rules, case studies - :Description: This paper gives several experience values on what types of patches - there are and how likley they get merged. - :Abstract: - [...]. This paper examines some common problems for - submitting larger changes and some strategies to avoid problems. - - * Title: **Overview of the Virtual File System** - - :Author: Richard Gooch. - :URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt - :Date: 2007 - :Keywords: VFS, File System, mounting filesystems, opening files, - dentries, dcache. - :Description: Brief introduction to the Linux Virtual File System. - What is it, how it works, operations taken when opening a file or - mounting a file system and description of important data - structures explaining the purpose of each of their entries. - - * Title: **Linux Device Drivers, Third Edition** - - :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman - :URL: http://lwn.net/Kernel/LDD3/ - :Date: 2005 - :Description: A 600-page book covering the (2.6.10) driver - programming API and kernel hacking in general. Available under the - Creative Commons Attribution-ShareAlike 2.0 license. - :note: You can also :ref:`purchase a copy from O'Reilly or elsewhere `. - - * Title: **Writing an ALSA Driver** - - :Author: Takashi Iwai - :URL: http://www.alsa-project.org/~iwai/writing-an-alsa-driver/index.html - :Date: 2005 - :Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware. - :Description: Advanced Linux Sound Architecture for developers, - both at kernel and user-level sides. ALSA is the Linux kernel - sound architecture in the 2.6 kernel version. - - * Title: **Linux PCMCIA Programmer's Guide** - - :Author: David Hinds. - :URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html - :Date: 2003 - :Keywords: PCMCIA. - :Description: "This document describes how to write kernel device - drivers for the Linux PCMCIA Card Services interface. It also - describes how to write user-mode utilities for communicating with - Card Services. - - * Title: **Linux Kernel Module Programming Guide** - - :Author: Ori Pomerantz. - :URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html - :Date: 2001 - :Keywords: modules, GPL book, /proc, ioctls, system calls, - interrupt handlers . - :Description: Very nice 92 pages GPL book on the topic of modules - programming. Lots of examples. - - * Title: **Global spinlock list and usage** - - :Author: Rick Lindsley. - :URL: http://lse.sourceforge.net/lockhier/global-spin-lock - :Date: 2001 - :Keywords: spinlock. - :Description: This is an attempt to document both the existence and - usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive - list of spinlocks showing when they are used, which functions - access them, how each lock is acquired, under what conditions it - is held, whether interrupts can occur or not while it is held... - - * Title: **A Linux vm README** - - :Author: Kanoj Sarcar. - :URL: http://kos.enix.org/pub/linux-vmm.html - :Date: 2001 - :Keywords: virtual memory, mm, pgd, vma, page, page flags, page - cache, swap cache, kswapd. - :Description: Telegraphic, short descriptions and definitions - relating the Linux virtual memory implementation. - - * Title: **Video4linux Drivers, Part 1: Video-Capture Device** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/406 - :Date: 2000 - :Keywords: video4linux, driver, video capture, capture devices, - camera driver. - :Description: The title says it all. - - * Title: **Video4linux Drivers, Part 2: Video-capture Devices** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/429 - :Date: 2000 - :Keywords: video4linux, driver, video capture, capture devices, - camera driver, control, query capabilities, capability, facility. - :Description: The title says it all. - - * Title: **Linux IP Networking. A Guide to the Implementation and Modification of the Linux Protocol Stack.** - - :Author: Glenn Herrin. - :URL: http://www.cs.unh.edu/cnrg/gherrin - :Date: 2000 - :Keywords: network, networking, protocol, IP, UDP, TCP, connection, - socket, receiving, transmitting, forwarding, routing, packets, - modules, /proc, sk_buff, FIB, tags. - :Description: Excellent paper devoted to the Linux IP Networking, - explaining anything from the kernel's to the user space - configuration tools' code. Very good to get a general overview of - the kernel networking implementation and understand all steps - packets follow from the time they are received at the network - device till they are delivered to applications. The studied kernel - code is from 2.2.14 version. Provides code for a working packet - dropper example. - - * Title: **How To Make Sure Your Driver Will Work On The Power Macintosh** - - :Author: Paul Mackerras. - :URL: http://www.linux-mag.com/id/261 - :Date: 1999 - :Keywords: Mac, Power Macintosh, porting, drivers, compatibility. - :Description: The title says it all. - - * Title: **An Introduction to SCSI Drivers** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/284 - :Date: 1999 - :Keywords: SCSI, device, driver. - :Description: The title says it all. - - * Title: **Advanced SCSI Drivers And Other Tales** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/307 - :Date: 1999 - :Keywords: SCSI, device, driver, advanced. - :Description: The title says it all. - - * Title: **Writing Linux Mouse Drivers** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/330 - :Date: 1999 - :Keywords: mouse, driver, gpm. - :Description: The title says it all. - - * Title: **More on Mouse Drivers** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/356 - :Date: 1999 - :Keywords: mouse, driver, gpm, races, asynchronous I/O. - :Description: The title still says it all. - - * Title: **Writing Video4linux Radio Driver** - - :Author: Alan Cox. - :URL: http://www.linux-mag.com/id/381 - :Date: 1999 - :Keywords: video4linux, driver, radio, radio devices. - :Description: The title says it all. - - * Title: **I/O Event Handling Under Linux** - - :Author: Richard Gooch. - :URL: http://web.mit.edu/~yandros/doc/io-events.html - :Date: 1999 - :Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness - event queues. - :Description: From the Introduction: "I/O Event handling is about - how your Operating System allows you to manage a large number of - open files (file descriptors in UNIX/POSIX, or FDs) in your - application. You want the OS to notify you when FDs become active - (have data ready to be read or are ready for writing). Ideally you - want a mechanism that is scalable. This means a large number of - inactive FDs cost very little in memory and CPU time to manage". - - * Title: **(nearly) Complete Linux Loadable Kernel Modules. The definitive guide for hackers, virus coders and system administrators.** - - :Author: pragmatic/THC. - :URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html - :Date: 1999 - :Keywords: syscalls, intercept, hide, abuse, symbol table. - :Description: Interesting paper on how to abuse the Linux kernel in - order to intercept and modify syscalls, make - files/directories/processes invisible, become root, hijack ttys, - write kernel modules based virus... and solutions for admins to - avoid all those abuses. - :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x - kernels. - - * Name: **Linux Virtual File System** - - :Author: Peter J. Braam. - :URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/ - :Date: 1998 - :Keywords: slides, VFS, inode, superblock, dentry, dcache. - :Description: Set of slides, presumably from a presentation on the - Linux VFS layer. Covers version 2.1.x, with dentries and the - dcache. - - * Title: **The Venus kernel interface** - - :Author: Peter J. Braam. - :URL: http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html - :Date: 1998 - :Keywords: coda, filesystem, venus, cache manager. - :Description: "This document describes the communication between - Venus and kernel level file system code needed for the operation - of the Coda filesystem. This version document is meant to describe - the current interface (version 1.0) as well as improvements we - envisage". - - * Title: **Design and Implementation of the Second Extended Filesystem** - - :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. - :URL: http://web.mit.edu/tytso/www/linux/ext2intro.html - :Date: 1998 - :Keywords: ext2, linux fs history, inode, directory, link, devices, - VFS, physical structure, performance, benchmarks, ext2fs library, - ext2fs tools, e2fsck. - :Description: Paper written by three of the top ext2 hackers. - Covers Linux filesystems history, ext2 motivation, ext2 features, - design, physical structure on disk, performance, benchmarks, - e2fsck's passes description... A must read! - :Notes: This paper was first published in the Proceedings of the - First Dutch International Symposium on Linux, ISBN 90-367-0385-9. - - * Title: **The Linux RAID-1, 4, 5 Code** - - :Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza. - :URL: http://www.linuxjournal.com/article.php?sid=2391 - :Date: 1997 - :Keywords: RAID, MD driver. - :Description: Linux Journal Kernel Korner article. Here is its - :Abstract: *A description of the implementation of the RAID-1, - RAID-4 and RAID-5 personalities of the MD device driver in the - Linux kernel, providing users with high performance and reliable, - secondary-storage capability using software*. - - * Title: **Linux Kernel Hackers' Guide** - - :Author: Michael K. Johnson. - :URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html - :Date: 1997 - :Keywords: device drivers, files, VFS, kernel interface, character vs - block devices, hardware interrupts, scsi, DMA, access to user memory, - memory allocation, timers. - :Description: A guide designed to help you get up to speed on the - concepts that are not intuitevly obvious, and to document the internal - structures of Linux. - - * Title: **Dynamic Kernels: Modularized Device Drivers** - - :Author: Alessandro Rubini. - :URL: http://www.linuxjournal.com/article.php?sid=1219 - :Date: 1996 - :Keywords: device driver, module, loading/unloading modules, - allocating resources. - :Description: Linux Journal Kernel Korner article. Here is its - :Abstract: *This is the first of a series of four articles - co-authored by Alessandro Rubini and Georg Zezchwitz which present - a practical approach to writing Linux device drivers as kernel - loadable modules. This installment presents an introduction to the - topic, preparing the reader to understand next month's - installment*. - - * Title: **Dynamic Kernels: Discovery** - - :Author: Alessandro Rubini. - :URL: http://www.linuxjournal.com/article.php?sid=1220 - :Date: 1996 - :Keywords: character driver, init_module, clean_up module, - autodetection, mayor number, minor number, file operations, - open(), close(). - :Description: Linux Journal Kernel Korner article. Here is its - :Abstract: *This article, the second of four, introduces part of - the actual code to create custom module implementing a character - device driver. It describes the code for module initialization and - cleanup, as well as the open() and close() system calls*. - - * Title: **The Devil's in the Details** - - :Author: Georg v. Zezschwitz and Alessandro Rubini. - :URL: http://www.linuxjournal.com/article.php?sid=1221 - :Date: 1996 - :Keywords: read(), write(), select(), ioctl(), blocking/non - blocking mode, interrupt handler. - :Description: Linux Journal Kernel Korner article. Here is its - :Abstract: *This article, the third of four on writing character - device drivers, introduces concepts of reading, writing, and using - ioctl-calls*. - - * Title: **Dissecting Interrupts and Browsing DMA** - - :Author: Alessandro Rubini and Georg v. Zezschwitz. - :URL: http://www.linuxjournal.com/article.php?sid=1222 - :Date: 1996 - :Keywords: interrupts, irqs, DMA, bottom halves, task queues. - :Description: Linux Journal Kernel Korner article. Here is its - :Abstract: *This is the fourth in a series of articles about - writing character device drivers as loadable kernel modules. This - month, we further investigate the field of interrupt handling. - Though it is conceptually simple, practical limitations and - constraints make this an ''interesting'' part of device driver - writing, and several different facilities have been provided for - different situations. We also investigate the complex topic of - DMA*. - - * Title: **Device Drivers Concluded** - - :Author: Georg v. Zezschwitz. - :URL: http://www.linuxjournal.com/article.php?sid=1287 - :Date: 1996 - :Keywords: address spaces, pages, pagination, page management, - demand loading, swapping, memory protection, memory mapping, mmap, - virtual memory areas (VMAs), vremap, PCI. - :Description: Finally, the above turned out into a five articles - series. This latest one's introduction reads: "This is the last of - five articles about character device drivers. In this final - section, Georg deals with memory mapping devices, beginning with - an overall description of the Linux memory management concepts". - - * Title: **Network Buffers And Memory Management** - - :Author: Alan Cox. - :URL: http://www.linuxjournal.com/article.php?sid=1312 - :Date: 1996 - :Keywords: sk_buffs, network devices, protocol/link layer - variables, network devices flags, transmit, receive, - configuration, multicast. - :Description: Linux Journal Kernel Korner. - :Abstract: *Writing a network device driver for Linux is fundamentally - simple---most of the complexity (other than talking to the - hardware) involves managing network packets in memory*. - - * Title: **Analysis of the Ext2fs structure** - - :Author: Louis-Dominique Dubeau. - :URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ - :Date: 1994 - :Keywords: ext2, filesystem, ext2fs. - :Description: Description of ext2's blocks, directories, inodes, - bitmaps, invariants... - -Published books ---------------- - - * Title: **Linux Treiber entwickeln** - - :Author: Jürgen Quade, Eva-Katharina Kunst - :Publisher: dpunkt.verlag - :Date: Oct 2015 (4th edition) - :Pages: 688 - :ISBN: 978-3-86490-288-8 - :Note: German. The third edition from 2011 is - much cheaper and still quite up-to-date. - - * Title: **Linux Kernel Networking: Implementation and Theory** - - :Author: Rami Rosen - :Publisher: Apress - :Date: December 22, 2013 - :Pages: 648 - :ISBN: 978-1430261964 - - * Title: **Embedded Linux Primer: A practical Real-World Approach, 2nd Edition** - - :Author: Christopher Hallinan - :Publisher: Pearson - :Date: November, 2010 - :Pages: 656 - :ISBN: 978-0137017836 - - * Title: **Linux Kernel Development, 3rd Edition** - - :Author: Robert Love - :Publisher: Addison-Wesley - :Date: July, 2010 - :Pages: 440 - :ISBN: 978-0672329463 - - * Title: **Essential Linux Device Drivers** - - :Author: Sreekrishnan Venkateswaran - :Published: Prentice Hall - :Date: April, 2008 - :Pages: 744 - :ISBN: 978-0132396554 - -.. _ldd3_published: - - * Title: **Linux Device Drivers, 3rd Edition** - - :Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman - :Publisher: O'Reilly & Associates - :Date: 2005 - :Pages: 636 - :ISBN: 0-596-00590-3 - :Notes: Further information in - http://www.oreilly.com/catalog/linuxdrive3/ - PDF format, URL: http://lwn.net/Kernel/LDD3/ - - * Title: **Linux Kernel Internals** - - :Author: Michael Beck - :Publisher: Addison-Wesley - :Date: 1997 - :ISBN: 0-201-33143-8 (second edition) - - * Title: **Programmation Linux 2.0 API systeme et fonctionnement du noyau** - - :Author: Remy Card, Eric Dumas, Franck Mevel - :Publisher: Eyrolles - :Date: 1997 - :Pages: 520 - :ISBN: 2-212-08932-5 - :Notes: French - - * Title: **The Design and Implementation of the 4.4 BSD UNIX Operating System** - - :Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, - John S. Quarterman - :Publisher: Addison-Wesley - :Date: 1996 - :ISBN: 0-201-54979-4 - - * Title: **Unix internals -- the new frontiers** - - :Author: Uresh Vahalia - :Publisher: Prentice Hall - :Date: 1996 - :Pages: 600 - :ISBN: 0-13-101908-2 - - * Title: **Programming for the real world - POSIX.4** - - :Author: Bill O. Gallmeister - :Publisher: O'Reilly & Associates, Inc - :Date: 1995 - :Pages: 552 - :ISBN: I-56592-074-0 - :Notes: Though not being directly about Linux, Linux aims to be - POSIX. Good reference. - - * Title: **UNIX Systems for Modern Architectures: Symmetric Multiprocessing and Caching for Kernel Programmers** - - :Author: Curt Schimmel - :Publisher: Addison Wesley - :Date: June, 1994 - :Pages: 432 - :ISBN: 0-201-63338-8 - - * Title: **The Design and Implementation of the 4.3 BSD UNIX Operating System** - - :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J - Karels, John S. Quarterman - :Publisher: Addison-Wesley - :Date: 1989 (reprinted with corrections on October, 1990) - :ISBN: 0-201-06196-1 - - * Title: **The Design of the UNIX Operating System** - - :Author: Maurice J. Bach - :Publisher: Prentice Hall - :Date: 1986 - :Pages: 471 - :ISBN: 0-13-201757-1 - -Miscellaneous -------------- - - * Name: **Cross-Referencing Linux** - - :URL: http://lxr.free-electrons.com/ - :Keywords: Browsing source code. - :Description: Another web-based Linux kernel source code browser. - Lots of cross references to variables and functions. You can see - where they are defined and where they are used. - - * Name: **Linux Weekly News** - - :URL: http://lwn.net - :Keywords: latest kernel news. - :Description: The title says it all. There's a fixed kernel section - summarizing developers' work, bug fixes, new features and versions - produced during the week. Published every Thursday. - - * Name: **The home page of Linux-MM** - - :Author: The Linux-MM team. - :URL: http://linux-mm.org/ - :Keywords: memory management, Linux-MM, mm patches, TODO, docs, - mailing list. - :Description: Site devoted to Linux Memory Management development. - Memory related patches, HOWTOs, links, mm developers... Don't miss - it if you are interested in memory management development! - - * Name: **Kernel Newbies IRC Channel and Website** - - :URL: http://www.kernelnewbies.org - :Keywords: IRC, newbies, channel, asking doubts. - :Description: #kernelnewbies on irc.oftc.net. - #kernelnewbies is an IRC network dedicated to the 'newbie' - kernel hacker. The audience mostly consists of people who are - learning about the kernel, working on kernel projects or - professional kernel hackers that want to help less seasoned kernel - people. - #kernelnewbies is on the OFTC IRC Network. - Try irc.oftc.net as your server and then /join #kernelnewbies. - The kernelnewbies website also hosts articles, documents, FAQs... - - * Name: **linux-kernel mailing list archives and search engines** - - :URL: http://vger.kernel.org/vger-lists.html - :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html - :URL: http://groups.google.com/group/mlist.linux.kernel - :Keywords: linux-kernel, archives, search. - :Description: Some of the linux-kernel mailing list archivers. If - you have a better/another one, please let me know. - -------- - -Document last updated on Tue 2016-Sep-20 - -This document is based on: - http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html diff --git a/Documentation/magic-number.txt b/Documentation/magic-number.txt deleted file mode 100644 index c74199f60c6c..000000000000 --- a/Documentation/magic-number.txt +++ /dev/null @@ -1,164 +0,0 @@ -Linux magic numbers -=================== - -This file is a registry of magic numbers which are in use. When you -add a magic number to a structure, you should also add it to this -file, since it is best if the magic numbers used by various structures -are unique. - -It is a **very** good idea to protect kernel data structures with magic -numbers. This allows you to check at run time whether (a) a structure -has been clobbered, or (b) you've passed the wrong structure to a -routine. This last is especially useful --- particularly when you are -passing pointers to structures via a void * pointer. The tty code, -for example, does this frequently to pass driver-specific and line -discipline-specific structures back and forth. - -The way to use magic numbers is to declare then at the beginning of -the structure, like so:: - - struct tty_ldisc { - int magic; - ... - }; - -Please follow this discipline when you are adding future enhancements -to the kernel! It has saved me countless hours of debugging, -especially in the screwy cases where an array has been overrun and -structures following the array have been overwritten. Using this -discipline, these cases get detected quickly and safely. - -Changelog:: - - Theodore Ts'o - 31 Mar 94 - - The magic table is current to Linux 2.1.55. - - Michael Chastain - - 22 Sep 1997 - - Now it should be up to date with Linux 2.1.112. Because - we are in feature freeze time it is very unlikely that - something will change before 2.2.x. The entries are - sorted by number field. - - Krzysztof G. Baranowski - - 29 Jul 1998 - - Updated the magic table to Linux 2.5.45. Right over the feature freeze, - but it is possible that some new magic numbers will sneak into the - kernel before 2.6.x yet. - - Petr Baudis - - 03 Nov 2002 - - Updated the magic table to Linux 2.5.74. - - Fabian Frederick - - 09 Jul 2003 - - -===================== ================ ======================== ========================================== -Magic Name Number Structure File -===================== ================ ======================== ========================================== -PG_MAGIC 'P' pg_{read,write}_hdr ``include/linux/pg.h`` -CMAGIC 0x0111 user ``include/linux/a.out.h`` -MKISS_DRIVER_MAGIC 0x04bf mkiss_channel ``drivers/net/mkiss.h`` -HDLC_MAGIC 0x239e n_hdlc ``drivers/char/n_hdlc.c`` -APM_BIOS_MAGIC 0x4101 apm_user ``arch/x86/kernel/apm_32.c`` -CYCLADES_MAGIC 0x4359 cyclades_port ``include/linux/cyclades.h`` -DB_MAGIC 0x4442 fc_info ``drivers/net/iph5526_novram.c`` -DL_MAGIC 0x444d fc_info ``drivers/net/iph5526_novram.c`` -FASYNC_MAGIC 0x4601 fasync_struct ``include/linux/fs.h`` -FF_MAGIC 0x4646 fc_info ``drivers/net/iph5526_novram.c`` -ISICOM_MAGIC 0x4d54 isi_port ``include/linux/isicom.h`` -PTY_MAGIC 0x5001 ``drivers/char/pty.c`` -PPP_MAGIC 0x5002 ppp ``include/linux/if_pppvar.h`` -SERIAL_MAGIC 0x5301 async_struct ``include/linux/serial.h`` -SSTATE_MAGIC 0x5302 serial_state ``include/linux/serial.h`` -SLIP_MAGIC 0x5302 slip ``drivers/net/slip.h`` -STRIP_MAGIC 0x5303 strip ``drivers/net/strip.c`` -X25_ASY_MAGIC 0x5303 x25_asy ``drivers/net/x25_asy.h`` -SIXPACK_MAGIC 0x5304 sixpack ``drivers/net/hamradio/6pack.h`` -AX25_MAGIC 0x5316 ax_disp ``drivers/net/mkiss.h`` -TTY_MAGIC 0x5401 tty_struct ``include/linux/tty.h`` -MGSL_MAGIC 0x5401 mgsl_info ``drivers/char/synclink.c`` -TTY_DRIVER_MAGIC 0x5402 tty_driver ``include/linux/tty_driver.h`` -MGSLPC_MAGIC 0x5402 mgslpc_info ``drivers/char/pcmcia/synclink_cs.c`` -TTY_LDISC_MAGIC 0x5403 tty_ldisc ``include/linux/tty_ldisc.h`` -USB_SERIAL_MAGIC 0x6702 usb_serial ``drivers/usb/serial/usb-serial.h`` -FULL_DUPLEX_MAGIC 0x6969 ``drivers/net/ethernet/dec/tulip/de2104x.c`` -USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth ``drivers/usb/class/bluetty.c`` -RFCOMM_TTY_MAGIC 0x6d02 ``net/bluetooth/rfcomm/tty.c`` -USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port ``drivers/usb/serial/usb-serial.h`` -CG_MAGIC 0x00090255 ufs_cylinder_group ``include/linux/ufs_fs.h`` -RPORT_MAGIC 0x00525001 r_port ``drivers/char/rocket_int.h`` -LSEMAGIC 0x05091998 lse ``drivers/fc4/fc.c`` -GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str ``drivers/scsi/gdth_ioctl.h`` -RIEBL_MAGIC 0x09051990 ``drivers/net/atarilance.c`` -NBD_REQUEST_MAGIC 0x12560953 nbd_request ``include/linux/nbd.h`` -RED_MAGIC2 0x170fc2a5 (any) ``mm/slab.c`` -BAYCOM_MAGIC 0x19730510 baycom_state ``drivers/net/baycom_epp.c`` -ISDN_X25IFACE_MAGIC 0x1e75a2b9 isdn_x25iface_proto_data ``drivers/isdn/isdn_x25iface.h`` -ECP_MAGIC 0x21504345 cdkecpsig ``include/linux/cdk.h`` -LSOMAGIC 0x27091997 lso ``drivers/fc4/fc.c`` -LSMAGIC 0x2a3b4d2a ls ``drivers/fc4/fc.c`` -WANPIPE_MAGIC 0x414C4453 sdla_{dump,exec} ``include/linux/wanpipe.h`` -CS_CARD_MAGIC 0x43525553 cs_card ``sound/oss/cs46xx.c`` -LABELCL_MAGIC 0x4857434c labelcl_info_s ``include/asm/ia64/sn/labelcl.h`` -ISDN_ASYNC_MAGIC 0x49344C01 modem_info ``include/linux/isdn.h`` -CTC_ASYNC_MAGIC 0x49344C01 ctc_tty_info ``drivers/s390/net/ctctty.c`` -ISDN_NET_MAGIC 0x49344C02 isdn_net_local_s ``drivers/isdn/i4l/isdn_net_lib.h`` -SAVEKMSG_MAGIC2 0x4B4D5347 savekmsg ``arch/*/amiga/config.c`` -CS_STATE_MAGIC 0x4c4f4749 cs_state ``sound/oss/cs46xx.c`` -SLAB_C_MAGIC 0x4f17a36d kmem_cache ``mm/slab.c`` -COW_MAGIC 0x4f4f4f4d cow_header_v1 ``arch/um/drivers/ubd_user.c`` -I810_CARD_MAGIC 0x5072696E i810_card ``sound/oss/i810_audio.c`` -TRIDENT_CARD_MAGIC 0x5072696E trident_card ``sound/oss/trident.c`` -ROUTER_MAGIC 0x524d4157 wan_device [in ``wanrouter.h`` pre 3.9] -SAVEKMSG_MAGIC1 0x53415645 savekmsg ``arch/*/amiga/config.c`` -GDA_MAGIC 0x58464552 gda ``arch/mips/include/asm/sn/gda.h`` -RED_MAGIC1 0x5a2cf071 (any) ``mm/slab.c`` -EEPROM_MAGIC_VALUE 0x5ab478d2 lanai_dev ``drivers/atm/lanai.c`` -HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state ``include/linux/hdlcdrv.h`` -PCXX_MAGIC 0x5c6df104 channel ``drivers/char/pcxx.h`` -KV_MAGIC 0x5f4b565f kernel_vars_s ``arch/mips/include/asm/sn/klkernvars.h`` -I810_STATE_MAGIC 0x63657373 i810_state ``sound/oss/i810_audio.c`` -TRIDENT_STATE_MAGIC 0x63657373 trient_state ``sound/oss/trident.c`` -M3_CARD_MAGIC 0x646e6f50 m3_card ``sound/oss/maestro3.c`` -FW_HEADER_MAGIC 0x65726F66 fw_header ``drivers/atm/fore200e.h`` -SLOT_MAGIC 0x67267321 slot ``drivers/hotplug/cpqphp.h`` -SLOT_MAGIC 0x67267322 slot ``drivers/hotplug/acpiphp.h`` -LO_MAGIC 0x68797548 nbd_device ``include/linux/nbd.h`` -OPROFILE_MAGIC 0x6f70726f super_block ``drivers/oprofile/oprofilefs.h`` -M3_STATE_MAGIC 0x734d724d m3_state ``sound/oss/maestro3.c`` -VMALLOC_MAGIC 0x87654320 snd_alloc_track ``sound/core/memory.c`` -KMALLOC_MAGIC 0x87654321 snd_alloc_track ``sound/core/memory.c`` -PWC_MAGIC 0x89DC10AB pwc_device ``drivers/usb/media/pwc.h`` -NBD_REPLY_MAGIC 0x96744668 nbd_reply ``include/linux/nbd.h`` -ENI155_MAGIC 0xa54b872d midway_eprom ``drivers/atm/eni.h`` -CODA_MAGIC 0xC0DAC0DA coda_file_info ``fs/coda/coda_fs_i.h`` -DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram ``drivers/scsi/gdth.h`` -YAM_MAGIC 0xF10A7654 yam_port ``drivers/net/hamradio/yam.c`` -CCB_MAGIC 0xf2691ad2 ccb ``drivers/scsi/ncr53c8xx.c`` -QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry ``drivers/scsi/arm/queue.c`` -QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry ``drivers/scsi/arm/queue.c`` -HTB_CMAGIC 0xFEFAFEF1 htb_class ``net/sched/sch_htb.c`` -NMI_MAGIC 0x48414d4d455201 nmi_s ``arch/mips/include/asm/sn/nmi.h`` -===================== ================ ======================== ========================================== - -Note that there are also defined special per-driver magic numbers in sound -memory management. See ``include/sound/sndmagic.h`` for complete list of them. Many -OSS sound drivers have their magic numbers constructed from the soundcard PCI -ID - these are not listed here as well. - -IrDA subsystem also uses large number of own magic numbers, see -``include/net/irda/irda.h`` for a complete list of them. - -HFS is another larger user of magic numbers - you can find them in -``fs/hfs/hfs.h``. diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst new file mode 100644 index 000000000000..f5b5b1aa51b3 --- /dev/null +++ b/Documentation/process/adding-syscalls.rst @@ -0,0 +1,542 @@ +Adding a New System Call +======================== + +This document describes what's involved in adding a new system call to the +Linux kernel, over and above the normal submission advice in +:ref:`Documentation/SubmittingPatches `. + + +System Call Alternatives +------------------------ + +The first thing to consider when adding a new system call is whether one of +the alternatives might be suitable instead. Although system calls are the +most traditional and most obvious interaction points between userspace and the +kernel, there are other possibilities -- choose what fits best for your +interface. + + - If the operations involved can be made to look like a filesystem-like + object, it may make more sense to create a new filesystem or device. This + also makes it easier to encapsulate the new functionality in a kernel module + rather than requiring it to be built into the main kernel. + + - If the new functionality involves operations where the kernel notifies + userspace that something has happened, then returning a new file + descriptor for the relevant object allows userspace to use + ``poll``/``select``/``epoll`` to receive that notification. + - However, operations that don't map to + :manpage:`read(2)`/:manpage:`write(2)`-like operations + have to be implemented as :manpage:`ioctl(2)` requests, which can lead + to a somewhat opaque API. + + - If you're just exposing runtime system information, a new node in sysfs + (see ``Documentation/filesystems/sysfs.txt``) or the ``/proc`` filesystem may + be more appropriate. However, access to these mechanisms requires that the + relevant filesystem is mounted, which might not always be the case (e.g. + in a namespaced/sandboxed/chrooted environment). Avoid adding any API to + debugfs, as this is not considered a 'production' interface to userspace. + - If the operation is specific to a particular file or file descriptor, then + an additional :manpage:`fcntl(2)` command option may be more appropriate. However, + :manpage:`fcntl(2)` is a multiplexing system call that hides a lot of complexity, so + this option is best for when the new function is closely analogous to + existing :manpage:`fcntl(2)` functionality, or the new functionality is very simple + (for example, getting/setting a simple flag related to a file descriptor). + - If the operation is specific to a particular task or process, then an + additional :manpage:`prctl(2)` command option may be more appropriate. As + with :manpage:`fcntl(2)`, this system call is a complicated multiplexor so + is best reserved for near-analogs of existing ``prctl()`` commands or + getting/setting a simple flag related to a process. + + +Designing the API: Planning for Extension +----------------------------------------- + +A new system call forms part of the API of the kernel, and has to be supported +indefinitely. As such, it's a very good idea to explicitly discuss the +interface on the kernel mailing list, and it's important to plan for future +extensions of the interface. + +(The syscall table is littered with historical examples where this wasn't done, +together with the corresponding follow-up system calls -- +``eventfd``/``eventfd2``, ``dup2``/``dup3``, ``inotify_init``/``inotify_init1``, +``pipe``/``pipe2``, ``renameat``/``renameat2`` -- so +learn from the history of the kernel and plan for extensions from the start.) + +For simpler system calls that only take a couple of arguments, the preferred +way to allow for future extensibility is to include a flags argument to the +system call. To make sure that userspace programs can safely use flags +between kernel versions, check whether the flags value holds any unknown +flags, and reject the system call (with ``EINVAL``) if it does:: + + if (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3)) + return -EINVAL; + +(If no flags values are used yet, check that the flags argument is zero.) + +For more sophisticated system calls that involve a larger number of arguments, +it's preferred to encapsulate the majority of the arguments into a structure +that is passed in by pointer. Such a structure can cope with future extension +by including a size argument in the structure:: + + struct xyzzy_params { + u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */ + u32 param_1; + u64 param_2; + u64 param_3; + }; + +As long as any subsequently added field, say ``param_4``, is designed so that a +zero value gives the previous behaviour, then this allows both directions of +version mismatch: + + - To cope with a later userspace program calling an older kernel, the kernel + code should check that any memory beyond the size of the structure that it + expects is zero (effectively checking that ``param_4 == 0``). + - To cope with an older userspace program calling a newer kernel, the kernel + code can zero-extend a smaller instance of the structure (effectively + setting ``param_4 = 0``). + +See :manpage:`perf_event_open(2)` and the ``perf_copy_attr()`` function (in +``kernel/events/core.c``) for an example of this approach. + + +Designing the API: Other Considerations +--------------------------------------- + +If your new system call allows userspace to refer to a kernel object, it +should use a file descriptor as the handle for that object -- don't invent a +new type of userspace object handle when the kernel already has mechanisms and +well-defined semantics for using file descriptors. + +If your new :manpage:`xyzzy(2)` system call does return a new file descriptor, +then the flags argument should include a value that is equivalent to setting +``O_CLOEXEC`` on the new FD. This makes it possible for userspace to close +the timing window between ``xyzzy()`` and calling +``fcntl(fd, F_SETFD, FD_CLOEXEC)``, where an unexpected ``fork()`` and +``execve()`` in another thread could leak a descriptor to +the exec'ed program. (However, resist the temptation to re-use the actual value +of the ``O_CLOEXEC`` constant, as it is architecture-specific and is part of a +numbering space of ``O_*`` flags that is fairly full.) + +If your system call returns a new file descriptor, you should also consider +what it means to use the :manpage:`poll(2)` family of system calls on that file +descriptor. Making a file descriptor ready for reading or writing is the +normal way for the kernel to indicate to userspace that an event has +occurred on the corresponding kernel object. + +If your new :manpage:`xyzzy(2)` system call involves a filename argument:: + + int sys_xyzzy(const char __user *path, ..., unsigned int flags); + +you should also consider whether an :manpage:`xyzzyat(2)` version is more appropriate:: + + int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags); + +This allows more flexibility for how userspace specifies the file in question; +in particular it allows userspace to request the functionality for an +already-opened file descriptor using the ``AT_EMPTY_PATH`` flag, effectively +giving an :manpage:`fxyzzy(3)` operation for free:: + + - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...) + - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...) + +(For more details on the rationale of the \*at() calls, see the +:manpage:`openat(2)` man page; for an example of AT_EMPTY_PATH, see the +:manpage:`fstatat(2)` man page.) + +If your new :manpage:`xyzzy(2)` system call involves a parameter describing an +offset within a file, make its type ``loff_t`` so that 64-bit offsets can be +supported even on 32-bit architectures. + +If your new :manpage:`xyzzy(2)` system call involves privileged functionality, +it needs to be governed by the appropriate Linux capability bit (checked with +a call to ``capable()``), as described in the :manpage:`capabilities(7)` man +page. Choose an existing capability bit that governs related functionality, +but try to avoid combining lots of only vaguely related functions together +under the same bit, as this goes against capabilities' purpose of splitting +the power of root. In particular, avoid adding new uses of the already +overly-general ``CAP_SYS_ADMIN`` capability. + +If your new :manpage:`xyzzy(2)` system call manipulates a process other than +the calling process, it should be restricted (using a call to +``ptrace_may_access()``) so that only a calling process with the same +permissions as the target process, or with the necessary capabilities, can +manipulate the target process. + +Finally, be aware that some non-x86 architectures have an easier time if +system call parameters that are explicitly 64-bit fall on odd-numbered +arguments (i.e. parameter 1, 3, 5), to allow use of contiguous pairs of 32-bit +registers. (This concern does not apply if the arguments are part of a +structure that's passed in by pointer.) + + +Proposing the API +----------------- + +To make new system calls easy to review, it's best to divide up the patchset +into separate chunks. These should include at least the following items as +distinct commits (each of which is described further below): + + - The core implementation of the system call, together with prototypes, + generic numbering, Kconfig changes and fallback stub implementation. + - Wiring up of the new system call for one particular architecture, usually + x86 (including all of x86_64, x86_32 and x32). + - A demonstration of the use of the new system call in userspace via a + selftest in ``tools/testing/selftests/``. + - A draft man-page for the new system call, either as plain text in the + cover letter, or as a patch to the (separate) man-pages repository. + +New system call proposals, like any change to the kernel's API, should always +be cc'ed to linux-api@vger.kernel.org. + + +Generic System Call Implementation +---------------------------------- + +The main entry point for your new :manpage:`xyzzy(2)` system call will be called +``sys_xyzzy()``, but you add this entry point with the appropriate +``SYSCALL_DEFINEn()`` macro rather than explicitly. The 'n' indicates the +number of arguments to the system call, and the macro takes the system call name +followed by the (type, name) pairs for the parameters as arguments. Using +this macro allows metadata about the new system call to be made available for +other tools. + +The new entry point also needs a corresponding function prototype, in +``include/linux/syscalls.h``, marked as asmlinkage to match the way that system +calls are invoked:: + + asmlinkage long sys_xyzzy(...); + +Some architectures (e.g. x86) have their own architecture-specific syscall +tables, but several other architectures share a generic syscall table. Add your +new system call to the generic list by adding an entry to the list in +``include/uapi/asm-generic/unistd.h``:: + + #define __NR_xyzzy 292 + __SYSCALL(__NR_xyzzy, sys_xyzzy) + +Also update the __NR_syscalls count to reflect the additional system call, and +note that if multiple new system calls are added in the same merge window, +your new syscall number may get adjusted to resolve conflicts. + +The file ``kernel/sys_ni.c`` provides a fallback stub implementation of each +system call, returning ``-ENOSYS``. Add your new system call here too:: + + cond_syscall(sys_xyzzy); + +Your new kernel functionality, and the system call that controls it, should +normally be optional, so add a ``CONFIG`` option (typically to +``init/Kconfig``) for it. As usual for new ``CONFIG`` options: + + - Include a description of the new functionality and system call controlled + by the option. + - Make the option depend on EXPERT if it should be hidden from normal users. + - Make any new source files implementing the function dependent on the CONFIG + option in the Makefile (e.g. ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.c``). + - Double check that the kernel still builds with the new CONFIG option turned + off. + +To summarize, you need a commit that includes: + + - ``CONFIG`` option for the new function, normally in ``init/Kconfig`` + - ``SYSCALL_DEFINEn(xyzzy, ...)`` for the entry point + - corresponding prototype in ``include/linux/syscalls.h`` + - generic table entry in ``include/uapi/asm-generic/unistd.h`` + - fallback stub in ``kernel/sys_ni.c`` + + +x86 System Call Implementation +------------------------------ + +To wire up your new system call for x86 platforms, you need to update the +master syscall tables. Assuming your new system call isn't special in some +way (see below), this involves a "common" entry (for x86_64 and x32) in +arch/x86/entry/syscalls/syscall_64.tbl:: + + 333 common xyzzy sys_xyzzy + +and an "i386" entry in ``arch/x86/entry/syscalls/syscall_32.tbl``:: + + 380 i386 xyzzy sys_xyzzy + +Again, these numbers are liable to be changed if there are conflicts in the +relevant merge window. + + +Compatibility System Calls (Generic) +------------------------------------ + +For most system calls the same 64-bit implementation can be invoked even when +the userspace program is itself 32-bit; even if the system call's parameters +include an explicit pointer, this is handled transparently. + +However, there are a couple of situations where a compatibility layer is +needed to cope with size differences between 32-bit and 64-bit. + +The first is if the 64-bit kernel also supports 32-bit userspace programs, and +so needs to parse areas of (``__user``) memory that could hold either 32-bit or +64-bit values. In particular, this is needed whenever a system call argument +is: + + - a pointer to a pointer + - a pointer to a struct containing a pointer (e.g. ``struct iovec __user *``) + - a pointer to a varying sized integral type (``time_t``, ``off_t``, + ``long``, ...) + - a pointer to a struct containing a varying sized integral type. + +The second situation that requires a compatibility layer is if one of the +system call's arguments has a type that is explicitly 64-bit even on a 32-bit +architecture, for example ``loff_t`` or ``__u64``. In this case, a value that +arrives at a 64-bit kernel from a 32-bit application will be split into two +32-bit values, which then need to be re-assembled in the compatibility layer. + +(Note that a system call argument that's a pointer to an explicit 64-bit type +does **not** need a compatibility layer; for example, :manpage:`splice(2)`'s arguments of +type ``loff_t __user *`` do not trigger the need for a ``compat_`` system call.) + +The compatibility version of the system call is called ``compat_sys_xyzzy()``, +and is added with the ``COMPAT_SYSCALL_DEFINEn()`` macro, analogously to +SYSCALL_DEFINEn. This version of the implementation runs as part of a 64-bit +kernel, but expects to receive 32-bit parameter values and does whatever is +needed to deal with them. (Typically, the ``compat_sys_`` version converts the +values to 64-bit versions and either calls on to the ``sys_`` version, or both of +them call a common inner implementation function.) + +The compat entry point also needs a corresponding function prototype, in +``include/linux/compat.h``, marked as asmlinkage to match the way that system +calls are invoked:: + + asmlinkage long compat_sys_xyzzy(...); + +If the system call involves a structure that is laid out differently on 32-bit +and 64-bit systems, say ``struct xyzzy_args``, then the include/linux/compat.h +header file should also include a compat version of the structure (``struct +compat_xyzzy_args``) where each variable-size field has the appropriate +``compat_`` type that corresponds to the type in ``struct xyzzy_args``. The +``compat_sys_xyzzy()`` routine can then use this ``compat_`` structure to +parse the arguments from a 32-bit invocation. + +For example, if there are fields:: + + struct xyzzy_args { + const char __user *ptr; + __kernel_long_t varying_val; + u64 fixed_val; + /* ... */ + }; + +in struct xyzzy_args, then struct compat_xyzzy_args would have:: + + struct compat_xyzzy_args { + compat_uptr_t ptr; + compat_long_t varying_val; + u64 fixed_val; + /* ... */ + }; + +The generic system call list also needs adjusting to allow for the compat +version; the entry in ``include/uapi/asm-generic/unistd.h`` should use +``__SC_COMP`` rather than ``__SYSCALL``:: + + #define __NR_xyzzy 292 + __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy) + +To summarize, you need: + + - a ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` for the compat entry point + - corresponding prototype in ``include/linux/compat.h`` + - (if needed) 32-bit mapping struct in ``include/linux/compat.h`` + - instance of ``__SC_COMP`` not ``__SYSCALL`` in + ``include/uapi/asm-generic/unistd.h`` + + +Compatibility System Calls (x86) +-------------------------------- + +To wire up the x86 architecture of a system call with a compatibility version, +the entries in the syscall tables need to be adjusted. + +First, the entry in ``arch/x86/entry/syscalls/syscall_32.tbl`` gets an extra +column to indicate that a 32-bit userspace program running on a 64-bit kernel +should hit the compat entry point:: + + 380 i386 xyzzy sys_xyzzy compat_sys_xyzzy + +Second, you need to figure out what should happen for the x32 ABI version of +the new system call. There's a choice here: the layout of the arguments +should either match the 64-bit version or the 32-bit version. + +If there's a pointer-to-a-pointer involved, the decision is easy: x32 is +ILP32, so the layout should match the 32-bit version, and the entry in +``arch/x86/entry/syscalls/syscall_64.tbl`` is split so that x32 programs hit +the compatibility wrapper:: + + 333 64 xyzzy sys_xyzzy + ... + 555 x32 xyzzy compat_sys_xyzzy + +If no pointers are involved, then it is preferable to re-use the 64-bit system +call for the x32 ABI (and consequently the entry in +arch/x86/entry/syscalls/syscall_64.tbl is unchanged). + +In either case, you should check that the types involved in your argument +layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or +64-bit (-m64) equivalents. + + +System Calls Returning Elsewhere +-------------------------------- + +For most system calls, once the system call is complete the user program +continues exactly where it left off -- at the next instruction, with the +stack the same and most of the registers the same as before the system call, +and with the same virtual memory space. + +However, a few system calls do things differently. They might return to a +different location (``rt_sigreturn``) or change the memory space +(``fork``/``vfork``/``clone``) or even architecture (``execve``/``execveat``) +of the program. + +To allow for this, the kernel implementation of the system call may need to +save and restore additional registers to the kernel stack, allowing complete +control of where and how execution continues after the system call. + +This is arch-specific, but typically involves defining assembly entry points +that save/restore additional registers and invoke the real system call entry +point. + +For x86_64, this is implemented as a ``stub_xyzzy`` entry point in +``arch/x86/entry/entry_64.S``, and the entry in the syscall table +(``arch/x86/entry/syscalls/syscall_64.tbl``) is adjusted to match:: + + 333 common xyzzy stub_xyzzy + +The equivalent for 32-bit programs running on a 64-bit kernel is normally +called ``stub32_xyzzy`` and implemented in ``arch/x86/entry/entry_64_compat.S``, +with the corresponding syscall table adjustment in +``arch/x86/entry/syscalls/syscall_32.tbl``:: + + 380 i386 xyzzy sys_xyzzy stub32_xyzzy + +If the system call needs a compatibility layer (as in the previous section) +then the ``stub32_`` version needs to call on to the ``compat_sys_`` version +of the system call rather than the native 64-bit version. Also, if the x32 ABI +implementation is not common with the x86_64 version, then its syscall +table will also need to invoke a stub that calls on to the ``compat_sys_`` +version. + +For completeness, it's also nice to set up a mapping so that user-mode Linux +still works -- its syscall table will reference stub_xyzzy, but the UML build +doesn't include ``arch/x86/entry/entry_64.S`` implementation (because UML +simulates registers etc). Fixing this is as simple as adding a #define to +``arch/x86/um/sys_call_table_64.c``:: + + #define stub_xyzzy sys_xyzzy + + +Other Details +------------- + +Most of the kernel treats system calls in a generic way, but there is the +occasional exception that may need updating for your particular system call. + +The audit subsystem is one such special case; it includes (arch-specific) +functions that classify some special types of system call -- specifically +file open (``open``/``openat``), program execution (``execve``/``exeveat``) or +socket multiplexor (``socketcall``) operations. If your new system call is +analogous to one of these, then the audit system should be updated. + +More generally, if there is an existing system call that is analogous to your +new system call, it's worth doing a kernel-wide grep for the existing system +call to check there are no other special cases. + + +Testing +------- + +A new system call should obviously be tested; it is also useful to provide +reviewers with a demonstration of how user space programs will use the system +call. A good way to combine these aims is to include a simple self-test +program in a new directory under ``tools/testing/selftests/``. + +For a new system call, there will obviously be no libc wrapper function and so +the test will need to invoke it using ``syscall()``; also, if the system call +involves a new userspace-visible structure, the corresponding header will need +to be installed to compile the test. + +Make sure the selftest runs successfully on all supported architectures. For +example, check that it works when compiled as an x86_64 (-m64), x86_32 (-m32) +and x32 (-mx32) ABI program. + +For more extensive and thorough testing of new functionality, you should also +consider adding tests to the Linux Test Project, or to the xfstests project +for filesystem-related changes. + + - https://linux-test-project.github.io/ + - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git + + +Man Page +-------- + +All new system calls should come with a complete man page, ideally using groff +markup, but plain text will do. If groff is used, it's helpful to include a +pre-rendered ASCII version of the man page in the cover email for the +patchset, for the convenience of reviewers. + +The man page should be cc'ed to linux-man@vger.kernel.org +For more details, see https://www.kernel.org/doc/man-pages/patches.html + +References and Sources +---------------------- + + - LWN article from Michael Kerrisk on use of flags argument in system calls: + https://lwn.net/Articles/585415/ + - LWN article from Michael Kerrisk on how to handle unknown flags in a system + call: https://lwn.net/Articles/588444/ + - LWN article from Jake Edge describing constraints on 64-bit system call + arguments: https://lwn.net/Articles/311630/ + - Pair of LWN articles from David Drysdale that describe the system call + implementation paths in detail for v3.14: + + - https://lwn.net/Articles/604287/ + - https://lwn.net/Articles/604515/ + + - Architecture-specific requirements for system calls are discussed in the + :manpage:`syscall(2)` man-page: + http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES + - Collated emails from Linus Torvalds discussing the problems with ``ioctl()``: + http://yarchive.net/comp/linux/ioctl.html + - "How to not invent kernel interfaces", Arnd Bergmann, + http://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf + - LWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN: + https://lwn.net/Articles/486306/ + - Recommendation from Andrew Morton that all related information for a new + system call should come in the same email thread: + https://lkml.org/lkml/2014/7/24/641 + - Recommendation from Michael Kerrisk that a new system call should come with + a man page: https://lkml.org/lkml/2014/6/13/309 + - Suggestion from Thomas Gleixner that x86 wire-up should be in a separate + commit: https://lkml.org/lkml/2014/11/19/254 + - Suggestion from Greg Kroah-Hartman that it's good for new system calls to + come with a man-page & selftest: https://lkml.org/lkml/2014/3/19/710 + - Discussion from Michael Kerrisk of new system call vs. :manpage:`prctl(2)` extension: + https://lkml.org/lkml/2014/6/3/411 + - Suggestion from Ingo Molnar that system calls that involve multiple + arguments should encapsulate those arguments in a struct, which includes a + size field for future extensibility: https://lkml.org/lkml/2015/7/30/117 + - Numbering oddities arising from (re-)use of O_* numbering space flags: + + - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness + check") + - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc + conflict") + - commit bb458c644a59 ("Safer ABI for O_TMPFILE") + + - Discussion from Matthew Wilcox about restrictions on 64-bit arguments: + https://lkml.org/lkml/2008/12/12/187 + - Recommendation from Greg Kroah-Hartman that unknown flags should be + policed: https://lkml.org/lkml/2014/7/17/577 + - Recommendation from Linus Torvalds that x32 system calls should prefer + compatibility with 64-bit versions rather than 32-bit versions: + https://lkml.org/lkml/2011/8/31/244 diff --git a/Documentation/process/applying-patches.rst b/Documentation/process/applying-patches.rst new file mode 100644 index 000000000000..abd7dc7ae240 --- /dev/null +++ b/Documentation/process/applying-patches.rst @@ -0,0 +1,464 @@ +.. _applying_patches: + +Applying Patches To The Linux Kernel +++++++++++++++++++++++++++++++++++++ + +Original by: + Jesper Juhl, August 2005 + +Last update: + 2016-09-14 + + +A frequently asked question on the Linux Kernel Mailing List is how to apply +a patch to the kernel or, more specifically, what base kernel a patch for +one of the many trees/branches should be applied to. Hopefully this document +will explain this to you. + +In addition to explaining how to apply and revert patches, a brief +description of the different kernel trees (and examples of how to apply +their specific patches) is also provided. + + +What is a patch? +================ + +A patch is a small text document containing a delta of changes between two +different versions of a source tree. Patches are created with the ``diff`` +program. + +To correctly apply a patch you need to know what base it was generated from +and what new version the patch will change the source tree into. These +should both be present in the patch file metadata or be possible to deduce +from the filename. + + +How do I apply or revert a patch? +================================= + +You apply a patch with the ``patch`` program. The patch program reads a diff +(or patch) file and makes the changes to the source tree described in it. + +Patches for the Linux kernel are generated relative to the parent directory +holding the kernel source dir. + +This means that paths to files inside the patch file contain the name of the +kernel source directories it was generated against (or some other directory +names like "a/" and "b/"). + +Since this is unlikely to match the name of the kernel source dir on your +local machine (but is often useful info to see what version an otherwise +unlabeled patch was generated against) you should change into your kernel +source directory and then strip the first element of the path from filenames +in the patch file when applying it (the ``-p1`` argument to ``patch`` does +this). + +To revert a previously applied patch, use the -R argument to patch. +So, if you applied a patch like this:: + + patch -p1 < ../patch-x.y.z + +You can revert (undo) it like this:: + + patch -R -p1 < ../patch-x.y.z + + +How do I feed a patch/diff file to ``patch``? +============================================= + +This (as usual with Linux and other UNIX like operating systems) can be +done in several different ways. + +In all the examples below I feed the file (in uncompressed form) to patch +via stdin using the following syntax:: + + patch -p1 < path/to/patch-x.y.z + +If you just want to be able to follow the examples below and don't want to +know of more than one way to use patch, then you can stop reading this +section here. + +Patch can also get the name of the file to use via the -i argument, like +this:: + + patch -p1 -i path/to/patch-x.y.z + +If your patch file is compressed with gzip or xz and you don't want to +uncompress it before applying it, then you can feed it to patch like this +instead:: + + xzcat path/to/patch-x.y.z.xz | patch -p1 + bzcat path/to/patch-x.y.z.gz | patch -p1 + +If you wish to uncompress the patch file by hand first before applying it +(what I assume you've done in the examples below), then you simply run +gunzip or xz on the file -- like this:: + + gunzip patch-x.y.z.gz + xz -d patch-x.y.z.xz + +Which will leave you with a plain text patch-x.y.z file that you can feed to +patch via stdin or the ``-i`` argument, as you prefer. + +A few other nice arguments for patch are ``-s`` which causes patch to be silent +except for errors which is nice to prevent errors from scrolling out of the +screen too fast, and ``--dry-run`` which causes patch to just print a listing of +what would happen, but doesn't actually make any changes. Finally ``--verbose`` +tells patch to print more information about the work being done. + + +Common errors when patching +=========================== + +When patch applies a patch file it attempts to verify the sanity of the +file in different ways. + +Checking that the file looks like a valid patch file and checking the code +around the bits being modified matches the context provided in the patch are +just two of the basic sanity checks patch does. + +If patch encounters something that doesn't look quite right it has two +options. It can either refuse to apply the changes and abort or it can try +to find a way to make the patch apply with a few minor changes. + +One example of something that's not 'quite right' that patch will attempt to +fix up is if all the context matches, the lines being changed match, but the +line numbers are different. This can happen, for example, if the patch makes +a change in the middle of the file but for some reasons a few lines have +been added or removed near the beginning of the file. In that case +everything looks good it has just moved up or down a bit, and patch will +usually adjust the line numbers and apply the patch. + +Whenever patch applies a patch that it had to modify a bit to make it fit +it'll tell you about it by saying the patch applied with **fuzz**. +You should be wary of such changes since even though patch probably got it +right it doesn't /always/ get it right, and the result will sometimes be +wrong. + +When patch encounters a change that it can't fix up with fuzz it rejects it +outright and leaves a file with a ``.rej`` extension (a reject file). You can +read this file to see exactly what change couldn't be applied, so you can +go fix it up by hand if you wish. + +If you don't have any third-party patches applied to your kernel source, but +only patches from kernel.org and you apply the patches in the correct order, +and have made no modifications yourself to the source files, then you should +never see a fuzz or reject message from patch. If you do see such messages +anyway, then there's a high risk that either your local source tree or the +patch file is corrupted in some way. In that case you should probably try +re-downloading the patch and if things are still not OK then you'd be advised +to start with a fresh tree downloaded in full from kernel.org. + +Let's look a bit more at some of the messages patch can produce. + +If patch stops and presents a ``File to patch:`` prompt, then patch could not +find a file to be patched. Most likely you forgot to specify -p1 or you are +in the wrong directory. Less often, you'll find patches that need to be +applied with ``-p0`` instead of ``-p1`` (reading the patch file should reveal if +this is the case -- if so, then this is an error by the person who created +the patch but is not fatal). + +If you get ``Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines).`` or a +message similar to that, then it means that patch had to adjust the location +of the change (in this example it needed to move 7 lines from where it +expected to make the change to make it fit). + +The resulting file may or may not be OK, depending on the reason the file +was different than expected. + +This often happens if you try to apply a patch that was generated against a +different kernel version than the one you are trying to patch. + +If you get a message like ``Hunk #3 FAILED at 2387.``, then it means that the +patch could not be applied correctly and the patch program was unable to +fuzz its way through. This will generate a ``.rej`` file with the change that +caused the patch to fail and also a ``.orig`` file showing you the original +content that couldn't be changed. + +If you get ``Reversed (or previously applied) patch detected! Assume -R? [n]`` +then patch detected that the change contained in the patch seems to have +already been made. + +If you actually did apply this patch previously and you just re-applied it +in error, then just say [n]o and abort this patch. If you applied this patch +previously and actually intended to revert it, but forgot to specify -R, +then you can say [**y**]es here to make patch revert it for you. + +This can also happen if the creator of the patch reversed the source and +destination directories when creating the patch, and in that case reverting +the patch will in fact apply it. + +A message similar to ``patch: **** unexpected end of file in patch`` or +``patch unexpectedly ends in middle of line`` means that patch could make no +sense of the file you fed to it. Either your download is broken, you tried to +feed patch a compressed patch file without uncompressing it first, or the patch +file that you are using has been mangled by a mail client or mail transfer +agent along the way somewhere, e.g., by splitting a long line into two lines. +Often these warnings can easily be fixed by joining (concatenating) the +two lines that had been split. + +As I already mentioned above, these errors should never happen if you apply +a patch from kernel.org to the correct version of an unmodified source tree. +So if you get these errors with kernel.org patches then you should probably +assume that either your patch file or your tree is broken and I'd advise you +to start over with a fresh download of a full kernel tree and the patch you +wish to apply. + + +Are there any alternatives to ``patch``? +======================================== + + +Yes there are alternatives. + +You can use the ``interdiff`` program (http://cyberelk.net/tim/patchutils/) to +generate a patch representing the differences between two patches and then +apply the result. + +This will let you move from something like 4.7.2 to 4.7.3 in a single +step. The -z flag to interdiff will even let you feed it patches in gzip or +bzip2 compressed form directly without the use of zcat or bzcat or manual +decompression. + +Here's how you'd go from 4.7.2 to 4.7.3 in a single step:: + + interdiff -z ../patch-4.7.2.gz ../patch-4.7.3.gz | patch -p1 + +Although interdiff may save you a step or two you are generally advised to +do the additional steps since interdiff can get things wrong in some cases. + +Another alternative is ``ketchup``, which is a python script for automatic +downloading and applying of patches (http://www.selenic.com/ketchup/). + +Other nice tools are diffstat, which shows a summary of changes made by a +patch; lsdiff, which displays a short listing of affected files in a patch +file, along with (optionally) the line numbers of the start of each patch; +and grepdiff, which displays a list of the files modified by a patch where +the patch contains a given regular expression. + + +Where can I download the patches? +================================= + +The patches are available at http://kernel.org/ +Most recent patches are linked from the front page, but they also have +specific homes. + +The 4.x.y (-stable) and 4.x patches live at + + ftp://ftp.kernel.org/pub/linux/kernel/v4.x/ + +The -rc patches live at + + ftp://ftp.kernel.org/pub/linux/kernel/v4.x/testing/ + +In place of ``ftp.kernel.org`` you can use ``ftp.cc.kernel.org``, where cc is a +country code. This way you'll be downloading from a mirror site that's most +likely geographically closer to you, resulting in faster downloads for you, +less bandwidth used globally and less load on the main kernel.org servers -- +these are good things, so do use mirrors when possible. + + +The 4.x kernels +=============== + +These are the base stable releases released by Linus. The highest numbered +release is the most recent. + +If regressions or other serious flaws are found, then a -stable fix patch +will be released (see below) on top of this base. Once a new 4.x base +kernel is released, a patch is made available that is a delta between the +previous 4.x kernel and the new one. + +To apply a patch moving from 4.6 to 4.7, you'd do the following (note +that such patches do **NOT** apply on top of 4.x.y kernels but on top of the +base 4.x kernel -- if you need to move from 4.x.y to 4.x+1 you need to +first revert the 4.x.y patch). + +Here are some examples:: + + # moving from 4.6 to 4.7 + + $ cd ~/linux-4.6 # change to kernel source dir + $ patch -p1 < ../patch-4.7 # apply the 4.7 patch + $ cd .. + $ mv linux-4.6 linux-4.7 # rename source dir + + # moving from 4.6.1 to 4.7 + + $ cd ~/linux-4.6.1 # change to kernel source dir + $ patch -p1 -R < ../patch-4.6.1 # revert the 4.6.1 patch + # source dir is now 4.6 + $ patch -p1 < ../patch-4.7 # apply new 4.7 patch + $ cd .. + $ mv linux-4.6.1 linux-4.7 # rename source dir + + +The 4.x.y kernels +================= + +Kernels with 3-digit versions are -stable kernels. They contain small(ish) +critical fixes for security problems or significant regressions discovered +in a given 4.x kernel. + +This is the recommended branch for users who want the most recent stable +kernel and are not interested in helping test development/experimental +versions. + +If no 4.x.y kernel is available, then the highest numbered 4.x kernel is +the current stable kernel. + +.. note:: + + The -stable team usually do make incremental patches available as well + as patches against the latest mainline release, but I only cover the + non-incremental ones below. The incremental ones can be found at + ftp://ftp.kernel.org/pub/linux/kernel/v4.x/incr/ + +These patches are not incremental, meaning that for example the 4.7.3 +patch does not apply on top of the 4.7.2 kernel source, but rather on top +of the base 4.7 kernel source. + +So, in order to apply the 4.7.3 patch to your existing 4.7.2 kernel +source you have to first back out the 4.7.2 patch (so you are left with a +base 4.7 kernel source) and then apply the new 4.7.3 patch. + +Here's a small example:: + + $ cd ~/linux-4.7.2 # change to the kernel source dir + $ patch -p1 -R < ../patch-4.7.2 # revert the 4.7.2 patch + $ patch -p1 < ../patch-4.7.3 # apply the new 4.7.3 patch + $ cd .. + $ mv linux-4.7.2 linux-4.7.3 # rename the kernel source dir + +The -rc kernels +=============== + +These are release-candidate kernels. These are development kernels released +by Linus whenever he deems the current git (the kernel's source management +tool) tree to be in a reasonably sane state adequate for testing. + +These kernels are not stable and you should expect occasional breakage if +you intend to run them. This is however the most stable of the main +development branches and is also what will eventually turn into the next +stable kernel, so it is important that it be tested by as many people as +possible. + +This is a good branch to run for people who want to help out testing +development kernels but do not want to run some of the really experimental +stuff (such people should see the sections about -git and -mm kernels below). + +The -rc patches are not incremental, they apply to a base 4.x kernel, just +like the 4.x.y patches described above. The kernel version before the -rcN +suffix denotes the version of the kernel that this -rc kernel will eventually +turn into. + +So, 4.8-rc5 means that this is the fifth release candidate for the 4.8 +kernel and the patch should be applied on top of the 4.7 kernel source. + +Here are 3 examples of how to apply these patches:: + + # first an example of moving from 4.7 to 4.8-rc3 + + $ cd ~/linux-4.7 # change to the 4.7 source dir + $ patch -p1 < ../patch-4.8-rc3 # apply the 4.8-rc3 patch + $ cd .. + $ mv linux-4.7 linux-4.8-rc3 # rename the source dir + + # now let's move from 4.8-rc3 to 4.8-rc5 + + $ cd ~/linux-4.8-rc3 # change to the 4.8-rc3 dir + $ patch -p1 -R < ../patch-4.8-rc3 # revert the 4.8-rc3 patch + $ patch -p1 < ../patch-4.8-rc5 # apply the new 4.8-rc5 patch + $ cd .. + $ mv linux-4.8-rc3 linux-4.8-rc5 # rename the source dir + + # finally let's try and move from 4.7.3 to 4.8-rc5 + + $ cd ~/linux-4.7.3 # change to the kernel source dir + $ patch -p1 -R < ../patch-4.7.3 # revert the 4.7.3 patch + $ patch -p1 < ../patch-4.8-rc5 # apply new 4.8-rc5 patch + $ cd .. + $ mv linux-4.7.3 linux-4.8-rc5 # rename the kernel source dir + + +The -git kernels +================ + +These are daily snapshots of Linus' kernel tree (managed in a git +repository, hence the name). + +These patches are usually released daily and represent the current state of +Linus's tree. They are more experimental than -rc kernels since they are +generated automatically without even a cursory glance to see if they are +sane. + +-git patches are not incremental and apply either to a base 4.x kernel or +a base 4.x-rc kernel -- you can see which from their name. +A patch named 4.7-git1 applies to the 4.7 kernel source and a patch +named 4.8-rc3-git2 applies to the source of the 4.8-rc3 kernel. + +Here are some examples of how to apply these patches:: + + # moving from 4.7 to 4.7-git1 + + $ cd ~/linux-4.7 # change to the kernel source dir + $ patch -p1 < ../patch-4.7-git1 # apply the 4.7-git1 patch + $ cd .. + $ mv linux-4.7 linux-4.7-git1 # rename the kernel source dir + + # moving from 4.7-git1 to 4.8-rc2-git3 + + $ cd ~/linux-4.7-git1 # change to the kernel source dir + $ patch -p1 -R < ../patch-4.7-git1 # revert the 4.7-git1 patch + # we now have a 4.7 kernel + $ patch -p1 < ../patch-4.8-rc2 # apply the 4.8-rc2 patch + # the kernel is now 4.8-rc2 + $ patch -p1 < ../patch-4.8-rc2-git3 # apply the 4.8-rc2-git3 patch + # the kernel is now 4.8-rc2-git3 + $ cd .. + $ mv linux-4.7-git1 linux-4.8-rc2-git3 # rename source dir + + +The -mm patches and the linux-next tree +======================================= + +The -mm patches are experimental patches released by Andrew Morton. + +In the past, -mm tree were used to also test subsystem patches, but this +function is now done via the +`linux-next ` +tree. The Subsystem maintainers push their patches first to linux-next, +and, during the merge window, sends them directly to Linus. + +The -mm patches serve as a sort of proving ground for new features and other +experimental patches that aren't merged via a subsystem tree. +Once such patches has proved its worth in -mm for a while Andrew pushes +it on to Linus for inclusion in mainline. + +The linux-next tree is daily updated, and includes the -mm patches. +Both are in constant flux and contains many experimental features, a +lot of debugging patches not appropriate for mainline etc., and is the most +experimental of the branches described in this document. + +These patches are not appropriate for use on systems that are supposed to be +stable and they are more risky to run than any of the other branches (make +sure you have up-to-date backups -- that goes for any experimental kernel but +even more so for -mm patches or using a Kernel from the linux-next tree). + +Testing of -mm patches and linux-next is greatly appreciated since the whole +point of those are to weed out regressions, crashes, data corruption bugs, +build breakage (and any other bug in general) before changes are merged into +the more stable mainline Linus tree. + +But testers of -mm and linux-next should be aware that breakages are +more common than in any other tree. + + +This concludes this list of explanations of the various kernel trees. +I hope you are now clear on how to apply the various patches and help testing +the kernel. + +Thank you's to Randy Dunlap, Rolf Eike Beer, Linus Torvalds, Bodo Eggert, +Johannes Stezenbach, Grant Coady, Pavel Machek and others that I may have +forgotten for their reviews and contributions to this document. diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst new file mode 100644 index 000000000000..22797a15dc24 --- /dev/null +++ b/Documentation/process/changes.rst @@ -0,0 +1,485 @@ +.. _changes: + +Minimal requerements to compile the Kernel +++++++++++++++++++++++++++++++++++++++++++ + +Intro +===== + +This document is designed to provide a list of the minimum levels of +software necessary to run the 4.x kernels. + +This document is originally based on my "Changes" file for 2.0.x kernels +and therefore owes credit to the same people as that file (Jared Mauch, +Axel Boldt, Alessandro Sigala, and countless other users all over the +'net). + +Current Minimal Requirements +**************************** + +Upgrade to at **least** these software revisions before thinking you've +encountered a bug! If you're unsure what version you're currently +running, the suggested command should tell you. + +Again, keep in mind that this list assumes you are already functionally +running a Linux kernel. Also, not all tools are necessary on all +systems; obviously, if you don't have any ISDN hardware, for example, +you probably needn't concern yourself with isdn4k-utils. + +====================== =============== ======================================== + Program Minimal version Command to check the version +====================== =============== ======================================== +GNU C 3.2 gcc --version +GNU make 3.80 make --version +binutils 2.12 ld -v +util-linux 2.10o fdformat --version +module-init-tools 0.9.10 depmod -V +e2fsprogs 1.41.4 e2fsck -V +jfsutils 1.1.3 fsck.jfs -V +reiserfsprogs 3.6.3 reiserfsck -V +xfsprogs 2.6.0 xfs_db -V +squashfs-tools 4.0 mksquashfs -version +btrfs-progs 0.18 btrfsck +pcmciautils 004 pccardctl -V +quota-tools 3.09 quota -V +PPP 2.4.0 pppd --version +isdn4k-utils 3.1pre1 isdnctrl 2>&1|grep version +nfs-utils 1.0.5 showmount --version +procps 3.2.0 ps --version +oprofile 0.9 oprofiled --version +udev 081 udevd --version +grub 0.93 grub --version || grub-install --version +mcelog 0.6 mcelog --version +iptables 1.4.2 iptables -V +openssl & libcrypto 1.0.0 openssl version +bc 1.06.95 bc --version +Sphinx\ [#f1]_ 1.2 sphinx-build --version +====================== =============== ======================================== + +.. [#f1] Sphinx is needed only to build the Kernel documentation + +Kernel compilation +****************** + +GCC +--- + +The gcc version requirements may vary depending on the type of CPU in your +computer. + +Make +---- + +You will need GNU make 3.80 or later to build the kernel. + +Binutils +-------- + +Linux on IA-32 has recently switched from using ``as86`` to using ``gas`` for +assembling the 16-bit boot code, removing the need for ``as86`` to compile +your kernel. This change does, however, mean that you need a recent +release of binutils. + +Perl +---- + +You will need perl 5 and the following modules: ``Getopt::Long``, +``Getopt::Std``, ``File::Basename``, and ``File::Find`` to build the kernel. + +BC +-- + +You will need bc to build kernels 3.10 and higher + + +OpenSSL +------- + +Module signing and external certificate handling use the OpenSSL program and +crypto library to do key creation and signature generation. + +You will need openssl to build kernels 3.7 and higher if module signing is +enabled. You will also need openssl development packages to build kernels 4.3 +and higher. + + +System utilities +**************** + +Architectural changes +--------------------- + +DevFS has been obsoleted in favour of udev +(http://www.kernel.org/pub/linux/utils/kernel/hotplug/) + +32-bit UID support is now in place. Have fun! + +Linux documentation for functions is transitioning to inline +documentation via specially-formatted comments near their +definitions in the source. These comments can be combined with the +SGML templates in the Documentation/DocBook directory to make DocBook +files, which can then be converted by DocBook stylesheets to PostScript, +HTML, PDF files, and several other formats. In order to convert from +DocBook format to a format of your choice, you'll need to install Jade as +well as the desired DocBook stylesheets. + +Util-linux +---------- + +New versions of util-linux provide ``fdisk`` support for larger disks, +support new options to mount, recognize more supported partition +types, have a fdformat which works with 2.4 kernels, and similar goodies. +You'll probably want to upgrade. + +Ksymoops +-------- + +If the unthinkable happens and your kernel oopses, you may need the +ksymoops tool to decode it, but in most cases you don't. +It is generally preferred to build the kernel with ``CONFIG_KALLSYMS`` so +that it produces readable dumps that can be used as-is (this also +produces better output than ksymoops). If for some reason your kernel +is not build with ``CONFIG_KALLSYMS`` and you have no way to rebuild and +reproduce the Oops with that option, then you can still decode that Oops +with ksymoops. + +Module-Init-Tools +----------------- + +A new module loader is now in the kernel that requires ``module-init-tools`` +to use. It is backward compatible with the 2.4.x series kernels. + +Mkinitrd +-------- + +These changes to the ``/lib/modules`` file tree layout also require that +mkinitrd be upgraded. + +E2fsprogs +--------- + +The latest version of ``e2fsprogs`` fixes several bugs in fsck and +debugfs. Obviously, it's a good idea to upgrade. + +JFSutils +-------- + +The ``jfsutils`` package contains the utilities for the file system. +The following utilities are available: + +- ``fsck.jfs`` - initiate replay of the transaction log, and check + and repair a JFS formatted partition. + +- ``mkfs.jfs`` - create a JFS formatted partition. + +- other file system utilities are also available in this package. + +Reiserfsprogs +------------- + +The reiserfsprogs package should be used for reiserfs-3.6.x +(Linux kernels 2.4.x). It is a combined package and contains working +versions of ``mkreiserfs``, ``resize_reiserfs``, ``debugreiserfs`` and +``reiserfsck``. These utils work on both i386 and alpha platforms. + +Xfsprogs +-------- + +The latest version of ``xfsprogs`` contains ``mkfs.xfs``, ``xfs_db``, and the +``xfs_repair`` utilities, among others, for the XFS filesystem. It is +architecture independent and any version from 2.0.0 onward should +work correctly with this version of the XFS kernel code (2.6.0 or +later is recommended, due to some significant improvements). + +PCMCIAutils +----------- + +PCMCIAutils replaces ``pcmcia-cs``. It properly sets up +PCMCIA sockets at system startup and loads the appropriate modules +for 16-bit PCMCIA devices if the kernel is modularized and the hotplug +subsystem is used. + +Quota-tools +----------- + +Support for 32 bit uid's and gid's is required if you want to use +the newer version 2 quota format. Quota-tools version 3.07 and +newer has this support. Use the recommended version or newer +from the table above. + +Intel IA32 microcode +-------------------- + +A driver has been added to allow updating of Intel IA32 microcode, +accessible as a normal (misc) character device. If you are not using +udev you may need to:: + + mkdir /dev/cpu + mknod /dev/cpu/microcode c 10 184 + chmod 0644 /dev/cpu/microcode + +as root before you can use this. You'll probably also want to +get the user-space microcode_ctl utility to use with this. + +udev +---- + +``udev`` is a userspace application for populating ``/dev`` dynamically with +only entries for devices actually present. ``udev`` replaces the basic +functionality of devfs, while allowing persistent device naming for +devices. + +FUSE +---- + +Needs libfuse 2.4.0 or later. Absolute minimum is 2.3.0 but mount +options ``direct_io`` and ``kernel_cache`` won't work. + +Networking +********** + +General changes +--------------- + +If you have advanced network configuration needs, you should probably +consider using the network tools from ip-route2. + +Packet Filter / NAT +------------------- +The packet filtering and NAT code uses the same tools like the previous 2.4.x +kernel series (iptables). It still includes backwards-compatibility modules +for 2.2.x-style ipchains and 2.0.x-style ipfwadm. + +PPP +--- + +The PPP driver has been restructured to support multilink and to +enable it to operate over diverse media layers. If you use PPP, +upgrade pppd to at least 2.4.0. + +If you are not using udev, you must have the device file /dev/ppp +which can be made by:: + + mknod /dev/ppp c 108 0 + +as root. + +Isdn4k-utils +------------ + +Due to changes in the length of the phone number field, isdn4k-utils +needs to be recompiled or (preferably) upgraded. + +NFS-utils +--------- + +In ancient (2.4 and earlier) kernels, the nfs server needed to know +about any client that expected to be able to access files via NFS. This +information would be given to the kernel by ``mountd`` when the client +mounted the filesystem, or by ``exportfs`` at system startup. exportfs +would take information about active clients from ``/var/lib/nfs/rmtab``. + +This approach is quite fragile as it depends on rmtab being correct +which is not always easy, particularly when trying to implement +fail-over. Even when the system is working well, ``rmtab`` suffers from +getting lots of old entries that never get removed. + +With modern kernels we have the option of having the kernel tell mountd +when it gets a request from an unknown host, and mountd can give +appropriate export information to the kernel. This removes the +dependency on ``rmtab`` and means that the kernel only needs to know about +currently active clients. + +To enable this new functionality, you need to:: + + mount -t nfsd nfsd /proc/fs/nfsd + +before running exportfs or mountd. It is recommended that all NFS +services be protected from the internet-at-large by a firewall where +that is possible. + +mcelog +------ + +On x86 kernels the mcelog utility is needed to process and log machine check +events when ``CONFIG_X86_MCE`` is enabled. Machine check events are errors +reported by the CPU. Processing them is strongly encouraged. + +Kernel documentation +******************** + +Sphinx +------ + +The ReST markups currently used by the Documentation/ files are meant to be +built with ``Sphinx`` version 1.2 or upper. If you're desiring to build +PDF outputs, it is recommended to use version 1.4.6. + +.. note:: + + Please notice that, for PDF and LaTeX output, you'll also need ``XeLaTeX`` + version 3.14159265. Depending on the distribution, you may also need + to install a series of ``texlive`` packages that provide the minimal + set of functionalities required for ``XeLaTex`` to work. + +Other tools +----------- + +In order to produce documentation from DocBook, you'll also need ``xmlto``. +Please notice, however, that we're currently migrating all documents to use +``Sphinx``. + +Getting updated software +======================== + +Kernel compilation +****************** + +gcc +--- + +- + +Make +---- + +- + +Binutils +-------- + +- + +OpenSSL +------- + +- + +System utilities +**************** + +Util-linux +---------- + +- + +Ksymoops +-------- + +- + +Module-Init-Tools +----------------- + +- + +Mkinitrd +-------- + +- + +E2fsprogs +--------- + +- + +JFSutils +-------- + +- + +Reiserfsprogs +------------- + +- + +Xfsprogs +-------- + +- + +Pcmciautils +----------- + +- + +Quota-tools +----------- + +- + +DocBook Stylesheets +------------------- + +- + +XMLTO XSLT Frontend +------------------- + +- + +Intel P6 microcode +------------------ + +- + +udev +---- + +- + +FUSE +---- + +- + +mcelog +------ + +- + +Networking +********** + +PPP +--- + +- + +Isdn4k-utils +------------ + +- + +NFS-utils +--------- + +- + +Iptables +-------- + +- + +Ip-route2 +--------- + +- + +OProfile +-------- + +- + +NFS-Utils +--------- + +- + +Kernel documentation +******************** + +Sphinx +------ + +- diff --git a/Documentation/process/code-of-conflict.rst b/Documentation/process/code-of-conflict.rst new file mode 100644 index 000000000000..47b6de763203 --- /dev/null +++ b/Documentation/process/code-of-conflict.rst @@ -0,0 +1,28 @@ +Code of Conflict +---------------- + +The Linux kernel development effort is a very personal process compared +to "traditional" ways of developing software. Your code and ideas +behind it will be carefully reviewed, often resulting in critique and +criticism. The review will almost always require improvements to the +code before it can be included in the kernel. Know that this happens +because everyone involved wants to see the best possible solution for +the overall success of Linux. This development process has been proven +to create the most robust operating system kernel ever, and we do not +want to do anything to cause the quality of submission and eventual +result to ever decrease. + +If however, anyone feels personally abused, threatened, or otherwise +uncomfortable due to this process, that is not acceptable. If so, +please contact the Linux Foundation's Technical Advisory Board at +, or the individual members, and they +will work to resolve the issue to the best of their ability. For more +information on who is on the Technical Advisory Board and what their +role is, please see: + + - http://www.linuxfoundation.org/projects/linux/tab + +As a reviewer of code, please strive to keep things civil and focused on +the technical issues involved. We are all humans, and frustrations can +be high on both sides of the process. Try to keep in mind the immortal +words of Bill and Ted, "Be excellent to each other." diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst new file mode 100644 index 000000000000..9c61c039ccd9 --- /dev/null +++ b/Documentation/process/coding-style.rst @@ -0,0 +1,1062 @@ +.. _codingstyle: + +Linux kernel coding style +========================= + +This is a short document describing the preferred coding style for the +linux kernel. Coding style is very personal, and I won't **force** my +views on anybody, but this is what goes for anything that I have to be +able to maintain, and I'd prefer it for most other things too. Please +at least consider the points made here. + +First off, I'd suggest printing out a copy of the GNU coding standards, +and NOT read it. Burn them, it's a great symbolic gesture. + +Anyway, here goes: + + +1) Indentation +-------------- + +Tabs are 8 characters, and thus indentations are also 8 characters. +There are heretic movements that try to make indentations 4 (or even 2!) +characters deep, and that is akin to trying to define the value of PI to +be 3. + +Rationale: The whole idea behind indentation is to clearly define where +a block of control starts and ends. Especially when you've been looking +at your screen for 20 straight hours, you'll find it a lot easier to see +how the indentation works if you have large indentations. + +Now, some people will claim that having 8-character indentations makes +the code move too far to the right, and makes it hard to read on a +80-character terminal screen. The answer to that is that if you need +more than 3 levels of indentation, you're screwed anyway, and should fix +your program. + +In short, 8-char indents make things easier to read, and have the added +benefit of warning you when you're nesting your functions too deep. +Heed that warning. + +The preferred way to ease multiple indentation levels in a switch statement is +to align the ``switch`` and its subordinate ``case`` labels in the same column +instead of ``double-indenting`` the ``case`` labels. E.g.: + +.. code-block:: c + + switch (suffix) { + case 'G': + case 'g': + mem <<= 30; + break; + case 'M': + case 'm': + mem <<= 20; + break; + case 'K': + case 'k': + mem <<= 10; + /* fall through */ + default: + break; + } + +Don't put multiple statements on a single line unless you have +something to hide: + +.. code-block:: c + + if (condition) do_this; + do_something_everytime; + +Don't put multiple assignments on a single line either. Kernel coding style +is super simple. Avoid tricky expressions. + +Outside of comments, documentation and except in Kconfig, spaces are never +used for indentation, and the above example is deliberately broken. + +Get a decent editor and don't leave whitespace at the end of lines. + + +2) Breaking long lines and strings +---------------------------------- + +Coding style is all about readability and maintainability using commonly +available tools. + +The limit on the length of lines is 80 columns and this is a strongly +preferred limit. + +Statements longer than 80 columns will be broken into sensible chunks, unless +exceeding 80 columns significantly increases readability and does not hide +information. Descendants are always substantially shorter than the parent and +are placed substantially to the right. The same applies to function headers +with a long argument list. However, never break user-visible strings such as +printk messages, because that breaks the ability to grep for them. + + +3) Placing Braces and Spaces +---------------------------- + +The other issue that always comes up in C styling is the placement of +braces. Unlike the indent size, there are few technical reasons to +choose one placement strategy over the other, but the preferred way, as +shown to us by the prophets Kernighan and Ritchie, is to put the opening +brace last on the line, and put the closing brace first, thusly: + +.. code-block:: c + + if (x is true) { + we do y + } + +This applies to all non-function statement blocks (if, switch, for, +while, do). E.g.: + +.. code-block:: c + + switch (action) { + case KOBJ_ADD: + return "add"; + case KOBJ_REMOVE: + return "remove"; + case KOBJ_CHANGE: + return "change"; + default: + return NULL; + } + +However, there is one special case, namely functions: they have the +opening brace at the beginning of the next line, thus: + +.. code-block:: c + + int function(int x) + { + body of function + } + +Heretic people all over the world have claimed that this inconsistency +is ... well ... inconsistent, but all right-thinking people know that +(a) K&R are **right** and (b) K&R are right. Besides, functions are +special anyway (you can't nest them in C). + +Note that the closing brace is empty on a line of its own, **except** in +the cases where it is followed by a continuation of the same statement, +ie a ``while`` in a do-statement or an ``else`` in an if-statement, like +this: + +.. code-block:: c + + do { + body of do-loop + } while (condition); + +and + +.. code-block:: c + + if (x == y) { + .. + } else if (x > y) { + ... + } else { + .... + } + +Rationale: K&R. + +Also, note that this brace-placement also minimizes the number of empty +(or almost empty) lines, without any loss of readability. Thus, as the +supply of new-lines on your screen is not a renewable resource (think +25-line terminal screens here), you have more empty lines to put +comments on. + +Do not unnecessarily use braces where a single statement will do. + +.. code-block:: c + + if (condition) + action(); + +and + +.. code-block:: none + + if (condition) + do_this(); + else + do_that(); + +This does not apply if only one branch of a conditional statement is a single +statement; in the latter case use braces in both branches: + +.. code-block:: c + + if (condition) { + do_this(); + do_that(); + } else { + otherwise(); + } + +3.1) Spaces +*********** + +Linux kernel style for use of spaces depends (mostly) on +function-versus-keyword usage. Use a space after (most) keywords. The +notable exceptions are sizeof, typeof, alignof, and __attribute__, which look +somewhat like functions (and are usually used with parentheses in Linux, +although they are not required in the language, as in: ``sizeof info`` after +``struct fileinfo info;`` is declared). + +So use a space after these keywords:: + + if, switch, case, for, do, while + +but not with sizeof, typeof, alignof, or __attribute__. E.g., + +.. code-block:: c + + + s = sizeof(struct file); + +Do not add spaces around (inside) parenthesized expressions. This example is +**bad**: + +.. code-block:: c + + + s = sizeof( struct file ); + +When declaring pointer data or a function that returns a pointer type, the +preferred use of ``*`` is adjacent to the data name or function name and not +adjacent to the type name. Examples: + +.. code-block:: c + + + char *linux_banner; + unsigned long long memparse(char *ptr, char **retptr); + char *match_strdup(substring_t *s); + +Use one space around (on each side of) most binary and ternary operators, +such as any of these:: + + = + - < > * / % | & ^ <= >= == != ? : + +but no space after unary operators:: + + & * + - ~ ! sizeof typeof alignof __attribute__ defined + +no space before the postfix increment & decrement unary operators:: + + ++ -- + +no space after the prefix increment & decrement unary operators:: + + ++ -- + +and no space around the ``.`` and ``->`` structure member operators. + +Do not leave trailing whitespace at the ends of lines. Some editors with +``smart`` indentation will insert whitespace at the beginning of new lines as +appropriate, so you can start typing the next line of code right away. +However, some such editors do not remove the whitespace if you end up not +putting a line of code there, such as if you leave a blank line. As a result, +you end up with lines containing trailing whitespace. + +Git will warn you about patches that introduce trailing whitespace, and can +optionally strip the trailing whitespace for you; however, if applying a series +of patches, this may make later patches in the series fail by changing their +context lines. + + +4) Naming +--------- + +C is a Spartan language, and so should your naming be. Unlike Modula-2 +and Pascal programmers, C programmers do not use cute names like +ThisVariableIsATemporaryCounter. A C programmer would call that +variable ``tmp``, which is much easier to write, and not the least more +difficult to understand. + +HOWEVER, while mixed-case names are frowned upon, descriptive names for +global variables are a must. To call a global function ``foo`` is a +shooting offense. + +GLOBAL variables (to be used only if you **really** need them) need to +have descriptive names, as do global functions. If you have a function +that counts the number of active users, you should call that +``count_active_users()`` or similar, you should **not** call it ``cntusr()``. + +Encoding the type of a function into the name (so-called Hungarian +notation) is brain damaged - the compiler knows the types anyway and can +check those, and it only confuses the programmer. No wonder MicroSoft +makes buggy programs. + +LOCAL variable names should be short, and to the point. If you have +some random integer loop counter, it should probably be called ``i``. +Calling it ``loop_counter`` is non-productive, if there is no chance of it +being mis-understood. Similarly, ``tmp`` can be just about any type of +variable that is used to hold a temporary value. + +If you are afraid to mix up your local variable names, you have another +problem, which is called the function-growth-hormone-imbalance syndrome. +See chapter 6 (Functions). + + +5) Typedefs +----------- + +Please don't use things like ``vps_t``. +It's a **mistake** to use typedef for structures and pointers. When you see a + +.. code-block:: c + + + vps_t a; + +in the source, what does it mean? +In contrast, if it says + +.. code-block:: c + + struct virtual_container *a; + +you can actually tell what ``a`` is. + +Lots of people think that typedefs ``help readability``. Not so. They are +useful only for: + + (a) totally opaque objects (where the typedef is actively used to **hide** + what the object is). + + Example: ``pte_t`` etc. opaque objects that you can only access using + the proper accessor functions. + + .. note:: + + Opaqueness and ``accessor functions`` are not good in themselves. + The reason we have them for things like pte_t etc. is that there + really is absolutely **zero** portably accessible information there. + + (b) Clear integer types, where the abstraction **helps** avoid confusion + whether it is ``int`` or ``long``. + + u8/u16/u32 are perfectly fine typedefs, although they fit into + category (d) better than here. + + .. note:: + + Again - there needs to be a **reason** for this. If something is + ``unsigned long``, then there's no reason to do + + typedef unsigned long myflags_t; + + but if there is a clear reason for why it under certain circumstances + might be an ``unsigned int`` and under other configurations might be + ``unsigned long``, then by all means go ahead and use a typedef. + + (c) when you use sparse to literally create a **new** type for + type-checking. + + (d) New types which are identical to standard C99 types, in certain + exceptional circumstances. + + Although it would only take a short amount of time for the eyes and + brain to become accustomed to the standard types like ``uint32_t``, + some people object to their use anyway. + + Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their + signed equivalents which are identical to standard types are + permitted -- although they are not mandatory in new code of your + own. + + When editing existing code which already uses one or the other set + of types, you should conform to the existing choices in that code. + + (e) Types safe for use in userspace. + + In certain structures which are visible to userspace, we cannot + require C99 types and cannot use the ``u32`` form above. Thus, we + use __u32 and similar types in all structures which are shared + with userspace. + +Maybe there are other cases too, but the rule should basically be to NEVER +EVER use a typedef unless you can clearly match one of those rules. + +In general, a pointer, or a struct that has elements that can reasonably +be directly accessed should **never** be a typedef. + + +6) Functions +------------ + +Functions should be short and sweet, and do just one thing. They should +fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, +as we all know), and do one thing and do that well. + +The maximum length of a function is inversely proportional to the +complexity and indentation level of that function. So, if you have a +conceptually simple function that is just one long (but simple) +case-statement, where you have to do lots of small things for a lot of +different cases, it's OK to have a longer function. + +However, if you have a complex function, and you suspect that a +less-than-gifted first-year high-school student might not even +understand what the function is all about, you should adhere to the +maximum limits all the more closely. Use helper functions with +descriptive names (you can ask the compiler to in-line them if you think +it's performance-critical, and it will probably do a better job of it +than you would have done). + +Another measure of the function is the number of local variables. They +shouldn't exceed 5-10, or you're doing something wrong. Re-think the +function, and split it into smaller pieces. A human brain can +generally easily keep track of about 7 different things, anything more +and it gets confused. You know you're brilliant, but maybe you'd like +to understand what you did 2 weeks from now. + +In source files, separate functions with one blank line. If the function is +exported, the **EXPORT** macro for it should follow immediately after the +closing function brace line. E.g.: + +.. code-block:: c + + int system_is_up(void) + { + return system_state == SYSTEM_RUNNING; + } + EXPORT_SYMBOL(system_is_up); + +In function prototypes, include parameter names with their data types. +Although this is not required by the C language, it is preferred in Linux +because it is a simple way to add valuable information for the reader. + + +7) Centralized exiting of functions +----------------------------------- + +Albeit deprecated by some people, the equivalent of the goto statement is +used frequently by compilers in form of the unconditional jump instruction. + +The goto statement comes in handy when a function exits from multiple +locations and some common work such as cleanup has to be done. If there is no +cleanup needed then just return directly. + +Choose label names which say what the goto does or why the goto exists. An +example of a good name could be ``out_free_buffer:`` if the goto frees ``buffer``. +Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to +renumber them if you ever add or remove exit paths, and they make correctness +difficult to verify anyway. + +The rationale for using gotos is: + +- unconditional statements are easier to understand and follow +- nesting is reduced +- errors by not updating individual exit points when making + modifications are prevented +- saves the compiler work to optimize redundant code away ;) + +.. code-block:: c + + int fun(int a) + { + int result = 0; + char *buffer; + + buffer = kmalloc(SIZE, GFP_KERNEL); + if (!buffer) + return -ENOMEM; + + if (condition1) { + while (loop1) { + ... + } + result = 1; + goto out_buffer; + } + ... + out_free_buffer: + kfree(buffer); + return result; + } + +A common type of bug to be aware of is ``one err bugs`` which look like this: + +.. code-block:: c + + err: + kfree(foo->bar); + kfree(foo); + return ret; + +The bug in this code is that on some exit paths ``foo`` is NULL. Normally the +fix for this is to split it up into two error labels ``err_free_bar:`` and +``err_free_foo:``: + +.. code-block:: c + + err_free_bar: + kfree(foo->bar); + err_free_foo: + kfree(foo); + return ret; + +Ideally you should simulate errors to test all exit paths. + + +8) Commenting +------------- + +Comments are good, but there is also a danger of over-commenting. NEVER +try to explain HOW your code works in a comment: it's much better to +write the code so that the **working** is obvious, and it's a waste of +time to explain badly written code. + +Generally, you want your comments to tell WHAT your code does, not HOW. +Also, try to avoid putting comments inside a function body: if the +function is so complex that you need to separately comment parts of it, +you should probably go back to chapter 6 for a while. You can make +small comments to note or warn about something particularly clever (or +ugly), but try to avoid excess. Instead, put the comments at the head +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-documentation.rst and scripts/kernel-doc +for details. + +The preferred style for long (multi-line) comments is: + +.. code-block:: c + + /* + * This is the preferred style for multi-line + * comments in the Linux kernel source code. + * Please use it consistently. + * + * Description: A column of asterisks on the left side, + * with beginning and ending almost-blank lines. + */ + +For files in net/ and drivers/net/ the preferred style for long (multi-line) +comments is a little different. + +.. code-block:: c + + /* 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. + */ + +It's also important to comment data, whether they are basic types or derived +types. To this end, use just one data declaration per line (no commas for +multiple data declarations). This leaves you room for a small comment on each +item, explaining its use. + + +9) You've made a mess of it +--------------------------- + +That's OK, we all do. You've probably been told by your long-time Unix +user helper that ``GNU emacs`` automatically formats the C sources for +you, and you've noticed that yes, it does do that, but the defaults it +uses are less than desirable (in fact, they are worse than random +typing - an infinite number of monkeys typing into GNU emacs would never +make a good program). + +So, you can either get rid of GNU emacs, or change it to use saner +values. To do the latter, you can stick the following in your .emacs file: + +.. code-block:: none + + (defun c-lineup-arglist-tabs-only (ignored) + "Line up argument lists by tabs, not spaces" + (let* ((anchor (c-langelem-pos c-syntactic-element)) + (column (c-langelem-2nd-pos c-syntactic-element)) + (offset (- (1+ column) anchor)) + (steps (floor offset c-basic-offset))) + (* (max steps 1) + c-basic-offset))) + + (add-hook 'c-mode-common-hook + (lambda () + ;; Add kernel style + (c-add-style + "linux-tabs-only" + '("linux" (c-offsets-alist + (arglist-cont-nonempty + c-lineup-gcc-asm-reg + c-lineup-arglist-tabs-only)))))) + + (add-hook 'c-mode-hook + (lambda () + (let ((filename (buffer-file-name))) + ;; Enable kernel mode for the appropriate files + (when (and filename + (string-match (expand-file-name "~/src/linux-trees") + filename)) + (setq indent-tabs-mode t) + (setq show-trailing-whitespace t) + (c-set-style "linux-tabs-only"))))) + +This will make emacs go better with the kernel coding style for C +files below ``~/src/linux-trees``. + +But even if you fail in getting emacs to do sane formatting, not +everything is lost: use ``indent``. + +Now, again, GNU indent has the same brain-dead settings that GNU emacs +has, which is why you need to give it a few command line options. +However, that's not too bad, because even the makers of GNU indent +recognize the authority of K&R (the GNU people aren't evil, they are +just severely misguided in this matter), so you just give indent the +options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use +``scripts/Lindent``, which indents in the latest style. + +``indent`` has a lot of options, and especially when it comes to comment +re-formatting you may want to take a look at the man page. But +remember: ``indent`` is not a fix for bad programming. + + +10) Kconfig configuration files +------------------------------- + +For all of the Kconfig* configuration files throughout the source tree, +the indentation is somewhat different. Lines under a ``config`` definition +are indented with one tab, while help text is indented an additional two +spaces. Example:: + + config AUDIT + bool "Auditing support" + depends on NET + help + Enable auditing infrastructure that can be used with another + kernel subsystem, such as SELinux (which requires this for + logging of avc messages output). Does not do system-call + auditing without CONFIG_AUDITSYSCALL. + +Seriously dangerous features (such as write support for certain +filesystems) should advertise this prominently in their prompt string:: + + config ADFS_FS_RW + bool "ADFS write support (DANGEROUS)" + depends on ADFS_FS + ... + +For full documentation on the configuration files, see the file +Documentation/kbuild/kconfig-language.txt. + + +11) Data structures +------------------- + +Data structures that have visibility outside the single-threaded +environment they are created and destroyed in should always have +reference counts. In the kernel, garbage collection doesn't exist (and +outside the kernel garbage collection is slow and inefficient), which +means that you absolutely **have** to reference count all your uses. + +Reference counting means that you can avoid locking, and allows multiple +users to have access to the data structure in parallel - and not having +to worry about the structure suddenly going away from under them just +because they slept or did something else for a while. + +Note that locking is **not** a replacement for reference counting. +Locking is used to keep data structures coherent, while reference +counting is a memory management technique. Usually both are needed, and +they are not to be confused with each other. + +Many data structures can indeed have two levels of reference counting, +when there are users of different ``classes``. The subclass count counts +the number of subclass users, and decrements the global count just once +when the subclass count goes to zero. + +Examples of this kind of ``multi-level-reference-counting`` can be found in +memory management (``struct mm_struct``: mm_users and mm_count), and in +filesystem code (``struct super_block``: s_count and s_active). + +Remember: if another thread can find your data structure, and you don't +have a reference count on it, you almost certainly have a bug. + + +12) Macros, Enums and RTL +------------------------- + +Names of macros defining constants and labels in enums are capitalized. + +.. code-block:: c + + #define CONSTANT 0x12345 + +Enums are preferred when defining several related constants. + +CAPITALIZED macro names are appreciated but macros resembling functions +may be named in lower case. + +Generally, inline functions are preferable to macros resembling functions. + +Macros with multiple statements should be enclosed in a do - while block: + +.. code-block:: c + + #define macrofun(a, b, c) \ + do { \ + if (a == 5) \ + do_this(b, c); \ + } while (0) + +Things to avoid when using macros: + +1) macros that affect control flow: + +.. code-block:: c + + #define FOO(x) \ + do { \ + if (blah(x) < 0) \ + return -EBUGGERED; \ + } while (0) + +is a **very** bad idea. It looks like a function call but exits the ``calling`` +function; don't break the internal parsers of those who will read the code. + +2) macros that depend on having a local variable with a magic name: + +.. code-block:: c + + #define FOO(val) bar(index, val) + +might look like a good thing, but it's confusing as hell when one reads the +code and it's prone to breakage from seemingly innocent changes. + +3) macros with arguments that are used as l-values: FOO(x) = y; will +bite you if somebody e.g. turns FOO into an inline function. + +4) forgetting about precedence: macros defining constants using expressions +must enclose the expression in parentheses. Beware of similar issues with +macros using parameters. + +.. code-block:: c + + #define CONSTANT 0x4000 + #define CONSTEXP (CONSTANT | 3) + +5) namespace collisions when defining local variables in macros resembling +functions: + +.. code-block:: c + + #define FOO(x) \ + ({ \ + typeof(x) ret; \ + ret = calc_ret(x); \ + (ret); \ + }) + +ret is a common name for a local variable - __foo_ret is less likely +to collide with an existing variable. + +The cpp manual deals with macros exhaustively. The gcc internals manual also +covers RTL which is used frequently with assembly language in the kernel. + + +13) Printing kernel messages +---------------------------- + +Kernel developers like to be seen as literate. Do mind the spelling +of kernel messages to make a good impression. Do not use crippled +words like ``dont``; use ``do not`` or ``don't`` instead. Make the messages +concise, clear, and unambiguous. + +Kernel messages do not have to be terminated with a period. + +Printing numbers in parentheses (%d) adds no value and should be avoided. + +There are a number of driver model diagnostic macros in +which you should use to make sure messages are matched to the right device +and driver, and are tagged with the right level: dev_err(), dev_warn(), +dev_info(), and so forth. For messages that aren't associated with a +particular device, defines pr_notice(), pr_info(), +pr_warn(), pr_err(), etc. + +Coming up with good debugging messages can be quite a challenge; and once +you have them, they can be a huge help for remote troubleshooting. However +debug message printing is handled differently than printing other non-debug +messages. While the other pr_XXX() functions print unconditionally, +pr_debug() does not; it is compiled out by default, unless either DEBUG is +defined or CONFIG_DYNAMIC_DEBUG is set. That is true for dev_dbg() also, +and a related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to +the ones already enabled by DEBUG. + +Many subsystems have Kconfig debug options to turn on -DDEBUG in the +corresponding Makefile; in other cases specific files #define DEBUG. And +when a debug message should be unconditionally printed, such as if it is +already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be +used. + + +14) Allocating memory +--------------------- + +The kernel provides the following general purpose memory allocators: +kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and +vzalloc(). Please refer to the API documentation for further information +about them. + +The preferred form for passing a size of a struct is the following: + +.. code-block:: c + + p = kmalloc(sizeof(*p), ...); + +The alternative form where struct name is spelled out hurts readability and +introduces an opportunity for a bug when the pointer variable type is changed +but the corresponding sizeof that is passed to a memory allocator is not. + +Casting the return value which is a void pointer is redundant. The conversion +from void pointer to any other pointer type is guaranteed by the C programming +language. + +The preferred form for allocating an array is the following: + +.. code-block:: c + + p = kmalloc_array(n, sizeof(...), ...); + +The preferred form for allocating a zeroed array is the following: + +.. code-block:: c + + p = kcalloc(n, sizeof(...), ...); + +Both forms check for overflow on the allocation size n * sizeof(...), +and return NULL if that occurred. + + +15) The inline disease +---------------------- + +There appears to be a common misperception that gcc has a magic "make me +faster" speedup option called ``inline``. While the use of inlines can be +appropriate (for example as a means of replacing macros, see Chapter 12), it +very often is not. Abundant use of the inline keyword leads to a much bigger +kernel, which in turn slows the system as a whole down, due to a bigger +icache footprint for the CPU and simply because there is less memory +available for the pagecache. Just think about it; a pagecache miss causes a +disk seek, which easily takes 5 milliseconds. There are a LOT of cpu cycles +that can go into these 5 milliseconds. + +A reasonable rule of thumb is to not put inline at functions that have more +than 3 lines of code in them. An exception to this rule are the cases where +a parameter is known to be a compiletime constant, and as a result of this +constantness you *know* the compiler will be able to optimize most of your +function away at compile time. For a good example of this later case, see +the kmalloc() inline function. + +Often people argue that adding inline to functions that are static and used +only once is always a win since there is no space tradeoff. While this is +technically correct, gcc is capable of inlining these automatically without +help, and the maintenance issue of removing the inline when a second user +appears outweighs the potential value of the hint that tells gcc to do +something it would have done anyway. + + +16) Function return values and names +------------------------------------ + +Functions can return values of many different kinds, and one of the +most common is a value indicating whether the function succeeded or +failed. Such a value can be represented as an error-code integer +(-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure, +non-zero = success). + +Mixing up these two sorts of representations is a fertile source of +difficult-to-find bugs. If the C language included a strong distinction +between integers and booleans then the compiler would find these mistakes +for us... but it doesn't. To help prevent such bugs, always follow this +convention:: + + If the name of a function is an action or an imperative command, + the function should return an error-code integer. If the name + is a predicate, the function should return a "succeeded" boolean. + +For example, ``add work`` is a command, and the add_work() function returns 0 +for success or -EBUSY for failure. In the same way, ``PCI device present`` is +a predicate, and the pci_dev_present() function returns 1 if it succeeds in +finding a matching device or 0 if it doesn't. + +All EXPORTed functions must respect this convention, and so should all +public functions. Private (static) functions need not, but it is +recommended that they do. + +Functions whose return value is the actual result of a computation, rather +than an indication of whether the computation succeeded, are not subject to +this rule. Generally they indicate failure by returning some out-of-range +result. Typical examples would be functions that return pointers; they use +NULL or the ERR_PTR mechanism to report failure. + + +17) Don't re-invent the kernel macros +------------------------------------- + +The header file include/linux/kernel.h contains a number of macros that +you should use, rather than explicitly coding some variant of them yourself. +For example, if you need to calculate the length of an array, take advantage +of the macro + +.. code-block:: c + + #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0])) + +Similarly, if you need to calculate the size of some structure member, use + +.. code-block:: c + + #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f)) + +There are also min() and max() macros that do strict type checking if you +need them. Feel free to peruse that header file to see what else is already +defined that you shouldn't reproduce in your code. + + +18) Editor modelines and other cruft +------------------------------------ + +Some editors can interpret configuration information embedded in source files, +indicated with special markers. For example, emacs interprets lines marked +like this: + +.. code-block:: c + + -*- mode: c -*- + +Or like this: + +.. code-block:: c + + /* + Local Variables: + compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c" + End: + */ + +Vim interprets markers that look like this: + +.. code-block:: c + + /* vim:set sw=8 noet */ + +Do not include any of these in source files. People have their own personal +editor configurations, and your source files should not override them. This +includes markers for indentation and mode configuration. People may use their +own custom mode, or may have some other magic method for making indentation +work correctly. + + +19) Inline assembly +------------------- + +In architecture-specific code, you may need to use inline assembly to interface +with CPU or platform functionality. Don't hesitate to do so when necessary. +However, don't use inline assembly gratuitously when C can do the job. You can +and should poke hardware from C when possible. + +Consider writing simple helper functions that wrap common bits of inline +assembly, rather than repeatedly writing them with slight variations. Remember +that inline assembly can use C parameters. + +Large, non-trivial assembly functions should go in .S files, with corresponding +C prototypes defined in C header files. The C prototypes for assembly +functions should use ``asmlinkage``. + +You may need to mark your asm statement as volatile, to prevent GCC from +removing it if GCC doesn't notice any side effects. You don't always need to +do so, though, and doing so unnecessarily can limit optimization. + +When writing a single inline assembly statement containing multiple +instructions, put each instruction on a separate line in a separate quoted +string, and end each string except the last with \n\t to properly indent the +next instruction in the assembly output: + +.. code-block:: c + + asm ("magic %reg1, #42\n\t" + "more_magic %reg2, %reg3" + : /* outputs */ : /* inputs */ : /* clobbers */); + + +20) Conditional Compilation +--------------------------- + +Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c +files; doing so makes code harder to read and logic harder to follow. Instead, +use such conditionals in a header file defining functions for use in those .c +files, providing no-op stub versions in the #else case, and then call those +functions unconditionally from .c files. The compiler will avoid generating +any code for the stub calls, producing identical results, but the logic will +remain easy to follow. + +Prefer to compile out entire functions, rather than portions of functions or +portions of expressions. Rather than putting an ifdef in an expression, factor +out part or all of the expression into a separate helper function and apply the +conditional to that function. + +If you have a function or variable which may potentially go unused in a +particular configuration, and the compiler would warn about its definition +going unused, mark the definition as __maybe_unused rather than wrapping it in +a preprocessor conditional. (However, if a function or variable *always* goes +unused, delete it.) + +Within code, where possible, use the IS_ENABLED macro to convert a Kconfig +symbol into a C boolean expression, and use it in a normal C conditional: + +.. code-block:: c + + if (IS_ENABLED(CONFIG_SOMETHING)) { + ... + } + +The compiler will constant-fold the conditional away, and include or exclude +the block of code just as with an #ifdef, so this will not add any runtime +overhead. However, this approach still allows the C compiler to see the code +inside the block, and check it for correctness (syntax, types, symbol +references, etc). Thus, you still have to use an #ifdef if the code inside the +block references symbols that will not exist if the condition is not met. + +At the end of any non-trivial #if or #ifdef block (more than a few lines), +place a comment after the #endif on the same line, noting the conditional +expression used. For instance: + +.. code-block:: c + + #ifdef CONFIG_SOMETHING + ... + #endif /* CONFIG_SOMETHING */ + + +Appendix I) References +---------------------- + +The C Programming Language, Second Edition +by Brian W. Kernighan and Dennis M. Ritchie. +Prentice Hall, Inc., 1988. +ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback). + +The Practice of Programming +by Brian W. Kernighan and Rob Pike. +Addison-Wesley, Inc., 1999. +ISBN 0-201-61586-X. + +GNU manuals - where in compliance with K&R and this text - for cpp, gcc, +gcc internals and indent, all available from http://www.gnu.org/manual/ + +WG14 is the international standardization working group for the programming +language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ + +Kernel CodingStyle, by greg@kroah.com at OLS 2002: +http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst new file mode 100644 index 000000000000..ac892b30815e --- /dev/null +++ b/Documentation/process/email-clients.rst @@ -0,0 +1,319 @@ +.. _email_clients: + +Email clients info for Linux +============================ + +Git +--- + +These days most developers use ``git send-email`` instead of regular +email clients. The man page for this is quite good. On the receiving +end, maintainers use ``git am`` to apply the patches. + +If you are new to ``git`` then send your first patch to yourself. Save it +as raw text including all the headers. Run ``git am raw_email.txt`` and +then review the changelog with ``git log``. When that works then send +the patch to the appropriate mailing list(s). + +General Preferences +------------------- + +Patches for the Linux kernel are submitted via email, preferably as +inline text in the body of the email. Some maintainers accept +attachments, but then the attachments should have content-type +``text/plain``. However, attachments are generally frowned upon because +it makes quoting portions of the patch more difficult in the patch +review process. + +Email clients that are used for Linux kernel patches should send the +patch text untouched. For example, they should not modify or delete tabs +or spaces, even at the beginning or end of lines. + +Don't send patches with ``format=flowed``. This can cause unexpected +and unwanted line breaks. + +Don't let your email client do automatic word wrapping for you. +This can also corrupt your patch. + +Email clients should not modify the character set encoding of the text. +Emailed patches should be in ASCII or UTF-8 encoding only. +If you configure your email client to send emails with UTF-8 encoding, +you avoid some possible charset problems. + +Email clients should generate and maintain References: or In-Reply-To: +headers so that mail threading is not broken. + +Copy-and-paste (or cut-and-paste) usually does not work for patches +because tabs are converted to spaces. Using xclipboard, xclip, and/or +xcutsel may work, but it's best to test this for yourself or just avoid +copy-and-paste. + +Don't use PGP/GPG signatures in mail that contains patches. +This breaks many scripts that read and apply the patches. +(This should be fixable.) + +It's a good idea to send a patch to yourself, save the received message, +and successfully apply it with 'patch' before sending patches to Linux +mailing lists. + + +Some email client (MUA) hints +----------------------------- + +Here are some specific MUA configuration hints for editing and sending +patches for the Linux kernel. These are not meant to be complete +software package configuration summaries. + + +Legend: + +- TUI = text-based user interface +- GUI = graphical user interface + +Alpine (TUI) +************ + +Config options: + +In the :menuselection:`Sending Preferences` section: + +- :menuselection:`Do Not Send Flowed Text` must be ``enabled`` +- :menuselection:`Strip Whitespace Before Sending` must be ``disabled`` + +When composing the message, the cursor should be placed where the patch +should appear, and then pressing :kbd:`CTRL-R` let you specify the patch file +to insert into the message. + +Claws Mail (GUI) +**************** + +Works. Some people use this successfully for patches. + +To insert a patch use :menuselection:`Message-->Insert` File (:kbd:`CTRL-I`) +or an external editor. + +If the inserted patch has to be edited in the Claws composition window +"Auto wrapping" in +:menuselection:`Configuration-->Preferences-->Compose-->Wrapping` should be +disabled. + +Evolution (GUI) +*************** + +Some people use this successfully for patches. + +When composing mail select: Preformat + from :menuselection:`Format-->Paragraph Style-->Preformatted` (:kbd:`CTRL-7`) + or the toolbar + +Then use: +:menuselection:`Insert-->Text File...` (:kbd:`ALT-N x`) +to insert the patch. + +You can also ``diff -Nru old.c new.c | xclip``, select +:menuselection:`Preformat`, then paste with the middle button. + +Kmail (GUI) +*********** + +Some people use Kmail successfully for patches. + +The default setting of not composing in HTML is appropriate; do not +enable it. + +When composing an email, under options, uncheck "word wrap". The only +disadvantage is any text you type in the email will not be word-wrapped +so you will have to manually word wrap text before the patch. The easiest +way around this is to compose your email with word wrap enabled, then save +it as a draft. Once you pull it up again from your drafts it is now hard +word-wrapped and you can uncheck "word wrap" without losing the existing +wrapping. + +At the bottom of your email, put the commonly-used patch delimiter before +inserting your patch: three hyphens (``---``). + +Then from the :menuselection:`Message` menu item, select insert file and +choose your patch. +As an added bonus you can customise the message creation toolbar menu +and put the :menuselection:`insert file` icon there. + +Make the composer window wide enough so that no lines wrap. As of +KMail 1.13.5 (KDE 4.5.4), KMail will apply word wrapping when sending +the email if the lines wrap in the composer window. Having word wrapping +disabled in the Options menu isn't enough. Thus, if your patch has very +long lines, you must make the composer window very wide before sending +the email. See: https://bugs.kde.org/show_bug.cgi?id=174034 + +You can safely GPG sign attachments, but inlined text is preferred for +patches so do not GPG sign them. Signing patches that have been inserted +as inlined text will make them tricky to extract from their 7-bit encoding. + +If you absolutely must send patches as attachments instead of inlining +them as text, right click on the attachment and select properties, and +highlight :menuselection:`Suggest automatic display` to make the attachment +inlined to make it more viewable. + +When saving patches that are sent as inlined text, select the email that +contains the patch from the message list pane, right click and select +:menuselection:`save as`. You can use the whole email unmodified as a patch +if it was properly composed. There is no option currently to save the email +when you are actually viewing it in its own window -- there has been a request +filed at kmail's bugzilla and hopefully this will be addressed. Emails are +saved as read-write for user only so you will have to chmod them to make them +group and world readable if you copy them elsewhere. + +Lotus Notes (GUI) +***************** + +Run away from it. + +Mutt (TUI) +********** + +Plenty of Linux developers use ``mutt``, so it must work pretty well. + +Mutt doesn't come with an editor, so whatever editor you use should be +used in a way that there are no automatic linebreaks. Most editors have +an :menuselection:`insert file` option that inserts the contents of a file +unaltered. + +To use ``vim`` with mutt:: + + set editor="vi" + +If using xclip, type the command:: + + :set paste + +before middle button or shift-insert or use:: + + :r filename + +if you want to include the patch inline. +(a)ttach works fine without ``set paste``. + +You can also generate patches with ``git format-patch`` and then use Mutt +to send them:: + + $ mutt -H 0001-some-bug-fix.patch + +Config options: + +It should work with default settings. +However, it's a good idea to set the ``send_charset`` to:: + + set send_charset="us-ascii:utf-8" + +Mutt is highly customizable. Here is a minimum configuration to start +using Mutt to send patches through Gmail:: + + # .muttrc + # ================ IMAP ==================== + set imap_user = 'yourusername@gmail.com' + set imap_pass = 'yourpassword' + set spoolfile = imaps://imap.gmail.com/INBOX + set folder = imaps://imap.gmail.com/ + set record="imaps://imap.gmail.com/[Gmail]/Sent Mail" + set postponed="imaps://imap.gmail.com/[Gmail]/Drafts" + set mbox="imaps://imap.gmail.com/[Gmail]/All Mail" + + # ================ SMTP ==================== + set smtp_url = "smtp://username@smtp.gmail.com:587/" + set smtp_pass = $imap_pass + set ssl_force_tls = yes # Require encrypted connection + + # ================ Composition ==================== + set editor = `echo \$EDITOR` + set edit_headers = yes # See the headers when editing + set charset = UTF-8 # value of $LANG; also fallback for send_charset + # Sender, email address, and sign-off line must match + unset use_domain # because joe@localhost is just embarrassing + set realname = "YOUR NAME" + set from = "username@gmail.com" + set use_from = yes + +The Mutt docs have lots more information: + + http://dev.mutt.org/trac/wiki/UseCases/Gmail + + http://dev.mutt.org/doc/manual.html + +Pine (TUI) +********** + +Pine has had some whitespace truncation issues in the past, but these +should all be fixed now. + +Use alpine (pine's successor) if you can. + +Config options: + +- ``quell-flowed-text`` is needed for recent versions +- the ``no-strip-whitespace-before-send`` option is needed + + +Sylpheed (GUI) +************** + +- Works well for inlining text (or using attachments). +- Allows use of an external editor. +- Is slow on large folders. +- Won't do TLS SMTP auth over a non-SSL connection. +- Has a helpful ruler bar in the compose window. +- Adding addresses to address book doesn't understand the display name + properly. + +Thunderbird (GUI) +***************** + +Thunderbird is an Outlook clone that likes to mangle text, but there are ways +to coerce it into behaving. + +- Allow use of an external editor: + The easiest thing to do with Thunderbird and patches is to use an + "external editor" extension and then just use your favorite ``$EDITOR`` + for reading/merging patches into the body text. To do this, download + and install the extension, then add a button for it using + :menuselection:`View-->Toolbars-->Customize...` and finally just click on it + when in the :menuselection:`Compose` dialog. + + Please note that "external editor" requires that your editor must not + fork, or in other words, the editor must not return before closing. + You may have to pass additional flags or change the settings of your + editor. Most notably if you are using gvim then you must pass the -f + option to gvim by putting ``/usr/bin/gvim -f`` (if the binary is in + ``/usr/bin``) to the text editor field in :menuselection:`external editor` + settings. If you are using some other editor then please read its manual + to find out how to do this. + +To beat some sense out of the internal editor, do this: + +- Edit your Thunderbird config settings so that it won't use ``format=flowed``. + Go to :menuselection:`edit-->preferences-->advanced-->config editor` to bring up + the thunderbird's registry editor. + +- Set ``mailnews.send_plaintext_flowed`` to ``false`` + +- Set ``mailnews.wraplength`` from ``72`` to ``0`` + +- :menuselection:`View-->Message Body As-->Plain Text` + +- :menuselection:`View-->Character Encoding-->Unicode (UTF-8)` + +TkRat (GUI) +*********** + +Works. Use "Insert file..." or external editor. + +Gmail (Web GUI) +*************** + +Does not work for sending patches. + +Gmail web client converts tabs to spaces automatically. + +At the same time it wraps lines every 78 chars with CRLF style line breaks +although tab2space problem can be solved with external editor. + +Another problem is that Gmail will base64-encode any message that has a +non-ASCII character. That includes things like European names. diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst new file mode 100644 index 000000000000..5f042349f987 --- /dev/null +++ b/Documentation/process/howto.rst @@ -0,0 +1,652 @@ +HOWTO do Linux kernel development +================================= + +This is the be-all, end-all document on this topic. It contains +instructions on how to become a Linux kernel developer and how to learn +to work with the Linux kernel development community. It tries to not +contain anything related to the technical aspects of kernel programming, +but will help point you in the right direction for that. + +If anything in this document becomes out of date, please send in patches +to the maintainer of this file, who is listed at the bottom of the +document. + + +Introduction +------------ + +So, you want to learn how to become a Linux kernel developer? Or you +have been told by your manager, "Go write a Linux driver for this +device." This document's goal is to teach you everything you need to +know to achieve this by describing the process you need to go through, +and hints on how to work with the community. It will also try to +explain some of the reasons why the community works like it does. + +The kernel is written mostly in C, with some architecture-dependent +parts written in assembly. A good understanding of C is required for +kernel development. Assembly (any architecture) is not required unless +you plan to do low-level development for that architecture. Though they +are not a good substitute for a solid C education and/or years of +experience, the following books are good for, if anything, reference: + + - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] + - "Practical C Programming" by Steve Oualline [O'Reilly] + - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] + +The kernel is written using GNU C and the GNU toolchain. While it +adheres to the ISO C89 standard, it uses a number of extensions that are +not featured in the standard. The kernel is a freestanding C +environment, with no reliance on the standard C library, so some +portions of the C standard are not supported. Arbitrary long long +divisions and floating point are not allowed. It can sometimes be +difficult to understand the assumptions the kernel has on the toolchain +and the extensions that it uses, and unfortunately there is no +definitive reference for them. Please check the gcc info pages (`info +gcc`) for some information on them. + +Please remember that you are trying to learn how to work with the +existing development community. It is a diverse group of people, with +high standards for coding, style and procedure. These standards have +been created over time based on what they have found to work best for +such a large and geographically dispersed team. Try to learn as much as +possible about these standards ahead of time, as they are well +documented; do not expect people to adapt to you or your company's way +of doing things. + + +Legal Issues +------------ + +The Linux kernel source code is released under the GPL. Please see the +file, COPYING, in the main directory of the source tree, for details on +the license. If you have further questions about the license, please +contact a lawyer, and do not ask on the Linux kernel mailing list. The +people on the mailing lists are not lawyers, and you should not rely on +their statements on legal matters. + +For common questions and answers about the GPL, please see: + + https://www.gnu.org/licenses/gpl-faq.html + + +Documentation +------------- + +The Linux kernel source tree has a large range of documents that are +invaluable for learning how to interact with the kernel community. When +new features are added to the kernel, it is recommended that new +documentation files are also added which explain how to use the feature. +When a kernel change causes the interface that the kernel exposes to +userspace to change, it is recommended that you send the information or +a patch to the manual pages explaining the change to the manual pages +maintainer at mtk.manpages@gmail.com, and CC the list +linux-api@vger.kernel.org. + +Here is a list of files that are in the kernel source tree that are +required reading: + + README + This file gives a short background on the Linux kernel and describes + what is necessary to do to configure and build the kernel. People + who are new to the kernel should start here. + + :ref:`Documentation/Changes ` + This file gives a list of the minimum levels of various software + packages that are necessary to build and run the kernel + successfully. + + :ref:`Documentation/CodingStyle ` + This describes the Linux kernel coding style, and some of the + rationale behind it. All new code is expected to follow the + guidelines in this document. Most maintainers will only accept + patches if these rules are followed, and many people will only + review code if it is in the proper style. + + :ref:`Documentation/SubmittingPatches ` and :ref:`Documentation/SubmittingDrivers ` + These files describe in explicit detail how to successfully create + and send a patch, including (but not limited to): + + - Email contents + - Email format + - Who to send it to + + Following these rules will not guarantee success (as all patches are + subject to scrutiny for content and style), but not following them + will almost always prevent it. + + Other excellent descriptions of how to create patches properly are: + + "The Perfect Patch" + https://www.ozlabs.org/~akpm/stuff/tpp.txt + + "Linux kernel patch submission format" + http://linux.yyz.us/patch-format.html + + :ref:`Documentation/stable_api_nonsense.txt ` + This file describes the rationale behind the conscious decision to + not have a stable API within the kernel, including things like: + + - Subsystem shim-layers (for compatibility?) + - Driver portability between Operating Systems. + - Mitigating rapid change within the kernel source tree (or + preventing rapid change) + + This document is crucial for understanding the Linux development + philosophy and is very important for people moving to Linux from + development on other Operating Systems. + + :ref:`Documentation/SecurityBugs ` + If you feel you have found a security problem in the Linux kernel, + please follow the steps in this document to help notify the kernel + developers, and help solve the issue. + + :ref:`Documentation/ManagementStyle ` + This document describes how Linux kernel maintainers operate and the + shared ethos behind their methodologies. This is important reading + for anyone new to kernel development (or anyone simply curious about + it), as it resolves a lot of common misconceptions and confusion + about the unique behavior of kernel maintainers. + + :ref:`Documentation/stable_kernel_rules.txt ` + This file describes the rules on how the stable kernel releases + happen, and what to do if you want to get a change into one of these + releases. + + :ref:`Documentation/kernel-docs.txt ` + A list of external documentation that pertains to kernel + development. Please consult this list if you do not find what you + are looking for within the in-kernel documentation. + + :ref:`Documentation/applying-patches.txt ` + A good introduction describing exactly what a patch is and how to + apply it to the different development branches of the kernel. + +The kernel also has a large number of documents that can be +automatically generated from the source code itself or from +ReStructuredText markups (ReST), like this one. This includes a +full description of the in-kernel API, and rules on how to handle +locking properly. + +All such documents can be generated as PDF or HTML by running:: + + make pdfdocs + make htmldocs + +respectively from the main kernel source directory. + +The documents that uses ReST markup will be generated at Documentation/output. +They can also be generated on LaTeX and ePub formats with:: + + make latexdocs + make epubdocs + +Currently, there are some documents written on DocBook that are in +the process of conversion to ReST. Such documents will be created in the +Documentation/DocBook/ directory and can be generated also as +Postscript or man pages by running:: + + make psdocs + make mandocs + +Becoming A Kernel Developer +--------------------------- + +If you do not know anything about Linux kernel development, you should +look at the Linux KernelNewbies project: + + https://kernelnewbies.org + +It consists of a helpful mailing list where you can ask almost any type +of basic kernel development question (make sure to search the archives +first, before asking something that has already been answered in the +past.) It also has an IRC channel that you can use to ask questions in +real-time, and a lot of helpful documentation that is useful for +learning about Linux kernel development. + +The website has basic information about code organization, subsystems, +and current projects (both in-tree and out-of-tree). It also describes +some basic logistical information, like how to compile a kernel and +apply a patch. + +If you do not know where you want to start, but you want to look for +some task to start doing to join into the kernel development community, +go to the Linux Kernel Janitor's project: + + https://kernelnewbies.org/KernelJanitors + +It is a great place to start. It describes a list of relatively simple +problems that need to be cleaned up and fixed within the Linux kernel +source tree. Working with the developers in charge of this project, you +will learn the basics of getting your patch into the Linux kernel tree, +and possibly be pointed in the direction of what to go work on next, if +you do not already have an idea. + +If you already have a chunk of code that you want to put into the kernel +tree, but need some help getting it in the proper form, the +kernel-mentors project was created to help you out with this. It is a +mailing list, and can be found at: + + https://selenic.com/mailman/listinfo/kernel-mentors + +Before making any actual modifications to the Linux kernel code, it is +imperative to understand how the code in question works. For this +purpose, nothing is better than reading through it directly (most tricky +bits are commented well), perhaps even with the help of specialized +tools. One such tool that is particularly recommended is the Linux +Cross-Reference project, which is able to present source code in a +self-referential, indexed webpage format. An excellent up-to-date +repository of the kernel code may be found at: + + http://lxr.free-electrons.com/ + + +The development process +----------------------- + +Linux kernel development process currently consists of a few different +main kernel "branches" and lots of different subsystem-specific kernel +branches. These different branches are: + + - main 4.x kernel tree + - 4.x.y -stable kernel tree + - 4.x -git kernel patches + - subsystem specific kernel trees and patches + - the 4.x -next kernel tree for integration tests + +4.x kernel tree +----------------- +4.x kernels are maintained by Linus Torvalds, and can be found on +https://kernel.org in the pub/linux/kernel/v4.x/ directory. Its development +process is as follows: + + - As soon as a new kernel is released a two weeks window is open, + during this period of time maintainers can submit big diffs to + Linus, usually the patches that have already been included in the + -next kernel for a few weeks. The preferred way to submit big changes + is using git (the kernel's source management tool, more information + can be found at https://git-scm.com/) but plain patches are also just + fine. + - After two weeks a -rc1 kernel is released it is now possible to push + only patches that do not include new features that could affect the + stability of the whole kernel. Please note that a whole new driver + (or filesystem) might be accepted after -rc1 because there is no + risk of causing regressions with such a change as long as the change + is self-contained and does not affect areas outside of the code that + is being added. git can be used to send patches to Linus after -rc1 + is released, but the patches need to also be sent to a public + mailing list for review. + - A new -rc is released whenever Linus deems the current git tree to + be in a reasonably sane state adequate for testing. The goal is to + release a new -rc kernel every week. + - Process continues until the kernel is considered "ready", the + process should last around 6 weeks. + +It is worth mentioning what Andrew Morton wrote on the linux-kernel +mailing list about kernel releases: + + *"Nobody knows when a kernel will be released, because it's + released according to perceived bug status, not according to a + preconceived timeline."* + +4.x.y -stable kernel tree +------------------------- +Kernels with 3-part versions are -stable kernels. They contain +relatively small and critical fixes for security problems or significant +regressions discovered in a given 4.x kernel. + +This is the recommended branch for users who want the most recent stable +kernel and are not interested in helping test development/experimental +versions. + +If no 4.x.y kernel is available, then the highest numbered 4.x +kernel is the current stable kernel. + +4.x.y are maintained by the "stable" team , and +are released as needs dictate. The normal release period is approximately +two weeks, but it can be longer if there are no pressing problems. A +security-related problem, instead, can cause a release to happen almost +instantly. + +The file Documentation/stable_kernel_rules.txt in the kernel tree +documents what kinds of changes are acceptable for the -stable tree, and +how the release process works. + +4.x -git patches +---------------- +These are daily snapshots of Linus' kernel tree which are managed in a +git repository (hence the name.) These patches are usually released +daily and represent the current state of Linus' tree. They are more +experimental than -rc kernels since they are generated automatically +without even a cursory glance to see if they are sane. + +Subsystem Specific kernel trees and patches +------------------------------------------- +The maintainers of the various kernel subsystems --- and also many +kernel subsystem developers --- expose their current state of +development in source repositories. That way, others can see what is +happening in the different areas of the kernel. In areas where +development is rapid, a developer may be asked to base his submissions +onto such a subsystem kernel tree so that conflicts between the +submission and other already ongoing work are avoided. + +Most of these repositories are git trees, but there are also other SCMs +in use, or patch queues being published as quilt series. Addresses of +these subsystem repositories are listed in the MAINTAINERS file. Many +of them can be browsed at https://git.kernel.org/. + +Before a proposed patch is committed to such a subsystem tree, it is +subject to review which primarily happens on mailing lists (see the +respective section below). For several kernel subsystems, this review +process is tracked with the tool patchwork. Patchwork offers a web +interface which shows patch postings, any comments on a patch or +revisions to it, and maintainers can mark patches as under review, +accepted, or rejected. Most of these patchwork sites are listed at +https://patchwork.kernel.org/. + +4.x -next kernel tree for integration tests +------------------------------------------- +Before updates from subsystem trees are merged into the mainline 4.x +tree, they need to be integration-tested. For this purpose, a special +testing repository exists into which virtually all subsystem trees are +pulled on an almost daily basis: + + https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git + +This way, the -next kernel gives a summary outlook onto what will be +expected to go into the mainline kernel at the next merge period. +Adventurous testers are very welcome to runtime-test the -next kernel. + + +Bug Reporting +------------- + +https://bugzilla.kernel.org is where the Linux kernel developers track kernel +bugs. Users are encouraged to report all bugs that they find in this +tool. For details on how to use the kernel bugzilla, please see: + + https://bugzilla.kernel.org/page.cgi?id=faq.html + +The file REPORTING-BUGS in the main kernel source directory has a good +template for how to report a possible kernel bug, and details what kind +of information is needed by the kernel developers to help track down the +problem. + + +Managing bug reports +-------------------- + +One of the best ways to put into practice your hacking skills is by fixing +bugs reported by other people. Not only you will help to make the kernel +more stable, you'll learn to fix real world problems and you will improve +your skills, and other developers will be aware of your presence. Fixing +bugs is one of the best ways to get merits among other developers, because +not many people like wasting time fixing other people's bugs. + +To work in the already reported bug reports, go to https://bugzilla.kernel.org. +If you want to be advised of the future bug reports, you can subscribe to the +bugme-new mailing list (only new bug reports are mailed here) or to the +bugme-janitor mailing list (every change in the bugzilla is mailed here) + + https://lists.linux-foundation.org/mailman/listinfo/bugme-new + + https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors + + + +Mailing lists +------------- + +As some of the above documents describe, the majority of the core kernel +developers participate on the Linux Kernel Mailing list. Details on how +to subscribe and unsubscribe from the list can be found at: + + http://vger.kernel.org/vger-lists.html#linux-kernel + +There are archives of the mailing list on the web in many different +places. Use a search engine to find these archives. For example: + + http://dir.gmane.org/gmane.linux.kernel + +It is highly recommended that you search the archives about the topic +you want to bring up, before you post it to the list. A lot of things +already discussed in detail are only recorded at the mailing list +archives. + +Most of the individual kernel subsystems also have their own separate +mailing list where they do their development efforts. See the +MAINTAINERS file for a list of what these lists are for the different +groups. + +Many of the lists are hosted on kernel.org. Information on them can be +found at: + + http://vger.kernel.org/vger-lists.html + +Please remember to follow good behavioral habits when using the lists. +Though a bit cheesy, the following URL has some simple guidelines for +interacting with the list (or any list): + + http://www.albion.com/netiquette/ + +If multiple people respond to your mail, the CC: list of recipients may +get pretty large. Don't remove anybody from the CC: list without a good +reason, or don't reply only to the list address. Get used to receiving the +mail twice, one from the sender and the one from the list, and don't try +to tune that by adding fancy mail-headers, people will not like it. + +Remember to keep the context and the attribution of your replies intact, +keep the "John Kernelhacker wrote ...:" lines at the top of your reply, and +add your statements between the individual quoted sections instead of +writing at the top of the mail. + +If you add patches to your mail, make sure they are plain readable text +as stated in Documentation/SubmittingPatches. +Kernel developers don't want to deal with +attachments or compressed patches; they may want to comment on +individual lines of your patch, which works only that way. Make sure you +use a mail program that does not mangle spaces and tab characters. A +good first test is to send the mail to yourself and try to apply your +own patch by yourself. If that doesn't work, get your mail program fixed +or change it until it works. + +Above all, please remember to show respect to other subscribers. + + +Working with the community +-------------------------- + +The goal of the kernel community is to provide the best possible kernel +there is. When you submit a patch for acceptance, it will be reviewed +on its technical merits and those alone. So, what should you be +expecting? + + - criticism + - comments + - requests for change + - requests for justification + - silence + +Remember, this is part of getting your patch into the kernel. You have +to be able to take criticism and comments about your patches, evaluate +them at a technical level and either rework your patches or provide +clear and concise reasoning as to why those changes should not be made. +If there are no responses to your posting, wait a few days and try +again, sometimes things get lost in the huge volume. + +What should you not do? + + - expect your patch to be accepted without question + - become defensive + - ignore comments + - resubmit the patch without making any of the requested changes + +In a community that is looking for the best technical solution possible, +there will always be differing opinions on how beneficial a patch is. +You have to be cooperative, and willing to adapt your idea to fit within +the kernel. Or at least be willing to prove your idea is worth it. +Remember, being wrong is acceptable as long as you are willing to work +toward a solution that is right. + +It is normal that the answers to your first patch might simply be a list +of a dozen things you should correct. This does **not** imply that your +patch will not be accepted, and it is **not** meant against you +personally. Simply correct all issues raised against your patch and +resend it. + + +Differences between the kernel community and corporate structures +----------------------------------------------------------------- + +The kernel community works differently than most traditional corporate +development environments. Here are a list of things that you can try to +do to avoid problems: + + Good things to say regarding your proposed changes: + + - "This solves multiple problems." + - "This deletes 2000 lines of code." + - "Here is a patch that explains what I am trying to describe." + - "I tested it on 5 different architectures..." + - "Here is a series of small patches that..." + - "This increases performance on typical machines..." + + Bad things you should avoid saying: + + - "We did it this way in AIX/ptx/Solaris, so therefore it must be + good..." + - "I've being doing this for 20 years, so..." + - "This is required for my company to make money" + - "This is for our Enterprise product line." + - "Here is my 1000 page design document that describes my idea" + - "I've been working on this for 6 months..." + - "Here's a 5000 line patch that..." + - "I rewrote all of the current mess, and here it is..." + - "I have a deadline, and this patch needs to be applied now." + +Another way the kernel community is different than most traditional +software engineering work environments is the faceless nature of +interaction. One benefit of using email and irc as the primary forms of +communication is the lack of discrimination based on gender or race. +The Linux kernel work environment is accepting of women and minorities +because all you are is an email address. The international aspect also +helps to level the playing field because you can't guess gender based on +a person's name. A man may be named Andrea and a woman may be named Pat. +Most women who have worked in the Linux kernel and have expressed an +opinion have had positive experiences. + +The language barrier can cause problems for some people who are not +comfortable with English. A good grasp of the language can be needed in +order to get ideas across properly on mailing lists, so it is +recommended that you check your emails to make sure they make sense in +English before sending them. + + +Break up your changes +--------------------- + +The Linux kernel community does not gladly accept large chunks of code +dropped on it all at once. The changes need to be properly introduced, +discussed, and broken up into tiny, individual portions. This is almost +the exact opposite of what companies are used to doing. Your proposal +should also be introduced very early in the development process, so that +you can receive feedback on what you are doing. It also lets the +community feel that you are working with them, and not simply using them +as a dumping ground for your feature. However, don't send 50 emails at +one time to a mailing list, your patch series should be smaller than +that almost all of the time. + +The reasons for breaking things up are the following: + +1) Small patches increase the likelihood that your patches will be + applied, since they don't take much time or effort to verify for + correctness. A 5 line patch can be applied by a maintainer with + barely a second glance. However, a 500 line patch may take hours to + review for correctness (the time it takes is exponentially + proportional to the size of the patch, or something). + + Small patches also make it very easy to debug when something goes + wrong. It's much easier to back out patches one by one than it is + to dissect a very large patch after it's been applied (and broken + something). + +2) It's important not only to send small patches, but also to rewrite + and simplify (or simply re-order) patches before submitting them. + +Here is an analogy from kernel developer Al Viro: + + *"Think of a teacher grading homework from a math student. The + teacher does not want to see the student's trials and errors + before they came up with the solution. They want to see the + cleanest, most elegant answer. A good student knows this, and + would never submit her intermediate work before the final + solution.* + + *The same is true of kernel development. The maintainers and + reviewers do not want to see the thought process behind the + solution to the problem one is solving. They want to see a + simple and elegant solution."* + +It may be challenging to keep the balance between presenting an elegant +solution and working together with the community and discussing your +unfinished work. Therefore it is good to get early in the process to +get feedback to improve your work, but also keep your changes in small +chunks that they may get already accepted, even when your whole task is +not ready for inclusion now. + +Also realize that it is not acceptable to send patches for inclusion +that are unfinished and will be "fixed up later." + + +Justify your change +------------------- + +Along with breaking up your patches, it is very important for you to let +the Linux community know why they should add this change. New features +must be justified as being needed and useful. + + +Document your change +-------------------- + +When sending in your patches, pay special attention to what you say in +the text in your email. This information will become the ChangeLog +information for the patch, and will be preserved for everyone to see for +all time. It should describe the patch completely, containing: + + - why the change is necessary + - the overall design approach in the patch + - implementation details + - testing results + +For more details on what this should all look like, please see the +ChangeLog section of the document: + + "The Perfect Patch" + http://www.ozlabs.org/~akpm/stuff/tpp.txt + + +All of these things are sometimes very hard to do. It can take years to +perfect these practices (if at all). It's a continuous process of +improvement that requires a lot of patience and determination. But +don't give up, it's possible. Many have done it before, and each had to +start exactly where you are now. + + + + +---------- + +Thanks to Paolo Ciarrocchi who allowed the "Development Process" +(https://lwn.net/Articles/94386/) section +to be based on text he had written, and to Randy Dunlap and Gerrit +Huizenga for some of the list of things you should and should not say. +Also thanks to Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers, +Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi +Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop, +David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard for +their review, comments, and contributions. Without their help, this +document would not have been possible. + + + +Maintainer: Greg Kroah-Hartman diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index c37475d91090..6ee818752474 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -1,3 +1,9 @@ +.. raw:: latex + + \renewcommand\thesection* + \renewcommand\thesubsection* + + Linux Kernel Development Documentation ====================================== @@ -6,4 +12,21 @@ Contents: .. toctree:: :maxdepth: 2 + howto + changes + coding-style + submitting-patches + submitting-drivers + stable-api-nonsense + management-style + stable-kernel-rules + kernel-docs + applying-patches + email-clients + submit-checklist + code-of-conflict + adding-syscalls + magic-number + volatile-considered-harmful + development-process diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst new file mode 100644 index 000000000000..05a7857a4a83 --- /dev/null +++ b/Documentation/process/kernel-docs.rst @@ -0,0 +1,652 @@ +.. _kernel_docs: + +Index of Documentation for People Interested in Writing and/or Understanding the Linux Kernel +============================================================================================= + + Juan-Mariano de Goyeneche + +The need for a document like this one became apparent in the +linux-kernel mailing list as the same questions, asking for pointers +to information, appeared again and again. + +Fortunately, as more and more people get to GNU/Linux, more and more +get interested in the Kernel. But reading the sources is not always +enough. It is easy to understand the code, but miss the concepts, the +philosophy and design decisions behind this code. + +Unfortunately, not many documents are available for beginners to +start. And, even if they exist, there was no "well-known" place which +kept track of them. These lines try to cover this lack. All documents +available on line known by the author are listed, while some reference +books are also mentioned. + +PLEASE, if you know any paper not listed here or write a new document, +send me an e-mail, and I'll include a reference to it here. Any +corrections, ideas or comments are also welcomed. + +The papers that follow are listed in no particular order. All are +cataloged with the following fields: the document's "Title", the +"Author"/s, the "URL" where they can be found, some "Keywords" helpful +when searching for specific topics, and a brief "Description" of the +Document. + +Enjoy! + +.. note:: + + The documents on each section of this document are ordered by its + published date, from the newest to the oldest. + +Docs at the Linux Kernel tree +----------------------------- + +The DocBook books should be built with ``make {htmldocs | psdocs | pdfdocs}``. +The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``. + + * Name: **linux/Documentation** + + :Author: Many. + :Location: Documentation/ + :Keywords: text files, Sphinx, DocBook. + :Description: Documentation that comes with the kernel sources, + inside the Documentation directory. Some pages from this document + (including this document itself) have been moved there, and might + be more up to date than the web version. + + * Title: **The Kernel Hacking HOWTO** + + :Author: Various Talented People, and Rusty. + :Location: Documentation/DocBook/kernel-hacking.tmpl + :Keywords: HOWTO, kernel contexts, deadlock, locking, modules, + symbols, return conventions. + :Description: From the Introduction: "Please understand that I + never wanted to write this document, being grossly underqualified, + but I always wanted to read it, and this was the only way. I + simply explain some best practices, and give reading entry-points + into the kernel sources. I avoid implementation details: that's + what the code is for, and I ignore whole tracts of useful + routines. This document assumes familiarity with C, and an + understanding of what the kernel is, and how it is used. It was + originally written for the 2.3 kernels, but nearly all of it + applies to 2.2 too; 2.0 is slightly different". + + * Title: **Linux Kernel Locking HOWTO** + + :Author: Various Talented People, and Rusty. + :Location: Documentation/DocBook/kernel-locking.tmpl + :Keywords: locks, locking, spinlock, semaphore, atomic, race + condition, bottom halves, tasklets, softirqs. + :Description: The title says it all: document describing the + locking system in the Linux Kernel either in uniprocessor or SMP + systems. + :Notes: "It was originally written for the later (>2.3.47) 2.3 + kernels, but most of it applies to 2.2 too; 2.0 is slightly + different". Freely redistributable under the conditions of the GNU + General Public License. + +On-line docs +------------ + + * Title: **Linux Kernel Mailing List Glossary** + + :Author: various + :URL: http://kernelnewbies.org/glossary/ + :Date: rolling version + :Keywords: glossary, terms, linux-kernel. + :Description: From the introduction: "This glossary is intended as + a brief description of some of the acronyms and terms you may hear + during discussion of the Linux kernel". + + * Title: **Tracing the Way of Data in a TCP Connection through the Linux Kernel** + + :Author: Richard Sailer + :URL: https://archive.org/details/linux_kernel_data_flow_short_paper + :Date: 2016 + :Keywords: Linux Kernel Networking, TCP, tracing, ftrace + :Description: A seminar paper explaining ftrace and how to use it for + understanding linux kernel internals, + illustrated at tracing the way of a TCP packet through the kernel. + :Abstract: *This short paper outlines the usage of ftrace a tracing framework + as a tool to understand a running Linux system. + Having obtained a trace-log a kernel hacker can read and understand + source code more determined and with context. + In a detailed example this approach is demonstrated in tracing + and the way of data in a TCP Connection through the kernel. + Finally this trace-log is used as base for more a exact conceptual + exploration and description of the Linux TCP/IP implementation.* + + * Title: **On submitting kernel Patches** + + :Author: Andi Kleen + :URL: http://halobates.de/on-submitting-kernel-patches.pdf + :Date: 2008 + :Keywords: patches, review process, types of submissions, basic rules, case studies + :Description: This paper gives several experience values on what types of patches + there are and how likley they get merged. + :Abstract: + [...]. This paper examines some common problems for + submitting larger changes and some strategies to avoid problems. + + * Title: **Overview of the Virtual File System** + + :Author: Richard Gooch. + :URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt + :Date: 2007 + :Keywords: VFS, File System, mounting filesystems, opening files, + dentries, dcache. + :Description: Brief introduction to the Linux Virtual File System. + What is it, how it works, operations taken when opening a file or + mounting a file system and description of important data + structures explaining the purpose of each of their entries. + + * Title: **Linux Device Drivers, Third Edition** + + :Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman + :URL: http://lwn.net/Kernel/LDD3/ + :Date: 2005 + :Description: A 600-page book covering the (2.6.10) driver + programming API and kernel hacking in general. Available under the + Creative Commons Attribution-ShareAlike 2.0 license. + :note: You can also :ref:`purchase a copy from O'Reilly or elsewhere `. + + * Title: **Writing an ALSA Driver** + + :Author: Takashi Iwai + :URL: http://www.alsa-project.org/~iwai/writing-an-alsa-driver/index.html + :Date: 2005 + :Keywords: ALSA, sound, soundcard, driver, lowlevel, hardware. + :Description: Advanced Linux Sound Architecture for developers, + both at kernel and user-level sides. ALSA is the Linux kernel + sound architecture in the 2.6 kernel version. + + * Title: **Linux PCMCIA Programmer's Guide** + + :Author: David Hinds. + :URL: http://pcmcia-cs.sourceforge.net/ftp/doc/PCMCIA-PROG.html + :Date: 2003 + :Keywords: PCMCIA. + :Description: "This document describes how to write kernel device + drivers for the Linux PCMCIA Card Services interface. It also + describes how to write user-mode utilities for communicating with + Card Services. + + * Title: **Linux Kernel Module Programming Guide** + + :Author: Ori Pomerantz. + :URL: http://tldp.org/LDP/lkmpg/2.6/html/index.html + :Date: 2001 + :Keywords: modules, GPL book, /proc, ioctls, system calls, + interrupt handlers . + :Description: Very nice 92 pages GPL book on the topic of modules + programming. Lots of examples. + + * Title: **Global spinlock list and usage** + + :Author: Rick Lindsley. + :URL: http://lse.sourceforge.net/lockhier/global-spin-lock + :Date: 2001 + :Keywords: spinlock. + :Description: This is an attempt to document both the existence and + usage of the spinlocks in the Linux 2.4.5 kernel. Comprehensive + list of spinlocks showing when they are used, which functions + access them, how each lock is acquired, under what conditions it + is held, whether interrupts can occur or not while it is held... + + * Title: **A Linux vm README** + + :Author: Kanoj Sarcar. + :URL: http://kos.enix.org/pub/linux-vmm.html + :Date: 2001 + :Keywords: virtual memory, mm, pgd, vma, page, page flags, page + cache, swap cache, kswapd. + :Description: Telegraphic, short descriptions and definitions + relating the Linux virtual memory implementation. + + * Title: **Video4linux Drivers, Part 1: Video-Capture Device** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/406 + :Date: 2000 + :Keywords: video4linux, driver, video capture, capture devices, + camera driver. + :Description: The title says it all. + + * Title: **Video4linux Drivers, Part 2: Video-capture Devices** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/429 + :Date: 2000 + :Keywords: video4linux, driver, video capture, capture devices, + camera driver, control, query capabilities, capability, facility. + :Description: The title says it all. + + * Title: **Linux IP Networking. A Guide to the Implementation and Modification of the Linux Protocol Stack.** + + :Author: Glenn Herrin. + :URL: http://www.cs.unh.edu/cnrg/gherrin + :Date: 2000 + :Keywords: network, networking, protocol, IP, UDP, TCP, connection, + socket, receiving, transmitting, forwarding, routing, packets, + modules, /proc, sk_buff, FIB, tags. + :Description: Excellent paper devoted to the Linux IP Networking, + explaining anything from the kernel's to the user space + configuration tools' code. Very good to get a general overview of + the kernel networking implementation and understand all steps + packets follow from the time they are received at the network + device till they are delivered to applications. The studied kernel + code is from 2.2.14 version. Provides code for a working packet + dropper example. + + * Title: **How To Make Sure Your Driver Will Work On The Power Macintosh** + + :Author: Paul Mackerras. + :URL: http://www.linux-mag.com/id/261 + :Date: 1999 + :Keywords: Mac, Power Macintosh, porting, drivers, compatibility. + :Description: The title says it all. + + * Title: **An Introduction to SCSI Drivers** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/284 + :Date: 1999 + :Keywords: SCSI, device, driver. + :Description: The title says it all. + + * Title: **Advanced SCSI Drivers And Other Tales** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/307 + :Date: 1999 + :Keywords: SCSI, device, driver, advanced. + :Description: The title says it all. + + * Title: **Writing Linux Mouse Drivers** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/330 + :Date: 1999 + :Keywords: mouse, driver, gpm. + :Description: The title says it all. + + * Title: **More on Mouse Drivers** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/356 + :Date: 1999 + :Keywords: mouse, driver, gpm, races, asynchronous I/O. + :Description: The title still says it all. + + * Title: **Writing Video4linux Radio Driver** + + :Author: Alan Cox. + :URL: http://www.linux-mag.com/id/381 + :Date: 1999 + :Keywords: video4linux, driver, radio, radio devices. + :Description: The title says it all. + + * Title: **I/O Event Handling Under Linux** + + :Author: Richard Gooch. + :URL: http://web.mit.edu/~yandros/doc/io-events.html + :Date: 1999 + :Keywords: IO, I/O, select(2), poll(2), FDs, aio_read(2), readiness + event queues. + :Description: From the Introduction: "I/O Event handling is about + how your Operating System allows you to manage a large number of + open files (file descriptors in UNIX/POSIX, or FDs) in your + application. You want the OS to notify you when FDs become active + (have data ready to be read or are ready for writing). Ideally you + want a mechanism that is scalable. This means a large number of + inactive FDs cost very little in memory and CPU time to manage". + + * Title: **(nearly) Complete Linux Loadable Kernel Modules. The definitive guide for hackers, virus coders and system administrators.** + + :Author: pragmatic/THC. + :URL: http://packetstormsecurity.org/docs/hack/LKM_HACKING.html + :Date: 1999 + :Keywords: syscalls, intercept, hide, abuse, symbol table. + :Description: Interesting paper on how to abuse the Linux kernel in + order to intercept and modify syscalls, make + files/directories/processes invisible, become root, hijack ttys, + write kernel modules based virus... and solutions for admins to + avoid all those abuses. + :Notes: For 2.0.x kernels. Gives guidances to port it to 2.2.x + kernels. + + * Name: **Linux Virtual File System** + + :Author: Peter J. Braam. + :URL: http://www.coda.cs.cmu.edu/doc/talks/linuxvfs/ + :Date: 1998 + :Keywords: slides, VFS, inode, superblock, dentry, dcache. + :Description: Set of slides, presumably from a presentation on the + Linux VFS layer. Covers version 2.1.x, with dentries and the + dcache. + + * Title: **The Venus kernel interface** + + :Author: Peter J. Braam. + :URL: http://www.coda.cs.cmu.edu/doc/html/kernel-venus-protocol.html + :Date: 1998 + :Keywords: coda, filesystem, venus, cache manager. + :Description: "This document describes the communication between + Venus and kernel level file system code needed for the operation + of the Coda filesystem. This version document is meant to describe + the current interface (version 1.0) as well as improvements we + envisage". + + * Title: **Design and Implementation of the Second Extended Filesystem** + + :Author: Rémy Card, Theodore Ts'o, Stephen Tweedie. + :URL: http://web.mit.edu/tytso/www/linux/ext2intro.html + :Date: 1998 + :Keywords: ext2, linux fs history, inode, directory, link, devices, + VFS, physical structure, performance, benchmarks, ext2fs library, + ext2fs tools, e2fsck. + :Description: Paper written by three of the top ext2 hackers. + Covers Linux filesystems history, ext2 motivation, ext2 features, + design, physical structure on disk, performance, benchmarks, + e2fsck's passes description... A must read! + :Notes: This paper was first published in the Proceedings of the + First Dutch International Symposium on Linux, ISBN 90-367-0385-9. + + * Title: **The Linux RAID-1, 4, 5 Code** + + :Author: Ingo Molnar, Gadi Oxman and Miguel de Icaza. + :URL: http://www.linuxjournal.com/article.php?sid=2391 + :Date: 1997 + :Keywords: RAID, MD driver. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *A description of the implementation of the RAID-1, + RAID-4 and RAID-5 personalities of the MD device driver in the + Linux kernel, providing users with high performance and reliable, + secondary-storage capability using software*. + + * Title: **Linux Kernel Hackers' Guide** + + :Author: Michael K. Johnson. + :URL: http://www.tldp.org/LDP/khg/HyperNews/get/khg.html + :Date: 1997 + :Keywords: device drivers, files, VFS, kernel interface, character vs + block devices, hardware interrupts, scsi, DMA, access to user memory, + memory allocation, timers. + :Description: A guide designed to help you get up to speed on the + concepts that are not intuitevly obvious, and to document the internal + structures of Linux. + + * Title: **Dynamic Kernels: Modularized Device Drivers** + + :Author: Alessandro Rubini. + :URL: http://www.linuxjournal.com/article.php?sid=1219 + :Date: 1996 + :Keywords: device driver, module, loading/unloading modules, + allocating resources. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This is the first of a series of four articles + co-authored by Alessandro Rubini and Georg Zezchwitz which present + a practical approach to writing Linux device drivers as kernel + loadable modules. This installment presents an introduction to the + topic, preparing the reader to understand next month's + installment*. + + * Title: **Dynamic Kernels: Discovery** + + :Author: Alessandro Rubini. + :URL: http://www.linuxjournal.com/article.php?sid=1220 + :Date: 1996 + :Keywords: character driver, init_module, clean_up module, + autodetection, mayor number, minor number, file operations, + open(), close(). + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This article, the second of four, introduces part of + the actual code to create custom module implementing a character + device driver. It describes the code for module initialization and + cleanup, as well as the open() and close() system calls*. + + * Title: **The Devil's in the Details** + + :Author: Georg v. Zezschwitz and Alessandro Rubini. + :URL: http://www.linuxjournal.com/article.php?sid=1221 + :Date: 1996 + :Keywords: read(), write(), select(), ioctl(), blocking/non + blocking mode, interrupt handler. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This article, the third of four on writing character + device drivers, introduces concepts of reading, writing, and using + ioctl-calls*. + + * Title: **Dissecting Interrupts and Browsing DMA** + + :Author: Alessandro Rubini and Georg v. Zezschwitz. + :URL: http://www.linuxjournal.com/article.php?sid=1222 + :Date: 1996 + :Keywords: interrupts, irqs, DMA, bottom halves, task queues. + :Description: Linux Journal Kernel Korner article. Here is its + :Abstract: *This is the fourth in a series of articles about + writing character device drivers as loadable kernel modules. This + month, we further investigate the field of interrupt handling. + Though it is conceptually simple, practical limitations and + constraints make this an ''interesting'' part of device driver + writing, and several different facilities have been provided for + different situations. We also investigate the complex topic of + DMA*. + + * Title: **Device Drivers Concluded** + + :Author: Georg v. Zezschwitz. + :URL: http://www.linuxjournal.com/article.php?sid=1287 + :Date: 1996 + :Keywords: address spaces, pages, pagination, page management, + demand loading, swapping, memory protection, memory mapping, mmap, + virtual memory areas (VMAs), vremap, PCI. + :Description: Finally, the above turned out into a five articles + series. This latest one's introduction reads: "This is the last of + five articles about character device drivers. In this final + section, Georg deals with memory mapping devices, beginning with + an overall description of the Linux memory management concepts". + + * Title: **Network Buffers And Memory Management** + + :Author: Alan Cox. + :URL: http://www.linuxjournal.com/article.php?sid=1312 + :Date: 1996 + :Keywords: sk_buffs, network devices, protocol/link layer + variables, network devices flags, transmit, receive, + configuration, multicast. + :Description: Linux Journal Kernel Korner. + :Abstract: *Writing a network device driver for Linux is fundamentally + simple---most of the complexity (other than talking to the + hardware) involves managing network packets in memory*. + + * Title: **Analysis of the Ext2fs structure** + + :Author: Louis-Dominique Dubeau. + :URL: http://teaching.csse.uwa.edu.au/units/CITS2002/fs-ext2/ + :Date: 1994 + :Keywords: ext2, filesystem, ext2fs. + :Description: Description of ext2's blocks, directories, inodes, + bitmaps, invariants... + +Published books +--------------- + + * Title: **Linux Treiber entwickeln** + + :Author: Jürgen Quade, Eva-Katharina Kunst + :Publisher: dpunkt.verlag + :Date: Oct 2015 (4th edition) + :Pages: 688 + :ISBN: 978-3-86490-288-8 + :Note: German. The third edition from 2011 is + much cheaper and still quite up-to-date. + + * Title: **Linux Kernel Networking: Implementation and Theory** + + :Author: Rami Rosen + :Publisher: Apress + :Date: December 22, 2013 + :Pages: 648 + :ISBN: 978-1430261964 + + * Title: **Embedded Linux Primer: A practical Real-World Approach, 2nd Edition** + + :Author: Christopher Hallinan + :Publisher: Pearson + :Date: November, 2010 + :Pages: 656 + :ISBN: 978-0137017836 + + * Title: **Linux Kernel Development, 3rd Edition** + + :Author: Robert Love + :Publisher: Addison-Wesley + :Date: July, 2010 + :Pages: 440 + :ISBN: 978-0672329463 + + * Title: **Essential Linux Device Drivers** + + :Author: Sreekrishnan Venkateswaran + :Published: Prentice Hall + :Date: April, 2008 + :Pages: 744 + :ISBN: 978-0132396554 + +.. _ldd3_published: + + * Title: **Linux Device Drivers, 3rd Edition** + + :Authors: Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman + :Publisher: O'Reilly & Associates + :Date: 2005 + :Pages: 636 + :ISBN: 0-596-00590-3 + :Notes: Further information in + http://www.oreilly.com/catalog/linuxdrive3/ + PDF format, URL: http://lwn.net/Kernel/LDD3/ + + * Title: **Linux Kernel Internals** + + :Author: Michael Beck + :Publisher: Addison-Wesley + :Date: 1997 + :ISBN: 0-201-33143-8 (second edition) + + * Title: **Programmation Linux 2.0 API systeme et fonctionnement du noyau** + + :Author: Remy Card, Eric Dumas, Franck Mevel + :Publisher: Eyrolles + :Date: 1997 + :Pages: 520 + :ISBN: 2-212-08932-5 + :Notes: French + + * Title: **The Design and Implementation of the 4.4 BSD UNIX Operating System** + + :Author: Marshall Kirk McKusick, Keith Bostic, Michael J. Karels, + John S. Quarterman + :Publisher: Addison-Wesley + :Date: 1996 + :ISBN: 0-201-54979-4 + + * Title: **Unix internals -- the new frontiers** + + :Author: Uresh Vahalia + :Publisher: Prentice Hall + :Date: 1996 + :Pages: 600 + :ISBN: 0-13-101908-2 + + * Title: **Programming for the real world - POSIX.4** + + :Author: Bill O. Gallmeister + :Publisher: O'Reilly & Associates, Inc + :Date: 1995 + :Pages: 552 + :ISBN: I-56592-074-0 + :Notes: Though not being directly about Linux, Linux aims to be + POSIX. Good reference. + + * Title: **UNIX Systems for Modern Architectures: Symmetric Multiprocessing and Caching for Kernel Programmers** + + :Author: Curt Schimmel + :Publisher: Addison Wesley + :Date: June, 1994 + :Pages: 432 + :ISBN: 0-201-63338-8 + + * Title: **The Design and Implementation of the 4.3 BSD UNIX Operating System** + + :Author: Samuel J. Leffler, Marshall Kirk McKusick, Michael J + Karels, John S. Quarterman + :Publisher: Addison-Wesley + :Date: 1989 (reprinted with corrections on October, 1990) + :ISBN: 0-201-06196-1 + + * Title: **The Design of the UNIX Operating System** + + :Author: Maurice J. Bach + :Publisher: Prentice Hall + :Date: 1986 + :Pages: 471 + :ISBN: 0-13-201757-1 + +Miscellaneous +------------- + + * Name: **Cross-Referencing Linux** + + :URL: http://lxr.free-electrons.com/ + :Keywords: Browsing source code. + :Description: Another web-based Linux kernel source code browser. + Lots of cross references to variables and functions. You can see + where they are defined and where they are used. + + * Name: **Linux Weekly News** + + :URL: http://lwn.net + :Keywords: latest kernel news. + :Description: The title says it all. There's a fixed kernel section + summarizing developers' work, bug fixes, new features and versions + produced during the week. Published every Thursday. + + * Name: **The home page of Linux-MM** + + :Author: The Linux-MM team. + :URL: http://linux-mm.org/ + :Keywords: memory management, Linux-MM, mm patches, TODO, docs, + mailing list. + :Description: Site devoted to Linux Memory Management development. + Memory related patches, HOWTOs, links, mm developers... Don't miss + it if you are interested in memory management development! + + * Name: **Kernel Newbies IRC Channel and Website** + + :URL: http://www.kernelnewbies.org + :Keywords: IRC, newbies, channel, asking doubts. + :Description: #kernelnewbies on irc.oftc.net. + #kernelnewbies is an IRC network dedicated to the 'newbie' + kernel hacker. The audience mostly consists of people who are + learning about the kernel, working on kernel projects or + professional kernel hackers that want to help less seasoned kernel + people. + #kernelnewbies is on the OFTC IRC Network. + Try irc.oftc.net as your server and then /join #kernelnewbies. + The kernelnewbies website also hosts articles, documents, FAQs... + + * Name: **linux-kernel mailing list archives and search engines** + + :URL: http://vger.kernel.org/vger-lists.html + :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html + :URL: http://groups.google.com/group/mlist.linux.kernel + :Keywords: linux-kernel, archives, search. + :Description: Some of the linux-kernel mailing list archivers. If + you have a better/another one, please let me know. + +------- + +Document last updated on Tue 2016-Sep-20 + +This document is based on: + http://www.dit.upm.es/~jmseyas/linux/kernel/hackers-docs.html diff --git a/Documentation/process/magic-number.rst b/Documentation/process/magic-number.rst new file mode 100644 index 000000000000..c74199f60c6c --- /dev/null +++ b/Documentation/process/magic-number.rst @@ -0,0 +1,164 @@ +Linux magic numbers +=================== + +This file is a registry of magic numbers which are in use. When you +add a magic number to a structure, you should also add it to this +file, since it is best if the magic numbers used by various structures +are unique. + +It is a **very** good idea to protect kernel data structures with magic +numbers. This allows you to check at run time whether (a) a structure +has been clobbered, or (b) you've passed the wrong structure to a +routine. This last is especially useful --- particularly when you are +passing pointers to structures via a void * pointer. The tty code, +for example, does this frequently to pass driver-specific and line +discipline-specific structures back and forth. + +The way to use magic numbers is to declare then at the beginning of +the structure, like so:: + + struct tty_ldisc { + int magic; + ... + }; + +Please follow this discipline when you are adding future enhancements +to the kernel! It has saved me countless hours of debugging, +especially in the screwy cases where an array has been overrun and +structures following the array have been overwritten. Using this +discipline, these cases get detected quickly and safely. + +Changelog:: + + Theodore Ts'o + 31 Mar 94 + + The magic table is current to Linux 2.1.55. + + Michael Chastain + + 22 Sep 1997 + + Now it should be up to date with Linux 2.1.112. Because + we are in feature freeze time it is very unlikely that + something will change before 2.2.x. The entries are + sorted by number field. + + Krzysztof G. Baranowski + + 29 Jul 1998 + + Updated the magic table to Linux 2.5.45. Right over the feature freeze, + but it is possible that some new magic numbers will sneak into the + kernel before 2.6.x yet. + + Petr Baudis + + 03 Nov 2002 + + Updated the magic table to Linux 2.5.74. + + Fabian Frederick + + 09 Jul 2003 + + +===================== ================ ======================== ========================================== +Magic Name Number Structure File +===================== ================ ======================== ========================================== +PG_MAGIC 'P' pg_{read,write}_hdr ``include/linux/pg.h`` +CMAGIC 0x0111 user ``include/linux/a.out.h`` +MKISS_DRIVER_MAGIC 0x04bf mkiss_channel ``drivers/net/mkiss.h`` +HDLC_MAGIC 0x239e n_hdlc ``drivers/char/n_hdlc.c`` +APM_BIOS_MAGIC 0x4101 apm_user ``arch/x86/kernel/apm_32.c`` +CYCLADES_MAGIC 0x4359 cyclades_port ``include/linux/cyclades.h`` +DB_MAGIC 0x4442 fc_info ``drivers/net/iph5526_novram.c`` +DL_MAGIC 0x444d fc_info ``drivers/net/iph5526_novram.c`` +FASYNC_MAGIC 0x4601 fasync_struct ``include/linux/fs.h`` +FF_MAGIC 0x4646 fc_info ``drivers/net/iph5526_novram.c`` +ISICOM_MAGIC 0x4d54 isi_port ``include/linux/isicom.h`` +PTY_MAGIC 0x5001 ``drivers/char/pty.c`` +PPP_MAGIC 0x5002 ppp ``include/linux/if_pppvar.h`` +SERIAL_MAGIC 0x5301 async_struct ``include/linux/serial.h`` +SSTATE_MAGIC 0x5302 serial_state ``include/linux/serial.h`` +SLIP_MAGIC 0x5302 slip ``drivers/net/slip.h`` +STRIP_MAGIC 0x5303 strip ``drivers/net/strip.c`` +X25_ASY_MAGIC 0x5303 x25_asy ``drivers/net/x25_asy.h`` +SIXPACK_MAGIC 0x5304 sixpack ``drivers/net/hamradio/6pack.h`` +AX25_MAGIC 0x5316 ax_disp ``drivers/net/mkiss.h`` +TTY_MAGIC 0x5401 tty_struct ``include/linux/tty.h`` +MGSL_MAGIC 0x5401 mgsl_info ``drivers/char/synclink.c`` +TTY_DRIVER_MAGIC 0x5402 tty_driver ``include/linux/tty_driver.h`` +MGSLPC_MAGIC 0x5402 mgslpc_info ``drivers/char/pcmcia/synclink_cs.c`` +TTY_LDISC_MAGIC 0x5403 tty_ldisc ``include/linux/tty_ldisc.h`` +USB_SERIAL_MAGIC 0x6702 usb_serial ``drivers/usb/serial/usb-serial.h`` +FULL_DUPLEX_MAGIC 0x6969 ``drivers/net/ethernet/dec/tulip/de2104x.c`` +USB_BLUETOOTH_MAGIC 0x6d02 usb_bluetooth ``drivers/usb/class/bluetty.c`` +RFCOMM_TTY_MAGIC 0x6d02 ``net/bluetooth/rfcomm/tty.c`` +USB_SERIAL_PORT_MAGIC 0x7301 usb_serial_port ``drivers/usb/serial/usb-serial.h`` +CG_MAGIC 0x00090255 ufs_cylinder_group ``include/linux/ufs_fs.h`` +RPORT_MAGIC 0x00525001 r_port ``drivers/char/rocket_int.h`` +LSEMAGIC 0x05091998 lse ``drivers/fc4/fc.c`` +GDTIOCTL_MAGIC 0x06030f07 gdth_iowr_str ``drivers/scsi/gdth_ioctl.h`` +RIEBL_MAGIC 0x09051990 ``drivers/net/atarilance.c`` +NBD_REQUEST_MAGIC 0x12560953 nbd_request ``include/linux/nbd.h`` +RED_MAGIC2 0x170fc2a5 (any) ``mm/slab.c`` +BAYCOM_MAGIC 0x19730510 baycom_state ``drivers/net/baycom_epp.c`` +ISDN_X25IFACE_MAGIC 0x1e75a2b9 isdn_x25iface_proto_data ``drivers/isdn/isdn_x25iface.h`` +ECP_MAGIC 0x21504345 cdkecpsig ``include/linux/cdk.h`` +LSOMAGIC 0x27091997 lso ``drivers/fc4/fc.c`` +LSMAGIC 0x2a3b4d2a ls ``drivers/fc4/fc.c`` +WANPIPE_MAGIC 0x414C4453 sdla_{dump,exec} ``include/linux/wanpipe.h`` +CS_CARD_MAGIC 0x43525553 cs_card ``sound/oss/cs46xx.c`` +LABELCL_MAGIC 0x4857434c labelcl_info_s ``include/asm/ia64/sn/labelcl.h`` +ISDN_ASYNC_MAGIC 0x49344C01 modem_info ``include/linux/isdn.h`` +CTC_ASYNC_MAGIC 0x49344C01 ctc_tty_info ``drivers/s390/net/ctctty.c`` +ISDN_NET_MAGIC 0x49344C02 isdn_net_local_s ``drivers/isdn/i4l/isdn_net_lib.h`` +SAVEKMSG_MAGIC2 0x4B4D5347 savekmsg ``arch/*/amiga/config.c`` +CS_STATE_MAGIC 0x4c4f4749 cs_state ``sound/oss/cs46xx.c`` +SLAB_C_MAGIC 0x4f17a36d kmem_cache ``mm/slab.c`` +COW_MAGIC 0x4f4f4f4d cow_header_v1 ``arch/um/drivers/ubd_user.c`` +I810_CARD_MAGIC 0x5072696E i810_card ``sound/oss/i810_audio.c`` +TRIDENT_CARD_MAGIC 0x5072696E trident_card ``sound/oss/trident.c`` +ROUTER_MAGIC 0x524d4157 wan_device [in ``wanrouter.h`` pre 3.9] +SAVEKMSG_MAGIC1 0x53415645 savekmsg ``arch/*/amiga/config.c`` +GDA_MAGIC 0x58464552 gda ``arch/mips/include/asm/sn/gda.h`` +RED_MAGIC1 0x5a2cf071 (any) ``mm/slab.c`` +EEPROM_MAGIC_VALUE 0x5ab478d2 lanai_dev ``drivers/atm/lanai.c`` +HDLCDRV_MAGIC 0x5ac6e778 hdlcdrv_state ``include/linux/hdlcdrv.h`` +PCXX_MAGIC 0x5c6df104 channel ``drivers/char/pcxx.h`` +KV_MAGIC 0x5f4b565f kernel_vars_s ``arch/mips/include/asm/sn/klkernvars.h`` +I810_STATE_MAGIC 0x63657373 i810_state ``sound/oss/i810_audio.c`` +TRIDENT_STATE_MAGIC 0x63657373 trient_state ``sound/oss/trident.c`` +M3_CARD_MAGIC 0x646e6f50 m3_card ``sound/oss/maestro3.c`` +FW_HEADER_MAGIC 0x65726F66 fw_header ``drivers/atm/fore200e.h`` +SLOT_MAGIC 0x67267321 slot ``drivers/hotplug/cpqphp.h`` +SLOT_MAGIC 0x67267322 slot ``drivers/hotplug/acpiphp.h`` +LO_MAGIC 0x68797548 nbd_device ``include/linux/nbd.h`` +OPROFILE_MAGIC 0x6f70726f super_block ``drivers/oprofile/oprofilefs.h`` +M3_STATE_MAGIC 0x734d724d m3_state ``sound/oss/maestro3.c`` +VMALLOC_MAGIC 0x87654320 snd_alloc_track ``sound/core/memory.c`` +KMALLOC_MAGIC 0x87654321 snd_alloc_track ``sound/core/memory.c`` +PWC_MAGIC 0x89DC10AB pwc_device ``drivers/usb/media/pwc.h`` +NBD_REPLY_MAGIC 0x96744668 nbd_reply ``include/linux/nbd.h`` +ENI155_MAGIC 0xa54b872d midway_eprom ``drivers/atm/eni.h`` +CODA_MAGIC 0xC0DAC0DA coda_file_info ``fs/coda/coda_fs_i.h`` +DPMEM_MAGIC 0xc0ffee11 gdt_pci_sram ``drivers/scsi/gdth.h`` +YAM_MAGIC 0xF10A7654 yam_port ``drivers/net/hamradio/yam.c`` +CCB_MAGIC 0xf2691ad2 ccb ``drivers/scsi/ncr53c8xx.c`` +QUEUE_MAGIC_FREE 0xf7e1c9a3 queue_entry ``drivers/scsi/arm/queue.c`` +QUEUE_MAGIC_USED 0xf7e1cc33 queue_entry ``drivers/scsi/arm/queue.c`` +HTB_CMAGIC 0xFEFAFEF1 htb_class ``net/sched/sch_htb.c`` +NMI_MAGIC 0x48414d4d455201 nmi_s ``arch/mips/include/asm/sn/nmi.h`` +===================== ================ ======================== ========================================== + +Note that there are also defined special per-driver magic numbers in sound +memory management. See ``include/sound/sndmagic.h`` for complete list of them. Many +OSS sound drivers have their magic numbers constructed from the soundcard PCI +ID - these are not listed here as well. + +IrDA subsystem also uses large number of own magic numbers, see +``include/net/irda/irda.h`` for a complete list of them. + +HFS is another larger user of magic numbers - you can find them in +``fs/hfs/hfs.h``. diff --git a/Documentation/process/management-style.rst b/Documentation/process/management-style.rst new file mode 100644 index 000000000000..dea2e66c9a10 --- /dev/null +++ b/Documentation/process/management-style.rst @@ -0,0 +1,288 @@ +.. _managementstyle: + +Linux kernel management style +============================= + +This is a short document describing the preferred (or made up, depending +on who you ask) management style for the linux kernel. It's meant to +mirror the CodingStyle document to some degree, and mainly written to +avoid answering [#f1]_ the same (or similar) questions over and over again. + +Management style is very personal and much harder to quantify than +simple coding style rules, so this document may or may not have anything +to do with reality. It started as a lark, but that doesn't mean that it +might not actually be true. You'll have to decide for yourself. + +Btw, when talking about "kernel manager", it's all about the technical +lead persons, not the people who do traditional management inside +companies. If you sign purchase orders or you have any clue about the +budget of your group, you're almost certainly not a kernel manager. +These suggestions may or may not apply to you. + +First off, I'd suggest buying "Seven Habits of Highly Effective +People", and NOT read it. Burn it, it's a great symbolic gesture. + +.. [#f1] This document does so not so much by answering the question, but by + making it painfully obvious to the questioner that we don't have a clue + to what the answer is. + +Anyway, here goes: + +.. _decisions: + +1) Decisions +------------ + +Everybody thinks managers make decisions, and that decision-making is +important. The bigger and more painful the decision, the bigger the +manager must be to make it. That's very deep and obvious, but it's not +actually true. + +The name of the game is to **avoid** having to make a decision. In +particular, if somebody tells you "choose (a) or (b), we really need you +to decide on this", you're in trouble as a manager. The people you +manage had better know the details better than you, so if they come to +you for a technical decision, you're screwed. You're clearly not +competent to make that decision for them. + +(Corollary:if the people you manage don't know the details better than +you, you're also screwed, although for a totally different reason. +Namely that you are in the wrong job, and that **they** should be managing +your brilliance instead). + +So the name of the game is to **avoid** decisions, at least the big and +painful ones. Making small and non-consequential decisions is fine, and +makes you look like you know what you're doing, so what a kernel manager +needs to do is to turn the big and painful ones into small things where +nobody really cares. + +It helps to realize that the key difference between a big decision and a +small one is whether you can fix your decision afterwards. Any decision +can be made small by just always making sure that if you were wrong (and +you **will** be wrong), you can always undo the damage later by +backtracking. Suddenly, you get to be doubly managerial for making +**two** inconsequential decisions - the wrong one **and** the right one. + +And people will even see that as true leadership (*cough* bullshit +*cough*). + +Thus the key to avoiding big decisions becomes to just avoiding to do +things that can't be undone. Don't get ushered into a corner from which +you cannot escape. A cornered rat may be dangerous - a cornered manager +is just pitiful. + +It turns out that since nobody would be stupid enough to ever really let +a kernel manager have huge fiscal responsibility **anyway**, it's usually +fairly easy to backtrack. Since you're not going to be able to waste +huge amounts of money that you might not be able to repay, the only +thing you can backtrack on is a technical decision, and there +back-tracking is very easy: just tell everybody that you were an +incompetent nincompoop, say you're sorry, and undo all the worthless +work you had people work on for the last year. Suddenly the decision +you made a year ago wasn't a big decision after all, since it could be +easily undone. + +It turns out that some people have trouble with this approach, for two +reasons: + + - admitting you were an idiot is harder than it looks. We all like to + maintain appearances, and coming out in public to say that you were + wrong is sometimes very hard indeed. + - having somebody tell you that what you worked on for the last year + wasn't worthwhile after all can be hard on the poor lowly engineers + too, and while the actual **work** was easy enough to undo by just + deleting it, you may have irrevocably lost the trust of that + engineer. And remember: "irrevocable" was what we tried to avoid in + the first place, and your decision ended up being a big one after + all. + +Happily, both of these reasons can be mitigated effectively by just +admitting up-front that you don't have a friggin' clue, and telling +people ahead of the fact that your decision is purely preliminary, and +might be the wrong thing. You should always reserve the right to change +your mind, and make people very **aware** of that. And it's much easier +to admit that you are stupid when you haven't **yet** done the really +stupid thing. + +Then, when it really does turn out to be stupid, people just roll their +eyes and say "Oops, he did it again". + +This preemptive admission of incompetence might also make the people who +actually do the work also think twice about whether it's worth doing or +not. After all, if **they** aren't certain whether it's a good idea, you +sure as hell shouldn't encourage them by promising them that what they +work on will be included. Make them at least think twice before they +embark on a big endeavor. + +Remember: they'd better know more about the details than you do, and +they usually already think they have the answer to everything. The best +thing you can do as a manager is not to instill confidence, but rather a +healthy dose of critical thinking on what they do. + +Btw, another way to avoid a decision is to plaintively just whine "can't +we just do both?" and look pitiful. Trust me, it works. If it's not +clear which approach is better, they'll eventually figure it out. The +answer may end up being that both teams get so frustrated by the +situation that they just give up. + +That may sound like a failure, but it's usually a sign that there was +something wrong with both projects, and the reason the people involved +couldn't decide was that they were both wrong. You end up coming up +smelling like roses, and you avoided yet another decision that you could +have screwed up on. + + +2) People +--------- + +Most people are idiots, and being a manager means you'll have to deal +with it, and perhaps more importantly, that **they** have to deal with +**you**. + +It turns out that while it's easy to undo technical mistakes, it's not +as easy to undo personality disorders. You just have to live with +theirs - and yours. + +However, in order to prepare yourself as a kernel manager, it's best to +remember not to burn any bridges, bomb any innocent villagers, or +alienate too many kernel developers. It turns out that alienating people +is fairly easy, and un-alienating them is hard. Thus "alienating" +immediately falls under the heading of "not reversible", and becomes a +no-no according to :ref:`decisions`. + +There's just a few simple rules here: + + (1) don't call people d*ckheads (at least not in public) + (2) learn how to apologize when you forgot rule (1) + +The problem with #1 is that it's very easy to do, since you can say +"you're a d*ckhead" in millions of different ways [#f2]_, sometimes without +even realizing it, and almost always with a white-hot conviction that +you are right. + +And the more convinced you are that you are right (and let's face it, +you can call just about **anybody** a d*ckhead, and you often **will** be +right), the harder it ends up being to apologize afterwards. + +To solve this problem, you really only have two options: + + - get really good at apologies + - spread the "love" out so evenly that nobody really ends up feeling + like they get unfairly targeted. Make it inventive enough, and they + might even be amused. + +The option of being unfailingly polite really doesn't exist. Nobody will +trust somebody who is so clearly hiding his true character. + +.. [#f2] Paul Simon sang "Fifty Ways to Leave Your Lover", because quite + frankly, "A Million Ways to Tell a Developer He Is a D*ckhead" doesn't + scan nearly as well. But I'm sure he thought about it. + + +3) People II - the Good Kind +---------------------------- + +While it turns out that most people are idiots, the corollary to that is +sadly that you are one too, and that while we can all bask in the secure +knowledge that we're better than the average person (let's face it, +nobody ever believes that they're average or below-average), we should +also admit that we're not the sharpest knife around, and there will be +other people that are less of an idiot than you are. + +Some people react badly to smart people. Others take advantage of them. + +Make sure that you, as a kernel maintainer, are in the second group. +Suck up to them, because they are the people who will make your job +easier. In particular, they'll be able to make your decisions for you, +which is what the game is all about. + +So when you find somebody smarter than you are, just coast along. Your +management responsibilities largely become ones of saying "Sounds like a +good idea - go wild", or "That sounds good, but what about xxx?". The +second version in particular is a great way to either learn something +new about "xxx" or seem **extra** managerial by pointing out something the +smarter person hadn't thought about. In either case, you win. + +One thing to look out for is to realize that greatness in one area does +not necessarily translate to other areas. So you might prod people in +specific directions, but let's face it, they might be good at what they +do, and suck at everything else. The good news is that people tend to +naturally gravitate back to what they are good at, so it's not like you +are doing something irreversible when you **do** prod them in some +direction, just don't push too hard. + + +4) Placing blame +---------------- + +Things will go wrong, and people want somebody to blame. Tag, you're it. + +It's not actually that hard to accept the blame, especially if people +kind of realize that it wasn't **all** your fault. Which brings us to the +best way of taking the blame: do it for another guy. You'll feel good +for taking the fall, he'll feel good about not getting blamed, and the +guy who lost his whole 36GB porn-collection because of your incompetence +will grudgingly admit that you at least didn't try to weasel out of it. + +Then make the developer who really screwed up (if you can find him) know +**in_private** that he screwed up. Not just so he can avoid it in the +future, but so that he knows he owes you one. And, perhaps even more +importantly, he's also likely the person who can fix it. Because, let's +face it, it sure ain't you. + +Taking the blame is also why you get to be manager in the first place. +It's part of what makes people trust you, and allow you the potential +glory, because you're the one who gets to say "I screwed up". And if +you've followed the previous rules, you'll be pretty good at saying that +by now. + + +5) Things to avoid +------------------ + +There's one thing people hate even more than being called "d*ckhead", +and that is being called a "d*ckhead" in a sanctimonious voice. The +first you can apologize for, the second one you won't really get the +chance. They likely will no longer be listening even if you otherwise +do a good job. + +We all think we're better than anybody else, which means that when +somebody else puts on airs, it **really** rubs us the wrong way. You may +be morally and intellectually superior to everybody around you, but +don't try to make it too obvious unless you really **intend** to irritate +somebody [#f3]_. + +Similarly, don't be too polite or subtle about things. Politeness easily +ends up going overboard and hiding the problem, and as they say, "On the +internet, nobody can hear you being subtle". Use a big blunt object to +hammer the point in, because you can't really depend on people getting +your point otherwise. + +Some humor can help pad both the bluntness and the moralizing. Going +overboard to the point of being ridiculous can drive a point home +without making it painful to the recipient, who just thinks you're being +silly. It can thus help get through the personal mental block we all +have about criticism. + +.. [#f3] Hint: internet newsgroups that are not directly related to your work + are great ways to take out your frustrations at other people. Write + insulting posts with a sneer just to get into a good flame every once in + a while, and you'll feel cleansed. Just don't crap too close to home. + + +6) Why me? +---------- + +Since your main responsibility seems to be to take the blame for other +peoples mistakes, and make it painfully obvious to everybody else that +you're incompetent, the obvious question becomes one of why do it in the +first place? + +First off, while you may or may not get screaming teenage girls (or +boys, let's not be judgmental or sexist here) knocking on your dressing +room door, you **will** get an immense feeling of personal accomplishment +for being "in charge". Never mind the fact that you're really leading +by trying to keep up with everybody else and running after them as fast +as you can. Everybody will still think you're the person in charge. + +It's a great job if you can hack it. diff --git a/Documentation/process/stable-api-nonsense.rst b/Documentation/process/stable-api-nonsense.rst new file mode 100644 index 000000000000..24f5aeecee91 --- /dev/null +++ b/Documentation/process/stable-api-nonsense.rst @@ -0,0 +1,205 @@ +.. _stable_api_nonsense: + +The Linux Kernel Driver Interface +================================== + +(all of your questions answered and then some) + +Greg Kroah-Hartman + +This is being written to try to explain why Linux **does not have a binary +kernel interface, nor does it have a stable kernel interface**. + +.. note:: + + Please realize that this article describes the **in kernel** interfaces, not + the kernel to userspace interfaces. + + The kernel to userspace interface is the one that application programs use, + the syscall interface. That interface is **very** stable over time, and + will not break. I have old programs that were built on a pre 0.9something + kernel that still work just fine on the latest 2.6 kernel release. + That interface is the one that users and application programmers can count + on being stable. + + +Executive Summary +----------------- +You think you want a stable kernel interface, but you really do not, and +you don't even know it. What you want is a stable running driver, and +you get that only if your driver is in the main kernel tree. You also +get lots of other good benefits if your driver is in the main kernel +tree, all of which has made Linux into such a strong, stable, and mature +operating system which is the reason you are using it in the first +place. + + +Intro +----- + +It's only the odd person who wants to write a kernel driver that needs +to worry about the in-kernel interfaces changing. For the majority of +the world, they neither see this interface, nor do they care about it at +all. + +First off, I'm not going to address **any** legal issues about closed +source, hidden source, binary blobs, source wrappers, or any other term +that describes kernel drivers that do not have their source code +released under the GPL. Please consult a lawyer if you have any legal +questions, I'm a programmer and hence, I'm just going to be describing +the technical issues here (not to make light of the legal issues, they +are real, and you do need to be aware of them at all times.) + +So, there are two main topics here, binary kernel interfaces and stable +kernel source interfaces. They both depend on each other, but we will +discuss the binary stuff first to get it out of the way. + + +Binary Kernel Interface +----------------------- +Assuming that we had a stable kernel source interface for the kernel, a +binary interface would naturally happen too, right? Wrong. Please +consider the following facts about the Linux kernel: + + - Depending on the version of the C compiler you use, different kernel + data structures will contain different alignment of structures, and + possibly include different functions in different ways (putting + functions inline or not.) The individual function organization + isn't that important, but the different data structure padding is + very important. + + - Depending on what kernel build options you select, a wide range of + different things can be assumed by the kernel: + + - different structures can contain different fields + - Some functions may not be implemented at all, (i.e. some locks + compile away to nothing for non-SMP builds.) + - Memory within the kernel can be aligned in different ways, + depending on the build options. + + - Linux runs on a wide range of different processor architectures. + There is no way that binary drivers from one architecture will run + on another architecture properly. + +Now a number of these issues can be addressed by simply compiling your +module for the exact specific kernel configuration, using the same exact +C compiler that the kernel was built with. This is sufficient if you +want to provide a module for a specific release version of a specific +Linux distribution. But multiply that single build by the number of +different Linux distributions and the number of different supported +releases of the Linux distribution and you quickly have a nightmare of +different build options on different releases. Also realize that each +Linux distribution release contains a number of different kernels, all +tuned to different hardware types (different processor types and +different options), so for even a single release you will need to create +multiple versions of your module. + +Trust me, you will go insane over time if you try to support this kind +of release, I learned this the hard way a long time ago... + + +Stable Kernel Source Interfaces +------------------------------- + +This is a much more "volatile" topic if you talk to people who try to +keep a Linux kernel driver that is not in the main kernel tree up to +date over time. + +Linux kernel development is continuous and at a rapid pace, never +stopping to slow down. As such, the kernel developers find bugs in +current interfaces, or figure out a better way to do things. If they do +that, they then fix the current interfaces to work better. When they do +so, function names may change, structures may grow or shrink, and +function parameters may be reworked. If this happens, all of the +instances of where this interface is used within the kernel are fixed up +at the same time, ensuring that everything continues to work properly. + +As a specific examples of this, the in-kernel USB interfaces have +undergone at least three different reworks over the lifetime of this +subsystem. These reworks were done to address a number of different +issues: + + - A change from a synchronous model of data streams to an asynchronous + one. This reduced the complexity of a number of drivers and + increased the throughput of all USB drivers such that we are now + running almost all USB devices at their maximum speed possible. + - A change was made in the way data packets were allocated from the + USB core by USB drivers so that all drivers now needed to provide + more information to the USB core to fix a number of documented + deadlocks. + +This is in stark contrast to a number of closed source operating systems +which have had to maintain their older USB interfaces over time. This +provides the ability for new developers to accidentally use the old +interfaces and do things in improper ways, causing the stability of the +operating system to suffer. + +In both of these instances, all developers agreed that these were +important changes that needed to be made, and they were made, with +relatively little pain. If Linux had to ensure that it will preserve a +stable source interface, a new interface would have been created, and +the older, broken one would have had to be maintained over time, leading +to extra work for the USB developers. Since all Linux USB developers do +their work on their own time, asking programmers to do extra work for no +gain, for free, is not a possibility. + +Security issues are also very important for Linux. When a +security issue is found, it is fixed in a very short amount of time. A +number of times this has caused internal kernel interfaces to be +reworked to prevent the security problem from occurring. When this +happens, all drivers that use the interfaces were also fixed at the +same time, ensuring that the security problem was fixed and could not +come back at some future time accidentally. If the internal interfaces +were not allowed to change, fixing this kind of security problem and +insuring that it could not happen again would not be possible. + +Kernel interfaces are cleaned up over time. If there is no one using a +current interface, it is deleted. This ensures that the kernel remains +as small as possible, and that all potential interfaces are tested as +well as they can be (unused interfaces are pretty much impossible to +test for validity.) + + +What to do +---------- + +So, if you have a Linux kernel driver that is not in the main kernel +tree, what are you, a developer, supposed to do? Releasing a binary +driver for every different kernel version for every distribution is a +nightmare, and trying to keep up with an ever changing kernel interface +is also a rough job. + +Simple, get your kernel driver into the main kernel tree (remember we +are talking about GPL released drivers here, if your code doesn't fall +under this category, good luck, you are on your own here, you leech +.) If your +driver is in the tree, and a kernel interface changes, it will be fixed +up by the person who did the kernel change in the first place. This +ensures that your driver is always buildable, and works over time, with +very little effort on your part. + +The very good side effects of having your driver in the main kernel tree +are: + + - The quality of the driver will rise as the maintenance costs (to the + original developer) will decrease. + - Other developers will add features to your driver. + - Other people will find and fix bugs in your driver. + - Other people will find tuning opportunities in your driver. + - Other people will update the driver for you when external interface + changes require it. + - The driver automatically gets shipped in all Linux distributions + without having to ask the distros to add it. + +As Linux supports a larger number of different devices "out of the box" +than any other operating system, and it supports these devices on more +different processor architectures than any other operating system, this +proven type of development model must be doing something right :) + + + +------ + +Thanks to Randy Dunlap, Andrew Morton, David Brownell, Hanna Linder, +Robert Love, and Nishanth Aravamudan for their review and comments on +early drafts of this paper. diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst new file mode 100644 index 000000000000..4d82e31b7958 --- /dev/null +++ b/Documentation/process/stable-kernel-rules.rst @@ -0,0 +1,181 @@ +.. _stable_kernel_rules: + +Everything you ever wanted to know about Linux -stable releases +=============================================================== + +Rules on what kind of patches are accepted, and which ones are not, into the +"-stable" tree: + + - It must be obviously correct and tested. + - It cannot be bigger than 100 lines, with context. + - It must fix only one thing. + - It must fix a real bug that bothers people (not a, "This could be a + problem..." type thing). + - It must fix a problem that causes a build error (but not for things + marked CONFIG_BROKEN), an oops, a hang, data corruption, a real + security issue, or some "oh, that's not good" issue. In short, something + critical. + - Serious issues as reported by a user of a distribution kernel may also + be considered if they fix a notable performance or interactivity issue. + As these fixes are not as obvious and have a higher risk of a subtle + regression they should only be submitted by a distribution kernel + maintainer and include an addendum linking to a bugzilla entry if it + exists and additional information on the user-visible impact. + - New device IDs and quirks are also accepted. + - No "theoretical race condition" issues, unless an explanation of how the + race can be exploited is also provided. + - It cannot contain any "trivial" fixes in it (spelling changes, + whitespace cleanups, etc). + - It must follow the + :ref:`Documentation/SubmittingPatches ` + rules. + - It or an equivalent fix must already exist in Linus' tree (upstream). + + +Procedure for submitting patches to the -stable tree +---------------------------------------------------- + + - If the patch covers files in net/ or drivers/net please follow netdev stable + submission guidelines as described in + Documentation/networking/netdev-FAQ.txt + - Security patches should not be handled (solely) by the -stable review + process but should follow the procedures in + :ref:`Documentation/SecurityBugs `. + +For all other submissions, choose one of the following procedures +----------------------------------------------------------------- + +.. _option_1: + +Option 1 +******** + +To have the patch automatically included in the stable tree, add the tag + +.. code-block:: none + + Cc: stable@vger.kernel.org + +in the sign-off area. Once the patch is merged it will be applied to +the stable tree without anything else needing to be done by the author +or subsystem maintainer. + +.. _option_2: + +Option 2 +******** + +After the patch has been merged to Linus' tree, send an email to +stable@vger.kernel.org containing the subject of the patch, the commit ID, +why you think it should be applied, and what kernel version you wish it to +be applied to. + +.. _option_3: + +Option 3 +******** + +Send the patch, after verifying that it follows the above rules, to +stable@vger.kernel.org. You must note the upstream commit ID in the +changelog of your submission, as well as the kernel version you wish +it to be applied to. + +:ref:`option_1` is **strongly** preferred, is the easiest and most common. +:ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed +worthy at the time it is applied to a public git tree (for instance, because +it deserves more regression testing first). :ref:`option_3` is especially +useful if the patch needs some special handling to apply to an older kernel +(e.g., if API's have changed in the meantime). + +Note that for :ref:`option_3`, if the patch deviates from the original +upstream patch (for example because it had to be backported) this must be very +clearly documented and justified in the patch description. + +The upstream commit ID must be specified with a separate line above the commit +text, like this: + +.. code-block:: none + + commit upstream. + +Additionally, some patches submitted via Option 1 may have additional patch +prerequisites which can be cherry-picked. This can be specified in the following +format in the sign-off area: + +.. code-block:: none + + Cc: # 3.3.x: a1f84a3: sched: Check for idle + Cc: # 3.3.x: 1b9508f: sched: Rate-limit newidle + Cc: # 3.3.x: fd21073: sched: Fix affinity logic + Cc: # 3.3.x + Signed-off-by: Ingo Molnar + +The tag sequence has the meaning of: + +.. code-block:: none + + git cherry-pick a1f84a3 + git cherry-pick 1b9508f + git cherry-pick fd21073 + git cherry-pick + +Also, some patches may have kernel version prerequisites. This can be +specified in the following format in the sign-off area: + +.. code-block:: none + + Cc: # 3.3.x- + +The tag has the meaning of: + +.. code-block:: none + + git cherry-pick + +For each "-stable" tree starting with the specified version. + +Following the submission: + + - The sender will receive an ACK when the patch has been accepted into the + queue, or a NAK if the patch is rejected. This response might take a few + days, according to the developer's schedules. + - If accepted, the patch will be added to the -stable queue, for review by + other developers and by the relevant subsystem maintainer. + + +Review cycle +------------ + + - When the -stable maintainers decide for a review cycle, the patches will be + sent to the review committee, and the maintainer of the affected area of + the patch (unless the submitter is the maintainer of the area) and CC: to + the linux-kernel mailing list. + - The review committee has 48 hours in which to ACK or NAK the patch. + - If the patch is rejected by a member of the committee, or linux-kernel + members object to the patch, bringing up issues that the maintainers and + members did not realize, the patch will be dropped from the queue. + - At the end of the review cycle, the ACKed patches will be added to the + latest -stable release, and a new -stable release will happen. + - Security patches will be accepted into the -stable tree directly from the + security kernel team, and not go through the normal review cycle. + Contact the kernel security team for more details on this procedure. + +Trees +----- + + - The queues of patches, for both completed versions and in progress + versions can be found at: + + http://git.kernel.org/?p=linux/kernel/git/stable/stable-queue.git + + - The finalized and tagged releases of all stable kernels can be found + in separate branches per version at: + + http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git + + +Review committee +---------------- + + - This is made up of a number of kernel developers who have volunteered for + this task, and a few that haven't. diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst new file mode 100644 index 000000000000..894289b22b15 --- /dev/null +++ b/Documentation/process/submit-checklist.rst @@ -0,0 +1,120 @@ +.. _submitchecklist: + +Linux Kernel patch submission checklist +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Here are some basic things that developers should do if they want to see their +kernel patch submissions accepted more quickly. + +These are all above and beyond the documentation that is provided in +:ref:`Documentation/SubmittingPatches ` +and elsewhere regarding submitting Linux kernel patches. + + +1) If you use a facility then #include the file that defines/declares + that facility. Don't depend on other header files pulling in ones + that you use. + +2) Builds cleanly: + + a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and + ``=n``. No ``gcc`` warnings/errors, no linker warnings/errors. + + b) Passes ``allnoconfig``, ``allmodconfig`` + + c) Builds successfully when using ``O=builddir`` + +3) Builds on multiple CPU architectures by using local cross-compile tools + or some other build farm. + +4) ppc64 is a good architecture for cross-compilation checking because it + tends to use ``unsigned long`` for 64-bit quantities. + +5) Check your patch for general style as detailed in + :ref:`Documentation/CodingStyle `. + Check for trivial violations with the patch style checker prior to + submission (``scripts/checkpatch.pl``). + You should be able to justify all violations that remain in + your patch. + +6) Any new or modified ``CONFIG`` options don't muck up the config menu. + +7) All new ``Kconfig`` options have help text. + +8) Has been carefully reviewed with respect to relevant ``Kconfig`` + combinations. This is very hard to get right with testing -- brainpower + pays off here. + +9) Check cleanly with sparse. + +10) Use ``make checkstack`` and ``make namespacecheck`` and fix any problems + that they find. + + .. note:: + + ``checkstack`` does not point out problems explicitly, + but any one function that uses more than 512 bytes on the stack is a + candidate for change. + +11) Include :ref:`kernel-doc ` to document global kernel APIs. + (Not required for static functions, but OK there also.) Use + ``make htmldocs`` or ``make pdfdocs`` to check the + :ref:`kernel-doc ` and fix any issues. + +12) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, + ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, + ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, + ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` all + simultaneously enabled. + +13) Has been build- and runtime tested with and without ``CONFIG_SMP`` and + ``CONFIG_PREEMPT.`` + +14) If the patch affects IO/Disk, etc: has been tested with and without + ``CONFIG_LBDAF.`` + +15) All codepaths have been exercised with all lockdep features enabled. + +16) All new ``/proc`` entries are documented under ``Documentation/`` + +17) All new kernel boot parameters are documented in + ``Documentation/kernel-parameters.txt``. + +18) All new module parameters are documented with ``MODULE_PARM_DESC()`` + +19) All new userspace interfaces are documented in ``Documentation/ABI/``. + See ``Documentation/ABI/README`` for more information. + Patches that change userspace interfaces should be CCed to + linux-api@vger.kernel.org. + +20) Check that it all passes ``make headers_check``. + +21) Has been checked with injection of at least slab and page-allocation + failures. See ``Documentation/fault-injection/``. + + If the new code is substantial, addition of subsystem-specific fault + injection might be appropriate. + +22) Newly-added code has been compiled with ``gcc -W`` (use + ``make EXTRA_CFLAGS=-W``). This will generate lots of noise, but is good + for finding bugs like "warning: comparison between signed and unsigned". + +23) Tested after it has been merged into the -mm patchset to make sure + that it still works with all of the other queued patches and various + changes in the VM, VFS, and other subsystems. + +24) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a + comment in the source code that explains the logic of what they are doing + and why. + +25) If any ioctl's are added by the patch, then also update + ``Documentation/ioctl/ioctl-number.txt``. + +26) If your modified source code depends on or uses any of the kernel + APIs or features that are related to the following ``Kconfig`` symbols, + then test multiple builds with the related ``Kconfig`` symbols disabled + and/or ``=m`` (if that option is available) [not all of these at the + same time, just various/random combinations of them]: + + ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, + ``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``). diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst new file mode 100644 index 000000000000..252b77a23fad --- /dev/null +++ b/Documentation/process/submitting-drivers.rst @@ -0,0 +1,183 @@ +.. _submittingdrivers: + +Submitting Drivers For The Linux Kernel +======================================= + +This document is intended to explain how to submit device drivers to the +various kernel trees. Note that if you are interested in video card drivers +you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org +(http://x.org/) instead. + +Also read the Documentation/SubmittingPatches document. + + +Allocating Device Numbers +------------------------- + +Major and minor numbers for block and character devices are allocated +by the Linux assigned name and number authority (currently this is +Torben Mathiasen). The site is http://www.lanana.org/. This +also deals with allocating numbers for devices that are not going to +be submitted to the mainstream kernel. +See Documentation/devices.txt for more information on this. + +If you don't use assigned numbers then when your device is submitted it will +be given an assigned number even if that is different from values you may +have shipped to customers before. + +Who To Submit Drivers To +------------------------ + +Linux 2.0: + No new drivers are accepted for this kernel tree. + +Linux 2.2: + No new drivers are accepted for this kernel tree. + +Linux 2.4: + If the code area has a general maintainer then please submit it to + the maintainer listed in MAINTAINERS in the kernel file. If the + maintainer does not respond or you cannot find the appropriate + maintainer then please contact Willy Tarreau . + +Linux 2.6 and upper: + The same rules apply as 2.4 except that you should follow linux-kernel + to track changes in API's. The final contact point for Linux 2.6+ + submissions is Andrew Morton. + +What Criteria Determine Acceptance +---------------------------------- + +Licensing: + The code must be released to us under the + GNU General Public License. We don't insist on any kind + of exclusive GPL licensing, and if you wish the driver + to be useful to other communities such as BSD you may well + wish to release under multiple licenses. + See accepted licenses at include/linux/module.h + +Copyright: + The copyright owner must agree to use of GPL. + It's best if the submitter and copyright owner + are the same person/entity. If not, the name of + the person/entity authorizing use of GPL should be + listed in case it's necessary to verify the will of + the copyright owner. + +Interfaces: + If your driver uses existing interfaces and behaves like + other drivers in the same class it will be much more likely + to be accepted than if it invents gratuitous new ones. + If you need to implement a common API over Linux and NT + drivers do it in userspace. + +Code: + Please use the Linux style of code formatting as documented + in :ref:`Documentation/CodingStyle `. + If you have sections of code + that need to be in other formats, for example because they + are shared with a windows driver kit and you want to + maintain them just once separate them out nicely and note + this fact. + +Portability: + Pointers are not always 32bits, not all computers are little + endian, people do not all have floating point and you + shouldn't use inline x86 assembler in your driver without + careful thought. Pure x86 drivers generally are not popular. + If you only have x86 hardware it is hard to test portability + but it is easy to make sure the code can easily be made + portable. + +Clarity: + It helps if anyone can see how to fix the driver. It helps + you because you get patches not bug reports. If you submit a + driver that intentionally obfuscates how the hardware works + it will go in the bitbucket. + +PM support: + Since Linux is used on many portable and desktop systems, your + driver is likely to be used on such a system and therefore it + should support basic power management by implementing, if + necessary, the .suspend and .resume methods used during the + system-wide suspend and resume transitions. You should verify + that your driver correctly handles the suspend and resume, but + if you are unable to ensure that, please at least define the + .suspend method returning the -ENOSYS ("Function not + implemented") error. You should also try to make sure that your + driver uses as little power as possible when it's not doing + anything. For the driver testing instructions see + Documentation/power/drivers-testing.txt and for a relatively + complete overview of the power management issues related to + drivers see Documentation/power/devices.txt . + +Control: + In general if there is active maintenance of a driver by + the author then patches will be redirected to them unless + they are totally obvious and without need of checking. + If you want to be the contact and update point for the + driver it is a good idea to state this in the comments, + and include an entry in MAINTAINERS for your driver. + +What Criteria Do Not Determine Acceptance +----------------------------------------- + +Vendor: + Being the hardware vendor and maintaining the driver is + often a good thing. If there is a stable working driver from + other people already in the tree don't expect 'we are the + vendor' to get your driver chosen. Ideally work with the + existing driver author to build a single perfect driver. + +Author: + It doesn't matter if a large Linux company wrote the driver, + or you did. Nobody has any special access to the kernel + tree. Anyone who tells you otherwise isn't telling the + whole story. + + +Resources +--------- + +Linux kernel master tree: + ftp.\ *country_code*\ .kernel.org:/pub/linux/kernel/... + + where *country_code* == your country code, such as + **us**, **uk**, **fr**, etc. + + http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git + +Linux kernel mailing list: + linux-kernel@vger.kernel.org + [mail majordomo@vger.kernel.org to subscribe] + +Linux Device Drivers, Third Edition (covers 2.6.10): + http://lwn.net/Kernel/LDD3/ (free version) + +LWN.net: + Weekly summary of kernel development activity - http://lwn.net/ + + 2.6 API changes: + + http://lwn.net/Articles/2.6-kernel-api/ + + Porting drivers from prior kernels to 2.6: + + http://lwn.net/Articles/driver-porting/ + +KernelNewbies: + Documentation and assistance for new kernel programmers + + http://kernelnewbies.org/ + +Linux USB project: + http://www.linux-usb.org/ + +How to NOT write kernel driver by Arjan van de Ven: + http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf + +Kernel Janitor: + http://kernelnewbies.org/KernelJanitors + +GIT, Fast Version Control System: + http://git-scm.com/ diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst new file mode 100644 index 000000000000..4cc20b2c6df3 --- /dev/null +++ b/Documentation/process/submitting-patches.rst @@ -0,0 +1,840 @@ +.. _submittingpatches: + +How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds +========================================================================================= + +For a person or company who wishes to submit a change to the Linux +kernel, the process can sometimes be daunting if you're not familiar +with "the system." This text is a collection of suggestions which +can greatly increase the chances of your change being accepted. + +This document contains a large number of suggestions in a relatively terse +format. For detailed information on how the kernel development process +works, see :ref:`Documentation/process `. +Also, read :ref:`Documentation/SubmitChecklist ` +for a list of items to check before +submitting code. If you are submitting a driver, also read +:ref:`Documentation/SubmittingDrivers `; +for device tree binding patches, read +Documentation/devicetree/bindings/submitting-patches.txt. + +Many of these steps describe the default behavior of the ``git`` version +control system; if you use ``git`` to prepare your patches, you'll find much +of the mechanical work done for you, though you'll still need to prepare +and document a sensible set of patches. In general, use of ``git`` will make +your life as a kernel developer easier. + +Creating and Sending your Change +******************************** + + +0) Obtain a current source tree +------------------------------- + +If you do not have a repository with the current kernel source handy, use +``git`` to obtain one. You'll want to start with the mainline repository, +which can be grabbed with:: + + git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git + +Note, however, that you may not want to develop against the mainline tree +directly. Most subsystem maintainers run their own trees and want to see +patches prepared against those trees. See the **T:** entry for the subsystem +in the MAINTAINERS file to find that tree, or simply ask the maintainer if +the tree is not listed there. + +It is still possible to download kernel releases via tarballs (as described +in the next section), but that is the hard way to do kernel development. + +1) ``diff -up`` +--------------- + +If you must generate your patches by hand, use ``diff -up`` or ``diff -uprN`` +to create patches. Git generates patches in this form by default; if +you're using ``git``, you can skip this section entirely. + +All changes to the Linux kernel occur in the form of patches, as +generated by :manpage:`diff(1)`. When creating your patch, make sure to +create it in "unified diff" format, as supplied by the ``-u`` argument +to :manpage:`diff(1)`. +Also, please use the ``-p`` argument which shows which C function each +change is in - that makes the resultant ``diff`` a lot easier to read. +Patches should be based in the root kernel source directory, +not in any lower subdirectory. + +To create a patch for a single file, it is often sufficient to do:: + + SRCTREE= linux + MYFILE= drivers/net/mydriver.c + + cd $SRCTREE + cp $MYFILE $MYFILE.orig + vi $MYFILE # make your change + cd .. + diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch + +To create a patch for multiple files, you should unpack a "vanilla", +or unmodified kernel source tree, and generate a ``diff`` against your +own source tree. For example:: + + MYSRC= /devel/linux + + tar xvfz linux-3.19.tar.gz + mv linux-3.19 linux-3.19-vanilla + diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ + linux-3.19-vanilla $MYSRC > /tmp/patch + +``dontdiff`` is a list of files which are generated by the kernel during +the build process, and should be ignored in any :manpage:`diff(1)`-generated +patch. + +Make sure your patch does not include any extra files which do not +belong in a patch submission. Make sure to review your patch -after- +generating it with :manpage:`diff(1)`, to ensure accuracy. + +If your changes produce a lot of deltas, you need to split them into +individual patches which modify things in logical stages; see +:ref:`split_changes`. This will facilitate review by other kernel developers, +very important if you want your patch accepted. + +If you're using ``git``, ``git rebase -i`` can help you with this process. If +you're not using ``git``, ``quilt`` +is another popular alternative. + +.. _describe_changes: + +2) Describe your changes +------------------------ + +Describe your problem. Whether your patch is a one-line bug fix or +5000 lines of a new feature, there must be an underlying problem that +motivated you to do this work. Convince the reviewer that there is a +problem worth fixing and that it makes sense for them to read past the +first paragraph. + +Describe user-visible impact. Straight up crashes and lockups are +pretty convincing, but not all bugs are that blatant. Even if the +problem was spotted during code review, describe the impact you think +it can have on users. Keep in mind that the majority of Linux +installations run kernels from secondary stable trees or +vendor/product-specific trees that cherry-pick only specific patches +from upstream, so include anything that could help route your change +downstream: provoking circumstances, excerpts from dmesg, crash +descriptions, performance regressions, latency spikes, lockups, etc. + +Quantify optimizations and trade-offs. If you claim improvements in +performance, memory consumption, stack footprint, or binary size, +include numbers that back them up. But also describe non-obvious +costs. Optimizations usually aren't free but trade-offs between CPU, +memory, and readability; or, when it comes to heuristics, between +different workloads. Describe the expected downsides of your +optimization so that the reviewer can weigh costs against benefits. + +Once the problem is established, describe what you are actually doing +about it in technical detail. It's important to describe the change +in plain English for the reviewer to verify that the code is behaving +as you intend it to. + +The maintainer will thank you if you write your patch description in a +form which can be easily pulled into Linux's source code management +system, ``git``, as a "commit log". See :ref:`explicit_in_reply_to`. + +Solve only one problem per patch. If your description starts to get +long, that's a sign that you probably need to split up your patch. +See :ref:`split_changes`. + +When you submit or resubmit a patch or patch series, include the +complete patch description and justification for it. Don't just +say that this is version N of the patch (series). Don't expect the +subsystem maintainer to refer back to earlier patch versions or referenced +URLs to find the patch description and put that into the patch. +I.e., the patch (series) and its description should be self-contained. +This benefits both the maintainers and reviewers. Some reviewers +probably didn't even receive earlier versions of the patch. + +Describe your changes in imperative mood, e.g. "make xyzzy do frotz" +instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy +to do frotz", as if you are giving orders to the codebase to change +its behaviour. + +If the patch fixes a logged bug entry, refer to that bug entry by +number and URL. If the patch follows from a mailing list discussion, +give a URL to the mailing list archive; use the https://lkml.kernel.org/ +redirector with a ``Message-Id``, to ensure that the links cannot become +stale. + +However, try to make your explanation understandable without external +resources. In addition to giving a URL to a mailing list archive or +bug, summarize the relevant points of the discussion that led to the +patch as submitted. + +If you want to refer to a specific commit, don't just refer to the +SHA-1 ID of the commit. Please also include the oneline summary of +the commit, to make it easier for reviewers to know what it is about. +Example:: + + Commit e21d2170f36602ae2708 ("video: remove unnecessary + platform_set_drvdata()") removed the unnecessary + platform_set_drvdata(), but left the variable "dev" unused, + delete it. + +You should also be sure to use at least the first twelve characters of the +SHA-1 ID. The kernel repository holds a *lot* of objects, making +collisions with shorter IDs a real possibility. Bear in mind that, even if +there is no collision with your six-character ID now, that condition may +change five years from now. + +If your patch fixes a bug in a specific commit, e.g. you found an issue using +``git bisect``, please use the 'Fixes:' tag with the first 12 characters of +the SHA-1 ID, and the one line summary. For example:: + + Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()") + +The following ``git config`` settings can be used to add a pretty format for +outputting the above style in the ``git log`` or ``git show`` commands:: + + [core] + abbrev = 12 + [pretty] + fixes = Fixes: %h (\"%s\") + +.. _split_changes: + +3) Separate your changes +------------------------ + +Separate each **logical change** into a separate patch. + +For example, if your changes include both bug fixes and performance +enhancements for a single driver, separate those changes into two +or more patches. If your changes include an API update, and a new +driver which uses that new API, separate those into two patches. + +On the other hand, if you make a single change to numerous files, +group those changes into a single patch. Thus a single logical change +is contained within a single patch. + +The point to remember is that each patch should make an easily understood +change that can be verified by reviewers. Each patch should be justifiable +on its own merits. + +If one patch depends on another patch in order for a change to be +complete, that is OK. Simply note **"this patch depends on patch X"** +in your patch description. + +When dividing your change into a series of patches, take special care to +ensure that the kernel builds and runs properly after each patch in the +series. Developers using ``git bisect`` to track down a problem can end up +splitting your patch series at any point; they will not thank you if you +introduce bugs in the middle. + +If you cannot condense your patch set into a smaller set of patches, +then only post say 15 or so at a time and wait for review and integration. + + + +4) Style-check your changes +--------------------------- + +Check your patch for basic style violations, details of which can be +found in +:ref:`Documentation/CodingStyle `. +Failure to do so simply wastes +the reviewers time and will get your patch rejected, probably +without even being read. + +One significant exception is when moving code from one file to +another -- in this case you should not modify the moved code at all in +the same patch which moves it. This clearly delineates the act of +moving the code and your changes. This greatly aids review of the +actual differences and allows tools to better track the history of +the code itself. + +Check your patches with the patch style checker prior to submission +(scripts/checkpatch.pl). Note, though, that the style checker should be +viewed as a guide, not as a replacement for human judgment. If your code +looks better with a violation then its probably best left alone. + +The checker reports at three levels: + - ERROR: things that are very likely to be wrong + - WARNING: things requiring careful review + - CHECK: things requiring thought + +You should be able to justify all violations that remain in your +patch. + + +5) Select the recipients for your patch +--------------------------------------- + +You should always copy the appropriate subsystem maintainer(s) on any patch +to code that they maintain; look through the MAINTAINERS file and the +source code revision history to see who those maintainers are. The +script scripts/get_maintainer.pl can be very useful at this step. If you +cannot find a maintainer for the subsystem you are working on, Andrew +Morton (akpm@linux-foundation.org) serves as a maintainer of last resort. + +You should also normally choose at least one mailing list to receive a copy +of your patch set. linux-kernel@vger.kernel.org functions as a list of +last resort, but the volume on that list has caused a number of developers +to tune it out. Look in the MAINTAINERS file for a subsystem-specific +list; your patch will probably get more attention there. Please do not +spam unrelated lists, though. + +Many kernel-related lists are hosted on vger.kernel.org; you can find a +list of them at http://vger.kernel.org/vger-lists.html. There are +kernel-related lists hosted elsewhere as well, though. + +Do not send more than 15 patches at once to the vger mailing lists!!! + +Linus Torvalds is the final arbiter of all changes accepted into the +Linux kernel. His e-mail address is . +He gets a lot of e-mail, and, at this point, very few patches go through +Linus directly, so typically you should do your best to -avoid- +sending him e-mail. + +If you have a patch that fixes an exploitable security bug, send that patch +to security@kernel.org. For severe bugs, a short embargo may be considered +to allow distributors to get the patch out to users; in such cases, +obviously, the patch should not be sent to any public lists. + +Patches that fix a severe bug in a released kernel should be directed +toward the stable maintainers by putting a line like this:: + + Cc: stable@vger.kernel.org + +into the sign-off area of your patch (note, NOT an email recipient). You +should also read +:ref:`Documentation/stable_kernel_rules.txt ` +in addition to this file. + +Note, however, that some subsystem maintainers want to come to their own +conclusions on which patches should go to the stable trees. The networking +maintainer, in particular, would rather not see individual developers +adding lines like the above to their patches. + +If changes affect userland-kernel interfaces, please send the MAN-PAGES +maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at +least a notification of the change, so that some information makes its way +into the manual pages. User-space API changes should also be copied to +linux-api@vger.kernel.org. + +For small patches you may want to CC the Trivial Patch Monkey +trivial@kernel.org which collects "trivial" patches. Have a look +into the MAINTAINERS file for its current manager. + +Trivial patches must qualify for one of the following rules: + +- Spelling fixes in documentation +- Spelling fixes for errors which could break :manpage:`grep(1)` +- Warning fixes (cluttering with useless warnings is bad) +- Compilation fixes (only if they are actually correct) +- Runtime fixes (only if they actually fix things) +- Removing use of deprecated functions/macros +- Contact detail and documentation fixes +- Non-portable code replaced by portable code (even in arch-specific, + since people copy, as long as it's trivial) +- Any fix by the author/maintainer of the file (ie. patch monkey + in re-transmission mode) + + + +6) No MIME, no links, no compression, no attachments. Just plain text +---------------------------------------------------------------------- + +Linus and other kernel developers need to be able to read and comment +on the changes you are submitting. It is important for a kernel +developer to be able to "quote" your changes, using standard e-mail +tools, so that they may comment on specific portions of your code. + +For this reason, all patches should be submitted by e-mail "inline". + +.. warning:: + + Be wary of your editor's word-wrap corrupting your patch, + if you choose to cut-n-paste your patch. + +Do not attach the patch as a MIME attachment, compressed or not. +Many popular e-mail applications will not always transmit a MIME +attachment as plain text, making it impossible to comment on your +code. A MIME attachment also takes Linus a bit more time to process, +decreasing the likelihood of your MIME-attached change being accepted. + +Exception: If your mailer is mangling patches then someone may ask +you to re-send them using MIME. + +See :ref:`Documentation/email-clients.txt ` +for hints about configuring your e-mail client so that it sends your patches +untouched. + +7) E-mail size +-------------- + +Large changes are not appropriate for mailing lists, and some +maintainers. If your patch, uncompressed, exceeds 300 kB in size, +it is preferred that you store your patch on an Internet-accessible +server, and provide instead a URL (link) pointing to your patch. But note +that if your patch exceeds 300 kB, it almost certainly needs to be broken up +anyway. + +8) Respond to review comments +----------------------------- + +Your patch will almost certainly get comments from reviewers on ways in +which the patch can be improved. You must respond to those comments; +ignoring reviewers is a good way to get ignored in return. Review comments +or questions that do not lead to a code change should almost certainly +bring about a comment or changelog entry so that the next reviewer better +understands what is going on. + +Be sure to tell the reviewers what changes you are making and to thank them +for their time. Code review is a tiring and time-consuming process, and +reviewers sometimes get grumpy. Even in that case, though, respond +politely and address the problems they have pointed out. + + +9) Don't get discouraged - or impatient +--------------------------------------- + +After you have submitted your change, be patient and wait. Reviewers are +busy people and may not get to your patch right away. + +Once upon a time, patches used to disappear into the void without comment, +but the development process works more smoothly than that now. You should +receive comments within a week or so; if that does not happen, make sure +that you have sent your patches to the right place. Wait for a minimum of +one week before resubmitting or pinging reviewers - possibly longer during +busy times like merge windows. + + +10) Include PATCH in the subject +-------------------------------- + +Due to high e-mail traffic to Linus, and to linux-kernel, it is common +convention to prefix your subject line with [PATCH]. This lets Linus +and other kernel developers more easily distinguish patches from other +e-mail discussions. + + + +11) Sign your work +------------------ + +To improve tracking of who did what, especially with patches that can +percolate to their final resting place in the kernel through several +layers of maintainers, we've introduced a "sign-off" procedure on +patches that are being emailed around. + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below: + +Developer's Certificate of Origin 1.1 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + +then you just add a line saying:: + + Signed-off-by: Random J Developer + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +Some people also put extra tags at the end. They'll just be ignored for +now, but you can do this to mark internal company procedures or just +point out some special detail about the sign-off. + +If you are a subsystem or branch maintainer, sometimes you need to slightly +modify patches you receive in order to merge them, because the code is not +exactly the same in your tree and the submitters'. If you stick strictly to +rule (c), you should ask the submitter to rediff, but this is a totally +counter-productive waste of time and energy. Rule (b) allows you to adjust +the code, but then it is very impolite to change one submitter's code and +make him endorse your bugs. To solve this problem, it is recommended that +you add a line between the last Signed-off-by header and yours, indicating +the nature of your changes. While there is nothing mandatory about this, it +seems like prepending the description with your mail and/or name, all +enclosed in square brackets, is noticeable enough to make it obvious that +you are responsible for last-minute changes. Example:: + + Signed-off-by: Random J Developer + [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] + Signed-off-by: Lucky K Maintainer + +This practice is particularly helpful if you maintain a stable branch and +want at the same time to credit the author, track changes, merge the fix, +and protect the submitter from complaints. Note that under no circumstances +can you change the author's identity (the From header), as it is the one +which appears in the changelog. + +Special note to back-porters: It seems to be a common and useful practice +to insert an indication of the origin of a patch at the top of the commit +message (just after the subject line) to facilitate tracking. For instance, +here's what we see in a 3.x-stable release:: + + Date: Tue Oct 7 07:26:38 2014 -0400 + + libata: Un-break ATA blacklist + + commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. + +And here's what might appear in an older kernel once a patch is backported:: + + Date: Tue May 13 22:12:27 2008 +0200 + + wireless, airo: waitbusy() won't delay + + [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] + +Whatever the format, this information provides a valuable help to people +tracking your trees, and to people trying to troubleshoot bugs in your +tree. + + +12) When to use Acked-by: and Cc: +--------------------------------- + +The Signed-off-by: tag indicates that the signer was involved in the +development of the patch, or that he/she was in the patch's delivery path. + +If a person was not directly involved in the preparation or handling of a +patch but wishes to signify and record their approval of it then they can +ask to have an Acked-by: line added to the patch's changelog. + +Acked-by: is often used by the maintainer of the affected code when that +maintainer neither contributed to nor forwarded the patch. + +Acked-by: is not as formal as Signed-off-by:. It is a record that the acker +has at least reviewed the patch and has indicated acceptance. Hence patch +mergers will sometimes manually convert an acker's "yep, looks good to me" +into an Acked-by: (but note that it is usually better to ask for an +explicit ack). + +Acked-by: does not necessarily indicate acknowledgement of the entire patch. +For example, if a patch affects multiple subsystems and has an Acked-by: from +one subsystem maintainer then this usually indicates acknowledgement of just +the part which affects that maintainer's code. Judgement should be used here. +When in doubt people should refer to the original discussion in the mailing +list archives. + +If a person has had the opportunity to comment on a patch, but has not +provided such comments, you may optionally add a ``Cc:`` tag to the patch. +This is the only tag which might be added without an explicit action by the +person it names - but it should indicate that this person was copied on the +patch. This tag documents that potentially interested parties +have been included in the discussion. + + +13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: +-------------------------------------------------------------------------- + +The Reported-by tag gives credit to people who find bugs and report them and it +hopefully inspires them to help us again in the future. Please note that if +the bug was reported in private, then ask for permission first before using the +Reported-by tag. + +A Tested-by: tag indicates that the patch has been successfully tested (in +some environment) by the person named. This tag informs maintainers that +some testing has been performed, provides a means to locate testers for +future patches, and ensures credit for the testers. + +Reviewed-by:, instead, indicates that the patch has been reviewed and found +acceptable according to the Reviewer's Statement: + +Reviewer's statement of oversight +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By offering my Reviewed-by: tag, I state that: + + (a) I have carried out a technical review of this patch to + evaluate its appropriateness and readiness for inclusion into + the mainline kernel. + + (b) Any problems, concerns, or questions relating to the patch + have been communicated back to the submitter. I am satisfied + with the submitter's response to my comments. + + (c) While there may be things that could be improved with this + submission, I believe that it is, at this time, (1) a + worthwhile modification to the kernel, and (2) free of known + issues which would argue against its inclusion. + + (d) While I have reviewed the patch and believe it to be sound, I + do not (unless explicitly stated elsewhere) make any + warranties or guarantees that it will achieve its stated + purpose or function properly in any given situation. + +A Reviewed-by tag is a statement of opinion that the patch is an +appropriate modification of the kernel without any remaining serious +technical issues. Any interested reviewer (who has done the work) can +offer a Reviewed-by tag for a patch. This tag serves to give credit to +reviewers and to inform maintainers of the degree of review which has been +done on the patch. Reviewed-by: tags, when supplied by reviewers known to +understand the subject area and to perform thorough reviews, will normally +increase the likelihood of your patch getting into the kernel. + +A Suggested-by: tag indicates that the patch idea is suggested by the person +named and ensures credit to the person for the idea. Please note that this +tag should not be added without the reporter's permission, especially if the +idea was not posted in a public forum. That said, if we diligently credit our +idea reporters, they will, hopefully, be inspired to help us again in the +future. + +A Fixes: tag indicates that the patch fixes an issue in a previous commit. It +is used to make it easy to determine where a bug originated, which can help +review a bug fix. This tag also assists the stable kernel team in determining +which stable kernel versions should receive your fix. This is the preferred +method for indicating a bug fixed by the patch. See :ref:`describe_changes` +for more details. + + +14) The canonical patch format +------------------------------ + +This section describes how the patch itself should be formatted. Note +that, if you have your patches stored in a ``git`` repository, proper patch +formatting can be had with ``git format-patch``. The tools cannot create +the necessary text, though, so read the instructions below anyway. + +The canonical patch subject line is:: + + Subject: [PATCH 001/123] subsystem: summary phrase + +The canonical patch message body contains the following: + + - A ``from`` line specifying the patch author (only needed if the person + sending the patch is not the author). + + - An empty line. + + - The body of the explanation, line wrapped at 75 columns, which will + be copied to the permanent changelog to describe this patch. + + - The ``Signed-off-by:`` lines, described above, which will + also go in the changelog. + + - A marker line containing simply ``---``. + + - Any additional comments not suitable for the changelog. + + - The actual patch (``diff`` output). + +The Subject line format makes it very easy to sort the emails +alphabetically by subject line - pretty much any email reader will +support that - since because the sequence number is zero-padded, +the numerical and alphabetic sort is the same. + +The ``subsystem`` in the email's Subject should identify which +area or subsystem of the kernel is being patched. + +The ``summary phrase`` in the email's Subject should concisely +describe the patch which that email contains. The ``summary +phrase`` should not be a filename. Do not use the same ``summary +phrase`` for every patch in a whole patch series (where a ``patch +series`` is an ordered sequence of multiple, related patches). + +Bear in mind that the ``summary phrase`` of your email becomes a +globally-unique identifier for that patch. It propagates all the way +into the ``git`` changelog. The ``summary phrase`` may later be used in +developer discussions which refer to the patch. People will want to +google for the ``summary phrase`` to read discussion regarding that +patch. It will also be the only thing that people may quickly see +when, two or three months later, they are going through perhaps +thousands of patches using tools such as ``gitk`` or ``git log +--oneline``. + +For these reasons, the ``summary`` must be no more than 70-75 +characters, and it must describe both what the patch changes, as well +as why the patch might be necessary. It is challenging to be both +succinct and descriptive, but that is what a well-written summary +should do. + +The ``summary phrase`` may be prefixed by tags enclosed in square +brackets: "Subject: [PATCH ...] ". The tags are +not considered part of the summary phrase, but describe how the patch +should be treated. Common tags might include a version descriptor if +the multiple versions of the patch have been sent out in response to +comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for +comments. If there are four patches in a patch series the individual +patches may be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures +that developers understand the order in which the patches should be +applied and that they have reviewed or applied all of the patches in +the patch series. + +A couple of example Subjects:: + + Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching + Subject: [PATCH v2 01/27] x86: fix eflags tracking + +The ``from`` line must be the very first line in the message body, +and has the form: + + From: Original Author + +The ``from`` line specifies who will be credited as the author of the +patch in the permanent changelog. If the ``from`` line is missing, +then the ``From:`` line from the email header will be used to determine +the patch author in the changelog. + +The explanation body will be committed to the permanent source +changelog, so should make sense to a competent reader who has long +since forgotten the immediate details of the discussion that might +have led to this patch. Including symptoms of the failure which the +patch addresses (kernel log messages, oops messages, etc.) is +especially useful for people who might be searching the commit logs +looking for the applicable patch. If a patch fixes a compile failure, +it may not be necessary to include _all_ of the compile failures; just +enough that it is likely that someone searching for the patch can find +it. As in the ``summary phrase``, it is important to be both succinct as +well as descriptive. + +The ``---`` marker line serves the essential purpose of marking for patch +handling tools where the changelog message ends. + +One good use for the additional comments after the ``---`` marker is for +a ``diffstat``, to show what files have changed, and the number of +inserted and deleted lines per file. A ``diffstat`` is especially useful +on bigger patches. Other comments relevant only to the moment or the +maintainer, not suitable for the permanent changelog, should also go +here. A good example of such comments might be ``patch changelogs`` +which describe what has changed between the v1 and v2 version of the +patch. + +If you are going to include a ``diffstat`` after the ``---`` marker, please +use ``diffstat`` options ``-p 1 -w 70`` so that filenames are listed from +the top of the kernel source tree and don't use too much horizontal +space (easily fit in 80 columns, maybe with some indentation). (``git`` +generates appropriate diffstats by default.) + +See more details on the proper patch format in the following +references. + +.. _explicit_in_reply_to: + +15) Explicit In-Reply-To headers +-------------------------------- + +It can be helpful to manually add In-Reply-To: headers to a patch +(e.g., when using ``git send-email``) to associate the patch with +previous relevant discussion, e.g. to link a bug fix to the email with +the bug report. However, for a multi-patch series, it is generally +best to avoid using In-Reply-To: to link to older versions of the +series. This way multiple versions of the patch don't become an +unmanageable forest of references in email clients. If a link is +helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in +the cover email text) to link to an earlier version of the patch series. + + +16) Sending ``git pull`` requests +--------------------------------- + +If you have a series of patches, it may be most convenient to have the +maintainer pull them directly into the subsystem repository with a +``git pull`` operation. Note, however, that pulling patches from a developer +requires a higher degree of trust than taking patches from a mailing list. +As a result, many subsystem maintainers are reluctant to take pull +requests, especially from new, unknown developers. If in doubt you can use +the pull request as the cover letter for a normal posting of the patch +series, giving the maintainer the option of using either. + +A pull request should have [GIT] or [PULL] in the subject line. The +request itself should include the repository name and the branch of +interest on a single line; it should look something like:: + + Please pull from + + git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus + + to get these changes: + +A pull request should also include an overall message saying what will be +included in the request, a ``git shortlog`` listing of the patches +themselves, and a ``diffstat`` showing the overall effect of the patch series. +The easiest way to get all this information together is, of course, to let +``git`` do it for you with the ``git request-pull`` command. + +Some maintainers (including Linus) want to see pull requests from signed +commits; that increases their confidence that the request actually came +from you. Linus, in particular, will not pull from public hosting sites +like GitHub in the absence of a signed tag. + +The first step toward creating such tags is to make a GNUPG key and get it +signed by one or more core kernel developers. This step can be hard for +new developers, but there is no way around it. Attending conferences can +be a good way to find developers who can sign your key. + +Once you have prepared a patch series in ``git`` that you wish to have somebody +pull, create a signed tag with ``git tag -s``. This will create a new tag +identifying the last commit in the series and containing a signature +created with your private key. You will also have the opportunity to add a +changelog-style message to the tag; this is an ideal place to describe the +effects of the pull request as a whole. + +If the tree the maintainer will be pulling from is not the repository you +are working from, don't forget to push the signed tag explicitly to the +public tree. + +When generating your pull request, use the signed tag as the target. A +command like this will do the trick:: + + git request-pull master git://my.public.tree/linux.git my-signed-tag + + +REFERENCES +********** + +Andrew Morton, "The perfect patch" (tpp). + + +Jeff Garzik, "Linux kernel patch submission format". + + +Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". + + + + + + + + + + + + +NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! + + +Kernel Documentation/CodingStyle: + :ref:`Documentation/CodingStyle ` + +Linus Torvalds's mail on the canonical patch format: + + +Andi Kleen, "On submitting kernel patches" + Some strategies to get difficult or controversial changes in. + + http://halobates.de/on-submitting-patches.pdf diff --git a/Documentation/process/volatile-considered-harmful.rst b/Documentation/process/volatile-considered-harmful.rst new file mode 100644 index 000000000000..e0d042af386c --- /dev/null +++ b/Documentation/process/volatile-considered-harmful.rst @@ -0,0 +1,122 @@ +Why the "volatile" type class should not be used +------------------------------------------------ + +C programmers have often taken volatile to mean that the variable could be +changed outside of the current thread of execution; as a result, they are +sometimes tempted to use it in kernel code when shared data structures are +being used. In other words, they have been known to treat volatile types +as a sort of easy atomic variable, which they are not. The use of volatile in +kernel code is almost never correct; this document describes why. + +The key point to understand with regard to volatile is that its purpose is +to suppress optimization, which is almost never what one really wants to +do. In the kernel, one must protect shared data structures against +unwanted concurrent access, which is very much a different task. The +process of protecting against unwanted concurrency will also avoid almost +all optimization-related problems in a more efficient way. + +Like volatile, the kernel primitives which make concurrent access to data +safe (spinlocks, mutexes, memory barriers, etc.) are designed to prevent +unwanted optimization. If they are being used properly, there will be no +need to use volatile as well. If volatile is still necessary, there is +almost certainly a bug in the code somewhere. In properly-written kernel +code, volatile can only serve to slow things down. + +Consider a typical block of kernel code:: + + spin_lock(&the_lock); + do_something_on(&shared_data); + do_something_else_with(&shared_data); + spin_unlock(&the_lock); + +If all the code follows the locking rules, the value of shared_data cannot +change unexpectedly while the_lock is held. Any other code which might +want to play with that data will be waiting on the lock. The spinlock +primitives act as memory barriers - they are explicitly written to do so - +meaning that data accesses will not be optimized across them. So the +compiler might think it knows what will be in shared_data, but the +spin_lock() call, since it acts as a memory barrier, will force it to +forget anything it knows. There will be no optimization problems with +accesses to that data. + +If shared_data were declared volatile, the locking would still be +necessary. But the compiler would also be prevented from optimizing access +to shared_data _within_ the critical section, when we know that nobody else +can be working with it. While the lock is held, shared_data is not +volatile. When dealing with shared data, proper locking makes volatile +unnecessary - and potentially harmful. + +The volatile storage class was originally meant for memory-mapped I/O +registers. Within the kernel, register accesses, too, should be protected +by locks, but one also does not want the compiler "optimizing" register +accesses within a critical section. But, within the kernel, I/O memory +accesses are always done through accessor functions; accessing I/O memory +directly through pointers is frowned upon and does not work on all +architectures. Those accessors are written to prevent unwanted +optimization, so, once again, volatile is unnecessary. + +Another situation where one might be tempted to use volatile is +when the processor is busy-waiting on the value of a variable. The right +way to perform a busy wait is:: + + while (my_variable != what_i_want) + cpu_relax(); + +The cpu_relax() call can lower CPU power consumption or yield to a +hyperthreaded twin processor; it also happens to serve as a compiler +barrier, so, once again, volatile is unnecessary. Of course, busy- +waiting is generally an anti-social act to begin with. + +There are still a few rare situations where volatile makes sense in the +kernel: + + - The above-mentioned accessor functions might use volatile on + architectures where direct I/O memory access does work. Essentially, + each accessor call becomes a little critical section on its own and + ensures that the access happens as expected by the programmer. + + - Inline assembly code which changes memory, but which has no other + visible side effects, risks being deleted by GCC. Adding the volatile + keyword to asm statements will prevent this removal. + + - The jiffies variable is special in that it can have a different value + every time it is referenced, but it can be read without any special + locking. So jiffies can be volatile, but the addition of other + variables of this type is strongly frowned upon. Jiffies is considered + to be a "stupid legacy" issue (Linus's words) in this regard; fixing it + would be more trouble than it is worth. + + - Pointers to data structures in coherent memory which might be modified + by I/O devices can, sometimes, legitimately be volatile. A ring buffer + used by a network adapter, where that adapter changes pointers to + indicate which descriptors have been processed, is an example of this + type of situation. + +For most code, none of the above justifications for volatile apply. As a +result, the use of volatile is likely to be seen as a bug and will bring +additional scrutiny to the code. Developers who are tempted to use +volatile should take a step back and think about what they are truly trying +to accomplish. + +Patches to remove volatile variables are generally welcome - as long as +they come with a justification which shows that the concurrency issues have +been properly thought through. + + +References +========== + +[1] http://lwn.net/Articles/233481/ + +[2] http://lwn.net/Articles/233482/ + +Credits +======= + +Original impetus and research by Randy Dunlap + +Written by Jonathan Corbet + +Improvements via comments from Satyam Sharma, Johannes Stezenbach, Jesper +Juhl, Heikki Orsila, H. Peter Anvin, Philipp Hahn, and Stefan +Richter. diff --git a/Documentation/stable_api_nonsense.txt b/Documentation/stable_api_nonsense.txt deleted file mode 100644 index 24f5aeecee91..000000000000 --- a/Documentation/stable_api_nonsense.txt +++ /dev/null @@ -1,205 +0,0 @@ -.. _stable_api_nonsense: - -The Linux Kernel Driver Interface -================================== - -(all of your questions answered and then some) - -Greg Kroah-Hartman - -This is being written to try to explain why Linux **does not have a binary -kernel interface, nor does it have a stable kernel interface**. - -.. note:: - - Please realize that this article describes the **in kernel** interfaces, not - the kernel to userspace interfaces. - - The kernel to userspace interface is the one that application programs use, - the syscall interface. That interface is **very** stable over time, and - will not break. I have old programs that were built on a pre 0.9something - kernel that still work just fine on the latest 2.6 kernel release. - That interface is the one that users and application programmers can count - on being stable. - - -Executive Summary ------------------ -You think you want a stable kernel interface, but you really do not, and -you don't even know it. What you want is a stable running driver, and -you get that only if your driver is in the main kernel tree. You also -get lots of other good benefits if your driver is in the main kernel -tree, all of which has made Linux into such a strong, stable, and mature -operating system which is the reason you are using it in the first -place. - - -Intro ------ - -It's only the odd person who wants to write a kernel driver that needs -to worry about the in-kernel interfaces changing. For the majority of -the world, they neither see this interface, nor do they care about it at -all. - -First off, I'm not going to address **any** legal issues about closed -source, hidden source, binary blobs, source wrappers, or any other term -that describes kernel drivers that do not have their source code -released under the GPL. Please consult a lawyer if you have any legal -questions, I'm a programmer and hence, I'm just going to be describing -the technical issues here (not to make light of the legal issues, they -are real, and you do need to be aware of them at all times.) - -So, there are two main topics here, binary kernel interfaces and stable -kernel source interfaces. They both depend on each other, but we will -discuss the binary stuff first to get it out of the way. - - -Binary Kernel Interface ------------------------ -Assuming that we had a stable kernel source interface for the kernel, a -binary interface would naturally happen too, right? Wrong. Please -consider the following facts about the Linux kernel: - - - Depending on the version of the C compiler you use, different kernel - data structures will contain different alignment of structures, and - possibly include different functions in different ways (putting - functions inline or not.) The individual function organization - isn't that important, but the different data structure padding is - very important. - - - Depending on what kernel build options you select, a wide range of - different things can be assumed by the kernel: - - - different structures can contain different fields - - Some functions may not be implemented at all, (i.e. some locks - compile away to nothing for non-SMP builds.) - - Memory within the kernel can be aligned in different ways, - depending on the build options. - - - Linux runs on a wide range of different processor architectures. - There is no way that binary drivers from one architecture will run - on another architecture properly. - -Now a number of these issues can be addressed by simply compiling your -module for the exact specific kernel configuration, using the same exact -C compiler that the kernel was built with. This is sufficient if you -want to provide a module for a specific release version of a specific -Linux distribution. But multiply that single build by the number of -different Linux distributions and the number of different supported -releases of the Linux distribution and you quickly have a nightmare of -different build options on different releases. Also realize that each -Linux distribution release contains a number of different kernels, all -tuned to different hardware types (different processor types and -different options), so for even a single release you will need to create -multiple versions of your module. - -Trust me, you will go insane over time if you try to support this kind -of release, I learned this the hard way a long time ago... - - -Stable Kernel Source Interfaces -------------------------------- - -This is a much more "volatile" topic if you talk to people who try to -keep a Linux kernel driver that is not in the main kernel tree up to -date over time. - -Linux kernel development is continuous and at a rapid pace, never -stopping to slow down. As such, the kernel developers find bugs in -current interfaces, or figure out a better way to do things. If they do -that, they then fix the current interfaces to work better. When they do -so, function names may change, structures may grow or shrink, and -function parameters may be reworked. If this happens, all of the -instances of where this interface is used within the kernel are fixed up -at the same time, ensuring that everything continues to work properly. - -As a specific examples of this, the in-kernel USB interfaces have -undergone at least three different reworks over the lifetime of this -subsystem. These reworks were done to address a number of different -issues: - - - A change from a synchronous model of data streams to an asynchronous - one. This reduced the complexity of a number of drivers and - increased the throughput of all USB drivers such that we are now - running almost all USB devices at their maximum speed possible. - - A change was made in the way data packets were allocated from the - USB core by USB drivers so that all drivers now needed to provide - more information to the USB core to fix a number of documented - deadlocks. - -This is in stark contrast to a number of closed source operating systems -which have had to maintain their older USB interfaces over time. This -provides the ability for new developers to accidentally use the old -interfaces and do things in improper ways, causing the stability of the -operating system to suffer. - -In both of these instances, all developers agreed that these were -important changes that needed to be made, and they were made, with -relatively little pain. If Linux had to ensure that it will preserve a -stable source interface, a new interface would have been created, and -the older, broken one would have had to be maintained over time, leading -to extra work for the USB developers. Since all Linux USB developers do -their work on their own time, asking programmers to do extra work for no -gain, for free, is not a possibility. - -Security issues are also very important for Linux. When a -security issue is found, it is fixed in a very short amount of time. A -number of times this has caused internal kernel interfaces to be -reworked to prevent the security problem from occurring. When this -happens, all drivers that use the interfaces were also fixed at the -same time, ensuring that the security problem was fixed and could not -come back at some future time accidentally. If the internal interfaces -were not allowed to change, fixing this kind of security problem and -insuring that it could not happen again would not be possible. - -Kernel interfaces are cleaned up over time. If there is no one using a -current interface, it is deleted. This ensures that the kernel remains -as small as possible, and that all potential interfaces are tested as -well as they can be (unused interfaces are pretty much impossible to -test for validity.) - - -What to do ----------- - -So, if you have a Linux kernel driver that is not in the main kernel -tree, what are you, a developer, supposed to do? Releasing a binary -driver for every different kernel version for every distribution is a -nightmare, and trying to keep up with an ever changing kernel interface -is also a rough job. - -Simple, get your kernel driver into the main kernel tree (remember we -are talking about GPL released drivers here, if your code doesn't fall -under this category, good luck, you are on your own here, you leech -.) If your -driver is in the tree, and a kernel interface changes, it will be fixed -up by the person who did the kernel change in the first place. This -ensures that your driver is always buildable, and works over time, with -very little effort on your part. - -The very good side effects of having your driver in the main kernel tree -are: - - - The quality of the driver will rise as the maintenance costs (to the - original developer) will decrease. - - Other developers will add features to your driver. - - Other people will find and fix bugs in your driver. - - Other people will find tuning opportunities in your driver. - - Other people will update the driver for you when external interface - changes require it. - - The driver automatically gets shipped in all Linux distributions - without having to ask the distros to add it. - -As Linux supports a larger number of different devices "out of the box" -than any other operating system, and it supports these devices on more -different processor architectures than any other operating system, this -proven type of development model must be doing something right :) - - - ------- - -Thanks to Randy Dunlap, Andrew Morton, David Brownell, Hanna Linder, -Robert Love, and Nishanth Aravamudan for their review and comments on -early drafts of this paper. diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/stable_kernel_rules.txt deleted file mode 100644 index 4d82e31b7958..000000000000 --- a/Documentation/stable_kernel_rules.txt +++ /dev/null @@ -1,181 +0,0 @@ -.. _stable_kernel_rules: - -Everything you ever wanted to know about Linux -stable releases -=============================================================== - -Rules on what kind of patches are accepted, and which ones are not, into the -"-stable" tree: - - - It must be obviously correct and tested. - - It cannot be bigger than 100 lines, with context. - - It must fix only one thing. - - It must fix a real bug that bothers people (not a, "This could be a - problem..." type thing). - - It must fix a problem that causes a build error (but not for things - marked CONFIG_BROKEN), an oops, a hang, data corruption, a real - security issue, or some "oh, that's not good" issue. In short, something - critical. - - Serious issues as reported by a user of a distribution kernel may also - be considered if they fix a notable performance or interactivity issue. - As these fixes are not as obvious and have a higher risk of a subtle - regression they should only be submitted by a distribution kernel - maintainer and include an addendum linking to a bugzilla entry if it - exists and additional information on the user-visible impact. - - New device IDs and quirks are also accepted. - - No "theoretical race condition" issues, unless an explanation of how the - race can be exploited is also provided. - - It cannot contain any "trivial" fixes in it (spelling changes, - whitespace cleanups, etc). - - It must follow the - :ref:`Documentation/SubmittingPatches ` - rules. - - It or an equivalent fix must already exist in Linus' tree (upstream). - - -Procedure for submitting patches to the -stable tree ----------------------------------------------------- - - - If the patch covers files in net/ or drivers/net please follow netdev stable - submission guidelines as described in - Documentation/networking/netdev-FAQ.txt - - Security patches should not be handled (solely) by the -stable review - process but should follow the procedures in - :ref:`Documentation/SecurityBugs `. - -For all other submissions, choose one of the following procedures ------------------------------------------------------------------ - -.. _option_1: - -Option 1 -******** - -To have the patch automatically included in the stable tree, add the tag - -.. code-block:: none - - Cc: stable@vger.kernel.org - -in the sign-off area. Once the patch is merged it will be applied to -the stable tree without anything else needing to be done by the author -or subsystem maintainer. - -.. _option_2: - -Option 2 -******** - -After the patch has been merged to Linus' tree, send an email to -stable@vger.kernel.org containing the subject of the patch, the commit ID, -why you think it should be applied, and what kernel version you wish it to -be applied to. - -.. _option_3: - -Option 3 -******** - -Send the patch, after verifying that it follows the above rules, to -stable@vger.kernel.org. You must note the upstream commit ID in the -changelog of your submission, as well as the kernel version you wish -it to be applied to. - -:ref:`option_1` is **strongly** preferred, is the easiest and most common. -:ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed -worthy at the time it is applied to a public git tree (for instance, because -it deserves more regression testing first). :ref:`option_3` is especially -useful if the patch needs some special handling to apply to an older kernel -(e.g., if API's have changed in the meantime). - -Note that for :ref:`option_3`, if the patch deviates from the original -upstream patch (for example because it had to be backported) this must be very -clearly documented and justified in the patch description. - -The upstream commit ID must be specified with a separate line above the commit -text, like this: - -.. code-block:: none - - commit upstream. - -Additionally, some patches submitted via Option 1 may have additional patch -prerequisites which can be cherry-picked. This can be specified in the following -format in the sign-off area: - -.. code-block:: none - - Cc: # 3.3.x: a1f84a3: sched: Check for idle - Cc: # 3.3.x: 1b9508f: sched: Rate-limit newidle - Cc: # 3.3.x: fd21073: sched: Fix affinity logic - Cc: # 3.3.x - Signed-off-by: Ingo Molnar - -The tag sequence has the meaning of: - -.. code-block:: none - - git cherry-pick a1f84a3 - git cherry-pick 1b9508f - git cherry-pick fd21073 - git cherry-pick - -Also, some patches may have kernel version prerequisites. This can be -specified in the following format in the sign-off area: - -.. code-block:: none - - Cc: # 3.3.x- - -The tag has the meaning of: - -.. code-block:: none - - git cherry-pick - -For each "-stable" tree starting with the specified version. - -Following the submission: - - - The sender will receive an ACK when the patch has been accepted into the - queue, or a NAK if the patch is rejected. This response might take a few - days, according to the developer's schedules. - - If accepted, the patch will be added to the -stable queue, for review by - other developers and by the relevant subsystem maintainer. - - -Review cycle ------------- - - - When the -stable maintainers decide for a review cycle, the patches will be - sent to the review committee, and the maintainer of the affected area of - the patch (unless the submitter is the maintainer of the area) and CC: to - the linux-kernel mailing list. - - The review committee has 48 hours in which to ACK or NAK the patch. - - If the patch is rejected by a member of the committee, or linux-kernel - members object to the patch, bringing up issues that the maintainers and - members did not realize, the patch will be dropped from the queue. - - At the end of the review cycle, the ACKed patches will be added to the - latest -stable release, and a new -stable release will happen. - - Security patches will be accepted into the -stable tree directly from the - security kernel team, and not go through the normal review cycle. - Contact the kernel security team for more details on this procedure. - -Trees ------ - - - The queues of patches, for both completed versions and in progress - versions can be found at: - - http://git.kernel.org/?p=linux/kernel/git/stable/stable-queue.git - - - The finalized and tagged releases of all stable kernels can be found - in separate branches per version at: - - http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git - - -Review committee ----------------- - - - This is made up of a number of kernel developers who have volunteered for - this task, and a few that haven't. diff --git a/Documentation/volatile-considered-harmful.txt b/Documentation/volatile-considered-harmful.txt deleted file mode 100644 index e0d042af386c..000000000000 --- a/Documentation/volatile-considered-harmful.txt +++ /dev/null @@ -1,122 +0,0 @@ -Why the "volatile" type class should not be used ------------------------------------------------- - -C programmers have often taken volatile to mean that the variable could be -changed outside of the current thread of execution; as a result, they are -sometimes tempted to use it in kernel code when shared data structures are -being used. In other words, they have been known to treat volatile types -as a sort of easy atomic variable, which they are not. The use of volatile in -kernel code is almost never correct; this document describes why. - -The key point to understand with regard to volatile is that its purpose is -to suppress optimization, which is almost never what one really wants to -do. In the kernel, one must protect shared data structures against -unwanted concurrent access, which is very much a different task. The -process of protecting against unwanted concurrency will also avoid almost -all optimization-related problems in a more efficient way. - -Like volatile, the kernel primitives which make concurrent access to data -safe (spinlocks, mutexes, memory barriers, etc.) are designed to prevent -unwanted optimization. If they are being used properly, there will be no -need to use volatile as well. If volatile is still necessary, there is -almost certainly a bug in the code somewhere. In properly-written kernel -code, volatile can only serve to slow things down. - -Consider a typical block of kernel code:: - - spin_lock(&the_lock); - do_something_on(&shared_data); - do_something_else_with(&shared_data); - spin_unlock(&the_lock); - -If all the code follows the locking rules, the value of shared_data cannot -change unexpectedly while the_lock is held. Any other code which might -want to play with that data will be waiting on the lock. The spinlock -primitives act as memory barriers - they are explicitly written to do so - -meaning that data accesses will not be optimized across them. So the -compiler might think it knows what will be in shared_data, but the -spin_lock() call, since it acts as a memory barrier, will force it to -forget anything it knows. There will be no optimization problems with -accesses to that data. - -If shared_data were declared volatile, the locking would still be -necessary. But the compiler would also be prevented from optimizing access -to shared_data _within_ the critical section, when we know that nobody else -can be working with it. While the lock is held, shared_data is not -volatile. When dealing with shared data, proper locking makes volatile -unnecessary - and potentially harmful. - -The volatile storage class was originally meant for memory-mapped I/O -registers. Within the kernel, register accesses, too, should be protected -by locks, but one also does not want the compiler "optimizing" register -accesses within a critical section. But, within the kernel, I/O memory -accesses are always done through accessor functions; accessing I/O memory -directly through pointers is frowned upon and does not work on all -architectures. Those accessors are written to prevent unwanted -optimization, so, once again, volatile is unnecessary. - -Another situation where one might be tempted to use volatile is -when the processor is busy-waiting on the value of a variable. The right -way to perform a busy wait is:: - - while (my_variable != what_i_want) - cpu_relax(); - -The cpu_relax() call can lower CPU power consumption or yield to a -hyperthreaded twin processor; it also happens to serve as a compiler -barrier, so, once again, volatile is unnecessary. Of course, busy- -waiting is generally an anti-social act to begin with. - -There are still a few rare situations where volatile makes sense in the -kernel: - - - The above-mentioned accessor functions might use volatile on - architectures where direct I/O memory access does work. Essentially, - each accessor call becomes a little critical section on its own and - ensures that the access happens as expected by the programmer. - - - Inline assembly code which changes memory, but which has no other - visible side effects, risks being deleted by GCC. Adding the volatile - keyword to asm statements will prevent this removal. - - - The jiffies variable is special in that it can have a different value - every time it is referenced, but it can be read without any special - locking. So jiffies can be volatile, but the addition of other - variables of this type is strongly frowned upon. Jiffies is considered - to be a "stupid legacy" issue (Linus's words) in this regard; fixing it - would be more trouble than it is worth. - - - Pointers to data structures in coherent memory which might be modified - by I/O devices can, sometimes, legitimately be volatile. A ring buffer - used by a network adapter, where that adapter changes pointers to - indicate which descriptors have been processed, is an example of this - type of situation. - -For most code, none of the above justifications for volatile apply. As a -result, the use of volatile is likely to be seen as a bug and will bring -additional scrutiny to the code. Developers who are tempted to use -volatile should take a step back and think about what they are truly trying -to accomplish. - -Patches to remove volatile variables are generally welcome - as long as -they come with a justification which shows that the concurrency issues have -been properly thought through. - - -References -========== - -[1] http://lwn.net/Articles/233481/ - -[2] http://lwn.net/Articles/233482/ - -Credits -======= - -Original impetus and research by Randy Dunlap - -Written by Jonathan Corbet - -Improvements via comments from Satyam Sharma, Johannes Stezenbach, Jesper -Juhl, Heikki Orsila, H. Peter Anvin, Philipp Hahn, and Stefan -Richter. -- cgit v1.2.3 From 9d85025b0418163fae079c9ba8f8445212de8568 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 09:51:11 -0300 Subject: docs-rst: create an user's manual book Place README, REPORTING-BUGS, SecurityBugs and kernel-parameters on an user's manual book. As we'll be numbering the user's manual, remove the manual numbering from SecurityBugs. Signed-off-by: Mauro Carvalho Chehab --- Documentation/BUG-HUNTING | 248 -- Documentation/SecurityBugs | 46 - Documentation/VGA-softcursor.txt | 66 - Documentation/admin-guide/README.rst | 410 ++ Documentation/admin-guide/bad-memory.rst | 50 + Documentation/admin-guide/basic-profiling.rst | 68 + Documentation/admin-guide/binfmt-misc.rst | 151 + Documentation/admin-guide/braille-console.rst | 38 + Documentation/admin-guide/bug-hunting.rst | 248 ++ Documentation/admin-guide/conf.py | 10 + Documentation/admin-guide/devices.rst | 3350 +++++++++++++++ Documentation/admin-guide/dynamic-debug-howto.rst | 353 ++ Documentation/admin-guide/index.rst | 34 + Documentation/admin-guide/init.rst | 52 + Documentation/admin-guide/initrd.rst | 383 ++ Documentation/admin-guide/java.rst | 417 ++ Documentation/admin-guide/kernel-parameters.rst | 4577 +++++++++++++++++++++ Documentation/admin-guide/md.rst | 727 ++++ Documentation/admin-guide/mono.rst | 68 + Documentation/admin-guide/oops-tracing.rst | 300 ++ Documentation/admin-guide/parport.rst | 286 ++ Documentation/admin-guide/ramoops.rst | 154 + Documentation/admin-guide/reporting-bugs.rst | 182 + Documentation/admin-guide/security-bugs.rst | 46 + Documentation/admin-guide/serial-console.rst | 115 + Documentation/admin-guide/sysfs-rules.rst | 192 + Documentation/admin-guide/sysrq.rst | 289 ++ Documentation/admin-guide/unicode.rst | 189 + Documentation/admin-guide/vga-softcursor.rst | 66 + Documentation/bad_memory.txt | 51 - Documentation/basic_profiling.txt | 69 - Documentation/binfmt_misc.txt | 151 - Documentation/braille-console.txt | 38 - Documentation/conf.py | 2 + Documentation/devices.txt | 3351 --------------- Documentation/dynamic-debug-howto.txt | 353 -- Documentation/index.rst | 1 + Documentation/init.txt | 52 - Documentation/initrd.txt | 383 -- Documentation/java.txt | 418 -- Documentation/kernel-parameters.txt | 4577 --------------------- Documentation/md.txt | 727 ---- Documentation/mono.txt | 68 - Documentation/oops-tracing.txt | 300 -- Documentation/parport.txt | 286 -- Documentation/ramoops.txt | 154 - Documentation/serial-console.txt | 115 - Documentation/sysfs-rules.txt | 192 - Documentation/sysrq.txt | 289 -- Documentation/unicode.txt | 189 - README | 411 -- REPORTING-BUGS | 182 - 52 files changed, 12758 insertions(+), 12716 deletions(-) delete mode 100644 Documentation/BUG-HUNTING delete mode 100644 Documentation/SecurityBugs delete mode 100644 Documentation/VGA-softcursor.txt create mode 100644 Documentation/admin-guide/README.rst create mode 100644 Documentation/admin-guide/bad-memory.rst create mode 100644 Documentation/admin-guide/basic-profiling.rst create mode 100644 Documentation/admin-guide/binfmt-misc.rst create mode 100644 Documentation/admin-guide/braille-console.rst create mode 100644 Documentation/admin-guide/bug-hunting.rst create mode 100644 Documentation/admin-guide/conf.py create mode 100644 Documentation/admin-guide/devices.rst create mode 100644 Documentation/admin-guide/dynamic-debug-howto.rst create mode 100644 Documentation/admin-guide/index.rst create mode 100644 Documentation/admin-guide/init.rst create mode 100644 Documentation/admin-guide/initrd.rst create mode 100644 Documentation/admin-guide/java.rst create mode 100644 Documentation/admin-guide/kernel-parameters.rst create mode 100644 Documentation/admin-guide/md.rst create mode 100644 Documentation/admin-guide/mono.rst create mode 100644 Documentation/admin-guide/oops-tracing.rst create mode 100644 Documentation/admin-guide/parport.rst create mode 100644 Documentation/admin-guide/ramoops.rst create mode 100644 Documentation/admin-guide/reporting-bugs.rst create mode 100644 Documentation/admin-guide/security-bugs.rst create mode 100644 Documentation/admin-guide/serial-console.rst create mode 100644 Documentation/admin-guide/sysfs-rules.rst create mode 100644 Documentation/admin-guide/sysrq.rst create mode 100644 Documentation/admin-guide/unicode.rst create mode 100644 Documentation/admin-guide/vga-softcursor.rst delete mode 100644 Documentation/bad_memory.txt delete mode 100644 Documentation/basic_profiling.txt delete mode 100644 Documentation/binfmt_misc.txt delete mode 100644 Documentation/braille-console.txt delete mode 100644 Documentation/devices.txt delete mode 100644 Documentation/dynamic-debug-howto.txt delete mode 100644 Documentation/init.txt delete mode 100644 Documentation/initrd.txt delete mode 100644 Documentation/java.txt delete mode 100644 Documentation/kernel-parameters.txt delete mode 100644 Documentation/md.txt delete mode 100644 Documentation/mono.txt delete mode 100644 Documentation/oops-tracing.txt delete mode 100644 Documentation/parport.txt delete mode 100644 Documentation/ramoops.txt delete mode 100644 Documentation/serial-console.txt delete mode 100644 Documentation/sysfs-rules.txt delete mode 100644 Documentation/sysrq.txt delete mode 100644 Documentation/unicode.txt delete mode 100644 README delete mode 100644 REPORTING-BUGS diff --git a/Documentation/BUG-HUNTING b/Documentation/BUG-HUNTING deleted file mode 100644 index a8ef794aadae..000000000000 --- a/Documentation/BUG-HUNTING +++ /dev/null @@ -1,248 +0,0 @@ -Bug hunting -+++++++++++ - -Last updated: 20 December 2005 - -Introduction -============ - -Always try the latest kernel from kernel.org and build from source. If you are -not confident in doing that please report the bug to your distribution vendor -instead of to a kernel developer. - -Finding bugs is not always easy. Have a go though. If you can't find it don't -give up. Report as much as you have found to the relevant maintainer. See -MAINTAINERS for who that is for the subsystem you have worked on. - -Before you submit a bug report read -:ref:`Documentation/REPORTING-BUGS `. - -Devices not appearing -===================== - -Often this is caused by udev. Check that first before blaming it on the -kernel. - -Finding patch that caused a bug -=============================== - - - -Finding using ``git-bisect`` ----------------------------- - -Using the provided tools with ``git`` makes finding bugs easy provided the bug -is reproducible. - -Steps to do it: - -- start using git for the kernel source -- read the man page for ``git-bisect`` -- have fun - -Finding it the old way ----------------------- - -[Sat Mar 2 10:32:33 PST 1996 KERNEL_BUG-HOWTO lm@sgi.com (Larry McVoy)] - -This is how to track down a bug if you know nothing about kernel hacking. -It's a brute force approach but it works pretty well. - -You need: - - - A reproducible bug - it has to happen predictably (sorry) - - All the kernel tar files from a revision that worked to the - revision that doesn't - -You will then do: - - - Rebuild a revision that you believe works, install, and verify that. - - Do a binary search over the kernels to figure out which one - introduced the bug. I.e., suppose 1.3.28 didn't have the bug, but - you know that 1.3.69 does. Pick a kernel in the middle and build - that, like 1.3.50. Build & test; if it works, pick the mid point - between .50 and .69, else the mid point between .28 and .50. - - You'll narrow it down to the kernel that introduced the bug. You - can probably do better than this but it gets tricky. - - - Narrow it down to a subdirectory - - - Copy kernel that works into "test". Let's say that 3.62 works, - but 3.63 doesn't. So you diff -r those two kernels and come - up with a list of directories that changed. For each of those - directories: - - Copy the non-working directory next to the working directory - as "dir.63". - One directory at time, try moving the working directory to - "dir.62" and mv dir.63 dir"time, try:: - - mv dir dir.62 - mv dir.63 dir - find dir -name '*.[oa]' -print | xargs rm -f - - And then rebuild and retest. Assuming that all related - changes were contained in the sub directory, this should - isolate the change to a directory. - - Problems: changes in header files may have occurred; I've - found in my case that they were self explanatory - you may - or may not want to give up when that happens. - - - Narrow it down to a file - - - You can apply the same technique to each file in the directory, - hoping that the changes in that file are self contained. - - - Narrow it down to a routine - - - You can take the old file and the new file and manually create - a merged file that has:: - - #ifdef VER62 - routine() - { - ... - } - #else - routine() - { - ... - } - #endif - - And then walk through that file, one routine at a time and - prefix it with:: - - #define VER62 - /* both routines here */ - #undef VER62 - - Then recompile, retest, move the ifdefs until you find the one - that makes the difference. - -Finally, you take all the info that you have, kernel revisions, bug -description, the extent to which you have narrowed it down, and pass -that off to whomever you believe is the maintainer of that section. -A post to linux.dev.kernel isn't such a bad idea if you've done some -work to narrow it down. - -If you get it down to a routine, you'll probably get a fix in 24 hours. - -My apologies to Linus and the other kernel hackers for describing this -brute force approach, it's hardly what a kernel hacker would do. However, -it does work and it lets non-hackers help fix bugs. And it is cool -because Linux snapshots will let you do this - something that you can't -do with vendor supplied releases. - -Fixing the bug -============== - -Nobody is going to tell you how to fix bugs. Seriously. You need to work it -out. But below are some hints on how to use the tools. - -To debug a kernel, use objdump and look for the hex offset from the crash -output to find the valid line of code/assembler. Without debug symbols, you -will see the assembler code for the routine shown, but if your kernel has -debug symbols the C code will also be available. (Debug symbols can be enabled -in the kernel hacking menu of the menu configuration.) For example:: - - objdump -r -S -l --disassemble net/dccp/ipv4.o - -.. note:: - - You need to be at the top level of the kernel tree for this to pick up - your C files. - -If you don't have access to the code you can also debug on some crash dumps -e.g. crash dump output as shown by Dave Miller:: - - EIP is at ip_queue_xmit+0x14/0x4c0 - ... - Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00 - 00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08 - <8b> 83 3c 01 00 00 89 44 24 14 8b 45 28 85 c0 89 44 24 18 0f 85 - - Put the bytes into a "foo.s" file like this: - - .text - .globl foo - foo: - .byte .... /* bytes from Code: part of OOPS dump */ - - Compile it with "gcc -c -o foo.o foo.s" then look at the output of - "objdump --disassemble foo.o". - - Output: - - ip_queue_xmit: - push %ebp - push %edi - push %esi - push %ebx - sub $0xbc, %esp - mov 0xd0(%esp), %ebp ! %ebp = arg0 (skb) - mov 0x8(%ebp), %ebx ! %ebx = skb->sk - mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt - -In addition, you can use GDB to figure out the exact file and line -number of the OOPS from the ``vmlinux`` file. If you have -``CONFIG_DEBUG_INFO`` enabled, you can simply copy the EIP value from the -OOPS:: - - EIP: 0060:[] Not tainted VLI - -And use GDB to translate that to human-readable form:: - - gdb vmlinux - (gdb) l *0xc021e50e - -If you don't have ``CONFIG_DEBUG_INFO`` enabled, you use the function -offset from the OOPS:: - - EIP is at vt_ioctl+0xda8/0x1482 - -And recompile the kernel with ``CONFIG_DEBUG_INFO`` enabled:: - - make vmlinux - gdb vmlinux - (gdb) p vt_ioctl - (gdb) l *(0x
+ 0xda8) - -or, as one command:: - - (gdb) l *(vt_ioctl + 0xda8) - -If you have a call trace, such as:: - - Call Trace: - [] :jbd:log_wait_commit+0xa3/0xf5 - [] autoremove_wake_function+0x0/0x2e - [] :jbd:journal_stop+0x1be/0x1ee - ... - -this shows the problem in the :jbd: module. You can load that module in gdb -and list the relevant code:: - - gdb fs/jbd/jbd.ko - (gdb) p log_wait_commit - (gdb) l *(0x
+ 0xa3) - -or:: - - (gdb) l *(log_wait_commit + 0xa3) - - -Another very useful option of the Kernel Hacking section in menuconfig is -Debug memory allocations. This will help you see whether data has been -initialised and not set before use etc. To see the values that get assigned -with this look at ``mm/slab.c`` and search for ``POISON_INUSE``. When using -this an Oops will often show the poisoned data instead of zero which is the -default. - -Once you have worked out a fix please submit it upstream. After all open -source is about sharing what you do and don't you want to be recognised for -your genius? - -Please do read :ref:`Documentation/SubmittingPatches ` -though to help your code get accepted. diff --git a/Documentation/SecurityBugs b/Documentation/SecurityBugs deleted file mode 100644 index 342d769834f6..000000000000 --- a/Documentation/SecurityBugs +++ /dev/null @@ -1,46 +0,0 @@ -.. _securitybugs: - -Security bugs -============= - -Linux kernel developers take security very seriously. As such, we'd -like to know when a security bug is found so that it can be fixed and -disclosed as quickly as possible. Please report security bugs to the -Linux kernel security team. - -1) Contact ----------- - -The Linux kernel security team can be contacted by email at -. This is a private list of security officers -who will help verify the bug report and develop and release a fix. -It is possible that the security team will bring in extra help from -area maintainers to understand and fix the security vulnerability. - -As it is with any bug, the more information provided the easier it -will be to diagnose and fix. Please review the procedure outlined in -REPORTING-BUGS if you are unclear about what information is helpful. -Any exploit code is very helpful and will not be released without -consent from the reporter unless it has already been made public. - -2) Disclosure -------------- - -The goal of the Linux kernel security team is to work with the -bug submitter to bug resolution as well as disclosure. We prefer -to fully disclose the bug as soon as possible. It is reasonable to -delay disclosure when the bug or the fix is not yet fully understood, -the solution is not well-tested or for vendor coordination. However, we -expect these delays to be short, measurable in days, not weeks or months. -A disclosure date is negotiated by the security team working with the -bug submitter as well as vendors. However, the kernel security team -holds the final say when setting a disclosure date. The timeframe for -disclosure is from immediate (esp. if it's already publicly known) -to a few weeks. As a basic default policy, we expect report date to -disclosure date to be on the order of 7 days. - -3) Non-disclosure agreements ----------------------------- - -The Linux kernel security team is not a formal body and therefore unable -to enter any non-disclosure agreements. diff --git a/Documentation/VGA-softcursor.txt b/Documentation/VGA-softcursor.txt deleted file mode 100644 index 9eac6744b3a1..000000000000 --- a/Documentation/VGA-softcursor.txt +++ /dev/null @@ -1,66 +0,0 @@ -Software cursor for VGA -======================= - -by Pavel Machek -and Martin Mares - -Linux now has some ability to manipulate cursor appearance. Normally, you -can set the size of hardware cursor (and also work around some ugly bugs in -those miserable Trident cards [#f1]_. You can now play a few new tricks: -you can make your cursor look - -like a non-blinking red block, make it inverse background of the character it's -over or to highlight that character and still choose whether the original -hardware cursor should remain visible or not. There may be other things I have -never thought of. - -The cursor appearance is controlled by a ``[?1;2;3c`` escape sequence -where 1, 2 and 3 are parameters described below. If you omit any of them, -they will default to zeroes. - -first Parameter - specifies cursor size:: - - 0=default - 1=invisible - 2=underline, - ... - 8=full block - + 16 if you want the software cursor to be applied - + 32 if you want to always change the background color - + 64 if you dislike having the background the same as the - foreground. - - Highlights are ignored for the last two flags. - -second parameter - selects character attribute bits you want to change - (by simply XORing them with the value of this parameter). On standard - VGA, the high four bits specify background and the low four the - foreground. In both groups, low three bits set color (as in normal - color codes used by the console) and the most significant one turns - on highlight (or sometimes blinking -- it depends on the configuration - of your VGA). - -third parameter - consists of character attribute bits you want to set. - - Bit setting takes place before bit toggling, so you can simply clear a - bit by including it in both the set mask and the toggle mask. - -.. [#f1] see ``#define TRIDENT_GLITCH`` in ``drivers/video/vgacon.c``. - -Examples: -========= - -To get normal blinking underline, use:: - - echo -e '\033[?2c' - -To get blinking block, use:: - - echo -e '\033[?6c' - -To get red non-blinking block, use:: - - echo -e '\033[?17;0;64c' diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst new file mode 100644 index 000000000000..05aad8543340 --- /dev/null +++ b/Documentation/admin-guide/README.rst @@ -0,0 +1,410 @@ +Linux kernel release 4.x +============================================= + +These are the release notes for Linux version 4. Read them carefully, +as they tell you what this is all about, explain how to install the +kernel, and what to do if something goes wrong. + +What is Linux? +-------------- + + Linux is a clone of the operating system Unix, written from scratch by + Linus Torvalds with assistance from a loosely-knit team of hackers across + the Net. It aims towards POSIX and Single UNIX Specification compliance. + + It has all the features you would expect in a modern fully-fledged Unix, + including true multitasking, virtual memory, shared libraries, demand + loading, shared copy-on-write executables, proper memory management, + and multistack networking including IPv4 and IPv6. + + It is distributed under the GNU General Public License - see the + accompanying COPYING file for more details. + +On what hardware does it run? +----------------------------- + + Although originally developed first for 32-bit x86-based PCs (386 or higher), + today Linux also runs on (at least) the Compaq Alpha AXP, Sun SPARC and + UltraSPARC, Motorola 68000, PowerPC, PowerPC64, ARM, Hitachi SuperH, Cell, + IBM S/390, MIPS, HP PA-RISC, Intel IA-64, DEC VAX, AMD x86-64, AXIS CRIS, + Xtensa, Tilera TILE, AVR32, ARC and Renesas M32R architectures. + + Linux is easily portable to most general-purpose 32- or 64-bit architectures + as long as they have a paged memory management unit (PMMU) and a port of the + GNU C compiler (gcc) (part of The GNU Compiler Collection, GCC). Linux has + also been ported to a number of architectures without a PMMU, although + functionality is then obviously somewhat limited. + Linux has also been ported to itself. You can now run the kernel as a + userspace application - this is called UserMode Linux (UML). + +Documentation +------------- + + - There is a lot of documentation available both in electronic form on + the Internet and in books, both Linux-specific and pertaining to + general UNIX questions. I'd recommend looking into the documentation + subdirectories on any Linux FTP site for the LDP (Linux Documentation + Project) books. This README is not meant to be documentation on the + system: there are much better sources available. + + - There are various README files in the Documentation/ subdirectory: + these typically contain kernel-specific installation notes for some + drivers for example. See Documentation/00-INDEX for a list of what + is contained in each file. Please read the Changes file, as it + contains information about the problems, which may result by upgrading + your kernel. + + - The Documentation/DocBook/ subdirectory contains several guides for + kernel developers and users. These guides can be rendered in a + number of formats: PostScript (.ps), PDF, HTML, & man-pages, among others. + After installation, ``make psdocs``, ``make pdfdocs``, ``make htmldocs``, + or ``make mandocs`` will render the documentation in the requested format. + +Installing the kernel source +---------------------------- + + - If you install the full sources, put the kernel tarball in a + directory where you have permissions (e.g. your home directory) and + unpack it:: + + xz -cd linux-4.X.tar.xz | tar xvf - + + Replace "X" with the version number of the latest kernel. + + Do NOT use the /usr/src/linux area! This area has a (usually + incomplete) set of kernel headers that are used by the library header + files. They should match the library, and not get messed up by + whatever the kernel-du-jour happens to be. + + - You can also upgrade between 4.x releases by patching. Patches are + distributed in the xz format. To install by patching, get all the + newer patch files, enter the top level directory of the kernel source + (linux-4.X) and execute:: + + xz -cd ../patch-4.x.xz | patch -p1 + + Replace "x" for all versions bigger than the version "X" of your current + source tree, **in_order**, and you should be ok. You may want to remove + the backup files (some-file-name~ or some-file-name.orig), and make sure + that there are no failed patches (some-file-name# or some-file-name.rej). + If there are, either you or I have made a mistake. + + Unlike patches for the 4.x kernels, patches for the 4.x.y kernels + (also known as the -stable kernels) are not incremental but instead apply + directly to the base 4.x kernel. For example, if your base kernel is 4.0 + and you want to apply the 4.0.3 patch, you must not first apply the 4.0.1 + and 4.0.2 patches. Similarly, if you are running kernel version 4.0.2 and + want to jump to 4.0.3, you must first reverse the 4.0.2 patch (that is, + patch -R) **before** applying the 4.0.3 patch. You can read more on this in + :ref:`Documentation/applying-patches.txt `. + + Alternatively, the script patch-kernel can be used to automate this + process. It determines the current kernel version and applies any + patches found:: + + linux/scripts/patch-kernel linux + + The first argument in the command above is the location of the + kernel source. Patches are applied from the current directory, but + an alternative directory can be specified as the second argument. + + - Make sure you have no stale .o files and dependencies lying around:: + + cd linux + make mrproper + + You should now have the sources correctly installed. + +Software requirements +--------------------- + + Compiling and running the 4.x kernels requires up-to-date + versions of various software packages. Consult + :ref:`Documentation/Changes ` for the minimum version numbers + required and how to get updates for these packages. Beware that using + excessively old versions of these packages can cause indirect + errors that are very difficult to track down, so don't assume that + you can just update packages when obvious problems arise during + build or operation. + +Build directory for the kernel +------------------------------ + + When compiling the kernel, all output files will per default be + stored together with the kernel source code. + Using the option ``make O=output/dir`` allows you to specify an alternate + place for the output files (including .config). + Example:: + + kernel source code: /usr/src/linux-4.X + build directory: /home/name/build/kernel + + To configure and build the kernel, use:: + + cd /usr/src/linux-4.X + make O=/home/name/build/kernel menuconfig + make O=/home/name/build/kernel + sudo make O=/home/name/build/kernel modules_install install + + Please note: If the ``O=output/dir`` option is used, then it must be + used for all invocations of make. + +Configuring the kernel +---------------------- + + Do not skip this step even if you are only upgrading one minor + version. New configuration options are added in each release, and + odd problems will turn up if the configuration files are not set up + as expected. If you want to carry your existing configuration to a + new version with minimal work, use ``make oldconfig``, which will + only ask you for the answers to new questions. + + - Alternative configuration commands are:: + + "make config" Plain text interface. + + "make menuconfig" Text based color menus, radiolists & dialogs. + + "make nconfig" Enhanced text based color menus. + + "make xconfig" Qt based configuration tool. + + "make gconfig" GTK+ based configuration tool. + + "make oldconfig" Default all questions based on the contents of + your existing ./.config file and asking about + new config symbols. + + "make silentoldconfig" + Like above, but avoids cluttering the screen + with questions already answered. + Additionally updates the dependencies. + + "make olddefconfig" + Like above, but sets new symbols to their default + values without prompting. + + "make defconfig" Create a ./.config file by using the default + symbol values from either arch/$ARCH/defconfig + or arch/$ARCH/configs/${PLATFORM}_defconfig, + depending on the architecture. + + "make ${PLATFORM}_defconfig" + Create a ./.config file by using the default + symbol values from + arch/$ARCH/configs/${PLATFORM}_defconfig. + Use "make help" to get a list of all available + platforms of your architecture. + + "make allyesconfig" + Create a ./.config file by setting symbol + values to 'y' as much as possible. + + "make allmodconfig" + Create a ./.config file by setting symbol + values to 'm' as much as possible. + + "make allnoconfig" Create a ./.config file by setting symbol + values to 'n' as much as possible. + + "make randconfig" Create a ./.config file by setting symbol + values to random values. + + "make localmodconfig" Create a config based on current config and + loaded modules (lsmod). Disables any module + option that is not needed for the loaded modules. + + To create a localmodconfig for another machine, + store the lsmod of that machine into a file + and pass it in as a LSMOD parameter. + + target$ lsmod > /tmp/mylsmod + target$ scp /tmp/mylsmod host:/tmp + + host$ make LSMOD=/tmp/mylsmod localmodconfig + + The above also works when cross compiling. + + "make localyesconfig" Similar to localmodconfig, except it will convert + all module options to built in (=y) options. + + You can find more information on using the Linux kernel config tools + in Documentation/kbuild/kconfig.txt. + + - NOTES on ``make config``: + + - Having unnecessary drivers will make the kernel bigger, and can + under some circumstances lead to problems: probing for a + nonexistent controller card may confuse your other controllers + + - A kernel with math-emulation compiled in will still use the + coprocessor if one is present: the math emulation will just + never get used in that case. The kernel will be slightly larger, + but will work on different machines regardless of whether they + have a math coprocessor or not. + + - The "kernel hacking" configuration details usually result in a + bigger or slower kernel (or both), and can even make the kernel + less stable by configuring some routines to actively try to + break bad code to find kernel problems (kmalloc()). Thus you + should probably answer 'n' to the questions for "development", + "experimental", or "debugging" features. + +Compiling the kernel +-------------------- + + - Make sure you have at least gcc 3.2 available. + For more information, refer to :ref:`Documentation/Changes `. + + Please note that you can still run a.out user programs with this kernel. + + - Do a ``make`` to create a compressed kernel image. It is also + possible to do ``make install`` if you have lilo installed to suit the + kernel makefiles, but you may want to check your particular lilo setup first. + + To do the actual install, you have to be root, but none of the normal + build should require that. Don't take the name of root in vain. + + - If you configured any of the parts of the kernel as ``modules``, you + will also have to do ``make modules_install``. + + - Verbose kernel compile/build output: + + Normally, the kernel build system runs in a fairly quiet mode (but not + totally silent). However, sometimes you or other kernel developers need + to see compile, link, or other commands exactly as they are executed. + For this, use "verbose" build mode. This is done by passing + ``V=1`` to the ``make`` command, e.g.:: + + make V=1 all + + To have the build system also tell the reason for the rebuild of each + target, use ``V=2``. The default is ``V=0``. + + - Keep a backup kernel handy in case something goes wrong. This is + especially true for the development releases, since each new release + contains new code which has not been debugged. Make sure you keep a + backup of the modules corresponding to that kernel, as well. If you + are installing a new kernel with the same version number as your + working kernel, make a backup of your modules directory before you + do a ``make modules_install``. + + Alternatively, before compiling, use the kernel config option + "LOCALVERSION" to append a unique suffix to the regular kernel version. + LOCALVERSION can be set in the "General Setup" menu. + + - In order to boot your new kernel, you'll need to copy the kernel + image (e.g. .../linux/arch/x86/boot/bzImage after compilation) + to the place where your regular bootable kernel is found. + + - Booting a kernel directly from a floppy without the assistance of a + bootloader such as LILO, is no longer supported. + + If you boot Linux from the hard drive, chances are you use LILO, which + uses the kernel image as specified in the file /etc/lilo.conf. The + kernel image file is usually /vmlinuz, /boot/vmlinuz, /bzImage or + /boot/bzImage. To use the new kernel, save a copy of the old image + and copy the new image over the old one. Then, you MUST RERUN LILO + to update the loading map! If you don't, you won't be able to boot + the new kernel image. + + Reinstalling LILO is usually a matter of running /sbin/lilo. + You may wish to edit /etc/lilo.conf to specify an entry for your + old kernel image (say, /vmlinux.old) in case the new one does not + work. See the LILO docs for more information. + + After reinstalling LILO, you should be all set. Shutdown the system, + reboot, and enjoy! + + If you ever need to change the default root device, video mode, + ramdisk size, etc. in the kernel image, use the ``rdev`` program (or + alternatively the LILO boot options when appropriate). No need to + recompile the kernel to change these parameters. + + - Reboot with the new kernel and enjoy. + +If something goes wrong +----------------------- + + - If you have problems that seem to be due to kernel bugs, please check + the file MAINTAINERS to see if there is a particular person associated + with the part of the kernel that you are having trouble with. If there + isn't anyone listed there, then the second best thing is to mail + them to me (torvalds@linux-foundation.org), and possibly to any other + relevant mailing-list or to the newsgroup. + + - In all bug-reports, *please* tell what kernel you are talking about, + how to duplicate the problem, and what your setup is (use your common + sense). If the problem is new, tell me so, and if the problem is + old, please try to tell me when you first noticed it. + + - If the bug results in a message like:: + + unable to handle kernel paging request at address C0000010 + Oops: 0002 + EIP: 0010:XXXXXXXX + eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx + esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx + ds: xxxx es: xxxx fs: xxxx gs: xxxx + Pid: xx, process nr: xx + xx xx xx xx xx xx xx xx xx xx + + or similar kernel debugging information on your screen or in your + system log, please duplicate it *exactly*. The dump may look + incomprehensible to you, but it does contain information that may + help debugging the problem. The text above the dump is also + important: it tells something about why the kernel dumped code (in + the above example, it's due to a bad kernel pointer). More information + on making sense of the dump is in Documentation/oops-tracing.txt + + - If you compiled the kernel with CONFIG_KALLSYMS you can send the dump + as is, otherwise you will have to use the ``ksymoops`` program to make + sense of the dump (but compiling with CONFIG_KALLSYMS is usually preferred). + This utility can be downloaded from + ftp://ftp..kernel.org/pub/linux/utils/kernel/ksymoops/ . + Alternatively, you can do the dump lookup by hand: + + - In debugging dumps like the above, it helps enormously if you can + look up what the EIP value means. The hex value as such doesn't help + me or anybody else very much: it will depend on your particular + kernel setup. What you should do is take the hex value from the EIP + line (ignore the ``0010:``), and look it up in the kernel namelist to + see which kernel function contains the offending address. + + To find out the kernel function name, you'll need to find the system + binary associated with the kernel that exhibited the symptom. This is + the file 'linux/vmlinux'. To extract the namelist and match it against + the EIP from the kernel crash, do:: + + nm vmlinux | sort | less + + This will give you a list of kernel addresses sorted in ascending + order, from which it is simple to find the function that contains the + offending address. Note that the address given by the kernel + debugging messages will not necessarily match exactly with the + function addresses (in fact, that is very unlikely), so you can't + just 'grep' the list: the list will, however, give you the starting + point of each kernel function, so by looking for the function that + has a starting address lower than the one you are searching for but + is followed by a function with a higher address you will find the one + you want. In fact, it may be a good idea to include a bit of + "context" in your problem report, giving a few lines around the + interesting one. + + If you for some reason cannot do the above (you have a pre-compiled + kernel image or similar), telling me as much about your setup as + possible will help. Please read the :ref:`REPORTING-BUGS ` + document for details. + + - Alternatively, you can use gdb on a running kernel. (read-only; i.e. you + cannot change values or set break points.) To do this, first compile the + kernel with -g; edit arch/x86/Makefile appropriately, then do a ``make + clean``. You'll also need to enable CONFIG_PROC_FS (via ``make config``). + + After you've rebooted with the new kernel, do ``gdb vmlinux /proc/kcore``. + You can now use all the usual gdb commands. The command to look up the + point where your system crashed is ``l *0xXXXXXXXX``. (Replace the XXXes + with the EIP value.) + + gdb'ing a non-running kernel currently fails because ``gdb`` (wrongly) + disregards the starting offset for which the kernel is compiled. diff --git a/Documentation/admin-guide/bad-memory.rst b/Documentation/admin-guide/bad-memory.rst new file mode 100644 index 000000000000..017fc86430c3 --- /dev/null +++ b/Documentation/admin-guide/bad-memory.rst @@ -0,0 +1,50 @@ +How to deal with bad memory e.g. reported by memtest86+ ? +========================================================= + +March 2008 +Jan-Simon Moeller, dl9pf@gmx.de + + + +There are three possibilities I know of: + +1) Reinsert/swap the memory modules + +2) Buy new modules (best!) or try to exchange the memory + if you have spare-parts + +3) Use BadRAM or memmap + +This Howto is about number 3) . + + +BadRAM +###### + +BadRAM is the actively developed and available as kernel-patch +here: http://rick.vanrein.org/linux/badram/ + +For more details see the BadRAM documentation. + +memmap +###### + +memmap is already in the kernel and usable as kernel-parameter at +boot-time. Its syntax is slightly strange and you may need to +calculate the values by yourself! + +Syntax to exclude a memory area (see kernel-parameters.txt for details):: + + memmap=$
+ +Example: memtest86+ reported here errors at address 0x18691458, 0x18698424 and +some others. All had 0x1869xxxx in common, so I chose a pattern of +0x18690000,0xffff0000. + +With the numbers of the example above:: + + memmap=64K$0x18690000 + +or:: + + memmap=0x10000$0x18690000 diff --git a/Documentation/admin-guide/basic-profiling.rst b/Documentation/admin-guide/basic-profiling.rst new file mode 100644 index 000000000000..72babc71b771 --- /dev/null +++ b/Documentation/admin-guide/basic-profiling.rst @@ -0,0 +1,68 @@ +Basic kernel profiling +====================== + + +These instructions are deliberately very basic. If you want something clever, +go read the real docs ;-) + +Please don't add more stuff, but feel free to +correct my mistakes ;-) (mbligh@aracnet.com) + +Thanks to John Levon, Dave Hansen, et al. for help writing this. + +```` is the thing you're trying to measure. +Make sure you have the correct ``System.map`` / ``vmlinux`` referenced! + +It is probably easiest to use ``make install`` for linux and hack +``/sbin/installkernel`` to copy ``vmlinux`` to ``/boot``, in addition to +``vmlinuz``, ``config``, ``System.map``, which are usually installed by default. + +Readprofile +----------- + +A recent ``readprofile`` command is needed for 2.6, such as found in util-linux +2.12a, which can be downloaded from: + + http://www.kernel.org/pub/linux/utils/util-linux/ + +Most distributions will ship it already. + +Add ``profile=2`` to the kernel command line. + +Some ``readprofile`` commands:: + + clear readprofile -r + + dump output readprofile -m /boot/System.map > captured_profile + +Oprofile +-------- + +Get the source (see Changes for required version) from +http://oprofile.sourceforge.net/ and add ``idle=poll`` to the kernel command +line. + +Configure with ``CONFIG_PROFILING=y`` and ``CONFIG_OPROFILE=y`` & reboot on new kernel:: + + ./configure --with-kernel-support + make install + +For superior results, be sure to enable the local APIC. If opreport sees +a 0Hz CPU, APIC was not on. Be aware that idle=poll may mean a performance +penalty. + +One time setup:: + + opcontrol --setup --vmlinux=/boot/vmlinux + +Some ``opcontrol`` commands:: + + clear opcontrol --reset + start opcontrol --start + + stop opcontrol --stop + dump output opreport > output_file + +To only report on the kernel, run ``opreport -l /boot/vmlinux > output_file`` + +A reset is needed to clear old statistics, which survive a reboot. diff --git a/Documentation/admin-guide/binfmt-misc.rst b/Documentation/admin-guide/binfmt-misc.rst new file mode 100644 index 000000000000..9c5ff8f260bf --- /dev/null +++ b/Documentation/admin-guide/binfmt-misc.rst @@ -0,0 +1,151 @@ +Kernel Support for miscellaneous (your favourite) Binary Formats v1.1 +===================================================================== + +This Kernel feature allows you to invoke almost (for restrictions see below) +every program by simply typing its name in the shell. +This includes for example compiled Java(TM), Python or Emacs programs. + +To achieve this you must tell binfmt_misc which interpreter has to be invoked +with which binary. Binfmt_misc recognises the binary-type by matching some bytes +at the beginning of the file with a magic byte sequence (masking out specified +bits) you have supplied. Binfmt_misc can also recognise a filename extension +aka ``.com`` or ``.exe``. + +First you must mount binfmt_misc:: + + mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc + +To actually register a new binary type, you have to set up a string looking like +``:name:type:offset:magic:mask:interpreter:flags`` (where you can choose the +``:`` upon your needs) and echo it to ``/proc/sys/fs/binfmt_misc/register``. + +Here is what the fields mean: + +- ``name`` + is an identifier string. A new /proc file will be created with this + ``name below /proc/sys/fs/binfmt_misc``; cannot contain slashes ``/`` for + obvious reasons. +- ``type`` + is the type of recognition. Give ``M`` for magic and ``E`` for extension. +- ``offset`` + is the offset of the magic/mask in the file, counted in bytes. This + defaults to 0 if you omit it (i.e. you write ``:name:type::magic...``). + Ignored when using filename extension matching. +- ``magic`` + is the byte sequence binfmt_misc is matching for. The magic string + may contain hex-encoded characters like ``\x0a`` or ``\xA4``. Note that you + must escape any NUL bytes; parsing halts at the first one. In a shell + environment you might have to write ``\\x0a`` to prevent the shell from + eating your ``\``. + If you chose filename extension matching, this is the extension to be + recognised (without the ``.``, the ``\x0a`` specials are not allowed). + Extension matching is case sensitive, and slashes ``/`` are not allowed! +- ``mask`` + is an (optional, defaults to all 0xff) mask. You can mask out some + bits from matching by supplying a string like magic and as long as magic. + The mask is anded with the byte sequence of the file. Note that you must + escape any NUL bytes; parsing halts at the first one. Ignored when using + filename extension matching. +- ``interpreter`` + is the program that should be invoked with the binary as first + argument (specify the full path) +- ``flags`` + is an optional field that controls several aspects of the invocation + of the interpreter. It is a string of capital letters, each controls a + certain aspect. The following flags are supported: + + ``P`` - preserve-argv[0] + Legacy behavior of binfmt_misc is to overwrite + the original argv[0] with the full path to the binary. When this + flag is included, binfmt_misc will add an argument to the argument + vector for this purpose, thus preserving the original ``argv[0]``. + e.g. If your interp is set to ``/bin/foo`` and you run ``blah`` + (which is in ``/usr/local/bin``), then the kernel will execute + ``/bin/foo`` with ``argv[]`` set to ``["/bin/foo", "/usr/local/bin/blah", "blah"]``. The interp has to be aware of this so it can + execute ``/usr/local/bin/blah`` + with ``argv[]`` set to ``["blah"]``. + ``O`` - open-binary + Legacy behavior of binfmt_misc is to pass the full path + of the binary to the interpreter as an argument. When this flag is + included, binfmt_misc will open the file for reading and pass its + descriptor as an argument, instead of the full path, thus allowing + the interpreter to execute non-readable binaries. This feature + should be used with care - the interpreter has to be trusted not to + emit the contents of the non-readable binary. + ``C`` - credentials + Currently, the behavior of binfmt_misc is to calculate + the credentials and security token of the new process according to + the interpreter. When this flag is included, these attributes are + calculated according to the binary. It also implies the ``O`` flag. + This feature should be used with care as the interpreter + will run with root permissions when a setuid binary owned by root + is run with binfmt_misc. + ``F`` - fix binary + The usual behaviour of binfmt_misc is to spawn the + binary lazily when the misc format file is invoked. However, + this doesn``t work very well in the face of mount namespaces and + changeroots, so the ``F`` mode opens the binary as soon as the + emulation is installed and uses the opened image to spawn the + emulator, meaning it is always available once installed, + regardless of how the environment changes. + + +There are some restrictions: + + - the whole register string may not exceed 1920 characters + - the magic must reside in the first 128 bytes of the file, i.e. + offset+size(magic) has to be less than 128 + - the interpreter string may not exceed 127 characters + +To use binfmt_misc you have to mount it first. You can mount it with +``mount -t binfmt_misc none /proc/sys/fs/binfmt_misc`` command, or you can add +a line ``none /proc/sys/fs/binfmt_misc binfmt_misc defaults 0 0`` to your +``/etc/fstab`` so it auto mounts on boot. + +You may want to add the binary formats in one of your ``/etc/rc`` scripts during +boot-up. Read the manual of your init program to figure out how to do this +right. + +Think about the order of adding entries! Later added entries are matched first! + + +A few examples (assumed you are in ``/proc/sys/fs/binfmt_misc``): + +- enable support for em86 (like binfmt_em86, for Alpha AXP only):: + + echo ':i386:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x03:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register + echo ':i486:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x06:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register + +- enable support for packed DOS applications (pre-configured dosemu hdimages):: + + echo ':DEXE:M::\x0eDEX::/usr/bin/dosexec:' > register + +- enable support for Windows executables using wine:: + + echo ':DOSWin:M::MZ::/usr/local/bin/wine:' > register + +For java support see Documentation/java.txt + + +You can enable/disable binfmt_misc or one binary type by echoing 0 (to disable) +or 1 (to enable) to ``/proc/sys/fs/binfmt_misc/status`` or +``/proc/.../the_name``. +Catting the file tells you the current status of ``binfmt_misc/the_entry``. + +You can remove one entry or all entries by echoing -1 to ``/proc/.../the_name`` +or ``/proc/sys/fs/binfmt_misc/status``. + + +Hints +----- + +If you want to pass special arguments to your interpreter, you can +write a wrapper script for it. See Documentation/java.txt for an +example. + +Your interpreter should NOT look in the PATH for the filename; the kernel +passes it the full filename (or the file descriptor) to use. Using ``$PATH`` can +cause unexpected behaviour and can be a security hazard. + + +Richard Günther diff --git a/Documentation/admin-guide/braille-console.rst b/Documentation/admin-guide/braille-console.rst new file mode 100644 index 000000000000..fa3702dc04ab --- /dev/null +++ b/Documentation/admin-guide/braille-console.rst @@ -0,0 +1,38 @@ +Linux Braille Console +===================== + +To get early boot messages on a braille device (before userspace screen +readers can start), you first need to compile the support for the usual serial +console (see :ref:`Documentation/serial-console.txt `), and +for braille device +(in :menuselection:`Device Drivers --> Accessibility support --> Console on braille device`). + +Then you need to specify a ``console=brl``, option on the kernel command line, the +format is:: + + console=brl,serial_options... + +where ``serial_options...`` are the same as described in +:ref:`Documentation/serial-console.txt `. + +So for instance you can use ``console=brl,ttyS0`` if the braille device is connected to the first serial port, and ``console=brl,ttyS0,115200`` to +override the baud rate to 115200, etc. + +By default, the braille device will just show the last kernel message (console +mode). To review previous messages, press the Insert key to switch to the VT +review mode. In review mode, the arrow keys permit to browse in the VT content, +:kbd:`PAGE-UP`/:kbd:`PAGE-DOWN` keys go at the top/bottom of the screen, and +the :kbd:`HOME` key goes back +to the cursor, hence providing very basic screen reviewing facility. + +Sound feedback can be obtained by adding the ``braille_console.sound=1`` kernel +parameter. + +For simplicity, only one braille console can be enabled, other uses of +``console=brl,...`` will be discarded. Also note that it does not interfere with +the console selection mechanism described in +:ref:`Documentation/serial-console.txt `. + +For now, only the VisioBraille device is supported. + +Samuel Thibault diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst new file mode 100644 index 000000000000..a8ef794aadae --- /dev/null +++ b/Documentation/admin-guide/bug-hunting.rst @@ -0,0 +1,248 @@ +Bug hunting ++++++++++++ + +Last updated: 20 December 2005 + +Introduction +============ + +Always try the latest kernel from kernel.org and build from source. If you are +not confident in doing that please report the bug to your distribution vendor +instead of to a kernel developer. + +Finding bugs is not always easy. Have a go though. If you can't find it don't +give up. Report as much as you have found to the relevant maintainer. See +MAINTAINERS for who that is for the subsystem you have worked on. + +Before you submit a bug report read +:ref:`Documentation/REPORTING-BUGS `. + +Devices not appearing +===================== + +Often this is caused by udev. Check that first before blaming it on the +kernel. + +Finding patch that caused a bug +=============================== + + + +Finding using ``git-bisect`` +---------------------------- + +Using the provided tools with ``git`` makes finding bugs easy provided the bug +is reproducible. + +Steps to do it: + +- start using git for the kernel source +- read the man page for ``git-bisect`` +- have fun + +Finding it the old way +---------------------- + +[Sat Mar 2 10:32:33 PST 1996 KERNEL_BUG-HOWTO lm@sgi.com (Larry McVoy)] + +This is how to track down a bug if you know nothing about kernel hacking. +It's a brute force approach but it works pretty well. + +You need: + + - A reproducible bug - it has to happen predictably (sorry) + - All the kernel tar files from a revision that worked to the + revision that doesn't + +You will then do: + + - Rebuild a revision that you believe works, install, and verify that. + - Do a binary search over the kernels to figure out which one + introduced the bug. I.e., suppose 1.3.28 didn't have the bug, but + you know that 1.3.69 does. Pick a kernel in the middle and build + that, like 1.3.50. Build & test; if it works, pick the mid point + between .50 and .69, else the mid point between .28 and .50. + - You'll narrow it down to the kernel that introduced the bug. You + can probably do better than this but it gets tricky. + + - Narrow it down to a subdirectory + + - Copy kernel that works into "test". Let's say that 3.62 works, + but 3.63 doesn't. So you diff -r those two kernels and come + up with a list of directories that changed. For each of those + directories: + + Copy the non-working directory next to the working directory + as "dir.63". + One directory at time, try moving the working directory to + "dir.62" and mv dir.63 dir"time, try:: + + mv dir dir.62 + mv dir.63 dir + find dir -name '*.[oa]' -print | xargs rm -f + + And then rebuild and retest. Assuming that all related + changes were contained in the sub directory, this should + isolate the change to a directory. + + Problems: changes in header files may have occurred; I've + found in my case that they were self explanatory - you may + or may not want to give up when that happens. + + - Narrow it down to a file + + - You can apply the same technique to each file in the directory, + hoping that the changes in that file are self contained. + + - Narrow it down to a routine + + - You can take the old file and the new file and manually create + a merged file that has:: + + #ifdef VER62 + routine() + { + ... + } + #else + routine() + { + ... + } + #endif + + And then walk through that file, one routine at a time and + prefix it with:: + + #define VER62 + /* both routines here */ + #undef VER62 + + Then recompile, retest, move the ifdefs until you find the one + that makes the difference. + +Finally, you take all the info that you have, kernel revisions, bug +description, the extent to which you have narrowed it down, and pass +that off to whomever you believe is the maintainer of that section. +A post to linux.dev.kernel isn't such a bad idea if you've done some +work to narrow it down. + +If you get it down to a routine, you'll probably get a fix in 24 hours. + +My apologies to Linus and the other kernel hackers for describing this +brute force approach, it's hardly what a kernel hacker would do. However, +it does work and it lets non-hackers help fix bugs. And it is cool +because Linux snapshots will let you do this - something that you can't +do with vendor supplied releases. + +Fixing the bug +============== + +Nobody is going to tell you how to fix bugs. Seriously. You need to work it +out. But below are some hints on how to use the tools. + +To debug a kernel, use objdump and look for the hex offset from the crash +output to find the valid line of code/assembler. Without debug symbols, you +will see the assembler code for the routine shown, but if your kernel has +debug symbols the C code will also be available. (Debug symbols can be enabled +in the kernel hacking menu of the menu configuration.) For example:: + + objdump -r -S -l --disassemble net/dccp/ipv4.o + +.. note:: + + You need to be at the top level of the kernel tree for this to pick up + your C files. + +If you don't have access to the code you can also debug on some crash dumps +e.g. crash dump output as shown by Dave Miller:: + + EIP is at ip_queue_xmit+0x14/0x4c0 + ... + Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00 + 00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08 + <8b> 83 3c 01 00 00 89 44 24 14 8b 45 28 85 c0 89 44 24 18 0f 85 + + Put the bytes into a "foo.s" file like this: + + .text + .globl foo + foo: + .byte .... /* bytes from Code: part of OOPS dump */ + + Compile it with "gcc -c -o foo.o foo.s" then look at the output of + "objdump --disassemble foo.o". + + Output: + + ip_queue_xmit: + push %ebp + push %edi + push %esi + push %ebx + sub $0xbc, %esp + mov 0xd0(%esp), %ebp ! %ebp = arg0 (skb) + mov 0x8(%ebp), %ebx ! %ebx = skb->sk + mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt + +In addition, you can use GDB to figure out the exact file and line +number of the OOPS from the ``vmlinux`` file. If you have +``CONFIG_DEBUG_INFO`` enabled, you can simply copy the EIP value from the +OOPS:: + + EIP: 0060:[] Not tainted VLI + +And use GDB to translate that to human-readable form:: + + gdb vmlinux + (gdb) l *0xc021e50e + +If you don't have ``CONFIG_DEBUG_INFO`` enabled, you use the function +offset from the OOPS:: + + EIP is at vt_ioctl+0xda8/0x1482 + +And recompile the kernel with ``CONFIG_DEBUG_INFO`` enabled:: + + make vmlinux + gdb vmlinux + (gdb) p vt_ioctl + (gdb) l *(0x
+ 0xda8) + +or, as one command:: + + (gdb) l *(vt_ioctl + 0xda8) + +If you have a call trace, such as:: + + Call Trace: + [] :jbd:log_wait_commit+0xa3/0xf5 + [] autoremove_wake_function+0x0/0x2e + [] :jbd:journal_stop+0x1be/0x1ee + ... + +this shows the problem in the :jbd: module. You can load that module in gdb +and list the relevant code:: + + gdb fs/jbd/jbd.ko + (gdb) p log_wait_commit + (gdb) l *(0x
+ 0xa3) + +or:: + + (gdb) l *(log_wait_commit + 0xa3) + + +Another very useful option of the Kernel Hacking section in menuconfig is +Debug memory allocations. This will help you see whether data has been +initialised and not set before use etc. To see the values that get assigned +with this look at ``mm/slab.c`` and search for ``POISON_INUSE``. When using +this an Oops will often show the poisoned data instead of zero which is the +default. + +Once you have worked out a fix please submit it upstream. After all open +source is about sharing what you do and don't you want to be recognised for +your genius? + +Please do read :ref:`Documentation/SubmittingPatches ` +though to help your code get accepted. diff --git a/Documentation/admin-guide/conf.py b/Documentation/admin-guide/conf.py new file mode 100644 index 000000000000..86f738953799 --- /dev/null +++ b/Documentation/admin-guide/conf.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8; mode: python -*- + +project = 'Linux Kernel User Documentation' + +tags.add("subproject") + +latex_documents = [ + ('index', 'linux-user.tex', 'Linux Kernel User Documentation', + 'The kernel development community', 'manual'), +] diff --git a/Documentation/admin-guide/devices.rst b/Documentation/admin-guide/devices.rst new file mode 100644 index 000000000000..b29555041531 --- /dev/null +++ b/Documentation/admin-guide/devices.rst @@ -0,0 +1,3350 @@ + +Linux allocated devices (4.x+ version) +====================================== + +This list is the Linux Device List, the official registry of allocated +device numbers and ``/dev`` directory nodes for the Linux operating +system. + +The LaTeX version of this document is no longer maintained, nor is +the document that used to reside at lanana.org. This version in the +mainline Linux kernel is the master document. Updates shall be sent +as patches to the kernel maintainers (see the +:ref:`Documentation/SubmittingPatches ` document). +Specifically explore the sections titled "CHAR and MISC DRIVERS", and +"BLOCK LAYER" in the MAINTAINERS file to find the right maintainers +to involve for character and block devices. + +This document is included by reference into the Filesystem Hierarchy +Standard (FHS). The FHS is available from http://www.pathname.com/fhs/. + +Allocations marked (68k/Amiga) apply to Linux/68k on the Amiga +platform only. Allocations marked (68k/Atari) apply to Linux/68k on +the Atari platform only. + +This document is in the public domain. The authors requests, however, +that semantically altered versions are not distributed without +permission of the authors, assuming the authors can be contacted without +an unreasonable effort. + + +.. attention:: + + DEVICE DRIVERS AUTHORS PLEASE READ THIS + + Linux now has extensive support for dynamic allocation of device numbering + and can use ``sysfs`` and ``udev`` (``systemd``) to handle the naming needs. + There are still some exceptions in the serial and boot device area. Before + asking for a device number make sure you actually need one. + + To have a major number allocated, or a minor number in situations + where that applies (e.g. busmice), please submit a patch and send to + the authors as indicated above. + + Keep the description of the device *in the same format + as this list*. The reason for this is that it is the only way we have + found to ensure we have all the requisite information to publish your + device and avoid conflicts. + + Finally, sometimes we have to play "namespace police." Please don't be + offended. We often get submissions for ``/dev`` names that would be bound + to cause conflicts down the road. We are trying to avoid getting in a + situation where we would have to suffer an incompatible forward + change. Therefore, please consult with us **before** you make your + device names and numbers in any way public, at least to the point + where it would be at all difficult to get them changed. + + Your cooperation is appreciated. + +:: + + 0 Unnamed devices (e.g. non-device mounts) + 0 = reserved as null device number + See block major 144, 145, 146 for expansion areas. + + 1 char Memory devices + 1 = /dev/mem Physical memory access + 2 = /dev/kmem Kernel virtual memory access + 3 = /dev/null Null device + 4 = /dev/port I/O port access + 5 = /dev/zero Null byte source + 6 = /dev/core OBSOLETE - replaced by /proc/kcore + 7 = /dev/full Returns ENOSPC on write + 8 = /dev/random Nondeterministic random number gen. + 9 = /dev/urandom Faster, less secure random number gen. + 10 = /dev/aio Asynchronous I/O notification interface + 11 = /dev/kmsg Writes to this come out as printk's, reads + export the buffered printk records. + 12 = /dev/oldmem OBSOLETE - replaced by /proc/vmcore + + 1 block RAM disk + 0 = /dev/ram0 First RAM disk + 1 = /dev/ram1 Second RAM disk + ... + 250 = /dev/initrd Initial RAM disk + + Older kernels had /dev/ramdisk (1, 1) here. + /dev/initrd refers to a RAM disk which was preloaded + by the boot loader; newer kernels use /dev/ram0 for + the initrd. + + 2 char Pseudo-TTY masters + 0 = /dev/ptyp0 First PTY master + 1 = /dev/ptyp1 Second PTY master + ... + 255 = /dev/ptyef 256th PTY master + + Pseudo-tty's are named as follows: + * Masters are "pty", slaves are "tty"; + * the fourth letter is one of pqrstuvwxyzabcde indicating + the 1st through 16th series of 16 pseudo-ttys each, and + * the fifth letter is one of 0123456789abcdef indicating + the position within the series. + + These are the old-style (BSD) PTY devices; Unix98 + devices are on major 128 and above and use the PTY + master multiplex (/dev/ptmx) to acquire a PTY on + demand. + + 2 block Floppy disks + 0 = /dev/fd0 Controller 0, drive 0, autodetect + 1 = /dev/fd1 Controller 0, drive 1, autodetect + 2 = /dev/fd2 Controller 0, drive 2, autodetect + 3 = /dev/fd3 Controller 0, drive 3, autodetect + 128 = /dev/fd4 Controller 1, drive 0, autodetect + 129 = /dev/fd5 Controller 1, drive 1, autodetect + 130 = /dev/fd6 Controller 1, drive 2, autodetect + 131 = /dev/fd7 Controller 1, drive 3, autodetect + + To specify format, add to the autodetect device number: + 0 = /dev/fd? Autodetect format + 4 = /dev/fd?d360 5.25" 360K in a 360K drive(1) + 20 = /dev/fd?h360 5.25" 360K in a 1200K drive(1) + 48 = /dev/fd?h410 5.25" 410K in a 1200K drive + 64 = /dev/fd?h420 5.25" 420K in a 1200K drive + 24 = /dev/fd?h720 5.25" 720K in a 1200K drive + 80 = /dev/fd?h880 5.25" 880K in a 1200K drive(1) + 8 = /dev/fd?h1200 5.25" 1200K in a 1200K drive(1) + 40 = /dev/fd?h1440 5.25" 1440K in a 1200K drive(1) + 56 = /dev/fd?h1476 5.25" 1476K in a 1200K drive + 72 = /dev/fd?h1494 5.25" 1494K in a 1200K drive + 92 = /dev/fd?h1600 5.25" 1600K in a 1200K drive(1) + + 12 = /dev/fd?u360 3.5" 360K Double Density(2) + 16 = /dev/fd?u720 3.5" 720K Double Density(1) + 120 = /dev/fd?u800 3.5" 800K Double Density(2) + 52 = /dev/fd?u820 3.5" 820K Double Density + 68 = /dev/fd?u830 3.5" 830K Double Density + 84 = /dev/fd?u1040 3.5" 1040K Double Density(1) + 88 = /dev/fd?u1120 3.5" 1120K Double Density(1) + 28 = /dev/fd?u1440 3.5" 1440K High Density(1) + 124 = /dev/fd?u1600 3.5" 1600K High Density(1) + 44 = /dev/fd?u1680 3.5" 1680K High Density(3) + 60 = /dev/fd?u1722 3.5" 1722K High Density + 76 = /dev/fd?u1743 3.5" 1743K High Density + 96 = /dev/fd?u1760 3.5" 1760K High Density + 116 = /dev/fd?u1840 3.5" 1840K High Density(3) + 100 = /dev/fd?u1920 3.5" 1920K High Density(1) + 32 = /dev/fd?u2880 3.5" 2880K Extra Density(1) + 104 = /dev/fd?u3200 3.5" 3200K Extra Density + 108 = /dev/fd?u3520 3.5" 3520K Extra Density + 112 = /dev/fd?u3840 3.5" 3840K Extra Density(1) + + 36 = /dev/fd?CompaQ Compaq 2880K drive; obsolete? + + (1) Autodetectable format + (2) Autodetectable format in a Double Density (720K) drive only + (3) Autodetectable format in a High Density (1440K) drive only + + NOTE: The letter in the device name (d, q, h or u) + signifies the type of drive: 5.25" Double Density (d), + 5.25" Quad Density (q), 5.25" High Density (h) or 3.5" + (any model, u). The use of the capital letters D, H + and E for the 3.5" models have been deprecated, since + the drive type is insignificant for these devices. + + 3 char Pseudo-TTY slaves + 0 = /dev/ttyp0 First PTY slave + 1 = /dev/ttyp1 Second PTY slave + ... + 255 = /dev/ttyef 256th PTY slave + + These are the old-style (BSD) PTY devices; Unix98 + devices are on major 136 and above. + + 3 block First MFM, RLL and IDE hard disk/CD-ROM interface + 0 = /dev/hda Master: whole disk (or CD-ROM) + 64 = /dev/hdb Slave: whole disk (or CD-ROM) + + For partitions, add to the whole disk device number: + 0 = /dev/hd? Whole disk + 1 = /dev/hd?1 First partition + 2 = /dev/hd?2 Second partition + ... + 63 = /dev/hd?63 63rd partition + + For Linux/i386, partitions 1-4 are the primary + partitions, and 5 and above are logical partitions. + Other versions of Linux use partitioning schemes + appropriate to their respective architectures. + + 4 char TTY devices + 0 = /dev/tty0 Current virtual console + + 1 = /dev/tty1 First virtual console + ... + 63 = /dev/tty63 63rd virtual console + 64 = /dev/ttyS0 First UART serial port + ... + 255 = /dev/ttyS191 192nd UART serial port + + UART serial ports refer to 8250/16450/16550 series devices. + + Older versions of the Linux kernel used this major + number for BSD PTY devices. As of Linux 2.1.115, this + is no longer supported. Use major numbers 2 and 3. + + 4 block Aliases for dynamically allocated major devices to be used + when its not possible to create the real device nodes + because the root filesystem is mounted read-only. + + 0 = /dev/root + + 5 char Alternate TTY devices + 0 = /dev/tty Current TTY device + 1 = /dev/console System console + 2 = /dev/ptmx PTY master multiplex + 3 = /dev/ttyprintk User messages via printk TTY device + 64 = /dev/cua0 Callout device for ttyS0 + ... + 255 = /dev/cua191 Callout device for ttyS191 + + (5,1) is /dev/console starting with Linux 2.1.71. See + the section on terminal devices for more information + on /dev/console. + + 6 char Parallel printer devices + 0 = /dev/lp0 Parallel printer on parport0 + 1 = /dev/lp1 Parallel printer on parport1 + ... + + Current Linux kernels no longer have a fixed mapping + between parallel ports and I/O addresses. Instead, + they are redirected through the parport multiplex layer. + + 7 char Virtual console capture devices + 0 = /dev/vcs Current vc text contents + 1 = /dev/vcs1 tty1 text contents + ... + 63 = /dev/vcs63 tty63 text contents + 128 = /dev/vcsa Current vc text/attribute contents + 129 = /dev/vcsa1 tty1 text/attribute contents + ... + 191 = /dev/vcsa63 tty63 text/attribute contents + + NOTE: These devices permit both read and write access. + + 7 block Loopback devices + 0 = /dev/loop0 First loop device + 1 = /dev/loop1 Second loop device + ... + + The loop devices are used to mount filesystems not + associated with block devices. The binding to the + loop devices is handled by mount(8) or losetup(8). + + 8 block SCSI disk devices (0-15) + 0 = /dev/sda First SCSI disk whole disk + 16 = /dev/sdb Second SCSI disk whole disk + 32 = /dev/sdc Third SCSI disk whole disk + ... + 240 = /dev/sdp Sixteenth SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 9 char SCSI tape devices + 0 = /dev/st0 First SCSI tape, mode 0 + 1 = /dev/st1 Second SCSI tape, mode 0 + ... + 32 = /dev/st0l First SCSI tape, mode 1 + 33 = /dev/st1l Second SCSI tape, mode 1 + ... + 64 = /dev/st0m First SCSI tape, mode 2 + 65 = /dev/st1m Second SCSI tape, mode 2 + ... + 96 = /dev/st0a First SCSI tape, mode 3 + 97 = /dev/st1a Second SCSI tape, mode 3 + ... + 128 = /dev/nst0 First SCSI tape, mode 0, no rewind + 129 = /dev/nst1 Second SCSI tape, mode 0, no rewind + ... + 160 = /dev/nst0l First SCSI tape, mode 1, no rewind + 161 = /dev/nst1l Second SCSI tape, mode 1, no rewind + ... + 192 = /dev/nst0m First SCSI tape, mode 2, no rewind + 193 = /dev/nst1m Second SCSI tape, mode 2, no rewind + ... + 224 = /dev/nst0a First SCSI tape, mode 3, no rewind + 225 = /dev/nst1a Second SCSI tape, mode 3, no rewind + ... + + "No rewind" refers to the omission of the default + automatic rewind on device close. The MTREW or MTOFFL + ioctl()'s can be used to rewind the tape regardless of + the device used to access it. + + 9 block Metadisk (RAID) devices + 0 = /dev/md0 First metadisk group + 1 = /dev/md1 Second metadisk group + ... + + The metadisk driver is used to span a + filesystem across multiple physical disks. + + 10 char Non-serial mice, misc features + 0 = /dev/logibm Logitech bus mouse + 1 = /dev/psaux PS/2-style mouse port + 2 = /dev/inportbm Microsoft Inport bus mouse + 3 = /dev/atibm ATI XL bus mouse + 4 = /dev/jbm J-mouse + 4 = /dev/amigamouse Amiga mouse (68k/Amiga) + 5 = /dev/atarimouse Atari mouse + 6 = /dev/sunmouse Sun mouse + 7 = /dev/amigamouse1 Second Amiga mouse + 8 = /dev/smouse Simple serial mouse driver + 9 = /dev/pc110pad IBM PC-110 digitizer pad + 10 = /dev/adbmouse Apple Desktop Bus mouse + 11 = /dev/vrtpanel Vr41xx embedded touch panel + 13 = /dev/vpcmouse Connectix Virtual PC Mouse + 14 = /dev/touchscreen/ucb1x00 UCB 1x00 touchscreen + 15 = /dev/touchscreen/mk712 MK712 touchscreen + 128 = /dev/beep Fancy beep device + 129 = + 130 = /dev/watchdog Watchdog timer port + 131 = /dev/temperature Machine internal temperature + 132 = /dev/hwtrap Hardware fault trap + 133 = /dev/exttrp External device trap + 134 = /dev/apm_bios Advanced Power Management BIOS + 135 = /dev/rtc Real Time Clock + 137 = /dev/vhci Bluetooth virtual HCI driver + 139 = /dev/openprom SPARC OpenBoot PROM + 140 = /dev/relay8 Berkshire Products Octal relay card + 141 = /dev/relay16 Berkshire Products ISO-16 relay card + 142 = + 143 = /dev/pciconf PCI configuration space + 144 = /dev/nvram Non-volatile configuration RAM + 145 = /dev/hfmodem Soundcard shortwave modem control + 146 = /dev/graphics Linux/SGI graphics device + 147 = /dev/opengl Linux/SGI OpenGL pipe + 148 = /dev/gfx Linux/SGI graphics effects device + 149 = /dev/input/mouse Linux/SGI Irix emulation mouse + 150 = /dev/input/keyboard Linux/SGI Irix emulation keyboard + 151 = /dev/led Front panel LEDs + 152 = /dev/kpoll Kernel Poll Driver + 153 = /dev/mergemem Memory merge device + 154 = /dev/pmu Macintosh PowerBook power manager + 155 = /dev/isictl MultiTech ISICom serial control + 156 = /dev/lcd Front panel LCD display + 157 = /dev/ac Applicom Intl Profibus card + 158 = /dev/nwbutton Netwinder external button + 159 = /dev/nwdebug Netwinder debug interface + 160 = /dev/nwflash Netwinder flash memory + 161 = /dev/userdma User-space DMA access + 162 = /dev/smbus System Management Bus + 163 = /dev/lik Logitech Internet Keyboard + 164 = /dev/ipmo Intel Intelligent Platform Management + 165 = /dev/vmmon VMware virtual machine monitor + 166 = /dev/i2o/ctl I2O configuration manager + 167 = /dev/specialix_sxctl Specialix serial control + 168 = /dev/tcldrv Technology Concepts serial control + 169 = /dev/specialix_rioctl Specialix RIO serial control + 170 = /dev/thinkpad/thinkpad IBM Thinkpad devices + 171 = /dev/srripc QNX4 API IPC manager + 172 = /dev/usemaclone Semaphore clone device + 173 = /dev/ipmikcs Intelligent Platform Management + 174 = /dev/uctrl SPARCbook 3 microcontroller + 175 = /dev/agpgart AGP Graphics Address Remapping Table + 176 = /dev/gtrsc Gorgy Timing radio clock + 177 = /dev/cbm Serial CBM bus + 178 = /dev/jsflash JavaStation OS flash SIMM + 179 = /dev/xsvc High-speed shared-mem/semaphore service + 180 = /dev/vrbuttons Vr41xx button input device + 181 = /dev/toshiba Toshiba laptop SMM support + 182 = /dev/perfctr Performance-monitoring counters + 183 = /dev/hwrng Generic random number generator + 184 = /dev/cpu/microcode CPU microcode update interface + 186 = /dev/atomicps Atomic shapshot of process state data + 187 = /dev/irnet IrNET device + 188 = /dev/smbusbios SMBus BIOS + 189 = /dev/ussp_ctl User space serial port control + 190 = /dev/crash Mission Critical Linux crash dump facility + 191 = /dev/pcl181 + 192 = /dev/nas_xbus NAS xbus LCD/buttons access + 193 = /dev/d7s SPARC 7-segment display + 194 = /dev/zkshim Zero-Knowledge network shim control + 195 = /dev/elographics/e2201 Elographics touchscreen E271-2201 + 196 = /dev/vfio/vfio VFIO userspace driver interface + 197 = /dev/pxa3xx-gcu PXA3xx graphics controller unit driver + 198 = /dev/sexec Signed executable interface + 199 = /dev/scanners/cuecat :CueCat barcode scanner + 200 = /dev/net/tun TAP/TUN network device + 201 = /dev/button/gulpb Transmeta GULP-B buttons + 202 = /dev/emd/ctl Enhanced Metadisk RAID (EMD) control + 203 = /dev/cuse Cuse (character device in user-space) + 204 = /dev/video/em8300 EM8300 DVD decoder control + 205 = /dev/video/em8300_mv EM8300 DVD decoder video + 206 = /dev/video/em8300_ma EM8300 DVD decoder audio + 207 = /dev/video/em8300_sp EM8300 DVD decoder subpicture + 208 = /dev/compaq/cpqphpc Compaq PCI Hot Plug Controller + 209 = /dev/compaq/cpqrid Compaq Remote Insight Driver + 210 = /dev/impi/bt IMPI coprocessor block transfer + 211 = /dev/impi/smic IMPI coprocessor stream interface + 212 = /dev/watchdogs/0 First watchdog device + 213 = /dev/watchdogs/1 Second watchdog device + 214 = /dev/watchdogs/2 Third watchdog device + 215 = /dev/watchdogs/3 Fourth watchdog device + 216 = /dev/fujitsu/apanel Fujitsu/Siemens application panel + 217 = /dev/ni/natmotn National Instruments Motion + 218 = /dev/kchuid Inter-process chuid control + 219 = /dev/modems/mwave MWave modem firmware upload + 220 = /dev/mptctl Message passing technology (MPT) control + 221 = /dev/mvista/hssdsi Montavista PICMG hot swap system driver + 222 = /dev/mvista/hasi Montavista PICMG high availability + 223 = /dev/input/uinput User level driver support for input + 224 = /dev/tpm TCPA TPM driver + 225 = /dev/pps Pulse Per Second driver + 226 = /dev/systrace Systrace device + 227 = /dev/mcelog X86_64 Machine Check Exception driver + 228 = /dev/hpet HPET driver + 229 = /dev/fuse Fuse (virtual filesystem in user-space) + 230 = /dev/midishare MidiShare driver + 231 = /dev/snapshot System memory snapshot device + 232 = /dev/kvm Kernel-based virtual machine (hardware virtualization extensions) + 233 = /dev/kmview View-OS A process with a view + 234 = /dev/btrfs-control Btrfs control device + 235 = /dev/autofs Autofs control device + 236 = /dev/mapper/control Device-Mapper control device + 237 = /dev/loop-control Loopback control device + 238 = /dev/vhost-net Host kernel accelerator for virtio net + 239 = /dev/uhid User-space I/O driver support for HID subsystem + + 240-254 Reserved for local use + 255 Reserved for MISC_DYNAMIC_MINOR + + 11 char Raw keyboard device (Linux/SPARC only) + 0 = /dev/kbd Raw keyboard device + + 11 char Serial Mux device (Linux/PA-RISC only) + 0 = /dev/ttyB0 First mux port + 1 = /dev/ttyB1 Second mux port + ... + + 11 block SCSI CD-ROM devices + 0 = /dev/scd0 First SCSI CD-ROM + 1 = /dev/scd1 Second SCSI CD-ROM + ... + + The prefix /dev/sr (instead of /dev/scd) has been deprecated. + + 12 char QIC-02 tape + 2 = /dev/ntpqic11 QIC-11, no rewind-on-close + 3 = /dev/tpqic11 QIC-11, rewind-on-close + 4 = /dev/ntpqic24 QIC-24, no rewind-on-close + 5 = /dev/tpqic24 QIC-24, rewind-on-close + 6 = /dev/ntpqic120 QIC-120, no rewind-on-close + 7 = /dev/tpqic120 QIC-120, rewind-on-close + 8 = /dev/ntpqic150 QIC-150, no rewind-on-close + 9 = /dev/tpqic150 QIC-150, rewind-on-close + + The device names specified are proposed -- if there + are "standard" names for these devices, please let me know. + + 12 block + + 13 char Input core + 0 = /dev/input/js0 First joystick + 1 = /dev/input/js1 Second joystick + ... + 32 = /dev/input/mouse0 First mouse + 33 = /dev/input/mouse1 Second mouse + ... + 63 = /dev/input/mice Unified mouse + 64 = /dev/input/event0 First event queue + 65 = /dev/input/event1 Second event queue + ... + + Each device type has 5 bits (32 minors). + + 13 block Previously used for the XT disk (/dev/xdN) + Deleted in kernel v3.9. + + 14 char Open Sound System (OSS) + 0 = /dev/mixer Mixer control + 1 = /dev/sequencer Audio sequencer + 2 = /dev/midi00 First MIDI port + 3 = /dev/dsp Digital audio + 4 = /dev/audio Sun-compatible digital audio + 6 = + 7 = /dev/audioctl SPARC audio control device + 8 = /dev/sequencer2 Sequencer -- alternate device + 16 = /dev/mixer1 Second soundcard mixer control + 17 = /dev/patmgr0 Sequencer patch manager + 18 = /dev/midi01 Second MIDI port + 19 = /dev/dsp1 Second soundcard digital audio + 20 = /dev/audio1 Second soundcard Sun digital audio + 33 = /dev/patmgr1 Sequencer patch manager + 34 = /dev/midi02 Third MIDI port + 50 = /dev/midi03 Fourth MIDI port + + 14 block + + 15 char Joystick + 0 = /dev/js0 First analog joystick + 1 = /dev/js1 Second analog joystick + ... + 128 = /dev/djs0 First digital joystick + 129 = /dev/djs1 Second digital joystick + ... + 15 block Sony CDU-31A/CDU-33A CD-ROM + 0 = /dev/sonycd Sony CDU-31a CD-ROM + + 16 char Non-SCSI scanners + 0 = /dev/gs4500 Genius 4500 handheld scanner + + 16 block GoldStar CD-ROM + 0 = /dev/gscd GoldStar CD-ROM + + 17 char OBSOLETE (was Chase serial card) + 0 = /dev/ttyH0 First Chase port + 1 = /dev/ttyH1 Second Chase port + ... + 17 block Optics Storage CD-ROM + 0 = /dev/optcd Optics Storage CD-ROM + + 18 char OBSOLETE (was Chase serial card - alternate devices) + 0 = /dev/cuh0 Callout device for ttyH0 + 1 = /dev/cuh1 Callout device for ttyH1 + ... + 18 block Sanyo CD-ROM + 0 = /dev/sjcd Sanyo CD-ROM + + 19 char Cyclades serial card + 0 = /dev/ttyC0 First Cyclades port + ... + 31 = /dev/ttyC31 32nd Cyclades port + + 19 block "Double" compressed disk + 0 = /dev/double0 First compressed disk + ... + 7 = /dev/double7 Eighth compressed disk + 128 = /dev/cdouble0 Mirror of first compressed disk + ... + 135 = /dev/cdouble7 Mirror of eighth compressed disk + + See the Double documentation for the meaning of the + mirror devices. + + 20 char Cyclades serial card - alternate devices + 0 = /dev/cub0 Callout device for ttyC0 + ... + 31 = /dev/cub31 Callout device for ttyC31 + + 20 block Hitachi CD-ROM (under development) + 0 = /dev/hitcd Hitachi CD-ROM + + 21 char Generic SCSI access + 0 = /dev/sg0 First generic SCSI device + 1 = /dev/sg1 Second generic SCSI device + ... + + Most distributions name these /dev/sga, /dev/sgb...; + this sets an unnecessary limit of 26 SCSI devices in + the system and is counter to standard Linux + device-naming practice. + + 21 block Acorn MFM hard drive interface + 0 = /dev/mfma First MFM drive whole disk + 64 = /dev/mfmb Second MFM drive whole disk + + This device is used on the ARM-based Acorn RiscPC. + Partitions are handled the same way as for IDE disks + (see major number 3). + + 22 char Digiboard serial card + 0 = /dev/ttyD0 First Digiboard port + 1 = /dev/ttyD1 Second Digiboard port + ... + 22 block Second IDE hard disk/CD-ROM interface + 0 = /dev/hdc Master: whole disk (or CD-ROM) + 64 = /dev/hdd Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 23 char Digiboard serial card - alternate devices + 0 = /dev/cud0 Callout device for ttyD0 + 1 = /dev/cud1 Callout device for ttyD1 + ... + 23 block Mitsumi proprietary CD-ROM + 0 = /dev/mcd Mitsumi CD-ROM + + 24 char Stallion serial card + 0 = /dev/ttyE0 Stallion port 0 card 0 + 1 = /dev/ttyE1 Stallion port 1 card 0 + ... + 64 = /dev/ttyE64 Stallion port 0 card 1 + 65 = /dev/ttyE65 Stallion port 1 card 1 + ... + 128 = /dev/ttyE128 Stallion port 0 card 2 + 129 = /dev/ttyE129 Stallion port 1 card 2 + ... + 192 = /dev/ttyE192 Stallion port 0 card 3 + 193 = /dev/ttyE193 Stallion port 1 card 3 + ... + 24 block Sony CDU-535 CD-ROM + 0 = /dev/cdu535 Sony CDU-535 CD-ROM + + 25 char Stallion serial card - alternate devices + 0 = /dev/cue0 Callout device for ttyE0 + 1 = /dev/cue1 Callout device for ttyE1 + ... + 64 = /dev/cue64 Callout device for ttyE64 + 65 = /dev/cue65 Callout device for ttyE65 + ... + 128 = /dev/cue128 Callout device for ttyE128 + 129 = /dev/cue129 Callout device for ttyE129 + ... + 192 = /dev/cue192 Callout device for ttyE192 + 193 = /dev/cue193 Callout device for ttyE193 + ... + 25 block First Matsushita (Panasonic/SoundBlaster) CD-ROM + 0 = /dev/sbpcd0 Panasonic CD-ROM controller 0 unit 0 + 1 = /dev/sbpcd1 Panasonic CD-ROM controller 0 unit 1 + 2 = /dev/sbpcd2 Panasonic CD-ROM controller 0 unit 2 + 3 = /dev/sbpcd3 Panasonic CD-ROM controller 0 unit 3 + + 26 char + + 26 block Second Matsushita (Panasonic/SoundBlaster) CD-ROM + 0 = /dev/sbpcd4 Panasonic CD-ROM controller 1 unit 0 + 1 = /dev/sbpcd5 Panasonic CD-ROM controller 1 unit 1 + 2 = /dev/sbpcd6 Panasonic CD-ROM controller 1 unit 2 + 3 = /dev/sbpcd7 Panasonic CD-ROM controller 1 unit 3 + + 27 char QIC-117 tape + 0 = /dev/qft0 Unit 0, rewind-on-close + 1 = /dev/qft1 Unit 1, rewind-on-close + 2 = /dev/qft2 Unit 2, rewind-on-close + 3 = /dev/qft3 Unit 3, rewind-on-close + 4 = /dev/nqft0 Unit 0, no rewind-on-close + 5 = /dev/nqft1 Unit 1, no rewind-on-close + 6 = /dev/nqft2 Unit 2, no rewind-on-close + 7 = /dev/nqft3 Unit 3, no rewind-on-close + 16 = /dev/zqft0 Unit 0, rewind-on-close, compression + 17 = /dev/zqft1 Unit 1, rewind-on-close, compression + 18 = /dev/zqft2 Unit 2, rewind-on-close, compression + 19 = /dev/zqft3 Unit 3, rewind-on-close, compression + 20 = /dev/nzqft0 Unit 0, no rewind-on-close, compression + 21 = /dev/nzqft1 Unit 1, no rewind-on-close, compression + 22 = /dev/nzqft2 Unit 2, no rewind-on-close, compression + 23 = /dev/nzqft3 Unit 3, no rewind-on-close, compression + 32 = /dev/rawqft0 Unit 0, rewind-on-close, no file marks + 33 = /dev/rawqft1 Unit 1, rewind-on-close, no file marks + 34 = /dev/rawqft2 Unit 2, rewind-on-close, no file marks + 35 = /dev/rawqft3 Unit 3, rewind-on-close, no file marks + 36 = /dev/nrawqft0 Unit 0, no rewind-on-close, no file marks + 37 = /dev/nrawqft1 Unit 1, no rewind-on-close, no file marks + 38 = /dev/nrawqft2 Unit 2, no rewind-on-close, no file marks + 39 = /dev/nrawqft3 Unit 3, no rewind-on-close, no file marks + + 27 block Third Matsushita (Panasonic/SoundBlaster) CD-ROM + 0 = /dev/sbpcd8 Panasonic CD-ROM controller 2 unit 0 + 1 = /dev/sbpcd9 Panasonic CD-ROM controller 2 unit 1 + 2 = /dev/sbpcd10 Panasonic CD-ROM controller 2 unit 2 + 3 = /dev/sbpcd11 Panasonic CD-ROM controller 2 unit 3 + + 28 char Stallion serial card - card programming + 0 = /dev/staliomem0 First Stallion card I/O memory + 1 = /dev/staliomem1 Second Stallion card I/O memory + 2 = /dev/staliomem2 Third Stallion card I/O memory + 3 = /dev/staliomem3 Fourth Stallion card I/O memory + + 28 char Atari SLM ACSI laser printer (68k/Atari) + 0 = /dev/slm0 First SLM laser printer + 1 = /dev/slm1 Second SLM laser printer + ... + 28 block Fourth Matsushita (Panasonic/SoundBlaster) CD-ROM + 0 = /dev/sbpcd12 Panasonic CD-ROM controller 3 unit 0 + 1 = /dev/sbpcd13 Panasonic CD-ROM controller 3 unit 1 + 2 = /dev/sbpcd14 Panasonic CD-ROM controller 3 unit 2 + 3 = /dev/sbpcd15 Panasonic CD-ROM controller 3 unit 3 + + 28 block ACSI disk (68k/Atari) + 0 = /dev/ada First ACSI disk whole disk + 16 = /dev/adb Second ACSI disk whole disk + 32 = /dev/adc Third ACSI disk whole disk + ... + 240 = /dev/adp 16th ACSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15, like SCSI. + + 29 char Universal frame buffer + 0 = /dev/fb0 First frame buffer + 1 = /dev/fb1 Second frame buffer + ... + 31 = /dev/fb31 32nd frame buffer + + 29 block Aztech/Orchid/Okano/Wearnes CD-ROM + 0 = /dev/aztcd Aztech CD-ROM + + 30 char iBCS-2 compatibility devices + 0 = /dev/socksys Socket access + 1 = /dev/spx SVR3 local X interface + 32 = /dev/inet/ip Network access + 33 = /dev/inet/icmp + 34 = /dev/inet/ggp + 35 = /dev/inet/ipip + 36 = /dev/inet/tcp + 37 = /dev/inet/egp + 38 = /dev/inet/pup + 39 = /dev/inet/udp + 40 = /dev/inet/idp + 41 = /dev/inet/rawip + + Additionally, iBCS-2 requires the following links: + + /dev/ip -> /dev/inet/ip + /dev/icmp -> /dev/inet/icmp + /dev/ggp -> /dev/inet/ggp + /dev/ipip -> /dev/inet/ipip + /dev/tcp -> /dev/inet/tcp + /dev/egp -> /dev/inet/egp + /dev/pup -> /dev/inet/pup + /dev/udp -> /dev/inet/udp + /dev/idp -> /dev/inet/idp + /dev/rawip -> /dev/inet/rawip + /dev/inet/arp -> /dev/inet/udp + /dev/inet/rip -> /dev/inet/udp + /dev/nfsd -> /dev/socksys + /dev/X0R -> /dev/null (? apparently not required ?) + + 30 block Philips LMS CM-205 CD-ROM + 0 = /dev/cm205cd Philips LMS CM-205 CD-ROM + + /dev/lmscd is an older name for this device. This + driver does not work with the CM-205MS CD-ROM. + + 31 char MPU-401 MIDI + 0 = /dev/mpu401data MPU-401 data port + 1 = /dev/mpu401stat MPU-401 status port + + 31 block ROM/flash memory card + 0 = /dev/rom0 First ROM card (rw) + ... + 7 = /dev/rom7 Eighth ROM card (rw) + 8 = /dev/rrom0 First ROM card (ro) + ... + 15 = /dev/rrom7 Eighth ROM card (ro) + 16 = /dev/flash0 First flash memory card (rw) + ... + 23 = /dev/flash7 Eighth flash memory card (rw) + 24 = /dev/rflash0 First flash memory card (ro) + ... + 31 = /dev/rflash7 Eighth flash memory card (ro) + + The read-write (rw) devices support back-caching + written data in RAM, as well as writing to flash RAM + devices. The read-only devices (ro) support reading + only. + + 32 char Specialix serial card + 0 = /dev/ttyX0 First Specialix port + 1 = /dev/ttyX1 Second Specialix port + ... + 32 block Philips LMS CM-206 CD-ROM + 0 = /dev/cm206cd Philips LMS CM-206 CD-ROM + + 33 char Specialix serial card - alternate devices + 0 = /dev/cux0 Callout device for ttyX0 + 1 = /dev/cux1 Callout device for ttyX1 + ... + 33 block Third IDE hard disk/CD-ROM interface + 0 = /dev/hde Master: whole disk (or CD-ROM) + 64 = /dev/hdf Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 34 char Z8530 HDLC driver + 0 = /dev/scc0 First Z8530, first port + 1 = /dev/scc1 First Z8530, second port + 2 = /dev/scc2 Second Z8530, first port + 3 = /dev/scc3 Second Z8530, second port + ... + + In a previous version these devices were named + /dev/sc1 for /dev/scc0, /dev/sc2 for /dev/scc1, and so + on. + + 34 block Fourth IDE hard disk/CD-ROM interface + 0 = /dev/hdg Master: whole disk (or CD-ROM) + 64 = /dev/hdh Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 35 char tclmidi MIDI driver + 0 = /dev/midi0 First MIDI port, kernel timed + 1 = /dev/midi1 Second MIDI port, kernel timed + 2 = /dev/midi2 Third MIDI port, kernel timed + 3 = /dev/midi3 Fourth MIDI port, kernel timed + 64 = /dev/rmidi0 First MIDI port, untimed + 65 = /dev/rmidi1 Second MIDI port, untimed + 66 = /dev/rmidi2 Third MIDI port, untimed + 67 = /dev/rmidi3 Fourth MIDI port, untimed + 128 = /dev/smpte0 First MIDI port, SMPTE timed + 129 = /dev/smpte1 Second MIDI port, SMPTE timed + 130 = /dev/smpte2 Third MIDI port, SMPTE timed + 131 = /dev/smpte3 Fourth MIDI port, SMPTE timed + + 35 block Slow memory ramdisk + 0 = /dev/slram Slow memory ramdisk + + 36 char Netlink support + 0 = /dev/route Routing, device updates, kernel to user + 1 = /dev/skip enSKIP security cache control + 3 = /dev/fwmonitor Firewall packet copies + 16 = /dev/tap0 First Ethertap device + ... + 31 = /dev/tap15 16th Ethertap device + + 36 block OBSOLETE (was MCA ESDI hard disk) + + 37 char IDE tape + 0 = /dev/ht0 First IDE tape + 1 = /dev/ht1 Second IDE tape + ... + 128 = /dev/nht0 First IDE tape, no rewind-on-close + 129 = /dev/nht1 Second IDE tape, no rewind-on-close + ... + + Currently, only one IDE tape drive is supported. + + 37 block Zorro II ramdisk + 0 = /dev/z2ram Zorro II ramdisk + + 38 char Myricom PCI Myrinet board + 0 = /dev/mlanai0 First Myrinet board + 1 = /dev/mlanai1 Second Myrinet board + ... + + This device is used for status query, board control + and "user level packet I/O." This board is also + accessible as a standard networking "eth" device. + + 38 block OBSOLETE (was Linux/AP+) + + 39 char ML-16P experimental I/O board + 0 = /dev/ml16pa-a0 First card, first analog channel + 1 = /dev/ml16pa-a1 First card, second analog channel + ... + 15 = /dev/ml16pa-a15 First card, 16th analog channel + 16 = /dev/ml16pa-d First card, digital lines + 17 = /dev/ml16pa-c0 First card, first counter/timer + 18 = /dev/ml16pa-c1 First card, second counter/timer + 19 = /dev/ml16pa-c2 First card, third counter/timer + 32 = /dev/ml16pb-a0 Second card, first analog channel + 33 = /dev/ml16pb-a1 Second card, second analog channel + ... + 47 = /dev/ml16pb-a15 Second card, 16th analog channel + 48 = /dev/ml16pb-d Second card, digital lines + 49 = /dev/ml16pb-c0 Second card, first counter/timer + 50 = /dev/ml16pb-c1 Second card, second counter/timer + 51 = /dev/ml16pb-c2 Second card, third counter/timer + ... + 39 block + + 40 char + + 40 block + + 41 char Yet Another Micro Monitor + 0 = /dev/yamm Yet Another Micro Monitor + + 41 block + + 42 char Demo/sample use + + 42 block Demo/sample use + + This number is intended for use in sample code, as + well as a general "example" device number. It + should never be used for a device driver that is being + distributed; either obtain an official number or use + the local/experimental range. The sudden addition or + removal of a driver with this number should not cause + ill effects to the system (bugs excepted.) + + IN PARTICULAR, ANY DISTRIBUTION WHICH CONTAINS A + DEVICE DRIVER USING MAJOR NUMBER 42 IS NONCOMPLIANT. + + 43 char isdn4linux virtual modem + 0 = /dev/ttyI0 First virtual modem + ... + 63 = /dev/ttyI63 64th virtual modem + + 43 block Network block devices + 0 = /dev/nb0 First network block device + 1 = /dev/nb1 Second network block device + ... + + Network Block Device is somehow similar to loopback + devices: If you read from it, it sends packet across + network asking server for data. If you write to it, it + sends packet telling server to write. It could be used + to mounting filesystems over the net, swapping over + the net, implementing block device in userland etc. + + 44 char isdn4linux virtual modem - alternate devices + 0 = /dev/cui0 Callout device for ttyI0 + ... + 63 = /dev/cui63 Callout device for ttyI63 + + 44 block Flash Translation Layer (FTL) filesystems + 0 = /dev/ftla FTL on first Memory Technology Device + 16 = /dev/ftlb FTL on second Memory Technology Device + 32 = /dev/ftlc FTL on third Memory Technology Device + ... + 240 = /dev/ftlp FTL on 16th Memory Technology Device + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the partition + limit is 15 rather than 63 per disk (same as SCSI.) + + 45 char isdn4linux ISDN BRI driver + 0 = /dev/isdn0 First virtual B channel raw data + ... + 63 = /dev/isdn63 64th virtual B channel raw data + 64 = /dev/isdnctrl0 First channel control/debug + ... + 127 = /dev/isdnctrl63 64th channel control/debug + + 128 = /dev/ippp0 First SyncPPP device + ... + 191 = /dev/ippp63 64th SyncPPP device + + 255 = /dev/isdninfo ISDN monitor interface + + 45 block Parallel port IDE disk devices + 0 = /dev/pda First parallel port IDE disk + 16 = /dev/pdb Second parallel port IDE disk + 32 = /dev/pdc Third parallel port IDE disk + 48 = /dev/pdd Fourth parallel port IDE disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the partition + limit is 15 rather than 63 per disk. + + 46 char Comtrol Rocketport serial card + 0 = /dev/ttyR0 First Rocketport port + 1 = /dev/ttyR1 Second Rocketport port + ... + 46 block Parallel port ATAPI CD-ROM devices + 0 = /dev/pcd0 First parallel port ATAPI CD-ROM + 1 = /dev/pcd1 Second parallel port ATAPI CD-ROM + 2 = /dev/pcd2 Third parallel port ATAPI CD-ROM + 3 = /dev/pcd3 Fourth parallel port ATAPI CD-ROM + + 47 char Comtrol Rocketport serial card - alternate devices + 0 = /dev/cur0 Callout device for ttyR0 + 1 = /dev/cur1 Callout device for ttyR1 + ... + 47 block Parallel port ATAPI disk devices + 0 = /dev/pf0 First parallel port ATAPI disk + 1 = /dev/pf1 Second parallel port ATAPI disk + 2 = /dev/pf2 Third parallel port ATAPI disk + 3 = /dev/pf3 Fourth parallel port ATAPI disk + + This driver is intended for floppy disks and similar + devices and hence does not support partitioning. + + 48 char SDL RISCom serial card + 0 = /dev/ttyL0 First RISCom port + 1 = /dev/ttyL1 Second RISCom port + ... + 48 block Mylex DAC960 PCI RAID controller; first controller + 0 = /dev/rd/c0d0 First disk, whole disk + 8 = /dev/rd/c0d1 Second disk, whole disk + ... + 248 = /dev/rd/c0d31 32nd disk, whole disk + + For partitions add: + 0 = /dev/rd/c?d? Whole disk + 1 = /dev/rd/c?d?p1 First partition + ... + 7 = /dev/rd/c?d?p7 Seventh partition + + 49 char SDL RISCom serial card - alternate devices + 0 = /dev/cul0 Callout device for ttyL0 + 1 = /dev/cul1 Callout device for ttyL1 + ... + 49 block Mylex DAC960 PCI RAID controller; second controller + 0 = /dev/rd/c1d0 First disk, whole disk + 8 = /dev/rd/c1d1 Second disk, whole disk + ... + 248 = /dev/rd/c1d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 50 char Reserved for GLINT + + 50 block Mylex DAC960 PCI RAID controller; third controller + 0 = /dev/rd/c2d0 First disk, whole disk + 8 = /dev/rd/c2d1 Second disk, whole disk + ... + 248 = /dev/rd/c2d31 32nd disk, whole disk + + 51 char Baycom radio modem OR Radio Tech BIM-XXX-RS232 radio modem + 0 = /dev/bc0 First Baycom radio modem + 1 = /dev/bc1 Second Baycom radio modem + ... + 51 block Mylex DAC960 PCI RAID controller; fourth controller + 0 = /dev/rd/c3d0 First disk, whole disk + 8 = /dev/rd/c3d1 Second disk, whole disk + ... + 248 = /dev/rd/c3d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 52 char Spellcaster DataComm/BRI ISDN card + 0 = /dev/dcbri0 First DataComm card + 1 = /dev/dcbri1 Second DataComm card + 2 = /dev/dcbri2 Third DataComm card + 3 = /dev/dcbri3 Fourth DataComm card + + 52 block Mylex DAC960 PCI RAID controller; fifth controller + 0 = /dev/rd/c4d0 First disk, whole disk + 8 = /dev/rd/c4d1 Second disk, whole disk + ... + 248 = /dev/rd/c4d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 53 char BDM interface for remote debugging MC683xx microcontrollers + 0 = /dev/pd_bdm0 PD BDM interface on lp0 + 1 = /dev/pd_bdm1 PD BDM interface on lp1 + 2 = /dev/pd_bdm2 PD BDM interface on lp2 + 4 = /dev/icd_bdm0 ICD BDM interface on lp0 + 5 = /dev/icd_bdm1 ICD BDM interface on lp1 + 6 = /dev/icd_bdm2 ICD BDM interface on lp2 + + This device is used for the interfacing to the MC683xx + microcontrollers via Background Debug Mode by use of a + Parallel Port interface. PD is the Motorola Public + Domain Interface and ICD is the commercial interface + by P&E. + + 53 block Mylex DAC960 PCI RAID controller; sixth controller + 0 = /dev/rd/c5d0 First disk, whole disk + 8 = /dev/rd/c5d1 Second disk, whole disk + ... + 248 = /dev/rd/c5d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 54 char Electrocardiognosis Holter serial card + 0 = /dev/holter0 First Holter port + 1 = /dev/holter1 Second Holter port + 2 = /dev/holter2 Third Holter port + + A custom serial card used by Electrocardiognosis SRL + to transfer data from Holter + 24-hour heart monitoring equipment. + + 54 block Mylex DAC960 PCI RAID controller; seventh controller + 0 = /dev/rd/c6d0 First disk, whole disk + 8 = /dev/rd/c6d1 Second disk, whole disk + ... + 248 = /dev/rd/c6d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 55 char DSP56001 digital signal processor + 0 = /dev/dsp56k First DSP56001 + + 55 block Mylex DAC960 PCI RAID controller; eighth controller + 0 = /dev/rd/c7d0 First disk, whole disk + 8 = /dev/rd/c7d1 Second disk, whole disk + ... + 248 = /dev/rd/c7d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 56 char Apple Desktop Bus + 0 = /dev/adb ADB bus control + + Additional devices will be added to this number, all + starting with /dev/adb. + + 56 block Fifth IDE hard disk/CD-ROM interface + 0 = /dev/hdi Master: whole disk (or CD-ROM) + 64 = /dev/hdj Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 57 char Hayes ESP serial card + 0 = /dev/ttyP0 First ESP port + 1 = /dev/ttyP1 Second ESP port + ... + + 57 block Sixth IDE hard disk/CD-ROM interface + 0 = /dev/hdk Master: whole disk (or CD-ROM) + 64 = /dev/hdl Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 58 char Hayes ESP serial card - alternate devices + 0 = /dev/cup0 Callout device for ttyP0 + 1 = /dev/cup1 Callout device for ttyP1 + ... + + 58 block Reserved for logical volume manager + + 59 char sf firewall package + 0 = /dev/firewall Communication with sf kernel module + + 59 block Generic PDA filesystem device + 0 = /dev/pda0 First PDA device + 1 = /dev/pda1 Second PDA device + ... + + The pda devices are used to mount filesystems on + remote pda's (basically slow handheld machines with + proprietary OS's and limited memory and storage + running small fs translation drivers) through serial / + IRDA / parallel links. + + NAMING CONFLICT -- PROPOSED REVISED NAME /dev/rpda0 etc + + 60-63 char LOCAL/EXPERIMENTAL USE + + 60-63 block LOCAL/EXPERIMENTAL USE + Allocated for local/experimental use. For devices not + assigned official numbers, these ranges should be + used in order to avoid conflicting with future assignments. + + 64 char ENskip kernel encryption package + 0 = /dev/enskip Communication with ENskip kernel module + + 64 block Scramdisk/DriveCrypt encrypted devices + 0 = /dev/scramdisk/master Master node for ioctls + 1 = /dev/scramdisk/1 First encrypted device + 2 = /dev/scramdisk/2 Second encrypted device + ... + 255 = /dev/scramdisk/255 255th encrypted device + + The filename of the encrypted container and the passwords + are sent via ioctls (using the sdmount tool) to the master + node which then activates them via one of the + /dev/scramdisk/x nodes for loop mounting (all handled + through the sdmount tool). + + Requested by: andy@scramdisklinux.org + + 65 char Sundance "plink" Transputer boards (obsolete, unused) + 0 = /dev/plink0 First plink device + 1 = /dev/plink1 Second plink device + 2 = /dev/plink2 Third plink device + 3 = /dev/plink3 Fourth plink device + 64 = /dev/rplink0 First plink device, raw + 65 = /dev/rplink1 Second plink device, raw + 66 = /dev/rplink2 Third plink device, raw + 67 = /dev/rplink3 Fourth plink device, raw + 128 = /dev/plink0d First plink device, debug + 129 = /dev/plink1d Second plink device, debug + 130 = /dev/plink2d Third plink device, debug + 131 = /dev/plink3d Fourth plink device, debug + 192 = /dev/rplink0d First plink device, raw, debug + 193 = /dev/rplink1d Second plink device, raw, debug + 194 = /dev/rplink2d Third plink device, raw, debug + 195 = /dev/rplink3d Fourth plink device, raw, debug + + This is a commercial driver; contact James Howes + for information. + + 65 block SCSI disk devices (16-31) + 0 = /dev/sdq 17th SCSI disk whole disk + 16 = /dev/sdr 18th SCSI disk whole disk + 32 = /dev/sds 19th SCSI disk whole disk + ... + 240 = /dev/sdaf 32nd SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 66 char YARC PowerPC PCI coprocessor card + 0 = /dev/yppcpci0 First YARC card + 1 = /dev/yppcpci1 Second YARC card + ... + + 66 block SCSI disk devices (32-47) + 0 = /dev/sdag 33th SCSI disk whole disk + 16 = /dev/sdah 34th SCSI disk whole disk + 32 = /dev/sdai 35th SCSI disk whole disk + ... + 240 = /dev/sdav 48nd SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 67 char Coda network file system + 0 = /dev/cfs0 Coda cache manager + + See http://www.coda.cs.cmu.edu for information about Coda. + + 67 block SCSI disk devices (48-63) + 0 = /dev/sdaw 49th SCSI disk whole disk + 16 = /dev/sdax 50th SCSI disk whole disk + 32 = /dev/sday 51st SCSI disk whole disk + ... + 240 = /dev/sdbl 64th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 68 char CAPI 2.0 interface + 0 = /dev/capi20 Control device + 1 = /dev/capi20.00 First CAPI 2.0 application + 2 = /dev/capi20.01 Second CAPI 2.0 application + ... + 20 = /dev/capi20.19 19th CAPI 2.0 application + + ISDN CAPI 2.0 driver for use with CAPI 2.0 + applications; currently supports the AVM B1 card. + + 68 block SCSI disk devices (64-79) + 0 = /dev/sdbm 65th SCSI disk whole disk + 16 = /dev/sdbn 66th SCSI disk whole disk + 32 = /dev/sdbo 67th SCSI disk whole disk + ... + 240 = /dev/sdcb 80th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 69 char MA16 numeric accelerator card + 0 = /dev/ma16 Board memory access + + 69 block SCSI disk devices (80-95) + 0 = /dev/sdcc 81st SCSI disk whole disk + 16 = /dev/sdcd 82nd SCSI disk whole disk + 32 = /dev/sdce 83th SCSI disk whole disk + ... + 240 = /dev/sdcr 96th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 70 char SpellCaster Protocol Services Interface + 0 = /dev/apscfg Configuration interface + 1 = /dev/apsauth Authentication interface + 2 = /dev/apslog Logging interface + 3 = /dev/apsdbg Debugging interface + 64 = /dev/apsisdn ISDN command interface + 65 = /dev/apsasync Async command interface + 128 = /dev/apsmon Monitor interface + + 70 block SCSI disk devices (96-111) + 0 = /dev/sdcs 97th SCSI disk whole disk + 16 = /dev/sdct 98th SCSI disk whole disk + 32 = /dev/sdcu 99th SCSI disk whole disk + ... + 240 = /dev/sddh 112nd SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 71 char Computone IntelliPort II serial card + 0 = /dev/ttyF0 IntelliPort II board 0, port 0 + 1 = /dev/ttyF1 IntelliPort II board 0, port 1 + ... + 63 = /dev/ttyF63 IntelliPort II board 0, port 63 + 64 = /dev/ttyF64 IntelliPort II board 1, port 0 + 65 = /dev/ttyF65 IntelliPort II board 1, port 1 + ... + 127 = /dev/ttyF127 IntelliPort II board 1, port 63 + 128 = /dev/ttyF128 IntelliPort II board 2, port 0 + 129 = /dev/ttyF129 IntelliPort II board 2, port 1 + ... + 191 = /dev/ttyF191 IntelliPort II board 2, port 63 + 192 = /dev/ttyF192 IntelliPort II board 3, port 0 + 193 = /dev/ttyF193 IntelliPort II board 3, port 1 + ... + 255 = /dev/ttyF255 IntelliPort II board 3, port 63 + + 71 block SCSI disk devices (112-127) + 0 = /dev/sddi 113th SCSI disk whole disk + 16 = /dev/sddj 114th SCSI disk whole disk + 32 = /dev/sddk 115th SCSI disk whole disk + ... + 240 = /dev/sddx 128th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 72 char Computone IntelliPort II serial card - alternate devices + 0 = /dev/cuf0 Callout device for ttyF0 + 1 = /dev/cuf1 Callout device for ttyF1 + ... + 63 = /dev/cuf63 Callout device for ttyF63 + 64 = /dev/cuf64 Callout device for ttyF64 + 65 = /dev/cuf65 Callout device for ttyF65 + ... + 127 = /dev/cuf127 Callout device for ttyF127 + 128 = /dev/cuf128 Callout device for ttyF128 + 129 = /dev/cuf129 Callout device for ttyF129 + ... + 191 = /dev/cuf191 Callout device for ttyF191 + 192 = /dev/cuf192 Callout device for ttyF192 + 193 = /dev/cuf193 Callout device for ttyF193 + ... + 255 = /dev/cuf255 Callout device for ttyF255 + + 72 block Compaq Intelligent Drive Array, first controller + 0 = /dev/ida/c0d0 First logical drive whole disk + 16 = /dev/ida/c0d1 Second logical drive whole disk + ... + 240 = /dev/ida/c0d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 73 char Computone IntelliPort II serial card - control devices + 0 = /dev/ip2ipl0 Loadware device for board 0 + 1 = /dev/ip2stat0 Status device for board 0 + 4 = /dev/ip2ipl1 Loadware device for board 1 + 5 = /dev/ip2stat1 Status device for board 1 + 8 = /dev/ip2ipl2 Loadware device for board 2 + 9 = /dev/ip2stat2 Status device for board 2 + 12 = /dev/ip2ipl3 Loadware device for board 3 + 13 = /dev/ip2stat3 Status device for board 3 + + 73 block Compaq Intelligent Drive Array, second controller + 0 = /dev/ida/c1d0 First logical drive whole disk + 16 = /dev/ida/c1d1 Second logical drive whole disk + ... + 240 = /dev/ida/c1d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 74 char SCI bridge + 0 = /dev/SCI/0 SCI device 0 + 1 = /dev/SCI/1 SCI device 1 + ... + + Currently for Dolphin Interconnect Solutions' PCI-SCI + bridge. + + 74 block Compaq Intelligent Drive Array, third controller + 0 = /dev/ida/c2d0 First logical drive whole disk + 16 = /dev/ida/c2d1 Second logical drive whole disk + ... + 240 = /dev/ida/c2d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 75 char Specialix IO8+ serial card + 0 = /dev/ttyW0 First IO8+ port, first card + 1 = /dev/ttyW1 Second IO8+ port, first card + ... + 8 = /dev/ttyW8 First IO8+ port, second card + ... + + 75 block Compaq Intelligent Drive Array, fourth controller + 0 = /dev/ida/c3d0 First logical drive whole disk + 16 = /dev/ida/c3d1 Second logical drive whole disk + ... + 240 = /dev/ida/c3d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 76 char Specialix IO8+ serial card - alternate devices + 0 = /dev/cuw0 Callout device for ttyW0 + 1 = /dev/cuw1 Callout device for ttyW1 + ... + 8 = /dev/cuw8 Callout device for ttyW8 + ... + + 76 block Compaq Intelligent Drive Array, fifth controller + 0 = /dev/ida/c4d0 First logical drive whole disk + 16 = /dev/ida/c4d1 Second logical drive whole disk + ... + 240 = /dev/ida/c4d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + + 77 char ComScire Quantum Noise Generator + 0 = /dev/qng ComScire Quantum Noise Generator + + 77 block Compaq Intelligent Drive Array, sixth controller + 0 = /dev/ida/c5d0 First logical drive whole disk + 16 = /dev/ida/c5d1 Second logical drive whole disk + ... + 240 = /dev/ida/c5d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 78 char PAM Software's multimodem boards + 0 = /dev/ttyM0 First PAM modem + 1 = /dev/ttyM1 Second PAM modem + ... + + 78 block Compaq Intelligent Drive Array, seventh controller + 0 = /dev/ida/c6d0 First logical drive whole disk + 16 = /dev/ida/c6d1 Second logical drive whole disk + ... + 240 = /dev/ida/c6d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 79 char PAM Software's multimodem boards - alternate devices + 0 = /dev/cum0 Callout device for ttyM0 + 1 = /dev/cum1 Callout device for ttyM1 + ... + + 79 block Compaq Intelligent Drive Array, eighth controller + 0 = /dev/ida/c7d0 First logical drive whole disk + 16 = /dev/ida/c7d1 Second logical drive whole disk + ... + 240 = /dev/ida/c715 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 80 char Photometrics AT200 CCD camera + 0 = /dev/at200 Photometrics AT200 CCD camera + + 80 block I2O hard disk + 0 = /dev/i2o/hda First I2O hard disk, whole disk + 16 = /dev/i2o/hdb Second I2O hard disk, whole disk + ... + 240 = /dev/i2o/hdp 16th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 81 char video4linux + 0 = /dev/video0 Video capture/overlay device + ... + 63 = /dev/video63 Video capture/overlay device + 64 = /dev/radio0 Radio device + ... + 127 = /dev/radio63 Radio device + 128 = /dev/swradio0 Software Defined Radio device + ... + 191 = /dev/swradio63 Software Defined Radio device + 224 = /dev/vbi0 Vertical blank interrupt + ... + 255 = /dev/vbi31 Vertical blank interrupt + + Minor numbers are allocated dynamically unless + CONFIG_VIDEO_FIXED_MINOR_RANGES (default n) + configuration option is set. + + 81 block I2O hard disk + 0 = /dev/i2o/hdq 17th I2O hard disk, whole disk + 16 = /dev/i2o/hdr 18th I2O hard disk, whole disk + ... + 240 = /dev/i2o/hdaf 32nd I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 82 char WiNRADiO communications receiver card + 0 = /dev/winradio0 First WiNRADiO card + 1 = /dev/winradio1 Second WiNRADiO card + ... + + The driver and documentation may be obtained from + http://www.winradio.com/ + + 82 block I2O hard disk + 0 = /dev/i2o/hdag 33rd I2O hard disk, whole disk + 16 = /dev/i2o/hdah 34th I2O hard disk, whole disk + ... + 240 = /dev/i2o/hdav 48th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 83 char Matrox mga_vid video driver + 0 = /dev/mga_vid0 1st video card + 1 = /dev/mga_vid1 2nd video card + 2 = /dev/mga_vid2 3rd video card + ... + 15 = /dev/mga_vid15 16th video card + + 83 block I2O hard disk + 0 = /dev/i2o/hdaw 49th I2O hard disk, whole disk + 16 = /dev/i2o/hdax 50th I2O hard disk, whole disk + ... + 240 = /dev/i2o/hdbl 64th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 84 char Ikon 1011[57] Versatec Greensheet Interface + 0 = /dev/ihcp0 First Greensheet port + 1 = /dev/ihcp1 Second Greensheet port + + 84 block I2O hard disk + 0 = /dev/i2o/hdbm 65th I2O hard disk, whole disk + 16 = /dev/i2o/hdbn 66th I2O hard disk, whole disk + ... + 240 = /dev/i2o/hdcb 80th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 85 char Linux/SGI shared memory input queue + 0 = /dev/shmiq Master shared input queue + 1 = /dev/qcntl0 First device pushed + 2 = /dev/qcntl1 Second device pushed + ... + + 85 block I2O hard disk + 0 = /dev/i2o/hdcc 81st I2O hard disk, whole disk + 16 = /dev/i2o/hdcd 82nd I2O hard disk, whole disk + ... + 240 = /dev/i2o/hdcr 96th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 86 char SCSI media changer + 0 = /dev/sch0 First SCSI media changer + 1 = /dev/sch1 Second SCSI media changer + ... + + 86 block I2O hard disk + 0 = /dev/i2o/hdcs 97th I2O hard disk, whole disk + 16 = /dev/i2o/hdct 98th I2O hard disk, whole disk + ... + 240 = /dev/i2o/hddh 112th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 87 char Sony Control-A1 stereo control bus + 0 = /dev/controla0 First device on chain + 1 = /dev/controla1 Second device on chain + ... + + 87 block I2O hard disk + 0 = /dev/i2o/hddi 113rd I2O hard disk, whole disk + 16 = /dev/i2o/hddj 114th I2O hard disk, whole disk + ... + 240 = /dev/i2o/hddx 128th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 88 char COMX synchronous serial card + 0 = /dev/comx0 COMX channel 0 + 1 = /dev/comx1 COMX channel 1 + ... + + 88 block Seventh IDE hard disk/CD-ROM interface + 0 = /dev/hdm Master: whole disk (or CD-ROM) + 64 = /dev/hdn Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 89 char I2C bus interface + 0 = /dev/i2c-0 First I2C adapter + 1 = /dev/i2c-1 Second I2C adapter + ... + + 89 block Eighth IDE hard disk/CD-ROM interface + 0 = /dev/hdo Master: whole disk (or CD-ROM) + 64 = /dev/hdp Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 90 char Memory Technology Device (RAM, ROM, Flash) + 0 = /dev/mtd0 First MTD (rw) + 1 = /dev/mtdr0 First MTD (ro) + ... + 30 = /dev/mtd15 16th MTD (rw) + 31 = /dev/mtdr15 16th MTD (ro) + + 90 block Ninth IDE hard disk/CD-ROM interface + 0 = /dev/hdq Master: whole disk (or CD-ROM) + 64 = /dev/hdr Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 91 char CAN-Bus devices + 0 = /dev/can0 First CAN-Bus controller + 1 = /dev/can1 Second CAN-Bus controller + ... + + 91 block Tenth IDE hard disk/CD-ROM interface + 0 = /dev/hds Master: whole disk (or CD-ROM) + 64 = /dev/hdt Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 92 char Reserved for ith Kommunikationstechnik MIC ISDN card + + 92 block PPDD encrypted disk driver + 0 = /dev/ppdd0 First encrypted disk + 1 = /dev/ppdd1 Second encrypted disk + ... + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 93 char + + 93 block NAND Flash Translation Layer filesystem + 0 = /dev/nftla First NFTL layer + 16 = /dev/nftlb Second NFTL layer + ... + 240 = /dev/nftlp 16th NTFL layer + + 94 char + + 94 block IBM S/390 DASD block storage + 0 = /dev/dasda First DASD device, major + 1 = /dev/dasda1 First DASD device, block 1 + 2 = /dev/dasda2 First DASD device, block 2 + 3 = /dev/dasda3 First DASD device, block 3 + 4 = /dev/dasdb Second DASD device, major + 5 = /dev/dasdb1 Second DASD device, block 1 + 6 = /dev/dasdb2 Second DASD device, block 2 + 7 = /dev/dasdb3 Second DASD device, block 3 + ... + + 95 char IP filter + 0 = /dev/ipl Filter control device/log file + 1 = /dev/ipnat NAT control device/log file + 2 = /dev/ipstate State information log file + 3 = /dev/ipauth Authentication control device/log file + ... + + 96 char Parallel port ATAPI tape devices + 0 = /dev/pt0 First parallel port ATAPI tape + 1 = /dev/pt1 Second parallel port ATAPI tape + ... + 128 = /dev/npt0 First p.p. ATAPI tape, no rewind + 129 = /dev/npt1 Second p.p. ATAPI tape, no rewind + ... + + 96 block Inverse NAND Flash Translation Layer + 0 = /dev/inftla First INFTL layer + 16 = /dev/inftlb Second INFTL layer + ... + 240 = /dev/inftlp 16th INTFL layer + + 97 char Parallel port generic ATAPI interface + 0 = /dev/pg0 First parallel port ATAPI device + 1 = /dev/pg1 Second parallel port ATAPI device + 2 = /dev/pg2 Third parallel port ATAPI device + 3 = /dev/pg3 Fourth parallel port ATAPI device + + These devices support the same API as the generic SCSI + devices. + + 98 char Control and Measurement Device (comedi) + 0 = /dev/comedi0 First comedi device + 1 = /dev/comedi1 Second comedi device + ... + + See http://stm.lbl.gov/comedi. + + 98 block User-mode virtual block device + 0 = /dev/ubda First user-mode block device + 16 = /dev/udbb Second user-mode block device + ... + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + This device is used by the user-mode virtual kernel port. + + 99 char Raw parallel ports + 0 = /dev/parport0 First parallel port + 1 = /dev/parport1 Second parallel port + ... + + 99 block JavaStation flash disk + 0 = /dev/jsfd JavaStation flash disk + + 100 char Telephony for Linux + 0 = /dev/phone0 First telephony device + 1 = /dev/phone1 Second telephony device + ... + + 101 char Motorola DSP 56xxx board + 0 = /dev/mdspstat Status information + 1 = /dev/mdsp1 First DSP board I/O controls + ... + 16 = /dev/mdsp16 16th DSP board I/O controls + + 101 block AMI HyperDisk RAID controller + 0 = /dev/amiraid/ar0 First array whole disk + 16 = /dev/amiraid/ar1 Second array whole disk + ... + 240 = /dev/amiraid/ar15 16th array whole disk + + For each device, partitions are added as: + 0 = /dev/amiraid/ar? Whole disk + 1 = /dev/amiraid/ar?p1 First partition + 2 = /dev/amiraid/ar?p2 Second partition + ... + 15 = /dev/amiraid/ar?p15 15th partition + + 102 char + + 102 block Compressed block device + 0 = /dev/cbd/a First compressed block device, whole device + 16 = /dev/cbd/b Second compressed block device, whole device + ... + 240 = /dev/cbd/p 16th compressed block device, whole device + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 103 char Arla network file system + 0 = /dev/nnpfs0 First NNPFS device + 1 = /dev/nnpfs1 Second NNPFS device + + Arla is a free clone of the Andrew File System, AFS. + The NNPFS device gives user mode filesystem + implementations a kernel presence for caching and easy + mounting. For more information about the project, + write to or see + http://www.stacken.kth.se/project/arla/ + + 103 block Audit device + 0 = /dev/audit Audit device + + 104 char Flash BIOS support + + 104 block Compaq Next Generation Drive Array, first controller + 0 = /dev/cciss/c0d0 First logical drive, whole disk + 16 = /dev/cciss/c0d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c0d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 105 char Comtrol VS-1000 serial controller + 0 = /dev/ttyV0 First VS-1000 port + 1 = /dev/ttyV1 Second VS-1000 port + ... + + 105 block Compaq Next Generation Drive Array, second controller + 0 = /dev/cciss/c1d0 First logical drive, whole disk + 16 = /dev/cciss/c1d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c1d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 106 char Comtrol VS-1000 serial controller - alternate devices + 0 = /dev/cuv0 First VS-1000 port + 1 = /dev/cuv1 Second VS-1000 port + ... + + 106 block Compaq Next Generation Drive Array, third controller + 0 = /dev/cciss/c2d0 First logical drive, whole disk + 16 = /dev/cciss/c2d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c2d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 107 char 3Dfx Voodoo Graphics device + 0 = /dev/3dfx Primary 3Dfx graphics device + + 107 block Compaq Next Generation Drive Array, fourth controller + 0 = /dev/cciss/c3d0 First logical drive, whole disk + 16 = /dev/cciss/c3d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c3d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 108 char Device independent PPP interface + 0 = /dev/ppp Device independent PPP interface + + 108 block Compaq Next Generation Drive Array, fifth controller + 0 = /dev/cciss/c4d0 First logical drive, whole disk + 16 = /dev/cciss/c4d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c4d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 109 char Reserved for logical volume manager + + 109 block Compaq Next Generation Drive Array, sixth controller + 0 = /dev/cciss/c5d0 First logical drive, whole disk + 16 = /dev/cciss/c5d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c5d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 110 char miroMEDIA Surround board + 0 = /dev/srnd0 First miroMEDIA Surround board + 1 = /dev/srnd1 Second miroMEDIA Surround board + ... + + 110 block Compaq Next Generation Drive Array, seventh controller + 0 = /dev/cciss/c6d0 First logical drive, whole disk + 16 = /dev/cciss/c6d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c6d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 111 char + + 111 block Compaq Next Generation Drive Array, eighth controller + 0 = /dev/cciss/c7d0 First logical drive, whole disk + 16 = /dev/cciss/c7d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c7d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 112 char ISI serial card + 0 = /dev/ttyM0 First ISI port + 1 = /dev/ttyM1 Second ISI port + ... + + There is currently a device-naming conflict between + these and PAM multimodems (major 78). + + 112 block IBM iSeries virtual disk + 0 = /dev/iseries/vda First virtual disk, whole disk + 8 = /dev/iseries/vdb Second virtual disk, whole disk + ... + 200 = /dev/iseries/vdz 26th virtual disk, whole disk + 208 = /dev/iseries/vdaa 27th virtual disk, whole disk + ... + 248 = /dev/iseries/vdaf 32nd virtual disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 7. + + 113 char ISI serial card - alternate devices + 0 = /dev/cum0 Callout device for ttyM0 + 1 = /dev/cum1 Callout device for ttyM1 + ... + + 113 block IBM iSeries virtual CD-ROM + 0 = /dev/iseries/vcda First virtual CD-ROM + 1 = /dev/iseries/vcdb Second virtual CD-ROM + ... + + 114 char Picture Elements ISE board + 0 = /dev/ise0 First ISE board + 1 = /dev/ise1 Second ISE board + ... + 128 = /dev/isex0 Control node for first ISE board + 129 = /dev/isex1 Control node for second ISE board + ... + + The ISE board is an embedded computer, optimized for + image processing. The /dev/iseN nodes are the general + I/O access to the board, the /dev/isex0 nodes command + nodes used to control the board. + + 114 block IDE BIOS powered software RAID interfaces such as the + Promise Fastrak + + 0 = /dev/ataraid/d0 + 1 = /dev/ataraid/d0p1 + 2 = /dev/ataraid/d0p2 + ... + 16 = /dev/ataraid/d1 + 17 = /dev/ataraid/d1p1 + 18 = /dev/ataraid/d1p2 + ... + 255 = /dev/ataraid/d15p15 + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 115 char TI link cable devices (115 was formerly the console driver speaker) + 0 = /dev/tipar0 Parallel cable on first parallel port + ... + 7 = /dev/tipar7 Parallel cable on seventh parallel port + + 8 = /dev/tiser0 Serial cable on first serial port + ... + 15 = /dev/tiser7 Serial cable on seventh serial port + + 16 = /dev/tiusb0 First USB cable + ... + 47 = /dev/tiusb31 32nd USB cable + + 115 block NetWare (NWFS) Devices (0-255) + + The NWFS (NetWare) devices are used to present a + collection of NetWare Mirror Groups or NetWare + Partitions as a logical storage segment for + use in mounting NetWare volumes. A maximum of + 256 NetWare volumes can be supported in a single + machine. + + http://cgfa.telepac.pt/ftp2/kernel.org/linux/kernel/people/jmerkey/nwfs/ + + 0 = /dev/nwfs/v0 First NetWare (NWFS) Logical Volume + 1 = /dev/nwfs/v1 Second NetWare (NWFS) Logical Volume + 2 = /dev/nwfs/v2 Third NetWare (NWFS) Logical Volume + ... + 255 = /dev/nwfs/v255 Last NetWare (NWFS) Logical Volume + + 116 char Advanced Linux Sound Driver (ALSA) + + 116 block MicroMemory battery backed RAM adapter (NVRAM) + Supports 16 boards, 15 partitions each. + Requested by neilb at cse.unsw.edu.au. + + 0 = /dev/umem/d0 Whole of first board + 1 = /dev/umem/d0p1 First partition of first board + 2 = /dev/umem/d0p2 Second partition of first board + 15 = /dev/umem/d0p15 15th partition of first board + + 16 = /dev/umem/d1 Whole of second board + 17 = /dev/umem/d1p1 First partition of second board + ... + 255= /dev/umem/d15p15 15th partition of 16th board. + + 117 char COSA/SRP synchronous serial card + 0 = /dev/cosa0c0 1st board, 1st channel + 1 = /dev/cosa0c1 1st board, 2nd channel + ... + 16 = /dev/cosa1c0 2nd board, 1st channel + 17 = /dev/cosa1c1 2nd board, 2nd channel + ... + + 117 block Enterprise Volume Management System (EVMS) + + The EVMS driver uses a layered, plug-in model to provide + unparalleled flexibility and extensibility in managing + storage. This allows for easy expansion or customization + of various levels of volume management. Requested by + Mark Peloquin (peloquin at us.ibm.com). + + Note: EVMS populates and manages all the devnodes in + /dev/evms. + + http://sf.net/projects/evms + + 0 = /dev/evms/block_device EVMS block device + 1 = /dev/evms/legacyname1 First EVMS legacy device + 2 = /dev/evms/legacyname2 Second EVMS legacy device + ... + Both ranges can grow (down or up) until they meet. + ... + 254 = /dev/evms/EVMSname2 Second EVMS native device + 255 = /dev/evms/EVMSname1 First EVMS native device + + Note: legacyname(s) are derived from the normal legacy + device names. For example, /dev/hda5 would become + /dev/evms/hda5. + + 118 char IBM Cryptographic Accelerator + 0 = /dev/ica Virtual interface to all IBM Crypto Accelerators + 1 = /dev/ica0 IBMCA Device 0 + 2 = /dev/ica1 IBMCA Device 1 + ... + + 119 char VMware virtual network control + 0 = /dev/vnet0 1st virtual network + 1 = /dev/vnet1 2nd virtual network + ... + + 120-127 char LOCAL/EXPERIMENTAL USE + + 120-127 block LOCAL/EXPERIMENTAL USE + Allocated for local/experimental use. For devices not + assigned official numbers, these ranges should be + used in order to avoid conflicting with future assignments. + + 128-135 char Unix98 PTY masters + + These devices should not have corresponding device + nodes; instead they should be accessed through the + /dev/ptmx cloning interface. + + 128 block SCSI disk devices (128-143) + 0 = /dev/sddy 129th SCSI disk whole disk + 16 = /dev/sddz 130th SCSI disk whole disk + 32 = /dev/sdea 131th SCSI disk whole disk + ... + 240 = /dev/sden 144th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 129 block SCSI disk devices (144-159) + 0 = /dev/sdeo 145th SCSI disk whole disk + 16 = /dev/sdep 146th SCSI disk whole disk + 32 = /dev/sdeq 147th SCSI disk whole disk + ... + 240 = /dev/sdfd 160th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 130 char (Misc devices) + + 130 block SCSI disk devices (160-175) + 0 = /dev/sdfe 161st SCSI disk whole disk + 16 = /dev/sdff 162nd SCSI disk whole disk + 32 = /dev/sdfg 163rd SCSI disk whole disk + ... + 240 = /dev/sdft 176th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 131 block SCSI disk devices (176-191) + 0 = /dev/sdfu 177th SCSI disk whole disk + 16 = /dev/sdfv 178th SCSI disk whole disk + 32 = /dev/sdfw 179th SCSI disk whole disk + ... + 240 = /dev/sdgj 192nd SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 132 block SCSI disk devices (192-207) + 0 = /dev/sdgk 193rd SCSI disk whole disk + 16 = /dev/sdgl 194th SCSI disk whole disk + 32 = /dev/sdgm 195th SCSI disk whole disk + ... + 240 = /dev/sdgz 208th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 133 block SCSI disk devices (208-223) + 0 = /dev/sdha 209th SCSI disk whole disk + 16 = /dev/sdhb 210th SCSI disk whole disk + 32 = /dev/sdhc 211th SCSI disk whole disk + ... + 240 = /dev/sdhp 224th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 134 block SCSI disk devices (224-239) + 0 = /dev/sdhq 225th SCSI disk whole disk + 16 = /dev/sdhr 226th SCSI disk whole disk + 32 = /dev/sdhs 227th SCSI disk whole disk + ... + 240 = /dev/sdif 240th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 135 block SCSI disk devices (240-255) + 0 = /dev/sdig 241st SCSI disk whole disk + 16 = /dev/sdih 242nd SCSI disk whole disk + 32 = /dev/sdih 243rd SCSI disk whole disk + ... + 240 = /dev/sdiv 256th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 136-143 char Unix98 PTY slaves + 0 = /dev/pts/0 First Unix98 pseudo-TTY + 1 = /dev/pts/1 Second Unix98 pseudo-TTY + ... + + These device nodes are automatically generated with + the proper permissions and modes by mounting the + devpts filesystem onto /dev/pts with the appropriate + mount options (distribution dependent, however, on + *most* distributions the appropriate options are + "mode=0620,gid=".) + + 136 block Mylex DAC960 PCI RAID controller; ninth controller + 0 = /dev/rd/c8d0 First disk, whole disk + 8 = /dev/rd/c8d1 Second disk, whole disk + ... + 248 = /dev/rd/c8d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 137 block Mylex DAC960 PCI RAID controller; tenth controller + 0 = /dev/rd/c9d0 First disk, whole disk + 8 = /dev/rd/c9d1 Second disk, whole disk + ... + 248 = /dev/rd/c9d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 138 block Mylex DAC960 PCI RAID controller; eleventh controller + 0 = /dev/rd/c10d0 First disk, whole disk + 8 = /dev/rd/c10d1 Second disk, whole disk + ... + 248 = /dev/rd/c10d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 139 block Mylex DAC960 PCI RAID controller; twelfth controller + 0 = /dev/rd/c11d0 First disk, whole disk + 8 = /dev/rd/c11d1 Second disk, whole disk + ... + 248 = /dev/rd/c11d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 140 block Mylex DAC960 PCI RAID controller; thirteenth controller + 0 = /dev/rd/c12d0 First disk, whole disk + 8 = /dev/rd/c12d1 Second disk, whole disk + ... + 248 = /dev/rd/c12d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 141 block Mylex DAC960 PCI RAID controller; fourteenth controller + 0 = /dev/rd/c13d0 First disk, whole disk + 8 = /dev/rd/c13d1 Second disk, whole disk + ... + 248 = /dev/rd/c13d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 142 block Mylex DAC960 PCI RAID controller; fifteenth controller + 0 = /dev/rd/c14d0 First disk, whole disk + 8 = /dev/rd/c14d1 Second disk, whole disk + ... + 248 = /dev/rd/c14d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 143 block Mylex DAC960 PCI RAID controller; sixteenth controller + 0 = /dev/rd/c15d0 First disk, whole disk + 8 = /dev/rd/c15d1 Second disk, whole disk + ... + 248 = /dev/rd/c15d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 144 char Encapsulated PPP + 0 = /dev/pppox0 First PPP over Ethernet + ... + 63 = /dev/pppox63 64th PPP over Ethernet + + This is primarily used for ADSL. + + The SST 5136-DN DeviceNet interface driver has been + relocated to major 183 due to an unfortunate conflict. + + 144 block Expansion Area #1 for more non-device (e.g. NFS) mounts + 0 = mounted device 256 + 255 = mounted device 511 + + 145 char SAM9407-based soundcard + 0 = /dev/sam0_mixer + 1 = /dev/sam0_sequencer + 2 = /dev/sam0_midi00 + 3 = /dev/sam0_dsp + 4 = /dev/sam0_audio + 6 = /dev/sam0_sndstat + 18 = /dev/sam0_midi01 + 34 = /dev/sam0_midi02 + 50 = /dev/sam0_midi03 + 64 = /dev/sam1_mixer + ... + 128 = /dev/sam2_mixer + ... + 192 = /dev/sam3_mixer + ... + + Device functions match OSS, but offer a number of + addons, which are sam9407 specific. OSS can be + operated simultaneously, taking care of the codec. + + 145 block Expansion Area #2 for more non-device (e.g. NFS) mounts + 0 = mounted device 512 + 255 = mounted device 767 + + 146 char SYSTRAM SCRAMNet mirrored-memory network + 0 = /dev/scramnet0 First SCRAMNet device + 1 = /dev/scramnet1 Second SCRAMNet device + ... + + 146 block Expansion Area #3 for more non-device (e.g. NFS) mounts + 0 = mounted device 768 + 255 = mounted device 1023 + + 147 char Aureal Semiconductor Vortex Audio device + 0 = /dev/aureal0 First Aureal Vortex + 1 = /dev/aureal1 Second Aureal Vortex + ... + + 147 block Distributed Replicated Block Device (DRBD) + 0 = /dev/drbd0 First DRBD device + 1 = /dev/drbd1 Second DRBD device + ... + + 148 char Technology Concepts serial card + 0 = /dev/ttyT0 First TCL port + 1 = /dev/ttyT1 Second TCL port + ... + + 149 char Technology Concepts serial card - alternate devices + 0 = /dev/cut0 Callout device for ttyT0 + 1 = /dev/cut0 Callout device for ttyT1 + ... + + 150 char Real-Time Linux FIFOs + 0 = /dev/rtf0 First RTLinux FIFO + 1 = /dev/rtf1 Second RTLinux FIFO + ... + + 151 char DPT I2O SmartRaid V controller + 0 = /dev/dpti0 First DPT I2O adapter + 1 = /dev/dpti1 Second DPT I2O adapter + ... + + 152 char EtherDrive Control Device + 0 = /dev/etherd/ctl Connect/Disconnect an EtherDrive + 1 = /dev/etherd/err Monitor errors + 2 = /dev/etherd/raw Raw AoE packet monitor + + 152 block EtherDrive Block Devices + 0 = /dev/etherd/0 EtherDrive 0 + ... + 255 = /dev/etherd/255 EtherDrive 255 + + 153 char SPI Bus Interface (sometimes referred to as MicroWire) + 0 = /dev/spi0 First SPI device on the bus + 1 = /dev/spi1 Second SPI device on the bus + ... + 15 = /dev/spi15 Sixteenth SPI device on the bus + + 153 block Enhanced Metadisk RAID (EMD) storage units + 0 = /dev/emd/0 First unit + 1 = /dev/emd/0p1 Partition 1 on First unit + 2 = /dev/emd/0p2 Partition 2 on First unit + ... + 15 = /dev/emd/0p15 Partition 15 on First unit + + 16 = /dev/emd/1 Second unit + 32 = /dev/emd/2 Third unit + ... + 240 = /dev/emd/15 Sixteenth unit + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 154 char Specialix RIO serial card + 0 = /dev/ttySR0 First RIO port + ... + 255 = /dev/ttySR255 256th RIO port + + 155 char Specialix RIO serial card - alternate devices + 0 = /dev/cusr0 Callout device for ttySR0 + ... + 255 = /dev/cusr255 Callout device for ttySR255 + + 156 char Specialix RIO serial card + 0 = /dev/ttySR256 257th RIO port + ... + 255 = /dev/ttySR511 512th RIO port + + 157 char Specialix RIO serial card - alternate devices + 0 = /dev/cusr256 Callout device for ttySR256 + ... + 255 = /dev/cusr511 Callout device for ttySR511 + + 158 char Dialogic GammaLink fax driver + 0 = /dev/gfax0 GammaLink channel 0 + 1 = /dev/gfax1 GammaLink channel 1 + ... + + 159 char RESERVED + + 159 block RESERVED + + 160 char General Purpose Instrument Bus (GPIB) + 0 = /dev/gpib0 First GPIB bus + 1 = /dev/gpib1 Second GPIB bus + ... + + 160 block Carmel 8-port SATA Disks on First Controller + 0 = /dev/carmel/0 SATA disk 0 whole disk + 1 = /dev/carmel/0p1 SATA disk 0 partition 1 + ... + 31 = /dev/carmel/0p31 SATA disk 0 partition 31 + + 32 = /dev/carmel/1 SATA disk 1 whole disk + 64 = /dev/carmel/2 SATA disk 2 whole disk + ... + 224 = /dev/carmel/7 SATA disk 7 whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 31. + + 161 char IrCOMM devices (IrDA serial/parallel emulation) + 0 = /dev/ircomm0 First IrCOMM device + 1 = /dev/ircomm1 Second IrCOMM device + ... + 16 = /dev/irlpt0 First IrLPT device + 17 = /dev/irlpt1 Second IrLPT device + ... + + 161 block Carmel 8-port SATA Disks on Second Controller + 0 = /dev/carmel/8 SATA disk 8 whole disk + 1 = /dev/carmel/8p1 SATA disk 8 partition 1 + ... + 31 = /dev/carmel/8p31 SATA disk 8 partition 31 + + 32 = /dev/carmel/9 SATA disk 9 whole disk + 64 = /dev/carmel/10 SATA disk 10 whole disk + ... + 224 = /dev/carmel/15 SATA disk 15 whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 31. + + 162 char Raw block device interface + 0 = /dev/rawctl Raw I/O control device + 1 = /dev/raw/raw1 First raw I/O device + 2 = /dev/raw/raw2 Second raw I/O device + ... + max minor number of raw device is set by kernel config + MAX_RAW_DEVS or raw module parameter 'max_raw_devs' + + 163 char + + 164 char Chase Research AT/PCI-Fast serial card + 0 = /dev/ttyCH0 AT/PCI-Fast board 0, port 0 + ... + 15 = /dev/ttyCH15 AT/PCI-Fast board 0, port 15 + 16 = /dev/ttyCH16 AT/PCI-Fast board 1, port 0 + ... + 31 = /dev/ttyCH31 AT/PCI-Fast board 1, port 15 + 32 = /dev/ttyCH32 AT/PCI-Fast board 2, port 0 + ... + 47 = /dev/ttyCH47 AT/PCI-Fast board 2, port 15 + 48 = /dev/ttyCH48 AT/PCI-Fast board 3, port 0 + ... + 63 = /dev/ttyCH63 AT/PCI-Fast board 3, port 15 + + 165 char Chase Research AT/PCI-Fast serial card - alternate devices + 0 = /dev/cuch0 Callout device for ttyCH0 + ... + 63 = /dev/cuch63 Callout device for ttyCH63 + + 166 char ACM USB modems + 0 = /dev/ttyACM0 First ACM modem + 1 = /dev/ttyACM1 Second ACM modem + ... + + 167 char ACM USB modems - alternate devices + 0 = /dev/cuacm0 Callout device for ttyACM0 + 1 = /dev/cuacm1 Callout device for ttyACM1 + ... + + 168 char Eracom CSA7000 PCI encryption adaptor + 0 = /dev/ecsa0 First CSA7000 + 1 = /dev/ecsa1 Second CSA7000 + ... + + 169 char Eracom CSA8000 PCI encryption adaptor + 0 = /dev/ecsa8-0 First CSA8000 + 1 = /dev/ecsa8-1 Second CSA8000 + ... + + 170 char AMI MegaRAC remote access controller + 0 = /dev/megarac0 First MegaRAC card + 1 = /dev/megarac1 Second MegaRAC card + ... + + 171 char Reserved for IEEE 1394 (Firewire) + + 172 char Moxa Intellio serial card + 0 = /dev/ttyMX0 First Moxa port + 1 = /dev/ttyMX1 Second Moxa port + ... + 127 = /dev/ttyMX127 128th Moxa port + 128 = /dev/moxactl Moxa control port + + 173 char Moxa Intellio serial card - alternate devices + 0 = /dev/cumx0 Callout device for ttyMX0 + 1 = /dev/cumx1 Callout device for ttyMX1 + ... + 127 = /dev/cumx127 Callout device for ttyMX127 + + 174 char SmartIO serial card + 0 = /dev/ttySI0 First SmartIO port + 1 = /dev/ttySI1 Second SmartIO port + ... + + 175 char SmartIO serial card - alternate devices + 0 = /dev/cusi0 Callout device for ttySI0 + 1 = /dev/cusi1 Callout device for ttySI1 + ... + + 176 char nCipher nFast PCI crypto accelerator + 0 = /dev/nfastpci0 First nFast PCI device + 1 = /dev/nfastpci1 First nFast PCI device + ... + + 177 char TI PCILynx memory spaces + 0 = /dev/pcilynx/aux0 AUX space of first PCILynx card + ... + 15 = /dev/pcilynx/aux15 AUX space of 16th PCILynx card + 16 = /dev/pcilynx/rom0 ROM space of first PCILynx card + ... + 31 = /dev/pcilynx/rom15 ROM space of 16th PCILynx card + 32 = /dev/pcilynx/ram0 RAM space of first PCILynx card + ... + 47 = /dev/pcilynx/ram15 RAM space of 16th PCILynx card + + 178 char Giganet cLAN1xxx virtual interface adapter + 0 = /dev/clanvi0 First cLAN adapter + 1 = /dev/clanvi1 Second cLAN adapter + ... + + 179 block MMC block devices + 0 = /dev/mmcblk0 First SD/MMC card + 1 = /dev/mmcblk0p1 First partition on first MMC card + 8 = /dev/mmcblk1 Second SD/MMC card + ... + + The start of next SD/MMC card can be configured with + CONFIG_MMC_BLOCK_MINORS, or overridden at boot/modprobe + time using the mmcblk.perdev_minors option. That would + bump the offset between each card to be the configured + value instead of the default 8. + + 179 char CCube DVXChip-based PCI products + 0 = /dev/dvxirq0 First DVX device + 1 = /dev/dvxirq1 Second DVX device + ... + + 180 char USB devices + 0 = /dev/usb/lp0 First USB printer + ... + 15 = /dev/usb/lp15 16th USB printer + 48 = /dev/usb/scanner0 First USB scanner + ... + 63 = /dev/usb/scanner15 16th USB scanner + 64 = /dev/usb/rio500 Diamond Rio 500 + 65 = /dev/usb/usblcd USBLCD Interface (info@usblcd.de) + 66 = /dev/usb/cpad0 Synaptics cPad (mouse/LCD) + 96 = /dev/usb/hiddev0 1st USB HID device + ... + 111 = /dev/usb/hiddev15 16th USB HID device + 112 = /dev/usb/auer0 1st auerswald ISDN device + ... + 127 = /dev/usb/auer15 16th auerswald ISDN device + 128 = /dev/usb/brlvgr0 First Braille Voyager device + ... + 131 = /dev/usb/brlvgr3 Fourth Braille Voyager device + 132 = /dev/usb/idmouse ID Mouse (fingerprint scanner) device + 133 = /dev/usb/sisusbvga1 First SiSUSB VGA device + ... + 140 = /dev/usb/sisusbvga8 Eighth SISUSB VGA device + 144 = /dev/usb/lcd USB LCD device + 160 = /dev/usb/legousbtower0 1st USB Legotower device + ... + 175 = /dev/usb/legousbtower15 16th USB Legotower device + 176 = /dev/usb/usbtmc1 First USB TMC device + ... + 191 = /dev/usb/usbtmc16 16th USB TMC device + 192 = /dev/usb/yurex1 First USB Yurex device + ... + 209 = /dev/usb/yurex16 16th USB Yurex device + + 180 block USB block devices + 0 = /dev/uba First USB block device + 8 = /dev/ubb Second USB block device + 16 = /dev/ubc Third USB block device + ... + + 181 char Conrad Electronic parallel port radio clocks + 0 = /dev/pcfclock0 First Conrad radio clock + 1 = /dev/pcfclock1 Second Conrad radio clock + ... + + 182 char Picture Elements THR2 binarizer + 0 = /dev/pethr0 First THR2 board + 1 = /dev/pethr1 Second THR2 board + ... + + 183 char SST 5136-DN DeviceNet interface + 0 = /dev/ss5136dn0 First DeviceNet interface + 1 = /dev/ss5136dn1 Second DeviceNet interface + ... + + This device used to be assigned to major number 144. + It had to be moved due to an unfortunate conflict. + + 184 char Picture Elements' video simulator/sender + 0 = /dev/pevss0 First sender board + 1 = /dev/pevss1 Second sender board + ... + + 185 char InterMezzo high availability file system + 0 = /dev/intermezzo0 First cache manager + 1 = /dev/intermezzo1 Second cache manager + ... + + See http://web.archive.org/web/20080115195241/ + http://inter-mezzo.org/index.html + + 186 char Object-based storage control device + 0 = /dev/obd0 First obd control device + 1 = /dev/obd1 Second obd control device + ... + + See ftp://ftp.lustre.org/pub/obd for code and information. + + 187 char DESkey hardware encryption device + 0 = /dev/deskey0 First DES key + 1 = /dev/deskey1 Second DES key + ... + + 188 char USB serial converters + 0 = /dev/ttyUSB0 First USB serial converter + 1 = /dev/ttyUSB1 Second USB serial converter + ... + + 189 char USB serial converters - alternate devices + 0 = /dev/cuusb0 Callout device for ttyUSB0 + 1 = /dev/cuusb1 Callout device for ttyUSB1 + ... + + 190 char Kansas City tracker/tuner card + 0 = /dev/kctt0 First KCT/T card + 1 = /dev/kctt1 Second KCT/T card + ... + + 191 char Reserved for PCMCIA + + 192 char Kernel profiling interface + 0 = /dev/profile Profiling control device + 1 = /dev/profile0 Profiling device for CPU 0 + 2 = /dev/profile1 Profiling device for CPU 1 + ... + + 193 char Kernel event-tracing interface + 0 = /dev/trace Tracing control device + 1 = /dev/trace0 Tracing device for CPU 0 + 2 = /dev/trace1 Tracing device for CPU 1 + ... + + 194 char linVideoStreams (LINVS) + 0 = /dev/mvideo/status0 Video compression status + 1 = /dev/mvideo/stream0 Video stream + 2 = /dev/mvideo/frame0 Single compressed frame + 3 = /dev/mvideo/rawframe0 Raw uncompressed frame + 4 = /dev/mvideo/codec0 Direct codec access + 5 = /dev/mvideo/video4linux0 Video4Linux compatibility + + 16 = /dev/mvideo/status1 Second device + ... + 32 = /dev/mvideo/status2 Third device + ... + ... + 240 = /dev/mvideo/status15 16th device + ... + + 195 char Nvidia graphics devices + 0 = /dev/nvidia0 First Nvidia card + 1 = /dev/nvidia1 Second Nvidia card + ... + 255 = /dev/nvidiactl Nvidia card control device + + 196 char Tormenta T1 card + 0 = /dev/tor/0 Master control channel for all cards + 1 = /dev/tor/1 First DS0 + 2 = /dev/tor/2 Second DS0 + ... + 48 = /dev/tor/48 48th DS0 + 49 = /dev/tor/49 First pseudo-channel + 50 = /dev/tor/50 Second pseudo-channel + ... + + 197 char OpenTNF tracing facility + 0 = /dev/tnf/t0 Trace 0 data extraction + 1 = /dev/tnf/t1 Trace 1 data extraction + ... + 128 = /dev/tnf/status Tracing facility status + 130 = /dev/tnf/trace Tracing device + + 198 char Total Impact TPMP2 quad coprocessor PCI card + 0 = /dev/tpmp2/0 First card + 1 = /dev/tpmp2/1 Second card + ... + + 199 char Veritas volume manager (VxVM) volumes + 0 = /dev/vx/rdsk/*/* First volume + 1 = /dev/vx/rdsk/*/* Second volume + ... + + 199 block Veritas volume manager (VxVM) volumes + 0 = /dev/vx/dsk/*/* First volume + 1 = /dev/vx/dsk/*/* Second volume + ... + + The namespace in these directories is maintained by + the user space VxVM software. + + 200 char Veritas VxVM configuration interface + 0 = /dev/vx/config Configuration access node + 1 = /dev/vx/trace Volume i/o trace access node + 2 = /dev/vx/iod Volume i/o daemon access node + 3 = /dev/vx/info Volume information access node + 4 = /dev/vx/task Volume tasks access node + 5 = /dev/vx/taskmon Volume tasks monitor daemon + + 201 char Veritas VxVM dynamic multipathing driver + 0 = /dev/vx/rdmp/* First multipath device + 1 = /dev/vx/rdmp/* Second multipath device + ... + 201 block Veritas VxVM dynamic multipathing driver + 0 = /dev/vx/dmp/* First multipath device + 1 = /dev/vx/dmp/* Second multipath device + ... + + The namespace in these directories is maintained by + the user space VxVM software. + + 202 char CPU model-specific registers + 0 = /dev/cpu/0/msr MSRs on CPU 0 + 1 = /dev/cpu/1/msr MSRs on CPU 1 + ... + + 202 block Xen Virtual Block Device + 0 = /dev/xvda First Xen VBD whole disk + 16 = /dev/xvdb Second Xen VBD whole disk + 32 = /dev/xvdc Third Xen VBD whole disk + ... + 240 = /dev/xvdp Sixteenth Xen VBD whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 203 char CPU CPUID information + 0 = /dev/cpu/0/cpuid CPUID on CPU 0 + 1 = /dev/cpu/1/cpuid CPUID on CPU 1 + ... + + 204 char Low-density serial ports + 0 = /dev/ttyLU0 LinkUp Systems L72xx UART - port 0 + 1 = /dev/ttyLU1 LinkUp Systems L72xx UART - port 1 + 2 = /dev/ttyLU2 LinkUp Systems L72xx UART - port 2 + 3 = /dev/ttyLU3 LinkUp Systems L72xx UART - port 3 + 4 = /dev/ttyFB0 Intel Footbridge (ARM) + 5 = /dev/ttySA0 StrongARM builtin serial port 0 + 6 = /dev/ttySA1 StrongARM builtin serial port 1 + 7 = /dev/ttySA2 StrongARM builtin serial port 2 + 8 = /dev/ttySC0 SCI serial port (SuperH) - port 0 + 9 = /dev/ttySC1 SCI serial port (SuperH) - port 1 + 10 = /dev/ttySC2 SCI serial port (SuperH) - port 2 + 11 = /dev/ttySC3 SCI serial port (SuperH) - port 3 + 12 = /dev/ttyFW0 Firmware console - port 0 + 13 = /dev/ttyFW1 Firmware console - port 1 + 14 = /dev/ttyFW2 Firmware console - port 2 + 15 = /dev/ttyFW3 Firmware console - port 3 + 16 = /dev/ttyAM0 ARM "AMBA" serial port 0 + ... + 31 = /dev/ttyAM15 ARM "AMBA" serial port 15 + 32 = /dev/ttyDB0 DataBooster serial port 0 + ... + 39 = /dev/ttyDB7 DataBooster serial port 7 + 40 = /dev/ttySG0 SGI Altix console port + 41 = /dev/ttySMX0 Motorola i.MX - port 0 + 42 = /dev/ttySMX1 Motorola i.MX - port 1 + 43 = /dev/ttySMX2 Motorola i.MX - port 2 + 44 = /dev/ttyMM0 Marvell MPSC - port 0 + 45 = /dev/ttyMM1 Marvell MPSC - port 1 + 46 = /dev/ttyCPM0 PPC CPM (SCC or SMC) - port 0 + ... + 47 = /dev/ttyCPM5 PPC CPM (SCC or SMC) - port 5 + 50 = /dev/ttyIOC0 Altix serial card + ... + 81 = /dev/ttyIOC31 Altix serial card + 82 = /dev/ttyVR0 NEC VR4100 series SIU + 83 = /dev/ttyVR1 NEC VR4100 series DSIU + 84 = /dev/ttyIOC84 Altix ioc4 serial card + ... + 115 = /dev/ttyIOC115 Altix ioc4 serial card + 116 = /dev/ttySIOC0 Altix ioc3 serial card + ... + 147 = /dev/ttySIOC31 Altix ioc3 serial card + 148 = /dev/ttyPSC0 PPC PSC - port 0 + ... + 153 = /dev/ttyPSC5 PPC PSC - port 5 + 154 = /dev/ttyAT0 ATMEL serial port 0 + ... + 169 = /dev/ttyAT15 ATMEL serial port 15 + 170 = /dev/ttyNX0 Hilscher netX serial port 0 + ... + 185 = /dev/ttyNX15 Hilscher netX serial port 15 + 186 = /dev/ttyJ0 JTAG1 DCC protocol based serial port emulation + 187 = /dev/ttyUL0 Xilinx uartlite - port 0 + ... + 190 = /dev/ttyUL3 Xilinx uartlite - port 3 + 191 = /dev/xvc0 Xen virtual console - port 0 + 192 = /dev/ttyPZ0 pmac_zilog - port 0 + ... + 195 = /dev/ttyPZ3 pmac_zilog - port 3 + 196 = /dev/ttyTX0 TX39/49 serial port 0 + ... + 204 = /dev/ttyTX7 TX39/49 serial port 7 + 205 = /dev/ttySC0 SC26xx serial port 0 + 206 = /dev/ttySC1 SC26xx serial port 1 + 207 = /dev/ttySC2 SC26xx serial port 2 + 208 = /dev/ttySC3 SC26xx serial port 3 + 209 = /dev/ttyMAX0 MAX3100 serial port 0 + 210 = /dev/ttyMAX1 MAX3100 serial port 1 + 211 = /dev/ttyMAX2 MAX3100 serial port 2 + 212 = /dev/ttyMAX3 MAX3100 serial port 3 + + 205 char Low-density serial ports (alternate device) + 0 = /dev/culu0 Callout device for ttyLU0 + 1 = /dev/culu1 Callout device for ttyLU1 + 2 = /dev/culu2 Callout device for ttyLU2 + 3 = /dev/culu3 Callout device for ttyLU3 + 4 = /dev/cufb0 Callout device for ttyFB0 + 5 = /dev/cusa0 Callout device for ttySA0 + 6 = /dev/cusa1 Callout device for ttySA1 + 7 = /dev/cusa2 Callout device for ttySA2 + 8 = /dev/cusc0 Callout device for ttySC0 + 9 = /dev/cusc1 Callout device for ttySC1 + 10 = /dev/cusc2 Callout device for ttySC2 + 11 = /dev/cusc3 Callout device for ttySC3 + 12 = /dev/cufw0 Callout device for ttyFW0 + 13 = /dev/cufw1 Callout device for ttyFW1 + 14 = /dev/cufw2 Callout device for ttyFW2 + 15 = /dev/cufw3 Callout device for ttyFW3 + 16 = /dev/cuam0 Callout device for ttyAM0 + ... + 31 = /dev/cuam15 Callout device for ttyAM15 + 32 = /dev/cudb0 Callout device for ttyDB0 + ... + 39 = /dev/cudb7 Callout device for ttyDB7 + 40 = /dev/cusg0 Callout device for ttySG0 + 41 = /dev/ttycusmx0 Callout device for ttySMX0 + 42 = /dev/ttycusmx1 Callout device for ttySMX1 + 43 = /dev/ttycusmx2 Callout device for ttySMX2 + 46 = /dev/cucpm0 Callout device for ttyCPM0 + ... + 49 = /dev/cucpm5 Callout device for ttyCPM5 + 50 = /dev/cuioc40 Callout device for ttyIOC40 + ... + 81 = /dev/cuioc431 Callout device for ttyIOC431 + 82 = /dev/cuvr0 Callout device for ttyVR0 + 83 = /dev/cuvr1 Callout device for ttyVR1 + + 206 char OnStream SC-x0 tape devices + 0 = /dev/osst0 First OnStream SCSI tape, mode 0 + 1 = /dev/osst1 Second OnStream SCSI tape, mode 0 + ... + 32 = /dev/osst0l First OnStream SCSI tape, mode 1 + 33 = /dev/osst1l Second OnStream SCSI tape, mode 1 + ... + 64 = /dev/osst0m First OnStream SCSI tape, mode 2 + 65 = /dev/osst1m Second OnStream SCSI tape, mode 2 + ... + 96 = /dev/osst0a First OnStream SCSI tape, mode 3 + 97 = /dev/osst1a Second OnStream SCSI tape, mode 3 + ... + 128 = /dev/nosst0 No rewind version of /dev/osst0 + 129 = /dev/nosst1 No rewind version of /dev/osst1 + ... + 160 = /dev/nosst0l No rewind version of /dev/osst0l + 161 = /dev/nosst1l No rewind version of /dev/osst1l + ... + 192 = /dev/nosst0m No rewind version of /dev/osst0m + 193 = /dev/nosst1m No rewind version of /dev/osst1m + ... + 224 = /dev/nosst0a No rewind version of /dev/osst0a + 225 = /dev/nosst1a No rewind version of /dev/osst1a + ... + + The OnStream SC-x0 SCSI tapes do not support the + standard SCSI SASD command set and therefore need + their own driver "osst". Note that the IDE, USB (and + maybe ParPort) versions may be driven via ide-scsi or + usb-storage SCSI emulation and this osst device and + driver as well. The ADR-x0 drives are QIC-157 + compliant and don't need osst. + + 207 char Compaq ProLiant health feature indicate + 0 = /dev/cpqhealth/cpqw Redirector interface + 1 = /dev/cpqhealth/crom EISA CROM + 2 = /dev/cpqhealth/cdt Data Table + 3 = /dev/cpqhealth/cevt Event Log + 4 = /dev/cpqhealth/casr Automatic Server Recovery + 5 = /dev/cpqhealth/cecc ECC Memory + 6 = /dev/cpqhealth/cmca Machine Check Architecture + 7 = /dev/cpqhealth/ccsm Deprecated CDT + 8 = /dev/cpqhealth/cnmi NMI Handling + 9 = /dev/cpqhealth/css Sideshow Management + 10 = /dev/cpqhealth/cram CMOS interface + 11 = /dev/cpqhealth/cpci PCI IRQ interface + + 208 char User space serial ports + 0 = /dev/ttyU0 First user space serial port + 1 = /dev/ttyU1 Second user space serial port + ... + + 209 char User space serial ports (alternate devices) + 0 = /dev/cuu0 Callout device for ttyU0 + 1 = /dev/cuu1 Callout device for ttyU1 + ... + + 210 char SBE, Inc. sync/async serial card + 0 = /dev/sbei/wxcfg0 Configuration device for board 0 + 1 = /dev/sbei/dld0 Download device for board 0 + 2 = /dev/sbei/wan00 WAN device, port 0, board 0 + 3 = /dev/sbei/wan01 WAN device, port 1, board 0 + 4 = /dev/sbei/wan02 WAN device, port 2, board 0 + 5 = /dev/sbei/wan03 WAN device, port 3, board 0 + 6 = /dev/sbei/wanc00 WAN clone device, port 0, board 0 + 7 = /dev/sbei/wanc01 WAN clone device, port 1, board 0 + 8 = /dev/sbei/wanc02 WAN clone device, port 2, board 0 + 9 = /dev/sbei/wanc03 WAN clone device, port 3, board 0 + 10 = /dev/sbei/wxcfg1 Configuration device for board 1 + 11 = /dev/sbei/dld1 Download device for board 1 + 12 = /dev/sbei/wan10 WAN device, port 0, board 1 + 13 = /dev/sbei/wan11 WAN device, port 1, board 1 + 14 = /dev/sbei/wan12 WAN device, port 2, board 1 + 15 = /dev/sbei/wan13 WAN device, port 3, board 1 + 16 = /dev/sbei/wanc10 WAN clone device, port 0, board 1 + 17 = /dev/sbei/wanc11 WAN clone device, port 1, board 1 + 18 = /dev/sbei/wanc12 WAN clone device, port 2, board 1 + 19 = /dev/sbei/wanc13 WAN clone device, port 3, board 1 + ... + + Yes, each board is really spaced 10 (decimal) apart. + + 211 char Addinum CPCI1500 digital I/O card + 0 = /dev/addinum/cpci1500/0 First CPCI1500 card + 1 = /dev/addinum/cpci1500/1 Second CPCI1500 card + ... + + 212 char LinuxTV.org DVB driver subsystem + 0 = /dev/dvb/adapter0/video0 first video decoder of first card + 1 = /dev/dvb/adapter0/audio0 first audio decoder of first card + 2 = /dev/dvb/adapter0/sec0 (obsolete/unused) + 3 = /dev/dvb/adapter0/frontend0 first frontend device of first card + 4 = /dev/dvb/adapter0/demux0 first demux device of first card + 5 = /dev/dvb/adapter0/dvr0 first digital video recoder device of first card + 6 = /dev/dvb/adapter0/ca0 first common access port of first card + 7 = /dev/dvb/adapter0/net0 first network device of first card + 8 = /dev/dvb/adapter0/osd0 first on-screen-display device of first card + 9 = /dev/dvb/adapter0/video1 second video decoder of first card + ... + 64 = /dev/dvb/adapter1/video0 first video decoder of second card + ... + 128 = /dev/dvb/adapter2/video0 first video decoder of third card + ... + 196 = /dev/dvb/adapter3/video0 first video decoder of fourth card + + 216 char Bluetooth RFCOMM TTY devices + 0 = /dev/rfcomm0 First Bluetooth RFCOMM TTY device + 1 = /dev/rfcomm1 Second Bluetooth RFCOMM TTY device + ... + + 217 char Bluetooth RFCOMM TTY devices (alternate devices) + 0 = /dev/curf0 Callout device for rfcomm0 + 1 = /dev/curf1 Callout device for rfcomm1 + ... + + 218 char The Logical Company bus Unibus/Qbus adapters + 0 = /dev/logicalco/bci/0 First bus adapter + 1 = /dev/logicalco/bci/1 First bus adapter + ... + + 219 char The Logical Company DCI-1300 digital I/O card + 0 = /dev/logicalco/dci1300/0 First DCI-1300 card + 1 = /dev/logicalco/dci1300/1 Second DCI-1300 card + ... + + 220 char Myricom Myrinet "GM" board + 0 = /dev/myricom/gm0 First Myrinet GM board + 1 = /dev/myricom/gmp0 First board "root access" + 2 = /dev/myricom/gm1 Second Myrinet GM board + 3 = /dev/myricom/gmp1 Second board "root access" + ... + + 221 char VME bus + 0 = /dev/bus/vme/m0 First master image + 1 = /dev/bus/vme/m1 Second master image + 2 = /dev/bus/vme/m2 Third master image + 3 = /dev/bus/vme/m3 Fourth master image + 4 = /dev/bus/vme/s0 First slave image + 5 = /dev/bus/vme/s1 Second slave image + 6 = /dev/bus/vme/s2 Third slave image + 7 = /dev/bus/vme/s3 Fourth slave image + 8 = /dev/bus/vme/ctl Control + + It is expected that all VME bus drivers will use the + same interface. For interface documentation see + http://www.vmelinux.org/. + + 224 char A2232 serial card + 0 = /dev/ttyY0 First A2232 port + 1 = /dev/ttyY1 Second A2232 port + ... + + 225 char A2232 serial card (alternate devices) + 0 = /dev/cuy0 Callout device for ttyY0 + 1 = /dev/cuy1 Callout device for ttyY1 + ... + + 226 char Direct Rendering Infrastructure (DRI) + 0 = /dev/dri/card0 First graphics card + 1 = /dev/dri/card1 Second graphics card + ... + + 227 char IBM 3270 terminal Unix tty access + 1 = /dev/3270/tty1 First 3270 terminal + 2 = /dev/3270/tty2 Seconds 3270 terminal + ... + + 228 char IBM 3270 terminal block-mode access + 0 = /dev/3270/tub Controlling interface + 1 = /dev/3270/tub1 First 3270 terminal + 2 = /dev/3270/tub2 Second 3270 terminal + ... + + 229 char IBM iSeries/pSeries virtual console + 0 = /dev/hvc0 First console port + 1 = /dev/hvc1 Second console port + ... + + 230 char IBM iSeries virtual tape + 0 = /dev/iseries/vt0 First virtual tape, mode 0 + 1 = /dev/iseries/vt1 Second virtual tape, mode 0 + ... + 32 = /dev/iseries/vt0l First virtual tape, mode 1 + 33 = /dev/iseries/vt1l Second virtual tape, mode 1 + ... + 64 = /dev/iseries/vt0m First virtual tape, mode 2 + 65 = /dev/iseries/vt1m Second virtual tape, mode 2 + ... + 96 = /dev/iseries/vt0a First virtual tape, mode 3 + 97 = /dev/iseries/vt1a Second virtual tape, mode 3 + ... + 128 = /dev/iseries/nvt0 First virtual tape, mode 0, no rewind + 129 = /dev/iseries/nvt1 Second virtual tape, mode 0, no rewind + ... + 160 = /dev/iseries/nvt0l First virtual tape, mode 1, no rewind + 161 = /dev/iseries/nvt1l Second virtual tape, mode 1, no rewind + ... + 192 = /dev/iseries/nvt0m First virtual tape, mode 2, no rewind + 193 = /dev/iseries/nvt1m Second virtual tape, mode 2, no rewind + ... + 224 = /dev/iseries/nvt0a First virtual tape, mode 3, no rewind + 225 = /dev/iseries/nvt1a Second virtual tape, mode 3, no rewind + ... + + "No rewind" refers to the omission of the default + automatic rewind on device close. The MTREW or MTOFFL + ioctl()'s can be used to rewind the tape regardless of + the device used to access it. + + 231 char InfiniBand + 0 = /dev/infiniband/umad0 + 1 = /dev/infiniband/umad1 + ... + 63 = /dev/infiniband/umad63 63rd InfiniBandMad device + 64 = /dev/infiniband/issm0 First InfiniBand IsSM device + 65 = /dev/infiniband/issm1 Second InfiniBand IsSM device + ... + 127 = /dev/infiniband/issm63 63rd InfiniBand IsSM device + 128 = /dev/infiniband/uverbs0 First InfiniBand verbs device + 129 = /dev/infiniband/uverbs1 Second InfiniBand verbs device + ... + 159 = /dev/infiniband/uverbs31 31st InfiniBand verbs device + + 232 char Biometric Devices + 0 = /dev/biometric/sensor0/fingerprint first fingerprint sensor on first device + 1 = /dev/biometric/sensor0/iris first iris sensor on first device + 2 = /dev/biometric/sensor0/retina first retina sensor on first device + 3 = /dev/biometric/sensor0/voiceprint first voiceprint sensor on first device + 4 = /dev/biometric/sensor0/facial first facial sensor on first device + 5 = /dev/biometric/sensor0/hand first hand sensor on first device + ... + 10 = /dev/biometric/sensor1/fingerprint first fingerprint sensor on second device + ... + 20 = /dev/biometric/sensor2/fingerprint first fingerprint sensor on third device + ... + + 233 char PathScale InfiniPath interconnect + 0 = /dev/ipath Primary device for programs (any unit) + 1 = /dev/ipath0 Access specifically to unit 0 + 2 = /dev/ipath1 Access specifically to unit 1 + ... + 4 = /dev/ipath3 Access specifically to unit 3 + 129 = /dev/ipath_sma Device used by Subnet Management Agent + 130 = /dev/ipath_diag Device used by diagnostics programs + + 234-254 char RESERVED FOR DYNAMIC ASSIGNMENT + Character devices that request a dynamic allocation of major number will + take numbers starting from 254 and downward. + + 240-254 block LOCAL/EXPERIMENTAL USE + Allocated for local/experimental use. For devices not + assigned official numbers, these ranges should be + used in order to avoid conflicting with future assignments. + + 255 char RESERVED + + 255 block RESERVED + + This major is reserved to assist the expansion to a + larger number space. No device nodes with this major + should ever be created on the filesystem. + (This is probably not true anymore, but I'll leave it + for now /Torben) + + ---LARGE MAJORS!!!!!--- + + 256 char Equinox SST multi-port serial boards + 0 = /dev/ttyEQ0 First serial port on first Equinox SST board + 127 = /dev/ttyEQ127 Last serial port on first Equinox SST board + 128 = /dev/ttyEQ128 First serial port on second Equinox SST board + ... + 1027 = /dev/ttyEQ1027 Last serial port on eighth Equinox SST board + + 256 block Resident Flash Disk Flash Translation Layer + 0 = /dev/rfda First RFD FTL layer + 16 = /dev/rfdb Second RFD FTL layer + ... + 240 = /dev/rfdp 16th RFD FTL layer + + 257 char Phoenix Technologies Cryptographic Services Driver + 0 = /dev/ptlsec Crypto Services Driver + + 257 block SSFDC Flash Translation Layer filesystem + 0 = /dev/ssfdca First SSFDC layer + 8 = /dev/ssfdcb Second SSFDC layer + 16 = /dev/ssfdcc Third SSFDC layer + 24 = /dev/ssfdcd 4th SSFDC layer + 32 = /dev/ssfdce 5th SSFDC layer + 40 = /dev/ssfdcf 6th SSFDC layer + 48 = /dev/ssfdcg 7th SSFDC layer + 56 = /dev/ssfdch 8th SSFDC layer + + 258 block ROM/Flash read-only translation layer + 0 = /dev/blockrom0 First ROM card's translation layer interface + 1 = /dev/blockrom1 Second ROM card's translation layer interface + ... + + 259 block Block Extended Major + Used dynamically to hold additional partition minor + numbers and allow large numbers of partitions per device + + 259 char FPGA configuration interfaces + 0 = /dev/icap0 First Xilinx internal configuration + 1 = /dev/icap1 Second Xilinx internal configuration + + 260 char OSD (Object-based-device) SCSI Device + 0 = /dev/osd0 First OSD Device + 1 = /dev/osd1 Second OSD Device + ... + 255 = /dev/osd255 256th OSD Device + + +Additional ``/dev/`` directory entries +-------------------------------------- + +This section details additional entries that should or may exist in +the /dev directory. It is preferred that symbolic links use the same +form (absolute or relative) as is indicated here. Links are +classified as "hard" or "symbolic" depending on the preferred type of +link; if possible, the indicated type of link should be used. + +Compulsory links +++++++++++++++++ + +These links should exist on all systems: + +=============== =============== =============== =============================== +/dev/fd /proc/self/fd symbolic File descriptors +/dev/stdin fd/0 symbolic stdin file descriptor +/dev/stdout fd/1 symbolic stdout file descriptor +/dev/stderr fd/2 symbolic stderr file descriptor +/dev/nfsd socksys symbolic Required by iBCS-2 +/dev/X0R null symbolic Required by iBCS-2 +=============== =============== =============== =============================== + +Note: ``/dev/X0R`` is --. + +Recommended links ++++++++++++++++++ + +It is recommended that these links exist on all systems: + + +=============== =============== =============== =============================== +/dev/core /proc/kcore symbolic Backward compatibility +/dev/ramdisk ram0 symbolic Backward compatibility +/dev/ftape qft0 symbolic Backward compatibility +/dev/bttv0 video0 symbolic Backward compatibility +/dev/radio radio0 symbolic Backward compatibility +/dev/i2o* /dev/i2o/* symbolic Backward compatibility +/dev/scd? sr? hard Alternate SCSI CD-ROM name +=============== =============== =============== =============================== + +Locally defined links ++++++++++++++++++++++ + +The following links may be established locally to conform to the +configuration of the system. This is merely a tabulation of existing +practice, and does not constitute a recommendation. However, if they +exist, they should have the following uses. + +=============== =============== =============== =============================== +/dev/mouse mouse port symbolic Current mouse device +/dev/tape tape device symbolic Current tape device +/dev/cdrom CD-ROM device symbolic Current CD-ROM device +/dev/cdwriter CD-writer symbolic Current CD-writer device +/dev/scanner scanner symbolic Current scanner device +/dev/modem modem port symbolic Current dialout device +/dev/root root device symbolic Current root filesystem +/dev/swap swap device symbolic Current swap device +=============== =============== =============== =============================== + +``/dev/modem`` should not be used for a modem which supports dialin as +well as dialout, as it tends to cause lock file problems. If it +exists, ``/dev/modem`` should point to the appropriate primary TTY device +(the use of the alternate callout devices is deprecated). + +For SCSI devices, ``/dev/tape`` and ``/dev/cdrom`` should point to the +*cooked* devices (``/dev/st*`` and ``/dev/sr*``, respectively), whereas +``/dev/cdwriter`` and /dev/scanner should point to the appropriate generic +SCSI devices (/dev/sg*). + +``/dev/mouse`` may point to a primary serial TTY device, a hardware mouse +device, or a socket for a mouse driver program (e.g. ``/dev/gpmdata``). + +Sockets and pipes ++++++++++++++++++ + +Non-transient sockets and named pipes may exist in /dev. Common entries are: + +=============== =============== =============================================== +/dev/printer socket lpd local socket +/dev/log socket syslog local socket +/dev/gpmdata socket gpm mouse multiplexer +=============== =============== =============================================== + +Mount points +++++++++++++ + +The following names are reserved for mounting special filesystems +under /dev. These special filesystems provide kernel interfaces that +cannot be provided with standard device nodes. + +=============== =============== =============================================== +/dev/pts devpts PTY slave filesystem +/dev/shm tmpfs POSIX shared memory maintenance access +=============== =============== =============================================== + +Terminal devices +---------------- + +Terminal, or TTY devices are a special class of character devices. A +terminal device is any device that could act as a controlling terminal +for a session; this includes virtual consoles, serial ports, and +pseudoterminals (PTYs). + +All terminal devices share a common set of capabilities known as line +disciplines; these include the common terminal line discipline as well +as SLIP and PPP modes. + +All terminal devices are named similarly; this section explains the +naming and use of the various types of TTYs. Note that the naming +conventions include several historical warts; some of these are +Linux-specific, some were inherited from other systems, and some +reflect Linux outgrowing a borrowed convention. + +A hash mark (``#``) in a device name is used here to indicate a decimal +number without leading zeroes. + +Virtual consoles and the console device ++++++++++++++++++++++++++++++++++++++++ + +Virtual consoles are full-screen terminal displays on the system video +monitor. Virtual consoles are named ``/dev/tty#``, with numbering +starting at ``/dev/tty1``; ``/dev/tty0`` is the current virtual console. +``/dev/tty0`` is the device that should be used to access the system video +card on those architectures for which the frame buffer devices +(``/dev/fb*``) are not applicable. Do not use ``/dev/console`` +for this purpose. + +The console device, ``/dev/console``, is the device to which system +messages should be sent, and on which logins should be permitted in +single-user mode. Starting with Linux 2.1.71, ``/dev/console`` is managed +by the kernel; for previous versions it should be a symbolic link to +either ``/dev/tty0``, a specific virtual console such as ``/dev/tty1``, or to +a serial port primary (``tty*``, not ``cu*``) device, depending on the +configuration of the system. + +Serial ports +++++++++++++ + +Serial ports are RS-232 serial ports and any device which simulates +one, either in hardware (such as internal modems) or in software (such +as the ISDN driver.) Under Linux, each serial ports has two device +names, the primary or callin device and the alternate or callout one. +Each kind of device is indicated by a different letter. For any +letter X, the names of the devices are ``/dev/ttyX#`` and ``/dev/cux#``, +respectively; for historical reasons, ``/dev/ttyS#`` and ``/dev/ttyC#`` +correspond to ``/dev/cua#`` and ``/dev/cub#``. In the future, it should be +expected that multiple letters will be used; all letters will be upper +case for the "tty" device (e.g. ``/dev/ttyDP#``) and lower case for the +"cu" device (e.g. ``/dev/cudp#``). + +The names ``/dev/ttyQ#`` and ``/dev/cuq#`` are reserved for local use. + +The alternate devices provide for kernel-based exclusion and somewhat +different defaults than the primary devices. Their main purpose is to +allow the use of serial ports with programs with no inherent or broken +support for serial ports. Their use is deprecated, and they may be +removed from a future version of Linux. + +Arbitration of serial ports is provided by the use of lock files with +the names ``/var/lock/LCK..ttyX#``. The contents of the lock file should +be the PID of the locking process as an ASCII number. + +It is common practice to install links such as /dev/modem +which point to serial ports. In order to ensure proper locking in the +presence of these links, it is recommended that software chase +symlinks and lock all possible names; additionally, it is recommended +that a lock file be installed with the corresponding alternate +device. In order to avoid deadlocks, it is recommended that the locks +are acquired in the following order, and released in the reverse: + + 1. The symbolic link name, if any (``/var/lock/LCK..modem``) + 2. The "tty" name (``/var/lock/LCK..ttyS2``) + 3. The alternate device name (``/var/lock/LCK..cua2``) + +In the case of nested symbolic links, the lock files should be +installed in the order the symlinks are resolved. + +Under no circumstances should an application hold a lock while waiting +for another to be released. In addition, applications which attempt +to create lock files for the corresponding alternate device names +should take into account the possibility of being used on a non-serial +port TTY, for which no alternate device would exist. + +Pseudoterminals (PTYs) +++++++++++++++++++++++ + +Pseudoterminals, or PTYs, are used to create login sessions or provide +other capabilities requiring a TTY line discipline (including SLIP or +PPP capability) to arbitrary data-generation processes. Each PTY has +a master side, named ``/dev/pty[p-za-e][0-9a-f]``, and a slave side, named +``/dev/tty[p-za-e][0-9a-f]``. The kernel arbitrates the use of PTYs by +allowing each master side to be opened only once. + +Once the master side has been opened, the corresponding slave device +can be used in the same manner as any TTY device. The master and +slave devices are connected by the kernel, generating the equivalent +of a bidirectional pipe with TTY capabilities. + +Recent versions of the Linux kernels and GNU libc contain support for +the System V/Unix98 naming scheme for PTYs, which assigns a common +device, ``/dev/ptmx``, to all the masters (opening it will automatically +give you a previously unassigned PTY) and a subdirectory, ``/dev/pts``, +for the slaves; the slaves are named with decimal integers (``/dev/pts/#`` +in our notation). This removes the problem of exhausting the +namespace and enables the kernel to automatically create the device +nodes for the slaves on demand using the "devpts" filesystem. diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst new file mode 100644 index 000000000000..88adcfdf5b2b --- /dev/null +++ b/Documentation/admin-guide/dynamic-debug-howto.rst @@ -0,0 +1,353 @@ +Dynamic debug ++++++++++++++ + + +Introduction +============ + +This document describes how to use the dynamic debug (dyndbg) feature. + +Dynamic debug is designed to allow you to dynamically enable/disable +kernel code to obtain additional kernel information. Currently, if +``CONFIG_DYNAMIC_DEBUG`` is set, then all ``pr_debug()``/``dev_dbg()`` and +``print_hex_dump_debug()``/``print_hex_dump_bytes()`` calls can be dynamically +enabled per-callsite. + +If ``CONFIG_DYNAMIC_DEBUG`` is not set, ``print_hex_dump_debug()`` is just +shortcut for ``print_hex_dump(KERN_DEBUG)``. + +For ``print_hex_dump_debug()``/``print_hex_dump_bytes()``, format string is +its ``prefix_str`` argument, if it is constant string; or ``hexdump`` +in case ``prefix_str`` is build dynamically. + +Dynamic debug has even more useful features: + + * Simple query language allows turning on and off debugging + statements by matching any combination of 0 or 1 of: + + - source filename + - function name + - line number (including ranges of line numbers) + - module name + - format string + + * Provides a debugfs control file: ``/dynamic_debug/control`` + which can be read to display the complete list of known debug + statements, to help guide you + +Controlling dynamic debug Behaviour +=================================== + +The behaviour of ``pr_debug()``/``dev_dbg()`` are controlled via writing to a +control file in the 'debugfs' filesystem. Thus, you must first mount +the debugfs filesystem, in order to make use of this feature. +Subsequently, we refer to the control file as: +``/dynamic_debug/control``. For example, if you want to enable +printing from source file ``svcsock.c``, line 1603 you simply do:: + + nullarbor:~ # echo 'file svcsock.c line 1603 +p' > + /dynamic_debug/control + +If you make a mistake with the syntax, the write will fail thus:: + + nullarbor:~ # echo 'file svcsock.c wtf 1 +p' > + /dynamic_debug/control + -bash: echo: write error: Invalid argument + +Viewing Dynamic Debug Behaviour +=============================== + +You can view the currently configured behaviour of all the debug +statements via:: + + nullarbor:~ # cat /dynamic_debug/control + # filename:lineno [module]function flags format + /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:323 [svcxprt_rdma]svc_rdma_cleanup =_ "SVCRDMA Module Removed, deregister RPC RDMA transport\012" + /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:341 [svcxprt_rdma]svc_rdma_init =_ "\011max_inline : %d\012" + /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:340 [svcxprt_rdma]svc_rdma_init =_ "\011sq_depth : %d\012" + /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:338 [svcxprt_rdma]svc_rdma_init =_ "\011max_requests : %d\012" + ... + + +You can also apply standard Unix text manipulation filters to this +data, e.g.:: + + nullarbor:~ # grep -i rdma /dynamic_debug/control | wc -l + 62 + + nullarbor:~ # grep -i tcp /dynamic_debug/control | wc -l + 42 + +The third column shows the currently enabled flags for each debug +statement callsite (see below for definitions of the flags). The +default value, with no flags enabled, is ``=_``. So you can view all +the debug statement callsites with any non-default flags:: + + nullarbor:~ # awk '$3 != "=_"' /dynamic_debug/control + # filename:lineno [module]function flags format + /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svcsock.c:1603 [sunrpc]svc_send p "svc_process: st_sendto returned %d\012" + +Command Language Reference +========================== + +At the lexical level, a command comprises a sequence of words separated +by spaces or tabs. So these are all equivalent:: + + nullarbor:~ # echo -c 'file svcsock.c line 1603 +p' > + /dynamic_debug/control + nullarbor:~ # echo -c ' file svcsock.c line 1603 +p ' > + /dynamic_debug/control + nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' > + /dynamic_debug/control + +Command submissions are bounded by a write() system call. +Multiple commands can be written together, separated by ``;`` or ``\n``:: + + ~# echo "func pnpacpi_get_resources +p; func pnp_assign_mem +p" \ + > /dynamic_debug/control + +If your query set is big, you can batch them too:: + + ~# cat query-batch-file > /dynamic_debug/control + +A another way is to use wildcard. The match rule support ``*`` (matches +zero or more characters) and ``?`` (matches exactly one character).For +example, you can match all usb drivers:: + + ~# echo "file drivers/usb/* +p" > /dynamic_debug/control + +At the syntactical level, a command comprises a sequence of match +specifications, followed by a flags change specification:: + + command ::= match-spec* flags-spec + +The match-spec's are used to choose a subset of the known pr_debug() +callsites to which to apply the flags-spec. Think of them as a query +with implicit ANDs between each pair. Note that an empty list of +match-specs will select all debug statement callsites. + +A match specification comprises a keyword, which controls the +attribute of the callsite to be compared, and a value to compare +against. Possible keywords are::: + + match-spec ::= 'func' string | + 'file' string | + 'module' string | + 'format' string | + 'line' line-range + + line-range ::= lineno | + '-'lineno | + lineno'-' | + lineno'-'lineno + + lineno ::= unsigned-int + +.. note:: + + ``line-range`` cannot contain space, e.g. + "1-30" is valid range but "1 - 30" is not. + + +The meanings of each keyword are: + +func + The given string is compared against the function name + of each callsite. Example:: + + func svc_tcp_accept + +file + The given string is compared against either the full pathname, the + src-root relative pathname, or the basename of the source file of + each callsite. Examples:: + + file svcsock.c + file kernel/freezer.c + file /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svcsock.c + +module + The given string is compared against the module name + of each callsite. The module name is the string as + seen in ``lsmod``, i.e. without the directory or the ``.ko`` + suffix and with ``-`` changed to ``_``. Examples:: + + module sunrpc + module nfsd + +format + The given string is searched for in the dynamic debug format + string. Note that the string does not need to match the + entire format, only some part. Whitespace and other + special characters can be escaped using C octal character + escape ``\ooo`` notation, e.g. the space character is ``\040``. + Alternatively, the string can be enclosed in double quote + characters (``"``) or single quote characters (``'``). + Examples:: + + format svcrdma: // many of the NFS/RDMA server pr_debugs + format readahead // some pr_debugs in the readahead cache + format nfsd:\040SETATTR // one way to match a format with whitespace + format "nfsd: SETATTR" // a neater way to match a format with whitespace + format 'nfsd: SETATTR' // yet another way to match a format with whitespace + +line + The given line number or range of line numbers is compared + against the line number of each ``pr_debug()`` callsite. A single + line number matches the callsite line number exactly. A + range of line numbers matches any callsite between the first + and last line number inclusive. An empty first number means + the first line in the file, an empty line number means the + last number in the file. Examples:: + + line 1603 // exactly line 1603 + line 1600-1605 // the six lines from line 1600 to line 1605 + line -1605 // the 1605 lines from line 1 to line 1605 + line 1600- // all lines from line 1600 to the end of the file + +The flags specification comprises a change operation followed +by one or more flag characters. The change operation is one +of the characters:: + + - remove the given flags + + add the given flags + = set the flags to the given flags + +The flags are:: + + p enables the pr_debug() callsite. + f Include the function name in the printed message + l Include line number in the printed message + m Include module name in the printed message + t Include thread ID in messages not generated from interrupt context + _ No flags are set. (Or'd with others on input) + +For ``print_hex_dump_debug()`` and ``print_hex_dump_bytes()``, only ``p`` flag +have meaning, other flags ignored. + +For display, the flags are preceded by ``=`` +(mnemonic: what the flags are currently equal to). + +Note the regexp ``^[-+=][flmpt_]+$`` matches a flags specification. +To clear all flags at once, use ``=_`` or ``-flmpt``. + + +Debug messages during Boot Process +================================== + +To activate debug messages for core code and built-in modules during +the boot process, even before userspace and debugfs exists, use +``dyndbg="QUERY"``, ``module.dyndbg="QUERY"``, or ``ddebug_query="QUERY"`` +(``ddebug_query`` is obsoleted by ``dyndbg``, and deprecated). QUERY follows +the syntax described above, but must not exceed 1023 characters. Your +bootloader may impose lower limits. + +These ``dyndbg`` params are processed just after the ddebug tables are +processed, as part of the arch_initcall. Thus you can enable debug +messages in all code run after this arch_initcall via this boot +parameter. + +On an x86 system for example ACPI enablement is a subsys_initcall and:: + + dyndbg="file ec.c +p" + +will show early Embedded Controller transactions during ACPI setup if +your machine (typically a laptop) has an Embedded Controller. +PCI (or other devices) initialization also is a hot candidate for using +this boot parameter for debugging purposes. + +If ``foo`` module is not built-in, ``foo.dyndbg`` will still be processed at +boot time, without effect, but will be reprocessed when module is +loaded later. ``dyndbg_query=`` and bare ``dyndbg=`` are only processed at +boot. + + +Debug Messages at Module Initialization Time +============================================ + +When ``modprobe foo`` is called, modprobe scans ``/proc/cmdline`` for +``foo.params``, strips ``foo.``, and passes them to the kernel along with +params given in modprobe args or ``/etc/modprob.d/*.conf`` files, +in the following order: + +1. parameters given via ``/etc/modprobe.d/*.conf``:: + + options foo dyndbg=+pt + options foo dyndbg # defaults to +p + +2. ``foo.dyndbg`` as given in boot args, ``foo.`` is stripped and passed:: + + foo.dyndbg=" func bar +p; func buz +mp" + +3. args to modprobe:: + + modprobe foo dyndbg==pmf # override previous settings + +These ``dyndbg`` queries are applied in order, with last having final say. +This allows boot args to override or modify those from ``/etc/modprobe.d`` +(sensible, since 1 is system wide, 2 is kernel or boot specific), and +modprobe args to override both. + +In the ``foo.dyndbg="QUERY"`` form, the query must exclude ``module foo``. +``foo`` is extracted from the param-name, and applied to each query in +``QUERY``, and only 1 match-spec of each type is allowed. + +The ``dyndbg`` option is a "fake" module parameter, which means: + +- modules do not need to define it explicitly +- every module gets it tacitly, whether they use pr_debug or not +- it doesn't appear in ``/sys/module/$module/parameters/`` + To see it, grep the control file, or inspect ``/proc/cmdline.`` + +For ``CONFIG_DYNAMIC_DEBUG`` kernels, any settings given at boot-time (or +enabled by ``-DDEBUG`` flag during compilation) can be disabled later via +the sysfs interface if the debug messages are no longer needed:: + + echo "module module_name -p" > /dynamic_debug/control + +Examples +======== + +:: + + // enable the message at line 1603 of file svcsock.c + nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' > + /dynamic_debug/control + + // enable all the messages in file svcsock.c + nullarbor:~ # echo -n 'file svcsock.c +p' > + /dynamic_debug/control + + // enable all the messages in the NFS server module + nullarbor:~ # echo -n 'module nfsd +p' > + /dynamic_debug/control + + // enable all 12 messages in the function svc_process() + nullarbor:~ # echo -n 'func svc_process +p' > + /dynamic_debug/control + + // disable all 12 messages in the function svc_process() + nullarbor:~ # echo -n 'func svc_process -p' > + /dynamic_debug/control + + // enable messages for NFS calls READ, READLINK, READDIR and READDIR+. + nullarbor:~ # echo -n 'format "nfsd: READ" +p' > + /dynamic_debug/control + + // enable messages in files of which the paths include string "usb" + nullarbor:~ # echo -n '*usb* +p' > /dynamic_debug/control + + // enable all messages + nullarbor:~ # echo -n '+p' > /dynamic_debug/control + + // add module, function to all enabled messages + nullarbor:~ # echo -n '+mf' > /dynamic_debug/control + + // boot-args example, with newlines and comments for readability + Kernel command line: ... + // see whats going on in dyndbg=value processing + dynamic_debug.verbose=1 + // enable pr_debugs in 2 builtins, #cmt is stripped + dyndbg="module params +p #cmt ; module sys +p" + // enable pr_debugs in 2 functions in a module loaded later + pc87360.dyndbg="func pc87360_init_device +p; func pc87360_find +p" diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst new file mode 100644 index 000000000000..4e5abbb4bbd5 --- /dev/null +++ b/Documentation/admin-guide/index.rst @@ -0,0 +1,34 @@ +Linux Kernel User's Documentation +================================= + +Contents: + +.. toctree:: + :maxdepth: 2 + :numbered: + + README + reporting-bugs + bug-hunting + oops-tracing + ramoops + initrd + init + dynamic-debug-howto + security-bugs + kernel-parameters + serial-console + braille-console + parport + md + module-signing + sysrq + unicode + vga-softcursor + sysfs-rules + devices + binfmt-misc + mono + java + bad-memory + basic-profiling diff --git a/Documentation/admin-guide/init.rst b/Documentation/admin-guide/init.rst new file mode 100644 index 000000000000..e89d97f31eaf --- /dev/null +++ b/Documentation/admin-guide/init.rst @@ -0,0 +1,52 @@ +Explaining the dreaded "No init found." boot hang message +========================================================= + +OK, so you've got this pretty unintuitive message (currently located +in init/main.c) and are wondering what the H*** went wrong. +Some high-level reasons for failure (listed roughly in order of execution) +to load the init binary are: + +A) Unable to mount root FS +B) init binary doesn't exist on rootfs +C) broken console device +D) binary exists but dependencies not available +E) binary cannot be loaded + +Detailed explanations: + +A) Set "debug" kernel parameter (in bootloader config file or CONFIG_CMDLINE) + to get more detailed kernel messages. +B) make sure you have the correct root FS type + (and ``root=`` kernel parameter points to the correct partition), + required drivers such as storage hardware (such as SCSI or USB!) + and filesystem (ext3, jffs2 etc.) are builtin (alternatively as modules, + to be pre-loaded by an initrd) +C) Possibly a conflict in ``console= setup`` --> initial console unavailable. + E.g. some serial consoles are unreliable due to serial IRQ issues (e.g. + missing interrupt-based configuration). + Try using a different ``console= device`` or e.g. ``netconsole=``. +D) e.g. required library dependencies of the init binary such as + ``/lib/ld-linux.so.2`` missing or broken. Use + ``readelf -d |grep NEEDED`` to find out which libraries are required. +E) make sure the binary's architecture matches your hardware. + E.g. i386 vs. x86_64 mismatch, or trying to load x86 on ARM hardware. + In case you tried loading a non-binary file here (shell script?), + you should make sure that the script specifies an interpreter in its shebang + header line (``#!/...``) that is fully working (including its library + dependencies). And before tackling scripts, better first test a simple + non-script binary such as ``/bin/sh`` and confirm its successful execution. + To find out more, add code ``to init/main.c`` to display kernel_execve()s + return values. + +Please extend this explanation whenever you find new failure causes +(after all loading the init binary is a CRITICAL and hard transition step +which needs to be made as painless as possible), then submit patch to LKML. +Further TODOs: + +- Implement the various ``run_init_process()`` invocations via a struct array + which can then store the ``kernel_execve()`` result value and on failure + log it all by iterating over **all** results (very important usability fix). +- try to make the implementation itself more helpful in general, + e.g. by providing additional error messages at affected places. + +Andreas Mohr diff --git a/Documentation/admin-guide/initrd.rst b/Documentation/admin-guide/initrd.rst new file mode 100644 index 000000000000..a03dabaaf3a3 --- /dev/null +++ b/Documentation/admin-guide/initrd.rst @@ -0,0 +1,383 @@ +Using the initial RAM disk (initrd) +=================================== + +Written 1996,2000 by Werner Almesberger and +Hans Lermen + + +initrd provides the capability to load a RAM disk by the boot loader. +This RAM disk can then be mounted as the root file system and programs +can be run from it. Afterwards, a new root file system can be mounted +from a different device. The previous root (from initrd) is then moved +to a directory and can be subsequently unmounted. + +initrd is mainly designed to allow system startup to occur in two phases, +where the kernel comes up with a minimum set of compiled-in drivers, and +where additional modules are loaded from initrd. + +This document gives a brief overview of the use of initrd. A more detailed +discussion of the boot process can be found in [#f1]_. + + +Operation +--------- + +When using initrd, the system typically boots as follows: + + 1) the boot loader loads the kernel and the initial RAM disk + 2) the kernel converts initrd into a "normal" RAM disk and + frees the memory used by initrd + 3) if the root device is not ``/dev/ram0``, the old (deprecated) + change_root procedure is followed. see the "Obsolete root change + mechanism" section below. + 4) root device is mounted. if it is ``/dev/ram0``, the initrd image is + then mounted as root + 5) /sbin/init is executed (this can be any valid executable, including + shell scripts; it is run with uid 0 and can do basically everything + init can do). + 6) init mounts the "real" root file system + 7) init places the root file system at the root directory using the + pivot_root system call + 8) init execs the ``/sbin/init`` on the new root filesystem, performing + the usual boot sequence + 9) the initrd file system is removed + +Note that changing the root directory does not involve unmounting it. +It is therefore possible to leave processes running on initrd during that +procedure. Also note that file systems mounted under initrd continue to +be accessible. + + +Boot command-line options +------------------------- + +initrd adds the following new options:: + + initrd= (e.g. LOADLIN) + + Loads the specified file as the initial RAM disk. When using LILO, you + have to specify the RAM disk image file in /etc/lilo.conf, using the + INITRD configuration variable. + + noinitrd + + initrd data is preserved but it is not converted to a RAM disk and + the "normal" root file system is mounted. initrd data can be read + from /dev/initrd. Note that the data in initrd can have any structure + in this case and doesn't necessarily have to be a file system image. + This option is used mainly for debugging. + + Note: /dev/initrd is read-only and it can only be used once. As soon + as the last process has closed it, all data is freed and /dev/initrd + can't be opened anymore. + + root=/dev/ram0 + + initrd is mounted as root, and the normal boot procedure is followed, + with the RAM disk mounted as root. + +Compressed cpio images +---------------------- + +Recent kernels have support for populating a ramdisk from a compressed cpio +archive. On such systems, the creation of a ramdisk image doesn't need to +involve special block devices or loopbacks; you merely create a directory on +disk with the desired initrd content, cd to that directory, and run (as an +example):: + + find . | cpio --quiet -H newc -o | gzip -9 -n > /boot/imagefile.img + +Examining the contents of an existing image file is just as simple:: + + mkdir /tmp/imagefile + cd /tmp/imagefile + gzip -cd /boot/imagefile.img | cpio -imd --quiet + +Installation +------------ + +First, a directory for the initrd file system has to be created on the +"normal" root file system, e.g.:: + + # mkdir /initrd + +The name is not relevant. More details can be found on the +:manpage:`pivot_root(2)` man page. + +If the root file system is created during the boot procedure (i.e. if +you're building an install floppy), the root file system creation +procedure should create the ``/initrd`` directory. + +If initrd will not be mounted in some cases, its content is still +accessible if the following device has been created:: + + # mknod /dev/initrd b 1 250 + # chmod 400 /dev/initrd + +Second, the kernel has to be compiled with RAM disk support and with +support for the initial RAM disk enabled. Also, at least all components +needed to execute programs from initrd (e.g. executable format and file +system) must be compiled into the kernel. + +Third, you have to create the RAM disk image. This is done by creating a +file system on a block device, copying files to it as needed, and then +copying the content of the block device to the initrd file. With recent +kernels, at least three types of devices are suitable for that: + + - a floppy disk (works everywhere but it's painfully slow) + - a RAM disk (fast, but allocates physical memory) + - a loopback device (the most elegant solution) + +We'll describe the loopback device method: + + 1) make sure loopback block devices are configured into the kernel + 2) create an empty file system of the appropriate size, e.g.:: + + # dd if=/dev/zero of=initrd bs=300k count=1 + # mke2fs -F -m0 initrd + + (if space is critical, you may want to use the Minix FS instead of Ext2) + 3) mount the file system, e.g.:: + + # mount -t ext2 -o loop initrd /mnt + + 4) create the console device:: + + # mkdir /mnt/dev + # mknod /mnt/dev/console c 5 1 + + 5) copy all the files that are needed to properly use the initrd + environment. Don't forget the most important file, ``/sbin/init`` + + .. note:: ``/sbin/init`` permissions must include "x" (execute). + + 6) correct operation the initrd environment can frequently be tested + even without rebooting with the command:: + + # chroot /mnt /sbin/init + + This is of course limited to initrds that do not interfere with the + general system state (e.g. by reconfiguring network interfaces, + overwriting mounted devices, trying to start already running demons, + etc. Note however that it is usually possible to use pivot_root in + such a chroot'ed initrd environment.) + 7) unmount the file system:: + + # umount /mnt + + 8) the initrd is now in the file "initrd". Optionally, it can now be + compressed:: + + # gzip -9 initrd + +For experimenting with initrd, you may want to take a rescue floppy and +only add a symbolic link from ``/sbin/init`` to ``/bin/sh``. Alternatively, you +can try the experimental newlib environment [#f2]_ to create a small +initrd. + +Finally, you have to boot the kernel and load initrd. Almost all Linux +boot loaders support initrd. Since the boot process is still compatible +with an older mechanism, the following boot command line parameters +have to be given:: + + root=/dev/ram0 rw + +(rw is only necessary if writing to the initrd file system.) + +With LOADLIN, you simply execute:: + + LOADLIN initrd= + +e.g.:: + + LOADLIN C:\LINUX\BZIMAGE initrd=C:\LINUX\INITRD.GZ root=/dev/ram0 rw + +With LILO, you add the option ``INITRD=`` to either the global section +or to the section of the respective kernel in ``/etc/lilo.conf``, and pass +the options using APPEND, e.g.:: + + image = /bzImage + initrd = /boot/initrd.gz + append = "root=/dev/ram0 rw" + +and run ``/sbin/lilo`` + +For other boot loaders, please refer to the respective documentation. + +Now you can boot and enjoy using initrd. + + +Changing the root device +------------------------ + +When finished with its duties, init typically changes the root device +and proceeds with starting the Linux system on the "real" root device. + +The procedure involves the following steps: + - mounting the new root file system + - turning it into the root file system + - removing all accesses to the old (initrd) root file system + - unmounting the initrd file system and de-allocating the RAM disk + +Mounting the new root file system is easy: it just needs to be mounted on +a directory under the current root. Example:: + + # mkdir /new-root + # mount -o ro /dev/hda1 /new-root + +The root change is accomplished with the pivot_root system call, which +is also available via the ``pivot_root`` utility (see :manpage:`pivot_root(8)` +man page; ``pivot_root`` is distributed with util-linux version 2.10h or higher +[#f3]_). ``pivot_root`` moves the current root to a directory under the new +root, and puts the new root at its place. The directory for the old root +must exist before calling ``pivot_root``. Example:: + + # cd /new-root + # mkdir initrd + # pivot_root . initrd + +Now, the init process may still access the old root via its +executable, shared libraries, standard input/output/error, and its +current root directory. All these references are dropped by the +following command:: + + # exec chroot . what-follows dev/console 2>&1 + +Where what-follows is a program under the new root, e.g. ``/sbin/init`` +If the new root file system will be used with udev and has no valid +``/dev`` directory, udev must be initialized before invoking chroot in order +to provide ``/dev/console``. + +Note: implementation details of pivot_root may change with time. In order +to ensure compatibility, the following points should be observed: + + - before calling pivot_root, the current directory of the invoking + process should point to the new root directory + - use . as the first argument, and the _relative_ path of the directory + for the old root as the second argument + - a chroot program must be available under the old and the new root + - chroot to the new root afterwards + - use relative paths for dev/console in the exec command + +Now, the initrd can be unmounted and the memory allocated by the RAM +disk can be freed:: + + # umount /initrd + # blockdev --flushbufs /dev/ram0 + +It is also possible to use initrd with an NFS-mounted root, see the +:manpage:`pivot_root(8)` man page for details. + + +Usage scenarios +--------------- + +The main motivation for implementing initrd was to allow for modular +kernel configuration at system installation. The procedure would work +as follows: + + 1) system boots from floppy or other media with a minimal kernel + (e.g. support for RAM disks, initrd, a.out, and the Ext2 FS) and + loads initrd + 2) ``/sbin/init`` determines what is needed to (1) mount the "real" root FS + (i.e. device type, device drivers, file system) and (2) the + distribution media (e.g. CD-ROM, network, tape, ...). This can be + done by asking the user, by auto-probing, or by using a hybrid + approach. + 3) ``/sbin/init`` loads the necessary kernel modules + 4) ``/sbin/init`` creates and populates the root file system (this doesn't + have to be a very usable system yet) + 5) ``/sbin/init`` invokes ``pivot_root`` to change the root file system and + execs - via chroot - a program that continues the installation + 6) the boot loader is installed + 7) the boot loader is configured to load an initrd with the set of + modules that was used to bring up the system (e.g. ``/initrd`` can be + modified, then unmounted, and finally, the image is written from + ``/dev/ram0`` or ``/dev/rd/0`` to a file) + 8) now the system is bootable and additional installation tasks can be + performed + +The key role of initrd here is to re-use the configuration data during +normal system operation without requiring the use of a bloated "generic" +kernel or re-compiling or re-linking the kernel. + +A second scenario is for installations where Linux runs on systems with +different hardware configurations in a single administrative domain. In +such cases, it is desirable to generate only a small set of kernels +(ideally only one) and to keep the system-specific part of configuration +information as small as possible. In this case, a common initrd could be +generated with all the necessary modules. Then, only ``/sbin/init`` or a file +read by it would have to be different. + +A third scenario is more convenient recovery disks, because information +like the location of the root FS partition doesn't have to be provided at +boot time, but the system loaded from initrd can invoke a user-friendly +dialog and it can also perform some sanity checks (or even some form of +auto-detection). + +Last not least, CD-ROM distributors may use it for better installation +from CD, e.g. by using a boot floppy and bootstrapping a bigger RAM disk +via initrd from CD; or by booting via a loader like ``LOADLIN`` or directly +from the CD-ROM, and loading the RAM disk from CD without need of +floppies. + + +Obsolete root change mechanism +------------------------------ + +The following mechanism was used before the introduction of pivot_root. +Current kernels still support it, but you should _not_ rely on its +continued availability. + +It works by mounting the "real" root device (i.e. the one set with rdev +in the kernel image or with root=... at the boot command line) as the +root file system when linuxrc exits. The initrd file system is then +unmounted, or, if it is still busy, moved to a directory ``/initrd``, if +such a directory exists on the new root file system. + +In order to use this mechanism, you do not have to specify the boot +command options root, init, or rw. (If specified, they will affect +the real root file system, not the initrd environment.) + +If /proc is mounted, the "real" root device can be changed from within +linuxrc by writing the number of the new root FS device to the special +file /proc/sys/kernel/real-root-dev, e.g.:: + + # echo 0x301 >/proc/sys/kernel/real-root-dev + +Note that the mechanism is incompatible with NFS and similar file +systems. + +This old, deprecated mechanism is commonly called ``change_root``, while +the new, supported mechanism is called ``pivot_root``. + + +Mixed change_root and pivot_root mechanism +------------------------------------------ + +In case you did not want to use ``root=/dev/ram0`` to trigger the pivot_root +mechanism, you may create both ``/linuxrc`` and ``/sbin/init`` in your initrd +image. + +``/linuxrc`` would contain only the following:: + + #! /bin/sh + mount -n -t proc proc /proc + echo 0x0100 >/proc/sys/kernel/real-root-dev + umount -n /proc + +Once linuxrc exited, the kernel would mount again your initrd as root, +this time executing ``/sbin/init``. Again, it would be the duty of this init +to build the right environment (maybe using the ``root= device`` passed on +the cmdline) before the final execution of the real ``/sbin/init``. + + +Resources +--------- + +.. [#f1] Almesberger, Werner; "Booting Linux: The History and the Future" + http://www.almesberger.net/cv/papers/ols2k-9.ps.gz +.. [#f2] newlib package (experimental), with initrd example + https://www.sourceware.org/newlib/ +.. [#f3] util-linux: Miscellaneous utilities for Linux + https://www.kernel.org/pub/linux/utils/util-linux/ diff --git a/Documentation/admin-guide/java.rst b/Documentation/admin-guide/java.rst new file mode 100644 index 000000000000..a0de7c1a1ed9 --- /dev/null +++ b/Documentation/admin-guide/java.rst @@ -0,0 +1,417 @@ +Java(tm) Binary Kernel Support for Linux v1.03 +---------------------------------------------- + +Linux beats them ALL! While all other OS's are TALKING about direct +support of Java Binaries in the OS, Linux is doing it! + +You can execute Java applications and Java Applets just like any +other program after you have done the following: + +1) You MUST FIRST install the Java Developers Kit for Linux. + The Java on Linux HOWTO gives the details on getting and + installing this. This HOWTO can be found at: + + ftp://sunsite.unc.edu/pub/Linux/docs/HOWTO/Java-HOWTO + + You should also set up a reasonable CLASSPATH environment + variable to use Java applications that make use of any + nonstandard classes (not included in the same directory + as the application itself). + +2) You have to compile BINFMT_MISC either as a module or into + the kernel (``CONFIG_BINFMT_MISC``) and set it up properly. + If you choose to compile it as a module, you will have + to insert it manually with modprobe/insmod, as kmod + cannot easily be supported with binfmt_misc. + Read the file 'binfmt_misc.txt' in this directory to know + more about the configuration process. + +3) Add the following configuration items to binfmt_misc + (you should really have read ``binfmt_misc.txt`` now): + support for Java applications:: + + ':Java:M::\xca\xfe\xba\xbe::/usr/local/bin/javawrapper:' + + support for executable Jar files:: + + ':ExecutableJAR:E::jar::/usr/local/bin/jarwrapper:' + + support for Java Applets:: + + ':Applet:E::html::/usr/bin/appletviewer:' + + or the following, if you want to be more selective:: + + ':Applet:M::`` in the first line + (``<`` has to be the first character!) to let this work! + + For the compiled Java programs you need a wrapper script like the + following (this is because Java is broken in case of the filename + handling), again fix the path names, both in the script and in the + above given configuration string. + + You, too, need the little program after the script. Compile like:: + + gcc -O2 -o javaclassname javaclassname.c + + and stick it to ``/usr/local/bin``. + + Both the javawrapper shellscript and the javaclassname program + were supplied by Colin J. Watson . + +Javawrapper shell script:: + + #!/bin/bash + # /usr/local/bin/javawrapper - the wrapper for binfmt_misc/java + + if [ -z "$1" ]; then + exec 1>&2 + echo Usage: $0 class-file + exit 1 + fi + + CLASS=$1 + FQCLASS=`/usr/local/bin/javaclassname $1` + FQCLASSN=`echo $FQCLASS | sed -e 's/^.*\.\([^.]*\)$/\1/'` + FQCLASSP=`echo $FQCLASS | sed -e 's-\.-/-g' -e 's-^[^/]*$--' -e 's-/[^/]*$--'` + + # for example: + # CLASS=Test.class + # FQCLASS=foo.bar.Test + # FQCLASSN=Test + # FQCLASSP=foo/bar + + unset CLASSBASE + + declare -i LINKLEVEL=0 + + while :; do + if [ "`basename $CLASS .class`" == "$FQCLASSN" ]; then + # See if this directory works straight off + cd -L `dirname $CLASS` + CLASSDIR=$PWD + cd $OLDPWD + if echo $CLASSDIR | grep -q "$FQCLASSP$"; then + CLASSBASE=`echo $CLASSDIR | sed -e "s.$FQCLASSP$.."` + break; + fi + # Try dereferencing the directory name + cd -P `dirname $CLASS` + CLASSDIR=$PWD + cd $OLDPWD + if echo $CLASSDIR | grep -q "$FQCLASSP$"; then + CLASSBASE=`echo $CLASSDIR | sed -e "s.$FQCLASSP$.."` + break; + fi + # If no other possible filename exists + if [ ! -L $CLASS ]; then + exec 1>&2 + echo $0: + echo " $CLASS should be in a" \ + "directory tree called $FQCLASSP" + exit 1 + fi + fi + if [ ! -L $CLASS ]; then break; fi + # Go down one more level of symbolic links + let LINKLEVEL+=1 + if [ $LINKLEVEL -gt 5 ]; then + exec 1>&2 + echo $0: + echo " Too many symbolic links encountered" + exit 1 + fi + CLASS=`ls --color=no -l $CLASS | sed -e 's/^.* \([^ ]*\)$/\1/'` + done + + if [ -z "$CLASSBASE" ]; then + if [ -z "$FQCLASSP" ]; then + GOODNAME=$FQCLASSN.class + else + GOODNAME=$FQCLASSP/$FQCLASSN.class + fi + exec 1>&2 + echo $0: + echo " $FQCLASS should be in a file called $GOODNAME" + exit 1 + fi + + if ! echo $CLASSPATH | grep -q "^\(.*:\)*$CLASSBASE\(:.*\)*"; then + # class is not in CLASSPATH, so prepend dir of class to CLASSPATH + if [ -z "${CLASSPATH}" ] ; then + export CLASSPATH=$CLASSBASE + else + export CLASSPATH=$CLASSBASE:$CLASSPATH + fi + fi + + shift + /usr/bin/java $FQCLASS "$@" + +javaclassname.c:: + + /* javaclassname.c + * + * Extracts the class name from a Java class file; intended for use in a Java + * wrapper of the type supported by the binfmt_misc option in the Linux kernel. + * + * Copyright (C) 1999 Colin J. Watson . + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ + + #include + #include + #include + #include + + /* From Sun's Java VM Specification, as tag entries in the constant pool. */ + + #define CP_UTF8 1 + #define CP_INTEGER 3 + #define CP_FLOAT 4 + #define CP_LONG 5 + #define CP_DOUBLE 6 + #define CP_CLASS 7 + #define CP_STRING 8 + #define CP_FIELDREF 9 + #define CP_METHODREF 10 + #define CP_INTERFACEMETHODREF 11 + #define CP_NAMEANDTYPE 12 + #define CP_METHODHANDLE 15 + #define CP_METHODTYPE 16 + #define CP_INVOKEDYNAMIC 18 + + /* Define some commonly used error messages */ + + #define seek_error() error("%s: Cannot seek\n", program) + #define corrupt_error() error("%s: Class file corrupt\n", program) + #define eof_error() error("%s: Unexpected end of file\n", program) + #define utf8_error() error("%s: Only ASCII 1-255 supported\n", program); + + char *program; + + long *pool; + + u_int8_t read_8(FILE *classfile); + u_int16_t read_16(FILE *classfile); + void skip_constant(FILE *classfile, u_int16_t *cur); + void error(const char *format, ...); + int main(int argc, char **argv); + + /* Reads in an unsigned 8-bit integer. */ + u_int8_t read_8(FILE *classfile) + { + int b = fgetc(classfile); + if(b == EOF) + eof_error(); + return (u_int8_t)b; + } + + /* Reads in an unsigned 16-bit integer. */ + u_int16_t read_16(FILE *classfile) + { + int b1, b2; + b1 = fgetc(classfile); + if(b1 == EOF) + eof_error(); + b2 = fgetc(classfile); + if(b2 == EOF) + eof_error(); + return (u_int16_t)((b1 << 8) | b2); + } + + /* Reads in a value from the constant pool. */ + void skip_constant(FILE *classfile, u_int16_t *cur) + { + u_int16_t len; + int seekerr = 1; + pool[*cur] = ftell(classfile); + switch(read_8(classfile)) + { + case CP_UTF8: + len = read_16(classfile); + seekerr = fseek(classfile, len, SEEK_CUR); + break; + case CP_CLASS: + case CP_STRING: + case CP_METHODTYPE: + seekerr = fseek(classfile, 2, SEEK_CUR); + break; + case CP_METHODHANDLE: + seekerr = fseek(classfile, 3, SEEK_CUR); + break; + case CP_INTEGER: + case CP_FLOAT: + case CP_FIELDREF: + case CP_METHODREF: + case CP_INTERFACEMETHODREF: + case CP_NAMEANDTYPE: + case CP_INVOKEDYNAMIC: + seekerr = fseek(classfile, 4, SEEK_CUR); + break; + case CP_LONG: + case CP_DOUBLE: + seekerr = fseek(classfile, 8, SEEK_CUR); + ++(*cur); + break; + default: + corrupt_error(); + } + if(seekerr) + seek_error(); + } + + void error(const char *format, ...) + { + va_list ap; + va_start(ap, format); + vfprintf(stderr, format, ap); + va_end(ap); + exit(1); + } + + int main(int argc, char **argv) + { + FILE *classfile; + u_int16_t cp_count, i, this_class, classinfo_ptr; + u_int8_t length; + + program = argv[0]; + + if(!argv[1]) + error("%s: Missing input file\n", program); + classfile = fopen(argv[1], "rb"); + if(!classfile) + error("%s: Error opening %s\n", program, argv[1]); + + if(fseek(classfile, 8, SEEK_SET)) /* skip magic and version numbers */ + seek_error(); + cp_count = read_16(classfile); + pool = calloc(cp_count, sizeof(long)); + if(!pool) + error("%s: Out of memory for constant pool\n", program); + + for(i = 1; i < cp_count; ++i) + skip_constant(classfile, &i); + if(fseek(classfile, 2, SEEK_CUR)) /* skip access flags */ + seek_error(); + + this_class = read_16(classfile); + if(this_class < 1 || this_class >= cp_count) + corrupt_error(); + if(!pool[this_class] || pool[this_class] == -1) + corrupt_error(); + if(fseek(classfile, pool[this_class] + 1, SEEK_SET)) + seek_error(); + + classinfo_ptr = read_16(classfile); + if(classinfo_ptr < 1 || classinfo_ptr >= cp_count) + corrupt_error(); + if(!pool[classinfo_ptr] || pool[classinfo_ptr] == -1) + corrupt_error(); + if(fseek(classfile, pool[classinfo_ptr] + 1, SEEK_SET)) + seek_error(); + + length = read_16(classfile); + for(i = 0; i < length; ++i) + { + u_int8_t x = read_8(classfile); + if((x & 0x80) || !x) + { + if((x & 0xE0) == 0xC0) + { + u_int8_t y = read_8(classfile); + if((y & 0xC0) == 0x80) + { + int c = ((x & 0x1f) << 6) + (y & 0x3f); + if(c) putchar(c); + else utf8_error(); + } + else utf8_error(); + } + else utf8_error(); + } + else if(x == '/') putchar('.'); + else putchar(x); + } + putchar('\n'); + free(pool); + fclose(classfile); + return 0; + } + +jarwrapper:: + + #!/bin/bash + # /usr/local/java/bin/jarwrapper - the wrapper for binfmt_misc/jar + + java -jar $1 + + +Now simply ``chmod +x`` the ``.class``, ``.jar`` and/or ``.html`` files you +want to execute. + +To add a Java program to your path best put a symbolic link to the main +.class file into /usr/bin (or another place you like) omitting the .class +extension. The directory containing the original .class file will be +added to your CLASSPATH during execution. + + +To test your new setup, enter in the following simple Java app, and name +it "HelloWorld.java":: + + class HelloWorld { + public static void main(String args[]) { + System.out.println("Hello World!"); + } + } + +Now compile the application with:: + + javac HelloWorld.java + +Set the executable permissions of the binary file, with:: + + chmod 755 HelloWorld.class + +And then execute it:: + + ./HelloWorld.class + + +To execute Java Jar files, simple chmod the ``*.jar`` files to include +the execution bit, then just do:: + + ./Application.jar + + +To execute Java Applets, simple chmod the ``*.html`` files to include +the execution bit, then just do:: + + ./Applet.html + + +originally by Brian A. Lantz, brian@lantz.com +heavily edited for binfmt_misc by Richard Günther +new scripts by Colin J. Watson +added executable Jar file support by Kurt Huwig diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst new file mode 100644 index 000000000000..b0804273b6e3 --- /dev/null +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -0,0 +1,4577 @@ +Kernel Parameters +~~~~~~~~~~~~~~~~~ + +The following is a consolidated list of the kernel parameters as +implemented by the __setup(), core_param() and module_param() macros +and sorted into English Dictionary order (defined as ignoring all +punctuation and sorting digits before letters in a case insensitive +manner), and with descriptions where known. + +The kernel parses parameters from the kernel command line up to "--"; +if it doesn't recognize a parameter and it doesn't contain a '.', the +parameter gets passed to init: parameters with '=' go into init's +environment, others are passed as command line arguments to init. +Everything after "--" is passed as an argument to init. + +Module parameters can be specified in two ways: via the kernel command +line with a module name prefix, or via modprobe, e.g.:: + + (kernel command line) usbcore.blinkenlights=1 + (modprobe command line) modprobe usbcore blinkenlights=1 + +Parameters for modules which are built into the kernel need to be +specified on the kernel command line. modprobe looks through the +kernel command line (/proc/cmdline) and collects module parameters +when it loads a module, so the kernel command line can be used for +loadable modules too. + +Hyphens (dashes) and underscores are equivalent in parameter names, so:: + + log_buf_len=1M print-fatal-signals=1 + +can also be entered as:: + + log-buf-len=1M print_fatal_signals=1 + +Double-quotes can be used to protect spaces in values, e.g.:: + + param="spaces in here" + +cpu lists: +---------- + +Some kernel parameters take a list of CPUs as a value, e.g. isolcpus, +nohz_full, irqaffinity, rcu_nocbs. The format of this list is: + + ,..., + +or + + - + (must be a positive range in ascending order) + +or a mixture + +,...,- + +Note that for the special case of a range one can split the range into equal +sized groups and for each group use some amount from the beginning of that +group: + + -cpu number>:/ + +For example one can add to the command line following parameter: + + isolcpus=1,2,10-20,100-2000:2/25 + +where the final item represents CPUs 100,101,125,126,150,151,... + + + +This document may not be entirely up to date and comprehensive. The command +"modinfo -p ${modulename}" shows a current list of all parameters of a loadable +module. Loadable modules, after being loaded into the running kernel, also +reveal their parameters in /sys/module/${modulename}/parameters/. Some of these +parameters may be changed at runtime by the command +``echo -n ${value} > /sys/module/${modulename}/parameters/${parm}``. + +The parameters listed below are only valid if certain kernel build options were +enabled and if respective hardware is present. The text in square brackets at +the beginning of each description states the restrictions within which a +parameter is applicable:: + + ACPI ACPI support is enabled. + AGP AGP (Accelerated Graphics Port) is enabled. + ALSA ALSA sound support is enabled. + APIC APIC support is enabled. + APM Advanced Power Management support is enabled. + ARM ARM architecture is enabled. + AVR32 AVR32 architecture is enabled. + AX25 Appropriate AX.25 support is enabled. + BLACKFIN Blackfin architecture is enabled. + CLK Common clock infrastructure is enabled. + CMA Contiguous Memory Area support is enabled. + DRM Direct Rendering Management support is enabled. + DYNAMIC_DEBUG Build in debug messages and enable them at runtime + EDD BIOS Enhanced Disk Drive Services (EDD) is enabled + EFI EFI Partitioning (GPT) is enabled + EIDE EIDE/ATAPI support is enabled. + EVM Extended Verification Module + FB The frame buffer device is enabled. + FTRACE Function tracing enabled. + GCOV GCOV profiling is enabled. + HW Appropriate hardware is enabled. + IA-64 IA-64 architecture is enabled. + IMA Integrity measurement architecture is enabled. + IOSCHED More than one I/O scheduler is enabled. + IP_PNP IP DHCP, BOOTP, or RARP is enabled. + IPV6 IPv6 support is enabled. + ISAPNP ISA PnP code is enabled. + ISDN Appropriate ISDN support is enabled. + JOY Appropriate joystick support is enabled. + KGDB Kernel debugger support is enabled. + KVM Kernel Virtual Machine support is enabled. + LIBATA Libata driver is enabled + LP Printer support is enabled. + LOOP Loopback device support is enabled. + M68k M68k architecture is enabled. + These options have more detailed description inside of + Documentation/m68k/kernel-options.txt. + MDA MDA console support is enabled. + MIPS MIPS architecture is enabled. + MOUSE Appropriate mouse support is enabled. + MSI Message Signaled Interrupts (PCI). + MTD MTD (Memory Technology Device) support is enabled. + NET Appropriate network support is enabled. + NUMA NUMA support is enabled. + NFS Appropriate NFS support is enabled. + OSS OSS sound support is enabled. + PV_OPS A paravirtualized kernel is enabled. + PARIDE The ParIDE (parallel port IDE) subsystem is enabled. + PARISC The PA-RISC architecture is enabled. + PCI PCI bus support is enabled. + PCIE PCI Express support is enabled. + PCMCIA The PCMCIA subsystem is enabled. + PNP Plug & Play support is enabled. + PPC PowerPC architecture is enabled. + PPT Parallel port support is enabled. + PS2 Appropriate PS/2 support is enabled. + RAM RAM disk support is enabled. + S390 S390 architecture is enabled. + SCSI Appropriate SCSI support is enabled. + A lot of drivers have their options described inside + the Documentation/scsi/ sub-directory. + SECURITY Different security models are enabled. + SELINUX SELinux support is enabled. + APPARMOR AppArmor support is enabled. + SERIAL Serial support is enabled. + SH SuperH architecture is enabled. + SMP The kernel is an SMP kernel. + SPARC Sparc architecture is enabled. + SWSUSP Software suspend (hibernation) is enabled. + SUSPEND System suspend states are enabled. + TPM TPM drivers are enabled. + TS Appropriate touchscreen support is enabled. + UMS USB Mass Storage support is enabled. + USB USB support is enabled. + USBHID USB Human Interface Device support is enabled. + V4L Video For Linux support is enabled. + VMMIO Driver for memory mapped virtio devices is enabled. + VGA The VGA console has been enabled. + VT Virtual terminal support is enabled. + WDT Watchdog support is enabled. + XT IBM PC/XT MFM hard disk support is enabled. + X86-32 X86-32, aka i386 architecture is enabled. + X86-64 X86-64 architecture is enabled. + More X86-64 boot options can be found in + Documentation/x86/x86_64/boot-options.txt . + X86 Either 32-bit or 64-bit x86 (same as X86-32+X86-64) + X86_UV SGI UV support is enabled. + XEN Xen support is enabled + +In addition, the following text indicates that the option:: + + BUGS= Relates to possible processor bugs on the said processor. + KNL Is a kernel start-up parameter. + BOOT Is a boot loader parameter. + +Parameters denoted with BOOT are actually interpreted by the boot +loader, and have no meaning to the kernel directly. +Do not modify the syntax of boot loader parameters without extreme +need or coordination with . + +There are also arch-specific kernel-parameters not documented here. +See for example . + +Note that ALL kernel parameters listed below are CASE SENSITIVE, and that +a trailing = on the name of any parameter states that that parameter will +be entered as an environment variable, whereas its absence indicates that +it will appear as a kernel argument readable via /proc/cmdline by programs +running once the system is up. + +The number of kernel parameters is not limited, but the length of the +complete command line (parameters including spaces etc.) is limited to +a fixed number of characters. This limit depends on the architecture +and is between 256 and 4096 characters. It is defined in the file +./include/asm/setup.h as COMMAND_LINE_SIZE. + +Finally, the [KMG] suffix is commonly described after a number of kernel +parameter values. These 'K', 'M', and 'G' letters represent the _binary_ +multipliers 'Kilo', 'Mega', and 'Giga', equalling 2^10, 2^20, and 2^30 +bytes respectively. Such letter suffixes can also be entirely omitted:: + + + acpi= [HW,ACPI,X86,ARM64] + Advanced Configuration and Power Interface + Format: { force | on | off | strict | noirq | rsdt | + copy_dsdt } + force -- enable ACPI if default was off + on -- enable ACPI but allow fallback to DT [arm64] + off -- disable ACPI if default was on + noirq -- do not use ACPI for IRQ routing + strict -- Be less tolerant of platforms that are not + strictly ACPI specification compliant. + rsdt -- prefer RSDT over (default) XSDT + copy_dsdt -- copy DSDT to memory + For ARM64, ONLY "acpi=off", "acpi=on" or "acpi=force" + are available + + See also Documentation/power/runtime_pm.txt, pci=noacpi + + acpi_apic_instance= [ACPI, IOAPIC] + Format: + 2: use 2nd APIC table, if available + 1,0: use 1st APIC table + default: 0 + + acpi_backlight= [HW,ACPI] + acpi_backlight=vendor + acpi_backlight=video + If set to vendor, prefer vendor specific driver + (e.g. thinkpad_acpi, sony_acpi, etc.) instead + of the ACPI video.ko driver. + + acpi_force_32bit_fadt_addr + force FADT to use 32 bit addresses rather than the + 64 bit X_* addresses. Some firmware have broken 64 + bit addresses for force ACPI ignore these and use + the older legacy 32 bit addresses. + + acpica_no_return_repair [HW, ACPI] + Disable AML predefined validation mechanism + This mechanism can repair the evaluation result to make + the return objects more ACPI specification compliant. + This option is useful for developers to identify the + root cause of an AML interpreter issue when the issue + has something to do with the repair mechanism. + + acpi.debug_layer= [HW,ACPI,ACPI_DEBUG] + acpi.debug_level= [HW,ACPI,ACPI_DEBUG] + Format: + CONFIG_ACPI_DEBUG must be enabled to produce any ACPI + debug output. Bits in debug_layer correspond to a + _COMPONENT in an ACPI source file, e.g., + #define _COMPONENT ACPI_PCI_COMPONENT + Bits in debug_level correspond to a level in + ACPI_DEBUG_PRINT statements, e.g., + ACPI_DEBUG_PRINT((ACPI_DB_INFO, ... + The debug_level mask defaults to "info". See + Documentation/acpi/debug.txt for more information about + debug layers and levels. + + Enable processor driver info messages: + acpi.debug_layer=0x20000000 + Enable PCI/PCI interrupt routing info messages: + acpi.debug_layer=0x400000 + Enable AML "Debug" output, i.e., stores to the Debug + object while interpreting AML: + acpi.debug_layer=0xffffffff acpi.debug_level=0x2 + Enable all messages related to ACPI hardware: + acpi.debug_layer=0x2 acpi.debug_level=0xffffffff + + Some values produce so much output that the system is + unusable. The "log_buf_len" parameter may be useful + if you need to capture more output. + + acpi_enforce_resources= [ACPI] + { strict | lax | no } + Check for resource conflicts between native drivers + and ACPI OperationRegions (SystemIO and SystemMemory + only). IO ports and memory declared in ACPI might be + used by the ACPI subsystem in arbitrary AML code and + can interfere with legacy drivers. + strict (default): access to resources claimed by ACPI + is denied; legacy drivers trying to access reserved + resources will fail to bind to device using them. + lax: access to resources claimed by ACPI is allowed; + legacy drivers trying to access reserved resources + will bind successfully but a warning message is logged. + no: ACPI OperationRegions are not marked as reserved, + no further checks are performed. + + acpi_force_table_verification [HW,ACPI] + Enable table checksum verification during early stage. + By default, this is disabled due to x86 early mapping + size limitation. + + acpi_irq_balance [HW,ACPI] + ACPI will balance active IRQs + default in APIC mode + + acpi_irq_nobalance [HW,ACPI] + ACPI will not move active IRQs (default) + default in PIC mode + + acpi_irq_isa= [HW,ACPI] If irq_balance, mark listed IRQs used by ISA + Format: ,... + + acpi_irq_pci= [HW,ACPI] If irq_balance, clear listed IRQs for + use by PCI + Format: ,... + + acpi_no_auto_serialize [HW,ACPI] + Disable auto-serialization of AML methods + AML control methods that contain the opcodes to create + named objects will be marked as "Serialized" by the + auto-serialization feature. + This feature is enabled by default. + This option allows to turn off the feature. + + acpi_no_memhotplug [ACPI] Disable memory hotplug. Useful for kdump + kernels. + + acpi_no_static_ssdt [HW,ACPI] + Disable installation of static SSDTs at early boot time + By default, SSDTs contained in the RSDT/XSDT will be + installed automatically and they will appear under + /sys/firmware/acpi/tables. + This option turns off this feature. + Note that specifying this option does not affect + dynamic table installation which will install SSDT + tables to /sys/firmware/acpi/tables/dynamic. + + acpi_rsdp= [ACPI,EFI,KEXEC] + Pass the RSDP address to the kernel, mostly used + on machines running EFI runtime service to boot the + second kernel for kdump. + + acpi_os_name= [HW,ACPI] Tell ACPI BIOS the name of the OS + Format: To spoof as Windows 98: ="Microsoft Windows" + + acpi_rev_override [ACPI] Override the _REV object to return 5 (instead + of 2 which is mandated by ACPI 6) as the supported ACPI + specification revision (when using this switch, it may + be necessary to carry out a cold reboot _twice_ in a + row to make it take effect on the platform firmware). + + acpi_osi= [HW,ACPI] Modify list of supported OS interface strings + acpi_osi="string1" # add string1 + acpi_osi="!string2" # remove string2 + acpi_osi=!* # remove all strings + acpi_osi=! # disable all built-in OS vendor + strings + acpi_osi=!! # enable all built-in OS vendor + strings + acpi_osi= # disable all strings + + 'acpi_osi=!' can be used in combination with single or + multiple 'acpi_osi="string1"' to support specific OS + vendor string(s). Note that such command can only + affect the default state of the OS vendor strings, thus + it cannot affect the default state of the feature group + strings and the current state of the OS vendor strings, + specifying it multiple times through kernel command line + is meaningless. This command is useful when one do not + care about the state of the feature group strings which + should be controlled by the OSPM. + Examples: + 1. 'acpi_osi=! acpi_osi="Windows 2000"' is equivalent + to 'acpi_osi="Windows 2000" acpi_osi=!', they all + can make '_OSI("Windows 2000")' TRUE. + + 'acpi_osi=' cannot be used in combination with other + 'acpi_osi=' command lines, the _OSI method will not + exist in the ACPI namespace. NOTE that such command can + only affect the _OSI support state, thus specifying it + multiple times through kernel command line is also + meaningless. + Examples: + 1. 'acpi_osi=' can make 'CondRefOf(_OSI, Local1)' + FALSE. + + 'acpi_osi=!*' can be used in combination with single or + multiple 'acpi_osi="string1"' to support specific + string(s). Note that such command can affect the + current state of both the OS vendor strings and the + feature group strings, thus specifying it multiple times + through kernel command line is meaningful. But it may + still not able to affect the final state of a string if + there are quirks related to this string. This command + is useful when one want to control the state of the + feature group strings to debug BIOS issues related to + the OSPM features. + Examples: + 1. 'acpi_osi="Module Device" acpi_osi=!*' can make + '_OSI("Module Device")' FALSE. + 2. 'acpi_osi=!* acpi_osi="Module Device"' can make + '_OSI("Module Device")' TRUE. + 3. 'acpi_osi=! acpi_osi=!* acpi_osi="Windows 2000"' is + equivalent to + 'acpi_osi=!* acpi_osi=! acpi_osi="Windows 2000"' + and + 'acpi_osi=!* acpi_osi="Windows 2000" acpi_osi=!', + they all will make '_OSI("Windows 2000")' TRUE. + + acpi_pm_good [X86] + Override the pmtimer bug detection: force the kernel + to assume that this machine's pmtimer latches its value + and always returns good values. + + acpi_sci= [HW,ACPI] ACPI System Control Interrupt trigger mode + Format: { level | edge | high | low } + + acpi_skip_timer_override [HW,ACPI] + Recognize and ignore IRQ0/pin2 Interrupt Override. + For broken nForce2 BIOS resulting in XT-PIC timer. + + acpi_sleep= [HW,ACPI] Sleep options + Format: { s3_bios, s3_mode, s3_beep, s4_nohwsig, + old_ordering, nonvs, sci_force_enable } + See Documentation/power/video.txt for information on + s3_bios and s3_mode. + s3_beep is for debugging; it makes the PC's speaker beep + as soon as the kernel's real-mode entry point is called. + s4_nohwsig prevents ACPI hardware signature from being + used during resume from hibernation. + old_ordering causes the ACPI 1.0 ordering of the _PTS + control method, with respect to putting devices into + low power states, to be enforced (the ACPI 2.0 ordering + of _PTS is used by default). + nonvs prevents the kernel from saving/restoring the + ACPI NVS memory during suspend/hibernation and resume. + sci_force_enable causes the kernel to set SCI_EN directly + on resume from S1/S3 (which is against the ACPI spec, + but some broken systems don't work without it). + + acpi_use_timer_override [HW,ACPI] + Use timer override. For some broken Nvidia NF5 boards + that require a timer override, but don't have HPET + + add_efi_memmap [EFI; X86] Include EFI memory map in + kernel's map of available physical RAM. + + agp= [AGP] + { off | try_unsupported } + off: disable AGP support + try_unsupported: try to drive unsupported chipsets + (may crash computer or cause data corruption) + + ALSA [HW,ALSA] + See Documentation/sound/alsa/alsa-parameters.txt + + alignment= [KNL,ARM] + Allow the default userspace alignment fault handler + behaviour to be specified. Bit 0 enables warnings, + bit 1 enables fixups, and bit 2 sends a segfault. + + align_va_addr= [X86-64] + Align virtual addresses by clearing slice [14:12] when + allocating a VMA at process creation time. This option + gives you up to 3% performance improvement on AMD F15h + machines (where it is enabled by default) for a + CPU-intensive style benchmark, and it can vary highly in + a microbenchmark depending on workload and compiler. + + 32: only for 32-bit processes + 64: only for 64-bit processes + on: enable for both 32- and 64-bit processes + off: disable for both 32- and 64-bit processes + + alloc_snapshot [FTRACE] + Allocate the ftrace snapshot buffer on boot up when the + main buffer is allocated. This is handy if debugging + and you need to use tracing_snapshot() on boot up, and + do not want to use tracing_snapshot_alloc() as it needs + to be done where GFP_KERNEL allocations are allowed. + + amd_iommu= [HW,X86-64] + Pass parameters to the AMD IOMMU driver in the system. + Possible values are: + fullflush - enable flushing of IO/TLB entries when + they are unmapped. Otherwise they are + flushed before they will be reused, which + is a lot of faster + off - do not initialize any AMD IOMMU found in + the system + force_isolation - Force device isolation for all + devices. The IOMMU driver is not + allowed anymore to lift isolation + requirements as needed. This option + does not override iommu=pt + + amd_iommu_dump= [HW,X86-64] + Enable AMD IOMMU driver option to dump the ACPI table + for AMD IOMMU. With this option enabled, AMD IOMMU + driver will print ACPI tables for AMD IOMMU during + IOMMU initialization. + + amd_iommu_intr= [HW,X86-64] + Specifies one of the following AMD IOMMU interrupt + remapping modes: + legacy - Use legacy interrupt remapping mode. + vapic - Use virtual APIC mode, which allows IOMMU + to inject interrupts directly into guest. + This mode requires kvm-amd.avic=1. + (Default when IOMMU HW support is present.) + + amijoy.map= [HW,JOY] Amiga joystick support + Map of devices attached to JOY0DAT and JOY1DAT + Format: , + See also Documentation/input/joystick.txt + + analog.map= [HW,JOY] Analog joystick and gamepad support + Specifies type or capabilities of an analog joystick + connected to one of 16 gameports + Format: ,,.. + + apc= [HW,SPARC] + Power management functions (SPARCstation-4/5 + deriv.) + Format: noidle + Disable APC CPU standby support. SPARCstation-Fox does + not play well with APC CPU idle - disable it if you have + APC and your system crashes randomly. + + apic= [APIC,X86-32] Advanced Programmable Interrupt Controller + Change the output verbosity whilst booting + Format: { quiet (default) | verbose | debug } + Change the amount of debugging information output + when initialising the APIC and IO-APIC components. + + apic_extnmi= [APIC,X86] External NMI delivery setting + Format: { bsp (default) | all | none } + bsp: External NMI is delivered only to CPU 0 + all: External NMIs are broadcast to all CPUs as a + backup of CPU 0 + none: External NMI is masked for all CPUs. This is + useful so that a dump capture kernel won't be + shot down by NMI + + autoconf= [IPV6] + See Documentation/networking/ipv6.txt. + + show_lapic= [APIC,X86] Advanced Programmable Interrupt Controller + Limit apic dumping. The parameter defines the maximal + number of local apics being dumped. Also it is possible + to set it to "all" by meaning -- no limit here. + Format: { 1 (default) | 2 | ... | all }. + The parameter valid if only apic=debug or + apic=verbose is specified. + Example: apic=debug show_lapic=all + + apm= [APM] Advanced Power Management + See header of arch/x86/kernel/apm_32.c. + + arcrimi= [HW,NET] ARCnet - "RIM I" (entirely mem-mapped) cards + Format: ,, + + ataflop= [HW,M68k] + + atarimouse= [HW,MOUSE] Atari Mouse + + atkbd.extra= [HW] Enable extra LEDs and keys on IBM RapidAccess, + EzKey and similar keyboards + + atkbd.reset= [HW] Reset keyboard during initialization + + atkbd.set= [HW] Select keyboard code set + Format: (2 = AT (default), 3 = PS/2) + + atkbd.scroll= [HW] Enable scroll wheel on MS Office and similar + keyboards + + atkbd.softraw= [HW] Choose between synthetic and real raw mode + Format: (0 = real, 1 = synthetic (default)) + + atkbd.softrepeat= [HW] + Use software keyboard repeat + + audit= [KNL] Enable the audit sub-system + Format: { "0" | "1" } (0 = disabled, 1 = enabled) + 0 - kernel audit is disabled and can not be enabled + until the next reboot + unset - kernel audit is initialized but disabled and + will be fully enabled by the userspace auditd. + 1 - kernel audit is initialized and partially enabled, + storing at most audit_backlog_limit messages in + RAM until it is fully enabled by the userspace + auditd. + Default: unset + + audit_backlog_limit= [KNL] Set the audit queue size limit. + Format: (must be >=0) + Default: 64 + + bau= [X86_UV] Enable the BAU on SGI UV. The default + behavior is to disable the BAU (i.e. bau=0). + Format: { "0" | "1" } + 0 - Disable the BAU. + 1 - Enable the BAU. + unset - Disable the BAU. + + baycom_epp= [HW,AX25] + Format: , + + baycom_par= [HW,AX25] BayCom Parallel Port AX.25 Modem + Format: , + See header of drivers/net/hamradio/baycom_par.c. + + baycom_ser_fdx= [HW,AX25] + BayCom Serial Port AX.25 Modem (Full Duplex Mode) + Format: ,,[,] + See header of drivers/net/hamradio/baycom_ser_fdx.c. + + baycom_ser_hdx= [HW,AX25] + BayCom Serial Port AX.25 Modem (Half Duplex Mode) + Format: ,, + See header of drivers/net/hamradio/baycom_ser_hdx.c. + + blkdevparts= Manual partition parsing of block device(s) for + embedded devices based on command line input. + See Documentation/block/cmdline-partition.txt + + boot_delay= Milliseconds to delay each printk during boot. + Values larger than 10 seconds (10000) are changed to + no delay (0). + Format: integer + + bootmem_debug [KNL] Enable bootmem allocator debug messages. + + bert_disable [ACPI] + Disable BERT OS support on buggy BIOSes. + + bttv.card= [HW,V4L] bttv (bt848 + bt878 based grabber cards) + bttv.radio= Most important insmod options are available as + kernel args too. + bttv.pll= See Documentation/video4linux/bttv/Insmod-options + bttv.tuner= + + bulk_remove=off [PPC] This parameter disables the use of the pSeries + firmware feature for flushing multiple hpte entries + at a time. + + c101= [NET] Moxa C101 synchronous serial card + + cachesize= [BUGS=X86-32] Override level 2 CPU cache size detection. + Sometimes CPU hardware bugs make them report the cache + size incorrectly. The kernel will attempt work arounds + to fix known problems, but for some CPUs it is not + possible to determine what the correct size should be. + This option provides an override for these situations. + + ca_keys= [KEYS] This parameter identifies a specific key(s) on + the system trusted keyring to be used for certificate + trust validation. + format: { id: | builtin } + + cca= [MIPS] Override the kernel pages' cache coherency + algorithm. Accepted values range from 0 to 7 + inclusive. See arch/mips/include/asm/pgtable-bits.h + for platform specific values (SB1, Loongson3 and + others). + + ccw_timeout_log [S390] + See Documentation/s390/CommonIO for details. + + cgroup_disable= [KNL] Disable a particular controller + Format: {name of the controller(s) to disable} + The effects of cgroup_disable=foo are: + - foo isn't auto-mounted if you mount all cgroups in + a single hierarchy + - foo isn't visible as an individually mountable + subsystem + {Currently only "memory" controller deal with this and + cut the overhead, others just disable the usage. So + only cgroup_disable=memory is actually worthy} + + cgroup_no_v1= [KNL] Disable one, multiple, all cgroup controllers in v1 + Format: { controller[,controller...] | "all" } + Like cgroup_disable, but only applies to cgroup v1; + the blacklisted controllers remain available in cgroup2. + + cgroup.memory= [KNL] Pass options to the cgroup memory controller. + Format: + nosocket -- Disable socket memory accounting. + nokmem -- Disable kernel memory accounting. + + checkreqprot [SELINUX] Set initial checkreqprot flag value. + Format: { "0" | "1" } + See security/selinux/Kconfig help text. + 0 -- check protection applied by kernel (includes + any implied execute protection). + 1 -- check protection requested by application. + Default value is set via a kernel config option. + Value can be changed at runtime via + /selinux/checkreqprot. + + cio_ignore= [S390] + See Documentation/s390/CommonIO for details. + clk_ignore_unused + [CLK] + Prevents the clock framework from automatically gating + clocks that have not been explicitly enabled by a Linux + device driver but are enabled in hardware at reset or + by the bootloader/firmware. Note that this does not + force such clocks to be always-on nor does it reserve + those clocks in any way. This parameter is useful for + debug and development, but should not be needed on a + platform with proper driver support. For more + information, see Documentation/clk.txt. + + clock= [BUGS=X86-32, HW] gettimeofday clocksource override. + [Deprecated] + Forces specified clocksource (if available) to be used + when calculating gettimeofday(). If specified + clocksource is not available, it defaults to PIT. + Format: { pit | tsc | cyclone | pmtmr } + + clocksource= Override the default clocksource + Format: + Override the default clocksource and use the clocksource + with the name specified. + Some clocksource names to choose from, depending on + the platform: + [all] jiffies (this is the base, fallback clocksource) + [ACPI] acpi_pm + [ARM] imx_timer1,OSTS,netx_timer,mpu_timer2, + pxa_timer,timer3,32k_counter,timer0_1 + [AVR32] avr32 + [X86-32] pit,hpet,tsc; + scx200_hrt on Geode; cyclone on IBM x440 + [MIPS] MIPS + [PARISC] cr16 + [S390] tod + [SH] SuperH + [SPARC64] tick + [X86-64] hpet,tsc + + clocksource.arm_arch_timer.evtstrm= + [ARM,ARM64] + Format: + Enable/disable the eventstream feature of the ARM + architected timer so that code using WFE-based polling + loops can be debugged more effectively on production + systems. + + clocksource.arm_arch_timer.fsl-a008585= + [ARM64] + Format: + Enable/disable the workaround of Freescale/NXP + erratum A-008585. This can be useful for KVM + guests, if the guest device tree doesn't show the + erratum. If unspecified, the workaround is + enabled based on the device tree. + + clearcpuid=BITNUM [X86] + Disable CPUID feature X for the kernel. See + arch/x86/include/asm/cpufeatures.h for the valid bit + numbers. Note the Linux specific bits are not necessarily + stable over kernel options, but the vendor specific + ones should be. + Also note that user programs calling CPUID directly + or using the feature without checking anything + will still see it. This just prevents it from + being used by the kernel or shown in /proc/cpuinfo. + Also note the kernel might malfunction if you disable + some critical bits. + + cma=nn[MG]@[start[MG][-end[MG]]] + [ARM,X86,KNL] + Sets the size of kernel global memory area for + contiguous memory allocations and optionally the + placement constraint by the physical address range of + memory allocations. A value of 0 disables CMA + altogether. For more information, see + include/linux/dma-contiguous.h + + cmo_free_hint= [PPC] Format: { yes | no } + Specify whether pages are marked as being inactive + when they are freed. This is used in CMO environments + to determine OS memory pressure for page stealing by + a hypervisor. + Default: yes + + coherent_pool=nn[KMG] [ARM,KNL] + Sets the size of memory pool for coherent, atomic dma + allocations, by default set to 256K. + + code_bytes [X86] How many bytes of object code to print + in an oops report. + Range: 0 - 8192 + Default: 64 + + com20020= [HW,NET] ARCnet - COM20020 chipset + Format: + [,[,[,[,[,]]]]] + + com90io= [HW,NET] ARCnet - COM90xx chipset (IO-mapped buffers) + Format: [,] + + com90xx= [HW,NET] + ARCnet - COM90xx chipset (memory-mapped buffers) + Format: [,[,]] + + condev= [HW,S390] console device + conmode= + + console= [KNL] Output console device and options. + + tty Use the virtual console device . + + ttyS[,options] + ttyUSB0[,options] + Use the specified serial port. The options are of + the form "bbbbpnf", where "bbbb" is the baud rate, + "p" is parity ("n", "o", or "e"), "n" is number of + bits, and "f" is flow control ("r" for RTS or + omit it). Default is "9600n8". + + See Documentation/serial-console.txt for more + information. See + Documentation/networking/netconsole.txt for an + alternative. + + uart[8250],io,[,options] + uart[8250],mmio,[,options] + uart[8250],mmio16,[,options] + uart[8250],mmio32,[,options] + uart[8250],0x[,options] + Start an early, polled-mode console on the 8250/16550 + UART at the specified I/O port or MMIO address, + switching to the matching ttyS device later. + MMIO inter-register address stride is either 8-bit + (mmio), 16-bit (mmio16), or 32-bit (mmio32). + If none of [io|mmio|mmio16|mmio32], is assumed + to be equivalent to 'mmio'. 'options' are specified in + the same format described for ttyS above; if unspecified, + the h/w is not re-initialized. + + hvc Use the hypervisor console device . This is for + both Xen and PowerPC hypervisors. + + If the device connected to the port is not a TTY but a braille + device, prepend "brl," before the device type, for instance + console=brl,ttyS0 + For now, only VisioBraille is supported. + + consoleblank= [KNL] The console blank (screen saver) timeout in + seconds. Defaults to 10*60 = 10mins. A value of 0 + disables the blank timer. + + coredump_filter= + [KNL] Change the default value for + /proc//coredump_filter. + See also Documentation/filesystems/proc.txt. + + cpuidle.off=1 [CPU_IDLE] + disable the cpuidle sub-system + + cpu_init_udelay=N + [X86] Delay for N microsec between assert and de-assert + of APIC INIT to start processors. This delay occurs + on every CPU online, such as boot, and resume from suspend. + Default: 10000 + + cpcihp_generic= [HW,PCI] Generic port I/O CompactPCI driver + Format: + ,,,[,] + + crashkernel=size[KMG][@offset[KMG]] + [KNL] Using kexec, Linux can switch to a 'crash kernel' + upon panic. This parameter reserves the physical + memory region [offset, offset + size] for that kernel + image. If '@offset' is omitted, then a suitable offset + is selected automatically. Check + Documentation/kdump/kdump.txt for further details. + + crashkernel=range1:size1[,range2:size2,...][@offset] + [KNL] Same as above, but depends on the memory + in the running system. The syntax of range is + start-[end] where start and end are both + a memory unit (amount[KMG]). See also + Documentation/kdump/kdump.txt for an example. + + crashkernel=size[KMG],high + [KNL, x86_64] range could be above 4G. Allow kernel + to allocate physical memory region from top, so could + be above 4G if system have more than 4G ram installed. + Otherwise memory region will be allocated below 4G, if + available. + It will be ignored if crashkernel=X is specified. + crashkernel=size[KMG],low + [KNL, x86_64] range under 4G. When crashkernel=X,high + is passed, kernel could allocate physical memory region + above 4G, that cause second kernel crash on system + that require some amount of low memory, e.g. swiotlb + requires at least 64M+32K low memory, also enough extra + low memory is needed to make sure DMA buffers for 32-bit + devices won't run out. Kernel would try to allocate at + at least 256M below 4G automatically. + This one let user to specify own low range under 4G + for second kernel instead. + 0: to disable low allocation. + It will be ignored when crashkernel=X,high is not used + or memory reserved is below 4G. + + cryptomgr.notests + [KNL] Disable crypto self-tests + + cs89x0_dma= [HW,NET] + Format: + + cs89x0_media= [HW,NET] + Format: { rj45 | aui | bnc } + + dasd= [HW,NET] + See header of drivers/s390/block/dasd_devmap.c. + + db9.dev[2|3]= [HW,JOY] Multisystem joystick support via parallel port + (one device per port) + Format: , + See also Documentation/input/joystick-parport.txt + + ddebug_query= [KNL,DYNAMIC_DEBUG] Enable debug messages at early boot + time. See Documentation/dynamic-debug-howto.txt for + details. Deprecated, see dyndbg. + + debug [KNL] Enable kernel debugging (events log level). + + debug_locks_verbose= + [KNL] verbose self-tests + Format=<0|1> + Print debugging info while doing the locking API + self-tests. + We default to 0 (no extra messages), setting it to + 1 will print _a lot_ more information - normally + only useful to kernel developers. + + debug_objects [KNL] Enable object debugging + + no_debug_objects + [KNL] Disable object debugging + + debug_guardpage_minorder= + [KNL] When CONFIG_DEBUG_PAGEALLOC is set, this + parameter allows control of the order of pages that will + be intentionally kept free (and hence protected) by the + buddy allocator. Bigger value increase the probability + of catching random memory corruption, but reduce the + amount of memory for normal system use. The maximum + possible value is MAX_ORDER/2. Setting this parameter + to 1 or 2 should be enough to identify most random + memory corruption problems caused by bugs in kernel or + driver code when a CPU writes to (or reads from) a + random memory location. Note that there exists a class + of memory corruptions problems caused by buggy H/W or + F/W or by drivers badly programing DMA (basically when + memory is written at bus level and the CPU MMU is + bypassed) which are not detectable by + CONFIG_DEBUG_PAGEALLOC, hence this option will not help + tracking down these problems. + + debug_pagealloc= + [KNL] When CONFIG_DEBUG_PAGEALLOC is set, this + parameter enables the feature at boot time. In + default, it is disabled. We can avoid allocating huge + chunk of memory for debug pagealloc if we don't enable + it at boot time and the system will work mostly same + with the kernel built without CONFIG_DEBUG_PAGEALLOC. + on: enable the feature + + debugpat [X86] Enable PAT debugging + + decnet.addr= [HW,NET] + Format: [,] + See also Documentation/networking/decnet.txt. + + default_hugepagesz= + [same as hugepagesz=] The size of the default + HugeTLB page size. This is the size represented by + the legacy /proc/ hugepages APIs, used for SHM, and + default size when mounting hugetlbfs filesystems. + Defaults to the default architecture's huge page size + if not specified. + + dhash_entries= [KNL] + Set number of hash buckets for dentry cache. + + disable_1tb_segments [PPC] + Disables the use of 1TB hash page table segments. This + causes the kernel to fall back to 256MB segments which + can be useful when debugging issues that require an SLB + miss to occur. + + disable= [IPV6] + See Documentation/networking/ipv6.txt. + + disable_radix [PPC] + Disable RADIX MMU mode on POWER9 + + disable_cpu_apicid= [X86,APIC,SMP] + Format: + The number of initial APIC ID for the + corresponding CPU to be disabled at boot, + mostly used for the kdump 2nd kernel to + disable BSP to wake up multiple CPUs without + causing system reset or hang due to sending + INIT from AP to BSP. + + disable_ddw [PPC/PSERIES] + Disable Dynamic DMA Window support. Use this if + to workaround buggy firmware. + + disable_ipv6= [IPV6] + See Documentation/networking/ipv6.txt. + + disable_mtrr_cleanup [X86] + The kernel tries to adjust MTRR layout from continuous + to discrete, to make X server driver able to add WB + entry later. This parameter disables that. + + disable_mtrr_trim [X86, Intel and AMD only] + By default the kernel will trim any uncacheable + memory out of your available memory pool based on + MTRR settings. This parameter disables that behavior, + possibly causing your machine to run very slowly. + + disable_timer_pin_1 [X86] + Disable PIN 1 of APIC timer + Can be useful to work around chipset bugs. + + dis_ucode_ldr [X86] Disable the microcode loader. + + dma_debug=off If the kernel is compiled with DMA_API_DEBUG support, + this option disables the debugging code at boot. + + dma_debug_entries= + This option allows to tune the number of preallocated + entries for DMA-API debugging code. One entry is + required per DMA-API allocation. Use this if the + DMA-API debugging code disables itself because the + architectural default is too low. + + dma_debug_driver= + With this option the DMA-API debugging driver + filter feature can be enabled at boot time. Just + pass the driver to filter for as the parameter. + The filter can be disabled or changed to another + driver later using sysfs. + + drm_kms_helper.edid_firmware=[:][,[:]] + Broken monitors, graphic adapters, KVMs and EDIDless + panels may send no or incorrect EDID data sets. + This parameter allows to specify an EDID data sets + in the /lib/firmware directory that are used instead. + Generic built-in EDID data sets are used, if one of + edid/1024x768.bin, edid/1280x1024.bin, + edid/1680x1050.bin, or edid/1920x1080.bin is given + and no file with the same name exists. Details and + instructions how to build your own EDID data are + available in Documentation/EDID/HOWTO.txt. An EDID + data set will only be used for a particular connector, + if its name and a colon are prepended to the EDID + name. Each connector may use a unique EDID data + set by separating the files with a comma. An EDID + data set with no connector name will be used for + any connectors not explicitly specified. + + dscc4.setup= [NET] + + dyndbg[="val"] [KNL,DYNAMIC_DEBUG] + module.dyndbg[="val"] + Enable debug messages at boot time. See + Documentation/dynamic-debug-howto.txt for details. + + nompx [X86] Disables Intel Memory Protection Extensions. + See Documentation/x86/intel_mpx.txt for more + information about the feature. + + nopku [X86] Disable Memory Protection Keys CPU feature found + in some Intel CPUs. + + eagerfpu= [X86] + on enable eager fpu restore + off disable eager fpu restore + auto selects the default scheme, which automatically + enables eagerfpu restore for xsaveopt. + + module.async_probe [KNL] + Enable asynchronous probe on this module. + + early_ioremap_debug [KNL] + Enable debug messages in early_ioremap support. This + is useful for tracking down temporary early mappings + which are not unmapped. + + earlycon= [KNL] Output early console device and options. + + When used with no options, the early console is + determined by the stdout-path property in device + tree's chosen node. + + cdns,[,options] + Start an early, polled-mode console on a Cadence + (xuartps) serial port at the specified address. Only + supported option is baud rate. If baud rate is not + specified, the serial port must already be setup and + configured. + + uart[8250],io,[,options] + uart[8250],mmio,[,options] + uart[8250],mmio32,[,options] + uart[8250],mmio32be,[,options] + uart[8250],0x[,options] + Start an early, polled-mode console on the 8250/16550 + UART at the specified I/O port or MMIO address. + MMIO inter-register address stride is either 8-bit + (mmio) or 32-bit (mmio32 or mmio32be). + If none of [io|mmio|mmio32|mmio32be], is assumed + to be equivalent to 'mmio'. 'options' are specified + in the same format described for "console=ttyS"; if + unspecified, the h/w is not initialized. + + pl011, + pl011,mmio32, + Start an early, polled-mode console on a pl011 serial + port at the specified address. The pl011 serial port + must already be setup and configured. Options are not + yet supported. If 'mmio32' is specified, then only + the driver will use only 32-bit accessors to read/write + the device registers. + + meson, + Start an early, polled-mode console on a meson serial + port at the specified address. The serial port must + already be setup and configured. Options are not yet + supported. + + msm_serial, + Start an early, polled-mode console on an msm serial + port at the specified address. The serial port + must already be setup and configured. Options are not + yet supported. + + msm_serial_dm, + Start an early, polled-mode console on an msm serial + dm port at the specified address. The serial port + must already be setup and configured. Options are not + yet supported. + + smh Use ARM semihosting calls for early console. + + s3c2410, + s3c2412, + s3c2440, + s3c6400, + s5pv210, + exynos4210, + Use early console provided by serial driver available + on Samsung SoCs, requires selecting proper type and + a correct base address of the selected UART port. The + serial port must already be setup and configured. + Options are not yet supported. + + lpuart, + lpuart32, + Use early console provided by Freescale LP UART driver + found on Freescale Vybrid and QorIQ LS1021A processors. + A valid base address must be provided, and the serial + port must already be setup and configured. + + armada3700_uart, + Start an early, polled-mode console on the + Armada 3700 serial port at the specified + address. The serial port must already be setup + and configured. Options are not yet supported. + + earlyprintk= [X86,SH,BLACKFIN,ARM,M68k] + earlyprintk=vga + earlyprintk=efi + earlyprintk=xen + earlyprintk=serial[,ttySn[,baudrate]] + earlyprintk=serial[,0x...[,baudrate]] + earlyprintk=ttySn[,baudrate] + earlyprintk=dbgp[debugController#] + earlyprintk=pciserial,bus:device.function[,baudrate] + + earlyprintk is useful when the kernel crashes before + the normal console is initialized. It is not enabled by + default because it has some cosmetic problems. + + Append ",keep" to not disable it when the real console + takes over. + + Only one of vga, efi, serial, or usb debug port can + be used at a time. + + Currently only ttyS0 and ttyS1 may be specified by + name. Other I/O ports may be explicitly specified + on some architectures (x86 and arm at least) by + replacing ttySn with an I/O port address, like this: + earlyprintk=serial,0x1008,115200 + You can find the port for a given device in + /proc/tty/driver/serial: + 2: uart:ST16650V2 port:00001008 irq:18 ... + + Interaction with the standard serial driver is not + very good. + + The VGA and EFI output is eventually overwritten by + the real console. + + The xen output can only be used by Xen PV guests. + + edac_report= [HW,EDAC] Control how to report EDAC event + Format: {"on" | "off" | "force"} + on: enable EDAC to report H/W event. May be overridden + by other higher priority error reporting module. + off: disable H/W event reporting through EDAC. + force: enforce the use of EDAC to report H/W event. + default: on. + + ekgdboc= [X86,KGDB] Allow early kernel console debugging + ekgdboc=kbd + + This is designed to be used in conjunction with + the boot argument: earlyprintk=vga + + edd= [EDD] + Format: {"off" | "on" | "skip[mbr]"} + + efi= [EFI] + Format: { "old_map", "nochunk", "noruntime", "debug" } + old_map [X86-64]: switch to the old ioremap-based EFI + runtime services mapping. 32-bit still uses this one by + default. + nochunk: disable reading files in "chunks" in the EFI + boot stub, as chunking can cause problems with some + firmware implementations. + noruntime : disable EFI runtime services support + debug: enable misc debug output + + efi_no_storage_paranoia [EFI; X86] + Using this parameter you can use more than 50% of + your efi variable storage. Use this parameter only if + you are really sure that your UEFI does sane gc and + fulfills the spec otherwise your board may brick. + + efi_fake_mem= nn[KMG]@ss[KMG]:aa[,nn[KMG]@ss[KMG]:aa,..] [EFI; X86] + Add arbitrary attribute to specific memory range by + updating original EFI memory map. + Region of memory which aa attribute is added to is + from ss to ss+nn. + If efi_fake_mem=2G@4G:0x10000,2G@0x10a0000000:0x10000 + is specified, EFI_MEMORY_MORE_RELIABLE(0x10000) + attribute is added to range 0x100000000-0x180000000 and + 0x10a0000000-0x1120000000. + + Using this parameter you can do debugging of EFI memmap + related feature. For example, you can do debugging of + Address Range Mirroring feature even if your box + doesn't support it. + + efivar_ssdt= [EFI; X86] Name of an EFI variable that contains an SSDT + that is to be dynamically loaded by Linux. If there are + multiple variables with the same name but with different + vendor GUIDs, all of them will be loaded. See + Documentation/acpi/ssdt-overlays.txt for details. + + + eisa_irq_edge= [PARISC,HW] + See header of drivers/parisc/eisa.c. + + elanfreq= [X86-32] + See comment before function elanfreq_setup() in + arch/x86/kernel/cpu/cpufreq/elanfreq.c. + + elevator= [IOSCHED] + Format: {"cfq" | "deadline" | "noop"} + See Documentation/block/cfq-iosched.txt and + Documentation/block/deadline-iosched.txt for details. + + elfcorehdr=[size[KMG]@]offset[KMG] [IA64,PPC,SH,X86,S390] + Specifies physical address of start of kernel core + image elf header and optionally the size. Generally + kexec loader will pass this option to capture kernel. + See Documentation/kdump/kdump.txt for details. + + enable_mtrr_cleanup [X86] + The kernel tries to adjust MTRR layout from continuous + to discrete, to make X server driver able to add WB + entry later. This parameter enables that. + + enable_timer_pin_1 [X86] + Enable PIN 1 of APIC timer + Can be useful to work around chipset bugs + (in particular on some ATI chipsets). + The kernel tries to set a reasonable default. + + enforcing [SELINUX] Set initial enforcing status. + Format: {"0" | "1"} + See security/selinux/Kconfig help text. + 0 -- permissive (log only, no denials). + 1 -- enforcing (deny and log). + Default value is 0. + Value can be changed at runtime via /selinux/enforce. + + erst_disable [ACPI] + Disable Error Record Serialization Table (ERST) + support. + + ether= [HW,NET] Ethernet cards parameters + This option is obsoleted by the "netdev=" option, which + has equivalent usage. See its documentation for details. + + evm= [EVM] + Format: { "fix" } + Permit 'security.evm' to be updated regardless of + current integrity status. + + failslab= + fail_page_alloc= + fail_make_request=[KNL] + General fault injection mechanism. + Format: ,,, + See also Documentation/fault-injection/. + + floppy= [HW] + See Documentation/blockdev/floppy.txt. + + force_pal_cache_flush + [IA-64] Avoid check_sal_cache_flush which may hang on + buggy SAL_CACHE_FLUSH implementations. Using this + parameter will force ia64_sal_cache_flush to call + ia64_pal_cache_flush instead of SAL_CACHE_FLUSH. + + forcepae [X86-32] + Forcefully enable Physical Address Extension (PAE). + Many Pentium M systems disable PAE but may have a + functionally usable PAE implementation. + Warning: use of this parameter will taint the kernel + and may cause unknown problems. + + ftrace=[tracer] + [FTRACE] will set and start the specified tracer + as early as possible in order to facilitate early + boot debugging. + + ftrace_dump_on_oops[=orig_cpu] + [FTRACE] will dump the trace buffers on oops. + If no parameter is passed, ftrace will dump + buffers of all CPUs, but if you pass orig_cpu, it will + dump only the buffer of the CPU that triggered the + oops. + + ftrace_filter=[function-list] + [FTRACE] Limit the functions traced by the function + tracer at boot up. function-list is a comma separated + list of functions. This list can be changed at run + time by the set_ftrace_filter file in the debugfs + tracing directory. + + ftrace_notrace=[function-list] + [FTRACE] Do not trace the functions specified in + function-list. This list can be changed at run time + by the set_ftrace_notrace file in the debugfs + tracing directory. + + ftrace_graph_filter=[function-list] + [FTRACE] Limit the top level callers functions traced + by the function graph tracer at boot up. + function-list is a comma separated list of functions + that can be changed at run time by the + set_graph_function file in the debugfs tracing directory. + + ftrace_graph_notrace=[function-list] + [FTRACE] Do not trace from the functions specified in + function-list. This list is a comma separated list of + functions that can be changed at run time by the + set_graph_notrace file in the debugfs tracing directory. + + gamecon.map[2|3]= + [HW,JOY] Multisystem joystick and NES/SNES/PSX pad + support via parallel port (up to 5 devices per port) + Format: ,,,,, + See also Documentation/input/joystick-parport.txt + + gamma= [HW,DRM] + + gart_fix_e820= [X86_64] disable the fix e820 for K8 GART + Format: off | on + default: on + + gcov_persist= [GCOV] When non-zero (default), profiling data for + kernel modules is saved and remains accessible via + debugfs, even when the module is unloaded/reloaded. + When zero, profiling data is discarded and associated + debugfs files are removed at module unload time. + + gpt [EFI] Forces disk with valid GPT signature but + invalid Protective MBR to be treated as GPT. If the + primary GPT is corrupted, it enables the backup/alternate + GPT to be used instead. + + grcan.enable0= [HW] Configuration of physical interface 0. Determines + the "Enable 0" bit of the configuration register. + Format: 0 | 1 + Default: 0 + grcan.enable1= [HW] Configuration of physical interface 1. Determines + the "Enable 0" bit of the configuration register. + Format: 0 | 1 + Default: 0 + grcan.select= [HW] Select which physical interface to use. + Format: 0 | 1 + Default: 0 + grcan.txsize= [HW] Sets the size of the tx buffer. + Format: such that (txsize & ~0x1fffc0) == 0. + Default: 1024 + grcan.rxsize= [HW] Sets the size of the rx buffer. + Format: such that (rxsize & ~0x1fffc0) == 0. + Default: 1024 + + gpio-mockup.gpio_mockup_ranges + [HW] Sets the ranges of gpiochip of for this device. + Format: ,,,... + + hardlockup_all_cpu_backtrace= + [KNL] Should the hard-lockup detector generate + backtraces on all cpus. + Format: + + hashdist= [KNL,NUMA] Large hashes allocated during boot + are distributed across NUMA nodes. Defaults on + for 64-bit NUMA, off otherwise. + Format: 0 | 1 (for off | on) + + hcl= [IA-64] SGI's Hardware Graph compatibility layer + + hd= [EIDE] (E)IDE hard drive subsystem geometry + Format: ,, + + hest_disable [ACPI] + Disable Hardware Error Source Table (HEST) support; + corresponding firmware-first mode error processing + logic will be disabled. + + highmem=nn[KMG] [KNL,BOOT] forces the highmem zone to have an exact + size of . This works even on boxes that have no + highmem otherwise. This also works to reduce highmem + size on bigger boxes. + + highres= [KNL] Enable/disable high resolution timer mode. + Valid parameters: "on", "off" + Default: "on" + + hisax= [HW,ISDN] + See Documentation/isdn/README.HiSax. + + hlt [BUGS=ARM,SH] + + hpet= [X86-32,HPET] option to control HPET usage + Format: { enable (default) | disable | force | + verbose } + disable: disable HPET and use PIT instead + force: allow force enabled of undocumented chips (ICH4, + VIA, nVidia) + verbose: show contents of HPET registers during setup + + hpet_mmap= [X86, HPET_MMAP] Allow userspace to mmap HPET + registers. Default set by CONFIG_HPET_MMAP_DEFAULT. + + hugepages= [HW,X86-32,IA-64] HugeTLB pages to allocate at boot. + hugepagesz= [HW,IA-64,PPC,X86-64] The size of the HugeTLB pages. + On x86-64 and powerpc, this option can be specified + multiple times interleaved with hugepages= to reserve + huge pages of different sizes. Valid pages sizes on + x86-64 are 2M (when the CPU supports "pse") and 1G + (when the CPU supports the "pdpe1gb" cpuinfo flag). + + hvc_iucv= [S390] Number of z/VM IUCV hypervisor console (HVC) + terminal devices. Valid values: 0..8 + hvc_iucv_allow= [S390] Comma-separated list of z/VM user IDs. + If specified, z/VM IUCV HVC accepts connections + from listed z/VM user IDs only. + + hwthread_map= [METAG] Comma-separated list of Linux cpu id to + hardware thread id mappings. + Format: : + + keep_bootcon [KNL] + Do not unregister boot console at start. This is only + useful for debugging when something happens in the window + between unregistering the boot console and initializing + the real console. + + i2c_bus= [HW] Override the default board specific I2C bus speed + or register an additional I2C bus that is not + registered from board initialization code. + Format: + , + + i8042.debug [HW] Toggle i8042 debug mode + i8042.unmask_kbd_data + [HW] Enable printing of interrupt data from the KBD port + (disabled by default, and as a pre-condition + requires that i8042.debug=1 be enabled) + i8042.direct [HW] Put keyboard port into non-translated mode + i8042.dumbkbd [HW] Pretend that controller can only read data from + keyboard and cannot control its state + (Don't attempt to blink the leds) + i8042.noaux [HW] Don't check for auxiliary (== mouse) port + i8042.nokbd [HW] Don't check/create keyboard port + i8042.noloop [HW] Disable the AUX Loopback command while probing + for the AUX port + i8042.nomux [HW] Don't check presence of an active multiplexing + controller + i8042.nopnp [HW] Don't use ACPIPnP / PnPBIOS to discover KBD/AUX + controllers + i8042.notimeout [HW] Ignore timeout condition signalled by controller + i8042.reset [HW] Reset the controller during init, cleanup and + suspend-to-ram transitions, only during s2r + transitions, or never reset + Format: { 1 | Y | y | 0 | N | n } + 1, Y, y: always reset controller + 0, N, n: don't ever reset controller + Default: only on s2r transitions on x86; most other + architectures force reset to be always executed + i8042.unlock [HW] Unlock (ignore) the keylock + i8042.kbdreset [HW] Reset device connected to KBD port + + i810= [HW,DRM] + + i8k.ignore_dmi [HW] Continue probing hardware even if DMI data + indicates that the driver is running on unsupported + hardware. + i8k.force [HW] Activate i8k driver even if SMM BIOS signature + does not match list of supported models. + i8k.power_status + [HW] Report power status in /proc/i8k + (disabled by default) + i8k.restricted [HW] Allow controlling fans only if SYS_ADMIN + capability is set. + + i915.invert_brightness= + [DRM] Invert the sense of the variable that is used to + set the brightness of the panel backlight. Normally a + brightness value of 0 indicates backlight switched off, + and the maximum of the brightness value sets the backlight + to maximum brightness. If this parameter is set to 0 + (default) and the machine requires it, or this parameter + is set to 1, a brightness value of 0 sets the backlight + to maximum brightness, and the maximum of the brightness + value switches the backlight off. + -1 -- never invert brightness + 0 -- machine default + 1 -- force brightness inversion + + icn= [HW,ISDN] + Format: [,[,[,]]] + + ide-core.nodma= [HW] (E)IDE subsystem + Format: =0.0 to prevent dma on hda, =0.1 hdb =1.0 hdc + .vlb_clock .pci_clock .noflush .nohpa .noprobe .nowerr + .cdrom .chs .ignore_cable are additional options + See Documentation/ide/ide.txt. + + ide-generic.probe-mask= [HW] (E)IDE subsystem + Format: + Probe mask for legacy ISA IDE ports. Depending on + platform up to 6 ports are supported, enabled by + setting corresponding bits in the mask to 1. The + default value is 0x0, which has a special meaning. + On systems that have PCI, it triggers scanning the + PCI bus for the first and the second port, which + are then probed. On systems without PCI the value + of 0x0 enables probing the two first ports as if it + was 0x3. + + ide-pci-generic.all-generic-ide [HW] (E)IDE subsystem + Claim all unknown PCI IDE storage controllers. + + idle= [X86] + Format: idle=poll, idle=halt, idle=nomwait + Poll forces a polling idle loop that can slightly + improve the performance of waking up a idle CPU, but + will use a lot of power and make the system run hot. + Not recommended. + idle=halt: Halt is forced to be used for CPU idle. + In such case C2/C3 won't be used again. + idle=nomwait: Disable mwait for CPU C-states + + ieee754= [MIPS] Select IEEE Std 754 conformance mode + Format: { strict | legacy | 2008 | relaxed } + Default: strict + + Choose which programs will be accepted for execution + based on the IEEE 754 NaN encoding(s) supported by + the FPU and the NaN encoding requested with the value + of an ELF file header flag individually set by each + binary. Hardware implementations are permitted to + support either or both of the legacy and the 2008 NaN + encoding mode. + + Available settings are as follows: + strict accept binaries that request a NaN encoding + supported by the FPU + legacy only accept legacy-NaN binaries, if supported + by the FPU + 2008 only accept 2008-NaN binaries, if supported + by the FPU + relaxed accept any binaries regardless of whether + supported by the FPU + + The FPU emulator is always able to support both NaN + encodings, so if no FPU hardware is present or it has + been disabled with 'nofpu', then the settings of + 'legacy' and '2008' strap the emulator accordingly, + 'relaxed' straps the emulator for both legacy-NaN and + 2008-NaN, whereas 'strict' enables legacy-NaN only on + legacy processors and both NaN encodings on MIPS32 or + MIPS64 CPUs. + + The setting for ABS.fmt/NEG.fmt instruction execution + mode generally follows that for the NaN encoding, + except where unsupported by hardware. + + ignore_loglevel [KNL] + Ignore loglevel setting - this will print /all/ + kernel messages to the console. Useful for debugging. + We also add it as printk module parameter, so users + could change it dynamically, usually by + /sys/module/printk/parameters/ignore_loglevel. + + ignore_rlimit_data + Ignore RLIMIT_DATA setting for data mappings, + print warning at first misuse. Can be changed via + /sys/module/kernel/parameters/ignore_rlimit_data. + + ihash_entries= [KNL] + Set number of hash buckets for inode cache. + + ima_appraise= [IMA] appraise integrity measurements + Format: { "off" | "enforce" | "fix" | "log" } + default: "enforce" + + ima_appraise_tcb [IMA] + The builtin appraise policy appraises all files + owned by uid=0. + + ima_hash= [IMA] + Format: { md5 | sha1 | rmd160 | sha256 | sha384 + | sha512 | ... } + default: "sha1" + + The list of supported hash algorithms is defined + in crypto/hash_info.h. + + ima_policy= [IMA] + The builtin measurement policy to load during IMA + setup. Specyfing "tcb" as the value, measures all + programs exec'd, files mmap'd for exec, and all files + opened with the read mode bit set by either the + effective uid (euid=0) or uid=0. + Format: "tcb" + + ima_tcb [IMA] Deprecated. Use ima_policy= instead. + Load a policy which meets the needs of the Trusted + Computing Base. This means IMA will measure all + programs exec'd, files mmap'd for exec, and all files + opened for read by uid=0. + + ima_template= [IMA] + Select one of defined IMA measurements template formats. + Formats: { "ima" | "ima-ng" | "ima-sig" } + Default: "ima-ng" + + ima_template_fmt= + [IMA] Define a custom template format. + Format: { "field1|...|fieldN" } + + ima.ahash_minsize= [IMA] Minimum file size for asynchronous hash usage + Format: + Set the minimal file size for using asynchronous hash. + If left unspecified, ahash usage is disabled. + + ahash performance varies for different data sizes on + different crypto accelerators. This option can be used + to achieve the best performance for a particular HW. + + ima.ahash_bufsize= [IMA] Asynchronous hash buffer size + Format: + Set hashing buffer size. Default: 4k. + + ahash performance varies for different chunk sizes on + different crypto accelerators. This option can be used + to achieve best performance for particular HW. + + init= [KNL] + Format: + Run specified binary instead of /sbin/init as init + process. + + initcall_debug [KNL] Trace initcalls as they are executed. Useful + for working out where the kernel is dying during + startup. + + initcall_blacklist= [KNL] Do not execute a comma-separated list of + initcall functions. Useful for debugging built-in + modules and initcalls. + + initrd= [BOOT] Specify the location of the initial ramdisk + + init_pkru= [x86] Specify the default memory protection keys rights + register contents for all processes. 0x55555554 by + default (disallow access to all but pkey 0). Can + override in debugfs after boot. + + inport.irq= [HW] Inport (ATI XL and Microsoft) busmouse driver + Format: + + int_pln_enable [x86] Enable power limit notification interrupt + + integrity_audit=[IMA] + Format: { "0" | "1" } + 0 -- basic integrity auditing messages. (Default) + 1 -- additional integrity auditing messages. + + intel_iommu= [DMAR] Intel IOMMU driver (DMAR) option + on + Enable intel iommu driver. + off + Disable intel iommu driver. + igfx_off [Default Off] + By default, gfx is mapped as normal device. If a gfx + device has a dedicated DMAR unit, the DMAR unit is + bypassed by not enabling DMAR with this option. In + this case, gfx device will use physical address for + DMA. + forcedac [x86_64] + With this option iommu will not optimize to look + for io virtual address below 32-bit forcing dual + address cycle on pci bus for cards supporting greater + than 32-bit addressing. The default is to look + for translation below 32-bit and if not available + then look in the higher range. + strict [Default Off] + With this option on every unmap_single operation will + result in a hardware IOTLB flush operation as opposed + to batching them for performance. + sp_off [Default Off] + By default, super page will be supported if Intel IOMMU + has the capability. With this option, super page will + not be supported. + ecs_off [Default Off] + By default, extended context tables will be supported if + the hardware advertises that it has support both for the + extended tables themselves, and also PASID support. With + this option set, extended tables will not be used even + on hardware which claims to support them. + + intel_idle.max_cstate= [KNL,HW,ACPI,X86] + 0 disables intel_idle and fall back on acpi_idle. + 1 to 9 specify maximum depth of C-state. + + intel_pstate= [X86] + disable + Do not enable intel_pstate as the default + scaling driver for the supported processors + force + Enable intel_pstate on systems that prohibit it by default + in favor of acpi-cpufreq. Forcing the intel_pstate driver + instead of acpi-cpufreq may disable platform features, such + as thermal controls and power capping, that rely on ACPI + P-States information being indicated to OSPM and therefore + should be used with caution. This option does not work with + processors that aren't supported by the intel_pstate driver + or on platforms that use pcc-cpufreq instead of acpi-cpufreq. + no_hwp + Do not enable hardware P state control (HWP) + if available. + hwp_only + Only load intel_pstate on systems which support + hardware P state control (HWP) if available. + support_acpi_ppc + Enforce ACPI _PPC performance limits. If the Fixed ACPI + Description Table, specifies preferred power management + profile as "Enterprise Server" or "Performance Server", + then this feature is turned on by default. + + intremap= [X86-64, Intel-IOMMU] + on enable Interrupt Remapping (default) + off disable Interrupt Remapping + nosid disable Source ID checking + no_x2apic_optout + BIOS x2APIC opt-out request will be ignored + nopost disable Interrupt Posting + + iomem= Disable strict checking of access to MMIO memory + strict regions from userspace. + relaxed + + iommu= [x86] + off + force + noforce + biomerge + panic + nopanic + merge + nomerge + forcesac + soft + pt [x86, IA-64] + nobypass [PPC/POWERNV] + Disable IOMMU bypass, using IOMMU for PCI devices. + + + io7= [HW] IO7 for Marvel based alpha systems + See comment before marvel_specify_io7 in + arch/alpha/kernel/core_marvel.c. + + io_delay= [X86] I/O delay method + 0x80 + Standard port 0x80 based delay + 0xed + Alternate port 0xed based delay (needed on some systems) + udelay + Simple two microseconds delay + none + No delay + + ip= [IP_PNP] + See Documentation/filesystems/nfs/nfsroot.txt. + + irqaffinity= [SMP] Set the default irq affinity mask + The argument is a cpu list, as described above. + + irqfixup [HW] + When an interrupt is not handled search all handlers + for it. Intended to get systems with badly broken + firmware running. + + irqpoll [HW] + When an interrupt is not handled search all handlers + for it. Also check all handlers each timer + interrupt. Intended to get systems with badly broken + firmware running. + + isapnp= [ISAPNP] + Format: ,,, + + isolcpus= [KNL,SMP] Isolate CPUs from the general scheduler. + The argument is a cpu list, as described above. + + This option can be used to specify one or more CPUs + to isolate from the general SMP balancing and scheduling + algorithms. You can move a process onto or off an + "isolated" CPU via the CPU affinity syscalls or cpuset. + begins at 0 and the maximum value is + "number of CPUs in system - 1". + + This option is the preferred way to isolate CPUs. The + alternative -- manually setting the CPU mask of all + tasks in the system -- can cause problems and + suboptimal load balancer performance. + + iucv= [HW,NET] + + ivrs_ioapic [HW,X86_64] + Provide an override to the IOAPIC-ID<->DEVICE-ID + mapping provided in the IVRS ACPI table. For + example, to map IOAPIC-ID decimal 10 to + PCI device 00:14.0 write the parameter as: + ivrs_ioapic[10]=00:14.0 + + ivrs_hpet [HW,X86_64] + Provide an override to the HPET-ID<->DEVICE-ID + mapping provided in the IVRS ACPI table. For + example, to map HPET-ID decimal 0 to + PCI device 00:14.0 write the parameter as: + ivrs_hpet[0]=00:14.0 + + ivrs_acpihid [HW,X86_64] + Provide an override to the ACPI-HID:UID<->DEVICE-ID + mapping provided in the IVRS ACPI table. For + example, to map UART-HID:UID AMD0020:0 to + PCI device 00:14.5 write the parameter as: + ivrs_acpihid[00:14.5]=AMD0020:0 + + js= [HW,JOY] Analog joystick + See Documentation/input/joystick.txt. + + nokaslr [KNL] + When CONFIG_RANDOMIZE_BASE is set, this disables + kernel and module base offset ASLR (Address Space + Layout Randomization). + + keepinitrd [HW,ARM] + + kernelcore= [KNL,X86,IA-64,PPC] + Format: nn[KMGTPE] | "mirror" + This parameter + specifies the amount of memory usable by the kernel + for non-movable allocations. The requested amount is + spread evenly throughout all nodes in the system. The + remaining memory in each node is used for Movable + pages. In the event, a node is too small to have both + kernelcore and Movable pages, kernelcore pages will + take priority and other nodes will have a larger number + of Movable pages. The Movable zone is used for the + allocation of pages that may be reclaimed or moved + by the page migration subsystem. This means that + HugeTLB pages may not be allocated from this zone. + Note that allocations like PTEs-from-HighMem still + use the HighMem zone if it exists, and the Normal + zone if it does not. + + Instead of specifying the amount of memory (nn[KMGTPE]), + you can specify "mirror" option. In case "mirror" + option is specified, mirrored (reliable) memory is used + for non-movable allocations and remaining memory is used + for Movable pages. nn[KMGTPE] and "mirror" are exclusive, + so you can NOT specify nn[KMGTPE] and "mirror" at the same + time. + + kgdbdbgp= [KGDB,HW] kgdb over EHCI usb debug port. + Format: [,poll interval] + The controller # is the number of the ehci usb debug + port as it is probed via PCI. The poll interval is + optional and is the number seconds in between + each poll cycle to the debug port in case you need + the functionality for interrupting the kernel with + gdb or control-c on the dbgp connection. When + not using this parameter you use sysrq-g to break into + the kernel debugger. + + kgdboc= [KGDB,HW] kgdb over consoles. + Requires a tty driver that supports console polling, + or a supported polling keyboard driver (non-usb). + Serial only format: [,baud] + keyboard only format: kbd + keyboard and serial format: kbd,[,baud] + Optional Kernel mode setting: + kms, kbd format: kms,kbd + kms, kbd and serial format: kms,kbd,[,baud] + + kgdbwait [KGDB] Stop kernel execution and enter the + kernel debugger at the earliest opportunity. + + kmac= [MIPS] korina ethernet MAC address. + Configure the RouterBoard 532 series on-chip + Ethernet adapter MAC address. + + kmemleak= [KNL] Boot-time kmemleak enable/disable + Valid arguments: on, off + Default: on + Built with CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF=y, + the default is off. + + kmemcheck= [X86] Boot-time kmemcheck enable/disable/one-shot mode + Valid arguments: 0, 1, 2 + kmemcheck=0 (disabled) + kmemcheck=1 (enabled) + kmemcheck=2 (one-shot mode) + Default: 2 (one-shot mode) + + kstack=N [X86] Print N words from the kernel stack + in oops dumps. + + kvm.ignore_msrs=[KVM] Ignore guest accesses to unhandled MSRs. + Default is 0 (don't ignore, but inject #GP) + + kvm.mmu_audit= [KVM] This is a R/W parameter which allows audit + KVM MMU at runtime. + Default is 0 (off) + + kvm-amd.nested= [KVM,AMD] Allow nested virtualization in KVM/SVM. + Default is 1 (enabled) + + kvm-amd.npt= [KVM,AMD] Disable nested paging (virtualized MMU) + for all guests. + Default is 1 (enabled) if in 64-bit or 32-bit PAE mode. + + kvm-intel.ept= [KVM,Intel] Disable extended page tables + (virtualized MMU) support on capable Intel chips. + Default is 1 (enabled) + + kvm-intel.emulate_invalid_guest_state= + [KVM,Intel] Enable emulation of invalid guest states + Default is 0 (disabled) + + kvm-intel.flexpriority= + [KVM,Intel] Disable FlexPriority feature (TPR shadow). + Default is 1 (enabled) + + kvm-intel.nested= + [KVM,Intel] Enable VMX nesting (nVMX). + Default is 0 (disabled) + + kvm-intel.unrestricted_guest= + [KVM,Intel] Disable unrestricted guest feature + (virtualized real and unpaged mode) on capable + Intel chips. Default is 1 (enabled) + + kvm-intel.vpid= [KVM,Intel] Disable Virtual Processor Identification + feature (tagged TLBs) on capable Intel chips. + Default is 1 (enabled) + + l2cr= [PPC] + + l3cr= [PPC] + + lapic [X86-32,APIC] Enable the local APIC even if BIOS + disabled it. + + lapic= [x86,APIC] "notscdeadline" Do not use TSC deadline + value for LAPIC timer one-shot implementation. Default + back to the programmable timer unit in the LAPIC. + + lapic_timer_c2_ok [X86,APIC] trust the local apic timer + in C2 power state. + + libata.dma= [LIBATA] DMA control + libata.dma=0 Disable all PATA and SATA DMA + libata.dma=1 PATA and SATA Disk DMA only + libata.dma=2 ATAPI (CDROM) DMA only + libata.dma=4 Compact Flash DMA only + Combinations also work, so libata.dma=3 enables DMA + for disks and CDROMs, but not CFs. + + libata.ignore_hpa= [LIBATA] Ignore HPA limit + libata.ignore_hpa=0 keep BIOS limits (default) + libata.ignore_hpa=1 ignore limits, using full disk + + libata.noacpi [LIBATA] Disables use of ACPI in libata suspend/resume + when set. + Format: + + libata.force= [LIBATA] Force configurations. The format is comma + separated list of "[ID:]VAL" where ID is + PORT[.DEVICE]. PORT and DEVICE are decimal numbers + matching port, link or device. Basically, it matches + the ATA ID string printed on console by libata. If + the whole ID part is omitted, the last PORT and DEVICE + values are used. If ID hasn't been specified yet, the + configuration applies to all ports, links and devices. + + If only DEVICE is omitted, the parameter applies to + the port and all links and devices behind it. DEVICE + number of 0 either selects the first device or the + first fan-out link behind PMP device. It does not + select the host link. DEVICE number of 15 selects the + host link and device attached to it. + + The VAL specifies the configuration to force. As long + as there's no ambiguity shortcut notation is allowed. + For example, both 1.5 and 1.5G would work for 1.5Gbps. + The following configurations can be forced. + + * Cable type: 40c, 80c, short40c, unk, ign or sata. + Any ID with matching PORT is used. + + * SATA link speed limit: 1.5Gbps or 3.0Gbps. + + * Transfer mode: pio[0-7], mwdma[0-4] and udma[0-7]. + udma[/][16,25,33,44,66,100,133] notation is also + allowed. + + * [no]ncq: Turn on or off NCQ. + + * [no]ncqtrim: Turn off queued DSM TRIM. + + * nohrst, nosrst, norst: suppress hard, soft + and both resets. + + * rstonce: only attempt one reset during + hot-unplug link recovery + + * dump_id: dump IDENTIFY data. + + * atapi_dmadir: Enable ATAPI DMADIR bridge support + + * disable: Disable this device. + + If there are multiple matching configurations changing + the same attribute, the last one is used. + + memblock=debug [KNL] Enable memblock debug messages. + + load_ramdisk= [RAM] List of ramdisks to load from floppy + See Documentation/blockdev/ramdisk.txt. + + lockd.nlm_grace_period=P [NFS] Assign grace period. + Format: + + lockd.nlm_tcpport=N [NFS] Assign TCP port. + Format: + + lockd.nlm_timeout=T [NFS] Assign timeout value. + Format: + + lockd.nlm_udpport=M [NFS] Assign UDP port. + Format: + + locktorture.nreaders_stress= [KNL] + Set the number of locking read-acquisition kthreads. + Defaults to being automatically set based on the + number of online CPUs. + + locktorture.nwriters_stress= [KNL] + Set the number of locking write-acquisition kthreads. + + locktorture.onoff_holdoff= [KNL] + Set time (s) after boot for CPU-hotplug testing. + + locktorture.onoff_interval= [KNL] + Set time (s) between CPU-hotplug operations, or + zero to disable CPU-hotplug testing. + + locktorture.shuffle_interval= [KNL] + Set task-shuffle interval (jiffies). Shuffling + tasks allows some CPUs to go into dyntick-idle + mode during the locktorture test. + + locktorture.shutdown_secs= [KNL] + Set time (s) after boot system shutdown. This + is useful for hands-off automated testing. + + locktorture.stat_interval= [KNL] + Time (s) between statistics printk()s. + + locktorture.stutter= [KNL] + Time (s) to stutter testing, for example, + specifying five seconds causes the test to run for + five seconds, wait for five seconds, and so on. + This tests the locking primitive's ability to + transition abruptly to and from idle. + + locktorture.torture_runnable= [BOOT] + Start locktorture running at boot time. + + locktorture.torture_type= [KNL] + Specify the locking implementation to test. + + locktorture.verbose= [KNL] + Enable additional printk() statements. + + logibm.irq= [HW,MOUSE] Logitech Bus Mouse Driver + Format: + + loglevel= All Kernel Messages with a loglevel smaller than the + console loglevel will be printed to the console. It can + also be changed with klogd or other programs. The + loglevels are defined as follows: + + 0 (KERN_EMERG) system is unusable + 1 (KERN_ALERT) action must be taken immediately + 2 (KERN_CRIT) critical conditions + 3 (KERN_ERR) error conditions + 4 (KERN_WARNING) warning conditions + 5 (KERN_NOTICE) normal but significant condition + 6 (KERN_INFO) informational + 7 (KERN_DEBUG) debug-level messages + + log_buf_len=n[KMG] Sets the size of the printk ring buffer, + in bytes. n must be a power of two and greater + than the minimal size. The minimal size is defined + by LOG_BUF_SHIFT kernel config parameter. There is + also CONFIG_LOG_CPU_MAX_BUF_SHIFT config parameter + that allows to increase the default size depending on + the number of CPUs. See init/Kconfig for more details. + + logo.nologo [FB] Disables display of the built-in Linux logo. + This may be used to provide more screen space for + kernel log messages and is useful when debugging + kernel boot problems. + + lp=0 [LP] Specify parallel ports to use, e.g, + lp=port[,port...] lp=none,parport0 (lp0 not configured, lp1 uses + lp=reset first parallel port). 'lp=0' disables the + lp=auto printer driver. 'lp=reset' (which can be + specified in addition to the ports) causes + attached printers to be reset. Using + lp=port1,port2,... specifies the parallel ports + to associate lp devices with, starting with + lp0. A port specification may be 'none' to skip + that lp device, or a parport name such as + 'parport0'. Specifying 'lp=auto' instead of a + port specification list means that device IDs + from each port should be examined, to see if + an IEEE 1284-compliant printer is attached; if + so, the driver will manage that printer. + See also header of drivers/char/lp.c. + + lpj=n [KNL] + Sets loops_per_jiffy to given constant, thus avoiding + time-consuming boot-time autodetection (up to 250 ms per + CPU). 0 enables autodetection (default). To determine + the correct value for your kernel, boot with normal + autodetection and see what value is printed. Note that + on SMP systems the preset will be applied to all CPUs, + which is likely to cause problems if your CPUs need + significantly divergent settings. An incorrect value + will cause delays in the kernel to be wrong, leading to + unpredictable I/O errors and other breakage. Although + unlikely, in the extreme case this might damage your + hardware. + + ltpc= [NET] + Format: ,, + + machvec= [IA-64] Force the use of a particular machine-vector + (machvec) in a generic kernel. + Example: machvec=hpzx1_swiotlb + + machtype= [Loongson] Share the same kernel image file between different + yeeloong laptop. + Example: machtype=lemote-yeeloong-2f-7inch + + max_addr=nn[KMG] [KNL,BOOT,ia64] All physical memory greater + than or equal to this physical address is ignored. + + maxcpus= [SMP] Maximum number of processors that an SMP kernel + will bring up during bootup. maxcpus=n : n >= 0 limits + the kernel to bring up 'n' processors. Surely after + bootup you can bring up the other plugged cpu by executing + "echo 1 > /sys/devices/system/cpu/cpuX/online". So maxcpus + only takes effect during system bootup. + While n=0 is a special case, it is equivalent to "nosmp", + which also disables the IO APIC. + + max_loop= [LOOP] The number of loop block devices that get + (loop.max_loop) unconditionally pre-created at init time. The default + number is configured by BLK_DEV_LOOP_MIN_COUNT. Instead + of statically allocating a predefined number, loop + devices can be requested on-demand with the + /dev/loop-control interface. + + mce [X86-32] Machine Check Exception + + mce=option [X86-64] See Documentation/x86/x86_64/boot-options.txt + + md= [HW] RAID subsystems devices and level + See Documentation/md.txt. + + mdacon= [MDA] + Format: , + Specifies range of consoles to be captured by the MDA. + + mem=nn[KMG] [KNL,BOOT] Force usage of a specific amount of memory + Amount of memory to be used when the kernel is not able + to see the whole system memory or for test. + [X86] Work as limiting max address. Use together + with memmap= to avoid physical address space collisions. + Without memmap= PCI devices could be placed at addresses + belonging to unused RAM. + + mem=nopentium [BUGS=X86-32] Disable usage of 4MB pages for kernel + memory. + + memchunk=nn[KMG] + [KNL,SH] Allow user to override the default size for + per-device physically contiguous DMA buffers. + + memhp_default_state=online/offline + [KNL] Set the initial state for the memory hotplug + onlining policy. If not specified, the default value is + set according to the + CONFIG_MEMORY_HOTPLUG_DEFAULT_ONLINE kernel config + option. + See Documentation/memory-hotplug.txt. + + memmap=exactmap [KNL,X86] Enable setting of an exact + E820 memory map, as specified by the user. + Such memmap=exactmap lines can be constructed based on + BIOS output or other requirements. See the memmap=nn@ss + option description. + + memmap=nn[KMG]@ss[KMG] + [KNL] Force usage of a specific region of memory. + Region of memory to be used is from ss to ss+nn. + + memmap=nn[KMG]#ss[KMG] + [KNL,ACPI] Mark specific memory as ACPI data. + Region of memory to be marked is from ss to ss+nn. + + memmap=nn[KMG]$ss[KMG] + [KNL,ACPI] Mark specific memory as reserved. + Region of memory to be reserved is from ss to ss+nn. + Example: Exclude memory from 0x18690000-0x1869ffff + memmap=64K$0x18690000 + or + memmap=0x10000$0x18690000 + + memmap=nn[KMG]!ss[KMG] + [KNL,X86] Mark specific memory as protected. + Region of memory to be used, from ss to ss+nn. + The memory region may be marked as e820 type 12 (0xc) + and is NVDIMM or ADR memory. + + memory_corruption_check=0/1 [X86] + Some BIOSes seem to corrupt the first 64k of + memory when doing things like suspend/resume. + Setting this option will scan the memory + looking for corruption. Enabling this will + both detect corruption and prevent the kernel + from using the memory being corrupted. + However, its intended as a diagnostic tool; if + repeatable BIOS-originated corruption always + affects the same memory, you can use memmap= + to prevent the kernel from using that memory. + + memory_corruption_check_size=size [X86] + By default it checks for corruption in the low + 64k, making this memory unavailable for normal + use. Use this parameter to scan for + corruption in more or less memory. + + memory_corruption_check_period=seconds [X86] + By default it checks for corruption every 60 + seconds. Use this parameter to check at some + other rate. 0 disables periodic checking. + + memtest= [KNL,X86,ARM] Enable memtest + Format: + default : 0 + Specifies the number of memtest passes to be + performed. Each pass selects another test + pattern from a given set of patterns. Memtest + fills the memory with this pattern, validates + memory contents and reserves bad memory + regions that are detected. + + meye.*= [HW] Set MotionEye Camera parameters + See Documentation/video4linux/meye.txt. + + mfgpt_irq= [IA-32] Specify the IRQ to use for the + Multi-Function General Purpose Timers on AMD Geode + platforms. + + mfgptfix [X86-32] Fix MFGPT timers on AMD Geode platforms when + the BIOS has incorrectly applied a workaround. TinyBIOS + version 0.98 is known to be affected, 0.99 fixes the + problem by letting the user disable the workaround. + + mga= [HW,DRM] + + min_addr=nn[KMG] [KNL,BOOT,ia64] All physical memory below this + physical address is ignored. + + mini2440= [ARM,HW,KNL] + Format:[0..2][b][c][t] + Default: "0tb" + MINI2440 configuration specification: + 0 - The attached screen is the 3.5" TFT + 1 - The attached screen is the 7" TFT + 2 - The VGA Shield is attached (1024x768) + Leaving out the screen size parameter will not load + the TFT driver, and the framebuffer will be left + unconfigured. + b - Enable backlight. The TFT backlight pin will be + linked to the kernel VESA blanking code and a GPIO + LED. This parameter is not necessary when using the + VGA shield. + c - Enable the s3c camera interface. + t - Reserved for enabling touchscreen support. The + touchscreen support is not enabled in the mainstream + kernel as of 2.6.30, a preliminary port can be found + in the "bleeding edge" mini2440 support kernel at + http://repo.or.cz/w/linux-2.6/mini2440.git + + mminit_loglevel= + [KNL] When CONFIG_DEBUG_MEMORY_INIT is set, this + parameter allows control of the logging verbosity for + the additional memory initialisation checks. A value + of 0 disables mminit logging and a level of 4 will + log everything. Information is printed at KERN_DEBUG + so loglevel=8 may also need to be specified. + + module.sig_enforce + [KNL] When CONFIG_MODULE_SIG is set, this means that + modules without (valid) signatures will fail to load. + Note that if CONFIG_MODULE_SIG_FORCE is set, that + is always true, so this option does nothing. + + module_blacklist= [KNL] Do not load a comma-separated list of + modules. Useful for debugging problem modules. + + mousedev.tap_time= + [MOUSE] Maximum time between finger touching and + leaving touchpad surface for touch to be considered + a tap and be reported as a left button click (for + touchpads working in absolute mode only). + Format: + mousedev.xres= [MOUSE] Horizontal screen resolution, used for devices + reporting absolute coordinates, such as tablets + mousedev.yres= [MOUSE] Vertical screen resolution, used for devices + reporting absolute coordinates, such as tablets + + movablecore=nn[KMG] [KNL,X86,IA-64,PPC] This parameter + is similar to kernelcore except it specifies the + amount of memory used for migratable allocations. + If both kernelcore and movablecore is specified, + then kernelcore will be at *least* the specified + value but may be more. If movablecore on its own + is specified, the administrator must be careful + that the amount of memory usable for all allocations + is not too small. + + movable_node [KNL,X86] Boot-time switch to enable the effects + of CONFIG_MOVABLE_NODE=y. See mm/Kconfig for details. + + MTD_Partition= [MTD] + Format: ,,, + + MTD_Region= [MTD] Format: + ,[,,,,] + + mtdparts= [MTD] + See drivers/mtd/cmdlinepart.c. + + multitce=off [PPC] This parameter disables the use of the pSeries + firmware feature for updating multiple TCE entries + at a time. + + onenand.bdry= [HW,MTD] Flex-OneNAND Boundary Configuration + + Format: [die0_boundary][,die0_lock][,die1_boundary][,die1_lock] + + boundary - index of last SLC block on Flex-OneNAND. + The remaining blocks are configured as MLC blocks. + lock - Configure if Flex-OneNAND boundary should be locked. + Once locked, the boundary cannot be changed. + 1 indicates lock status, 0 indicates unlock status. + + mtdset= [ARM] + ARM/S3C2412 JIVE boot control + + See arch/arm/mach-s3c2412/mach-jive.c + + mtouchusb.raw_coordinates= + [HW] Make the MicroTouch USB driver use raw coordinates + ('y', default) or cooked coordinates ('n') + + mtrr_chunk_size=nn[KMG] [X86] + used for mtrr cleanup. It is largest continuous chunk + that could hold holes aka. UC entries. + + mtrr_gran_size=nn[KMG] [X86] + Used for mtrr cleanup. It is granularity of mtrr block. + Default is 1. + Large value could prevent small alignment from + using up MTRRs. + + mtrr_spare_reg_nr=n [X86] + Format: + Range: 0,7 : spare reg number + Default : 1 + Used for mtrr cleanup. It is spare mtrr entries number. + Set to 2 or more if your graphical card needs more. + + n2= [NET] SDL Inc. RISCom/N2 synchronous serial card + + netdev= [NET] Network devices parameters + Format: ,,,, + Note that mem_start is often overloaded to mean + something different and driver-specific. + This usage is only documented in each driver source + file if at all. + + nf_conntrack.acct= + [NETFILTER] Enable connection tracking flow accounting + 0 to disable accounting + 1 to enable accounting + Default value is 0. + + nfsaddrs= [NFS] Deprecated. Use ip= instead. + See Documentation/filesystems/nfs/nfsroot.txt. + + nfsroot= [NFS] nfs root filesystem for disk-less boxes. + See Documentation/filesystems/nfs/nfsroot.txt. + + nfsrootdebug [NFS] enable nfsroot debugging messages. + See Documentation/filesystems/nfs/nfsroot.txt. + + nfs.callback_nr_threads= + [NFSv4] set the total number of threads that the + NFS client will assign to service NFSv4 callback + requests. + + nfs.callback_tcpport= + [NFS] set the TCP port on which the NFSv4 callback + channel should listen. + + nfs.cache_getent= + [NFS] sets the pathname to the program which is used + to update the NFS client cache entries. + + nfs.cache_getent_timeout= + [NFS] sets the timeout after which an attempt to + update a cache entry is deemed to have failed. + + nfs.idmap_cache_timeout= + [NFS] set the maximum lifetime for idmapper cache + entries. + + nfs.enable_ino64= + [NFS] enable 64-bit inode numbers. + If zero, the NFS client will fake up a 32-bit inode + number for the readdir() and stat() syscalls instead + of returning the full 64-bit number. + The default is to return 64-bit inode numbers. + + nfs.max_session_cb_slots= + [NFSv4.1] Sets the maximum number of session + slots the client will assign to the callback + channel. This determines the maximum number of + callbacks the client will process in parallel for + a particular server. + + nfs.max_session_slots= + [NFSv4.1] Sets the maximum number of session slots + the client will attempt to negotiate with the server. + This limits the number of simultaneous RPC requests + that the client can send to the NFSv4.1 server. + Note that there is little point in setting this + value higher than the max_tcp_slot_table_limit. + + nfs.nfs4_disable_idmapping= + [NFSv4] When set to the default of '1', this option + ensures that both the RPC level authentication + scheme and the NFS level operations agree to use + numeric uids/gids if the mount is using the + 'sec=sys' security flavour. In effect it is + disabling idmapping, which can make migration from + legacy NFSv2/v3 systems to NFSv4 easier. + Servers that do not support this mode of operation + will be autodetected by the client, and it will fall + back to using the idmapper. + To turn off this behaviour, set the value to '0'. + nfs.nfs4_unique_id= + [NFS4] Specify an additional fixed unique ident- + ification string that NFSv4 clients can insert into + their nfs_client_id4 string. This is typically a + UUID that is generated at system install time. + + nfs.send_implementation_id = + [NFSv4.1] Send client implementation identification + information in exchange_id requests. + If zero, no implementation identification information + will be sent. + The default is to send the implementation identification + information. + + nfs.recover_lost_locks = + [NFSv4] Attempt to recover locks that were lost due + to a lease timeout on the server. Please note that + doing this risks data corruption, since there are + no guarantees that the file will remain unchanged + after the locks are lost. + If you want to enable the kernel legacy behaviour of + attempting to recover these locks, then set this + parameter to '1'. + The default parameter value of '0' causes the kernel + not to attempt recovery of lost locks. + + nfs4.layoutstats_timer = + [NFSv4.2] Change the rate at which the kernel sends + layoutstats to the pNFS metadata server. + + Setting this to value to 0 causes the kernel to use + whatever value is the default set by the layout + driver. A non-zero value sets the minimum interval + in seconds between layoutstats transmissions. + + nfsd.nfs4_disable_idmapping= + [NFSv4] When set to the default of '1', the NFSv4 + server will return only numeric uids and gids to + clients using auth_sys, and will accept numeric uids + and gids from such clients. This is intended to ease + migration from NFSv2/v3. + + objlayoutdriver.osd_login_prog= + [NFS] [OBJLAYOUT] sets the pathname to the program which + is used to automatically discover and login into new + osd-targets. Please see: + Documentation/filesystems/pnfs.txt for more explanations + + nmi_debug= [KNL,AVR32,SH] Specify one or more actions to take + when a NMI is triggered. + Format: [state][,regs][,debounce][,die] + + nmi_watchdog= [KNL,BUGS=X86] Debugging features for SMP kernels + Format: [panic,][nopanic,][num] + Valid num: 0 or 1 + 0 - turn hardlockup detector in nmi_watchdog off + 1 - turn hardlockup detector in nmi_watchdog on + When panic is specified, panic when an NMI watchdog + timeout occurs (or 'nopanic' to override the opposite + default). To disable both hard and soft lockup detectors, + please see 'nowatchdog'. + This is useful when you use a panic=... timeout and + need the box quickly up again. + + netpoll.carrier_timeout= + [NET] Specifies amount of time (in seconds) that + netpoll should wait for a carrier. By default netpoll + waits 4 seconds. + + no387 [BUGS=X86-32] Tells the kernel to use the 387 maths + emulation library even if a 387 maths coprocessor + is present. + + no_console_suspend + [HW] Never suspend the console + Disable suspending of consoles during suspend and + hibernate operations. Once disabled, debugging + messages can reach various consoles while the rest + of the system is being put to sleep (ie, while + debugging driver suspend/resume hooks). This may + not work reliably with all consoles, but is known + to work with serial and VGA consoles. + To facilitate more flexible debugging, we also add + console_suspend, a printk module parameter to control + it. Users could use console_suspend (usually + /sys/module/printk/parameters/console_suspend) to + turn on/off it dynamically. + + noaliencache [MM, NUMA, SLAB] Disables the allocation of alien + caches in the slab allocator. Saves per-node memory, + but will impact performance. + + noalign [KNL,ARM] + + noapic [SMP,APIC] Tells the kernel to not make use of any + IOAPICs that may be present in the system. + + noautogroup Disable scheduler automatic task group creation. + + nobats [PPC] Do not use BATs for mapping kernel lowmem + on "Classic" PPC cores. + + nocache [ARM] + + noclflush [BUGS=X86] Don't use the CLFLUSH instruction + + nodelayacct [KNL] Disable per-task delay accounting + + nodsp [SH] Disable hardware DSP at boot time. + + noefi Disable EFI runtime services support. + + noexec [IA-64] + + noexec [X86] + On X86-32 available only on PAE configured kernels. + noexec=on: enable non-executable mappings (default) + noexec=off: disable non-executable mappings + + nosmap [X86] + Disable SMAP (Supervisor Mode Access Prevention) + even if it is supported by processor. + + nosmep [X86] + Disable SMEP (Supervisor Mode Execution Prevention) + even if it is supported by processor. + + noexec32 [X86-64] + This affects only 32-bit executables. + noexec32=on: enable non-executable mappings (default) + read doesn't imply executable mappings + noexec32=off: disable non-executable mappings + read implies executable mappings + + nofpu [MIPS,SH] Disable hardware FPU at boot time. + + nofxsr [BUGS=X86-32] Disables x86 floating point extended + register save and restore. The kernel will only save + legacy floating-point registers on task switch. + + nohugeiomap [KNL,x86] Disable kernel huge I/O mappings. + + nosmt [KNL,S390] Disable symmetric multithreading (SMT). + Equivalent to smt=1. + + noxsave [BUGS=X86] Disables x86 extended register state save + and restore using xsave. The kernel will fallback to + enabling legacy floating-point and sse state. + + noxsaveopt [X86] Disables xsaveopt used in saving x86 extended + register states. The kernel will fall back to use + xsave to save the states. By using this parameter, + performance of saving the states is degraded because + xsave doesn't support modified optimization while + xsaveopt supports it on xsaveopt enabled systems. + + noxsaves [X86] Disables xsaves and xrstors used in saving and + restoring x86 extended register state in compacted + form of xsave area. The kernel will fall back to use + xsaveopt and xrstor to save and restore the states + in standard form of xsave area. By using this + parameter, xsave area per process might occupy more + memory on xsaves enabled systems. + + nohlt [BUGS=ARM,SH] Tells the kernel that the sleep(SH) or + wfi(ARM) instruction doesn't work correctly and not to + use it. This is also useful when using JTAG debugger. + + no_file_caps Tells the kernel not to honor file capabilities. The + only way then for a file to be executed with privilege + is to be setuid root or executed by root. + + nohalt [IA-64] Tells the kernel not to use the power saving + function PAL_HALT_LIGHT when idle. This increases + power-consumption. On the positive side, it reduces + interrupt wake-up latency, which may improve performance + in certain environments such as networked servers or + real-time systems. + + nohibernate [HIBERNATION] Disable hibernation and resume. + + nohz= [KNL] Boottime enable/disable dynamic ticks + Valid arguments: on, off + Default: on + + nohz_full= [KNL,BOOT] + The argument is a cpu list, as described above. + In kernels built with CONFIG_NO_HZ_FULL=y, set + the specified list of CPUs whose tick will be stopped + whenever possible. The boot CPU will be forced outside + the range to maintain the timekeeping. + The CPUs in this range must also be included in the + rcu_nocbs= set. + + noiotrap [SH] Disables trapped I/O port accesses. + + noirqdebug [X86-32] Disables the code which attempts to detect and + disable unhandled interrupt sources. + + no_timer_check [X86,APIC] Disables the code which tests for + broken timer IRQ sources. + + noisapnp [ISAPNP] Disables ISA PnP code. + + noinitrd [RAM] Tells the kernel not to load any configured + initial RAM disk. + + nointremap [X86-64, Intel-IOMMU] Do not enable interrupt + remapping. + [Deprecated - use intremap=off] + + nointroute [IA-64] + + noinvpcid [X86] Disable the INVPCID cpu feature. + + nojitter [IA-64] Disables jitter checking for ITC timers. + + no-kvmclock [X86,KVM] Disable paravirtualized KVM clock driver + + no-kvmapf [X86,KVM] Disable paravirtualized asynchronous page + fault handling. + + no-steal-acc [X86,KVM] Disable paravirtualized steal time accounting. + steal time is computed, but won't influence scheduler + behaviour + + nolapic [X86-32,APIC] Do not enable or use the local APIC. + + nolapic_timer [X86-32,APIC] Do not use the local APIC timer. + + noltlbs [PPC] Do not use large page/tlb entries for kernel + lowmem mapping on PPC40x and PPC8xx + + nomca [IA-64] Disable machine check abort handling + + nomce [X86-32] Disable Machine Check Exception + + nomfgpt [X86-32] Disable Multi-Function General Purpose + Timer usage (for AMD Geode machines). + + nonmi_ipi [X86] Disable using NMI IPIs during panic/reboot to + shutdown the other cpus. Instead use the REBOOT_VECTOR + irq. + + nomodule Disable module load + + nopat [X86] Disable PAT (page attribute table extension of + pagetables) support. + + norandmaps Don't use address space randomization. Equivalent to + echo 0 > /proc/sys/kernel/randomize_va_space + + noreplace-paravirt [X86,IA-64,PV_OPS] Don't patch paravirt_ops + + noreplace-smp [X86-32,SMP] Don't replace SMP instructions + with UP alternatives + + nordrand [X86] Disable kernel use of the RDRAND and + RDSEED instructions even if they are supported + by the processor. RDRAND and RDSEED are still + available to user space applications. + + noresume [SWSUSP] Disables resume and restores original swap + space. + + no-scroll [VGA] Disables scrollback. + This is required for the Braillex ib80-piezo Braille + reader made by F.H. Papenmeier (Germany). + + nosbagart [IA-64] + + nosep [BUGS=X86-32] Disables x86 SYSENTER/SYSEXIT support. + + nosmp [SMP] Tells an SMP kernel to act as a UP kernel, + and disable the IO APIC. legacy for "maxcpus=0". + + nosoftlockup [KNL] Disable the soft-lockup detector. + + nosync [HW,M68K] Disables sync negotiation for all devices. + + notsc [BUGS=X86-32] Disable Time Stamp Counter + + nowatchdog [KNL] Disable both lockup detectors, i.e. + soft-lockup and NMI watchdog (hard-lockup). + + nowb [ARM] + + nox2apic [X86-64,APIC] Do not enable x2APIC mode. + + cpu0_hotplug [X86] Turn on CPU0 hotplug feature when + CONFIG_BOOTPARAM_HOTPLUG_CPU0 is off. + Some features depend on CPU0. Known dependencies are: + 1. Resume from suspend/hibernate depends on CPU0. + Suspend/hibernate will fail if CPU0 is offline and you + need to online CPU0 before suspend/hibernate. + 2. PIC interrupts also depend on CPU0. CPU0 can't be + removed if a PIC interrupt is detected. + It's said poweroff/reboot may depend on CPU0 on some + machines although I haven't seen such issues so far + after CPU0 is offline on a few tested machines. + If the dependencies are under your control, you can + turn on cpu0_hotplug. + + nptcg= [IA-64] Override max number of concurrent global TLB + purges which is reported from either PAL_VM_SUMMARY or + SAL PALO. + + nr_cpus= [SMP] Maximum number of processors that an SMP kernel + could support. nr_cpus=n : n >= 1 limits the kernel to + support 'n' processors. It could be larger than the + number of already plugged CPU during bootup, later in + runtime you can physically add extra cpu until it reaches + n. So during boot up some boot time memory for per-cpu + variables need be pre-allocated for later physical cpu + hot plugging. + + nr_uarts= [SERIAL] maximum number of UARTs to be registered. + + numa_balancing= [KNL,X86] Enable or disable automatic NUMA balancing. + Allowed values are enable and disable + + numa_zonelist_order= [KNL, BOOT] Select zonelist order for NUMA. + one of ['zone', 'node', 'default'] can be specified + This can be set from sysctl after boot. + See Documentation/sysctl/vm.txt for details. + + ohci1394_dma=early [HW] enable debugging via the ohci1394 driver. + See Documentation/debugging-via-ohci1394.txt for more + info. + + olpc_ec_timeout= [OLPC] ms delay when issuing EC commands + Rather than timing out after 20 ms if an EC + command is not properly ACKed, override the length + of the timeout. We have interrupts disabled while + waiting for the ACK, so if this is set too high + interrupts *may* be lost! + + omap_mux= [OMAP] Override bootloader pin multiplexing. + Format: ... + For example, to override I2C bus2: + omap_mux=i2c2_scl.i2c2_scl=0x100,i2c2_sda.i2c2_sda=0x100 + + oprofile.timer= [HW] + Use timer interrupt instead of performance counters + + oprofile.cpu_type= Force an oprofile cpu type + This might be useful if you have an older oprofile + userland or if you want common events. + Format: { arch_perfmon } + arch_perfmon: [X86] Force use of architectural + perfmon on Intel CPUs instead of the + CPU specific event set. + timer: [X86] Force use of architectural NMI + timer mode (see also oprofile.timer + for generic hr timer mode) + + oops=panic Always panic on oopses. Default is to just kill the + process, but there is a small probability of + deadlocking the machine. + This will also cause panics on machine check exceptions. + Useful together with panic=30 to trigger a reboot. + + OSS [HW,OSS] + See Documentation/sound/oss/oss-parameters.txt + + page_owner= [KNL] Boot-time page_owner enabling option. + Storage of the information about who allocated + each page is disabled in default. With this switch, + we can turn it on. + on: enable the feature + + page_poison= [KNL] Boot-time parameter changing the state of + poisoning on the buddy allocator. + off: turn off poisoning + on: turn on poisoning + + panic= [KNL] Kernel behaviour on panic: delay + timeout > 0: seconds before rebooting + timeout = 0: wait forever + timeout < 0: reboot immediately + Format: + + panic_on_warn panic() instead of WARN(). Useful to cause kdump + on a WARN(). + + crash_kexec_post_notifiers + Run kdump after running panic-notifiers and dumping + kmsg. This only for the users who doubt kdump always + succeeds in any situation. + Note that this also increases risks of kdump failure, + because some panic notifiers can make the crashed + kernel more unstable. + + parkbd.port= [HW] Parallel port number the keyboard adapter is + connected to, default is 0. + Format: + parkbd.mode= [HW] Parallel port keyboard adapter mode of operation, + 0 for XT, 1 for AT (default is AT). + Format: + + parport= [HW,PPT] Specify parallel ports. 0 disables. + Format: { 0 | auto | 0xBBB[,IRQ[,DMA]] } + Use 'auto' to force the driver to use any + IRQ/DMA settings detected (the default is to + ignore detected IRQ/DMA settings because of + possible conflicts). You can specify the base + address, IRQ, and DMA settings; IRQ and DMA + should be numbers, or 'auto' (for using detected + settings on that particular port), or 'nofifo' + (to avoid using a FIFO even if it is detected). + Parallel ports are assigned in the order they + are specified on the command line, starting + with parport0. + + parport_init_mode= [HW,PPT] + Configure VIA parallel port to operate in + a specific mode. This is necessary on Pegasos + computer where firmware has no options for setting + up parallel port mode and sets it to spp. + Currently this function knows 686a and 8231 chips. + Format: [spp|ps2|epp|ecp|ecpepp] + + pause_on_oops= + Halt all CPUs after the first oops has been printed for + the specified number of seconds. This is to be used if + your oopses keep scrolling off the screen. + + pcbit= [HW,ISDN] + + pcd. [PARIDE] + See header of drivers/block/paride/pcd.c. + See also Documentation/blockdev/paride.txt. + + pci=option[,option...] [PCI] various PCI subsystem options: + earlydump [X86] dump PCI config space before the kernel + changes anything + off [X86] don't probe for the PCI bus + bios [X86-32] force use of PCI BIOS, don't access + the hardware directly. Use this if your machine + has a non-standard PCI host bridge. + nobios [X86-32] disallow use of PCI BIOS, only direct + hardware access methods are allowed. Use this + if you experience crashes upon bootup and you + suspect they are caused by the BIOS. + conf1 [X86] Force use of PCI Configuration Access + Mechanism 1 (config address in IO port 0xCF8, + data in IO port 0xCFC, both 32-bit). + conf2 [X86] Force use of PCI Configuration Access + Mechanism 2 (IO port 0xCF8 is an 8-bit port for + the function, IO port 0xCFA, also 8-bit, sets + bus number. The config space is then accessed + through ports 0xC000-0xCFFF). + See http://wiki.osdev.org/PCI for more info + on the configuration access mechanisms. + noaer [PCIE] If the PCIEAER kernel config parameter is + enabled, this kernel boot option can be used to + disable the use of PCIE advanced error reporting. + nodomains [PCI] Disable support for multiple PCI + root domains (aka PCI segments, in ACPI-speak). + nommconf [X86] Disable use of MMCONFIG for PCI + Configuration + check_enable_amd_mmconf [X86] check for and enable + properly configured MMIO access to PCI + config space on AMD family 10h CPU + nomsi [MSI] If the PCI_MSI kernel config parameter is + enabled, this kernel boot option can be used to + disable the use of MSI interrupts system-wide. + noioapicquirk [APIC] Disable all boot interrupt quirks. + Safety option to keep boot IRQs enabled. This + should never be necessary. + ioapicreroute [APIC] Enable rerouting of boot IRQs to the + primary IO-APIC for bridges that cannot disable + boot IRQs. This fixes a source of spurious IRQs + when the system masks IRQs. + noioapicreroute [APIC] Disable workaround that uses the + boot IRQ equivalent of an IRQ that connects to + a chipset where boot IRQs cannot be disabled. + The opposite of ioapicreroute. + biosirq [X86-32] Use PCI BIOS calls to get the interrupt + routing table. These calls are known to be buggy + on several machines and they hang the machine + when used, but on other computers it's the only + way to get the interrupt routing table. Try + this option if the kernel is unable to allocate + IRQs or discover secondary PCI buses on your + motherboard. + rom [X86] Assign address space to expansion ROMs. + Use with caution as certain devices share + address decoders between ROMs and other + resources. + norom [X86] Do not assign address space to + expansion ROMs that do not already have + BIOS assigned address ranges. + nobar [X86] Do not assign address space to the + BARs that weren't assigned by the BIOS. + irqmask=0xMMMM [X86] Set a bit mask of IRQs allowed to be + assigned automatically to PCI devices. You can + make the kernel exclude IRQs of your ISA cards + this way. + pirqaddr=0xAAAAA [X86] Specify the physical address + of the PIRQ table (normally generated + by the BIOS) if it is outside the + F0000h-100000h range. + lastbus=N [X86] Scan all buses thru bus #N. Can be + useful if the kernel is unable to find your + secondary buses and you want to tell it + explicitly which ones they are. + assign-busses [X86] Always assign all PCI bus + numbers ourselves, overriding + whatever the firmware may have done. + usepirqmask [X86] Honor the possible IRQ mask stored + in the BIOS $PIR table. This is needed on + some systems with broken BIOSes, notably + some HP Pavilion N5400 and Omnibook XE3 + notebooks. This will have no effect if ACPI + IRQ routing is enabled. + noacpi [X86] Do not use ACPI for IRQ routing + or for PCI scanning. + use_crs [X86] Use PCI host bridge window information + from ACPI. On BIOSes from 2008 or later, this + is enabled by default. If you need to use this, + please report a bug. + nocrs [X86] Ignore PCI host bridge windows from ACPI. + If you need to use this, please report a bug. + routeirq Do IRQ routing for all PCI devices. + This is normally done in pci_enable_device(), + so this option is a temporary workaround + for broken drivers that don't call it. + skip_isa_align [X86] do not align io start addr, so can + handle more pci cards + noearly [X86] Don't do any early type 1 scanning. + This might help on some broken boards which + machine check when some devices' config space + is read. But various workarounds are disabled + and some IOMMU drivers will not work. + bfsort Sort PCI devices into breadth-first order. + This sorting is done to get a device + order compatible with older (<= 2.4) kernels. + nobfsort Don't sort PCI devices into breadth-first order. + pcie_bus_tune_off Disable PCIe MPS (Max Payload Size) + tuning and use the BIOS-configured MPS defaults. + pcie_bus_safe Set every device's MPS to the largest value + supported by all devices below the root complex. + pcie_bus_perf Set device MPS to the largest allowable MPS + based on its parent bus. Also set MRRS (Max + Read Request Size) to the largest supported + value (no larger than the MPS that the device + or bus can support) for best performance. + pcie_bus_peer2peer Set every device's MPS to 128B, which + every device is guaranteed to support. This + configuration allows peer-to-peer DMA between + any pair of devices, possibly at the cost of + reduced performance. This also guarantees + that hot-added devices will work. + cbiosize=nn[KMG] The fixed amount of bus space which is + reserved for the CardBus bridge's IO window. + The default value is 256 bytes. + cbmemsize=nn[KMG] The fixed amount of bus space which is + reserved for the CardBus bridge's memory + window. The default value is 64 megabytes. + resource_alignment= + Format: + [@][:]:.[; ...] + [@]pci::\ + [::][; ...] + Specifies alignment and device to reassign + aligned memory resources. + If is not specified, + PAGE_SIZE is used as alignment. + PCI-PCI bridge can be specified, if resource + windows need to be expanded. + To specify the alignment for several + instances of a device, the PCI vendor, + device, subvendor, and subdevice may be + specified, e.g., 4096@pci:8086:9c22:103c:198f + ecrc= Enable/disable PCIe ECRC (transaction layer + end-to-end CRC checking). + bios: Use BIOS/firmware settings. This is the + the default. + off: Turn ECRC off + on: Turn ECRC on. + hpiosize=nn[KMG] The fixed amount of bus space which is + reserved for hotplug bridge's IO window. + Default size is 256 bytes. + hpmemsize=nn[KMG] The fixed amount of bus space which is + reserved for hotplug bridge's memory window. + Default size is 2 megabytes. + hpbussize=nn The minimum amount of additional bus numbers + reserved for buses below a hotplug bridge. + Default is 1. + realloc= Enable/disable reallocating PCI bridge resources + if allocations done by BIOS are too small to + accommodate resources required by all child + devices. + off: Turn realloc off + on: Turn realloc on + realloc same as realloc=on + noari do not use PCIe ARI. + pcie_scan_all Scan all possible PCIe devices. Otherwise we + only look for one device below a PCIe downstream + port. + + pcie_aspm= [PCIE] Forcibly enable or disable PCIe Active State Power + Management. + off Disable ASPM. + force Enable ASPM even on devices that claim not to support it. + WARNING: Forcing ASPM on may cause system lockups. + + pcie_hp= [PCIE] PCI Express Hotplug driver options: + nomsi Do not use MSI for PCI Express Native Hotplug (this + makes all PCIe ports use INTx for hotplug services). + + pcie_ports= [PCIE] PCIe ports handling: + auto Ask the BIOS whether or not to use native PCIe services + associated with PCIe ports (PME, hot-plug, AER). Use + them only if that is allowed by the BIOS. + native Use native PCIe services associated with PCIe ports + unconditionally. + compat Treat PCIe ports as PCI-to-PCI bridges, disable the PCIe + ports driver. + + pcie_port_pm= [PCIE] PCIe port power management handling: + off Disable power management of all PCIe ports + force Forcibly enable power management of all PCIe ports + + pcie_pme= [PCIE,PM] Native PCIe PME signaling options: + nomsi Do not use MSI for native PCIe PME signaling (this makes + all PCIe root ports use INTx for all services). + + pcmv= [HW,PCMCIA] BadgePAD 4 + + pd_ignore_unused + [PM] + Keep all power-domains already enabled by bootloader on, + even if no driver has claimed them. This is useful + for debug and development, but should not be + needed on a platform with proper driver support. + + pd. [PARIDE] + See Documentation/blockdev/paride.txt. + + pdcchassis= [PARISC,HW] Disable/Enable PDC Chassis Status codes at + boot time. + Format: { 0 | 1 } + See arch/parisc/kernel/pdc_chassis.c + + percpu_alloc= Select which percpu first chunk allocator to use. + Currently supported values are "embed" and "page". + Archs may support subset or none of the selections. + See comments in mm/percpu.c for details on each + allocator. This parameter is primarily for debugging + and performance comparison. + + pf. [PARIDE] + See Documentation/blockdev/paride.txt. + + pg. [PARIDE] + See Documentation/blockdev/paride.txt. + + pirq= [SMP,APIC] Manual mp-table setup + See Documentation/x86/i386/IO-APIC.txt. + + plip= [PPT,NET] Parallel port network link + Format: { parport | timid | 0 } + See also Documentation/parport.txt. + + pmtmr= [X86] Manual setup of pmtmr I/O Port. + Override pmtimer IOPort with a hex value. + e.g. pmtmr=0x508 + + pnp.debug=1 [PNP] + Enable PNP debug messages (depends on the + CONFIG_PNP_DEBUG_MESSAGES option). Change at run-time + via /sys/module/pnp/parameters/debug. We always show + current resource usage; turning this on also shows + possible settings and some assignment information. + + pnpacpi= [ACPI] + { off } + + pnpbios= [ISAPNP] + { on | off | curr | res | no-curr | no-res } + + pnp_reserve_irq= + [ISAPNP] Exclude IRQs for the autoconfiguration + + pnp_reserve_dma= + [ISAPNP] Exclude DMAs for the autoconfiguration + + pnp_reserve_io= [ISAPNP] Exclude I/O ports for the autoconfiguration + Ranges are in pairs (I/O port base and size). + + pnp_reserve_mem= + [ISAPNP] Exclude memory regions for the + autoconfiguration. + Ranges are in pairs (memory base and size). + + ports= [IP_VS_FTP] IPVS ftp helper module + Default is 21. + Up to 8 (IP_VS_APP_MAX_PORTS) ports + may be specified. + Format: ,.... + + ppc_strict_facility_enable + [PPC] This option catches any kernel floating point, + Altivec, VSX and SPE outside of regions specifically + allowed (eg kernel_enable_fpu()/kernel_disable_fpu()). + There is some performance impact when enabling this. + + print-fatal-signals= + [KNL] debug: print fatal signals + + If enabled, warn about various signal handling + related application anomalies: too many signals, + too many POSIX.1 timers, fatal signals causing a + coredump - etc. + + If you hit the warning due to signal overflow, + you might want to try "ulimit -i unlimited". + + default: off. + + printk.always_kmsg_dump= + Trigger kmsg_dump for cases other than kernel oops or + panics + Format: (1/Y/y=enable, 0/N/n=disable) + default: disabled + + printk.devkmsg={on,off,ratelimit} + Control writing to /dev/kmsg. + on - unlimited logging to /dev/kmsg from userspace + off - logging to /dev/kmsg disabled + ratelimit - ratelimit the logging + Default: ratelimit + + printk.time= Show timing data prefixed to each printk message line + Format: (1/Y/y=enable, 0/N/n=disable) + + processor.max_cstate= [HW,ACPI] + Limit processor to maximum C-state + max_cstate=9 overrides any DMI blacklist limit. + + processor.nocst [HW,ACPI] + Ignore the _CST method to determine C-states, + instead using the legacy FADT method + + profile= [KNL] Enable kernel profiling via /proc/profile + Format: [schedule,] + Param: "schedule" - profile schedule points. + Param: - step/bucket size as a power of 2 for + statistical time based profiling. + Param: "sleep" - profile D-state sleeping (millisecs). + Requires CONFIG_SCHEDSTATS + Param: "kvm" - profile VM exits. + + prompt_ramdisk= [RAM] List of RAM disks to prompt for floppy disk + before loading. + See Documentation/blockdev/ramdisk.txt. + + psmouse.proto= [HW,MOUSE] Highest PS2 mouse protocol extension to + probe for; one of (bare|imps|exps|lifebook|any). + psmouse.rate= [HW,MOUSE] Set desired mouse report rate, in reports + per second. + psmouse.resetafter= [HW,MOUSE] + Try to reset the device after so many bad packets + (0 = never). + psmouse.resolution= + [HW,MOUSE] Set desired mouse resolution, in dpi. + psmouse.smartscroll= + [HW,MOUSE] Controls Logitech smartscroll autorepeat. + 0 = disabled, 1 = enabled (default). + + pstore.backend= Specify the name of the pstore backend to use + + pt. [PARIDE] + See Documentation/blockdev/paride.txt. + + pty.legacy_count= + [KNL] Number of legacy pty's. Overwrites compiled-in + default number. + + quiet [KNL] Disable most log messages + + r128= [HW,DRM] + + raid= [HW,RAID] + See Documentation/md.txt. + + ramdisk_size= [RAM] Sizes of RAM disks in kilobytes + See Documentation/blockdev/ramdisk.txt. + + rcu_nocbs= [KNL] + The argument is a cpu list, as described above. + + In kernels built with CONFIG_RCU_NOCB_CPU=y, set + the specified list of CPUs to be no-callback CPUs. + Invocation of these CPUs' RCU callbacks will + be offloaded to "rcuox/N" kthreads created for + that purpose, where "x" is "b" for RCU-bh, "p" + for RCU-preempt, and "s" for RCU-sched, and "N" + is the CPU number. This reduces OS jitter on the + offloaded CPUs, which can be useful for HPC and + real-time workloads. It can also improve energy + efficiency for asymmetric multiprocessors. + + rcu_nocb_poll [KNL] + Rather than requiring that offloaded CPUs + (specified by rcu_nocbs= above) explicitly + awaken the corresponding "rcuoN" kthreads, + make these kthreads poll for callbacks. + This improves the real-time response for the + offloaded CPUs by relieving them of the need to + wake up the corresponding kthread, but degrades + energy efficiency by requiring that the kthreads + periodically wake up to do the polling. + + rcutree.blimit= [KNL] + Set maximum number of finished RCU callbacks to + process in one batch. + + rcutree.dump_tree= [KNL] + Dump the structure of the rcu_node combining tree + out at early boot. This is used for diagnostic + purposes, to verify correct tree setup. + + rcutree.gp_cleanup_delay= [KNL] + Set the number of jiffies to delay each step of + RCU grace-period cleanup. This only has effect + when CONFIG_RCU_TORTURE_TEST_SLOW_CLEANUP is set. + + rcutree.gp_init_delay= [KNL] + Set the number of jiffies to delay each step of + RCU grace-period initialization. This only has + effect when CONFIG_RCU_TORTURE_TEST_SLOW_INIT + is set. + + rcutree.gp_preinit_delay= [KNL] + Set the number of jiffies to delay each step of + RCU grace-period pre-initialization, that is, + the propagation of recent CPU-hotplug changes up + the rcu_node combining tree. This only has effect + when CONFIG_RCU_TORTURE_TEST_SLOW_PREINIT is set. + + rcutree.rcu_fanout_exact= [KNL] + Disable autobalancing of the rcu_node combining + tree. This is used by rcutorture, and might + possibly be useful for architectures having high + cache-to-cache transfer latencies. + + rcutree.rcu_fanout_leaf= [KNL] + Change the number of CPUs assigned to each + leaf rcu_node structure. Useful for very + large systems, which will choose the value 64, + and for NUMA systems with large remote-access + latencies, which will choose a value aligned + with the appropriate hardware boundaries. + + rcutree.jiffies_till_sched_qs= [KNL] + Set required age in jiffies for a + given grace period before RCU starts + soliciting quiescent-state help from + rcu_note_context_switch(). + + rcutree.jiffies_till_first_fqs= [KNL] + Set delay from grace-period initialization to + first attempt to force quiescent states. + Units are jiffies, minimum value is zero, + and maximum value is HZ. + + rcutree.jiffies_till_next_fqs= [KNL] + Set delay between subsequent attempts to force + quiescent states. Units are jiffies, minimum + value is one, and maximum value is HZ. + + rcutree.kthread_prio= [KNL,BOOT] + Set the SCHED_FIFO priority of the RCU per-CPU + kthreads (rcuc/N). This value is also used for + the priority of the RCU boost threads (rcub/N) + and for the RCU grace-period kthreads (rcu_bh, + rcu_preempt, and rcu_sched). If RCU_BOOST is + set, valid values are 1-99 and the default is 1 + (the least-favored priority). Otherwise, when + RCU_BOOST is not set, valid values are 0-99 and + the default is zero (non-realtime operation). + + rcutree.rcu_nocb_leader_stride= [KNL] + Set the number of NOCB kthread groups, which + defaults to the square root of the number of + CPUs. Larger numbers reduces the wakeup overhead + on the per-CPU grace-period kthreads, but increases + that same overhead on each group's leader. + + rcutree.qhimark= [KNL] + Set threshold of queued RCU callbacks beyond which + batch limiting is disabled. + + rcutree.qlowmark= [KNL] + Set threshold of queued RCU callbacks below which + batch limiting is re-enabled. + + rcutree.rcu_idle_gp_delay= [KNL] + Set wakeup interval for idle CPUs that have + RCU callbacks (RCU_FAST_NO_HZ=y). + + rcutree.rcu_idle_lazy_gp_delay= [KNL] + Set wakeup interval for idle CPUs that have + only "lazy" RCU callbacks (RCU_FAST_NO_HZ=y). + Lazy RCU callbacks are those which RCU can + prove do nothing more than free memory. + + rcuperf.gp_exp= [KNL] + Measure performance of expedited synchronous + grace-period primitives. + + rcuperf.holdoff= [KNL] + Set test-start holdoff period. The purpose of + this parameter is to delay the start of the + test until boot completes in order to avoid + interference. + + rcuperf.nreaders= [KNL] + Set number of RCU readers. The value -1 selects + N, where N is the number of CPUs. A value + "n" less than -1 selects N-n+1, where N is again + the number of CPUs. For example, -2 selects N + (the number of CPUs), -3 selects N+1, and so on. + A value of "n" less than or equal to -N selects + a single reader. + + rcuperf.nwriters= [KNL] + Set number of RCU writers. The values operate + the same as for rcuperf.nreaders. + N, where N is the number of CPUs + + rcuperf.perf_runnable= [BOOT] + Start rcuperf running at boot time. + + rcuperf.shutdown= [KNL] + Shut the system down after performance tests + complete. This is useful for hands-off automated + testing. + + rcuperf.perf_type= [KNL] + Specify the RCU implementation to test. + + rcuperf.verbose= [KNL] + Enable additional printk() statements. + + rcutorture.cbflood_inter_holdoff= [KNL] + Set holdoff time (jiffies) between successive + callback-flood tests. + + rcutorture.cbflood_intra_holdoff= [KNL] + Set holdoff time (jiffies) between successive + bursts of callbacks within a given callback-flood + test. + + rcutorture.cbflood_n_burst= [KNL] + Set the number of bursts making up a given + callback-flood test. Set this to zero to + disable callback-flood testing. + + rcutorture.cbflood_n_per_burst= [KNL] + Set the number of callbacks to be registered + in a given burst of a callback-flood test. + + rcutorture.fqs_duration= [KNL] + Set duration of force_quiescent_state bursts + in microseconds. + + rcutorture.fqs_holdoff= [KNL] + Set holdoff time within force_quiescent_state bursts + in microseconds. + + rcutorture.fqs_stutter= [KNL] + Set wait time between force_quiescent_state bursts + in seconds. + + rcutorture.gp_cond= [KNL] + Use conditional/asynchronous update-side + primitives, if available. + + rcutorture.gp_exp= [KNL] + Use expedited update-side primitives, if available. + + rcutorture.gp_normal= [KNL] + Use normal (non-expedited) asynchronous + update-side primitives, if available. + + rcutorture.gp_sync= [KNL] + Use normal (non-expedited) synchronous + update-side primitives, if available. If all + of rcutorture.gp_cond=, rcutorture.gp_exp=, + rcutorture.gp_normal=, and rcutorture.gp_sync= + are zero, rcutorture acts as if is interpreted + they are all non-zero. + + rcutorture.n_barrier_cbs= [KNL] + Set callbacks/threads for rcu_barrier() testing. + + rcutorture.nfakewriters= [KNL] + Set number of concurrent RCU writers. These just + stress RCU, they don't participate in the actual + test, hence the "fake". + + rcutorture.nreaders= [KNL] + Set number of RCU readers. The value -1 selects + N-1, where N is the number of CPUs. A value + "n" less than -1 selects N-n-2, where N is again + the number of CPUs. For example, -2 selects N + (the number of CPUs), -3 selects N+1, and so on. + + rcutorture.object_debug= [KNL] + Enable debug-object double-call_rcu() testing. + + rcutorture.onoff_holdoff= [KNL] + Set time (s) after boot for CPU-hotplug testing. + + rcutorture.onoff_interval= [KNL] + Set time (s) between CPU-hotplug operations, or + zero to disable CPU-hotplug testing. + + rcutorture.shuffle_interval= [KNL] + Set task-shuffle interval (s). Shuffling tasks + allows some CPUs to go into dyntick-idle mode + during the rcutorture test. + + rcutorture.shutdown_secs= [KNL] + Set time (s) after boot system shutdown. This + is useful for hands-off automated testing. + + rcutorture.stall_cpu= [KNL] + Duration of CPU stall (s) to test RCU CPU stall + warnings, zero to disable. + + rcutorture.stall_cpu_holdoff= [KNL] + Time to wait (s) after boot before inducing stall. + + rcutorture.stat_interval= [KNL] + Time (s) between statistics printk()s. + + rcutorture.stutter= [KNL] + Time (s) to stutter testing, for example, specifying + five seconds causes the test to run for five seconds, + wait for five seconds, and so on. This tests RCU's + ability to transition abruptly to and from idle. + + rcutorture.test_boost= [KNL] + Test RCU priority boosting? 0=no, 1=maybe, 2=yes. + "Maybe" means test if the RCU implementation + under test support RCU priority boosting. + + rcutorture.test_boost_duration= [KNL] + Duration (s) of each individual boost test. + + rcutorture.test_boost_interval= [KNL] + Interval (s) between each boost test. + + rcutorture.test_no_idle_hz= [KNL] + Test RCU's dyntick-idle handling. See also the + rcutorture.shuffle_interval parameter. + + rcutorture.torture_runnable= [BOOT] + Start rcutorture running at boot time. + + rcutorture.torture_type= [KNL] + Specify the RCU implementation to test. + + rcutorture.verbose= [KNL] + Enable additional printk() statements. + + rcupdate.rcu_cpu_stall_suppress= [KNL] + Suppress RCU CPU stall warning messages. + + rcupdate.rcu_cpu_stall_timeout= [KNL] + Set timeout for RCU CPU stall warning messages. + + rcupdate.rcu_expedited= [KNL] + Use expedited grace-period primitives, for + example, synchronize_rcu_expedited() instead + of synchronize_rcu(). This reduces latency, + but can increase CPU utilization, degrade + real-time latency, and degrade energy efficiency. + No effect on CONFIG_TINY_RCU kernels. + + rcupdate.rcu_normal= [KNL] + Use only normal grace-period primitives, + for example, synchronize_rcu() instead of + synchronize_rcu_expedited(). This improves + real-time latency, CPU utilization, and + energy efficiency, but can expose users to + increased grace-period latency. This parameter + overrides rcupdate.rcu_expedited. No effect on + CONFIG_TINY_RCU kernels. + + rcupdate.rcu_normal_after_boot= [KNL] + Once boot has completed (that is, after + rcu_end_inkernel_boot() has been invoked), use + only normal grace-period primitives. No effect + on CONFIG_TINY_RCU kernels. + + rcupdate.rcu_task_stall_timeout= [KNL] + Set timeout in jiffies for RCU task stall warning + messages. Disable with a value less than or equal + to zero. + + rcupdate.rcu_self_test= [KNL] + Run the RCU early boot self tests + + rcupdate.rcu_self_test_bh= [KNL] + Run the RCU bh early boot self tests + + rcupdate.rcu_self_test_sched= [KNL] + Run the RCU sched early boot self tests + + rdinit= [KNL] + Format: + Run specified binary instead of /init from the ramdisk, + used for early userspace startup. See initrd. + + reboot= [KNL] + Format (x86 or x86_64): + [w[arm] | c[old] | h[ard] | s[oft] | g[pio]] \ + [[,]s[mp]#### \ + [[,]b[ios] | a[cpi] | k[bd] | t[riple] | e[fi] | p[ci]] \ + [[,]f[orce] + Where reboot_mode is one of warm (soft) or cold (hard) or gpio, + reboot_type is one of bios, acpi, kbd, triple, efi, or pci, + reboot_force is either force or not specified, + reboot_cpu is s[mp]#### with #### being the processor + to be used for rebooting. + + relax_domain_level= + [KNL, SMP] Set scheduler's default relax_domain_level. + See Documentation/cgroup-v1/cpusets.txt. + + relative_sleep_states= + [SUSPEND] Use sleep state labeling where the deepest + state available other than hibernation is always "mem". + Format: { "0" | "1" } + 0 -- Traditional sleep state labels. + 1 -- Relative sleep state labels. + + reserve= [KNL,BUGS] Force the kernel to ignore some iomem area + + reservetop= [X86-32] + Format: nn[KMG] + Reserves a hole at the top of the kernel virtual + address space. + + reservelow= [X86] + Format: nn[K] + Set the amount of memory to reserve for BIOS at + the bottom of the address space. + + reset_devices [KNL] Force drivers to reset the underlying device + during initialization. + + resume= [SWSUSP] + Specify the partition device for software suspend + Format: + {/dev/ | PARTUUID= | : | } + + resume_offset= [SWSUSP] + Specify the offset from the beginning of the partition + given by "resume=" at which the swap header is located, + in units (needed only for swap files). + See Documentation/power/swsusp-and-swap-files.txt + + resumedelay= [HIBERNATION] Delay (in seconds) to pause before attempting to + read the resume files + + resumewait [HIBERNATION] Wait (indefinitely) for resume device to show up. + Useful for devices that are detected asynchronously + (e.g. USB and MMC devices). + + hibernate= [HIBERNATION] + noresume Don't check if there's a hibernation image + present during boot. + nocompress Don't compress/decompress hibernation images. + no Disable hibernation and resume. + protect_image Turn on image protection during restoration + (that will set all pages holding image data + during restoration read-only). + + retain_initrd [RAM] Keep initrd memory after extraction + + rfkill.default_state= + 0 "airplane mode". All wifi, bluetooth, wimax, gps, fm, + etc. communication is blocked by default. + 1 Unblocked. + + rfkill.master_switch_mode= + 0 The "airplane mode" button does nothing. + 1 The "airplane mode" button toggles between everything + blocked and the previous configuration. + 2 The "airplane mode" button toggles between everything + blocked and everything unblocked. + + rhash_entries= [KNL,NET] + Set number of hash buckets for route cache + + ro [KNL] Mount root device read-only on boot + + rodata= [KNL] + on Mark read-only kernel memory as read-only (default). + off Leave read-only kernel memory writable for debugging. + + rockchip.usb_uart + Enable the uart passthrough on the designated usb port + on Rockchip SoCs. When active, the signals of the + debug-uart get routed to the D+ and D- pins of the usb + port and the regular usb controller gets disabled. + + root= [KNL] Root filesystem + See name_to_dev_t comment in init/do_mounts.c. + + rootdelay= [KNL] Delay (in seconds) to pause before attempting to + mount the root filesystem + + rootflags= [KNL] Set root filesystem mount option string + + rootfstype= [KNL] Set root filesystem type + + rootwait [KNL] Wait (indefinitely) for root device to show up. + Useful for devices that are detected asynchronously + (e.g. USB and MMC devices). + + rproc_mem=nn[KMG][@address] + [KNL,ARM,CMA] Remoteproc physical memory block. + Memory area to be used by remote processor image, + managed by CMA. + + rw [KNL] Mount root device read-write on boot + + S [KNL] Run init in single mode + + s390_iommu= [HW,S390] + Set s390 IOTLB flushing mode + strict + With strict flushing every unmap operation will result in + an IOTLB flush. Default is lazy flushing before reuse, + which is faster. + + sa1100ir [NET] + See drivers/net/irda/sa1100_ir.c. + + sbni= [NET] Granch SBNI12 leased line adapter + + sched_debug [KNL] Enables verbose scheduler debug messages. + + schedstats= [KNL,X86] Enable or disable scheduled statistics. + Allowed values are enable and disable. This feature + incurs a small amount of overhead in the scheduler + but is useful for debugging and performance tuning. + + skew_tick= [KNL] Offset the periodic timer tick per cpu to mitigate + xtime_lock contention on larger systems, and/or RCU lock + contention on all systems with CONFIG_MAXSMP set. + Format: { "0" | "1" } + 0 -- disable. (may be 1 via CONFIG_CMDLINE="skew_tick=1" + 1 -- enable. + Note: increases power consumption, thus should only be + enabled if running jitter sensitive (HPC/RT) workloads. + + security= [SECURITY] Choose a security module to enable at boot. + If this boot parameter is not specified, only the first + security module asking for security registration will be + loaded. An invalid security module name will be treated + as if no module has been chosen. + + selinux= [SELINUX] Disable or enable SELinux at boot time. + Format: { "0" | "1" } + See security/selinux/Kconfig help text. + 0 -- disable. + 1 -- enable. + Default value is set via kernel config option. + If enabled at boot time, /selinux/disable can be used + later to disable prior to initial policy load. + + apparmor= [APPARMOR] Disable or enable AppArmor at boot time + Format: { "0" | "1" } + See security/apparmor/Kconfig help text + 0 -- disable. + 1 -- enable. + Default value is set via kernel config option. + + serialnumber [BUGS=X86-32] + + shapers= [NET] + Maximal number of shapers. + + show_msr= [x86] show boot-time MSR settings + Format: { } + Show boot-time (BIOS-initialized) MSR settings. + The parameter means the number of CPUs to show, + for example 1 means boot CPU only. + + simeth= [IA-64] + simscsi= + + slram= [HW,MTD] + + slab_nomerge [MM] + Disable merging of slabs with similar size. May be + necessary if there is some reason to distinguish + allocs to different slabs. Debug options disable + merging on their own. + For more information see Documentation/vm/slub.txt. + + slab_max_order= [MM, SLAB] + Determines the maximum allowed order for slabs. + A high setting may cause OOMs due to memory + fragmentation. Defaults to 1 for systems with + more than 32MB of RAM, 0 otherwise. + + slub_debug[=options[,slabs]] [MM, SLUB] + Enabling slub_debug allows one to determine the + culprit if slab objects become corrupted. Enabling + slub_debug can create guard zones around objects and + may poison objects when not in use. Also tracks the + last alloc / free. For more information see + Documentation/vm/slub.txt. + + slub_max_order= [MM, SLUB] + Determines the maximum allowed order for slabs. + A high setting may cause OOMs due to memory + fragmentation. For more information see + Documentation/vm/slub.txt. + + slub_min_objects= [MM, SLUB] + The minimum number of objects per slab. SLUB will + increase the slab order up to slub_max_order to + generate a sufficiently large slab able to contain + the number of objects indicated. The higher the number + of objects the smaller the overhead of tracking slabs + and the less frequently locks need to be acquired. + For more information see Documentation/vm/slub.txt. + + slub_min_order= [MM, SLUB] + Determines the minimum page order for slabs. Must be + lower than slub_max_order. + For more information see Documentation/vm/slub.txt. + + slub_nomerge [MM, SLUB] + Same with slab_nomerge. This is supported for legacy. + See slab_nomerge for more information. + + smart2= [HW] + Format: [,[,...,]] + + smsc-ircc2.nopnp [HW] Don't use PNP to discover SMC devices + smsc-ircc2.ircc_cfg= [HW] Device configuration I/O port + smsc-ircc2.ircc_sir= [HW] SIR base I/O port + smsc-ircc2.ircc_fir= [HW] FIR base I/O port + smsc-ircc2.ircc_irq= [HW] IRQ line + smsc-ircc2.ircc_dma= [HW] DMA channel + smsc-ircc2.ircc_transceiver= [HW] Transceiver type: + 0: Toshiba Satellite 1800 (GP data pin select) + 1: Fast pin select (default) + 2: ATC IRMode + + smt [KNL,S390] Set the maximum number of threads (logical + CPUs) to use per physical CPU on systems capable of + symmetric multithreading (SMT). Will be capped to the + actual hardware limit. + Format: + Default: -1 (no limit) + + softlockup_panic= + [KNL] Should the soft-lockup detector generate panics. + Format: + + softlockup_all_cpu_backtrace= + [KNL] Should the soft-lockup detector generate + backtraces on all cpus. + Format: + + sonypi.*= [HW] Sony Programmable I/O Control Device driver + See Documentation/laptops/sonypi.txt + + spia_io_base= [HW,MTD] + spia_fio_base= + spia_pedr= + spia_peddr= + + stacktrace [FTRACE] + Enabled the stack tracer on boot up. + + stacktrace_filter=[function-list] + [FTRACE] Limit the functions that the stack tracer + will trace at boot up. function-list is a comma separated + list of functions. This list can be changed at run + time by the stack_trace_filter file in the debugfs + tracing directory. Note, this enables stack tracing + and the stacktrace above is not needed. + + sti= [PARISC,HW] + Format: + Set the STI (builtin display/keyboard on the HP-PARISC + machines) console (graphic card) which should be used + as the initial boot-console. + See also comment in drivers/video/console/sticore.c. + + sti_font= [HW] + See comment in drivers/video/console/sticore.c. + + stifb= [HW] + Format: bpp:[:[:...]] + + sunrpc.min_resvport= + sunrpc.max_resvport= + [NFS,SUNRPC] + SunRPC servers often require that client requests + originate from a privileged port (i.e. a port in the + range 0 < portnr < 1024). + An administrator who wishes to reserve some of these + ports for other uses may adjust the range that the + kernel's sunrpc client considers to be privileged + using these two parameters to set the minimum and + maximum port values. + + sunrpc.svc_rpc_per_connection_limit= + [NFS,SUNRPC] + Limit the number of requests that the server will + process in parallel from a single connection. + The default value is 0 (no limit). + + sunrpc.pool_mode= + [NFS] + Control how the NFS server code allocates CPUs to + service thread pools. Depending on how many NICs + you have and where their interrupts are bound, this + option will affect which CPUs will do NFS serving. + Note: this parameter cannot be changed while the + NFS server is running. + + auto the server chooses an appropriate mode + automatically using heuristics + global a single global pool contains all CPUs + percpu one pool for each CPU + pernode one pool for each NUMA node (equivalent + to global on non-NUMA machines) + + sunrpc.tcp_slot_table_entries= + sunrpc.udp_slot_table_entries= + [NFS,SUNRPC] + Sets the upper limit on the number of simultaneous + RPC calls that can be sent from the client to a + server. Increasing these values may allow you to + improve throughput, but will also increase the + amount of memory reserved for use by the client. + + suspend.pm_test_delay= + [SUSPEND] + Sets the number of seconds to remain in a suspend test + mode before resuming the system (see + /sys/power/pm_test). Only available when CONFIG_PM_DEBUG + is set. Default value is 5. + + swapaccount=[0|1] + [KNL] Enable accounting of swap in memory resource + controller if no parameter or 1 is given or disable + it if 0 is given (See Documentation/cgroup-v1/memory.txt) + + swiotlb= [ARM,IA-64,PPC,MIPS,X86] + Format: { | force } + -- Number of I/O TLB slabs + force -- force using of bounce buffers even if they + wouldn't be automatically used by the kernel + + switches= [HW,M68k] + + sysfs.deprecated=0|1 [KNL] + Enable/disable old style sysfs layout for old udev + on older distributions. When this option is enabled + very new udev will not work anymore. When this option + is disabled (or CONFIG_SYSFS_DEPRECATED not compiled) + in older udev will not work anymore. + Default depends on CONFIG_SYSFS_DEPRECATED_V2 set in + the kernel configuration. + + sysrq_always_enabled + [KNL] + Ignore sysrq setting - this boot parameter will + neutralize any effect of /proc/sys/kernel/sysrq. + Useful for debugging. + + tcpmhash_entries= [KNL,NET] + Set the number of tcp_metrics_hash slots. + Default value is 8192 or 16384 depending on total + ram pages. This is used to specify the TCP metrics + cache size. See Documentation/networking/ip-sysctl.txt + "tcp_no_metrics_save" section for more details. + + tdfx= [HW,DRM] + + test_suspend= [SUSPEND][,N] + Specify "mem" (for Suspend-to-RAM) or "standby" (for + standby suspend) or "freeze" (for suspend type freeze) + as the system sleep state during system startup with + the optional capability to repeat N number of times. + The system is woken from this state using a + wakeup-capable RTC alarm. + + thash_entries= [KNL,NET] + Set number of hash buckets for TCP connection + + thermal.act= [HW,ACPI] + -1: disable all active trip points in all thermal zones + : override all lowest active trip points + + thermal.crt= [HW,ACPI] + -1: disable all critical trip points in all thermal zones + : override all critical trip points + + thermal.nocrt= [HW,ACPI] + Set to disable actions on ACPI thermal zone + critical and hot trip points. + + thermal.off= [HW,ACPI] + 1: disable ACPI thermal control + + thermal.psv= [HW,ACPI] + -1: disable all passive trip points + : override all passive trip points to this + value + + thermal.tzp= [HW,ACPI] + Specify global default ACPI thermal zone polling rate + : poll all this frequency + 0: no polling (default) + + threadirqs [KNL] + Force threading of all interrupt handlers except those + marked explicitly IRQF_NO_THREAD. + + tmem [KNL,XEN] + Enable the Transcendent memory driver if built-in. + + tmem.cleancache=0|1 [KNL, XEN] + Default is on (1). Disable the usage of the cleancache + API to send anonymous pages to the hypervisor. + + tmem.frontswap=0|1 [KNL, XEN] + Default is on (1). Disable the usage of the frontswap + API to send swap pages to the hypervisor. If disabled + the selfballooning and selfshrinking are force disabled. + + tmem.selfballooning=0|1 [KNL, XEN] + Default is on (1). Disable the driving of swap pages + to the hypervisor. + + tmem.selfshrinking=0|1 [KNL, XEN] + Default is on (1). Partial swapoff that immediately + transfers pages from Xen hypervisor back to the + kernel based on different criteria. + + topology= [S390] + Format: {off | on} + Specify if the kernel should make use of the cpu + topology information if the hardware supports this. + The scheduler will make use of this information and + e.g. base its process migration decisions on it. + Default is on. + + topology_updates= [KNL, PPC, NUMA] + Format: {off} + Specify if the kernel should ignore (off) + topology updates sent by the hypervisor to this + LPAR. + + tp720= [HW,PS2] + + tpm_suspend_pcr=[HW,TPM] + Format: integer pcr id + Specify that at suspend time, the tpm driver + should extend the specified pcr with zeros, + as a workaround for some chips which fail to + flush the last written pcr on TPM_SaveState. + This will guarantee that all the other pcrs + are saved. + + trace_buf_size=nn[KMG] + [FTRACE] will set tracing buffer size on each cpu. + + trace_event=[event-list] + [FTRACE] Set and start specified trace events in order + 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. + The option-list is a comma delimited list of options + that can be enabled or disabled just as if you were + to echo the option name into + + /sys/kernel/debug/tracing/trace_options + + For example, to enable stacktrace option (to dump the + stack trace of each event), add to the command line: + + trace_options=stacktrace + + See also Documentation/trace/ftrace.txt "trace options" + section. + + tp_printk[FTRACE] + Have the tracepoints sent to printk as well as the + tracing ring buffer. This is useful for early boot up + where the system hangs or reboots and does not give the + option for reading the tracing buffer or performing a + ftrace_dump_on_oops. + + To turn off having tracepoints sent to printk, + echo 0 > /proc/sys/kernel/tracepoint_printk + Note, echoing 1 into this file without the + tracepoint_printk kernel cmdline option has no effect. + + ** CAUTION ** + + Having tracepoints sent to printk() and activating high + frequency tracepoints such as irq or sched, can cause + the system to live lock. + + traceoff_on_warning + [FTRACE] enable this option to disable tracing when a + warning is hit. This turns off "tracing_on". Tracing can + be enabled again by echoing '1' into the "tracing_on" + file located in /sys/kernel/debug/tracing/ + + This option is useful, as it disables the trace before + the WARNING dump is called, which prevents the trace to + be filled with content caused by the warning output. + + This option can also be set at run time via the sysctl + option: kernel/traceoff_on_warning + + transparent_hugepage= + [KNL] + Format: [always|madvise|never] + Can be used to control the default behavior of the system + with respect to transparent hugepages. + See Documentation/vm/transhuge.txt for more details. + + tsc= Disable clocksource stability checks for TSC. + Format: + [x86] reliable: mark tsc clocksource as reliable, this + disables clocksource verification at runtime, as well + as the stability checks done at bootup. Used to enable + high-resolution timer mode on older hardware, and in + virtualized environment. + [x86] noirqtime: Do not use TSC to do irq accounting. + Used to run time disable IRQ_TIME_ACCOUNTING on any + platforms where RDTSC is slow and this accounting + can add overhead. + + turbografx.map[2|3]= [HW,JOY] + TurboGraFX parallel port interface + Format: + ,,,,,,, + See also Documentation/input/joystick-parport.txt + + udbg-immortal [PPC] When debugging early kernel crashes that + happen after console_init() and before a proper + console driver takes over, this boot options might + help "seeing" what's going on. + + uhash_entries= [KNL,NET] + Set number of hash buckets for UDP/UDP-Lite connections + + uhci-hcd.ignore_oc= + [USB] Ignore overcurrent events (default N). + Some badly-designed motherboards generate lots of + bogus events, for ports that aren't wired to + anything. Set this parameter to avoid log spamming. + Note that genuine overcurrent events won't be + reported either. + + unknown_nmi_panic + [X86] Cause panic on unknown NMI. + + usbcore.authorized_default= + [USB] Default USB device authorization: + (default -1 = authorized except for wireless USB, + 0 = not authorized, 1 = authorized) + + usbcore.autosuspend= + [USB] The autosuspend time delay (in seconds) used + for newly-detected USB devices (default 2). This + is the time required before an idle device will be + autosuspended. Devices for which the delay is set + to a negative value won't be autosuspended at all. + + usbcore.usbfs_snoop= + [USB] Set to log all usbfs traffic (default 0 = off). + + usbcore.usbfs_snoop_max= + [USB] Maximum number of bytes to snoop in each URB + (default = 65536). + + usbcore.blinkenlights= + [USB] Set to cycle leds on hubs (default 0 = off). + + usbcore.old_scheme_first= + [USB] Start with the old device initialization + scheme (default 0 = off). + + usbcore.usbfs_memory_mb= + [USB] Memory limit (in MB) for buffers allocated by + usbfs (default = 16, 0 = max = 2047). + + usbcore.use_both_schemes= + [USB] Try the other device initialization scheme + if the first one fails (default 1 = enabled). + + usbcore.initial_descriptor_timeout= + [USB] Specifies timeout for the initial 64-byte + USB_REQ_GET_DESCRIPTOR request in milliseconds + (default 5000 = 5.0 seconds). + + usbcore.nousb [USB] Disable the USB subsystem + + usbhid.mousepoll= + [USBHID] The interval which mice are to be polled at. + + usb-storage.delay_use= + [UMS] The delay in seconds before a new device is + scanned for Logical Units (default 1). + + usb-storage.quirks= + [UMS] A list of quirks entries to supplement or + override the built-in unusual_devs list. List + entries are separated by commas. Each entry has + the form VID:PID:Flags where VID and PID are Vendor + and Product ID values (4-digit hex numbers) and + Flags is a set of characters, each corresponding + to a common usb-storage quirk flag as follows: + a = SANE_SENSE (collect more than 18 bytes + of sense data); + b = BAD_SENSE (don't collect more than 18 + bytes of sense data); + c = FIX_CAPACITY (decrease the reported + device capacity by one sector); + d = NO_READ_DISC_INFO (don't use + READ_DISC_INFO command); + e = NO_READ_CAPACITY_16 (don't use + READ_CAPACITY_16 command); + f = NO_REPORT_OPCODES (don't use report opcodes + command, uas only); + g = MAX_SECTORS_240 (don't transfer more than + 240 sectors at a time, uas only); + h = CAPACITY_HEURISTICS (decrease the + reported device capacity by one + sector if the number is odd); + i = IGNORE_DEVICE (don't bind to this + device); + j = NO_REPORT_LUNS (don't use report luns + command, uas only); + l = NOT_LOCKABLE (don't try to lock and + unlock ejectable media); + m = MAX_SECTORS_64 (don't transfer more + than 64 sectors = 32 KB at a time); + n = INITIAL_READ10 (force a retry of the + initial READ(10) command); + o = CAPACITY_OK (accept the capacity + reported by the device); + p = WRITE_CACHE (the device cache is ON + by default); + r = IGNORE_RESIDUE (the device reports + bogus residue values); + s = SINGLE_LUN (the device has only one + Logical Unit); + t = NO_ATA_1X (don't allow ATA(12) and ATA(16) + commands, uas only); + u = IGNORE_UAS (don't bind to the uas driver); + w = NO_WP_DETECT (don't test whether the + medium is write-protected). + y = ALWAYS_SYNC (issue a SYNCHRONIZE_CACHE + even if the device claims no cache) + Example: quirks=0419:aaf5:rl,0421:0433:rc + + user_debug= [KNL,ARM] + Format: + See arch/arm/Kconfig.debug help text. + 1 - undefined instruction events + 2 - system calls + 4 - invalid data aborts + 8 - SIGSEGV faults + 16 - SIGBUS faults + Example: user_debug=31 + + userpte= + [X86] Flags controlling user PTE allocations. + + nohigh = do not allocate PTE pages in + HIGHMEM regardless of setting + of CONFIG_HIGHPTE. + + vdso= [X86,SH] + On X86_32, this is an alias for vdso32=. Otherwise: + + vdso=1: enable VDSO (the default) + vdso=0: disable VDSO mapping + + vdso32= [X86] Control the 32-bit vDSO + vdso32=1: enable 32-bit VDSO + vdso32=0 or vdso32=2: disable 32-bit VDSO + + See the help text for CONFIG_COMPAT_VDSO for more + details. If CONFIG_COMPAT_VDSO is set, the default is + vdso32=0; otherwise, the default is vdso32=1. + + For compatibility with older kernels, vdso32=2 is an + alias for vdso32=0. + + Try vdso32=0 if you encounter an error that says: + dl_main: Assertion `(void *) ph->p_vaddr == _rtld_local._dl_sysinfo_dso' failed! + + vector= [IA-64,SMP] + vector=percpu: enable percpu vector domain + + video= [FB] Frame buffer configuration + See Documentation/fb/modedb.txt. + + video.brightness_switch_enabled= [0,1] + If set to 1, on receiving an ACPI notify event + generated by hotkey, video driver will adjust brightness + level and then send out the event to user space through + the allocated input device; If set to 0, video driver + will only send out the event without touching backlight + brightness level. + default: 1 + + virtio_mmio.device= + [VMMIO] Memory mapped virtio (platform) device. + + @:[:] + where: + := size (can use standard suffixes + like K, M and G) + := physical base address + := interrupt number (as passed to + request_irq()) + := (optional) platform device id + example: + virtio_mmio.device=1K@0x100b0000:48:7 + + Can be used multiple times for multiple devices. + + vga= [BOOT,X86-32] Select a particular video mode + See Documentation/x86/boot.txt and + Documentation/svga.txt. + Use vga=ask for menu. + This is actually a boot loader parameter; the value is + passed to the kernel using a special protocol. + + vmalloc=nn[KMG] [KNL,BOOT] Forces the vmalloc area to have an exact + size of . This can be used to increase the + minimum size (128MB on x86). It can also be used to + decrease the size and leave more room for directly + mapped kernel RAM. + + vmhalt= [KNL,S390] Perform z/VM CP command after system halt. + Format: + + vmpanic= [KNL,S390] Perform z/VM CP command after kernel panic. + Format: + + vmpoff= [KNL,S390] Perform z/VM CP command after power off. + Format: + + vsyscall= [X86-64] + Controls the behavior of vsyscalls (i.e. calls to + fixed addresses of 0xffffffffff600x00 from legacy + code). Most statically-linked binaries and older + versions of glibc use these calls. Because these + functions are at fixed addresses, they make nice + targets for exploits that can control RIP. + + emulate [default] Vsyscalls turn into traps and are + emulated reasonably safely. + + native Vsyscalls are native syscall instructions. + This is a little bit faster than trapping + and makes a few dynamic recompilers work + better than they would in emulation mode. + It also makes exploits much easier to write. + + none Vsyscalls don't work at all. This makes + them quite hard to use for exploits but + might break your system. + + vt.color= [VT] Default text color. + Format: 0xYX, X = foreground, Y = background. + Default: 0x07 = light gray on black. + + vt.cur_default= [VT] Default cursor shape. + Format: 0xCCBBAA, where AA, BB, and CC are the same as + the parameters of the [?A;B;Cc escape sequence; + see VGA-softcursor.txt. Default: 2 = underline. + + vt.default_blu= [VT] + Format: ,,,..., + Change the default blue palette of the console. + This is a 16-member array composed of values + ranging from 0-255. + + vt.default_grn= [VT] + Format: ,,,..., + Change the default green palette of the console. + This is a 16-member array composed of values + ranging from 0-255. + + vt.default_red= [VT] + Format: ,,,..., + Change the default red palette of the console. + This is a 16-member array composed of values + ranging from 0-255. + + vt.default_utf8= + [VT] + Format=<0|1> + Set system-wide default UTF-8 mode for all tty's. + Default is 1, i.e. UTF-8 mode is enabled for all + newly opened terminals. + + vt.global_cursor_default= + [VT] + Format=<-1|0|1> + Set system-wide default for whether a cursor + is shown on new VTs. Default is -1, + i.e. cursors will be created by default unless + overridden by individual drivers. 0 will hide + cursors, 1 will display them. + + vt.italic= [VT] Default color for italic text; 0-15. + Default: 2 = green. + + vt.underline= [VT] Default color for underlined text; 0-15. + Default: 3 = cyan. + + watchdog timers [HW,WDT] For information on watchdog timers, + see Documentation/watchdog/watchdog-parameters.txt + or other driver-specific files in the + Documentation/watchdog/ directory. + + workqueue.watchdog_thresh= + If CONFIG_WQ_WATCHDOG is configured, workqueue can + warn stall conditions and dump internal state to + help debugging. 0 disables workqueue stall + detection; otherwise, it's the stall threshold + duration in seconds. The default value is 30 and + it can be updated at runtime by writing to the + corresponding sysfs file. + + workqueue.disable_numa + By default, all work items queued to unbound + workqueues are affine to the NUMA nodes they're + issued on, which results in better behavior in + general. If NUMA affinity needs to be disabled for + whatever reason, this option can be used. Note + that this also can be controlled per-workqueue for + workqueues visible under /sys/bus/workqueue/. + + workqueue.power_efficient + Per-cpu workqueues are generally preferred because + they show better performance thanks to cache + locality; unfortunately, per-cpu workqueues tend to + be more power hungry than unbound workqueues. + + Enabling this makes the per-cpu workqueues which + were observed to contribute significantly to power + consumption unbound, leading to measurably lower + power usage at the cost of small performance + overhead. + + The default value of this parameter is determined by + the config option CONFIG_WQ_POWER_EFFICIENT_DEFAULT. + + workqueue.debug_force_rr_cpu + Workqueue used to implicitly guarantee that work + items queued without explicit CPU specified are put + on the local CPU. This guarantee is no longer true + and while local CPU is still preferred work items + may be put on foreign CPUs. This debug option + forces round-robin CPU selection to flush out + usages which depend on the now broken guarantee. + When enabled, memory and cache locality will be + impacted. + + x2apic_phys [X86-64,APIC] Use x2apic physical mode instead of + default x2apic cluster mode on platforms + supporting x2apic. + + x86_intel_mid_timer= [X86-32,APBT] + Choose timer option for x86 Intel MID platform. + Two valid options are apbt timer only and lapic timer + plus one apbt timer for broadcast timer. + x86_intel_mid_timer=apbt_only | lapic_and_apbt + + xen_512gb_limit [KNL,X86-64,XEN] + Restricts the kernel running paravirtualized under Xen + to use only up to 512 GB of RAM. The reason to do so is + crash analysis tools and Xen tools for doing domain + save/restore/migration must be enabled to handle larger + domains. + + xen_emul_unplug= [HW,X86,XEN] + Unplug Xen emulated devices + Format: [unplug0,][unplug1] + ide-disks -- unplug primary master IDE devices + aux-ide-disks -- unplug non-primary-master IDE devices + nics -- unplug network devices + all -- unplug all emulated devices (NICs and IDE disks) + unnecessary -- unplugging emulated devices is + unnecessary even if the host did not respond to + the unplug protocol + never -- do not unplug even if version check succeeds + + xen_nopvspin [X86,XEN] + Disables the ticketlock slowpath using Xen PV + optimizations. + + xen_nopv [X86] + Disables the PV optimizations forcing the HVM guest to + run as generic HVM guest with no PV drivers. + + xirc2ps_cs= [NET,PCMCIA] + Format: + ,,,,,[,[,[,]]] + +------------------------ + +Todo +---- + + Add more DRM drivers. diff --git a/Documentation/admin-guide/md.rst b/Documentation/admin-guide/md.rst new file mode 100644 index 000000000000..e449fb5f277c --- /dev/null +++ b/Documentation/admin-guide/md.rst @@ -0,0 +1,727 @@ +RAID arrays +=========== + +Boot time assembly of RAID arrays +--------------------------------- + +Tools that manage md devices can be found at + http://www.kernel.org/pub/linux/utils/raid/ + + +You can boot with your md device with the following kernel command +lines: + +for old raid arrays without persistent superblocks:: + + md=,,,,dev0,dev1,...,devn + +for raid arrays with persistent superblocks:: + + md=,dev0,dev1,...,devn + +or, to assemble a partitionable array:: + + md=d,dev0,dev1,...,devn + +``md device no.`` ++++++++++++++++++ + +The number of the md device + +================= ========= +``md device no.`` device +================= ========= + 0 md0 + 1 md1 + 2 md2 + 3 md3 + 4 md4 +================= ========= + +``raid level`` +++++++++++++++ + +level of the RAID array + +=============== ============= +``raid level`` level +=============== ============= +-1 linear mode +0 striped mode +=============== ============= + +other modes are only supported with persistent super blocks + +``chunk size factor`` ++++++++++++++++++++++ + +(raid-0 and raid-1 only) + +Set the chunk size as 4k << n. + +``fault level`` ++++++++++++++++ + +Totally ignored + +``dev0`` to ``devn`` +++++++++++++++++++++ + +e.g. ``/dev/hda1``, ``/dev/hdc1``, ``/dev/sda1``, ``/dev/sdb1`` + +A possible loadlin line (Harald Hoyer ) looks like this:: + + e:\loadlin\loadlin e:\zimage root=/dev/md0 md=0,0,4,0,/dev/hdb2,/dev/hdc3 ro + + +Boot time autodetection of RAID arrays +-------------------------------------- + +When md is compiled into the kernel (not as module), partitions of +type 0xfd are scanned and automatically assembled into RAID arrays. +This autodetection may be suppressed with the kernel parameter +``raid=noautodetect``. As of kernel 2.6.9, only drives with a type 0 +superblock can be autodetected and run at boot time. + +The kernel parameter ``raid=partitionable`` (or ``raid=part``) means +that all auto-detected arrays are assembled as partitionable. + +Boot time assembly of degraded/dirty arrays +------------------------------------------- + +If a raid5 or raid6 array is both dirty and degraded, it could have +undetectable data corruption. This is because the fact that it is +``dirty`` means that the parity cannot be trusted, and the fact that it +is degraded means that some datablocks are missing and cannot reliably +be reconstructed (due to no parity). + +For this reason, md will normally refuse to start such an array. This +requires the sysadmin to take action to explicitly start the array +despite possible corruption. This is normally done with:: + + mdadm --assemble --force .... + +This option is not really available if the array has the root +filesystem on it. In order to support this booting from such an +array, md supports a module parameter ``start_dirty_degraded`` which, +when set to 1, bypassed the checks and will allows dirty degraded +arrays to be started. + +So, to boot with a root filesystem of a dirty degraded raid 5 or 6, use:: + + md-mod.start_dirty_degraded=1 + + +Superblock formats +------------------ + +The md driver can support a variety of different superblock formats. +Currently, it supports superblock formats ``0.90.0`` and the ``md-1`` format +introduced in the 2.5 development series. + +The kernel will autodetect which format superblock is being used. + +Superblock format ``0`` is treated differently to others for legacy +reasons - it is the original superblock format. + + +General Rules - apply for all superblock formats +------------------------------------------------ + +An array is ``created`` by writing appropriate superblocks to all +devices. + +It is ``assembled`` by associating each of these devices with an +particular md virtual device. Once it is completely assembled, it can +be accessed. + +An array should be created by a user-space tool. This will write +superblocks to all devices. It will usually mark the array as +``unclean``, or with some devices missing so that the kernel md driver +can create appropriate redundancy (copying in raid 1, parity +calculation in raid 4/5). + +When an array is assembled, it is first initialized with the +SET_ARRAY_INFO ioctl. This contains, in particular, a major and minor +version number. The major version number selects which superblock +format is to be used. The minor number might be used to tune handling +of the format, such as suggesting where on each device to look for the +superblock. + +Then each device is added using the ADD_NEW_DISK ioctl. This +provides, in particular, a major and minor number identifying the +device to add. + +The array is started with the RUN_ARRAY ioctl. + +Once started, new devices can be added. They should have an +appropriate superblock written to them, and then be passed in with +ADD_NEW_DISK. + +Devices that have failed or are not yet active can be detached from an +array using HOT_REMOVE_DISK. + + +Specific Rules that apply to format-0 super block arrays, and arrays with no superblock (non-persistent) +-------------------------------------------------------------------------------------------------------- + +An array can be ``created`` by describing the array (level, chunksize +etc) in a SET_ARRAY_INFO ioctl. This must have ``major_version==0`` and +``raid_disks != 0``. + +Then uninitialized devices can be added with ADD_NEW_DISK. The +structure passed to ADD_NEW_DISK must specify the state of the device +and its role in the array. + +Once started with RUN_ARRAY, uninitialized spares can be added with +HOT_ADD_DISK. + + +MD devices in sysfs +------------------- + +md devices appear in sysfs (``/sys``) as regular block devices, +e.g.:: + + /sys/block/md0 + +Each ``md`` device will contain a subdirectory called ``md`` which +contains further md-specific information about the device. + +All md devices contain: + + level + a text file indicating the ``raid level``. e.g. raid0, raid1, + raid5, linear, multipath, faulty. + If no raid level has been set yet (array is still being + assembled), the value will reflect whatever has been written + to it, which may be a name like the above, or may be a number + such as ``0``, ``5``, etc. + + raid_disks + a text file with a simple number indicating the number of devices + in a fully functional array. If this is not yet known, the file + will be empty. If an array is being resized this will contain + the new number of devices. + Some raid levels allow this value to be set while the array is + active. This will reconfigure the array. Otherwise it can only + be set while assembling an array. + A change to this attribute will not be permitted if it would + reduce the size of the array. To reduce the number of drives + in an e.g. raid5, the array size must first be reduced by + setting the ``array_size`` attribute. + + chunk_size + This is the size in bytes for ``chunks`` and is only relevant to + raid levels that involve striping (0,4,5,6,10). The address space + of the array is conceptually divided into chunks and consecutive + chunks are striped onto neighbouring devices. + The size should be at least PAGE_SIZE (4k) and should be a power + of 2. This can only be set while assembling an array + + layout + The ``layout`` for the array for the particular level. This is + simply a number that is interpretted differently by different + levels. It can be written while assembling an array. + + array_size + This can be used to artificially constrain the available space in + the array to be less than is actually available on the combined + devices. Writing a number (in Kilobytes) which is less than + the available size will set the size. Any reconfiguration of the + array (e.g. adding devices) will not cause the size to change. + Writing the word ``default`` will cause the effective size of the + array to be whatever size is actually available based on + ``level``, ``chunk_size`` and ``component_size``. + + This can be used to reduce the size of the array before reducing + the number of devices in a raid4/5/6, or to support external + metadata formats which mandate such clipping. + + reshape_position + This is either ``none`` or a sector number within the devices of + the array where ``reshape`` is up to. If this is set, the three + attributes mentioned above (raid_disks, chunk_size, layout) can + potentially have 2 values, an old and a new value. If these + values differ, reading the attribute returns:: + + new (old) + + and writing will effect the ``new`` value, leaving the ``old`` + unchanged. + + component_size + For arrays with data redundancy (i.e. not raid0, linear, faulty, + multipath), all components must be the same size - or at least + there must a size that they all provide space for. This is a key + part or the geometry of the array. It is measured in sectors + and can be read from here. Writing to this value may resize + the array if the personality supports it (raid1, raid5, raid6), + and if the component drives are large enough. + + metadata_version + This indicates the format that is being used to record metadata + about the array. It can be 0.90 (traditional format), 1.0, 1.1, + 1.2 (newer format in varying locations) or ``none`` indicating that + the kernel isn't managing metadata at all. + Alternately it can be ``external:`` followed by a string which + is set by user-space. This indicates that metadata is managed + by a user-space program. Any device failure or other event that + requires a metadata update will cause array activity to be + suspended until the event is acknowledged. + + resync_start + The point at which resync should start. If no resync is needed, + this will be a very large number (or ``none`` since 2.6.30-rc1). At + array creation it will default to 0, though starting the array as + ``clean`` will set it much larger. + + new_dev + This file can be written but not read. The value written should + be a block device number as major:minor. e.g. 8:0 + This will cause that device to be attached to the array, if it is + available. It will then appear at md/dev-XXX (depending on the + name of the device) and further configuration is then possible. + + safe_mode_delay + When an md array has seen no write requests for a certain period + of time, it will be marked as ``clean``. When another write + request arrives, the array is marked as ``dirty`` before the write + commences. This is known as ``safe_mode``. + The ``certain period`` is controlled by this file which stores the + period as a number of seconds. The default is 200msec (0.200). + Writing a value of 0 disables safemode. + + array_state + This file contains a single word which describes the current + state of the array. In many cases, the state can be set by + writing the word for the desired state, however some states + cannot be explicitly set, and some transitions are not allowed. + + Select/poll works on this file. All changes except between + Active_idle and active (which can be frequent and are not + very interesting) are notified. active->active_idle is + reported if the metadata is externally managed. + + clear + No devices, no size, no level + + Writing is equivalent to STOP_ARRAY ioctl + + inactive + May have some settings, but array is not active + all IO results in error + + When written, doesn't tear down array, but just stops it + + suspended (not supported yet) + All IO requests will block. The array can be reconfigured. + + Writing this, if accepted, will block until array is quiessent + + readonly + no resync can happen. no superblocks get written. + + Write requests fail + + read-auto + like readonly, but behaves like ``clean`` on a write request. + + clean + no pending writes, but otherwise active. + + When written to inactive array, starts without resync + + If a write request arrives then + if metadata is known, mark ``dirty`` and switch to ``active``. + if not known, block and switch to write-pending + + If written to an active array that has pending writes, then fails. + active + fully active: IO and resync can be happening. + When written to inactive array, starts with resync + + write-pending + clean, but writes are blocked waiting for ``active`` to be written. + + active-idle + like active, but no writes have been seen for a while (safe_mode_delay). + + bitmap/location + This indicates where the write-intent bitmap for the array is + stored. + + It can be one of ``none``, ``file`` or ``[+-]N``. + ``file`` may later be extended to ``file:/file/name`` + ``[+-]N`` means that many sectors from the start of the metadata. + + This is replicated on all devices. For arrays with externally + managed metadata, the offset is from the beginning of the + device. + + bitmap/chunksize + The size, in bytes, of the chunk which will be represented by a + single bit. For RAID456, it is a portion of an individual + device. For RAID10, it is a portion of the array. For RAID1, it + is both (they come to the same thing). + + bitmap/time_base + The time, in seconds, between looking for bits in the bitmap to + be cleared. In the current implementation, a bit will be cleared + between 2 and 3 times ``time_base`` after all the covered blocks + are known to be in-sync. + + bitmap/backlog + When write-mostly devices are active in a RAID1, write requests + to those devices proceed in the background - the filesystem (or + other user of the device) does not have to wait for them. + ``backlog`` sets a limit on the number of concurrent background + writes. If there are more than this, new writes will by + synchronous. + + bitmap/metadata + This can be either ``internal`` or ``external``. + + ``internal`` + is the default and means the metadata for the bitmap + is stored in the first 256 bytes of the allocated space and is + managed by the md module. + + ``external`` + means that bitmap metadata is managed externally to + the kernel (i.e. by some userspace program) + + bitmap/can_clear + This is either ``true`` or ``false``. If ``true``, then bits in the + bitmap will be cleared when the corresponding blocks are thought + to be in-sync. If ``false``, bits will never be cleared. + This is automatically set to ``false`` if a write happens on a + degraded array, or if the array becomes degraded during a write. + When metadata is managed externally, it should be set to true + once the array becomes non-degraded, and this fact has been + recorded in the metadata. + + + + +As component devices are added to an md array, they appear in the ``md`` +directory as new directories named:: + + dev-XXX + +where ``XXX`` is a name that the kernel knows for the device, e.g. hdb1. +Each directory contains: + + block + a symlink to the block device in /sys/block, e.g.:: + + /sys/block/md0/md/dev-hdb1/block -> ../../../../block/hdb/hdb1 + + super + A file containing an image of the superblock read from, or + written to, that device. + + state + A file recording the current state of the device in the array + which can be a comma separated list of: + + faulty + device has been kicked from active use due to + a detected fault, or it has unacknowledged bad + blocks + + in_sync + device is a fully in-sync member of the array + + writemostly + device will only be subject to read + requests if there are no other options. + + This applies only to raid1 arrays. + + blocked + device has failed, and the failure hasn't been + acknowledged yet by the metadata handler. + + Writes that would write to this device if + it were not faulty are blocked. + + spare + device is working, but not a full member. + + This includes spares that are in the process + of being recovered to + + write_error + device has ever seen a write error. + + want_replacement + device is (mostly) working but probably + should be replaced, either due to errors or + due to user request. + + replacement + device is a replacement for another active + device with same raid_disk. + + + This list may grow in future. + + This can be written to. + + Writing ``faulty`` simulates a failure on the device. + + Writing ``remove`` removes the device from the array. + + Writing ``writemostly`` sets the writemostly flag. + + Writing ``-writemostly`` clears the writemostly flag. + + Writing ``blocked`` sets the ``blocked`` flag. + + Writing ``-blocked`` clears the ``blocked`` flags and allows writes + to complete and possibly simulates an error. + + Writing ``in_sync`` sets the in_sync flag. + + Writing ``write_error`` sets writeerrorseen flag. + + Writing ``-write_error`` clears writeerrorseen flag. + + Writing ``want_replacement`` is allowed at any time except to a + replacement device or a spare. It sets the flag. + + Writing ``-want_replacement`` is allowed at any time. It clears + the flag. + + Writing ``replacement`` or ``-replacement`` is only allowed before + starting the array. It sets or clears the flag. + + + This file responds to select/poll. Any change to ``faulty`` + or ``blocked`` causes an event. + + errors + An approximate count of read errors that have been detected on + this device but have not caused the device to be evicted from + the array (either because they were corrected or because they + happened while the array was read-only). When using version-1 + metadata, this value persists across restarts of the array. + + This value can be written while assembling an array thus + providing an ongoing count for arrays with metadata managed by + userspace. + + slot + This gives the role that the device has in the array. It will + either be ``none`` if the device is not active in the array + (i.e. is a spare or has failed) or an integer less than the + ``raid_disks`` number for the array indicating which position + it currently fills. This can only be set while assembling an + array. A device for which this is set is assumed to be working. + + offset + This gives the location in the device (in sectors from the + start) where data from the array will be stored. Any part of + the device before this offset is not touched, unless it is + used for storing metadata (Formats 1.1 and 1.2). + + size + The amount of the device, after the offset, that can be used + for storage of data. This will normally be the same as the + component_size. This can be written while assembling an + array. If a value less than the current component_size is + written, it will be rejected. + + recovery_start + When the device is not ``in_sync``, this records the number of + sectors from the start of the device which are known to be + correct. This is normally zero, but during a recovery + operation it will steadily increase, and if the recovery is + interrupted, restoring this value can cause recovery to + avoid repeating the earlier blocks. With v1.x metadata, this + value is saved and restored automatically. + + This can be set whenever the device is not an active member of + the array, either before the array is activated, or before + the ``slot`` is set. + + Setting this to ``none`` is equivalent to setting ``in_sync``. + Setting to any other value also clears the ``in_sync`` flag. + + bad_blocks + This gives the list of all known bad blocks in the form of + start address and length (in sectors respectively). If output + is too big to fit in a page, it will be truncated. Writing + ``sector length`` to this file adds new acknowledged (i.e. + recorded to disk safely) bad blocks. + + unacknowledged_bad_blocks + This gives the list of known-but-not-yet-saved-to-disk bad + blocks in the same form of ``bad_blocks``. If output is too big + to fit in a page, it will be truncated. Writing to this file + adds bad blocks without acknowledging them. This is largely + for testing. + + + +An active md device will also contain an entry for each active device +in the array. These are named:: + + rdNN + +where ``NN`` is the position in the array, starting from 0. +So for a 3 drive array there will be rd0, rd1, rd2. +These are symbolic links to the appropriate ``dev-XXX`` entry. +Thus, for example:: + + cat /sys/block/md*/md/rd*/state + +will show ``in_sync`` on every line. + + + +Active md devices for levels that support data redundancy (1,4,5,6,10) +also have + + sync_action + a text file that can be used to monitor and control the rebuild + process. It contains one word which can be one of: + + resync + redundancy is being recalculated after unclean + shutdown or creation + + recover + a hot spare is being built to replace a + failed/missing device + + idle + nothing is happening + check + A full check of redundancy was requested and is + happening. This reads all blocks and checks + them. A repair may also happen for some raid + levels. + + repair + A full check and repair is happening. This is + similar to ``resync``, but was requested by the + user, and the write-intent bitmap is NOT used to + optimise the process. + + This file is writable, and each of the strings that could be + read are meaningful for writing. + + ``idle`` will stop an active resync/recovery etc. There is no + guarantee that another resync/recovery may not be automatically + started again, though some event will be needed to trigger + this. + + ``resync`` or ``recovery`` can be used to restart the + corresponding operation if it was stopped with ``idle``. + + ``check`` and ``repair`` will start the appropriate process + providing the current state is ``idle``. + + This file responds to select/poll. Any important change in the value + triggers a poll event. Sometimes the value will briefly be + ``recover`` if a recovery seems to be needed, but cannot be + achieved. In that case, the transition to ``recover`` isn't + notified, but the transition away is. + + degraded + This contains a count of the number of devices by which the + arrays is degraded. So an optimal array will show ``0``. A + single failed/missing drive will show ``1``, etc. + + This file responds to select/poll, any increase or decrease + in the count of missing devices will trigger an event. + + mismatch_count + When performing ``check`` and ``repair``, and possibly when + performing ``resync``, md will count the number of errors that are + found. The count in ``mismatch_cnt`` is the number of sectors + that were re-written, or (for ``check``) would have been + re-written. As most raid levels work in units of pages rather + than sectors, this may be larger than the number of actual errors + by a factor of the number of sectors in a page. + + bitmap_set_bits + If the array has a write-intent bitmap, then writing to this + attribute can set bits in the bitmap, indicating that a resync + would need to check the corresponding blocks. Either individual + numbers or start-end pairs can be written. Multiple numbers + can be separated by a space. + + Note that the numbers are ``bit`` numbers, not ``block`` numbers. + They should be scaled by the bitmap_chunksize. + + sync_speed_min, sync_speed_max + This are similar to ``/proc/sys/dev/raid/speed_limit_{min,max}`` + however they only apply to the particular array. + + If no value has been written to these, or if the word ``system`` + is written, then the system-wide value is used. If a value, + in kibibytes-per-second is written, then it is used. + + When the files are read, they show the currently active value + followed by ``(local)`` or ``(system)`` depending on whether it is + a locally set or system-wide value. + + sync_completed + This shows the number of sectors that have been completed of + whatever the current sync_action is, followed by the number of + sectors in total that could need to be processed. The two + numbers are separated by a ``/`` thus effectively showing one + value, a fraction of the process that is complete. + + A ``select`` on this attribute will return when resync completes, + when it reaches the current sync_max (below) and possibly at + other times. + + sync_speed + This shows the current actual speed, in K/sec, of the current + sync_action. It is averaged over the last 30 seconds. + + suspend_lo, suspend_hi + The two values, given as numbers of sectors, indicate a range + within the array where IO will be blocked. This is currently + only supported for raid4/5/6. + + sync_min, sync_max + The two values, given as numbers of sectors, indicate a range + within the array where ``check``/``repair`` will operate. Must be + a multiple of chunk_size. When it reaches ``sync_max`` it will + pause, rather than complete. + You can use ``select`` or ``poll`` on ``sync_completed`` to wait for + that number to reach sync_max. Then you can either increase + ``sync_max``, or can write ``idle`` to ``sync_action``. + + The value of ``max`` for ``sync_max`` effectively disables the limit. + When a resync is active, the value can only ever be increased, + never decreased. + The value of ``0`` is the minimum for ``sync_min``. + + + +Each active md device may also have attributes specific to the +personality module that manages it. +These are specific to the implementation of the module and could +change substantially if the implementation changes. + +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, 17). Default is 256. + + strip_cache_active (currently raid5 only) + number of active entries in the stripe cache + + preread_bypass_threshold (currently raid5 only) + number of times a stripe requiring preread will be bypassed by + a stripe that does not require preread. For fairness defaults + to 1. Setting this to 0 disables bypass accounting and + requires preread stripes to wait until all full-width stripe- + writes are complete. Valid values are 0 to stripe_cache_size. diff --git a/Documentation/admin-guide/mono.rst b/Documentation/admin-guide/mono.rst new file mode 100644 index 000000000000..9a9744ca0cf3 --- /dev/null +++ b/Documentation/admin-guide/mono.rst @@ -0,0 +1,68 @@ +Mono(tm) Binary Kernel Support for Linux +----------------------------------------- + +To configure Linux to automatically execute Mono-based .NET binaries +(in the form of .exe files) without the need to use the mono CLR +wrapper, you can use the BINFMT_MISC kernel support. + +This will allow you to execute Mono-based .NET binaries just like any +other program after you have done the following: + +1) You MUST FIRST install the Mono CLR support, either by downloading + a binary package, a source tarball or by installing from CVS. Binary + packages for several distributions can be found at: + + http://go-mono.com/download.html + + Instructions for compiling Mono can be found at: + + http://www.go-mono.com/compiling.html + + Once the Mono CLR support has been installed, just check that + ``/usr/bin/mono`` (which could be located elsewhere, for example + ``/usr/local/bin/mono``) is working. + +2) You have to compile BINFMT_MISC either as a module or into + the kernel (``CONFIG_BINFMT_MISC``) and set it up properly. + If you choose to compile it as a module, you will have + to insert it manually with modprobe/insmod, as kmod + cannot be easily supported with binfmt_misc. + Read the file ``binfmt_misc.txt`` in this directory to know + more about the configuration process. + +3) Add the following entries to ``/etc/rc.local`` or similar script + to be run at system startup:: + + # Insert BINFMT_MISC module into the kernel + if [ ! -e /proc/sys/fs/binfmt_misc/register ]; then + /sbin/modprobe binfmt_misc + # Some distributions, like Fedora Core, perform + # the following command automatically when the + # binfmt_misc module is loaded into the kernel + # or during normal boot up (systemd-based systems). + # Thus, it is possible that the following line + # is not needed at all. + mount -t binfmt_misc none /proc/sys/fs/binfmt_misc + fi + + # Register support for .NET CLR binaries + if [ -e /proc/sys/fs/binfmt_misc/register ]; then + # Replace /usr/bin/mono with the correct pathname to + # the Mono CLR runtime (usually /usr/local/bin/mono + # when compiling from sources or CVS). + echo ':CLR:M::MZ::/usr/bin/mono:' > /proc/sys/fs/binfmt_misc/register + else + echo "No binfmt_misc support" + exit 1 + fi + +4) Check that ``.exe`` binaries can be ran without the need of a + wrapper script, simply by launching the ``.exe`` file directly + from a command prompt, for example:: + + /usr/bin/xsd.exe + + .. note:: + + If this fails with a permission denied error, check + that the ``.exe`` file has execute permissions. diff --git a/Documentation/admin-guide/oops-tracing.rst b/Documentation/admin-guide/oops-tracing.rst new file mode 100644 index 000000000000..3e25ea7349ee --- /dev/null +++ b/Documentation/admin-guide/oops-tracing.rst @@ -0,0 +1,300 @@ +OOPS tracing +============ + +.. note:: + + ``ksymoops`` is useless on 2.6 or upper. Please use the Oops in its original + format (from ``dmesg``, etc). Ignore any references in this or other docs to + "decoding the Oops" or "running it through ksymoops". + If you post an Oops from 2.6+ that has been run through ``ksymoops``, + people will just tell you to repost it. + +Quick Summary +------------- + +Find the Oops and send it to the maintainer of the kernel area that seems to be +involved with the problem. Don't worry too much about getting the wrong person. +If you are unsure send it to the person responsible for the code relevant to +what you were doing. If it occurs repeatably try and describe how to recreate +it. That's worth even more than the oops. + +If you are totally stumped as to whom to send the report, send it to +linux-kernel@vger.kernel.org. Thanks for your help in making Linux as +stable as humanly possible. + +Where is the Oops? +---------------------- + +Normally the Oops text is read from the kernel buffers by klogd and +handed to ``syslogd`` which writes it to a syslog file, typically +``/var/log/messages`` (depends on ``/etc/syslog.conf``). Sometimes ``klogd`` +dies, in which case you can run ``dmesg > file`` to read the data from the +kernel buffers and save it. Or you can ``cat /proc/kmsg > file``, however you +have to break in to stop the transfer, ``kmsg`` is a "never ending file". +If the machine has crashed so badly that you cannot enter commands or +the disk is not available then you have three options : + +(1) Hand copy the text from the screen and type it in after the machine + has restarted. Messy but it is the only option if you have not + planned for a crash. Alternatively, you can take a picture of + the screen with a digital camera - not nice, but better than + nothing. If the messages scroll off the top of the console, you + may find that booting with a higher resolution (eg, ``vga=791``) + will allow you to read more of the text. (Caveat: This needs ``vesafb``, + so won't help for 'early' oopses) + +(2) Boot with a serial console (see + :ref:`Documentation/serial-console.txt `), + run a null modem to a second machine and capture the output there + using your favourite communication program. Minicom works well. + +(3) Use Kdump (see Documentation/kdump/kdump.txt), + extract the kernel ring buffer from old memory with using dmesg + gdbmacro in Documentation/kdump/gdbmacros.txt. + + +Full Information +---------------- + +.. note:: + + the message from Linus below applies to 2.4 kernel. I have preserved it + for historical reasons, and because some of the information in it still + applies. Especially, please ignore any references to ksymoops. + + :: + + From: Linus Torvalds + + How to track down an Oops.. [originally a mail to linux-kernel] + + The main trick is having 5 years of experience with those pesky oops + messages ;-) + +Actually, there are things you can do that make this easier. I have two +separate approaches:: + + gdb /usr/src/linux/vmlinux + gdb> disassemble + +That's the easy way to find the problem, at least if the bug-report is +well made (like this one was - run through ``ksymoops`` to get the +information of which function and the offset in the function that it +happened in). + +Oh, it helps if the report happens on a kernel that is compiled with the +same compiler and similar setups. + +The other thing to do is disassemble the "Code:" part of the bug report: +ksymoops will do this too with the correct tools, but if you don't have +the tools you can just do a silly program:: + + char str[] = "\xXX\xXX\xXX..."; + main(){} + +and compile it with ``gcc -g`` and then do ``disassemble str`` (where the ``XX`` +stuff are the values reported by the Oops - you can just cut-and-paste +and do a replace of spaces to ``\x`` - that's what I do, as I'm too lazy +to write a program to automate this all). + +Alternatively, you can use the shell script in ``scripts/decodecode``. +Its usage is:: + + decodecode < oops.txt + +The hex bytes that follow "Code:" may (in some architectures) have a series +of bytes that precede the current instruction pointer as well as bytes at and +following the current instruction pointer. In some cases, one instruction +byte or word is surrounded by ``<>`` or ``()``, as in ``<86>`` or ``(f00d)``. +These ``<>`` or ``()`` markings indicate the current instruction pointer. + +Example from i386, split into multiple lines for readability:: + + Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1 + 64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54 + 7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0 + +Finally, if you want to see where the code comes from, you can do:: + + cd /usr/src/linux + make fs/buffer.s # or whatever file the bug happened in + +and then you get a better idea of what happens than with the gdb +disassembly. + +Now, the trick is just then to combine all the data you have: the C +sources (and general knowledge of what it **should** do), the assembly +listing and the code disassembly (and additionally the register dump you +also get from the "oops" message - that can be useful to see **what** the +corrupted pointers were, and when you have the assembler listing you can +also match the other registers to whatever C expressions they were used +for). + +Essentially, you just look at what doesn't match (in this case it was the +"Code" disassembly that didn't match with what the compiler generated). +Then you need to find out **why** they don't match. Often it's simple - you +see that the code uses a NULL pointer and then you look at the code and +wonder how the NULL pointer got there, and if it's a valid thing to do +you just check against it.. + +Now, if somebody gets the idea that this is time-consuming and requires +some small amount of concentration, you're right. Which is why I will +mostly just ignore any panic reports that don't have the symbol table +info etc looked up: it simply gets too hard to look it up (I have some +programs to search for specific patterns in the kernel code segment, and +sometimes I have been able to look up those kinds of panics too, but +that really requires pretty good knowledge of the kernel just to be able +to pick out the right sequences etc..) + +**Sometimes** it happens that I just see the disassembled code sequence +from the panic, and I know immediately where it's coming from. That's when +I get worried that I've been doing this for too long ;-) + + Linus + + +--------------------------------------------------------------------------- + +Notes on Oops tracing with ``klogd`` +------------------------------------ + +In order to help Linus and the other kernel developers there has been +substantial support incorporated into ``klogd`` for processing protection +faults. In order to have full support for address resolution at least +version 1.3-pl3 of the ``sysklogd`` package should be used. + +When a protection fault occurs the ``klogd`` daemon automatically +translates important addresses in the kernel log messages to their +symbolic equivalents. This translated kernel message is then +forwarded through whatever reporting mechanism ``klogd`` is using. The +protection fault message can be simply cut out of the message files +and forwarded to the kernel developers. + +Two types of address resolution are performed by ``klogd``. The first is +static translation and the second is dynamic translation. Static +translation uses the System.map file in much the same manner that +ksymoops does. In order to do static translation the ``klogd`` daemon +must be able to find a system map file at daemon initialization time. +See the klogd man page for information on how ``klogd`` searches for map +files. + +Dynamic address translation is important when kernel loadable modules +are being used. Since memory for kernel modules is allocated from the +kernel's dynamic memory pools there are no fixed locations for either +the start of the module or for functions and symbols in the module. + +The kernel supports system calls which allow a program to determine +which modules are loaded and their location in memory. Using these +system calls the klogd daemon builds a symbol table which can be used +to debug a protection fault which occurs in a loadable kernel module. + +At the very minimum klogd will provide the name of the module which +generated the protection fault. There may be additional symbolic +information available if the developer of the loadable module chose to +export symbol information from the module. + +Since the kernel module environment can be dynamic there must be a +mechanism for notifying the ``klogd`` daemon when a change in module +environment occurs. There are command line options available which +allow klogd to signal the currently executing daemon that symbol +information should be refreshed. See the ``klogd`` manual page for more +information. + +A patch is included with the sysklogd distribution which modifies the +``modules-2.0.0`` package to automatically signal klogd whenever a module +is loaded or unloaded. Applying this patch provides essentially +seamless support for debugging protection faults which occur with +kernel loadable modules. + +The following is an example of a protection fault in a loadable module +processed by ``klogd``:: + + Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc + Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 + Aug 29 09:51:01 blizard kernel: *pde = 00000000 + Aug 29 09:51:01 blizard kernel: Oops: 0002 + Aug 29 09:51:01 blizard kernel: CPU: 0 + Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] + Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 + Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c + Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c + Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 + Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) + Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 + Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 + Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 + Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] + Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 + +--------------------------------------------------------------------------- + +:: + + Dr. G.W. Wettstein Oncology Research Div. Computing Facility + Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com + 820 4th St. N. + Fargo, ND 58122 + Phone: 701-234-7556 + + +--------------------------------------------------------------------------- + +Tainted kernels +--------------- + +Some oops reports contain the string **'Tainted: '** after the program +counter. This indicates that the kernel has been tainted by some +mechanism. The string is followed by a series of position-sensitive +characters, each representing a particular tainted value. + + 1) 'G' if all modules loaded have a GPL or compatible license, 'P' if + any proprietary module has been loaded. Modules without a + MODULE_LICENSE or with a MODULE_LICENSE that is not recognised by + insmod as GPL compatible are assumed to be proprietary. + + 2) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all + modules were loaded normally. + + 3) ``S`` if the oops occurred on an SMP kernel running on hardware that + hasn't been certified as safe to run multiprocessor. + Currently this occurs only on various Athlons that are not + SMP capable. + + 4) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all + modules were unloaded normally. + + 5) ``M`` if any processor has reported a Machine Check Exception, + ``' '`` if no Machine Check Exceptions have occurred. + + 6) ``B`` if a page-release function has found a bad page reference or + some unexpected page flags. + + 7) ``U`` if a user or user application specifically requested that the + Tainted flag be set, ``' '`` otherwise. + + 8) ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG. + + 9) ``A`` if the ACPI table has been overridden. + + 10) ``W`` if a warning has previously been issued by the kernel. + (Though some warnings may set more specific taint flags.) + + 11) ``C`` if a staging driver has been loaded. + + 12) ``I`` if the kernel is working around a severe bug in the platform + firmware (BIOS or similar). + + 13) ``O`` if an externally-built ("out-of-tree") module has been loaded. + + 14) ``E`` if an unsigned module has been loaded in a kernel supporting + module signature. + + 15) ``L`` if a soft lockup has previously occurred on the system. + + 16) ``K`` if the kernel has been live patched. + +The primary reason for the **'Tainted: '** string is to tell kernel +debuggers if this is a clean kernel or if anything unusual has +occurred. Tainting is permanent: even if an offending module is +unloaded, the tainted value remains to indicate that the kernel is not +trustworthy. diff --git a/Documentation/admin-guide/parport.rst b/Documentation/admin-guide/parport.rst new file mode 100644 index 000000000000..ad3f9b8a11e1 --- /dev/null +++ b/Documentation/admin-guide/parport.rst @@ -0,0 +1,286 @@ +Parport ++++++++ + +The ``parport`` code provides parallel-port support under Linux. This +includes the ability to share one port between multiple device +drivers. + +You can pass parameters to the ``parport`` code to override its automatic +detection of your hardware. This is particularly useful if you want +to use IRQs, since in general these can't be autoprobed successfully. +By default IRQs are not used even if they **can** be probed. This is +because there are a lot of people using the same IRQ for their +parallel port and a sound card or network card. + +The ``parport`` code is split into two parts: generic (which deals with +port-sharing) and architecture-dependent (which deals with actually +using the port). + + +Parport as modules +================== + +If you load the `parport`` code as a module, say:: + + # insmod parport + +to load the generic ``parport`` code. You then must load the +architecture-dependent code with (for example):: + + # insmod parport_pc io=0x3bc,0x378,0x278 irq=none,7,auto + +to tell the ``parport`` code that you want three PC-style ports, one at +0x3bc with no IRQ, one at 0x378 using IRQ 7, and one at 0x278 with an +auto-detected IRQ. Currently, PC-style (``parport_pc``), Sun ``bpp``, +Amiga, Atari, and MFC3 hardware is supported. + +PCI parallel I/O card support comes from ``parport_pc``. Base I/O +addresses should not be specified for supported PCI cards since they +are automatically detected. + + +modprobe +-------- + +If you use modprobe , you will find it useful to add lines as below to a +configuration file in /etc/modprobe.d/ directory:: + + alias parport_lowlevel parport_pc + options parport_pc io=0x378,0x278 irq=7,auto + +modprobe will load ``parport_pc`` (with the options ``io=0x378,0x278 irq=7,auto``) +whenever a parallel port device driver (such as ``lp``) is loaded. + +Note that these are example lines only! You shouldn't in general need +to specify any options to ``parport_pc`` in order to be able to use a +parallel port. + + +Parport probe [optional] +------------------------ + +In 2.2 kernels there was a module called ``parport_probe``, which was used +for collecting IEEE 1284 device ID information. This has now been +enhanced and now lives with the IEEE 1284 support. When a parallel +port is detected, the devices that are connected to it are analysed, +and information is logged like this:: + + parport0: Printer, BJC-210 (Canon) + +The probe information is available from files in ``/proc/sys/dev/parport/``. + + +Parport linked into the kernel statically +========================================= + +If you compile the ``parport`` code into the kernel, then you can use +kernel boot parameters to get the same effect. Add something like the +following to your LILO command line:: + + parport=0x3bc parport=0x378,7 parport=0x278,auto,nofifo + +You can have many ``parport=...`` statements, one for each port you want +to add. Adding ``parport=0`` to the kernel command-line will disable +parport support entirely. Adding ``parport=auto`` to the kernel +command-line will make ``parport`` use any IRQ lines or DMA channels that +it auto-detects. + + +Files in /proc +============== + +If you have configured the ``/proc`` filesystem into your kernel, you will +see a new directory entry: ``/proc/sys/dev/parport``. In there will be a +directory entry for each parallel port for which parport is +configured. In each of those directories are a collection of files +describing that parallel port. + +The ``/proc/sys/dev/parport`` directory tree looks like:: + + parport + |-- default + | |-- spintime + | `-- timeslice + |-- parport0 + | |-- autoprobe + | |-- autoprobe0 + | |-- autoprobe1 + | |-- autoprobe2 + | |-- autoprobe3 + | |-- devices + | | |-- active + | | `-- lp + | | `-- timeslice + | |-- base-addr + | |-- irq + | |-- dma + | |-- modes + | `-- spintime + `-- parport1 + |-- autoprobe + |-- autoprobe0 + |-- autoprobe1 + |-- autoprobe2 + |-- autoprobe3 + |-- devices + | |-- active + | `-- ppa + | `-- timeslice + |-- base-addr + |-- irq + |-- dma + |-- modes + `-- spintime + +.. tabularcolumns:: |p{4.0cm}|p{13.5cm}| + +======================= ======================================================= +File Contents +======================= ======================================================= +``devices/active`` A list of the device drivers using that port. A "+" + will appear by the name of the device currently using + the port (it might not appear against any). The + string "none" means that there are no device drivers + using that port. + +``base-addr`` Parallel port's base address, or addresses if the port + has more than one in which case they are separated + with tabs. These values might not have any sensible + meaning for some ports. + +``irq`` Parallel port's IRQ, or -1 if none is being used. + +``dma`` Parallel port's DMA channel, or -1 if none is being + used. + +``modes`` Parallel port's hardware modes, comma-separated, + meaning: + + - PCSPP + PC-style SPP registers are available. + + - TRISTATE + Port is bidirectional. + + - COMPAT + Hardware acceleration for printers is + available and will be used. + + - EPP + Hardware acceleration for EPP protocol + is available and will be used. + + - ECP + Hardware acceleration for ECP protocol + is available and will be used. + + - DMA + DMA is available and will be used. + + Note that the current implementation will only take + advantage of COMPAT and ECP modes if it has an IRQ + line to use. + +``autoprobe`` Any IEEE-1284 device ID information that has been + acquired from the (non-IEEE 1284.3) device. + +``autoprobe[0-3]`` IEEE 1284 device ID information retrieved from + daisy-chain devices that conform to IEEE 1284.3. + +``spintime`` The number of microseconds to busy-loop while waiting + for the peripheral to respond. You might find that + adjusting this improves performance, depending on your + peripherals. This is a port-wide setting, i.e. it + applies to all devices on a particular port. + +``timeslice`` The number of milliseconds that a device driver is + allowed to keep a port claimed for. This is advisory, + and driver can ignore it if it must. + +``default/*`` The defaults for spintime and timeslice. When a new + port is registered, it picks up the default spintime. + When a new device is registered, it picks up the + default timeslice. +======================= ======================================================= + +Device drivers +============== + +Once the parport code is initialised, you can attach device drivers to +specific ports. Normally this happens automatically; if the lp driver +is loaded it will create one lp device for each port found. You can +override this, though, by using parameters either when you load the lp +driver:: + + # insmod lp parport=0,2 + +or on the LILO command line:: + + lp=parport0 lp=parport2 + +Both the above examples would inform lp that you want ``/dev/lp0`` to be +the first parallel port, and /dev/lp1 to be the **third** parallel port, +with no lp device associated with the second port (parport1). Note +that this is different to the way older kernels worked; there used to +be a static association between the I/O port address and the device +name, so ``/dev/lp0`` was always the port at 0x3bc. This is no longer the +case - if you only have one port, it will default to being ``/dev/lp0``, +regardless of base address. + +Also: + + * If you selected the IEEE 1284 support at compile time, you can say + ``lp=auto`` on the kernel command line, and lp will create devices + only for those ports that seem to have printers attached. + + * If you give PLIP the ``timid`` parameter, either with ``plip=timid`` on + the command line, or with ``insmod plip timid=1`` when using modules, + it will avoid any ports that seem to be in use by other devices. + + * IRQ autoprobing works only for a few port types at the moment. + +Reporting printer problems with parport +======================================= + +If you are having problems printing, please go through these steps to +try to narrow down where the problem area is. + +When reporting problems with parport, really you need to give all of +the messages that ``parport_pc`` spits out when it initialises. There are +several code paths: + +- polling +- interrupt-driven, protocol in software +- interrupt-driven, protocol in hardware using PIO +- interrupt-driven, protocol in hardware using DMA + +The kernel messages that ``parport_pc`` logs give an indication of which +code path is being used. (They could be a lot better actually..) + +For normal printer protocol, having IEEE 1284 modes enabled or not +should not make a difference. + +To turn off the 'protocol in hardware' code paths, disable +``CONFIG_PARPORT_PC_FIFO``. Note that when they are enabled they are not +necessarily **used**; it depends on whether the hardware is available, +enabled by the BIOS, and detected by the driver. + +So, to start with, disable ``CONFIG_PARPORT_PC_FIFO``, and load ``parport_pc`` +with ``irq=none``. See if printing works then. It really should, +because this is the simplest code path. + +If that works fine, try with ``io=0x378 irq=7`` (adjust for your +hardware), to make it use interrupt-driven in-software protocol. + +If **that** works fine, then one of the hardware modes isn't working +right. Enable ``CONFIG_FIFO`` (no, it isn't a module option, +and yes, it should be), set the port to ECP mode in the BIOS and note +the DMA channel, and try with:: + + io=0x378 irq=7 dma=none (for PIO) + io=0x378 irq=7 dma=3 (for DMA) + +---------- + +philb@gnu.org +tim@cyberelk.net diff --git a/Documentation/admin-guide/ramoops.rst b/Documentation/admin-guide/ramoops.rst new file mode 100644 index 000000000000..7eaf1e71c083 --- /dev/null +++ b/Documentation/admin-guide/ramoops.rst @@ -0,0 +1,154 @@ +Ramoops oops/panic logger +========================= + +Sergiu Iordache + +Updated: 17 November 2011 + +Introduction +------------ + +Ramoops is an oops/panic logger that writes its logs to RAM before the system +crashes. It works by logging oopses and panics in a circular buffer. Ramoops +needs a system with persistent RAM so that the content of that area can +survive after a restart. + +Ramoops concepts +---------------- + +Ramoops uses a predefined memory area to store the dump. The start and size +and type of the memory area are set using three variables: + + * ``mem_address`` for the start + * ``mem_size`` for the size. The memory size will be rounded down to a + power of two. + * ``mem_type`` to specifiy if the memory type (default is pgprot_writecombine). + +Typically the default value of ``mem_type=0`` should be used as that sets the pstore +mapping to pgprot_writecombine. Setting ``mem_type=1`` attempts to use +``pgprot_noncached``, which only works on some platforms. This is because pstore +depends on atomic operations. At least on ARM, pgprot_noncached causes the +memory to be mapped strongly ordered, and atomic operations on strongly ordered +memory are implementation defined, and won't work on many ARMs such as omaps. + +The memory area is divided into ``record_size`` chunks (also rounded down to +power of two) and each oops/panic writes a ``record_size`` chunk of +information. + +Dumping both oopses and panics can be done by setting 1 in the ``dump_oops`` +variable while setting 0 in that variable dumps only the panics. + +The module uses a counter to record multiple dumps but the counter gets reset +on restart (i.e. new dumps after the restart will overwrite old ones). + +Ramoops also supports software ECC protection of persistent memory regions. +This might be useful when a hardware reset was used to bring the machine back +to life (i.e. a watchdog triggered). In such cases, RAM may be somewhat +corrupt, but usually it is restorable. + +Setting the parameters +---------------------- + +Setting the ramoops parameters can be done in several different manners: + + A. Use the module parameters (which have the names of the variables described + as before). For quick debugging, you can also reserve parts of memory during + boot and then use the reserved memory for ramoops. For example, assuming a + machine with > 128 MB of memory, the following kernel command line will tell + the kernel to use only the first 128 MB of memory, and place ECC-protected + ramoops region at 128 MB boundary:: + + mem=128M ramoops.mem_address=0x8000000 ramoops.ecc=1 + + B. Use Device Tree bindings, as described in + ``Documentation/device-tree/bindings/reserved-memory/ramoops.txt``. + For example:: + + reserved-memory { + #address-cells = <2>; + #size-cells = <2>; + ranges; + + ramoops@8f000000 { + compatible = "ramoops"; + reg = <0 0x8f000000 0 0x100000>; + record-size = <0x4000>; + console-size = <0x4000>; + }; + }; + + C. Use a platform device and set the platform data. The parameters can then + be set through that platform data. An example of doing that is:: + + #include + [...] + + static struct ramoops_platform_data ramoops_data = { + .mem_size = <...>, + .mem_address = <...>, + .mem_type = <...>, + .record_size = <...>, + .dump_oops = <...>, + .ecc = <...>, + }; + + static struct platform_device ramoops_dev = { + .name = "ramoops", + .dev = { + .platform_data = &ramoops_data, + }, + }; + + [... inside a function ...] + int ret; + + ret = platform_device_register(&ramoops_dev); + if (ret) { + printk(KERN_ERR "unable to register platform device\n"); + return ret; + } + +You can specify either RAM memory or peripheral devices' memory. However, when +specifying RAM, be sure to reserve the memory by issuing memblock_reserve() +very early in the architecture code, e.g.:: + + #include + + memblock_reserve(ramoops_data.mem_address, ramoops_data.mem_size); + +Dump format +----------- + +The data dump begins with a header, currently defined as ``====`` followed by a +timestamp and a new line. The dump then continues with the actual data. + +Reading the data +---------------- + +The dump data can be read from the pstore filesystem. The format for these +files is ``dmesg-ramoops-N``, where N is the record number in memory. To delete +a stored record from RAM, simply unlink the respective pstore file. + +Persistent function tracing +--------------------------- + +Persistent function tracing might be useful for debugging software or hardware +related hangs. The functions call chain log is stored in a ``ftrace-ramoops`` +file. Here is an example of usage:: + + # mount -t debugfs debugfs /sys/kernel/debug/ + # echo 1 > /sys/kernel/debug/pstore/record_ftrace + # reboot -f + [...] + # mount -t pstore pstore /mnt/ + # tail /mnt/ftrace-ramoops + 0 ffffffff8101ea64 ffffffff8101bcda native_apic_mem_read <- disconnect_bsp_APIC+0x6a/0xc0 + 0 ffffffff8101ea44 ffffffff8101bcf6 native_apic_mem_write <- disconnect_bsp_APIC+0x86/0xc0 + 0 ffffffff81020084 ffffffff8101a4b5 hpet_disable <- native_machine_shutdown+0x75/0x90 + 0 ffffffff81005f94 ffffffff8101a4bb iommu_shutdown_noop <- native_machine_shutdown+0x7b/0x90 + 0 ffffffff8101a6a1 ffffffff8101a437 native_machine_emergency_restart <- native_machine_restart+0x37/0x40 + 0 ffffffff811f9876 ffffffff8101a73a acpi_reboot <- native_machine_emergency_restart+0xaa/0x1e0 + 0 ffffffff8101a514 ffffffff8101a772 mach_reboot_fixups <- native_machine_emergency_restart+0xe2/0x1e0 + 0 ffffffff811d9c54 ffffffff8101a7a0 __const_udelay <- native_machine_emergency_restart+0x110/0x1e0 + 0 ffffffff811d9c34 ffffffff811d9c80 __delay <- __const_udelay+0x30/0x40 + 0 ffffffff811d9d14 ffffffff811d9c3f delay_tsc <- __delay+0xf/0x20 diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst new file mode 100644 index 000000000000..05c53ac7fa76 --- /dev/null +++ b/Documentation/admin-guide/reporting-bugs.rst @@ -0,0 +1,182 @@ +.. _reportingbugs: + +Reporting bugs +++++++++++++++ + +Background +========== + +The upstream Linux kernel maintainers only fix bugs for specific kernel +versions. Those versions include the current "release candidate" (or -rc) +kernel, any "stable" kernel versions, and any "long term" kernels. + +Please see https://www.kernel.org/ for a list of supported kernels. Any +kernel marked with [EOL] is "end of life" and will not have any fixes +backported to it. + +If you've found a bug on a kernel version that isn't listed on kernel.org, +contact your Linux distribution or embedded vendor for support. +Alternatively, you can attempt to run one of the supported stable or -rc +kernels, and see if you can reproduce the bug on that. It's preferable +to reproduce the bug on the latest -rc kernel. + + +How to report Linux kernel bugs +=============================== + + +Identify the problematic subsystem +---------------------------------- + +Identifying which part of the Linux kernel might be causing your issue +increases your chances of getting your bug fixed. Simply posting to the +generic linux-kernel mailing list (LKML) may cause your bug report to be +lost in the noise of a mailing list that gets 1000+ emails a day. + +Instead, try to figure out which kernel subsystem is causing the issue, +and email that subsystem's maintainer and mailing list. If the subsystem +maintainer doesn't answer, then expand your scope to mailing lists like +LKML. + + +Identify who to notify +---------------------- + +Once you know the subsystem that is causing the issue, you should send a +bug report. Some maintainers prefer bugs to be reported via bugzilla +(https://bugzilla.kernel.org), while others prefer that bugs be reported +via the subsystem mailing list. + +To find out where to send an emailed bug report, find your subsystem or +device driver in the MAINTAINERS file. Search in the file for relevant +entries, and send your bug report to the person(s) listed in the "M:" +lines, making sure to Cc the mailing list(s) in the "L:" lines. When the +maintainer replies to you, make sure to 'Reply-all' in order to keep the +public mailing list(s) in the email thread. + +If you know which driver is causing issues, you can pass one of the driver +files to the get_maintainer.pl script:: + + perl scripts/get_maintainer.pl -f + +If it is a security bug, please copy the Security Contact listed in the +MAINTAINERS file. They can help coordinate bugfix and disclosure. See +:ref:`Documentation/SecurityBugs ` for more information. + +If you can't figure out which subsystem caused the issue, you should file +a bug in kernel.org bugzilla and send email to +linux-kernel@vger.kernel.org, referencing the bugzilla URL. (For more +information on the linux-kernel mailing list see +http://www.tux.org/lkml/). + + +Tips for reporting bugs +----------------------- + +If you haven't reported a bug before, please read: + + http://www.chiark.greenend.org.uk/~sgtatham/bugs.html + + http://www.catb.org/esr/faqs/smart-questions.html + +It's REALLY important to report bugs that seem unrelated as separate email +threads or separate bugzilla entries. If you report several unrelated +bugs at once, it's difficult for maintainers to tease apart the relevant +data. + + +Gather information +------------------ + +The most important information in a bug report is how to reproduce the +bug. This includes system information, and (most importantly) +step-by-step instructions for how a user can trigger the bug. + +If the failure includes an "OOPS:", take a picture of the screen, capture +a netconsole trace, or type the message from your screen into the bug +report. Please read "Documentation/oops-tracing.txt" before posting your +bug report. This explains what you should do with the "Oops" information +to make it useful to the recipient. + +This is a suggested format for a bug report sent via email or bugzilla. +Having a standardized bug report form makes it easier for you not to +overlook things, and easier for the developers to find the pieces of +information they're really interested in. If some information is not +relevant to your bug, feel free to exclude it. + +First run the ver_linux script included as scripts/ver_linux, which +reports the version of some important subsystems. Run this script with +the command ``sh scripts/ver_linux``. + +Use that information to fill in all fields of the bug report form, and +post it to the mailing list with a subject of "PROBLEM: " for easy identification by the developers:: + + [1.] One line summary of the problem: + [2.] Full description of the problem/report: + [3.] Keywords (i.e., modules, networking, kernel): + [4.] Kernel information + [4.1.] Kernel version (from /proc/version): + [4.2.] Kernel .config file: + [5.] Most recent kernel version which did not have the bug: + [6.] Output of Oops.. message (if applicable) with symbolic information + resolved (see Documentation/oops-tracing.txt) + [7.] A small shell script or example program which triggers the + problem (if possible) + [8.] Environment + [8.1.] Software (add the output of the ver_linux script here) + [8.2.] Processor information (from /proc/cpuinfo): + [8.3.] Module information (from /proc/modules): + [8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem) + [8.5.] PCI information ('lspci -vvv' as root) + [8.6.] SCSI information (from /proc/scsi/scsi) + [8.7.] Other information that might be relevant to the problem + (please look in /proc and include all information that you + think to be relevant): + [X.] Other notes, patches, fixes, workarounds: + + +Follow up +========= + +Expectations for bug reporters +------------------------------ + +Linux kernel maintainers expect bug reporters to be able to follow up on +bug reports. That may include running new tests, applying patches, +recompiling your kernel, and/or re-triggering your bug. The most +frustrating thing for maintainers is for someone to report a bug, and then +never follow up on a request to try out a fix. + +That said, it's still useful for a kernel maintainer to know a bug exists +on a supported kernel, even if you can't follow up with retests. Follow +up reports, such as replying to the email thread with "I tried the latest +kernel and I can't reproduce my bug anymore" are also helpful, because +maintainers have to assume silence means things are still broken. + +Expectations for kernel maintainers +----------------------------------- + +Linux kernel maintainers are busy, overworked human beings. Some times +they may not be able to address your bug in a day, a week, or two weeks. +If they don't answer your email, they may be on vacation, or at a Linux +conference. Check the conference schedule at https://LWN.net for more info: + + https://lwn.net/Calendar/ + +In general, kernel maintainers take 1 to 5 business days to respond to +bugs. The majority of kernel maintainers are employed to work on the +kernel, and they may not work on the weekends. Maintainers are scattered +around the world, and they may not work in your time zone. Unless you +have a high priority bug, please wait at least a week after the first bug +report before sending the maintainer a reminder email. + +The exceptions to this rule are regressions, kernel crashes, security holes, +or userspace breakage caused by new kernel behavior. Those bugs should be +addressed by the maintainers ASAP. If you suspect a maintainer is not +responding to these types of bugs in a timely manner (especially during a +merge window), escalate the bug to LKML and Linus Torvalds. + +Thank you! + +[Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ] diff --git a/Documentation/admin-guide/security-bugs.rst b/Documentation/admin-guide/security-bugs.rst new file mode 100644 index 000000000000..df795e22d08b --- /dev/null +++ b/Documentation/admin-guide/security-bugs.rst @@ -0,0 +1,46 @@ +.. _securitybugs: + +Security bugs +============= + +Linux kernel developers take security very seriously. As such, we'd +like to know when a security bug is found so that it can be fixed and +disclosed as quickly as possible. Please report security bugs to the +Linux kernel security team. + +Contact +------- + +The Linux kernel security team can be contacted by email at +. This is a private list of security officers +who will help verify the bug report and develop and release a fix. +It is possible that the security team will bring in extra help from +area maintainers to understand and fix the security vulnerability. + +As it is with any bug, the more information provided the easier it +will be to diagnose and fix. Please review the procedure outlined in +REPORTING-BUGS if you are unclear about what information is helpful. +Any exploit code is very helpful and will not be released without +consent from the reporter unless it has already been made public. + +Disclosure +---------- + +The goal of the Linux kernel security team is to work with the +bug submitter to bug resolution as well as disclosure. We prefer +to fully disclose the bug as soon as possible. It is reasonable to +delay disclosure when the bug or the fix is not yet fully understood, +the solution is not well-tested or for vendor coordination. However, we +expect these delays to be short, measurable in days, not weeks or months. +A disclosure date is negotiated by the security team working with the +bug submitter as well as vendors. However, the kernel security team +holds the final say when setting a disclosure date. The timeframe for +disclosure is from immediate (esp. if it's already publicly known) +to a few weeks. As a basic default policy, we expect report date to +disclosure date to be on the order of 7 days. + +Non-disclosure agreements +------------------------- + +The Linux kernel security team is not a formal body and therefore unable +to enter any non-disclosure agreements. diff --git a/Documentation/admin-guide/serial-console.rst b/Documentation/admin-guide/serial-console.rst new file mode 100644 index 000000000000..a8d1e36b627a --- /dev/null +++ b/Documentation/admin-guide/serial-console.rst @@ -0,0 +1,115 @@ +.. _serial_console: + +Linux Serial Console +==================== + +To use a serial port as console you need to compile the support into your +kernel - by default it is not compiled in. For PC style serial ports +it's the config option next to menu option: + +:menuselection:`Character devices --> Serial drivers --> 8250/16550 and compatible serial support --> Console on 8250/16550 and compatible serial port` + +You must compile serial support into the kernel and not as a module. + +It is possible to specify multiple devices for console output. You can +define a new kernel command line option to select which device(s) to +use for console output. + +The format of this option is:: + + console=device,options + + device: tty0 for the foreground virtual console + ttyX for any other virtual console + ttySx for a serial port + lp0 for the first parallel port + ttyUSB0 for the first USB serial device + + options: depend on the driver. For the serial port this + defines the baudrate/parity/bits/flow control of + the port, in the format BBBBPNF, where BBBB is the + speed, P is parity (n/o/e), N is number of bits, + and F is flow control ('r' for RTS). Default is + 9600n8. The maximum baudrate is 115200. + +You can specify multiple console= options on the kernel command line. +Output will appear on all of them. The last device will be used when +you open ``/dev/console``. So, for example:: + + console=ttyS1,9600 console=tty0 + +defines that opening ``/dev/console`` will get you the current foreground +virtual console, and kernel messages will appear on both the VGA +console and the 2nd serial port (ttyS1 or COM2) at 9600 baud. + +Note that you can only define one console per device type (serial, video). + +If no console device is specified, the first device found capable of +acting as a system console will be used. At this time, the system +first looks for a VGA card and then for a serial port. So if you don't +have a VGA card in your system the first serial port will automatically +become the console. + +You will need to create a new device to use ``/dev/console``. The official +``/dev/console`` is now character device 5,1. + +(You can also use a network device as a console. See +``Documentation/networking/netconsole.txt`` for information on that.) + +Here's an example that will use ``/dev/ttyS1`` (COM2) as the console. +Replace the sample values as needed. + +1. Create ``/dev/console`` (real console) and ``/dev/tty0`` (master virtual + console):: + + cd /dev + rm -f console tty0 + mknod -m 622 console c 5 1 + mknod -m 622 tty0 c 4 0 + +2. LILO can also take input from a serial device. This is a very + useful option. To tell LILO to use the serial port: + In lilo.conf (global section):: + + serial = 1,9600n8 (ttyS1, 9600 bd, no parity, 8 bits) + +3. Adjust to kernel flags for the new kernel, + again in lilo.conf (kernel section):: + + append = "console=ttyS1,9600" + +4. Make sure a getty runs on the serial port so that you can login to + it once the system is done booting. This is done by adding a line + like this to ``/etc/inittab`` (exact syntax depends on your getty):: + + S1:23:respawn:/sbin/getty -L ttyS1 9600 vt100 + +5. Init and ``/etc/ioctl.save`` + + Sysvinit remembers its stty settings in a file in ``/etc``, called + ``/etc/ioctl.save``. REMOVE THIS FILE before using the serial + console for the first time, because otherwise init will probably + set the baudrate to 38400 (baudrate of the virtual console). + +6. ``/dev/console`` and X + Programs that want to do something with the virtual console usually + open ``/dev/console``. If you have created the new ``/dev/console`` device, + and your console is NOT the virtual console some programs will fail. + Those are programs that want to access the VT interface, and use + ``/dev/console instead of /dev/tty0``. Some of those programs are:: + + Xfree86, svgalib, gpm, SVGATextMode + + It should be fixed in modern versions of these programs though. + + Note that if you boot without a ``console=`` option (or with + ``console=/dev/tty0``), ``/dev/console`` is the same as ``/dev/tty0``. + In that case everything will still work. + +7. Thanks + + Thanks to Geert Uytterhoeven + for porting the patches from 2.1.4x to 2.1.6x for taking care of + the integration of these patches into m68k, ppc and alpha. + +Miquel van Smoorenburg , 11-Jun-2000 diff --git a/Documentation/admin-guide/sysfs-rules.rst b/Documentation/admin-guide/sysfs-rules.rst new file mode 100644 index 000000000000..04bdd52cba1d --- /dev/null +++ b/Documentation/admin-guide/sysfs-rules.rst @@ -0,0 +1,192 @@ +Rules on how to access information in the Linux kernel sysfs +============================================================ + +The kernel-exported sysfs exports internal kernel implementation details +and depends on internal kernel structures and layout. It is agreed upon +by the kernel developers that the Linux kernel does not provide a stable +internal API. Therefore, there are aspects of the sysfs interface that +may not be stable across kernel releases. + +To minimize the risk of breaking users of sysfs, which are in most cases +low-level userspace applications, with a new kernel release, the users +of sysfs must follow some rules to use an as-abstract-as-possible way to +access this filesystem. The current udev and HAL programs already +implement this and users are encouraged to plug, if possible, into the +abstractions these programs provide instead of accessing sysfs directly. + +But if you really do want or need to access sysfs directly, please follow +the following rules and then your programs should work with future +versions of the sysfs interface. + +- Do not use libsysfs + It makes assumptions about sysfs which are not true. Its API does not + offer any abstraction, it exposes all the kernel driver-core + implementation details in its own API. Therefore it is not better than + reading directories and opening the files yourself. + Also, it is not actively maintained, in the sense of reflecting the + current kernel development. The goal of providing a stable interface + to sysfs has failed; it causes more problems than it solves. It + violates many of the rules in this document. + +- sysfs is always at ``/sys`` + Parsing ``/proc/mounts`` is a waste of time. Other mount points are a + system configuration bug you should not try to solve. For test cases, + possibly support a ``SYSFS_PATH`` environment variable to overwrite the + application's behavior, but never try to search for sysfs. Never try + to mount it, if you are not an early boot script. + +- devices are only "devices" + There is no such thing like class-, bus-, physical devices, + interfaces, and such that you can rely on in userspace. Everything is + just simply a "device". Class-, bus-, physical, ... types are just + kernel implementation details which should not be expected by + applications that look for devices in sysfs. + + The properties of a device are: + + - devpath (``/devices/pci0000:00/0000:00:1d.1/usb2/2-2/2-2:1.0``) + + - identical to the DEVPATH value in the event sent from the kernel + at device creation and removal + - the unique key to the device at that point in time + - the kernel's path to the device directory without the leading + ``/sys``, and always starting with a slash + - all elements of a devpath must be real directories. Symlinks + pointing to /sys/devices must always be resolved to their real + target and the target path must be used to access the device. + That way the devpath to the device matches the devpath of the + kernel used at event time. + - using or exposing symlink values as elements in a devpath string + is a bug in the application + + - kernel name (``sda``, ``tty``, ``0000:00:1f.2``, ...) + + - a directory name, identical to the last element of the devpath + - applications need to handle spaces and characters like ``!`` in + the name + + - subsystem (``block``, ``tty``, ``pci``, ...) + + - simple string, never a path or a link + - retrieved by reading the "subsystem"-link and using only the + last element of the target path + + - driver (``tg3``, ``ata_piix``, ``uhci_hcd``) + + - a simple string, which may contain spaces, never a path or a + link + - it is retrieved by reading the "driver"-link and using only the + last element of the target path + - devices which do not have "driver"-link just do not have a + driver; copying the driver value in a child device context is a + bug in the application + + - attributes + + - the files in the device directory or files below subdirectories + of the same device directory + - accessing attributes reached by a symlink pointing to another device, + like the "device"-link, is a bug in the application + + Everything else is just a kernel driver-core implementation detail + that should not be assumed to be stable across kernel releases. + +- Properties of parent devices never belong into a child device. + Always look at the parent devices themselves for determining device + context properties. If the device ``eth0`` or ``sda`` does not have a + "driver"-link, then this device does not have a driver. Its value is empty. + Never copy any property of the parent-device into a child-device. Parent + device properties may change dynamically without any notice to the + child device. + +- Hierarchy in a single device tree + There is only one valid place in sysfs where hierarchy can be examined + and this is below: ``/sys/devices.`` + It is planned that all device directories will end up in the tree + below this directory. + +- Classification by subsystem + There are currently three places for classification of devices: + ``/sys/block,`` ``/sys/class`` and ``/sys/bus.`` It is planned that these will + not contain any device directories themselves, but only flat lists of + symlinks pointing to the unified ``/sys/devices`` tree. + All three places have completely different rules on how to access + device information. It is planned to merge all three + classification directories into one place at ``/sys/subsystem``, + following the layout of the bus directories. All buses and + classes, including the converted block subsystem, will show up + there. + The devices belonging to a subsystem will create a symlink in the + "devices" directory at ``/sys/subsystem//devices``, + + If ``/sys/subsystem`` exists, ``/sys/bus``, ``/sys/class`` and ``/sys/block`` + can be ignored. If it does not exist, you always have to scan all three + places, as the kernel is free to move a subsystem from one place to + the other, as long as the devices are still reachable by the same + subsystem name. + + Assuming ``/sys/class/`` and ``/sys/bus/``, or + ``/sys/block`` and ``/sys/class/block`` are not interchangeable is a bug in + the application. + +- Block + The converted block subsystem at ``/sys/class/block`` or + ``/sys/subsystem/block`` will contain the links for disks and partitions + at the same level, never in a hierarchy. Assuming the block subsystem to + contain only disks and not partition devices in the same flat list is + a bug in the application. + +- "device"-link and :-links + Never depend on the "device"-link. The "device"-link is a workaround + for the old layout, where class devices are not created in + ``/sys/devices/`` like the bus devices. If the link-resolving of a + device directory does not end in ``/sys/devices/``, you can use the + "device"-link to find the parent devices in ``/sys/devices/``, That is the + single valid use of the "device"-link; it must never appear in any + path as an element. Assuming the existence of the "device"-link for + a device in ``/sys/devices/`` is a bug in the application. + Accessing ``/sys/class/net/eth0/device`` is a bug in the application. + + Never depend on the class-specific links back to the ``/sys/class`` + directory. These links are also a workaround for the design mistake + that class devices are not created in ``/sys/devices.`` If a device + directory does not contain directories for child devices, these links + may be used to find the child devices in ``/sys/class.`` That is the single + valid use of these links; they must never appear in any path as an + element. Assuming the existence of these links for devices which are + real child device directories in the ``/sys/devices`` tree is a bug in + the application. + + It is planned to remove all these links when all class device + directories live in ``/sys/devices.`` + +- Position of devices along device chain can change. + Never depend on a specific parent device position in the devpath, + or the chain of parent devices. The kernel is free to insert devices into + the chain. You must always request the parent device you are looking for + by its subsystem value. You need to walk up the chain until you find + the device that matches the expected subsystem. Depending on a specific + position of a parent device or exposing relative paths using ``../`` to + access the chain of parents is a bug in the application. + +- When reading and writing sysfs device attribute files, avoid dependency + on specific error codes wherever possible. This minimizes coupling to + the error handling implementation within the kernel. + + In general, failures to read or write sysfs device attributes shall + propagate errors wherever possible. Common errors include, but are not + limited to: + + ``-EIO``: The read or store operation is not supported, typically + returned by the sysfs system itself if the read or store pointer + is ``NULL``. + + ``-ENXIO``: The read or store operation failed + + Error codes will not be changed without good reason, and should a change + to error codes result in user-space breakage, it will be fixed, or the + the offending change will be reverted. + + Userspace applications can, however, expect the format and contents of + the attribute files to remain consistent in the absence of a version + attribute change in the context of a given attribute. diff --git a/Documentation/admin-guide/sysrq.rst b/Documentation/admin-guide/sysrq.rst new file mode 100644 index 000000000000..d1712ea2d314 --- /dev/null +++ b/Documentation/admin-guide/sysrq.rst @@ -0,0 +1,289 @@ +Linux Magic System Request Key Hacks +==================================== + +Documentation for sysrq.c + +What is the magic SysRq key? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It is a 'magical' key combo you can hit which the kernel will respond to +regardless of whatever else it is doing, unless it is completely locked up. + +How do I enable the magic SysRq key? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You need to say "yes" to 'Magic SysRq key (CONFIG_MAGIC_SYSRQ)' when +configuring the kernel. When running a kernel with SysRq compiled in, +/proc/sys/kernel/sysrq controls the functions allowed to be invoked via +the SysRq key. The default value in this file is set by the +CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE config symbol, which itself defaults +to 1. Here is the list of possible values in /proc/sys/kernel/sysrq: + + - 0 - disable sysrq completely + - 1 - enable all functions of sysrq + - >1 - bitmask of allowed sysrq functions (see below for detailed function + description):: + + 2 = 0x2 - enable control of console logging level + 4 = 0x4 - enable control of keyboard (SAK, unraw) + 8 = 0x8 - enable debugging dumps of processes etc. + 16 = 0x10 - enable sync command + 32 = 0x20 - enable remount read-only + 64 = 0x40 - enable signalling of processes (term, kill, oom-kill) + 128 = 0x80 - allow reboot/poweroff + 256 = 0x100 - allow nicing of all RT tasks + +You can set the value in the file by the following command:: + + echo "number" >/proc/sys/kernel/sysrq + +The number may be written here either as decimal or as hexadecimal +with the 0x prefix. CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE must always be +written in hexadecimal. + +Note that the value of ``/proc/sys/kernel/sysrq`` influences only the invocation +via a keyboard. Invocation of any operation via ``/proc/sysrq-trigger`` is +always allowed (by a user with admin privileges). + +How do I use the magic SysRq key? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +On x86 - You press the key combo :kbd:`ALT-SysRq-`. + +.. note:: + Some + keyboards may not have a key labeled 'SysRq'. The 'SysRq' key is + also known as the 'Print Screen' key. Also some keyboards cannot + handle so many keys being pressed at the same time, so you might + have better luck with press :kbd:`Alt`, press :kbd:`SysRq`, + release :kbd:`SysRq`, press :kbd:``, release everything. + +On SPARC - You press :kbd:`ALT-STOP-`, I believe. + +On the serial console (PC style standard serial ports only) + You send a ``BREAK``, then within 5 seconds a command key. Sending + ``BREAK`` twice is interpreted as a normal BREAK. + +On PowerPC + Press :kbd:`ALT - Print Screen` (or :kbd:`F13`) - :kbd:``, + :kbd:`Print Screen` (or :kbd:`F13`) - :kbd:`` may suffice. + +On other + If you know of the key combos for other architectures, please + let me know so I can add them to this section. + +On all + write a character to /proc/sysrq-trigger. e.g.:: + + echo t > /proc/sysrq-trigger + +What are the 'command' keys? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +=========== =================================================================== +Command Function +=========== =================================================================== +``b`` Will immediately reboot the system without syncing or unmounting + your disks. + +``c`` Will perform a system crash by a NULL pointer dereference. + A crashdump will be taken if configured. + +``d`` Shows all locks that are held. + +``e`` Send a SIGTERM to all processes, except for init. + +``f`` Will call the oom killer to kill a memory hog process, but do not + panic if nothing can be killed. + +``g`` Used by kgdb (kernel debugger) + +``h`` Will display help (actually any other key than those listed + here will display help. but ``h`` is easy to remember :-) + +``i`` Send a SIGKILL to all processes, except for init. + +``j`` Forcibly "Just thaw it" - filesystems frozen by the FIFREEZE ioctl. + +``k`` Secure Access Key (SAK) Kills all programs on the current virtual + console. NOTE: See important comments below in SAK section. + +``l`` Shows a stack backtrace for all active CPUs. + +``m`` Will dump current memory info to your console. + +``n`` Used to make RT tasks nice-able + +``o`` Will shut your system off (if configured and supported). + +``p`` Will dump the current registers and flags to your console. + +``q`` Will dump per CPU lists of all armed hrtimers (but NOT regular + timer_list timers) and detailed information about all + clockevent devices. + +``r`` Turns off keyboard raw mode and sets it to XLATE. + +``s`` Will attempt to sync all mounted filesystems. + +``t`` Will dump a list of current tasks and their information to your + console. + +``u`` Will attempt to remount all mounted filesystems read-only. + +``v`` Forcefully restores framebuffer console +``v`` Causes ETM buffer dump [ARM-specific] + +``w`` Dumps tasks that are in uninterruptable (blocked) state. + +``x`` Used by xmon interface on ppc/powerpc platforms. + Show global PMU Registers on sparc64. + Dump all TLB entries on MIPS. + +``y`` Show global CPU Registers [SPARC-64 specific] + +``z`` Dump the ftrace buffer + +``0``-``9`` Sets the console log level, controlling which kernel messages + will be printed to your console. (``0``, for example would make + it so that only emergency messages like PANICs or OOPSes would + make it to your console.) +=========== =================================================================== + +Okay, so what can I use them for? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Well, unraw(r) is very handy when your X server or a svgalib program crashes. + +sak(k) (Secure Access Key) is useful when you want to be sure there is no +trojan program running at console which could grab your password +when you would try to login. It will kill all programs on given console, +thus letting you make sure that the login prompt you see is actually +the one from init, not some trojan program. + +.. important:: + + In its true form it is not a true SAK like the one in a + c2 compliant system, and it should not be mistaken as + such. + +It seems others find it useful as (System Attention Key) which is +useful when you want to exit a program that will not let you switch consoles. +(For example, X or a svgalib program.) + +``reboot(b)`` is good when you're unable to shut down. But you should also +``sync(s)`` and ``umount(u)`` first. + +``crash(c)`` can be used to manually trigger a crashdump when the system is hung. +Note that this just triggers a crash if there is no dump mechanism available. + +``sync(s)`` is great when your system is locked up, it allows you to sync your +disks and will certainly lessen the chance of data loss and fscking. Note +that the sync hasn't taken place until you see the "OK" and "Done" appear +on the screen. (If the kernel is really in strife, you may not ever get the +OK or Done message...) + +``umount(u)`` is basically useful in the same ways as ``sync(s)``. I generally +``sync(s)``, ``umount(u)``, then ``reboot(b)`` when my system locks. It's saved +me many a fsck. Again, the unmount (remount read-only) hasn't taken place until +you see the "OK" and "Done" message appear on the screen. + +The loglevels ``0``-``9`` are useful when your console is being flooded with +kernel messages you do not want to see. Selecting ``0`` will prevent all but +the most urgent kernel messages from reaching your console. (They will +still be logged if syslogd/klogd are alive, though.) + +``term(e)`` and ``kill(i)`` are useful if you have some sort of runaway process +you are unable to kill any other way, especially if it's spawning other +processes. + +"just thaw ``it(j)``" is useful if your system becomes unresponsive due to a +frozen (probably root) filesystem via the FIFREEZE ioctl. + +Sometimes SysRq seems to get 'stuck' after using it, what can I do? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +That happens to me, also. I've found that tapping shift, alt, and control +on both sides of the keyboard, and hitting an invalid sysrq sequence again +will fix the problem. (i.e., something like :kbd:`alt-sysrq-z`). Switching to +another virtual console (:kbd:`ALT+Fn`) and then back again should also help. + +I hit SysRq, but nothing seems to happen, what's wrong? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are some keyboards that produce a different keycode for SysRq than the +pre-defined value of 99 (see ``KEY_SYSRQ`` in ``include/linux/input.h``), or +which don't have a SysRq key at all. In these cases, run ``showkey -s`` to find +an appropriate scancode sequence, and use ``setkeycodes 99`` to map +this sequence to the usual SysRq code (e.g., ``setkeycodes e05b 99``). It's +probably best to put this command in a boot script. Oh, and by the way, you +exit ``showkey`` by not typing anything for ten seconds. + +I want to add SysRQ key events to a module, how does it work? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to register a basic function with the table, you must first include +the header ``include/linux/sysrq.h``, this will define everything else you need. +Next, you must create a ``sysrq_key_op`` struct, and populate it with A) the key +handler function you will use, B) a help_msg string, that will print when SysRQ +prints help, and C) an action_msg string, that will print right before your +handler is called. Your handler must conform to the prototype in 'sysrq.h'. + +After the ``sysrq_key_op`` is created, you can call the kernel function +``register_sysrq_key(int key, struct sysrq_key_op *op_p);`` this will +register the operation pointed to by ``op_p`` at table key 'key', +if that slot in the table is blank. At module unload time, you must call +the function ``unregister_sysrq_key(int key, struct sysrq_key_op *op_p)``, which +will remove the key op pointed to by 'op_p' from the key 'key', if and only if +it is currently registered in that slot. This is in case the slot has been +overwritten since you registered it. + +The Magic SysRQ system works by registering key operations against a key op +lookup table, which is defined in 'drivers/tty/sysrq.c'. This key table has +a number of operations registered into it at compile time, but is mutable, +and 2 functions are exported for interface to it:: + + register_sysrq_key and unregister_sysrq_key. + +Of course, never ever leave an invalid pointer in the table. I.e., when +your module that called register_sysrq_key() exits, it must call +unregister_sysrq_key() to clean up the sysrq key table entry that it used. +Null pointers in the table are always safe. :) + +If for some reason you feel the need to call the handle_sysrq function from +within a function called by handle_sysrq, you must be aware that you are in +a lock (you are also in an interrupt handler, which means don't sleep!), so +you must call ``__handle_sysrq_nolock`` instead. + +When I hit a SysRq key combination only the header appears on the console? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Sysrq output is subject to the same console loglevel control as all +other console output. This means that if the kernel was booted 'quiet' +as is common on distro kernels the output may not appear on the actual +console, even though it will appear in the dmesg buffer, and be accessible +via the dmesg command and to the consumers of ``/proc/kmsg``. As a specific +exception the header line from the sysrq command is passed to all console +consumers as if the current loglevel was maximum. If only the header +is emitted it is almost certain that the kernel loglevel is too low. +Should you require the output on the console channel then you will need +to temporarily up the console loglevel using :kbd:`alt-sysrq-8` or:: + + echo 8 > /proc/sysrq-trigger + +Remember to return the loglevel to normal after triggering the sysrq +command you are interested in. + +I have more questions, who can I ask? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Just ask them on the linux-kernel mailing list: + linux-kernel@vger.kernel.org + +Credits +~~~~~~~ + +Written by Mydraal +Updated by Adam Sulmicki +Updated by Jeremy M. Dolan 2001/01/28 10:15:59 +Added to by Crutcher Dunnavant diff --git a/Documentation/admin-guide/unicode.rst b/Documentation/admin-guide/unicode.rst new file mode 100644 index 000000000000..012e8e895842 --- /dev/null +++ b/Documentation/admin-guide/unicode.rst @@ -0,0 +1,189 @@ +Unicode support +=============== + + Last update: 2005-01-17, version 1.4 + +This file is maintained by H. Peter Anvin as part +of the Linux Assigned Names And Numbers Authority (LANANA) project. +The current version can be found at: + + http://www.lanana.org/docs/unicode/unicode.txt + +Introdution +----------- + +The Linux kernel code has been rewritten to use Unicode to map +characters to fonts. By downloading a single Unicode-to-font table, +both the eight-bit character sets and UTF-8 mode are changed to use +the font as indicated. + +This changes the semantics of the eight-bit character tables subtly. +The four character tables are now: + +=============== =============================== ================ +Map symbol Map name Escape code (G0) +=============== =============================== ================ +LAT1_MAP Latin-1 (ISO 8859-1) ESC ( B +GRAF_MAP DEC VT100 pseudographics ESC ( 0 +IBMPC_MAP IBM code page 437 ESC ( U +USER_MAP User defined ESC ( K +=============== =============================== ================ + +In particular, ESC ( U is no longer "straight to font", since the font +might be completely different than the IBM character set. This +permits for example the use of block graphics even with a Latin-1 font +loaded. + +Note that although these codes are similar to ISO 2022, neither the +codes nor their uses match ISO 2022; Linux has two 8-bit codes (G0 and +G1), whereas ISO 2022 has four 7-bit codes (G0-G3). + +In accordance with the Unicode standard/ISO 10646 the range U+F000 to +U+F8FF has been reserved for OS-wide allocation (the Unicode Standard +refers to this as a "Corporate Zone", since this is inaccurate for +Linux we call it the "Linux Zone"). U+F000 was picked as the starting +point since it lets the direct-mapping area start on a large power of +two (in case 1024- or 2048-character fonts ever become necessary). +This leaves U+E000 to U+EFFF as End User Zone. + +[v1.2]: The Unicodes range from U+F000 and up to U+F7FF have been +hard-coded to map directly to the loaded font, bypassing the +translation table. The user-defined map now defaults to U+F000 to +U+F0FF, emulating the previous behaviour. In practice, this range +might be shorter; for example, vgacon can only handle 256-character +(U+F000..U+F0FF) or 512-character (U+F000..U+F1FF) fonts. + + +Actual characters assigned in the Linux Zone +-------------------------------------------- + +In addition, the following characters not present in Unicode 1.1.4 +have been defined; these are used by the DEC VT graphics map. [v1.2] +THIS USE IS OBSOLETE AND SHOULD NO LONGER BE USED; PLEASE SEE BELOW. + +====== ====================================== +U+F800 DEC VT GRAPHICS HORIZONTAL LINE SCAN 1 +U+F801 DEC VT GRAPHICS HORIZONTAL LINE SCAN 3 +U+F803 DEC VT GRAPHICS HORIZONTAL LINE SCAN 7 +U+F804 DEC VT GRAPHICS HORIZONTAL LINE SCAN 9 +====== ====================================== + +The DEC VT220 uses a 6x10 character matrix, and these characters form +a smooth progression in the DEC VT graphics character set. I have +omitted the scan 5 line, since it is also used as a block-graphics +character, and hence has been coded as U+2500 FORMS LIGHT HORIZONTAL. + +[v1.3]: These characters have been officially added to Unicode 3.2.0; +they are added at U+23BA, U+23BB, U+23BC, U+23BD. Linux now uses the +new values. + +[v1.2]: The following characters have been added to represent common +keyboard symbols that are unlikely to ever be added to Unicode proper +since they are horribly vendor-specific. This, of course, is an +excellent example of horrible design. + +====== ====================================== +U+F810 KEYBOARD SYMBOL FLYING FLAG +U+F811 KEYBOARD SYMBOL PULLDOWN MENU +U+F812 KEYBOARD SYMBOL OPEN APPLE +U+F813 KEYBOARD SYMBOL SOLID APPLE +====== ====================================== + +Klingon language support +------------------------ + +In 1996, Linux was the first operating system in the world to add +support for the artificial language Klingon, created by Marc Okrand +for the "Star Trek" television series. This encoding was later +adopted by the ConScript Unicode Registry and proposed (but ultimately +rejected) for inclusion in Unicode Plane 1. Thus, it remains as a +Linux/CSUR private assignment in the Linux Zone. + +This encoding has been endorsed by the Klingon Language Institute. +For more information, contact them at: + + http://www.kli.org/ + +Since the characters in the beginning of the Linux CZ have been more +of the dingbats/symbols/forms type and this is a language, I have +located it at the end, on a 16-cell boundary in keeping with standard +Unicode practice. + +.. note:: + + This range is now officially managed by the ConScript Unicode + Registry. The normative reference is at: + + http://www.evertype.com/standards/csur/klingon.html + +Klingon has an alphabet of 26 characters, a positional numeric writing +system with 10 digits, and is written left-to-right, top-to-bottom. + +Several glyph forms for the Klingon alphabet have been proposed. +However, since the set of symbols appear to be consistent throughout, +with only the actual shapes being different, in keeping with standard +Unicode practice these differences are considered font variants. + +====== ======================================================= +U+F8D0 KLINGON LETTER A +U+F8D1 KLINGON LETTER B +U+F8D2 KLINGON LETTER CH +U+F8D3 KLINGON LETTER D +U+F8D4 KLINGON LETTER E +U+F8D5 KLINGON LETTER GH +U+F8D6 KLINGON LETTER H +U+F8D7 KLINGON LETTER I +U+F8D8 KLINGON LETTER J +U+F8D9 KLINGON LETTER L +U+F8DA KLINGON LETTER M +U+F8DB KLINGON LETTER N +U+F8DC KLINGON LETTER NG +U+F8DD KLINGON LETTER O +U+F8DE KLINGON LETTER P +U+F8DF KLINGON LETTER Q + - Written in standard Okrand Latin transliteration +U+F8E0 KLINGON LETTER QH + - Written in standard Okrand Latin transliteration +U+F8E1 KLINGON LETTER R +U+F8E2 KLINGON LETTER S +U+F8E3 KLINGON LETTER T +U+F8E4 KLINGON LETTER TLH +U+F8E5 KLINGON LETTER U +U+F8E6 KLINGON LETTER V +U+F8E7 KLINGON LETTER W +U+F8E8 KLINGON LETTER Y +U+F8E9 KLINGON LETTER GLOTTAL STOP + +U+F8F0 KLINGON DIGIT ZERO +U+F8F1 KLINGON DIGIT ONE +U+F8F2 KLINGON DIGIT TWO +U+F8F3 KLINGON DIGIT THREE +U+F8F4 KLINGON DIGIT FOUR +U+F8F5 KLINGON DIGIT FIVE +U+F8F6 KLINGON DIGIT SIX +U+F8F7 KLINGON DIGIT SEVEN +U+F8F8 KLINGON DIGIT EIGHT +U+F8F9 KLINGON DIGIT NINE + +U+F8FD KLINGON COMMA +U+F8FE KLINGON FULL STOP +U+F8FF KLINGON SYMBOL FOR EMPIRE +====== ======================================================= + +Other Fictional and Artificial Scripts +-------------------------------------- + +Since the assignment of the Klingon Linux Unicode block, a registry of +fictional and artificial scripts has been established by John Cowan + and Michael Everson . +The ConScript Unicode Registry is accessible at: + + http://www.evertype.com/standards/csur/ + +The ranges used fall at the low end of the End User Zone and can hence +not be normatively assigned, but it is recommended that people who +wish to encode fictional scripts use these codes, in the interest of +interoperability. For Klingon, CSUR has adopted the Linux encoding. +The CSUR people are driving adding Tengwar and Cirth into Unicode +Plane 1; the addition of Klingon to Unicode Plane 1 has been rejected +and so the above encoding remains official. diff --git a/Documentation/admin-guide/vga-softcursor.rst b/Documentation/admin-guide/vga-softcursor.rst new file mode 100644 index 000000000000..9eac6744b3a1 --- /dev/null +++ b/Documentation/admin-guide/vga-softcursor.rst @@ -0,0 +1,66 @@ +Software cursor for VGA +======================= + +by Pavel Machek +and Martin Mares + +Linux now has some ability to manipulate cursor appearance. Normally, you +can set the size of hardware cursor (and also work around some ugly bugs in +those miserable Trident cards [#f1]_. You can now play a few new tricks: +you can make your cursor look + +like a non-blinking red block, make it inverse background of the character it's +over or to highlight that character and still choose whether the original +hardware cursor should remain visible or not. There may be other things I have +never thought of. + +The cursor appearance is controlled by a ``[?1;2;3c`` escape sequence +where 1, 2 and 3 are parameters described below. If you omit any of them, +they will default to zeroes. + +first Parameter + specifies cursor size:: + + 0=default + 1=invisible + 2=underline, + ... + 8=full block + + 16 if you want the software cursor to be applied + + 32 if you want to always change the background color + + 64 if you dislike having the background the same as the + foreground. + + Highlights are ignored for the last two flags. + +second parameter + selects character attribute bits you want to change + (by simply XORing them with the value of this parameter). On standard + VGA, the high four bits specify background and the low four the + foreground. In both groups, low three bits set color (as in normal + color codes used by the console) and the most significant one turns + on highlight (or sometimes blinking -- it depends on the configuration + of your VGA). + +third parameter + consists of character attribute bits you want to set. + + Bit setting takes place before bit toggling, so you can simply clear a + bit by including it in both the set mask and the toggle mask. + +.. [#f1] see ``#define TRIDENT_GLITCH`` in ``drivers/video/vgacon.c``. + +Examples: +========= + +To get normal blinking underline, use:: + + echo -e '\033[?2c' + +To get blinking block, use:: + + echo -e '\033[?6c' + +To get red non-blinking block, use:: + + echo -e '\033[?17;0;64c' diff --git a/Documentation/bad_memory.txt b/Documentation/bad_memory.txt deleted file mode 100644 index 5cac93e27a97..000000000000 --- a/Documentation/bad_memory.txt +++ /dev/null @@ -1,51 +0,0 @@ -How to deal with bad memory e.g. reported by memtest86+ ? -========================================================= - -March 2008 -Jan-Simon Moeller, dl9pf@gmx.de - - - -There are three possibilities I know of: - -1) Reinsert/swap the memory modules - -2) Buy new modules (best!) or try to exchange the memory - if you have spare-parts - -3) Use BadRAM or memmap - -This Howto is about number 3) . - - -BadRAM -###### - -BadRAM is the actively developed and available as kernel-patch -here: http://rick.vanrein.org/linux/badram/ - -For more details see the BadRAM documentation. - -memmap -###### - -memmap is already in the kernel and usable as kernel-parameter at -boot-time. Its syntax is slightly strange and you may need to -calculate the values by yourself! - -Syntax to exclude a memory area (see kernel-parameters.txt for details):: - - memmap=$
- -Example: memtest86+ reported here errors at address 0x18691458, 0x18698424 and -some others. All had 0x1869xxxx in common, so I chose a pattern of -0x18690000,0xffff0000. - -With the numbers of the example above:: - - memmap=64K$0x18690000 - -or:: - - memmap=0x10000$0x18690000 - diff --git a/Documentation/basic_profiling.txt b/Documentation/basic_profiling.txt deleted file mode 100644 index 15a49dbd0189..000000000000 --- a/Documentation/basic_profiling.txt +++ /dev/null @@ -1,69 +0,0 @@ -Basic kernel profiling -====================== - - -These instructions are deliberately very basic. If you want something clever, -go read the real docs ;-) - -Please don't add more stuff, but feel free to -correct my mistakes ;-) (mbligh@aracnet.com) - -Thanks to John Levon, Dave Hansen, et al. for help writing this. - -```` is the thing you're trying to measure. -Make sure you have the correct ``System.map`` / ``vmlinux`` referenced! - -It is probably easiest to use ``make install`` for linux and hack -``/sbin/installkernel`` to copy ``vmlinux`` to ``/boot``, in addition to -``vmlinuz``, ``config``, ``System.map``, which are usually installed by default. - -Readprofile ------------ - -A recent ``readprofile`` command is needed for 2.6, such as found in util-linux -2.12a, which can be downloaded from: - - http://www.kernel.org/pub/linux/utils/util-linux/ - -Most distributions will ship it already. - -Add ``profile=2`` to the kernel command line. - -Some ``readprofile`` commands:: - - clear readprofile -r - - dump output readprofile -m /boot/System.map > captured_profile - -Oprofile --------- - -Get the source (see Changes for required version) from -http://oprofile.sourceforge.net/ and add ``idle=poll`` to the kernel command -line. - -Configure with ``CONFIG_PROFILING=y`` and ``CONFIG_OPROFILE=y`` & reboot on new kernel:: - - ./configure --with-kernel-support - make install - -For superior results, be sure to enable the local APIC. If opreport sees -a 0Hz CPU, APIC was not on. Be aware that idle=poll may mean a performance -penalty. - -One time setup:: - - opcontrol --setup --vmlinux=/boot/vmlinux - -Some ``opcontrol`` commands:: - - clear opcontrol --reset - start opcontrol --start - - stop opcontrol --stop - dump output opreport > output_file - -To only report on the kernel, run ``opreport -l /boot/vmlinux > output_file`` - -A reset is needed to clear old statistics, which survive a reboot. - diff --git a/Documentation/binfmt_misc.txt b/Documentation/binfmt_misc.txt deleted file mode 100644 index 9c5ff8f260bf..000000000000 --- a/Documentation/binfmt_misc.txt +++ /dev/null @@ -1,151 +0,0 @@ -Kernel Support for miscellaneous (your favourite) Binary Formats v1.1 -===================================================================== - -This Kernel feature allows you to invoke almost (for restrictions see below) -every program by simply typing its name in the shell. -This includes for example compiled Java(TM), Python or Emacs programs. - -To achieve this you must tell binfmt_misc which interpreter has to be invoked -with which binary. Binfmt_misc recognises the binary-type by matching some bytes -at the beginning of the file with a magic byte sequence (masking out specified -bits) you have supplied. Binfmt_misc can also recognise a filename extension -aka ``.com`` or ``.exe``. - -First you must mount binfmt_misc:: - - mount binfmt_misc -t binfmt_misc /proc/sys/fs/binfmt_misc - -To actually register a new binary type, you have to set up a string looking like -``:name:type:offset:magic:mask:interpreter:flags`` (where you can choose the -``:`` upon your needs) and echo it to ``/proc/sys/fs/binfmt_misc/register``. - -Here is what the fields mean: - -- ``name`` - is an identifier string. A new /proc file will be created with this - ``name below /proc/sys/fs/binfmt_misc``; cannot contain slashes ``/`` for - obvious reasons. -- ``type`` - is the type of recognition. Give ``M`` for magic and ``E`` for extension. -- ``offset`` - is the offset of the magic/mask in the file, counted in bytes. This - defaults to 0 if you omit it (i.e. you write ``:name:type::magic...``). - Ignored when using filename extension matching. -- ``magic`` - is the byte sequence binfmt_misc is matching for. The magic string - may contain hex-encoded characters like ``\x0a`` or ``\xA4``. Note that you - must escape any NUL bytes; parsing halts at the first one. In a shell - environment you might have to write ``\\x0a`` to prevent the shell from - eating your ``\``. - If you chose filename extension matching, this is the extension to be - recognised (without the ``.``, the ``\x0a`` specials are not allowed). - Extension matching is case sensitive, and slashes ``/`` are not allowed! -- ``mask`` - is an (optional, defaults to all 0xff) mask. You can mask out some - bits from matching by supplying a string like magic and as long as magic. - The mask is anded with the byte sequence of the file. Note that you must - escape any NUL bytes; parsing halts at the first one. Ignored when using - filename extension matching. -- ``interpreter`` - is the program that should be invoked with the binary as first - argument (specify the full path) -- ``flags`` - is an optional field that controls several aspects of the invocation - of the interpreter. It is a string of capital letters, each controls a - certain aspect. The following flags are supported: - - ``P`` - preserve-argv[0] - Legacy behavior of binfmt_misc is to overwrite - the original argv[0] with the full path to the binary. When this - flag is included, binfmt_misc will add an argument to the argument - vector for this purpose, thus preserving the original ``argv[0]``. - e.g. If your interp is set to ``/bin/foo`` and you run ``blah`` - (which is in ``/usr/local/bin``), then the kernel will execute - ``/bin/foo`` with ``argv[]`` set to ``["/bin/foo", "/usr/local/bin/blah", "blah"]``. The interp has to be aware of this so it can - execute ``/usr/local/bin/blah`` - with ``argv[]`` set to ``["blah"]``. - ``O`` - open-binary - Legacy behavior of binfmt_misc is to pass the full path - of the binary to the interpreter as an argument. When this flag is - included, binfmt_misc will open the file for reading and pass its - descriptor as an argument, instead of the full path, thus allowing - the interpreter to execute non-readable binaries. This feature - should be used with care - the interpreter has to be trusted not to - emit the contents of the non-readable binary. - ``C`` - credentials - Currently, the behavior of binfmt_misc is to calculate - the credentials and security token of the new process according to - the interpreter. When this flag is included, these attributes are - calculated according to the binary. It also implies the ``O`` flag. - This feature should be used with care as the interpreter - will run with root permissions when a setuid binary owned by root - is run with binfmt_misc. - ``F`` - fix binary - The usual behaviour of binfmt_misc is to spawn the - binary lazily when the misc format file is invoked. However, - this doesn``t work very well in the face of mount namespaces and - changeroots, so the ``F`` mode opens the binary as soon as the - emulation is installed and uses the opened image to spawn the - emulator, meaning it is always available once installed, - regardless of how the environment changes. - - -There are some restrictions: - - - the whole register string may not exceed 1920 characters - - the magic must reside in the first 128 bytes of the file, i.e. - offset+size(magic) has to be less than 128 - - the interpreter string may not exceed 127 characters - -To use binfmt_misc you have to mount it first. You can mount it with -``mount -t binfmt_misc none /proc/sys/fs/binfmt_misc`` command, or you can add -a line ``none /proc/sys/fs/binfmt_misc binfmt_misc defaults 0 0`` to your -``/etc/fstab`` so it auto mounts on boot. - -You may want to add the binary formats in one of your ``/etc/rc`` scripts during -boot-up. Read the manual of your init program to figure out how to do this -right. - -Think about the order of adding entries! Later added entries are matched first! - - -A few examples (assumed you are in ``/proc/sys/fs/binfmt_misc``): - -- enable support for em86 (like binfmt_em86, for Alpha AXP only):: - - echo ':i386:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x03:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register - echo ':i486:M::\x7fELF\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x06:\xff\xff\xff\xff\xff\xfe\xfe\xff\xff\xff\xff\xff\xff\xff\xff\xff\xfb\xff\xff:/bin/em86:' > register - -- enable support for packed DOS applications (pre-configured dosemu hdimages):: - - echo ':DEXE:M::\x0eDEX::/usr/bin/dosexec:' > register - -- enable support for Windows executables using wine:: - - echo ':DOSWin:M::MZ::/usr/local/bin/wine:' > register - -For java support see Documentation/java.txt - - -You can enable/disable binfmt_misc or one binary type by echoing 0 (to disable) -or 1 (to enable) to ``/proc/sys/fs/binfmt_misc/status`` or -``/proc/.../the_name``. -Catting the file tells you the current status of ``binfmt_misc/the_entry``. - -You can remove one entry or all entries by echoing -1 to ``/proc/.../the_name`` -or ``/proc/sys/fs/binfmt_misc/status``. - - -Hints ------ - -If you want to pass special arguments to your interpreter, you can -write a wrapper script for it. See Documentation/java.txt for an -example. - -Your interpreter should NOT look in the PATH for the filename; the kernel -passes it the full filename (or the file descriptor) to use. Using ``$PATH`` can -cause unexpected behaviour and can be a security hazard. - - -Richard Günther diff --git a/Documentation/braille-console.txt b/Documentation/braille-console.txt deleted file mode 100644 index fa3702dc04ab..000000000000 --- a/Documentation/braille-console.txt +++ /dev/null @@ -1,38 +0,0 @@ -Linux Braille Console -===================== - -To get early boot messages on a braille device (before userspace screen -readers can start), you first need to compile the support for the usual serial -console (see :ref:`Documentation/serial-console.txt `), and -for braille device -(in :menuselection:`Device Drivers --> Accessibility support --> Console on braille device`). - -Then you need to specify a ``console=brl``, option on the kernel command line, the -format is:: - - console=brl,serial_options... - -where ``serial_options...`` are the same as described in -:ref:`Documentation/serial-console.txt `. - -So for instance you can use ``console=brl,ttyS0`` if the braille device is connected to the first serial port, and ``console=brl,ttyS0,115200`` to -override the baud rate to 115200, etc. - -By default, the braille device will just show the last kernel message (console -mode). To review previous messages, press the Insert key to switch to the VT -review mode. In review mode, the arrow keys permit to browse in the VT content, -:kbd:`PAGE-UP`/:kbd:`PAGE-DOWN` keys go at the top/bottom of the screen, and -the :kbd:`HOME` key goes back -to the cursor, hence providing very basic screen reviewing facility. - -Sound feedback can be obtained by adding the ``braille_console.sound=1`` kernel -parameter. - -For simplicity, only one braille console can be enabled, other uses of -``console=brl,...`` will be discarded. Also note that it does not interfere with -the console selection mechanism described in -:ref:`Documentation/serial-console.txt `. - -For now, only the VisioBraille device is supported. - -Samuel Thibault diff --git a/Documentation/conf.py b/Documentation/conf.py index b08e0c9b73b7..d9bad21dd427 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -336,6 +336,8 @@ latex_elements = { # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ + ('user/index', 'linux-user.tex', 'Linux Kernel User Documentation', + 'The kernel development community', 'manual'), ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation', 'The kernel development community', 'manual'), ('process/index', 'development-process.tex', 'Linux Kernel Development Documentation', diff --git a/Documentation/devices.txt b/Documentation/devices.txt deleted file mode 100644 index 17b365331f23..000000000000 --- a/Documentation/devices.txt +++ /dev/null @@ -1,3351 +0,0 @@ - -Linux allocated devices (4.x+ version) -====================================== - -This list is the Linux Device List, the official registry of allocated -device numbers and ``/dev`` directory nodes for the Linux operating -system. - -The LaTeX version of this document is no longer maintained, nor is -the document that used to reside at lanana.org. This version in the -mainline Linux kernel is the master document. Updates shall be sent -as patches to the kernel maintainers (see the -:ref:`Documentation/SubmittingPatches ` document). -Specifically explore the sections titled "CHAR and MISC DRIVERS", and -"BLOCK LAYER" in the MAINTAINERS file to find the right maintainers -to involve for character and block devices. - -This document is included by reference into the Filesystem Hierarchy -Standard (FHS). The FHS is available from http://www.pathname.com/fhs/. - -Allocations marked (68k/Amiga) apply to Linux/68k on the Amiga -platform only. Allocations marked (68k/Atari) apply to Linux/68k on -the Atari platform only. - -This document is in the public domain. The authors requests, however, -that semantically altered versions are not distributed without -permission of the authors, assuming the authors can be contacted without -an unreasonable effort. - - -.. attention:: - - DEVICE DRIVERS AUTHORS PLEASE READ THIS - - Linux now has extensive support for dynamic allocation of device numbering - and can use ``sysfs`` and ``udev`` (``systemd``) to handle the naming needs. - There are still some exceptions in the serial and boot device area. Before - asking for a device number make sure you actually need one. - - To have a major number allocated, or a minor number in situations - where that applies (e.g. busmice), please submit a patch and send to - the authors as indicated above. - - Keep the description of the device *in the same format - as this list*. The reason for this is that it is the only way we have - found to ensure we have all the requisite information to publish your - device and avoid conflicts. - - Finally, sometimes we have to play "namespace police." Please don't be - offended. We often get submissions for ``/dev`` names that would be bound - to cause conflicts down the road. We are trying to avoid getting in a - situation where we would have to suffer an incompatible forward - change. Therefore, please consult with us **before** you make your - device names and numbers in any way public, at least to the point - where it would be at all difficult to get them changed. - - Your cooperation is appreciated. - -:: - - 0 Unnamed devices (e.g. non-device mounts) - 0 = reserved as null device number - See block major 144, 145, 146 for expansion areas. - - 1 char Memory devices - 1 = /dev/mem Physical memory access - 2 = /dev/kmem Kernel virtual memory access - 3 = /dev/null Null device - 4 = /dev/port I/O port access - 5 = /dev/zero Null byte source - 6 = /dev/core OBSOLETE - replaced by /proc/kcore - 7 = /dev/full Returns ENOSPC on write - 8 = /dev/random Nondeterministic random number gen. - 9 = /dev/urandom Faster, less secure random number gen. - 10 = /dev/aio Asynchronous I/O notification interface - 11 = /dev/kmsg Writes to this come out as printk's, reads - export the buffered printk records. - 12 = /dev/oldmem OBSOLETE - replaced by /proc/vmcore - - 1 block RAM disk - 0 = /dev/ram0 First RAM disk - 1 = /dev/ram1 Second RAM disk - ... - 250 = /dev/initrd Initial RAM disk - - Older kernels had /dev/ramdisk (1, 1) here. - /dev/initrd refers to a RAM disk which was preloaded - by the boot loader; newer kernels use /dev/ram0 for - the initrd. - - 2 char Pseudo-TTY masters - 0 = /dev/ptyp0 First PTY master - 1 = /dev/ptyp1 Second PTY master - ... - 255 = /dev/ptyef 256th PTY master - - Pseudo-tty's are named as follows: - * Masters are "pty", slaves are "tty"; - * the fourth letter is one of pqrstuvwxyzabcde indicating - the 1st through 16th series of 16 pseudo-ttys each, and - * the fifth letter is one of 0123456789abcdef indicating - the position within the series. - - These are the old-style (BSD) PTY devices; Unix98 - devices are on major 128 and above and use the PTY - master multiplex (/dev/ptmx) to acquire a PTY on - demand. - - 2 block Floppy disks - 0 = /dev/fd0 Controller 0, drive 0, autodetect - 1 = /dev/fd1 Controller 0, drive 1, autodetect - 2 = /dev/fd2 Controller 0, drive 2, autodetect - 3 = /dev/fd3 Controller 0, drive 3, autodetect - 128 = /dev/fd4 Controller 1, drive 0, autodetect - 129 = /dev/fd5 Controller 1, drive 1, autodetect - 130 = /dev/fd6 Controller 1, drive 2, autodetect - 131 = /dev/fd7 Controller 1, drive 3, autodetect - - To specify format, add to the autodetect device number: - 0 = /dev/fd? Autodetect format - 4 = /dev/fd?d360 5.25" 360K in a 360K drive(1) - 20 = /dev/fd?h360 5.25" 360K in a 1200K drive(1) - 48 = /dev/fd?h410 5.25" 410K in a 1200K drive - 64 = /dev/fd?h420 5.25" 420K in a 1200K drive - 24 = /dev/fd?h720 5.25" 720K in a 1200K drive - 80 = /dev/fd?h880 5.25" 880K in a 1200K drive(1) - 8 = /dev/fd?h1200 5.25" 1200K in a 1200K drive(1) - 40 = /dev/fd?h1440 5.25" 1440K in a 1200K drive(1) - 56 = /dev/fd?h1476 5.25" 1476K in a 1200K drive - 72 = /dev/fd?h1494 5.25" 1494K in a 1200K drive - 92 = /dev/fd?h1600 5.25" 1600K in a 1200K drive(1) - - 12 = /dev/fd?u360 3.5" 360K Double Density(2) - 16 = /dev/fd?u720 3.5" 720K Double Density(1) - 120 = /dev/fd?u800 3.5" 800K Double Density(2) - 52 = /dev/fd?u820 3.5" 820K Double Density - 68 = /dev/fd?u830 3.5" 830K Double Density - 84 = /dev/fd?u1040 3.5" 1040K Double Density(1) - 88 = /dev/fd?u1120 3.5" 1120K Double Density(1) - 28 = /dev/fd?u1440 3.5" 1440K High Density(1) - 124 = /dev/fd?u1600 3.5" 1600K High Density(1) - 44 = /dev/fd?u1680 3.5" 1680K High Density(3) - 60 = /dev/fd?u1722 3.5" 1722K High Density - 76 = /dev/fd?u1743 3.5" 1743K High Density - 96 = /dev/fd?u1760 3.5" 1760K High Density - 116 = /dev/fd?u1840 3.5" 1840K High Density(3) - 100 = /dev/fd?u1920 3.5" 1920K High Density(1) - 32 = /dev/fd?u2880 3.5" 2880K Extra Density(1) - 104 = /dev/fd?u3200 3.5" 3200K Extra Density - 108 = /dev/fd?u3520 3.5" 3520K Extra Density - 112 = /dev/fd?u3840 3.5" 3840K Extra Density(1) - - 36 = /dev/fd?CompaQ Compaq 2880K drive; obsolete? - - (1) Autodetectable format - (2) Autodetectable format in a Double Density (720K) drive only - (3) Autodetectable format in a High Density (1440K) drive only - - NOTE: The letter in the device name (d, q, h or u) - signifies the type of drive: 5.25" Double Density (d), - 5.25" Quad Density (q), 5.25" High Density (h) or 3.5" - (any model, u). The use of the capital letters D, H - and E for the 3.5" models have been deprecated, since - the drive type is insignificant for these devices. - - 3 char Pseudo-TTY slaves - 0 = /dev/ttyp0 First PTY slave - 1 = /dev/ttyp1 Second PTY slave - ... - 255 = /dev/ttyef 256th PTY slave - - These are the old-style (BSD) PTY devices; Unix98 - devices are on major 136 and above. - - 3 block First MFM, RLL and IDE hard disk/CD-ROM interface - 0 = /dev/hda Master: whole disk (or CD-ROM) - 64 = /dev/hdb Slave: whole disk (or CD-ROM) - - For partitions, add to the whole disk device number: - 0 = /dev/hd? Whole disk - 1 = /dev/hd?1 First partition - 2 = /dev/hd?2 Second partition - ... - 63 = /dev/hd?63 63rd partition - - For Linux/i386, partitions 1-4 are the primary - partitions, and 5 and above are logical partitions. - Other versions of Linux use partitioning schemes - appropriate to their respective architectures. - - 4 char TTY devices - 0 = /dev/tty0 Current virtual console - - 1 = /dev/tty1 First virtual console - ... - 63 = /dev/tty63 63rd virtual console - 64 = /dev/ttyS0 First UART serial port - ... - 255 = /dev/ttyS191 192nd UART serial port - - UART serial ports refer to 8250/16450/16550 series devices. - - Older versions of the Linux kernel used this major - number for BSD PTY devices. As of Linux 2.1.115, this - is no longer supported. Use major numbers 2 and 3. - - 4 block Aliases for dynamically allocated major devices to be used - when its not possible to create the real device nodes - because the root filesystem is mounted read-only. - - 0 = /dev/root - - 5 char Alternate TTY devices - 0 = /dev/tty Current TTY device - 1 = /dev/console System console - 2 = /dev/ptmx PTY master multiplex - 3 = /dev/ttyprintk User messages via printk TTY device - 64 = /dev/cua0 Callout device for ttyS0 - ... - 255 = /dev/cua191 Callout device for ttyS191 - - (5,1) is /dev/console starting with Linux 2.1.71. See - the section on terminal devices for more information - on /dev/console. - - 6 char Parallel printer devices - 0 = /dev/lp0 Parallel printer on parport0 - 1 = /dev/lp1 Parallel printer on parport1 - ... - - Current Linux kernels no longer have a fixed mapping - between parallel ports and I/O addresses. Instead, - they are redirected through the parport multiplex layer. - - 7 char Virtual console capture devices - 0 = /dev/vcs Current vc text contents - 1 = /dev/vcs1 tty1 text contents - ... - 63 = /dev/vcs63 tty63 text contents - 128 = /dev/vcsa Current vc text/attribute contents - 129 = /dev/vcsa1 tty1 text/attribute contents - ... - 191 = /dev/vcsa63 tty63 text/attribute contents - - NOTE: These devices permit both read and write access. - - 7 block Loopback devices - 0 = /dev/loop0 First loop device - 1 = /dev/loop1 Second loop device - ... - - The loop devices are used to mount filesystems not - associated with block devices. The binding to the - loop devices is handled by mount(8) or losetup(8). - - 8 block SCSI disk devices (0-15) - 0 = /dev/sda First SCSI disk whole disk - 16 = /dev/sdb Second SCSI disk whole disk - 32 = /dev/sdc Third SCSI disk whole disk - ... - 240 = /dev/sdp Sixteenth SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 9 char SCSI tape devices - 0 = /dev/st0 First SCSI tape, mode 0 - 1 = /dev/st1 Second SCSI tape, mode 0 - ... - 32 = /dev/st0l First SCSI tape, mode 1 - 33 = /dev/st1l Second SCSI tape, mode 1 - ... - 64 = /dev/st0m First SCSI tape, mode 2 - 65 = /dev/st1m Second SCSI tape, mode 2 - ... - 96 = /dev/st0a First SCSI tape, mode 3 - 97 = /dev/st1a Second SCSI tape, mode 3 - ... - 128 = /dev/nst0 First SCSI tape, mode 0, no rewind - 129 = /dev/nst1 Second SCSI tape, mode 0, no rewind - ... - 160 = /dev/nst0l First SCSI tape, mode 1, no rewind - 161 = /dev/nst1l Second SCSI tape, mode 1, no rewind - ... - 192 = /dev/nst0m First SCSI tape, mode 2, no rewind - 193 = /dev/nst1m Second SCSI tape, mode 2, no rewind - ... - 224 = /dev/nst0a First SCSI tape, mode 3, no rewind - 225 = /dev/nst1a Second SCSI tape, mode 3, no rewind - ... - - "No rewind" refers to the omission of the default - automatic rewind on device close. The MTREW or MTOFFL - ioctl()'s can be used to rewind the tape regardless of - the device used to access it. - - 9 block Metadisk (RAID) devices - 0 = /dev/md0 First metadisk group - 1 = /dev/md1 Second metadisk group - ... - - The metadisk driver is used to span a - filesystem across multiple physical disks. - - 10 char Non-serial mice, misc features - 0 = /dev/logibm Logitech bus mouse - 1 = /dev/psaux PS/2-style mouse port - 2 = /dev/inportbm Microsoft Inport bus mouse - 3 = /dev/atibm ATI XL bus mouse - 4 = /dev/jbm J-mouse - 4 = /dev/amigamouse Amiga mouse (68k/Amiga) - 5 = /dev/atarimouse Atari mouse - 6 = /dev/sunmouse Sun mouse - 7 = /dev/amigamouse1 Second Amiga mouse - 8 = /dev/smouse Simple serial mouse driver - 9 = /dev/pc110pad IBM PC-110 digitizer pad - 10 = /dev/adbmouse Apple Desktop Bus mouse - 11 = /dev/vrtpanel Vr41xx embedded touch panel - 13 = /dev/vpcmouse Connectix Virtual PC Mouse - 14 = /dev/touchscreen/ucb1x00 UCB 1x00 touchscreen - 15 = /dev/touchscreen/mk712 MK712 touchscreen - 128 = /dev/beep Fancy beep device - 129 = - 130 = /dev/watchdog Watchdog timer port - 131 = /dev/temperature Machine internal temperature - 132 = /dev/hwtrap Hardware fault trap - 133 = /dev/exttrp External device trap - 134 = /dev/apm_bios Advanced Power Management BIOS - 135 = /dev/rtc Real Time Clock - 137 = /dev/vhci Bluetooth virtual HCI driver - 139 = /dev/openprom SPARC OpenBoot PROM - 140 = /dev/relay8 Berkshire Products Octal relay card - 141 = /dev/relay16 Berkshire Products ISO-16 relay card - 142 = - 143 = /dev/pciconf PCI configuration space - 144 = /dev/nvram Non-volatile configuration RAM - 145 = /dev/hfmodem Soundcard shortwave modem control - 146 = /dev/graphics Linux/SGI graphics device - 147 = /dev/opengl Linux/SGI OpenGL pipe - 148 = /dev/gfx Linux/SGI graphics effects device - 149 = /dev/input/mouse Linux/SGI Irix emulation mouse - 150 = /dev/input/keyboard Linux/SGI Irix emulation keyboard - 151 = /dev/led Front panel LEDs - 152 = /dev/kpoll Kernel Poll Driver - 153 = /dev/mergemem Memory merge device - 154 = /dev/pmu Macintosh PowerBook power manager - 155 = /dev/isictl MultiTech ISICom serial control - 156 = /dev/lcd Front panel LCD display - 157 = /dev/ac Applicom Intl Profibus card - 158 = /dev/nwbutton Netwinder external button - 159 = /dev/nwdebug Netwinder debug interface - 160 = /dev/nwflash Netwinder flash memory - 161 = /dev/userdma User-space DMA access - 162 = /dev/smbus System Management Bus - 163 = /dev/lik Logitech Internet Keyboard - 164 = /dev/ipmo Intel Intelligent Platform Management - 165 = /dev/vmmon VMware virtual machine monitor - 166 = /dev/i2o/ctl I2O configuration manager - 167 = /dev/specialix_sxctl Specialix serial control - 168 = /dev/tcldrv Technology Concepts serial control - 169 = /dev/specialix_rioctl Specialix RIO serial control - 170 = /dev/thinkpad/thinkpad IBM Thinkpad devices - 171 = /dev/srripc QNX4 API IPC manager - 172 = /dev/usemaclone Semaphore clone device - 173 = /dev/ipmikcs Intelligent Platform Management - 174 = /dev/uctrl SPARCbook 3 microcontroller - 175 = /dev/agpgart AGP Graphics Address Remapping Table - 176 = /dev/gtrsc Gorgy Timing radio clock - 177 = /dev/cbm Serial CBM bus - 178 = /dev/jsflash JavaStation OS flash SIMM - 179 = /dev/xsvc High-speed shared-mem/semaphore service - 180 = /dev/vrbuttons Vr41xx button input device - 181 = /dev/toshiba Toshiba laptop SMM support - 182 = /dev/perfctr Performance-monitoring counters - 183 = /dev/hwrng Generic random number generator - 184 = /dev/cpu/microcode CPU microcode update interface - 186 = /dev/atomicps Atomic shapshot of process state data - 187 = /dev/irnet IrNET device - 188 = /dev/smbusbios SMBus BIOS - 189 = /dev/ussp_ctl User space serial port control - 190 = /dev/crash Mission Critical Linux crash dump facility - 191 = /dev/pcl181 - 192 = /dev/nas_xbus NAS xbus LCD/buttons access - 193 = /dev/d7s SPARC 7-segment display - 194 = /dev/zkshim Zero-Knowledge network shim control - 195 = /dev/elographics/e2201 Elographics touchscreen E271-2201 - 196 = /dev/vfio/vfio VFIO userspace driver interface - 197 = /dev/pxa3xx-gcu PXA3xx graphics controller unit driver - 198 = /dev/sexec Signed executable interface - 199 = /dev/scanners/cuecat :CueCat barcode scanner - 200 = /dev/net/tun TAP/TUN network device - 201 = /dev/button/gulpb Transmeta GULP-B buttons - 202 = /dev/emd/ctl Enhanced Metadisk RAID (EMD) control - 203 = /dev/cuse Cuse (character device in user-space) - 204 = /dev/video/em8300 EM8300 DVD decoder control - 205 = /dev/video/em8300_mv EM8300 DVD decoder video - 206 = /dev/video/em8300_ma EM8300 DVD decoder audio - 207 = /dev/video/em8300_sp EM8300 DVD decoder subpicture - 208 = /dev/compaq/cpqphpc Compaq PCI Hot Plug Controller - 209 = /dev/compaq/cpqrid Compaq Remote Insight Driver - 210 = /dev/impi/bt IMPI coprocessor block transfer - 211 = /dev/impi/smic IMPI coprocessor stream interface - 212 = /dev/watchdogs/0 First watchdog device - 213 = /dev/watchdogs/1 Second watchdog device - 214 = /dev/watchdogs/2 Third watchdog device - 215 = /dev/watchdogs/3 Fourth watchdog device - 216 = /dev/fujitsu/apanel Fujitsu/Siemens application panel - 217 = /dev/ni/natmotn National Instruments Motion - 218 = /dev/kchuid Inter-process chuid control - 219 = /dev/modems/mwave MWave modem firmware upload - 220 = /dev/mptctl Message passing technology (MPT) control - 221 = /dev/mvista/hssdsi Montavista PICMG hot swap system driver - 222 = /dev/mvista/hasi Montavista PICMG high availability - 223 = /dev/input/uinput User level driver support for input - 224 = /dev/tpm TCPA TPM driver - 225 = /dev/pps Pulse Per Second driver - 226 = /dev/systrace Systrace device - 227 = /dev/mcelog X86_64 Machine Check Exception driver - 228 = /dev/hpet HPET driver - 229 = /dev/fuse Fuse (virtual filesystem in user-space) - 230 = /dev/midishare MidiShare driver - 231 = /dev/snapshot System memory snapshot device - 232 = /dev/kvm Kernel-based virtual machine (hardware virtualization extensions) - 233 = /dev/kmview View-OS A process with a view - 234 = /dev/btrfs-control Btrfs control device - 235 = /dev/autofs Autofs control device - 236 = /dev/mapper/control Device-Mapper control device - 237 = /dev/loop-control Loopback control device - 238 = /dev/vhost-net Host kernel accelerator for virtio net - 239 = /dev/uhid User-space I/O driver support for HID subsystem - - 240-254 Reserved for local use - 255 Reserved for MISC_DYNAMIC_MINOR - - 11 char Raw keyboard device (Linux/SPARC only) - 0 = /dev/kbd Raw keyboard device - - 11 char Serial Mux device (Linux/PA-RISC only) - 0 = /dev/ttyB0 First mux port - 1 = /dev/ttyB1 Second mux port - ... - - 11 block SCSI CD-ROM devices - 0 = /dev/scd0 First SCSI CD-ROM - 1 = /dev/scd1 Second SCSI CD-ROM - ... - - The prefix /dev/sr (instead of /dev/scd) has been deprecated. - - 12 char QIC-02 tape - 2 = /dev/ntpqic11 QIC-11, no rewind-on-close - 3 = /dev/tpqic11 QIC-11, rewind-on-close - 4 = /dev/ntpqic24 QIC-24, no rewind-on-close - 5 = /dev/tpqic24 QIC-24, rewind-on-close - 6 = /dev/ntpqic120 QIC-120, no rewind-on-close - 7 = /dev/tpqic120 QIC-120, rewind-on-close - 8 = /dev/ntpqic150 QIC-150, no rewind-on-close - 9 = /dev/tpqic150 QIC-150, rewind-on-close - - The device names specified are proposed -- if there - are "standard" names for these devices, please let me know. - - 12 block - - 13 char Input core - 0 = /dev/input/js0 First joystick - 1 = /dev/input/js1 Second joystick - ... - 32 = /dev/input/mouse0 First mouse - 33 = /dev/input/mouse1 Second mouse - ... - 63 = /dev/input/mice Unified mouse - 64 = /dev/input/event0 First event queue - 65 = /dev/input/event1 Second event queue - ... - - Each device type has 5 bits (32 minors). - - 13 block Previously used for the XT disk (/dev/xdN) - Deleted in kernel v3.9. - - 14 char Open Sound System (OSS) - 0 = /dev/mixer Mixer control - 1 = /dev/sequencer Audio sequencer - 2 = /dev/midi00 First MIDI port - 3 = /dev/dsp Digital audio - 4 = /dev/audio Sun-compatible digital audio - 6 = - 7 = /dev/audioctl SPARC audio control device - 8 = /dev/sequencer2 Sequencer -- alternate device - 16 = /dev/mixer1 Second soundcard mixer control - 17 = /dev/patmgr0 Sequencer patch manager - 18 = /dev/midi01 Second MIDI port - 19 = /dev/dsp1 Second soundcard digital audio - 20 = /dev/audio1 Second soundcard Sun digital audio - 33 = /dev/patmgr1 Sequencer patch manager - 34 = /dev/midi02 Third MIDI port - 50 = /dev/midi03 Fourth MIDI port - - 14 block - - 15 char Joystick - 0 = /dev/js0 First analog joystick - 1 = /dev/js1 Second analog joystick - ... - 128 = /dev/djs0 First digital joystick - 129 = /dev/djs1 Second digital joystick - ... - 15 block Sony CDU-31A/CDU-33A CD-ROM - 0 = /dev/sonycd Sony CDU-31a CD-ROM - - 16 char Non-SCSI scanners - 0 = /dev/gs4500 Genius 4500 handheld scanner - - 16 block GoldStar CD-ROM - 0 = /dev/gscd GoldStar CD-ROM - - 17 char OBSOLETE (was Chase serial card) - 0 = /dev/ttyH0 First Chase port - 1 = /dev/ttyH1 Second Chase port - ... - 17 block Optics Storage CD-ROM - 0 = /dev/optcd Optics Storage CD-ROM - - 18 char OBSOLETE (was Chase serial card - alternate devices) - 0 = /dev/cuh0 Callout device for ttyH0 - 1 = /dev/cuh1 Callout device for ttyH1 - ... - 18 block Sanyo CD-ROM - 0 = /dev/sjcd Sanyo CD-ROM - - 19 char Cyclades serial card - 0 = /dev/ttyC0 First Cyclades port - ... - 31 = /dev/ttyC31 32nd Cyclades port - - 19 block "Double" compressed disk - 0 = /dev/double0 First compressed disk - ... - 7 = /dev/double7 Eighth compressed disk - 128 = /dev/cdouble0 Mirror of first compressed disk - ... - 135 = /dev/cdouble7 Mirror of eighth compressed disk - - See the Double documentation for the meaning of the - mirror devices. - - 20 char Cyclades serial card - alternate devices - 0 = /dev/cub0 Callout device for ttyC0 - ... - 31 = /dev/cub31 Callout device for ttyC31 - - 20 block Hitachi CD-ROM (under development) - 0 = /dev/hitcd Hitachi CD-ROM - - 21 char Generic SCSI access - 0 = /dev/sg0 First generic SCSI device - 1 = /dev/sg1 Second generic SCSI device - ... - - Most distributions name these /dev/sga, /dev/sgb...; - this sets an unnecessary limit of 26 SCSI devices in - the system and is counter to standard Linux - device-naming practice. - - 21 block Acorn MFM hard drive interface - 0 = /dev/mfma First MFM drive whole disk - 64 = /dev/mfmb Second MFM drive whole disk - - This device is used on the ARM-based Acorn RiscPC. - Partitions are handled the same way as for IDE disks - (see major number 3). - - 22 char Digiboard serial card - 0 = /dev/ttyD0 First Digiboard port - 1 = /dev/ttyD1 Second Digiboard port - ... - 22 block Second IDE hard disk/CD-ROM interface - 0 = /dev/hdc Master: whole disk (or CD-ROM) - 64 = /dev/hdd Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 23 char Digiboard serial card - alternate devices - 0 = /dev/cud0 Callout device for ttyD0 - 1 = /dev/cud1 Callout device for ttyD1 - ... - 23 block Mitsumi proprietary CD-ROM - 0 = /dev/mcd Mitsumi CD-ROM - - 24 char Stallion serial card - 0 = /dev/ttyE0 Stallion port 0 card 0 - 1 = /dev/ttyE1 Stallion port 1 card 0 - ... - 64 = /dev/ttyE64 Stallion port 0 card 1 - 65 = /dev/ttyE65 Stallion port 1 card 1 - ... - 128 = /dev/ttyE128 Stallion port 0 card 2 - 129 = /dev/ttyE129 Stallion port 1 card 2 - ... - 192 = /dev/ttyE192 Stallion port 0 card 3 - 193 = /dev/ttyE193 Stallion port 1 card 3 - ... - 24 block Sony CDU-535 CD-ROM - 0 = /dev/cdu535 Sony CDU-535 CD-ROM - - 25 char Stallion serial card - alternate devices - 0 = /dev/cue0 Callout device for ttyE0 - 1 = /dev/cue1 Callout device for ttyE1 - ... - 64 = /dev/cue64 Callout device for ttyE64 - 65 = /dev/cue65 Callout device for ttyE65 - ... - 128 = /dev/cue128 Callout device for ttyE128 - 129 = /dev/cue129 Callout device for ttyE129 - ... - 192 = /dev/cue192 Callout device for ttyE192 - 193 = /dev/cue193 Callout device for ttyE193 - ... - 25 block First Matsushita (Panasonic/SoundBlaster) CD-ROM - 0 = /dev/sbpcd0 Panasonic CD-ROM controller 0 unit 0 - 1 = /dev/sbpcd1 Panasonic CD-ROM controller 0 unit 1 - 2 = /dev/sbpcd2 Panasonic CD-ROM controller 0 unit 2 - 3 = /dev/sbpcd3 Panasonic CD-ROM controller 0 unit 3 - - 26 char - - 26 block Second Matsushita (Panasonic/SoundBlaster) CD-ROM - 0 = /dev/sbpcd4 Panasonic CD-ROM controller 1 unit 0 - 1 = /dev/sbpcd5 Panasonic CD-ROM controller 1 unit 1 - 2 = /dev/sbpcd6 Panasonic CD-ROM controller 1 unit 2 - 3 = /dev/sbpcd7 Panasonic CD-ROM controller 1 unit 3 - - 27 char QIC-117 tape - 0 = /dev/qft0 Unit 0, rewind-on-close - 1 = /dev/qft1 Unit 1, rewind-on-close - 2 = /dev/qft2 Unit 2, rewind-on-close - 3 = /dev/qft3 Unit 3, rewind-on-close - 4 = /dev/nqft0 Unit 0, no rewind-on-close - 5 = /dev/nqft1 Unit 1, no rewind-on-close - 6 = /dev/nqft2 Unit 2, no rewind-on-close - 7 = /dev/nqft3 Unit 3, no rewind-on-close - 16 = /dev/zqft0 Unit 0, rewind-on-close, compression - 17 = /dev/zqft1 Unit 1, rewind-on-close, compression - 18 = /dev/zqft2 Unit 2, rewind-on-close, compression - 19 = /dev/zqft3 Unit 3, rewind-on-close, compression - 20 = /dev/nzqft0 Unit 0, no rewind-on-close, compression - 21 = /dev/nzqft1 Unit 1, no rewind-on-close, compression - 22 = /dev/nzqft2 Unit 2, no rewind-on-close, compression - 23 = /dev/nzqft3 Unit 3, no rewind-on-close, compression - 32 = /dev/rawqft0 Unit 0, rewind-on-close, no file marks - 33 = /dev/rawqft1 Unit 1, rewind-on-close, no file marks - 34 = /dev/rawqft2 Unit 2, rewind-on-close, no file marks - 35 = /dev/rawqft3 Unit 3, rewind-on-close, no file marks - 36 = /dev/nrawqft0 Unit 0, no rewind-on-close, no file marks - 37 = /dev/nrawqft1 Unit 1, no rewind-on-close, no file marks - 38 = /dev/nrawqft2 Unit 2, no rewind-on-close, no file marks - 39 = /dev/nrawqft3 Unit 3, no rewind-on-close, no file marks - - 27 block Third Matsushita (Panasonic/SoundBlaster) CD-ROM - 0 = /dev/sbpcd8 Panasonic CD-ROM controller 2 unit 0 - 1 = /dev/sbpcd9 Panasonic CD-ROM controller 2 unit 1 - 2 = /dev/sbpcd10 Panasonic CD-ROM controller 2 unit 2 - 3 = /dev/sbpcd11 Panasonic CD-ROM controller 2 unit 3 - - 28 char Stallion serial card - card programming - 0 = /dev/staliomem0 First Stallion card I/O memory - 1 = /dev/staliomem1 Second Stallion card I/O memory - 2 = /dev/staliomem2 Third Stallion card I/O memory - 3 = /dev/staliomem3 Fourth Stallion card I/O memory - - 28 char Atari SLM ACSI laser printer (68k/Atari) - 0 = /dev/slm0 First SLM laser printer - 1 = /dev/slm1 Second SLM laser printer - ... - 28 block Fourth Matsushita (Panasonic/SoundBlaster) CD-ROM - 0 = /dev/sbpcd12 Panasonic CD-ROM controller 3 unit 0 - 1 = /dev/sbpcd13 Panasonic CD-ROM controller 3 unit 1 - 2 = /dev/sbpcd14 Panasonic CD-ROM controller 3 unit 2 - 3 = /dev/sbpcd15 Panasonic CD-ROM controller 3 unit 3 - - 28 block ACSI disk (68k/Atari) - 0 = /dev/ada First ACSI disk whole disk - 16 = /dev/adb Second ACSI disk whole disk - 32 = /dev/adc Third ACSI disk whole disk - ... - 240 = /dev/adp 16th ACSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15, like SCSI. - - 29 char Universal frame buffer - 0 = /dev/fb0 First frame buffer - 1 = /dev/fb1 Second frame buffer - ... - 31 = /dev/fb31 32nd frame buffer - - 29 block Aztech/Orchid/Okano/Wearnes CD-ROM - 0 = /dev/aztcd Aztech CD-ROM - - 30 char iBCS-2 compatibility devices - 0 = /dev/socksys Socket access - 1 = /dev/spx SVR3 local X interface - 32 = /dev/inet/ip Network access - 33 = /dev/inet/icmp - 34 = /dev/inet/ggp - 35 = /dev/inet/ipip - 36 = /dev/inet/tcp - 37 = /dev/inet/egp - 38 = /dev/inet/pup - 39 = /dev/inet/udp - 40 = /dev/inet/idp - 41 = /dev/inet/rawip - - Additionally, iBCS-2 requires the following links: - - /dev/ip -> /dev/inet/ip - /dev/icmp -> /dev/inet/icmp - /dev/ggp -> /dev/inet/ggp - /dev/ipip -> /dev/inet/ipip - /dev/tcp -> /dev/inet/tcp - /dev/egp -> /dev/inet/egp - /dev/pup -> /dev/inet/pup - /dev/udp -> /dev/inet/udp - /dev/idp -> /dev/inet/idp - /dev/rawip -> /dev/inet/rawip - /dev/inet/arp -> /dev/inet/udp - /dev/inet/rip -> /dev/inet/udp - /dev/nfsd -> /dev/socksys - /dev/X0R -> /dev/null (? apparently not required ?) - - 30 block Philips LMS CM-205 CD-ROM - 0 = /dev/cm205cd Philips LMS CM-205 CD-ROM - - /dev/lmscd is an older name for this device. This - driver does not work with the CM-205MS CD-ROM. - - 31 char MPU-401 MIDI - 0 = /dev/mpu401data MPU-401 data port - 1 = /dev/mpu401stat MPU-401 status port - - 31 block ROM/flash memory card - 0 = /dev/rom0 First ROM card (rw) - ... - 7 = /dev/rom7 Eighth ROM card (rw) - 8 = /dev/rrom0 First ROM card (ro) - ... - 15 = /dev/rrom7 Eighth ROM card (ro) - 16 = /dev/flash0 First flash memory card (rw) - ... - 23 = /dev/flash7 Eighth flash memory card (rw) - 24 = /dev/rflash0 First flash memory card (ro) - ... - 31 = /dev/rflash7 Eighth flash memory card (ro) - - The read-write (rw) devices support back-caching - written data in RAM, as well as writing to flash RAM - devices. The read-only devices (ro) support reading - only. - - 32 char Specialix serial card - 0 = /dev/ttyX0 First Specialix port - 1 = /dev/ttyX1 Second Specialix port - ... - 32 block Philips LMS CM-206 CD-ROM - 0 = /dev/cm206cd Philips LMS CM-206 CD-ROM - - 33 char Specialix serial card - alternate devices - 0 = /dev/cux0 Callout device for ttyX0 - 1 = /dev/cux1 Callout device for ttyX1 - ... - 33 block Third IDE hard disk/CD-ROM interface - 0 = /dev/hde Master: whole disk (or CD-ROM) - 64 = /dev/hdf Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 34 char Z8530 HDLC driver - 0 = /dev/scc0 First Z8530, first port - 1 = /dev/scc1 First Z8530, second port - 2 = /dev/scc2 Second Z8530, first port - 3 = /dev/scc3 Second Z8530, second port - ... - - In a previous version these devices were named - /dev/sc1 for /dev/scc0, /dev/sc2 for /dev/scc1, and so - on. - - 34 block Fourth IDE hard disk/CD-ROM interface - 0 = /dev/hdg Master: whole disk (or CD-ROM) - 64 = /dev/hdh Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 35 char tclmidi MIDI driver - 0 = /dev/midi0 First MIDI port, kernel timed - 1 = /dev/midi1 Second MIDI port, kernel timed - 2 = /dev/midi2 Third MIDI port, kernel timed - 3 = /dev/midi3 Fourth MIDI port, kernel timed - 64 = /dev/rmidi0 First MIDI port, untimed - 65 = /dev/rmidi1 Second MIDI port, untimed - 66 = /dev/rmidi2 Third MIDI port, untimed - 67 = /dev/rmidi3 Fourth MIDI port, untimed - 128 = /dev/smpte0 First MIDI port, SMPTE timed - 129 = /dev/smpte1 Second MIDI port, SMPTE timed - 130 = /dev/smpte2 Third MIDI port, SMPTE timed - 131 = /dev/smpte3 Fourth MIDI port, SMPTE timed - - 35 block Slow memory ramdisk - 0 = /dev/slram Slow memory ramdisk - - 36 char Netlink support - 0 = /dev/route Routing, device updates, kernel to user - 1 = /dev/skip enSKIP security cache control - 3 = /dev/fwmonitor Firewall packet copies - 16 = /dev/tap0 First Ethertap device - ... - 31 = /dev/tap15 16th Ethertap device - - 36 block OBSOLETE (was MCA ESDI hard disk) - - 37 char IDE tape - 0 = /dev/ht0 First IDE tape - 1 = /dev/ht1 Second IDE tape - ... - 128 = /dev/nht0 First IDE tape, no rewind-on-close - 129 = /dev/nht1 Second IDE tape, no rewind-on-close - ... - - Currently, only one IDE tape drive is supported. - - 37 block Zorro II ramdisk - 0 = /dev/z2ram Zorro II ramdisk - - 38 char Myricom PCI Myrinet board - 0 = /dev/mlanai0 First Myrinet board - 1 = /dev/mlanai1 Second Myrinet board - ... - - This device is used for status query, board control - and "user level packet I/O." This board is also - accessible as a standard networking "eth" device. - - 38 block OBSOLETE (was Linux/AP+) - - 39 char ML-16P experimental I/O board - 0 = /dev/ml16pa-a0 First card, first analog channel - 1 = /dev/ml16pa-a1 First card, second analog channel - ... - 15 = /dev/ml16pa-a15 First card, 16th analog channel - 16 = /dev/ml16pa-d First card, digital lines - 17 = /dev/ml16pa-c0 First card, first counter/timer - 18 = /dev/ml16pa-c1 First card, second counter/timer - 19 = /dev/ml16pa-c2 First card, third counter/timer - 32 = /dev/ml16pb-a0 Second card, first analog channel - 33 = /dev/ml16pb-a1 Second card, second analog channel - ... - 47 = /dev/ml16pb-a15 Second card, 16th analog channel - 48 = /dev/ml16pb-d Second card, digital lines - 49 = /dev/ml16pb-c0 Second card, first counter/timer - 50 = /dev/ml16pb-c1 Second card, second counter/timer - 51 = /dev/ml16pb-c2 Second card, third counter/timer - ... - 39 block - - 40 char - - 40 block - - 41 char Yet Another Micro Monitor - 0 = /dev/yamm Yet Another Micro Monitor - - 41 block - - 42 char Demo/sample use - - 42 block Demo/sample use - - This number is intended for use in sample code, as - well as a general "example" device number. It - should never be used for a device driver that is being - distributed; either obtain an official number or use - the local/experimental range. The sudden addition or - removal of a driver with this number should not cause - ill effects to the system (bugs excepted.) - - IN PARTICULAR, ANY DISTRIBUTION WHICH CONTAINS A - DEVICE DRIVER USING MAJOR NUMBER 42 IS NONCOMPLIANT. - - 43 char isdn4linux virtual modem - 0 = /dev/ttyI0 First virtual modem - ... - 63 = /dev/ttyI63 64th virtual modem - - 43 block Network block devices - 0 = /dev/nb0 First network block device - 1 = /dev/nb1 Second network block device - ... - - Network Block Device is somehow similar to loopback - devices: If you read from it, it sends packet across - network asking server for data. If you write to it, it - sends packet telling server to write. It could be used - to mounting filesystems over the net, swapping over - the net, implementing block device in userland etc. - - 44 char isdn4linux virtual modem - alternate devices - 0 = /dev/cui0 Callout device for ttyI0 - ... - 63 = /dev/cui63 Callout device for ttyI63 - - 44 block Flash Translation Layer (FTL) filesystems - 0 = /dev/ftla FTL on first Memory Technology Device - 16 = /dev/ftlb FTL on second Memory Technology Device - 32 = /dev/ftlc FTL on third Memory Technology Device - ... - 240 = /dev/ftlp FTL on 16th Memory Technology Device - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the partition - limit is 15 rather than 63 per disk (same as SCSI.) - - 45 char isdn4linux ISDN BRI driver - 0 = /dev/isdn0 First virtual B channel raw data - ... - 63 = /dev/isdn63 64th virtual B channel raw data - 64 = /dev/isdnctrl0 First channel control/debug - ... - 127 = /dev/isdnctrl63 64th channel control/debug - - 128 = /dev/ippp0 First SyncPPP device - ... - 191 = /dev/ippp63 64th SyncPPP device - - 255 = /dev/isdninfo ISDN monitor interface - - 45 block Parallel port IDE disk devices - 0 = /dev/pda First parallel port IDE disk - 16 = /dev/pdb Second parallel port IDE disk - 32 = /dev/pdc Third parallel port IDE disk - 48 = /dev/pdd Fourth parallel port IDE disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the partition - limit is 15 rather than 63 per disk. - - 46 char Comtrol Rocketport serial card - 0 = /dev/ttyR0 First Rocketport port - 1 = /dev/ttyR1 Second Rocketport port - ... - 46 block Parallel port ATAPI CD-ROM devices - 0 = /dev/pcd0 First parallel port ATAPI CD-ROM - 1 = /dev/pcd1 Second parallel port ATAPI CD-ROM - 2 = /dev/pcd2 Third parallel port ATAPI CD-ROM - 3 = /dev/pcd3 Fourth parallel port ATAPI CD-ROM - - 47 char Comtrol Rocketport serial card - alternate devices - 0 = /dev/cur0 Callout device for ttyR0 - 1 = /dev/cur1 Callout device for ttyR1 - ... - 47 block Parallel port ATAPI disk devices - 0 = /dev/pf0 First parallel port ATAPI disk - 1 = /dev/pf1 Second parallel port ATAPI disk - 2 = /dev/pf2 Third parallel port ATAPI disk - 3 = /dev/pf3 Fourth parallel port ATAPI disk - - This driver is intended for floppy disks and similar - devices and hence does not support partitioning. - - 48 char SDL RISCom serial card - 0 = /dev/ttyL0 First RISCom port - 1 = /dev/ttyL1 Second RISCom port - ... - 48 block Mylex DAC960 PCI RAID controller; first controller - 0 = /dev/rd/c0d0 First disk, whole disk - 8 = /dev/rd/c0d1 Second disk, whole disk - ... - 248 = /dev/rd/c0d31 32nd disk, whole disk - - For partitions add: - 0 = /dev/rd/c?d? Whole disk - 1 = /dev/rd/c?d?p1 First partition - ... - 7 = /dev/rd/c?d?p7 Seventh partition - - 49 char SDL RISCom serial card - alternate devices - 0 = /dev/cul0 Callout device for ttyL0 - 1 = /dev/cul1 Callout device for ttyL1 - ... - 49 block Mylex DAC960 PCI RAID controller; second controller - 0 = /dev/rd/c1d0 First disk, whole disk - 8 = /dev/rd/c1d1 Second disk, whole disk - ... - 248 = /dev/rd/c1d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 50 char Reserved for GLINT - - 50 block Mylex DAC960 PCI RAID controller; third controller - 0 = /dev/rd/c2d0 First disk, whole disk - 8 = /dev/rd/c2d1 Second disk, whole disk - ... - 248 = /dev/rd/c2d31 32nd disk, whole disk - - 51 char Baycom radio modem OR Radio Tech BIM-XXX-RS232 radio modem - 0 = /dev/bc0 First Baycom radio modem - 1 = /dev/bc1 Second Baycom radio modem - ... - 51 block Mylex DAC960 PCI RAID controller; fourth controller - 0 = /dev/rd/c3d0 First disk, whole disk - 8 = /dev/rd/c3d1 Second disk, whole disk - ... - 248 = /dev/rd/c3d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 52 char Spellcaster DataComm/BRI ISDN card - 0 = /dev/dcbri0 First DataComm card - 1 = /dev/dcbri1 Second DataComm card - 2 = /dev/dcbri2 Third DataComm card - 3 = /dev/dcbri3 Fourth DataComm card - - 52 block Mylex DAC960 PCI RAID controller; fifth controller - 0 = /dev/rd/c4d0 First disk, whole disk - 8 = /dev/rd/c4d1 Second disk, whole disk - ... - 248 = /dev/rd/c4d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 53 char BDM interface for remote debugging MC683xx microcontrollers - 0 = /dev/pd_bdm0 PD BDM interface on lp0 - 1 = /dev/pd_bdm1 PD BDM interface on lp1 - 2 = /dev/pd_bdm2 PD BDM interface on lp2 - 4 = /dev/icd_bdm0 ICD BDM interface on lp0 - 5 = /dev/icd_bdm1 ICD BDM interface on lp1 - 6 = /dev/icd_bdm2 ICD BDM interface on lp2 - - This device is used for the interfacing to the MC683xx - microcontrollers via Background Debug Mode by use of a - Parallel Port interface. PD is the Motorola Public - Domain Interface and ICD is the commercial interface - by P&E. - - 53 block Mylex DAC960 PCI RAID controller; sixth controller - 0 = /dev/rd/c5d0 First disk, whole disk - 8 = /dev/rd/c5d1 Second disk, whole disk - ... - 248 = /dev/rd/c5d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 54 char Electrocardiognosis Holter serial card - 0 = /dev/holter0 First Holter port - 1 = /dev/holter1 Second Holter port - 2 = /dev/holter2 Third Holter port - - A custom serial card used by Electrocardiognosis SRL - to transfer data from Holter - 24-hour heart monitoring equipment. - - 54 block Mylex DAC960 PCI RAID controller; seventh controller - 0 = /dev/rd/c6d0 First disk, whole disk - 8 = /dev/rd/c6d1 Second disk, whole disk - ... - 248 = /dev/rd/c6d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 55 char DSP56001 digital signal processor - 0 = /dev/dsp56k First DSP56001 - - 55 block Mylex DAC960 PCI RAID controller; eighth controller - 0 = /dev/rd/c7d0 First disk, whole disk - 8 = /dev/rd/c7d1 Second disk, whole disk - ... - 248 = /dev/rd/c7d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 56 char Apple Desktop Bus - 0 = /dev/adb ADB bus control - - Additional devices will be added to this number, all - starting with /dev/adb. - - 56 block Fifth IDE hard disk/CD-ROM interface - 0 = /dev/hdi Master: whole disk (or CD-ROM) - 64 = /dev/hdj Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 57 char Hayes ESP serial card - 0 = /dev/ttyP0 First ESP port - 1 = /dev/ttyP1 Second ESP port - ... - - 57 block Sixth IDE hard disk/CD-ROM interface - 0 = /dev/hdk Master: whole disk (or CD-ROM) - 64 = /dev/hdl Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 58 char Hayes ESP serial card - alternate devices - 0 = /dev/cup0 Callout device for ttyP0 - 1 = /dev/cup1 Callout device for ttyP1 - ... - - 58 block Reserved for logical volume manager - - 59 char sf firewall package - 0 = /dev/firewall Communication with sf kernel module - - 59 block Generic PDA filesystem device - 0 = /dev/pda0 First PDA device - 1 = /dev/pda1 Second PDA device - ... - - The pda devices are used to mount filesystems on - remote pda's (basically slow handheld machines with - proprietary OS's and limited memory and storage - running small fs translation drivers) through serial / - IRDA / parallel links. - - NAMING CONFLICT -- PROPOSED REVISED NAME /dev/rpda0 etc - - 60-63 char LOCAL/EXPERIMENTAL USE - - 60-63 block LOCAL/EXPERIMENTAL USE - Allocated for local/experimental use. For devices not - assigned official numbers, these ranges should be - used in order to avoid conflicting with future assignments. - - 64 char ENskip kernel encryption package - 0 = /dev/enskip Communication with ENskip kernel module - - 64 block Scramdisk/DriveCrypt encrypted devices - 0 = /dev/scramdisk/master Master node for ioctls - 1 = /dev/scramdisk/1 First encrypted device - 2 = /dev/scramdisk/2 Second encrypted device - ... - 255 = /dev/scramdisk/255 255th encrypted device - - The filename of the encrypted container and the passwords - are sent via ioctls (using the sdmount tool) to the master - node which then activates them via one of the - /dev/scramdisk/x nodes for loop mounting (all handled - through the sdmount tool). - - Requested by: andy@scramdisklinux.org - - 65 char Sundance "plink" Transputer boards (obsolete, unused) - 0 = /dev/plink0 First plink device - 1 = /dev/plink1 Second plink device - 2 = /dev/plink2 Third plink device - 3 = /dev/plink3 Fourth plink device - 64 = /dev/rplink0 First plink device, raw - 65 = /dev/rplink1 Second plink device, raw - 66 = /dev/rplink2 Third plink device, raw - 67 = /dev/rplink3 Fourth plink device, raw - 128 = /dev/plink0d First plink device, debug - 129 = /dev/plink1d Second plink device, debug - 130 = /dev/plink2d Third plink device, debug - 131 = /dev/plink3d Fourth plink device, debug - 192 = /dev/rplink0d First plink device, raw, debug - 193 = /dev/rplink1d Second plink device, raw, debug - 194 = /dev/rplink2d Third plink device, raw, debug - 195 = /dev/rplink3d Fourth plink device, raw, debug - - This is a commercial driver; contact James Howes - for information. - - 65 block SCSI disk devices (16-31) - 0 = /dev/sdq 17th SCSI disk whole disk - 16 = /dev/sdr 18th SCSI disk whole disk - 32 = /dev/sds 19th SCSI disk whole disk - ... - 240 = /dev/sdaf 32nd SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 66 char YARC PowerPC PCI coprocessor card - 0 = /dev/yppcpci0 First YARC card - 1 = /dev/yppcpci1 Second YARC card - ... - - 66 block SCSI disk devices (32-47) - 0 = /dev/sdag 33th SCSI disk whole disk - 16 = /dev/sdah 34th SCSI disk whole disk - 32 = /dev/sdai 35th SCSI disk whole disk - ... - 240 = /dev/sdav 48nd SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 67 char Coda network file system - 0 = /dev/cfs0 Coda cache manager - - See http://www.coda.cs.cmu.edu for information about Coda. - - 67 block SCSI disk devices (48-63) - 0 = /dev/sdaw 49th SCSI disk whole disk - 16 = /dev/sdax 50th SCSI disk whole disk - 32 = /dev/sday 51st SCSI disk whole disk - ... - 240 = /dev/sdbl 64th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 68 char CAPI 2.0 interface - 0 = /dev/capi20 Control device - 1 = /dev/capi20.00 First CAPI 2.0 application - 2 = /dev/capi20.01 Second CAPI 2.0 application - ... - 20 = /dev/capi20.19 19th CAPI 2.0 application - - ISDN CAPI 2.0 driver for use with CAPI 2.0 - applications; currently supports the AVM B1 card. - - 68 block SCSI disk devices (64-79) - 0 = /dev/sdbm 65th SCSI disk whole disk - 16 = /dev/sdbn 66th SCSI disk whole disk - 32 = /dev/sdbo 67th SCSI disk whole disk - ... - 240 = /dev/sdcb 80th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 69 char MA16 numeric accelerator card - 0 = /dev/ma16 Board memory access - - 69 block SCSI disk devices (80-95) - 0 = /dev/sdcc 81st SCSI disk whole disk - 16 = /dev/sdcd 82nd SCSI disk whole disk - 32 = /dev/sdce 83th SCSI disk whole disk - ... - 240 = /dev/sdcr 96th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 70 char SpellCaster Protocol Services Interface - 0 = /dev/apscfg Configuration interface - 1 = /dev/apsauth Authentication interface - 2 = /dev/apslog Logging interface - 3 = /dev/apsdbg Debugging interface - 64 = /dev/apsisdn ISDN command interface - 65 = /dev/apsasync Async command interface - 128 = /dev/apsmon Monitor interface - - 70 block SCSI disk devices (96-111) - 0 = /dev/sdcs 97th SCSI disk whole disk - 16 = /dev/sdct 98th SCSI disk whole disk - 32 = /dev/sdcu 99th SCSI disk whole disk - ... - 240 = /dev/sddh 112nd SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 71 char Computone IntelliPort II serial card - 0 = /dev/ttyF0 IntelliPort II board 0, port 0 - 1 = /dev/ttyF1 IntelliPort II board 0, port 1 - ... - 63 = /dev/ttyF63 IntelliPort II board 0, port 63 - 64 = /dev/ttyF64 IntelliPort II board 1, port 0 - 65 = /dev/ttyF65 IntelliPort II board 1, port 1 - ... - 127 = /dev/ttyF127 IntelliPort II board 1, port 63 - 128 = /dev/ttyF128 IntelliPort II board 2, port 0 - 129 = /dev/ttyF129 IntelliPort II board 2, port 1 - ... - 191 = /dev/ttyF191 IntelliPort II board 2, port 63 - 192 = /dev/ttyF192 IntelliPort II board 3, port 0 - 193 = /dev/ttyF193 IntelliPort II board 3, port 1 - ... - 255 = /dev/ttyF255 IntelliPort II board 3, port 63 - - 71 block SCSI disk devices (112-127) - 0 = /dev/sddi 113th SCSI disk whole disk - 16 = /dev/sddj 114th SCSI disk whole disk - 32 = /dev/sddk 115th SCSI disk whole disk - ... - 240 = /dev/sddx 128th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 72 char Computone IntelliPort II serial card - alternate devices - 0 = /dev/cuf0 Callout device for ttyF0 - 1 = /dev/cuf1 Callout device for ttyF1 - ... - 63 = /dev/cuf63 Callout device for ttyF63 - 64 = /dev/cuf64 Callout device for ttyF64 - 65 = /dev/cuf65 Callout device for ttyF65 - ... - 127 = /dev/cuf127 Callout device for ttyF127 - 128 = /dev/cuf128 Callout device for ttyF128 - 129 = /dev/cuf129 Callout device for ttyF129 - ... - 191 = /dev/cuf191 Callout device for ttyF191 - 192 = /dev/cuf192 Callout device for ttyF192 - 193 = /dev/cuf193 Callout device for ttyF193 - ... - 255 = /dev/cuf255 Callout device for ttyF255 - - 72 block Compaq Intelligent Drive Array, first controller - 0 = /dev/ida/c0d0 First logical drive whole disk - 16 = /dev/ida/c0d1 Second logical drive whole disk - ... - 240 = /dev/ida/c0d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 73 char Computone IntelliPort II serial card - control devices - 0 = /dev/ip2ipl0 Loadware device for board 0 - 1 = /dev/ip2stat0 Status device for board 0 - 4 = /dev/ip2ipl1 Loadware device for board 1 - 5 = /dev/ip2stat1 Status device for board 1 - 8 = /dev/ip2ipl2 Loadware device for board 2 - 9 = /dev/ip2stat2 Status device for board 2 - 12 = /dev/ip2ipl3 Loadware device for board 3 - 13 = /dev/ip2stat3 Status device for board 3 - - 73 block Compaq Intelligent Drive Array, second controller - 0 = /dev/ida/c1d0 First logical drive whole disk - 16 = /dev/ida/c1d1 Second logical drive whole disk - ... - 240 = /dev/ida/c1d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 74 char SCI bridge - 0 = /dev/SCI/0 SCI device 0 - 1 = /dev/SCI/1 SCI device 1 - ... - - Currently for Dolphin Interconnect Solutions' PCI-SCI - bridge. - - 74 block Compaq Intelligent Drive Array, third controller - 0 = /dev/ida/c2d0 First logical drive whole disk - 16 = /dev/ida/c2d1 Second logical drive whole disk - ... - 240 = /dev/ida/c2d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 75 char Specialix IO8+ serial card - 0 = /dev/ttyW0 First IO8+ port, first card - 1 = /dev/ttyW1 Second IO8+ port, first card - ... - 8 = /dev/ttyW8 First IO8+ port, second card - ... - - 75 block Compaq Intelligent Drive Array, fourth controller - 0 = /dev/ida/c3d0 First logical drive whole disk - 16 = /dev/ida/c3d1 Second logical drive whole disk - ... - 240 = /dev/ida/c3d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 76 char Specialix IO8+ serial card - alternate devices - 0 = /dev/cuw0 Callout device for ttyW0 - 1 = /dev/cuw1 Callout device for ttyW1 - ... - 8 = /dev/cuw8 Callout device for ttyW8 - ... - - 76 block Compaq Intelligent Drive Array, fifth controller - 0 = /dev/ida/c4d0 First logical drive whole disk - 16 = /dev/ida/c4d1 Second logical drive whole disk - ... - 240 = /dev/ida/c4d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - - 77 char ComScire Quantum Noise Generator - 0 = /dev/qng ComScire Quantum Noise Generator - - 77 block Compaq Intelligent Drive Array, sixth controller - 0 = /dev/ida/c5d0 First logical drive whole disk - 16 = /dev/ida/c5d1 Second logical drive whole disk - ... - 240 = /dev/ida/c5d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 78 char PAM Software's multimodem boards - 0 = /dev/ttyM0 First PAM modem - 1 = /dev/ttyM1 Second PAM modem - ... - - 78 block Compaq Intelligent Drive Array, seventh controller - 0 = /dev/ida/c6d0 First logical drive whole disk - 16 = /dev/ida/c6d1 Second logical drive whole disk - ... - 240 = /dev/ida/c6d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 79 char PAM Software's multimodem boards - alternate devices - 0 = /dev/cum0 Callout device for ttyM0 - 1 = /dev/cum1 Callout device for ttyM1 - ... - - 79 block Compaq Intelligent Drive Array, eighth controller - 0 = /dev/ida/c7d0 First logical drive whole disk - 16 = /dev/ida/c7d1 Second logical drive whole disk - ... - 240 = /dev/ida/c715 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 80 char Photometrics AT200 CCD camera - 0 = /dev/at200 Photometrics AT200 CCD camera - - 80 block I2O hard disk - 0 = /dev/i2o/hda First I2O hard disk, whole disk - 16 = /dev/i2o/hdb Second I2O hard disk, whole disk - ... - 240 = /dev/i2o/hdp 16th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 81 char video4linux - 0 = /dev/video0 Video capture/overlay device - ... - 63 = /dev/video63 Video capture/overlay device - 64 = /dev/radio0 Radio device - ... - 127 = /dev/radio63 Radio device - 128 = /dev/swradio0 Software Defined Radio device - ... - 191 = /dev/swradio63 Software Defined Radio device - 224 = /dev/vbi0 Vertical blank interrupt - ... - 255 = /dev/vbi31 Vertical blank interrupt - - Minor numbers are allocated dynamically unless - CONFIG_VIDEO_FIXED_MINOR_RANGES (default n) - configuration option is set. - - 81 block I2O hard disk - 0 = /dev/i2o/hdq 17th I2O hard disk, whole disk - 16 = /dev/i2o/hdr 18th I2O hard disk, whole disk - ... - 240 = /dev/i2o/hdaf 32nd I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 82 char WiNRADiO communications receiver card - 0 = /dev/winradio0 First WiNRADiO card - 1 = /dev/winradio1 Second WiNRADiO card - ... - - The driver and documentation may be obtained from - http://www.winradio.com/ - - 82 block I2O hard disk - 0 = /dev/i2o/hdag 33rd I2O hard disk, whole disk - 16 = /dev/i2o/hdah 34th I2O hard disk, whole disk - ... - 240 = /dev/i2o/hdav 48th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 83 char Matrox mga_vid video driver - 0 = /dev/mga_vid0 1st video card - 1 = /dev/mga_vid1 2nd video card - 2 = /dev/mga_vid2 3rd video card - ... - 15 = /dev/mga_vid15 16th video card - - 83 block I2O hard disk - 0 = /dev/i2o/hdaw 49th I2O hard disk, whole disk - 16 = /dev/i2o/hdax 50th I2O hard disk, whole disk - ... - 240 = /dev/i2o/hdbl 64th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 84 char Ikon 1011[57] Versatec Greensheet Interface - 0 = /dev/ihcp0 First Greensheet port - 1 = /dev/ihcp1 Second Greensheet port - - 84 block I2O hard disk - 0 = /dev/i2o/hdbm 65th I2O hard disk, whole disk - 16 = /dev/i2o/hdbn 66th I2O hard disk, whole disk - ... - 240 = /dev/i2o/hdcb 80th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 85 char Linux/SGI shared memory input queue - 0 = /dev/shmiq Master shared input queue - 1 = /dev/qcntl0 First device pushed - 2 = /dev/qcntl1 Second device pushed - ... - - 85 block I2O hard disk - 0 = /dev/i2o/hdcc 81st I2O hard disk, whole disk - 16 = /dev/i2o/hdcd 82nd I2O hard disk, whole disk - ... - 240 = /dev/i2o/hdcr 96th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 86 char SCSI media changer - 0 = /dev/sch0 First SCSI media changer - 1 = /dev/sch1 Second SCSI media changer - ... - - 86 block I2O hard disk - 0 = /dev/i2o/hdcs 97th I2O hard disk, whole disk - 16 = /dev/i2o/hdct 98th I2O hard disk, whole disk - ... - 240 = /dev/i2o/hddh 112th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 87 char Sony Control-A1 stereo control bus - 0 = /dev/controla0 First device on chain - 1 = /dev/controla1 Second device on chain - ... - - 87 block I2O hard disk - 0 = /dev/i2o/hddi 113rd I2O hard disk, whole disk - 16 = /dev/i2o/hddj 114th I2O hard disk, whole disk - ... - 240 = /dev/i2o/hddx 128th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 88 char COMX synchronous serial card - 0 = /dev/comx0 COMX channel 0 - 1 = /dev/comx1 COMX channel 1 - ... - - 88 block Seventh IDE hard disk/CD-ROM interface - 0 = /dev/hdm Master: whole disk (or CD-ROM) - 64 = /dev/hdn Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 89 char I2C bus interface - 0 = /dev/i2c-0 First I2C adapter - 1 = /dev/i2c-1 Second I2C adapter - ... - - 89 block Eighth IDE hard disk/CD-ROM interface - 0 = /dev/hdo Master: whole disk (or CD-ROM) - 64 = /dev/hdp Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 90 char Memory Technology Device (RAM, ROM, Flash) - 0 = /dev/mtd0 First MTD (rw) - 1 = /dev/mtdr0 First MTD (ro) - ... - 30 = /dev/mtd15 16th MTD (rw) - 31 = /dev/mtdr15 16th MTD (ro) - - 90 block Ninth IDE hard disk/CD-ROM interface - 0 = /dev/hdq Master: whole disk (or CD-ROM) - 64 = /dev/hdr Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 91 char CAN-Bus devices - 0 = /dev/can0 First CAN-Bus controller - 1 = /dev/can1 Second CAN-Bus controller - ... - - 91 block Tenth IDE hard disk/CD-ROM interface - 0 = /dev/hds Master: whole disk (or CD-ROM) - 64 = /dev/hdt Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 92 char Reserved for ith Kommunikationstechnik MIC ISDN card - - 92 block PPDD encrypted disk driver - 0 = /dev/ppdd0 First encrypted disk - 1 = /dev/ppdd1 Second encrypted disk - ... - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 93 char - - 93 block NAND Flash Translation Layer filesystem - 0 = /dev/nftla First NFTL layer - 16 = /dev/nftlb Second NFTL layer - ... - 240 = /dev/nftlp 16th NTFL layer - - 94 char - - 94 block IBM S/390 DASD block storage - 0 = /dev/dasda First DASD device, major - 1 = /dev/dasda1 First DASD device, block 1 - 2 = /dev/dasda2 First DASD device, block 2 - 3 = /dev/dasda3 First DASD device, block 3 - 4 = /dev/dasdb Second DASD device, major - 5 = /dev/dasdb1 Second DASD device, block 1 - 6 = /dev/dasdb2 Second DASD device, block 2 - 7 = /dev/dasdb3 Second DASD device, block 3 - ... - - 95 char IP filter - 0 = /dev/ipl Filter control device/log file - 1 = /dev/ipnat NAT control device/log file - 2 = /dev/ipstate State information log file - 3 = /dev/ipauth Authentication control device/log file - ... - - 96 char Parallel port ATAPI tape devices - 0 = /dev/pt0 First parallel port ATAPI tape - 1 = /dev/pt1 Second parallel port ATAPI tape - ... - 128 = /dev/npt0 First p.p. ATAPI tape, no rewind - 129 = /dev/npt1 Second p.p. ATAPI tape, no rewind - ... - - 96 block Inverse NAND Flash Translation Layer - 0 = /dev/inftla First INFTL layer - 16 = /dev/inftlb Second INFTL layer - ... - 240 = /dev/inftlp 16th INTFL layer - - 97 char Parallel port generic ATAPI interface - 0 = /dev/pg0 First parallel port ATAPI device - 1 = /dev/pg1 Second parallel port ATAPI device - 2 = /dev/pg2 Third parallel port ATAPI device - 3 = /dev/pg3 Fourth parallel port ATAPI device - - These devices support the same API as the generic SCSI - devices. - - 98 char Control and Measurement Device (comedi) - 0 = /dev/comedi0 First comedi device - 1 = /dev/comedi1 Second comedi device - ... - - See http://stm.lbl.gov/comedi. - - 98 block User-mode virtual block device - 0 = /dev/ubda First user-mode block device - 16 = /dev/udbb Second user-mode block device - ... - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - This device is used by the user-mode virtual kernel port. - - 99 char Raw parallel ports - 0 = /dev/parport0 First parallel port - 1 = /dev/parport1 Second parallel port - ... - - 99 block JavaStation flash disk - 0 = /dev/jsfd JavaStation flash disk - - 100 char Telephony for Linux - 0 = /dev/phone0 First telephony device - 1 = /dev/phone1 Second telephony device - ... - - 101 char Motorola DSP 56xxx board - 0 = /dev/mdspstat Status information - 1 = /dev/mdsp1 First DSP board I/O controls - ... - 16 = /dev/mdsp16 16th DSP board I/O controls - - 101 block AMI HyperDisk RAID controller - 0 = /dev/amiraid/ar0 First array whole disk - 16 = /dev/amiraid/ar1 Second array whole disk - ... - 240 = /dev/amiraid/ar15 16th array whole disk - - For each device, partitions are added as: - 0 = /dev/amiraid/ar? Whole disk - 1 = /dev/amiraid/ar?p1 First partition - 2 = /dev/amiraid/ar?p2 Second partition - ... - 15 = /dev/amiraid/ar?p15 15th partition - - 102 char - - 102 block Compressed block device - 0 = /dev/cbd/a First compressed block device, whole device - 16 = /dev/cbd/b Second compressed block device, whole device - ... - 240 = /dev/cbd/p 16th compressed block device, whole device - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 103 char Arla network file system - 0 = /dev/nnpfs0 First NNPFS device - 1 = /dev/nnpfs1 Second NNPFS device - - Arla is a free clone of the Andrew File System, AFS. - The NNPFS device gives user mode filesystem - implementations a kernel presence for caching and easy - mounting. For more information about the project, - write to or see - http://www.stacken.kth.se/project/arla/ - - 103 block Audit device - 0 = /dev/audit Audit device - - 104 char Flash BIOS support - - 104 block Compaq Next Generation Drive Array, first controller - 0 = /dev/cciss/c0d0 First logical drive, whole disk - 16 = /dev/cciss/c0d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c0d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 105 char Comtrol VS-1000 serial controller - 0 = /dev/ttyV0 First VS-1000 port - 1 = /dev/ttyV1 Second VS-1000 port - ... - - 105 block Compaq Next Generation Drive Array, second controller - 0 = /dev/cciss/c1d0 First logical drive, whole disk - 16 = /dev/cciss/c1d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c1d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 106 char Comtrol VS-1000 serial controller - alternate devices - 0 = /dev/cuv0 First VS-1000 port - 1 = /dev/cuv1 Second VS-1000 port - ... - - 106 block Compaq Next Generation Drive Array, third controller - 0 = /dev/cciss/c2d0 First logical drive, whole disk - 16 = /dev/cciss/c2d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c2d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 107 char 3Dfx Voodoo Graphics device - 0 = /dev/3dfx Primary 3Dfx graphics device - - 107 block Compaq Next Generation Drive Array, fourth controller - 0 = /dev/cciss/c3d0 First logical drive, whole disk - 16 = /dev/cciss/c3d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c3d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 108 char Device independent PPP interface - 0 = /dev/ppp Device independent PPP interface - - 108 block Compaq Next Generation Drive Array, fifth controller - 0 = /dev/cciss/c4d0 First logical drive, whole disk - 16 = /dev/cciss/c4d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c4d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 109 char Reserved for logical volume manager - - 109 block Compaq Next Generation Drive Array, sixth controller - 0 = /dev/cciss/c5d0 First logical drive, whole disk - 16 = /dev/cciss/c5d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c5d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 110 char miroMEDIA Surround board - 0 = /dev/srnd0 First miroMEDIA Surround board - 1 = /dev/srnd1 Second miroMEDIA Surround board - ... - - 110 block Compaq Next Generation Drive Array, seventh controller - 0 = /dev/cciss/c6d0 First logical drive, whole disk - 16 = /dev/cciss/c6d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c6d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 111 char - - 111 block Compaq Next Generation Drive Array, eighth controller - 0 = /dev/cciss/c7d0 First logical drive, whole disk - 16 = /dev/cciss/c7d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c7d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 112 char ISI serial card - 0 = /dev/ttyM0 First ISI port - 1 = /dev/ttyM1 Second ISI port - ... - - There is currently a device-naming conflict between - these and PAM multimodems (major 78). - - 112 block IBM iSeries virtual disk - 0 = /dev/iseries/vda First virtual disk, whole disk - 8 = /dev/iseries/vdb Second virtual disk, whole disk - ... - 200 = /dev/iseries/vdz 26th virtual disk, whole disk - 208 = /dev/iseries/vdaa 27th virtual disk, whole disk - ... - 248 = /dev/iseries/vdaf 32nd virtual disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 7. - - 113 char ISI serial card - alternate devices - 0 = /dev/cum0 Callout device for ttyM0 - 1 = /dev/cum1 Callout device for ttyM1 - ... - - 113 block IBM iSeries virtual CD-ROM - 0 = /dev/iseries/vcda First virtual CD-ROM - 1 = /dev/iseries/vcdb Second virtual CD-ROM - ... - - 114 char Picture Elements ISE board - 0 = /dev/ise0 First ISE board - 1 = /dev/ise1 Second ISE board - ... - 128 = /dev/isex0 Control node for first ISE board - 129 = /dev/isex1 Control node for second ISE board - ... - - The ISE board is an embedded computer, optimized for - image processing. The /dev/iseN nodes are the general - I/O access to the board, the /dev/isex0 nodes command - nodes used to control the board. - - 114 block IDE BIOS powered software RAID interfaces such as the - Promise Fastrak - - 0 = /dev/ataraid/d0 - 1 = /dev/ataraid/d0p1 - 2 = /dev/ataraid/d0p2 - ... - 16 = /dev/ataraid/d1 - 17 = /dev/ataraid/d1p1 - 18 = /dev/ataraid/d1p2 - ... - 255 = /dev/ataraid/d15p15 - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 115 char TI link cable devices (115 was formerly the console driver speaker) - 0 = /dev/tipar0 Parallel cable on first parallel port - ... - 7 = /dev/tipar7 Parallel cable on seventh parallel port - - 8 = /dev/tiser0 Serial cable on first serial port - ... - 15 = /dev/tiser7 Serial cable on seventh serial port - - 16 = /dev/tiusb0 First USB cable - ... - 47 = /dev/tiusb31 32nd USB cable - - 115 block NetWare (NWFS) Devices (0-255) - - The NWFS (NetWare) devices are used to present a - collection of NetWare Mirror Groups or NetWare - Partitions as a logical storage segment for - use in mounting NetWare volumes. A maximum of - 256 NetWare volumes can be supported in a single - machine. - - http://cgfa.telepac.pt/ftp2/kernel.org/linux/kernel/people/jmerkey/nwfs/ - - 0 = /dev/nwfs/v0 First NetWare (NWFS) Logical Volume - 1 = /dev/nwfs/v1 Second NetWare (NWFS) Logical Volume - 2 = /dev/nwfs/v2 Third NetWare (NWFS) Logical Volume - ... - 255 = /dev/nwfs/v255 Last NetWare (NWFS) Logical Volume - - 116 char Advanced Linux Sound Driver (ALSA) - - 116 block MicroMemory battery backed RAM adapter (NVRAM) - Supports 16 boards, 15 partitions each. - Requested by neilb at cse.unsw.edu.au. - - 0 = /dev/umem/d0 Whole of first board - 1 = /dev/umem/d0p1 First partition of first board - 2 = /dev/umem/d0p2 Second partition of first board - 15 = /dev/umem/d0p15 15th partition of first board - - 16 = /dev/umem/d1 Whole of second board - 17 = /dev/umem/d1p1 First partition of second board - ... - 255= /dev/umem/d15p15 15th partition of 16th board. - - 117 char COSA/SRP synchronous serial card - 0 = /dev/cosa0c0 1st board, 1st channel - 1 = /dev/cosa0c1 1st board, 2nd channel - ... - 16 = /dev/cosa1c0 2nd board, 1st channel - 17 = /dev/cosa1c1 2nd board, 2nd channel - ... - - 117 block Enterprise Volume Management System (EVMS) - - The EVMS driver uses a layered, plug-in model to provide - unparalleled flexibility and extensibility in managing - storage. This allows for easy expansion or customization - of various levels of volume management. Requested by - Mark Peloquin (peloquin at us.ibm.com). - - Note: EVMS populates and manages all the devnodes in - /dev/evms. - - http://sf.net/projects/evms - - 0 = /dev/evms/block_device EVMS block device - 1 = /dev/evms/legacyname1 First EVMS legacy device - 2 = /dev/evms/legacyname2 Second EVMS legacy device - ... - Both ranges can grow (down or up) until they meet. - ... - 254 = /dev/evms/EVMSname2 Second EVMS native device - 255 = /dev/evms/EVMSname1 First EVMS native device - - Note: legacyname(s) are derived from the normal legacy - device names. For example, /dev/hda5 would become - /dev/evms/hda5. - - 118 char IBM Cryptographic Accelerator - 0 = /dev/ica Virtual interface to all IBM Crypto Accelerators - 1 = /dev/ica0 IBMCA Device 0 - 2 = /dev/ica1 IBMCA Device 1 - ... - - 119 char VMware virtual network control - 0 = /dev/vnet0 1st virtual network - 1 = /dev/vnet1 2nd virtual network - ... - - 120-127 char LOCAL/EXPERIMENTAL USE - - 120-127 block LOCAL/EXPERIMENTAL USE - Allocated for local/experimental use. For devices not - assigned official numbers, these ranges should be - used in order to avoid conflicting with future assignments. - - 128-135 char Unix98 PTY masters - - These devices should not have corresponding device - nodes; instead they should be accessed through the - /dev/ptmx cloning interface. - - 128 block SCSI disk devices (128-143) - 0 = /dev/sddy 129th SCSI disk whole disk - 16 = /dev/sddz 130th SCSI disk whole disk - 32 = /dev/sdea 131th SCSI disk whole disk - ... - 240 = /dev/sden 144th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 129 block SCSI disk devices (144-159) - 0 = /dev/sdeo 145th SCSI disk whole disk - 16 = /dev/sdep 146th SCSI disk whole disk - 32 = /dev/sdeq 147th SCSI disk whole disk - ... - 240 = /dev/sdfd 160th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 130 char (Misc devices) - - 130 block SCSI disk devices (160-175) - 0 = /dev/sdfe 161st SCSI disk whole disk - 16 = /dev/sdff 162nd SCSI disk whole disk - 32 = /dev/sdfg 163rd SCSI disk whole disk - ... - 240 = /dev/sdft 176th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 131 block SCSI disk devices (176-191) - 0 = /dev/sdfu 177th SCSI disk whole disk - 16 = /dev/sdfv 178th SCSI disk whole disk - 32 = /dev/sdfw 179th SCSI disk whole disk - ... - 240 = /dev/sdgj 192nd SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 132 block SCSI disk devices (192-207) - 0 = /dev/sdgk 193rd SCSI disk whole disk - 16 = /dev/sdgl 194th SCSI disk whole disk - 32 = /dev/sdgm 195th SCSI disk whole disk - ... - 240 = /dev/sdgz 208th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 133 block SCSI disk devices (208-223) - 0 = /dev/sdha 209th SCSI disk whole disk - 16 = /dev/sdhb 210th SCSI disk whole disk - 32 = /dev/sdhc 211th SCSI disk whole disk - ... - 240 = /dev/sdhp 224th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 134 block SCSI disk devices (224-239) - 0 = /dev/sdhq 225th SCSI disk whole disk - 16 = /dev/sdhr 226th SCSI disk whole disk - 32 = /dev/sdhs 227th SCSI disk whole disk - ... - 240 = /dev/sdif 240th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 135 block SCSI disk devices (240-255) - 0 = /dev/sdig 241st SCSI disk whole disk - 16 = /dev/sdih 242nd SCSI disk whole disk - 32 = /dev/sdih 243rd SCSI disk whole disk - ... - 240 = /dev/sdiv 256th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 136-143 char Unix98 PTY slaves - 0 = /dev/pts/0 First Unix98 pseudo-TTY - 1 = /dev/pts/1 Second Unix98 pseudo-TTY - ... - - These device nodes are automatically generated with - the proper permissions and modes by mounting the - devpts filesystem onto /dev/pts with the appropriate - mount options (distribution dependent, however, on - *most* distributions the appropriate options are - "mode=0620,gid=".) - - 136 block Mylex DAC960 PCI RAID controller; ninth controller - 0 = /dev/rd/c8d0 First disk, whole disk - 8 = /dev/rd/c8d1 Second disk, whole disk - ... - 248 = /dev/rd/c8d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 137 block Mylex DAC960 PCI RAID controller; tenth controller - 0 = /dev/rd/c9d0 First disk, whole disk - 8 = /dev/rd/c9d1 Second disk, whole disk - ... - 248 = /dev/rd/c9d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 138 block Mylex DAC960 PCI RAID controller; eleventh controller - 0 = /dev/rd/c10d0 First disk, whole disk - 8 = /dev/rd/c10d1 Second disk, whole disk - ... - 248 = /dev/rd/c10d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 139 block Mylex DAC960 PCI RAID controller; twelfth controller - 0 = /dev/rd/c11d0 First disk, whole disk - 8 = /dev/rd/c11d1 Second disk, whole disk - ... - 248 = /dev/rd/c11d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 140 block Mylex DAC960 PCI RAID controller; thirteenth controller - 0 = /dev/rd/c12d0 First disk, whole disk - 8 = /dev/rd/c12d1 Second disk, whole disk - ... - 248 = /dev/rd/c12d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 141 block Mylex DAC960 PCI RAID controller; fourteenth controller - 0 = /dev/rd/c13d0 First disk, whole disk - 8 = /dev/rd/c13d1 Second disk, whole disk - ... - 248 = /dev/rd/c13d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 142 block Mylex DAC960 PCI RAID controller; fifteenth controller - 0 = /dev/rd/c14d0 First disk, whole disk - 8 = /dev/rd/c14d1 Second disk, whole disk - ... - 248 = /dev/rd/c14d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 143 block Mylex DAC960 PCI RAID controller; sixteenth controller - 0 = /dev/rd/c15d0 First disk, whole disk - 8 = /dev/rd/c15d1 Second disk, whole disk - ... - 248 = /dev/rd/c15d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 144 char Encapsulated PPP - 0 = /dev/pppox0 First PPP over Ethernet - ... - 63 = /dev/pppox63 64th PPP over Ethernet - - This is primarily used for ADSL. - - The SST 5136-DN DeviceNet interface driver has been - relocated to major 183 due to an unfortunate conflict. - - 144 block Expansion Area #1 for more non-device (e.g. NFS) mounts - 0 = mounted device 256 - 255 = mounted device 511 - - 145 char SAM9407-based soundcard - 0 = /dev/sam0_mixer - 1 = /dev/sam0_sequencer - 2 = /dev/sam0_midi00 - 3 = /dev/sam0_dsp - 4 = /dev/sam0_audio - 6 = /dev/sam0_sndstat - 18 = /dev/sam0_midi01 - 34 = /dev/sam0_midi02 - 50 = /dev/sam0_midi03 - 64 = /dev/sam1_mixer - ... - 128 = /dev/sam2_mixer - ... - 192 = /dev/sam3_mixer - ... - - Device functions match OSS, but offer a number of - addons, which are sam9407 specific. OSS can be - operated simultaneously, taking care of the codec. - - 145 block Expansion Area #2 for more non-device (e.g. NFS) mounts - 0 = mounted device 512 - 255 = mounted device 767 - - 146 char SYSTRAM SCRAMNet mirrored-memory network - 0 = /dev/scramnet0 First SCRAMNet device - 1 = /dev/scramnet1 Second SCRAMNet device - ... - - 146 block Expansion Area #3 for more non-device (e.g. NFS) mounts - 0 = mounted device 768 - 255 = mounted device 1023 - - 147 char Aureal Semiconductor Vortex Audio device - 0 = /dev/aureal0 First Aureal Vortex - 1 = /dev/aureal1 Second Aureal Vortex - ... - - 147 block Distributed Replicated Block Device (DRBD) - 0 = /dev/drbd0 First DRBD device - 1 = /dev/drbd1 Second DRBD device - ... - - 148 char Technology Concepts serial card - 0 = /dev/ttyT0 First TCL port - 1 = /dev/ttyT1 Second TCL port - ... - - 149 char Technology Concepts serial card - alternate devices - 0 = /dev/cut0 Callout device for ttyT0 - 1 = /dev/cut0 Callout device for ttyT1 - ... - - 150 char Real-Time Linux FIFOs - 0 = /dev/rtf0 First RTLinux FIFO - 1 = /dev/rtf1 Second RTLinux FIFO - ... - - 151 char DPT I2O SmartRaid V controller - 0 = /dev/dpti0 First DPT I2O adapter - 1 = /dev/dpti1 Second DPT I2O adapter - ... - - 152 char EtherDrive Control Device - 0 = /dev/etherd/ctl Connect/Disconnect an EtherDrive - 1 = /dev/etherd/err Monitor errors - 2 = /dev/etherd/raw Raw AoE packet monitor - - 152 block EtherDrive Block Devices - 0 = /dev/etherd/0 EtherDrive 0 - ... - 255 = /dev/etherd/255 EtherDrive 255 - - 153 char SPI Bus Interface (sometimes referred to as MicroWire) - 0 = /dev/spi0 First SPI device on the bus - 1 = /dev/spi1 Second SPI device on the bus - ... - 15 = /dev/spi15 Sixteenth SPI device on the bus - - 153 block Enhanced Metadisk RAID (EMD) storage units - 0 = /dev/emd/0 First unit - 1 = /dev/emd/0p1 Partition 1 on First unit - 2 = /dev/emd/0p2 Partition 2 on First unit - ... - 15 = /dev/emd/0p15 Partition 15 on First unit - - 16 = /dev/emd/1 Second unit - 32 = /dev/emd/2 Third unit - ... - 240 = /dev/emd/15 Sixteenth unit - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 154 char Specialix RIO serial card - 0 = /dev/ttySR0 First RIO port - ... - 255 = /dev/ttySR255 256th RIO port - - 155 char Specialix RIO serial card - alternate devices - 0 = /dev/cusr0 Callout device for ttySR0 - ... - 255 = /dev/cusr255 Callout device for ttySR255 - - 156 char Specialix RIO serial card - 0 = /dev/ttySR256 257th RIO port - ... - 255 = /dev/ttySR511 512th RIO port - - 157 char Specialix RIO serial card - alternate devices - 0 = /dev/cusr256 Callout device for ttySR256 - ... - 255 = /dev/cusr511 Callout device for ttySR511 - - 158 char Dialogic GammaLink fax driver - 0 = /dev/gfax0 GammaLink channel 0 - 1 = /dev/gfax1 GammaLink channel 1 - ... - - 159 char RESERVED - - 159 block RESERVED - - 160 char General Purpose Instrument Bus (GPIB) - 0 = /dev/gpib0 First GPIB bus - 1 = /dev/gpib1 Second GPIB bus - ... - - 160 block Carmel 8-port SATA Disks on First Controller - 0 = /dev/carmel/0 SATA disk 0 whole disk - 1 = /dev/carmel/0p1 SATA disk 0 partition 1 - ... - 31 = /dev/carmel/0p31 SATA disk 0 partition 31 - - 32 = /dev/carmel/1 SATA disk 1 whole disk - 64 = /dev/carmel/2 SATA disk 2 whole disk - ... - 224 = /dev/carmel/7 SATA disk 7 whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 31. - - 161 char IrCOMM devices (IrDA serial/parallel emulation) - 0 = /dev/ircomm0 First IrCOMM device - 1 = /dev/ircomm1 Second IrCOMM device - ... - 16 = /dev/irlpt0 First IrLPT device - 17 = /dev/irlpt1 Second IrLPT device - ... - - 161 block Carmel 8-port SATA Disks on Second Controller - 0 = /dev/carmel/8 SATA disk 8 whole disk - 1 = /dev/carmel/8p1 SATA disk 8 partition 1 - ... - 31 = /dev/carmel/8p31 SATA disk 8 partition 31 - - 32 = /dev/carmel/9 SATA disk 9 whole disk - 64 = /dev/carmel/10 SATA disk 10 whole disk - ... - 224 = /dev/carmel/15 SATA disk 15 whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 31. - - 162 char Raw block device interface - 0 = /dev/rawctl Raw I/O control device - 1 = /dev/raw/raw1 First raw I/O device - 2 = /dev/raw/raw2 Second raw I/O device - ... - max minor number of raw device is set by kernel config - MAX_RAW_DEVS or raw module parameter 'max_raw_devs' - - 163 char - - 164 char Chase Research AT/PCI-Fast serial card - 0 = /dev/ttyCH0 AT/PCI-Fast board 0, port 0 - ... - 15 = /dev/ttyCH15 AT/PCI-Fast board 0, port 15 - 16 = /dev/ttyCH16 AT/PCI-Fast board 1, port 0 - ... - 31 = /dev/ttyCH31 AT/PCI-Fast board 1, port 15 - 32 = /dev/ttyCH32 AT/PCI-Fast board 2, port 0 - ... - 47 = /dev/ttyCH47 AT/PCI-Fast board 2, port 15 - 48 = /dev/ttyCH48 AT/PCI-Fast board 3, port 0 - ... - 63 = /dev/ttyCH63 AT/PCI-Fast board 3, port 15 - - 165 char Chase Research AT/PCI-Fast serial card - alternate devices - 0 = /dev/cuch0 Callout device for ttyCH0 - ... - 63 = /dev/cuch63 Callout device for ttyCH63 - - 166 char ACM USB modems - 0 = /dev/ttyACM0 First ACM modem - 1 = /dev/ttyACM1 Second ACM modem - ... - - 167 char ACM USB modems - alternate devices - 0 = /dev/cuacm0 Callout device for ttyACM0 - 1 = /dev/cuacm1 Callout device for ttyACM1 - ... - - 168 char Eracom CSA7000 PCI encryption adaptor - 0 = /dev/ecsa0 First CSA7000 - 1 = /dev/ecsa1 Second CSA7000 - ... - - 169 char Eracom CSA8000 PCI encryption adaptor - 0 = /dev/ecsa8-0 First CSA8000 - 1 = /dev/ecsa8-1 Second CSA8000 - ... - - 170 char AMI MegaRAC remote access controller - 0 = /dev/megarac0 First MegaRAC card - 1 = /dev/megarac1 Second MegaRAC card - ... - - 171 char Reserved for IEEE 1394 (Firewire) - - 172 char Moxa Intellio serial card - 0 = /dev/ttyMX0 First Moxa port - 1 = /dev/ttyMX1 Second Moxa port - ... - 127 = /dev/ttyMX127 128th Moxa port - 128 = /dev/moxactl Moxa control port - - 173 char Moxa Intellio serial card - alternate devices - 0 = /dev/cumx0 Callout device for ttyMX0 - 1 = /dev/cumx1 Callout device for ttyMX1 - ... - 127 = /dev/cumx127 Callout device for ttyMX127 - - 174 char SmartIO serial card - 0 = /dev/ttySI0 First SmartIO port - 1 = /dev/ttySI1 Second SmartIO port - ... - - 175 char SmartIO serial card - alternate devices - 0 = /dev/cusi0 Callout device for ttySI0 - 1 = /dev/cusi1 Callout device for ttySI1 - ... - - 176 char nCipher nFast PCI crypto accelerator - 0 = /dev/nfastpci0 First nFast PCI device - 1 = /dev/nfastpci1 First nFast PCI device - ... - - 177 char TI PCILynx memory spaces - 0 = /dev/pcilynx/aux0 AUX space of first PCILynx card - ... - 15 = /dev/pcilynx/aux15 AUX space of 16th PCILynx card - 16 = /dev/pcilynx/rom0 ROM space of first PCILynx card - ... - 31 = /dev/pcilynx/rom15 ROM space of 16th PCILynx card - 32 = /dev/pcilynx/ram0 RAM space of first PCILynx card - ... - 47 = /dev/pcilynx/ram15 RAM space of 16th PCILynx card - - 178 char Giganet cLAN1xxx virtual interface adapter - 0 = /dev/clanvi0 First cLAN adapter - 1 = /dev/clanvi1 Second cLAN adapter - ... - - 179 block MMC block devices - 0 = /dev/mmcblk0 First SD/MMC card - 1 = /dev/mmcblk0p1 First partition on first MMC card - 8 = /dev/mmcblk1 Second SD/MMC card - ... - - The start of next SD/MMC card can be configured with - CONFIG_MMC_BLOCK_MINORS, or overridden at boot/modprobe - time using the mmcblk.perdev_minors option. That would - bump the offset between each card to be the configured - value instead of the default 8. - - 179 char CCube DVXChip-based PCI products - 0 = /dev/dvxirq0 First DVX device - 1 = /dev/dvxirq1 Second DVX device - ... - - 180 char USB devices - 0 = /dev/usb/lp0 First USB printer - ... - 15 = /dev/usb/lp15 16th USB printer - 48 = /dev/usb/scanner0 First USB scanner - ... - 63 = /dev/usb/scanner15 16th USB scanner - 64 = /dev/usb/rio500 Diamond Rio 500 - 65 = /dev/usb/usblcd USBLCD Interface (info@usblcd.de) - 66 = /dev/usb/cpad0 Synaptics cPad (mouse/LCD) - 96 = /dev/usb/hiddev0 1st USB HID device - ... - 111 = /dev/usb/hiddev15 16th USB HID device - 112 = /dev/usb/auer0 1st auerswald ISDN device - ... - 127 = /dev/usb/auer15 16th auerswald ISDN device - 128 = /dev/usb/brlvgr0 First Braille Voyager device - ... - 131 = /dev/usb/brlvgr3 Fourth Braille Voyager device - 132 = /dev/usb/idmouse ID Mouse (fingerprint scanner) device - 133 = /dev/usb/sisusbvga1 First SiSUSB VGA device - ... - 140 = /dev/usb/sisusbvga8 Eighth SISUSB VGA device - 144 = /dev/usb/lcd USB LCD device - 160 = /dev/usb/legousbtower0 1st USB Legotower device - ... - 175 = /dev/usb/legousbtower15 16th USB Legotower device - 176 = /dev/usb/usbtmc1 First USB TMC device - ... - 191 = /dev/usb/usbtmc16 16th USB TMC device - 192 = /dev/usb/yurex1 First USB Yurex device - ... - 209 = /dev/usb/yurex16 16th USB Yurex device - - 180 block USB block devices - 0 = /dev/uba First USB block device - 8 = /dev/ubb Second USB block device - 16 = /dev/ubc Third USB block device - ... - - 181 char Conrad Electronic parallel port radio clocks - 0 = /dev/pcfclock0 First Conrad radio clock - 1 = /dev/pcfclock1 Second Conrad radio clock - ... - - 182 char Picture Elements THR2 binarizer - 0 = /dev/pethr0 First THR2 board - 1 = /dev/pethr1 Second THR2 board - ... - - 183 char SST 5136-DN DeviceNet interface - 0 = /dev/ss5136dn0 First DeviceNet interface - 1 = /dev/ss5136dn1 Second DeviceNet interface - ... - - This device used to be assigned to major number 144. - It had to be moved due to an unfortunate conflict. - - 184 char Picture Elements' video simulator/sender - 0 = /dev/pevss0 First sender board - 1 = /dev/pevss1 Second sender board - ... - - 185 char InterMezzo high availability file system - 0 = /dev/intermezzo0 First cache manager - 1 = /dev/intermezzo1 Second cache manager - ... - - See http://web.archive.org/web/20080115195241/ - http://inter-mezzo.org/index.html - - 186 char Object-based storage control device - 0 = /dev/obd0 First obd control device - 1 = /dev/obd1 Second obd control device - ... - - See ftp://ftp.lustre.org/pub/obd for code and information. - - 187 char DESkey hardware encryption device - 0 = /dev/deskey0 First DES key - 1 = /dev/deskey1 Second DES key - ... - - 188 char USB serial converters - 0 = /dev/ttyUSB0 First USB serial converter - 1 = /dev/ttyUSB1 Second USB serial converter - ... - - 189 char USB serial converters - alternate devices - 0 = /dev/cuusb0 Callout device for ttyUSB0 - 1 = /dev/cuusb1 Callout device for ttyUSB1 - ... - - 190 char Kansas City tracker/tuner card - 0 = /dev/kctt0 First KCT/T card - 1 = /dev/kctt1 Second KCT/T card - ... - - 191 char Reserved for PCMCIA - - 192 char Kernel profiling interface - 0 = /dev/profile Profiling control device - 1 = /dev/profile0 Profiling device for CPU 0 - 2 = /dev/profile1 Profiling device for CPU 1 - ... - - 193 char Kernel event-tracing interface - 0 = /dev/trace Tracing control device - 1 = /dev/trace0 Tracing device for CPU 0 - 2 = /dev/trace1 Tracing device for CPU 1 - ... - - 194 char linVideoStreams (LINVS) - 0 = /dev/mvideo/status0 Video compression status - 1 = /dev/mvideo/stream0 Video stream - 2 = /dev/mvideo/frame0 Single compressed frame - 3 = /dev/mvideo/rawframe0 Raw uncompressed frame - 4 = /dev/mvideo/codec0 Direct codec access - 5 = /dev/mvideo/video4linux0 Video4Linux compatibility - - 16 = /dev/mvideo/status1 Second device - ... - 32 = /dev/mvideo/status2 Third device - ... - ... - 240 = /dev/mvideo/status15 16th device - ... - - 195 char Nvidia graphics devices - 0 = /dev/nvidia0 First Nvidia card - 1 = /dev/nvidia1 Second Nvidia card - ... - 255 = /dev/nvidiactl Nvidia card control device - - 196 char Tormenta T1 card - 0 = /dev/tor/0 Master control channel for all cards - 1 = /dev/tor/1 First DS0 - 2 = /dev/tor/2 Second DS0 - ... - 48 = /dev/tor/48 48th DS0 - 49 = /dev/tor/49 First pseudo-channel - 50 = /dev/tor/50 Second pseudo-channel - ... - - 197 char OpenTNF tracing facility - 0 = /dev/tnf/t0 Trace 0 data extraction - 1 = /dev/tnf/t1 Trace 1 data extraction - ... - 128 = /dev/tnf/status Tracing facility status - 130 = /dev/tnf/trace Tracing device - - 198 char Total Impact TPMP2 quad coprocessor PCI card - 0 = /dev/tpmp2/0 First card - 1 = /dev/tpmp2/1 Second card - ... - - 199 char Veritas volume manager (VxVM) volumes - 0 = /dev/vx/rdsk/*/* First volume - 1 = /dev/vx/rdsk/*/* Second volume - ... - - 199 block Veritas volume manager (VxVM) volumes - 0 = /dev/vx/dsk/*/* First volume - 1 = /dev/vx/dsk/*/* Second volume - ... - - The namespace in these directories is maintained by - the user space VxVM software. - - 200 char Veritas VxVM configuration interface - 0 = /dev/vx/config Configuration access node - 1 = /dev/vx/trace Volume i/o trace access node - 2 = /dev/vx/iod Volume i/o daemon access node - 3 = /dev/vx/info Volume information access node - 4 = /dev/vx/task Volume tasks access node - 5 = /dev/vx/taskmon Volume tasks monitor daemon - - 201 char Veritas VxVM dynamic multipathing driver - 0 = /dev/vx/rdmp/* First multipath device - 1 = /dev/vx/rdmp/* Second multipath device - ... - 201 block Veritas VxVM dynamic multipathing driver - 0 = /dev/vx/dmp/* First multipath device - 1 = /dev/vx/dmp/* Second multipath device - ... - - The namespace in these directories is maintained by - the user space VxVM software. - - 202 char CPU model-specific registers - 0 = /dev/cpu/0/msr MSRs on CPU 0 - 1 = /dev/cpu/1/msr MSRs on CPU 1 - ... - - 202 block Xen Virtual Block Device - 0 = /dev/xvda First Xen VBD whole disk - 16 = /dev/xvdb Second Xen VBD whole disk - 32 = /dev/xvdc Third Xen VBD whole disk - ... - 240 = /dev/xvdp Sixteenth Xen VBD whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 203 char CPU CPUID information - 0 = /dev/cpu/0/cpuid CPUID on CPU 0 - 1 = /dev/cpu/1/cpuid CPUID on CPU 1 - ... - - 204 char Low-density serial ports - 0 = /dev/ttyLU0 LinkUp Systems L72xx UART - port 0 - 1 = /dev/ttyLU1 LinkUp Systems L72xx UART - port 1 - 2 = /dev/ttyLU2 LinkUp Systems L72xx UART - port 2 - 3 = /dev/ttyLU3 LinkUp Systems L72xx UART - port 3 - 4 = /dev/ttyFB0 Intel Footbridge (ARM) - 5 = /dev/ttySA0 StrongARM builtin serial port 0 - 6 = /dev/ttySA1 StrongARM builtin serial port 1 - 7 = /dev/ttySA2 StrongARM builtin serial port 2 - 8 = /dev/ttySC0 SCI serial port (SuperH) - port 0 - 9 = /dev/ttySC1 SCI serial port (SuperH) - port 1 - 10 = /dev/ttySC2 SCI serial port (SuperH) - port 2 - 11 = /dev/ttySC3 SCI serial port (SuperH) - port 3 - 12 = /dev/ttyFW0 Firmware console - port 0 - 13 = /dev/ttyFW1 Firmware console - port 1 - 14 = /dev/ttyFW2 Firmware console - port 2 - 15 = /dev/ttyFW3 Firmware console - port 3 - 16 = /dev/ttyAM0 ARM "AMBA" serial port 0 - ... - 31 = /dev/ttyAM15 ARM "AMBA" serial port 15 - 32 = /dev/ttyDB0 DataBooster serial port 0 - ... - 39 = /dev/ttyDB7 DataBooster serial port 7 - 40 = /dev/ttySG0 SGI Altix console port - 41 = /dev/ttySMX0 Motorola i.MX - port 0 - 42 = /dev/ttySMX1 Motorola i.MX - port 1 - 43 = /dev/ttySMX2 Motorola i.MX - port 2 - 44 = /dev/ttyMM0 Marvell MPSC - port 0 - 45 = /dev/ttyMM1 Marvell MPSC - port 1 - 46 = /dev/ttyCPM0 PPC CPM (SCC or SMC) - port 0 - ... - 47 = /dev/ttyCPM5 PPC CPM (SCC or SMC) - port 5 - 50 = /dev/ttyIOC0 Altix serial card - ... - 81 = /dev/ttyIOC31 Altix serial card - 82 = /dev/ttyVR0 NEC VR4100 series SIU - 83 = /dev/ttyVR1 NEC VR4100 series DSIU - 84 = /dev/ttyIOC84 Altix ioc4 serial card - ... - 115 = /dev/ttyIOC115 Altix ioc4 serial card - 116 = /dev/ttySIOC0 Altix ioc3 serial card - ... - 147 = /dev/ttySIOC31 Altix ioc3 serial card - 148 = /dev/ttyPSC0 PPC PSC - port 0 - ... - 153 = /dev/ttyPSC5 PPC PSC - port 5 - 154 = /dev/ttyAT0 ATMEL serial port 0 - ... - 169 = /dev/ttyAT15 ATMEL serial port 15 - 170 = /dev/ttyNX0 Hilscher netX serial port 0 - ... - 185 = /dev/ttyNX15 Hilscher netX serial port 15 - 186 = /dev/ttyJ0 JTAG1 DCC protocol based serial port emulation - 187 = /dev/ttyUL0 Xilinx uartlite - port 0 - ... - 190 = /dev/ttyUL3 Xilinx uartlite - port 3 - 191 = /dev/xvc0 Xen virtual console - port 0 - 192 = /dev/ttyPZ0 pmac_zilog - port 0 - ... - 195 = /dev/ttyPZ3 pmac_zilog - port 3 - 196 = /dev/ttyTX0 TX39/49 serial port 0 - ... - 204 = /dev/ttyTX7 TX39/49 serial port 7 - 205 = /dev/ttySC0 SC26xx serial port 0 - 206 = /dev/ttySC1 SC26xx serial port 1 - 207 = /dev/ttySC2 SC26xx serial port 2 - 208 = /dev/ttySC3 SC26xx serial port 3 - 209 = /dev/ttyMAX0 MAX3100 serial port 0 - 210 = /dev/ttyMAX1 MAX3100 serial port 1 - 211 = /dev/ttyMAX2 MAX3100 serial port 2 - 212 = /dev/ttyMAX3 MAX3100 serial port 3 - - 205 char Low-density serial ports (alternate device) - 0 = /dev/culu0 Callout device for ttyLU0 - 1 = /dev/culu1 Callout device for ttyLU1 - 2 = /dev/culu2 Callout device for ttyLU2 - 3 = /dev/culu3 Callout device for ttyLU3 - 4 = /dev/cufb0 Callout device for ttyFB0 - 5 = /dev/cusa0 Callout device for ttySA0 - 6 = /dev/cusa1 Callout device for ttySA1 - 7 = /dev/cusa2 Callout device for ttySA2 - 8 = /dev/cusc0 Callout device for ttySC0 - 9 = /dev/cusc1 Callout device for ttySC1 - 10 = /dev/cusc2 Callout device for ttySC2 - 11 = /dev/cusc3 Callout device for ttySC3 - 12 = /dev/cufw0 Callout device for ttyFW0 - 13 = /dev/cufw1 Callout device for ttyFW1 - 14 = /dev/cufw2 Callout device for ttyFW2 - 15 = /dev/cufw3 Callout device for ttyFW3 - 16 = /dev/cuam0 Callout device for ttyAM0 - ... - 31 = /dev/cuam15 Callout device for ttyAM15 - 32 = /dev/cudb0 Callout device for ttyDB0 - ... - 39 = /dev/cudb7 Callout device for ttyDB7 - 40 = /dev/cusg0 Callout device for ttySG0 - 41 = /dev/ttycusmx0 Callout device for ttySMX0 - 42 = /dev/ttycusmx1 Callout device for ttySMX1 - 43 = /dev/ttycusmx2 Callout device for ttySMX2 - 46 = /dev/cucpm0 Callout device for ttyCPM0 - ... - 49 = /dev/cucpm5 Callout device for ttyCPM5 - 50 = /dev/cuioc40 Callout device for ttyIOC40 - ... - 81 = /dev/cuioc431 Callout device for ttyIOC431 - 82 = /dev/cuvr0 Callout device for ttyVR0 - 83 = /dev/cuvr1 Callout device for ttyVR1 - - 206 char OnStream SC-x0 tape devices - 0 = /dev/osst0 First OnStream SCSI tape, mode 0 - 1 = /dev/osst1 Second OnStream SCSI tape, mode 0 - ... - 32 = /dev/osst0l First OnStream SCSI tape, mode 1 - 33 = /dev/osst1l Second OnStream SCSI tape, mode 1 - ... - 64 = /dev/osst0m First OnStream SCSI tape, mode 2 - 65 = /dev/osst1m Second OnStream SCSI tape, mode 2 - ... - 96 = /dev/osst0a First OnStream SCSI tape, mode 3 - 97 = /dev/osst1a Second OnStream SCSI tape, mode 3 - ... - 128 = /dev/nosst0 No rewind version of /dev/osst0 - 129 = /dev/nosst1 No rewind version of /dev/osst1 - ... - 160 = /dev/nosst0l No rewind version of /dev/osst0l - 161 = /dev/nosst1l No rewind version of /dev/osst1l - ... - 192 = /dev/nosst0m No rewind version of /dev/osst0m - 193 = /dev/nosst1m No rewind version of /dev/osst1m - ... - 224 = /dev/nosst0a No rewind version of /dev/osst0a - 225 = /dev/nosst1a No rewind version of /dev/osst1a - ... - - The OnStream SC-x0 SCSI tapes do not support the - standard SCSI SASD command set and therefore need - their own driver "osst". Note that the IDE, USB (and - maybe ParPort) versions may be driven via ide-scsi or - usb-storage SCSI emulation and this osst device and - driver as well. The ADR-x0 drives are QIC-157 - compliant and don't need osst. - - 207 char Compaq ProLiant health feature indicate - 0 = /dev/cpqhealth/cpqw Redirector interface - 1 = /dev/cpqhealth/crom EISA CROM - 2 = /dev/cpqhealth/cdt Data Table - 3 = /dev/cpqhealth/cevt Event Log - 4 = /dev/cpqhealth/casr Automatic Server Recovery - 5 = /dev/cpqhealth/cecc ECC Memory - 6 = /dev/cpqhealth/cmca Machine Check Architecture - 7 = /dev/cpqhealth/ccsm Deprecated CDT - 8 = /dev/cpqhealth/cnmi NMI Handling - 9 = /dev/cpqhealth/css Sideshow Management - 10 = /dev/cpqhealth/cram CMOS interface - 11 = /dev/cpqhealth/cpci PCI IRQ interface - - 208 char User space serial ports - 0 = /dev/ttyU0 First user space serial port - 1 = /dev/ttyU1 Second user space serial port - ... - - 209 char User space serial ports (alternate devices) - 0 = /dev/cuu0 Callout device for ttyU0 - 1 = /dev/cuu1 Callout device for ttyU1 - ... - - 210 char SBE, Inc. sync/async serial card - 0 = /dev/sbei/wxcfg0 Configuration device for board 0 - 1 = /dev/sbei/dld0 Download device for board 0 - 2 = /dev/sbei/wan00 WAN device, port 0, board 0 - 3 = /dev/sbei/wan01 WAN device, port 1, board 0 - 4 = /dev/sbei/wan02 WAN device, port 2, board 0 - 5 = /dev/sbei/wan03 WAN device, port 3, board 0 - 6 = /dev/sbei/wanc00 WAN clone device, port 0, board 0 - 7 = /dev/sbei/wanc01 WAN clone device, port 1, board 0 - 8 = /dev/sbei/wanc02 WAN clone device, port 2, board 0 - 9 = /dev/sbei/wanc03 WAN clone device, port 3, board 0 - 10 = /dev/sbei/wxcfg1 Configuration device for board 1 - 11 = /dev/sbei/dld1 Download device for board 1 - 12 = /dev/sbei/wan10 WAN device, port 0, board 1 - 13 = /dev/sbei/wan11 WAN device, port 1, board 1 - 14 = /dev/sbei/wan12 WAN device, port 2, board 1 - 15 = /dev/sbei/wan13 WAN device, port 3, board 1 - 16 = /dev/sbei/wanc10 WAN clone device, port 0, board 1 - 17 = /dev/sbei/wanc11 WAN clone device, port 1, board 1 - 18 = /dev/sbei/wanc12 WAN clone device, port 2, board 1 - 19 = /dev/sbei/wanc13 WAN clone device, port 3, board 1 - ... - - Yes, each board is really spaced 10 (decimal) apart. - - 211 char Addinum CPCI1500 digital I/O card - 0 = /dev/addinum/cpci1500/0 First CPCI1500 card - 1 = /dev/addinum/cpci1500/1 Second CPCI1500 card - ... - - 212 char LinuxTV.org DVB driver subsystem - 0 = /dev/dvb/adapter0/video0 first video decoder of first card - 1 = /dev/dvb/adapter0/audio0 first audio decoder of first card - 2 = /dev/dvb/adapter0/sec0 (obsolete/unused) - 3 = /dev/dvb/adapter0/frontend0 first frontend device of first card - 4 = /dev/dvb/adapter0/demux0 first demux device of first card - 5 = /dev/dvb/adapter0/dvr0 first digital video recoder device of first card - 6 = /dev/dvb/adapter0/ca0 first common access port of first card - 7 = /dev/dvb/adapter0/net0 first network device of first card - 8 = /dev/dvb/adapter0/osd0 first on-screen-display device of first card - 9 = /dev/dvb/adapter0/video1 second video decoder of first card - ... - 64 = /dev/dvb/adapter1/video0 first video decoder of second card - ... - 128 = /dev/dvb/adapter2/video0 first video decoder of third card - ... - 196 = /dev/dvb/adapter3/video0 first video decoder of fourth card - - 216 char Bluetooth RFCOMM TTY devices - 0 = /dev/rfcomm0 First Bluetooth RFCOMM TTY device - 1 = /dev/rfcomm1 Second Bluetooth RFCOMM TTY device - ... - - 217 char Bluetooth RFCOMM TTY devices (alternate devices) - 0 = /dev/curf0 Callout device for rfcomm0 - 1 = /dev/curf1 Callout device for rfcomm1 - ... - - 218 char The Logical Company bus Unibus/Qbus adapters - 0 = /dev/logicalco/bci/0 First bus adapter - 1 = /dev/logicalco/bci/1 First bus adapter - ... - - 219 char The Logical Company DCI-1300 digital I/O card - 0 = /dev/logicalco/dci1300/0 First DCI-1300 card - 1 = /dev/logicalco/dci1300/1 Second DCI-1300 card - ... - - 220 char Myricom Myrinet "GM" board - 0 = /dev/myricom/gm0 First Myrinet GM board - 1 = /dev/myricom/gmp0 First board "root access" - 2 = /dev/myricom/gm1 Second Myrinet GM board - 3 = /dev/myricom/gmp1 Second board "root access" - ... - - 221 char VME bus - 0 = /dev/bus/vme/m0 First master image - 1 = /dev/bus/vme/m1 Second master image - 2 = /dev/bus/vme/m2 Third master image - 3 = /dev/bus/vme/m3 Fourth master image - 4 = /dev/bus/vme/s0 First slave image - 5 = /dev/bus/vme/s1 Second slave image - 6 = /dev/bus/vme/s2 Third slave image - 7 = /dev/bus/vme/s3 Fourth slave image - 8 = /dev/bus/vme/ctl Control - - It is expected that all VME bus drivers will use the - same interface. For interface documentation see - http://www.vmelinux.org/. - - 224 char A2232 serial card - 0 = /dev/ttyY0 First A2232 port - 1 = /dev/ttyY1 Second A2232 port - ... - - 225 char A2232 serial card (alternate devices) - 0 = /dev/cuy0 Callout device for ttyY0 - 1 = /dev/cuy1 Callout device for ttyY1 - ... - - 226 char Direct Rendering Infrastructure (DRI) - 0 = /dev/dri/card0 First graphics card - 1 = /dev/dri/card1 Second graphics card - ... - - 227 char IBM 3270 terminal Unix tty access - 1 = /dev/3270/tty1 First 3270 terminal - 2 = /dev/3270/tty2 Seconds 3270 terminal - ... - - 228 char IBM 3270 terminal block-mode access - 0 = /dev/3270/tub Controlling interface - 1 = /dev/3270/tub1 First 3270 terminal - 2 = /dev/3270/tub2 Second 3270 terminal - ... - - 229 char IBM iSeries/pSeries virtual console - 0 = /dev/hvc0 First console port - 1 = /dev/hvc1 Second console port - ... - - 230 char IBM iSeries virtual tape - 0 = /dev/iseries/vt0 First virtual tape, mode 0 - 1 = /dev/iseries/vt1 Second virtual tape, mode 0 - ... - 32 = /dev/iseries/vt0l First virtual tape, mode 1 - 33 = /dev/iseries/vt1l Second virtual tape, mode 1 - ... - 64 = /dev/iseries/vt0m First virtual tape, mode 2 - 65 = /dev/iseries/vt1m Second virtual tape, mode 2 - ... - 96 = /dev/iseries/vt0a First virtual tape, mode 3 - 97 = /dev/iseries/vt1a Second virtual tape, mode 3 - ... - 128 = /dev/iseries/nvt0 First virtual tape, mode 0, no rewind - 129 = /dev/iseries/nvt1 Second virtual tape, mode 0, no rewind - ... - 160 = /dev/iseries/nvt0l First virtual tape, mode 1, no rewind - 161 = /dev/iseries/nvt1l Second virtual tape, mode 1, no rewind - ... - 192 = /dev/iseries/nvt0m First virtual tape, mode 2, no rewind - 193 = /dev/iseries/nvt1m Second virtual tape, mode 2, no rewind - ... - 224 = /dev/iseries/nvt0a First virtual tape, mode 3, no rewind - 225 = /dev/iseries/nvt1a Second virtual tape, mode 3, no rewind - ... - - "No rewind" refers to the omission of the default - automatic rewind on device close. The MTREW or MTOFFL - ioctl()'s can be used to rewind the tape regardless of - the device used to access it. - - 231 char InfiniBand - 0 = /dev/infiniband/umad0 - 1 = /dev/infiniband/umad1 - ... - 63 = /dev/infiniband/umad63 63rd InfiniBandMad device - 64 = /dev/infiniband/issm0 First InfiniBand IsSM device - 65 = /dev/infiniband/issm1 Second InfiniBand IsSM device - ... - 127 = /dev/infiniband/issm63 63rd InfiniBand IsSM device - 128 = /dev/infiniband/uverbs0 First InfiniBand verbs device - 129 = /dev/infiniband/uverbs1 Second InfiniBand verbs device - ... - 159 = /dev/infiniband/uverbs31 31st InfiniBand verbs device - - 232 char Biometric Devices - 0 = /dev/biometric/sensor0/fingerprint first fingerprint sensor on first device - 1 = /dev/biometric/sensor0/iris first iris sensor on first device - 2 = /dev/biometric/sensor0/retina first retina sensor on first device - 3 = /dev/biometric/sensor0/voiceprint first voiceprint sensor on first device - 4 = /dev/biometric/sensor0/facial first facial sensor on first device - 5 = /dev/biometric/sensor0/hand first hand sensor on first device - ... - 10 = /dev/biometric/sensor1/fingerprint first fingerprint sensor on second device - ... - 20 = /dev/biometric/sensor2/fingerprint first fingerprint sensor on third device - ... - - 233 char PathScale InfiniPath interconnect - 0 = /dev/ipath Primary device for programs (any unit) - 1 = /dev/ipath0 Access specifically to unit 0 - 2 = /dev/ipath1 Access specifically to unit 1 - ... - 4 = /dev/ipath3 Access specifically to unit 3 - 129 = /dev/ipath_sma Device used by Subnet Management Agent - 130 = /dev/ipath_diag Device used by diagnostics programs - - 234-254 char RESERVED FOR DYNAMIC ASSIGNMENT - Character devices that request a dynamic allocation of major number will - take numbers starting from 254 and downward. - - 240-254 block LOCAL/EXPERIMENTAL USE - Allocated for local/experimental use. For devices not - assigned official numbers, these ranges should be - used in order to avoid conflicting with future assignments. - - 255 char RESERVED - - 255 block RESERVED - - This major is reserved to assist the expansion to a - larger number space. No device nodes with this major - should ever be created on the filesystem. - (This is probably not true anymore, but I'll leave it - for now /Torben) - - ---LARGE MAJORS!!!!!--- - - 256 char Equinox SST multi-port serial boards - 0 = /dev/ttyEQ0 First serial port on first Equinox SST board - 127 = /dev/ttyEQ127 Last serial port on first Equinox SST board - 128 = /dev/ttyEQ128 First serial port on second Equinox SST board - ... - 1027 = /dev/ttyEQ1027 Last serial port on eighth Equinox SST board - - 256 block Resident Flash Disk Flash Translation Layer - 0 = /dev/rfda First RFD FTL layer - 16 = /dev/rfdb Second RFD FTL layer - ... - 240 = /dev/rfdp 16th RFD FTL layer - - 257 char Phoenix Technologies Cryptographic Services Driver - 0 = /dev/ptlsec Crypto Services Driver - - 257 block SSFDC Flash Translation Layer filesystem - 0 = /dev/ssfdca First SSFDC layer - 8 = /dev/ssfdcb Second SSFDC layer - 16 = /dev/ssfdcc Third SSFDC layer - 24 = /dev/ssfdcd 4th SSFDC layer - 32 = /dev/ssfdce 5th SSFDC layer - 40 = /dev/ssfdcf 6th SSFDC layer - 48 = /dev/ssfdcg 7th SSFDC layer - 56 = /dev/ssfdch 8th SSFDC layer - - 258 block ROM/Flash read-only translation layer - 0 = /dev/blockrom0 First ROM card's translation layer interface - 1 = /dev/blockrom1 Second ROM card's translation layer interface - ... - - 259 block Block Extended Major - Used dynamically to hold additional partition minor - numbers and allow large numbers of partitions per device - - 259 char FPGA configuration interfaces - 0 = /dev/icap0 First Xilinx internal configuration - 1 = /dev/icap1 Second Xilinx internal configuration - - 260 char OSD (Object-based-device) SCSI Device - 0 = /dev/osd0 First OSD Device - 1 = /dev/osd1 Second OSD Device - ... - 255 = /dev/osd255 256th OSD Device - - -Additional ``/dev/`` directory entries --------------------------------------- - -This section details additional entries that should or may exist in -the /dev directory. It is preferred that symbolic links use the same -form (absolute or relative) as is indicated here. Links are -classified as "hard" or "symbolic" depending on the preferred type of -link; if possible, the indicated type of link should be used. - -Compulsory links -++++++++++++++++ - -These links should exist on all systems: - -=============== =============== =============== =============================== -/dev/fd /proc/self/fd symbolic File descriptors -/dev/stdin fd/0 symbolic stdin file descriptor -/dev/stdout fd/1 symbolic stdout file descriptor -/dev/stderr fd/2 symbolic stderr file descriptor -/dev/nfsd socksys symbolic Required by iBCS-2 -/dev/X0R null symbolic Required by iBCS-2 -=============== =============== =============== =============================== - -Note: ``/dev/X0R`` is --. - -Recommended links -+++++++++++++++++ - -It is recommended that these links exist on all systems: - - -=============== =============== =============== =============================== -/dev/core /proc/kcore symbolic Backward compatibility -/dev/ramdisk ram0 symbolic Backward compatibility -/dev/ftape qft0 symbolic Backward compatibility -/dev/bttv0 video0 symbolic Backward compatibility -/dev/radio radio0 symbolic Backward compatibility -/dev/i2o* /dev/i2o/* symbolic Backward compatibility -/dev/scd? sr? hard Alternate SCSI CD-ROM name -=============== =============== =============== =============================== - -Locally defined links -+++++++++++++++++++++ - -The following links may be established locally to conform to the -configuration of the system. This is merely a tabulation of existing -practice, and does not constitute a recommendation. However, if they -exist, they should have the following uses. - -=============== =============== =============== =============================== -/dev/mouse mouse port symbolic Current mouse device -/dev/tape tape device symbolic Current tape device -/dev/cdrom CD-ROM device symbolic Current CD-ROM device -/dev/cdwriter CD-writer symbolic Current CD-writer device -/dev/scanner scanner symbolic Current scanner device -/dev/modem modem port symbolic Current dialout device -/dev/root root device symbolic Current root filesystem -/dev/swap swap device symbolic Current swap device -=============== =============== =============== =============================== - -``/dev/modem`` should not be used for a modem which supports dialin as -well as dialout, as it tends to cause lock file problems. If it -exists, ``/dev/modem`` should point to the appropriate primary TTY device -(the use of the alternate callout devices is deprecated). - -For SCSI devices, ``/dev/tape`` and ``/dev/cdrom`` should point to the -*cooked* devices (``/dev/st*`` and ``/dev/sr*``, respectively), whereas -``/dev/cdwriter`` and /dev/scanner should point to the appropriate generic -SCSI devices (/dev/sg*). - -``/dev/mouse`` may point to a primary serial TTY device, a hardware mouse -device, or a socket for a mouse driver program (e.g. ``/dev/gpmdata``). - -Sockets and pipes -+++++++++++++++++ - -Non-transient sockets and named pipes may exist in /dev. Common entries are: - -=============== =============== =============================================== -/dev/printer socket lpd local socket -/dev/log socket syslog local socket -/dev/gpmdata socket gpm mouse multiplexer -=============== =============== =============================================== - -Mount points -++++++++++++ - -The following names are reserved for mounting special filesystems -under /dev. These special filesystems provide kernel interfaces that -cannot be provided with standard device nodes. - -=============== =============== =============================================== -/dev/pts devpts PTY slave filesystem -/dev/shm tmpfs POSIX shared memory maintenance access -=============== =============== =============================================== - -Terminal devices ----------------- - -Terminal, or TTY devices are a special class of character devices. A -terminal device is any device that could act as a controlling terminal -for a session; this includes virtual consoles, serial ports, and -pseudoterminals (PTYs). - -All terminal devices share a common set of capabilities known as line -disciplines; these include the common terminal line discipline as well -as SLIP and PPP modes. - -All terminal devices are named similarly; this section explains the -naming and use of the various types of TTYs. Note that the naming -conventions include several historical warts; some of these are -Linux-specific, some were inherited from other systems, and some -reflect Linux outgrowing a borrowed convention. - -A hash mark (``#``) in a device name is used here to indicate a decimal -number without leading zeroes. - -Virtual consoles and the console device -+++++++++++++++++++++++++++++++++++++++ - -Virtual consoles are full-screen terminal displays on the system video -monitor. Virtual consoles are named ``/dev/tty#``, with numbering -starting at ``/dev/tty1``; ``/dev/tty0`` is the current virtual console. -``/dev/tty0`` is the device that should be used to access the system video -card on those architectures for which the frame buffer devices -(``/dev/fb*``) are not applicable. Do not use ``/dev/console`` -for this purpose. - -The console device, ``/dev/console``, is the device to which system -messages should be sent, and on which logins should be permitted in -single-user mode. Starting with Linux 2.1.71, ``/dev/console`` is managed -by the kernel; for previous versions it should be a symbolic link to -either ``/dev/tty0``, a specific virtual console such as ``/dev/tty1``, or to -a serial port primary (``tty*``, not ``cu*``) device, depending on the -configuration of the system. - -Serial ports -++++++++++++ - -Serial ports are RS-232 serial ports and any device which simulates -one, either in hardware (such as internal modems) or in software (such -as the ISDN driver.) Under Linux, each serial ports has two device -names, the primary or callin device and the alternate or callout one. -Each kind of device is indicated by a different letter. For any -letter X, the names of the devices are ``/dev/ttyX#`` and ``/dev/cux#``, -respectively; for historical reasons, ``/dev/ttyS#`` and ``/dev/ttyC#`` -correspond to ``/dev/cua#`` and ``/dev/cub#``. In the future, it should be -expected that multiple letters will be used; all letters will be upper -case for the "tty" device (e.g. ``/dev/ttyDP#``) and lower case for the -"cu" device (e.g. ``/dev/cudp#``). - -The names ``/dev/ttyQ#`` and ``/dev/cuq#`` are reserved for local use. - -The alternate devices provide for kernel-based exclusion and somewhat -different defaults than the primary devices. Their main purpose is to -allow the use of serial ports with programs with no inherent or broken -support for serial ports. Their use is deprecated, and they may be -removed from a future version of Linux. - -Arbitration of serial ports is provided by the use of lock files with -the names ``/var/lock/LCK..ttyX#``. The contents of the lock file should -be the PID of the locking process as an ASCII number. - -It is common practice to install links such as /dev/modem -which point to serial ports. In order to ensure proper locking in the -presence of these links, it is recommended that software chase -symlinks and lock all possible names; additionally, it is recommended -that a lock file be installed with the corresponding alternate -device. In order to avoid deadlocks, it is recommended that the locks -are acquired in the following order, and released in the reverse: - - 1. The symbolic link name, if any (``/var/lock/LCK..modem``) - 2. The "tty" name (``/var/lock/LCK..ttyS2``) - 3. The alternate device name (``/var/lock/LCK..cua2``) - -In the case of nested symbolic links, the lock files should be -installed in the order the symlinks are resolved. - -Under no circumstances should an application hold a lock while waiting -for another to be released. In addition, applications which attempt -to create lock files for the corresponding alternate device names -should take into account the possibility of being used on a non-serial -port TTY, for which no alternate device would exist. - -Pseudoterminals (PTYs) -++++++++++++++++++++++ - -Pseudoterminals, or PTYs, are used to create login sessions or provide -other capabilities requiring a TTY line discipline (including SLIP or -PPP capability) to arbitrary data-generation processes. Each PTY has -a master side, named ``/dev/pty[p-za-e][0-9a-f]``, and a slave side, named -``/dev/tty[p-za-e][0-9a-f]``. The kernel arbitrates the use of PTYs by -allowing each master side to be opened only once. - -Once the master side has been opened, the corresponding slave device -can be used in the same manner as any TTY device. The master and -slave devices are connected by the kernel, generating the equivalent -of a bidirectional pipe with TTY capabilities. - -Recent versions of the Linux kernels and GNU libc contain support for -the System V/Unix98 naming scheme for PTYs, which assigns a common -device, ``/dev/ptmx``, to all the masters (opening it will automatically -give you a previously unassigned PTY) and a subdirectory, ``/dev/pts``, -for the slaves; the slaves are named with decimal integers (``/dev/pts/#`` -in our notation). This removes the problem of exhausting the -namespace and enables the kernel to automatically create the device -nodes for the slaves on demand using the "devpts" filesystem. - diff --git a/Documentation/dynamic-debug-howto.txt b/Documentation/dynamic-debug-howto.txt deleted file mode 100644 index 88adcfdf5b2b..000000000000 --- a/Documentation/dynamic-debug-howto.txt +++ /dev/null @@ -1,353 +0,0 @@ -Dynamic debug -+++++++++++++ - - -Introduction -============ - -This document describes how to use the dynamic debug (dyndbg) feature. - -Dynamic debug is designed to allow you to dynamically enable/disable -kernel code to obtain additional kernel information. Currently, if -``CONFIG_DYNAMIC_DEBUG`` is set, then all ``pr_debug()``/``dev_dbg()`` and -``print_hex_dump_debug()``/``print_hex_dump_bytes()`` calls can be dynamically -enabled per-callsite. - -If ``CONFIG_DYNAMIC_DEBUG`` is not set, ``print_hex_dump_debug()`` is just -shortcut for ``print_hex_dump(KERN_DEBUG)``. - -For ``print_hex_dump_debug()``/``print_hex_dump_bytes()``, format string is -its ``prefix_str`` argument, if it is constant string; or ``hexdump`` -in case ``prefix_str`` is build dynamically. - -Dynamic debug has even more useful features: - - * Simple query language allows turning on and off debugging - statements by matching any combination of 0 or 1 of: - - - source filename - - function name - - line number (including ranges of line numbers) - - module name - - format string - - * Provides a debugfs control file: ``/dynamic_debug/control`` - which can be read to display the complete list of known debug - statements, to help guide you - -Controlling dynamic debug Behaviour -=================================== - -The behaviour of ``pr_debug()``/``dev_dbg()`` are controlled via writing to a -control file in the 'debugfs' filesystem. Thus, you must first mount -the debugfs filesystem, in order to make use of this feature. -Subsequently, we refer to the control file as: -``/dynamic_debug/control``. For example, if you want to enable -printing from source file ``svcsock.c``, line 1603 you simply do:: - - nullarbor:~ # echo 'file svcsock.c line 1603 +p' > - /dynamic_debug/control - -If you make a mistake with the syntax, the write will fail thus:: - - nullarbor:~ # echo 'file svcsock.c wtf 1 +p' > - /dynamic_debug/control - -bash: echo: write error: Invalid argument - -Viewing Dynamic Debug Behaviour -=============================== - -You can view the currently configured behaviour of all the debug -statements via:: - - nullarbor:~ # cat /dynamic_debug/control - # filename:lineno [module]function flags format - /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:323 [svcxprt_rdma]svc_rdma_cleanup =_ "SVCRDMA Module Removed, deregister RPC RDMA transport\012" - /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:341 [svcxprt_rdma]svc_rdma_init =_ "\011max_inline : %d\012" - /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:340 [svcxprt_rdma]svc_rdma_init =_ "\011sq_depth : %d\012" - /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svc_rdma.c:338 [svcxprt_rdma]svc_rdma_init =_ "\011max_requests : %d\012" - ... - - -You can also apply standard Unix text manipulation filters to this -data, e.g.:: - - nullarbor:~ # grep -i rdma /dynamic_debug/control | wc -l - 62 - - nullarbor:~ # grep -i tcp /dynamic_debug/control | wc -l - 42 - -The third column shows the currently enabled flags for each debug -statement callsite (see below for definitions of the flags). The -default value, with no flags enabled, is ``=_``. So you can view all -the debug statement callsites with any non-default flags:: - - nullarbor:~ # awk '$3 != "=_"' /dynamic_debug/control - # filename:lineno [module]function flags format - /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svcsock.c:1603 [sunrpc]svc_send p "svc_process: st_sendto returned %d\012" - -Command Language Reference -========================== - -At the lexical level, a command comprises a sequence of words separated -by spaces or tabs. So these are all equivalent:: - - nullarbor:~ # echo -c 'file svcsock.c line 1603 +p' > - /dynamic_debug/control - nullarbor:~ # echo -c ' file svcsock.c line 1603 +p ' > - /dynamic_debug/control - nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' > - /dynamic_debug/control - -Command submissions are bounded by a write() system call. -Multiple commands can be written together, separated by ``;`` or ``\n``:: - - ~# echo "func pnpacpi_get_resources +p; func pnp_assign_mem +p" \ - > /dynamic_debug/control - -If your query set is big, you can batch them too:: - - ~# cat query-batch-file > /dynamic_debug/control - -A another way is to use wildcard. The match rule support ``*`` (matches -zero or more characters) and ``?`` (matches exactly one character).For -example, you can match all usb drivers:: - - ~# echo "file drivers/usb/* +p" > /dynamic_debug/control - -At the syntactical level, a command comprises a sequence of match -specifications, followed by a flags change specification:: - - command ::= match-spec* flags-spec - -The match-spec's are used to choose a subset of the known pr_debug() -callsites to which to apply the flags-spec. Think of them as a query -with implicit ANDs between each pair. Note that an empty list of -match-specs will select all debug statement callsites. - -A match specification comprises a keyword, which controls the -attribute of the callsite to be compared, and a value to compare -against. Possible keywords are::: - - match-spec ::= 'func' string | - 'file' string | - 'module' string | - 'format' string | - 'line' line-range - - line-range ::= lineno | - '-'lineno | - lineno'-' | - lineno'-'lineno - - lineno ::= unsigned-int - -.. note:: - - ``line-range`` cannot contain space, e.g. - "1-30" is valid range but "1 - 30" is not. - - -The meanings of each keyword are: - -func - The given string is compared against the function name - of each callsite. Example:: - - func svc_tcp_accept - -file - The given string is compared against either the full pathname, the - src-root relative pathname, or the basename of the source file of - each callsite. Examples:: - - file svcsock.c - file kernel/freezer.c - file /usr/src/packages/BUILD/sgi-enhancednfs-1.4/default/net/sunrpc/svcsock.c - -module - The given string is compared against the module name - of each callsite. The module name is the string as - seen in ``lsmod``, i.e. without the directory or the ``.ko`` - suffix and with ``-`` changed to ``_``. Examples:: - - module sunrpc - module nfsd - -format - The given string is searched for in the dynamic debug format - string. Note that the string does not need to match the - entire format, only some part. Whitespace and other - special characters can be escaped using C octal character - escape ``\ooo`` notation, e.g. the space character is ``\040``. - Alternatively, the string can be enclosed in double quote - characters (``"``) or single quote characters (``'``). - Examples:: - - format svcrdma: // many of the NFS/RDMA server pr_debugs - format readahead // some pr_debugs in the readahead cache - format nfsd:\040SETATTR // one way to match a format with whitespace - format "nfsd: SETATTR" // a neater way to match a format with whitespace - format 'nfsd: SETATTR' // yet another way to match a format with whitespace - -line - The given line number or range of line numbers is compared - against the line number of each ``pr_debug()`` callsite. A single - line number matches the callsite line number exactly. A - range of line numbers matches any callsite between the first - and last line number inclusive. An empty first number means - the first line in the file, an empty line number means the - last number in the file. Examples:: - - line 1603 // exactly line 1603 - line 1600-1605 // the six lines from line 1600 to line 1605 - line -1605 // the 1605 lines from line 1 to line 1605 - line 1600- // all lines from line 1600 to the end of the file - -The flags specification comprises a change operation followed -by one or more flag characters. The change operation is one -of the characters:: - - - remove the given flags - + add the given flags - = set the flags to the given flags - -The flags are:: - - p enables the pr_debug() callsite. - f Include the function name in the printed message - l Include line number in the printed message - m Include module name in the printed message - t Include thread ID in messages not generated from interrupt context - _ No flags are set. (Or'd with others on input) - -For ``print_hex_dump_debug()`` and ``print_hex_dump_bytes()``, only ``p`` flag -have meaning, other flags ignored. - -For display, the flags are preceded by ``=`` -(mnemonic: what the flags are currently equal to). - -Note the regexp ``^[-+=][flmpt_]+$`` matches a flags specification. -To clear all flags at once, use ``=_`` or ``-flmpt``. - - -Debug messages during Boot Process -================================== - -To activate debug messages for core code and built-in modules during -the boot process, even before userspace and debugfs exists, use -``dyndbg="QUERY"``, ``module.dyndbg="QUERY"``, or ``ddebug_query="QUERY"`` -(``ddebug_query`` is obsoleted by ``dyndbg``, and deprecated). QUERY follows -the syntax described above, but must not exceed 1023 characters. Your -bootloader may impose lower limits. - -These ``dyndbg`` params are processed just after the ddebug tables are -processed, as part of the arch_initcall. Thus you can enable debug -messages in all code run after this arch_initcall via this boot -parameter. - -On an x86 system for example ACPI enablement is a subsys_initcall and:: - - dyndbg="file ec.c +p" - -will show early Embedded Controller transactions during ACPI setup if -your machine (typically a laptop) has an Embedded Controller. -PCI (or other devices) initialization also is a hot candidate for using -this boot parameter for debugging purposes. - -If ``foo`` module is not built-in, ``foo.dyndbg`` will still be processed at -boot time, without effect, but will be reprocessed when module is -loaded later. ``dyndbg_query=`` and bare ``dyndbg=`` are only processed at -boot. - - -Debug Messages at Module Initialization Time -============================================ - -When ``modprobe foo`` is called, modprobe scans ``/proc/cmdline`` for -``foo.params``, strips ``foo.``, and passes them to the kernel along with -params given in modprobe args or ``/etc/modprob.d/*.conf`` files, -in the following order: - -1. parameters given via ``/etc/modprobe.d/*.conf``:: - - options foo dyndbg=+pt - options foo dyndbg # defaults to +p - -2. ``foo.dyndbg`` as given in boot args, ``foo.`` is stripped and passed:: - - foo.dyndbg=" func bar +p; func buz +mp" - -3. args to modprobe:: - - modprobe foo dyndbg==pmf # override previous settings - -These ``dyndbg`` queries are applied in order, with last having final say. -This allows boot args to override or modify those from ``/etc/modprobe.d`` -(sensible, since 1 is system wide, 2 is kernel or boot specific), and -modprobe args to override both. - -In the ``foo.dyndbg="QUERY"`` form, the query must exclude ``module foo``. -``foo`` is extracted from the param-name, and applied to each query in -``QUERY``, and only 1 match-spec of each type is allowed. - -The ``dyndbg`` option is a "fake" module parameter, which means: - -- modules do not need to define it explicitly -- every module gets it tacitly, whether they use pr_debug or not -- it doesn't appear in ``/sys/module/$module/parameters/`` - To see it, grep the control file, or inspect ``/proc/cmdline.`` - -For ``CONFIG_DYNAMIC_DEBUG`` kernels, any settings given at boot-time (or -enabled by ``-DDEBUG`` flag during compilation) can be disabled later via -the sysfs interface if the debug messages are no longer needed:: - - echo "module module_name -p" > /dynamic_debug/control - -Examples -======== - -:: - - // enable the message at line 1603 of file svcsock.c - nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' > - /dynamic_debug/control - - // enable all the messages in file svcsock.c - nullarbor:~ # echo -n 'file svcsock.c +p' > - /dynamic_debug/control - - // enable all the messages in the NFS server module - nullarbor:~ # echo -n 'module nfsd +p' > - /dynamic_debug/control - - // enable all 12 messages in the function svc_process() - nullarbor:~ # echo -n 'func svc_process +p' > - /dynamic_debug/control - - // disable all 12 messages in the function svc_process() - nullarbor:~ # echo -n 'func svc_process -p' > - /dynamic_debug/control - - // enable messages for NFS calls READ, READLINK, READDIR and READDIR+. - nullarbor:~ # echo -n 'format "nfsd: READ" +p' > - /dynamic_debug/control - - // enable messages in files of which the paths include string "usb" - nullarbor:~ # echo -n '*usb* +p' > /dynamic_debug/control - - // enable all messages - nullarbor:~ # echo -n '+p' > /dynamic_debug/control - - // add module, function to all enabled messages - nullarbor:~ # echo -n '+mf' > /dynamic_debug/control - - // boot-args example, with newlines and comments for readability - Kernel command line: ... - // see whats going on in dyndbg=value processing - dynamic_debug.verbose=1 - // enable pr_debugs in 2 builtins, #cmt is stripped - dyndbg="module params +p #cmt ; module sys +p" - // enable pr_debugs in 2 functions in a module loaded later - pc87360.dyndbg="func pc87360_init_device +p; func pc87360_find +p" diff --git a/Documentation/index.rst b/Documentation/index.rst index e1f18b3db6e4..f6a3d4766495 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -11,6 +11,7 @@ Contents: .. toctree:: :maxdepth: 2 + admin-guide/index kernel-documentation process/index dev-tools/tools diff --git a/Documentation/init.txt b/Documentation/init.txt deleted file mode 100644 index e89d97f31eaf..000000000000 --- a/Documentation/init.txt +++ /dev/null @@ -1,52 +0,0 @@ -Explaining the dreaded "No init found." boot hang message -========================================================= - -OK, so you've got this pretty unintuitive message (currently located -in init/main.c) and are wondering what the H*** went wrong. -Some high-level reasons for failure (listed roughly in order of execution) -to load the init binary are: - -A) Unable to mount root FS -B) init binary doesn't exist on rootfs -C) broken console device -D) binary exists but dependencies not available -E) binary cannot be loaded - -Detailed explanations: - -A) Set "debug" kernel parameter (in bootloader config file or CONFIG_CMDLINE) - to get more detailed kernel messages. -B) make sure you have the correct root FS type - (and ``root=`` kernel parameter points to the correct partition), - required drivers such as storage hardware (such as SCSI or USB!) - and filesystem (ext3, jffs2 etc.) are builtin (alternatively as modules, - to be pre-loaded by an initrd) -C) Possibly a conflict in ``console= setup`` --> initial console unavailable. - E.g. some serial consoles are unreliable due to serial IRQ issues (e.g. - missing interrupt-based configuration). - Try using a different ``console= device`` or e.g. ``netconsole=``. -D) e.g. required library dependencies of the init binary such as - ``/lib/ld-linux.so.2`` missing or broken. Use - ``readelf -d |grep NEEDED`` to find out which libraries are required. -E) make sure the binary's architecture matches your hardware. - E.g. i386 vs. x86_64 mismatch, or trying to load x86 on ARM hardware. - In case you tried loading a non-binary file here (shell script?), - you should make sure that the script specifies an interpreter in its shebang - header line (``#!/...``) that is fully working (including its library - dependencies). And before tackling scripts, better first test a simple - non-script binary such as ``/bin/sh`` and confirm its successful execution. - To find out more, add code ``to init/main.c`` to display kernel_execve()s - return values. - -Please extend this explanation whenever you find new failure causes -(after all loading the init binary is a CRITICAL and hard transition step -which needs to be made as painless as possible), then submit patch to LKML. -Further TODOs: - -- Implement the various ``run_init_process()`` invocations via a struct array - which can then store the ``kernel_execve()`` result value and on failure - log it all by iterating over **all** results (very important usability fix). -- try to make the implementation itself more helpful in general, - e.g. by providing additional error messages at affected places. - -Andreas Mohr diff --git a/Documentation/initrd.txt b/Documentation/initrd.txt deleted file mode 100644 index a03dabaaf3a3..000000000000 --- a/Documentation/initrd.txt +++ /dev/null @@ -1,383 +0,0 @@ -Using the initial RAM disk (initrd) -=================================== - -Written 1996,2000 by Werner Almesberger and -Hans Lermen - - -initrd provides the capability to load a RAM disk by the boot loader. -This RAM disk can then be mounted as the root file system and programs -can be run from it. Afterwards, a new root file system can be mounted -from a different device. The previous root (from initrd) is then moved -to a directory and can be subsequently unmounted. - -initrd is mainly designed to allow system startup to occur in two phases, -where the kernel comes up with a minimum set of compiled-in drivers, and -where additional modules are loaded from initrd. - -This document gives a brief overview of the use of initrd. A more detailed -discussion of the boot process can be found in [#f1]_. - - -Operation ---------- - -When using initrd, the system typically boots as follows: - - 1) the boot loader loads the kernel and the initial RAM disk - 2) the kernel converts initrd into a "normal" RAM disk and - frees the memory used by initrd - 3) if the root device is not ``/dev/ram0``, the old (deprecated) - change_root procedure is followed. see the "Obsolete root change - mechanism" section below. - 4) root device is mounted. if it is ``/dev/ram0``, the initrd image is - then mounted as root - 5) /sbin/init is executed (this can be any valid executable, including - shell scripts; it is run with uid 0 and can do basically everything - init can do). - 6) init mounts the "real" root file system - 7) init places the root file system at the root directory using the - pivot_root system call - 8) init execs the ``/sbin/init`` on the new root filesystem, performing - the usual boot sequence - 9) the initrd file system is removed - -Note that changing the root directory does not involve unmounting it. -It is therefore possible to leave processes running on initrd during that -procedure. Also note that file systems mounted under initrd continue to -be accessible. - - -Boot command-line options -------------------------- - -initrd adds the following new options:: - - initrd= (e.g. LOADLIN) - - Loads the specified file as the initial RAM disk. When using LILO, you - have to specify the RAM disk image file in /etc/lilo.conf, using the - INITRD configuration variable. - - noinitrd - - initrd data is preserved but it is not converted to a RAM disk and - the "normal" root file system is mounted. initrd data can be read - from /dev/initrd. Note that the data in initrd can have any structure - in this case and doesn't necessarily have to be a file system image. - This option is used mainly for debugging. - - Note: /dev/initrd is read-only and it can only be used once. As soon - as the last process has closed it, all data is freed and /dev/initrd - can't be opened anymore. - - root=/dev/ram0 - - initrd is mounted as root, and the normal boot procedure is followed, - with the RAM disk mounted as root. - -Compressed cpio images ----------------------- - -Recent kernels have support for populating a ramdisk from a compressed cpio -archive. On such systems, the creation of a ramdisk image doesn't need to -involve special block devices or loopbacks; you merely create a directory on -disk with the desired initrd content, cd to that directory, and run (as an -example):: - - find . | cpio --quiet -H newc -o | gzip -9 -n > /boot/imagefile.img - -Examining the contents of an existing image file is just as simple:: - - mkdir /tmp/imagefile - cd /tmp/imagefile - gzip -cd /boot/imagefile.img | cpio -imd --quiet - -Installation ------------- - -First, a directory for the initrd file system has to be created on the -"normal" root file system, e.g.:: - - # mkdir /initrd - -The name is not relevant. More details can be found on the -:manpage:`pivot_root(2)` man page. - -If the root file system is created during the boot procedure (i.e. if -you're building an install floppy), the root file system creation -procedure should create the ``/initrd`` directory. - -If initrd will not be mounted in some cases, its content is still -accessible if the following device has been created:: - - # mknod /dev/initrd b 1 250 - # chmod 400 /dev/initrd - -Second, the kernel has to be compiled with RAM disk support and with -support for the initial RAM disk enabled. Also, at least all components -needed to execute programs from initrd (e.g. executable format and file -system) must be compiled into the kernel. - -Third, you have to create the RAM disk image. This is done by creating a -file system on a block device, copying files to it as needed, and then -copying the content of the block device to the initrd file. With recent -kernels, at least three types of devices are suitable for that: - - - a floppy disk (works everywhere but it's painfully slow) - - a RAM disk (fast, but allocates physical memory) - - a loopback device (the most elegant solution) - -We'll describe the loopback device method: - - 1) make sure loopback block devices are configured into the kernel - 2) create an empty file system of the appropriate size, e.g.:: - - # dd if=/dev/zero of=initrd bs=300k count=1 - # mke2fs -F -m0 initrd - - (if space is critical, you may want to use the Minix FS instead of Ext2) - 3) mount the file system, e.g.:: - - # mount -t ext2 -o loop initrd /mnt - - 4) create the console device:: - - # mkdir /mnt/dev - # mknod /mnt/dev/console c 5 1 - - 5) copy all the files that are needed to properly use the initrd - environment. Don't forget the most important file, ``/sbin/init`` - - .. note:: ``/sbin/init`` permissions must include "x" (execute). - - 6) correct operation the initrd environment can frequently be tested - even without rebooting with the command:: - - # chroot /mnt /sbin/init - - This is of course limited to initrds that do not interfere with the - general system state (e.g. by reconfiguring network interfaces, - overwriting mounted devices, trying to start already running demons, - etc. Note however that it is usually possible to use pivot_root in - such a chroot'ed initrd environment.) - 7) unmount the file system:: - - # umount /mnt - - 8) the initrd is now in the file "initrd". Optionally, it can now be - compressed:: - - # gzip -9 initrd - -For experimenting with initrd, you may want to take a rescue floppy and -only add a symbolic link from ``/sbin/init`` to ``/bin/sh``. Alternatively, you -can try the experimental newlib environment [#f2]_ to create a small -initrd. - -Finally, you have to boot the kernel and load initrd. Almost all Linux -boot loaders support initrd. Since the boot process is still compatible -with an older mechanism, the following boot command line parameters -have to be given:: - - root=/dev/ram0 rw - -(rw is only necessary if writing to the initrd file system.) - -With LOADLIN, you simply execute:: - - LOADLIN initrd= - -e.g.:: - - LOADLIN C:\LINUX\BZIMAGE initrd=C:\LINUX\INITRD.GZ root=/dev/ram0 rw - -With LILO, you add the option ``INITRD=`` to either the global section -or to the section of the respective kernel in ``/etc/lilo.conf``, and pass -the options using APPEND, e.g.:: - - image = /bzImage - initrd = /boot/initrd.gz - append = "root=/dev/ram0 rw" - -and run ``/sbin/lilo`` - -For other boot loaders, please refer to the respective documentation. - -Now you can boot and enjoy using initrd. - - -Changing the root device ------------------------- - -When finished with its duties, init typically changes the root device -and proceeds with starting the Linux system on the "real" root device. - -The procedure involves the following steps: - - mounting the new root file system - - turning it into the root file system - - removing all accesses to the old (initrd) root file system - - unmounting the initrd file system and de-allocating the RAM disk - -Mounting the new root file system is easy: it just needs to be mounted on -a directory under the current root. Example:: - - # mkdir /new-root - # mount -o ro /dev/hda1 /new-root - -The root change is accomplished with the pivot_root system call, which -is also available via the ``pivot_root`` utility (see :manpage:`pivot_root(8)` -man page; ``pivot_root`` is distributed with util-linux version 2.10h or higher -[#f3]_). ``pivot_root`` moves the current root to a directory under the new -root, and puts the new root at its place. The directory for the old root -must exist before calling ``pivot_root``. Example:: - - # cd /new-root - # mkdir initrd - # pivot_root . initrd - -Now, the init process may still access the old root via its -executable, shared libraries, standard input/output/error, and its -current root directory. All these references are dropped by the -following command:: - - # exec chroot . what-follows dev/console 2>&1 - -Where what-follows is a program under the new root, e.g. ``/sbin/init`` -If the new root file system will be used with udev and has no valid -``/dev`` directory, udev must be initialized before invoking chroot in order -to provide ``/dev/console``. - -Note: implementation details of pivot_root may change with time. In order -to ensure compatibility, the following points should be observed: - - - before calling pivot_root, the current directory of the invoking - process should point to the new root directory - - use . as the first argument, and the _relative_ path of the directory - for the old root as the second argument - - a chroot program must be available under the old and the new root - - chroot to the new root afterwards - - use relative paths for dev/console in the exec command - -Now, the initrd can be unmounted and the memory allocated by the RAM -disk can be freed:: - - # umount /initrd - # blockdev --flushbufs /dev/ram0 - -It is also possible to use initrd with an NFS-mounted root, see the -:manpage:`pivot_root(8)` man page for details. - - -Usage scenarios ---------------- - -The main motivation for implementing initrd was to allow for modular -kernel configuration at system installation. The procedure would work -as follows: - - 1) system boots from floppy or other media with a minimal kernel - (e.g. support for RAM disks, initrd, a.out, and the Ext2 FS) and - loads initrd - 2) ``/sbin/init`` determines what is needed to (1) mount the "real" root FS - (i.e. device type, device drivers, file system) and (2) the - distribution media (e.g. CD-ROM, network, tape, ...). This can be - done by asking the user, by auto-probing, or by using a hybrid - approach. - 3) ``/sbin/init`` loads the necessary kernel modules - 4) ``/sbin/init`` creates and populates the root file system (this doesn't - have to be a very usable system yet) - 5) ``/sbin/init`` invokes ``pivot_root`` to change the root file system and - execs - via chroot - a program that continues the installation - 6) the boot loader is installed - 7) the boot loader is configured to load an initrd with the set of - modules that was used to bring up the system (e.g. ``/initrd`` can be - modified, then unmounted, and finally, the image is written from - ``/dev/ram0`` or ``/dev/rd/0`` to a file) - 8) now the system is bootable and additional installation tasks can be - performed - -The key role of initrd here is to re-use the configuration data during -normal system operation without requiring the use of a bloated "generic" -kernel or re-compiling or re-linking the kernel. - -A second scenario is for installations where Linux runs on systems with -different hardware configurations in a single administrative domain. In -such cases, it is desirable to generate only a small set of kernels -(ideally only one) and to keep the system-specific part of configuration -information as small as possible. In this case, a common initrd could be -generated with all the necessary modules. Then, only ``/sbin/init`` or a file -read by it would have to be different. - -A third scenario is more convenient recovery disks, because information -like the location of the root FS partition doesn't have to be provided at -boot time, but the system loaded from initrd can invoke a user-friendly -dialog and it can also perform some sanity checks (or even some form of -auto-detection). - -Last not least, CD-ROM distributors may use it for better installation -from CD, e.g. by using a boot floppy and bootstrapping a bigger RAM disk -via initrd from CD; or by booting via a loader like ``LOADLIN`` or directly -from the CD-ROM, and loading the RAM disk from CD without need of -floppies. - - -Obsolete root change mechanism ------------------------------- - -The following mechanism was used before the introduction of pivot_root. -Current kernels still support it, but you should _not_ rely on its -continued availability. - -It works by mounting the "real" root device (i.e. the one set with rdev -in the kernel image or with root=... at the boot command line) as the -root file system when linuxrc exits. The initrd file system is then -unmounted, or, if it is still busy, moved to a directory ``/initrd``, if -such a directory exists on the new root file system. - -In order to use this mechanism, you do not have to specify the boot -command options root, init, or rw. (If specified, they will affect -the real root file system, not the initrd environment.) - -If /proc is mounted, the "real" root device can be changed from within -linuxrc by writing the number of the new root FS device to the special -file /proc/sys/kernel/real-root-dev, e.g.:: - - # echo 0x301 >/proc/sys/kernel/real-root-dev - -Note that the mechanism is incompatible with NFS and similar file -systems. - -This old, deprecated mechanism is commonly called ``change_root``, while -the new, supported mechanism is called ``pivot_root``. - - -Mixed change_root and pivot_root mechanism ------------------------------------------- - -In case you did not want to use ``root=/dev/ram0`` to trigger the pivot_root -mechanism, you may create both ``/linuxrc`` and ``/sbin/init`` in your initrd -image. - -``/linuxrc`` would contain only the following:: - - #! /bin/sh - mount -n -t proc proc /proc - echo 0x0100 >/proc/sys/kernel/real-root-dev - umount -n /proc - -Once linuxrc exited, the kernel would mount again your initrd as root, -this time executing ``/sbin/init``. Again, it would be the duty of this init -to build the right environment (maybe using the ``root= device`` passed on -the cmdline) before the final execution of the real ``/sbin/init``. - - -Resources ---------- - -.. [#f1] Almesberger, Werner; "Booting Linux: The History and the Future" - http://www.almesberger.net/cv/papers/ols2k-9.ps.gz -.. [#f2] newlib package (experimental), with initrd example - https://www.sourceware.org/newlib/ -.. [#f3] util-linux: Miscellaneous utilities for Linux - https://www.kernel.org/pub/linux/utils/util-linux/ diff --git a/Documentation/java.txt b/Documentation/java.txt deleted file mode 100644 index ae33d959638c..000000000000 --- a/Documentation/java.txt +++ /dev/null @@ -1,418 +0,0 @@ -Java(tm) Binary Kernel Support for Linux v1.03 ----------------------------------------------- - -Linux beats them ALL! While all other OS's are TALKING about direct -support of Java Binaries in the OS, Linux is doing it! - -You can execute Java applications and Java Applets just like any -other program after you have done the following: - -1) You MUST FIRST install the Java Developers Kit for Linux. - The Java on Linux HOWTO gives the details on getting and - installing this. This HOWTO can be found at: - - ftp://sunsite.unc.edu/pub/Linux/docs/HOWTO/Java-HOWTO - - You should also set up a reasonable CLASSPATH environment - variable to use Java applications that make use of any - nonstandard classes (not included in the same directory - as the application itself). - -2) You have to compile BINFMT_MISC either as a module or into - the kernel (``CONFIG_BINFMT_MISC``) and set it up properly. - If you choose to compile it as a module, you will have - to insert it manually with modprobe/insmod, as kmod - cannot easily be supported with binfmt_misc. - Read the file 'binfmt_misc.txt' in this directory to know - more about the configuration process. - -3) Add the following configuration items to binfmt_misc - (you should really have read ``binfmt_misc.txt`` now): - support for Java applications:: - - ':Java:M::\xca\xfe\xba\xbe::/usr/local/bin/javawrapper:' - - support for executable Jar files:: - - ':ExecutableJAR:E::jar::/usr/local/bin/jarwrapper:' - - support for Java Applets:: - - ':Applet:E::html::/usr/bin/appletviewer:' - - or the following, if you want to be more selective:: - - ':Applet:M::`` in the first line - (``<`` has to be the first character!) to let this work! - - For the compiled Java programs you need a wrapper script like the - following (this is because Java is broken in case of the filename - handling), again fix the path names, both in the script and in the - above given configuration string. - - You, too, need the little program after the script. Compile like:: - - gcc -O2 -o javaclassname javaclassname.c - - and stick it to ``/usr/local/bin``. - - Both the javawrapper shellscript and the javaclassname program - were supplied by Colin J. Watson . - -Javawrapper shell script:: - - #!/bin/bash - # /usr/local/bin/javawrapper - the wrapper for binfmt_misc/java - - if [ -z "$1" ]; then - exec 1>&2 - echo Usage: $0 class-file - exit 1 - fi - - CLASS=$1 - FQCLASS=`/usr/local/bin/javaclassname $1` - FQCLASSN=`echo $FQCLASS | sed -e 's/^.*\.\([^.]*\)$/\1/'` - FQCLASSP=`echo $FQCLASS | sed -e 's-\.-/-g' -e 's-^[^/]*$--' -e 's-/[^/]*$--'` - - # for example: - # CLASS=Test.class - # FQCLASS=foo.bar.Test - # FQCLASSN=Test - # FQCLASSP=foo/bar - - unset CLASSBASE - - declare -i LINKLEVEL=0 - - while :; do - if [ "`basename $CLASS .class`" == "$FQCLASSN" ]; then - # See if this directory works straight off - cd -L `dirname $CLASS` - CLASSDIR=$PWD - cd $OLDPWD - if echo $CLASSDIR | grep -q "$FQCLASSP$"; then - CLASSBASE=`echo $CLASSDIR | sed -e "s.$FQCLASSP$.."` - break; - fi - # Try dereferencing the directory name - cd -P `dirname $CLASS` - CLASSDIR=$PWD - cd $OLDPWD - if echo $CLASSDIR | grep -q "$FQCLASSP$"; then - CLASSBASE=`echo $CLASSDIR | sed -e "s.$FQCLASSP$.."` - break; - fi - # If no other possible filename exists - if [ ! -L $CLASS ]; then - exec 1>&2 - echo $0: - echo " $CLASS should be in a" \ - "directory tree called $FQCLASSP" - exit 1 - fi - fi - if [ ! -L $CLASS ]; then break; fi - # Go down one more level of symbolic links - let LINKLEVEL+=1 - if [ $LINKLEVEL -gt 5 ]; then - exec 1>&2 - echo $0: - echo " Too many symbolic links encountered" - exit 1 - fi - CLASS=`ls --color=no -l $CLASS | sed -e 's/^.* \([^ ]*\)$/\1/'` - done - - if [ -z "$CLASSBASE" ]; then - if [ -z "$FQCLASSP" ]; then - GOODNAME=$FQCLASSN.class - else - GOODNAME=$FQCLASSP/$FQCLASSN.class - fi - exec 1>&2 - echo $0: - echo " $FQCLASS should be in a file called $GOODNAME" - exit 1 - fi - - if ! echo $CLASSPATH | grep -q "^\(.*:\)*$CLASSBASE\(:.*\)*"; then - # class is not in CLASSPATH, so prepend dir of class to CLASSPATH - if [ -z "${CLASSPATH}" ] ; then - export CLASSPATH=$CLASSBASE - else - export CLASSPATH=$CLASSBASE:$CLASSPATH - fi - fi - - shift - /usr/bin/java $FQCLASS "$@" - -javaclassname.c:: - - /* javaclassname.c - * - * Extracts the class name from a Java class file; intended for use in a Java - * wrapper of the type supported by the binfmt_misc option in the Linux kernel. - * - * Copyright (C) 1999 Colin J. Watson . - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ - - #include - #include - #include - #include - - /* From Sun's Java VM Specification, as tag entries in the constant pool. */ - - #define CP_UTF8 1 - #define CP_INTEGER 3 - #define CP_FLOAT 4 - #define CP_LONG 5 - #define CP_DOUBLE 6 - #define CP_CLASS 7 - #define CP_STRING 8 - #define CP_FIELDREF 9 - #define CP_METHODREF 10 - #define CP_INTERFACEMETHODREF 11 - #define CP_NAMEANDTYPE 12 - #define CP_METHODHANDLE 15 - #define CP_METHODTYPE 16 - #define CP_INVOKEDYNAMIC 18 - - /* Define some commonly used error messages */ - - #define seek_error() error("%s: Cannot seek\n", program) - #define corrupt_error() error("%s: Class file corrupt\n", program) - #define eof_error() error("%s: Unexpected end of file\n", program) - #define utf8_error() error("%s: Only ASCII 1-255 supported\n", program); - - char *program; - - long *pool; - - u_int8_t read_8(FILE *classfile); - u_int16_t read_16(FILE *classfile); - void skip_constant(FILE *classfile, u_int16_t *cur); - void error(const char *format, ...); - int main(int argc, char **argv); - - /* Reads in an unsigned 8-bit integer. */ - u_int8_t read_8(FILE *classfile) - { - int b = fgetc(classfile); - if(b == EOF) - eof_error(); - return (u_int8_t)b; - } - - /* Reads in an unsigned 16-bit integer. */ - u_int16_t read_16(FILE *classfile) - { - int b1, b2; - b1 = fgetc(classfile); - if(b1 == EOF) - eof_error(); - b2 = fgetc(classfile); - if(b2 == EOF) - eof_error(); - return (u_int16_t)((b1 << 8) | b2); - } - - /* Reads in a value from the constant pool. */ - void skip_constant(FILE *classfile, u_int16_t *cur) - { - u_int16_t len; - int seekerr = 1; - pool[*cur] = ftell(classfile); - switch(read_8(classfile)) - { - case CP_UTF8: - len = read_16(classfile); - seekerr = fseek(classfile, len, SEEK_CUR); - break; - case CP_CLASS: - case CP_STRING: - case CP_METHODTYPE: - seekerr = fseek(classfile, 2, SEEK_CUR); - break; - case CP_METHODHANDLE: - seekerr = fseek(classfile, 3, SEEK_CUR); - break; - case CP_INTEGER: - case CP_FLOAT: - case CP_FIELDREF: - case CP_METHODREF: - case CP_INTERFACEMETHODREF: - case CP_NAMEANDTYPE: - case CP_INVOKEDYNAMIC: - seekerr = fseek(classfile, 4, SEEK_CUR); - break; - case CP_LONG: - case CP_DOUBLE: - seekerr = fseek(classfile, 8, SEEK_CUR); - ++(*cur); - break; - default: - corrupt_error(); - } - if(seekerr) - seek_error(); - } - - void error(const char *format, ...) - { - va_list ap; - va_start(ap, format); - vfprintf(stderr, format, ap); - va_end(ap); - exit(1); - } - - int main(int argc, char **argv) - { - FILE *classfile; - u_int16_t cp_count, i, this_class, classinfo_ptr; - u_int8_t length; - - program = argv[0]; - - if(!argv[1]) - error("%s: Missing input file\n", program); - classfile = fopen(argv[1], "rb"); - if(!classfile) - error("%s: Error opening %s\n", program, argv[1]); - - if(fseek(classfile, 8, SEEK_SET)) /* skip magic and version numbers */ - seek_error(); - cp_count = read_16(classfile); - pool = calloc(cp_count, sizeof(long)); - if(!pool) - error("%s: Out of memory for constant pool\n", program); - - for(i = 1; i < cp_count; ++i) - skip_constant(classfile, &i); - if(fseek(classfile, 2, SEEK_CUR)) /* skip access flags */ - seek_error(); - - this_class = read_16(classfile); - if(this_class < 1 || this_class >= cp_count) - corrupt_error(); - if(!pool[this_class] || pool[this_class] == -1) - corrupt_error(); - if(fseek(classfile, pool[this_class] + 1, SEEK_SET)) - seek_error(); - - classinfo_ptr = read_16(classfile); - if(classinfo_ptr < 1 || classinfo_ptr >= cp_count) - corrupt_error(); - if(!pool[classinfo_ptr] || pool[classinfo_ptr] == -1) - corrupt_error(); - if(fseek(classfile, pool[classinfo_ptr] + 1, SEEK_SET)) - seek_error(); - - length = read_16(classfile); - for(i = 0; i < length; ++i) - { - u_int8_t x = read_8(classfile); - if((x & 0x80) || !x) - { - if((x & 0xE0) == 0xC0) - { - u_int8_t y = read_8(classfile); - if((y & 0xC0) == 0x80) - { - int c = ((x & 0x1f) << 6) + (y & 0x3f); - if(c) putchar(c); - else utf8_error(); - } - else utf8_error(); - } - else utf8_error(); - } - else if(x == '/') putchar('.'); - else putchar(x); - } - putchar('\n'); - free(pool); - fclose(classfile); - return 0; - } - -jarwrapper:: - - #!/bin/bash - # /usr/local/java/bin/jarwrapper - the wrapper for binfmt_misc/jar - - java -jar $1 - - -Now simply ``chmod +x`` the ``.class``, ``.jar`` and/or ``.html`` files you -want to execute. - -To add a Java program to your path best put a symbolic link to the main -.class file into /usr/bin (or another place you like) omitting the .class -extension. The directory containing the original .class file will be -added to your CLASSPATH during execution. - - -To test your new setup, enter in the following simple Java app, and name -it "HelloWorld.java":: - - class HelloWorld { - public static void main(String args[]) { - System.out.println("Hello World!"); - } - } - -Now compile the application with:: - - javac HelloWorld.java - -Set the executable permissions of the binary file, with:: - - chmod 755 HelloWorld.class - -And then execute it:: - - ./HelloWorld.class - - -To execute Java Jar files, simple chmod the ``*.jar`` files to include -the execution bit, then just do:: - - ./Application.jar - - -To execute Java Applets, simple chmod the ``*.html`` files to include -the execution bit, then just do:: - - ./Applet.html - - -originally by Brian A. Lantz, brian@lantz.com -heavily edited for binfmt_misc by Richard Günther -new scripts by Colin J. Watson -added executable Jar file support by Kurt Huwig - diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt deleted file mode 100644 index b0804273b6e3..000000000000 --- a/Documentation/kernel-parameters.txt +++ /dev/null @@ -1,4577 +0,0 @@ -Kernel Parameters -~~~~~~~~~~~~~~~~~ - -The following is a consolidated list of the kernel parameters as -implemented by the __setup(), core_param() and module_param() macros -and sorted into English Dictionary order (defined as ignoring all -punctuation and sorting digits before letters in a case insensitive -manner), and with descriptions where known. - -The kernel parses parameters from the kernel command line up to "--"; -if it doesn't recognize a parameter and it doesn't contain a '.', the -parameter gets passed to init: parameters with '=' go into init's -environment, others are passed as command line arguments to init. -Everything after "--" is passed as an argument to init. - -Module parameters can be specified in two ways: via the kernel command -line with a module name prefix, or via modprobe, e.g.:: - - (kernel command line) usbcore.blinkenlights=1 - (modprobe command line) modprobe usbcore blinkenlights=1 - -Parameters for modules which are built into the kernel need to be -specified on the kernel command line. modprobe looks through the -kernel command line (/proc/cmdline) and collects module parameters -when it loads a module, so the kernel command line can be used for -loadable modules too. - -Hyphens (dashes) and underscores are equivalent in parameter names, so:: - - log_buf_len=1M print-fatal-signals=1 - -can also be entered as:: - - log-buf-len=1M print_fatal_signals=1 - -Double-quotes can be used to protect spaces in values, e.g.:: - - param="spaces in here" - -cpu lists: ----------- - -Some kernel parameters take a list of CPUs as a value, e.g. isolcpus, -nohz_full, irqaffinity, rcu_nocbs. The format of this list is: - - ,..., - -or - - - - (must be a positive range in ascending order) - -or a mixture - -,...,- - -Note that for the special case of a range one can split the range into equal -sized groups and for each group use some amount from the beginning of that -group: - - -cpu number>:/ - -For example one can add to the command line following parameter: - - isolcpus=1,2,10-20,100-2000:2/25 - -where the final item represents CPUs 100,101,125,126,150,151,... - - - -This document may not be entirely up to date and comprehensive. The command -"modinfo -p ${modulename}" shows a current list of all parameters of a loadable -module. Loadable modules, after being loaded into the running kernel, also -reveal their parameters in /sys/module/${modulename}/parameters/. Some of these -parameters may be changed at runtime by the command -``echo -n ${value} > /sys/module/${modulename}/parameters/${parm}``. - -The parameters listed below are only valid if certain kernel build options were -enabled and if respective hardware is present. The text in square brackets at -the beginning of each description states the restrictions within which a -parameter is applicable:: - - ACPI ACPI support is enabled. - AGP AGP (Accelerated Graphics Port) is enabled. - ALSA ALSA sound support is enabled. - APIC APIC support is enabled. - APM Advanced Power Management support is enabled. - ARM ARM architecture is enabled. - AVR32 AVR32 architecture is enabled. - AX25 Appropriate AX.25 support is enabled. - BLACKFIN Blackfin architecture is enabled. - CLK Common clock infrastructure is enabled. - CMA Contiguous Memory Area support is enabled. - DRM Direct Rendering Management support is enabled. - DYNAMIC_DEBUG Build in debug messages and enable them at runtime - EDD BIOS Enhanced Disk Drive Services (EDD) is enabled - EFI EFI Partitioning (GPT) is enabled - EIDE EIDE/ATAPI support is enabled. - EVM Extended Verification Module - FB The frame buffer device is enabled. - FTRACE Function tracing enabled. - GCOV GCOV profiling is enabled. - HW Appropriate hardware is enabled. - IA-64 IA-64 architecture is enabled. - IMA Integrity measurement architecture is enabled. - IOSCHED More than one I/O scheduler is enabled. - IP_PNP IP DHCP, BOOTP, or RARP is enabled. - IPV6 IPv6 support is enabled. - ISAPNP ISA PnP code is enabled. - ISDN Appropriate ISDN support is enabled. - JOY Appropriate joystick support is enabled. - KGDB Kernel debugger support is enabled. - KVM Kernel Virtual Machine support is enabled. - LIBATA Libata driver is enabled - LP Printer support is enabled. - LOOP Loopback device support is enabled. - M68k M68k architecture is enabled. - These options have more detailed description inside of - Documentation/m68k/kernel-options.txt. - MDA MDA console support is enabled. - MIPS MIPS architecture is enabled. - MOUSE Appropriate mouse support is enabled. - MSI Message Signaled Interrupts (PCI). - MTD MTD (Memory Technology Device) support is enabled. - NET Appropriate network support is enabled. - NUMA NUMA support is enabled. - NFS Appropriate NFS support is enabled. - OSS OSS sound support is enabled. - PV_OPS A paravirtualized kernel is enabled. - PARIDE The ParIDE (parallel port IDE) subsystem is enabled. - PARISC The PA-RISC architecture is enabled. - PCI PCI bus support is enabled. - PCIE PCI Express support is enabled. - PCMCIA The PCMCIA subsystem is enabled. - PNP Plug & Play support is enabled. - PPC PowerPC architecture is enabled. - PPT Parallel port support is enabled. - PS2 Appropriate PS/2 support is enabled. - RAM RAM disk support is enabled. - S390 S390 architecture is enabled. - SCSI Appropriate SCSI support is enabled. - A lot of drivers have their options described inside - the Documentation/scsi/ sub-directory. - SECURITY Different security models are enabled. - SELINUX SELinux support is enabled. - APPARMOR AppArmor support is enabled. - SERIAL Serial support is enabled. - SH SuperH architecture is enabled. - SMP The kernel is an SMP kernel. - SPARC Sparc architecture is enabled. - SWSUSP Software suspend (hibernation) is enabled. - SUSPEND System suspend states are enabled. - TPM TPM drivers are enabled. - TS Appropriate touchscreen support is enabled. - UMS USB Mass Storage support is enabled. - USB USB support is enabled. - USBHID USB Human Interface Device support is enabled. - V4L Video For Linux support is enabled. - VMMIO Driver for memory mapped virtio devices is enabled. - VGA The VGA console has been enabled. - VT Virtual terminal support is enabled. - WDT Watchdog support is enabled. - XT IBM PC/XT MFM hard disk support is enabled. - X86-32 X86-32, aka i386 architecture is enabled. - X86-64 X86-64 architecture is enabled. - More X86-64 boot options can be found in - Documentation/x86/x86_64/boot-options.txt . - X86 Either 32-bit or 64-bit x86 (same as X86-32+X86-64) - X86_UV SGI UV support is enabled. - XEN Xen support is enabled - -In addition, the following text indicates that the option:: - - BUGS= Relates to possible processor bugs on the said processor. - KNL Is a kernel start-up parameter. - BOOT Is a boot loader parameter. - -Parameters denoted with BOOT are actually interpreted by the boot -loader, and have no meaning to the kernel directly. -Do not modify the syntax of boot loader parameters without extreme -need or coordination with . - -There are also arch-specific kernel-parameters not documented here. -See for example . - -Note that ALL kernel parameters listed below are CASE SENSITIVE, and that -a trailing = on the name of any parameter states that that parameter will -be entered as an environment variable, whereas its absence indicates that -it will appear as a kernel argument readable via /proc/cmdline by programs -running once the system is up. - -The number of kernel parameters is not limited, but the length of the -complete command line (parameters including spaces etc.) is limited to -a fixed number of characters. This limit depends on the architecture -and is between 256 and 4096 characters. It is defined in the file -./include/asm/setup.h as COMMAND_LINE_SIZE. - -Finally, the [KMG] suffix is commonly described after a number of kernel -parameter values. These 'K', 'M', and 'G' letters represent the _binary_ -multipliers 'Kilo', 'Mega', and 'Giga', equalling 2^10, 2^20, and 2^30 -bytes respectively. Such letter suffixes can also be entirely omitted:: - - - acpi= [HW,ACPI,X86,ARM64] - Advanced Configuration and Power Interface - Format: { force | on | off | strict | noirq | rsdt | - copy_dsdt } - force -- enable ACPI if default was off - on -- enable ACPI but allow fallback to DT [arm64] - off -- disable ACPI if default was on - noirq -- do not use ACPI for IRQ routing - strict -- Be less tolerant of platforms that are not - strictly ACPI specification compliant. - rsdt -- prefer RSDT over (default) XSDT - copy_dsdt -- copy DSDT to memory - For ARM64, ONLY "acpi=off", "acpi=on" or "acpi=force" - are available - - See also Documentation/power/runtime_pm.txt, pci=noacpi - - acpi_apic_instance= [ACPI, IOAPIC] - Format: - 2: use 2nd APIC table, if available - 1,0: use 1st APIC table - default: 0 - - acpi_backlight= [HW,ACPI] - acpi_backlight=vendor - acpi_backlight=video - If set to vendor, prefer vendor specific driver - (e.g. thinkpad_acpi, sony_acpi, etc.) instead - of the ACPI video.ko driver. - - acpi_force_32bit_fadt_addr - force FADT to use 32 bit addresses rather than the - 64 bit X_* addresses. Some firmware have broken 64 - bit addresses for force ACPI ignore these and use - the older legacy 32 bit addresses. - - acpica_no_return_repair [HW, ACPI] - Disable AML predefined validation mechanism - This mechanism can repair the evaluation result to make - the return objects more ACPI specification compliant. - This option is useful for developers to identify the - root cause of an AML interpreter issue when the issue - has something to do with the repair mechanism. - - acpi.debug_layer= [HW,ACPI,ACPI_DEBUG] - acpi.debug_level= [HW,ACPI,ACPI_DEBUG] - Format: - CONFIG_ACPI_DEBUG must be enabled to produce any ACPI - debug output. Bits in debug_layer correspond to a - _COMPONENT in an ACPI source file, e.g., - #define _COMPONENT ACPI_PCI_COMPONENT - Bits in debug_level correspond to a level in - ACPI_DEBUG_PRINT statements, e.g., - ACPI_DEBUG_PRINT((ACPI_DB_INFO, ... - The debug_level mask defaults to "info". See - Documentation/acpi/debug.txt for more information about - debug layers and levels. - - Enable processor driver info messages: - acpi.debug_layer=0x20000000 - Enable PCI/PCI interrupt routing info messages: - acpi.debug_layer=0x400000 - Enable AML "Debug" output, i.e., stores to the Debug - object while interpreting AML: - acpi.debug_layer=0xffffffff acpi.debug_level=0x2 - Enable all messages related to ACPI hardware: - acpi.debug_layer=0x2 acpi.debug_level=0xffffffff - - Some values produce so much output that the system is - unusable. The "log_buf_len" parameter may be useful - if you need to capture more output. - - acpi_enforce_resources= [ACPI] - { strict | lax | no } - Check for resource conflicts between native drivers - and ACPI OperationRegions (SystemIO and SystemMemory - only). IO ports and memory declared in ACPI might be - used by the ACPI subsystem in arbitrary AML code and - can interfere with legacy drivers. - strict (default): access to resources claimed by ACPI - is denied; legacy drivers trying to access reserved - resources will fail to bind to device using them. - lax: access to resources claimed by ACPI is allowed; - legacy drivers trying to access reserved resources - will bind successfully but a warning message is logged. - no: ACPI OperationRegions are not marked as reserved, - no further checks are performed. - - acpi_force_table_verification [HW,ACPI] - Enable table checksum verification during early stage. - By default, this is disabled due to x86 early mapping - size limitation. - - acpi_irq_balance [HW,ACPI] - ACPI will balance active IRQs - default in APIC mode - - acpi_irq_nobalance [HW,ACPI] - ACPI will not move active IRQs (default) - default in PIC mode - - acpi_irq_isa= [HW,ACPI] If irq_balance, mark listed IRQs used by ISA - Format: ,... - - acpi_irq_pci= [HW,ACPI] If irq_balance, clear listed IRQs for - use by PCI - Format: ,... - - acpi_no_auto_serialize [HW,ACPI] - Disable auto-serialization of AML methods - AML control methods that contain the opcodes to create - named objects will be marked as "Serialized" by the - auto-serialization feature. - This feature is enabled by default. - This option allows to turn off the feature. - - acpi_no_memhotplug [ACPI] Disable memory hotplug. Useful for kdump - kernels. - - acpi_no_static_ssdt [HW,ACPI] - Disable installation of static SSDTs at early boot time - By default, SSDTs contained in the RSDT/XSDT will be - installed automatically and they will appear under - /sys/firmware/acpi/tables. - This option turns off this feature. - Note that specifying this option does not affect - dynamic table installation which will install SSDT - tables to /sys/firmware/acpi/tables/dynamic. - - acpi_rsdp= [ACPI,EFI,KEXEC] - Pass the RSDP address to the kernel, mostly used - on machines running EFI runtime service to boot the - second kernel for kdump. - - acpi_os_name= [HW,ACPI] Tell ACPI BIOS the name of the OS - Format: To spoof as Windows 98: ="Microsoft Windows" - - acpi_rev_override [ACPI] Override the _REV object to return 5 (instead - of 2 which is mandated by ACPI 6) as the supported ACPI - specification revision (when using this switch, it may - be necessary to carry out a cold reboot _twice_ in a - row to make it take effect on the platform firmware). - - acpi_osi= [HW,ACPI] Modify list of supported OS interface strings - acpi_osi="string1" # add string1 - acpi_osi="!string2" # remove string2 - acpi_osi=!* # remove all strings - acpi_osi=! # disable all built-in OS vendor - strings - acpi_osi=!! # enable all built-in OS vendor - strings - acpi_osi= # disable all strings - - 'acpi_osi=!' can be used in combination with single or - multiple 'acpi_osi="string1"' to support specific OS - vendor string(s). Note that such command can only - affect the default state of the OS vendor strings, thus - it cannot affect the default state of the feature group - strings and the current state of the OS vendor strings, - specifying it multiple times through kernel command line - is meaningless. This command is useful when one do not - care about the state of the feature group strings which - should be controlled by the OSPM. - Examples: - 1. 'acpi_osi=! acpi_osi="Windows 2000"' is equivalent - to 'acpi_osi="Windows 2000" acpi_osi=!', they all - can make '_OSI("Windows 2000")' TRUE. - - 'acpi_osi=' cannot be used in combination with other - 'acpi_osi=' command lines, the _OSI method will not - exist in the ACPI namespace. NOTE that such command can - only affect the _OSI support state, thus specifying it - multiple times through kernel command line is also - meaningless. - Examples: - 1. 'acpi_osi=' can make 'CondRefOf(_OSI, Local1)' - FALSE. - - 'acpi_osi=!*' can be used in combination with single or - multiple 'acpi_osi="string1"' to support specific - string(s). Note that such command can affect the - current state of both the OS vendor strings and the - feature group strings, thus specifying it multiple times - through kernel command line is meaningful. But it may - still not able to affect the final state of a string if - there are quirks related to this string. This command - is useful when one want to control the state of the - feature group strings to debug BIOS issues related to - the OSPM features. - Examples: - 1. 'acpi_osi="Module Device" acpi_osi=!*' can make - '_OSI("Module Device")' FALSE. - 2. 'acpi_osi=!* acpi_osi="Module Device"' can make - '_OSI("Module Device")' TRUE. - 3. 'acpi_osi=! acpi_osi=!* acpi_osi="Windows 2000"' is - equivalent to - 'acpi_osi=!* acpi_osi=! acpi_osi="Windows 2000"' - and - 'acpi_osi=!* acpi_osi="Windows 2000" acpi_osi=!', - they all will make '_OSI("Windows 2000")' TRUE. - - acpi_pm_good [X86] - Override the pmtimer bug detection: force the kernel - to assume that this machine's pmtimer latches its value - and always returns good values. - - acpi_sci= [HW,ACPI] ACPI System Control Interrupt trigger mode - Format: { level | edge | high | low } - - acpi_skip_timer_override [HW,ACPI] - Recognize and ignore IRQ0/pin2 Interrupt Override. - For broken nForce2 BIOS resulting in XT-PIC timer. - - acpi_sleep= [HW,ACPI] Sleep options - Format: { s3_bios, s3_mode, s3_beep, s4_nohwsig, - old_ordering, nonvs, sci_force_enable } - See Documentation/power/video.txt for information on - s3_bios and s3_mode. - s3_beep is for debugging; it makes the PC's speaker beep - as soon as the kernel's real-mode entry point is called. - s4_nohwsig prevents ACPI hardware signature from being - used during resume from hibernation. - old_ordering causes the ACPI 1.0 ordering of the _PTS - control method, with respect to putting devices into - low power states, to be enforced (the ACPI 2.0 ordering - of _PTS is used by default). - nonvs prevents the kernel from saving/restoring the - ACPI NVS memory during suspend/hibernation and resume. - sci_force_enable causes the kernel to set SCI_EN directly - on resume from S1/S3 (which is against the ACPI spec, - but some broken systems don't work without it). - - acpi_use_timer_override [HW,ACPI] - Use timer override. For some broken Nvidia NF5 boards - that require a timer override, but don't have HPET - - add_efi_memmap [EFI; X86] Include EFI memory map in - kernel's map of available physical RAM. - - agp= [AGP] - { off | try_unsupported } - off: disable AGP support - try_unsupported: try to drive unsupported chipsets - (may crash computer or cause data corruption) - - ALSA [HW,ALSA] - See Documentation/sound/alsa/alsa-parameters.txt - - alignment= [KNL,ARM] - Allow the default userspace alignment fault handler - behaviour to be specified. Bit 0 enables warnings, - bit 1 enables fixups, and bit 2 sends a segfault. - - align_va_addr= [X86-64] - Align virtual addresses by clearing slice [14:12] when - allocating a VMA at process creation time. This option - gives you up to 3% performance improvement on AMD F15h - machines (where it is enabled by default) for a - CPU-intensive style benchmark, and it can vary highly in - a microbenchmark depending on workload and compiler. - - 32: only for 32-bit processes - 64: only for 64-bit processes - on: enable for both 32- and 64-bit processes - off: disable for both 32- and 64-bit processes - - alloc_snapshot [FTRACE] - Allocate the ftrace snapshot buffer on boot up when the - main buffer is allocated. This is handy if debugging - and you need to use tracing_snapshot() on boot up, and - do not want to use tracing_snapshot_alloc() as it needs - to be done where GFP_KERNEL allocations are allowed. - - amd_iommu= [HW,X86-64] - Pass parameters to the AMD IOMMU driver in the system. - Possible values are: - fullflush - enable flushing of IO/TLB entries when - they are unmapped. Otherwise they are - flushed before they will be reused, which - is a lot of faster - off - do not initialize any AMD IOMMU found in - the system - force_isolation - Force device isolation for all - devices. The IOMMU driver is not - allowed anymore to lift isolation - requirements as needed. This option - does not override iommu=pt - - amd_iommu_dump= [HW,X86-64] - Enable AMD IOMMU driver option to dump the ACPI table - for AMD IOMMU. With this option enabled, AMD IOMMU - driver will print ACPI tables for AMD IOMMU during - IOMMU initialization. - - amd_iommu_intr= [HW,X86-64] - Specifies one of the following AMD IOMMU interrupt - remapping modes: - legacy - Use legacy interrupt remapping mode. - vapic - Use virtual APIC mode, which allows IOMMU - to inject interrupts directly into guest. - This mode requires kvm-amd.avic=1. - (Default when IOMMU HW support is present.) - - amijoy.map= [HW,JOY] Amiga joystick support - Map of devices attached to JOY0DAT and JOY1DAT - Format: , - See also Documentation/input/joystick.txt - - analog.map= [HW,JOY] Analog joystick and gamepad support - Specifies type or capabilities of an analog joystick - connected to one of 16 gameports - Format: ,,.. - - apc= [HW,SPARC] - Power management functions (SPARCstation-4/5 + deriv.) - Format: noidle - Disable APC CPU standby support. SPARCstation-Fox does - not play well with APC CPU idle - disable it if you have - APC and your system crashes randomly. - - apic= [APIC,X86-32] Advanced Programmable Interrupt Controller - Change the output verbosity whilst booting - Format: { quiet (default) | verbose | debug } - Change the amount of debugging information output - when initialising the APIC and IO-APIC components. - - apic_extnmi= [APIC,X86] External NMI delivery setting - Format: { bsp (default) | all | none } - bsp: External NMI is delivered only to CPU 0 - all: External NMIs are broadcast to all CPUs as a - backup of CPU 0 - none: External NMI is masked for all CPUs. This is - useful so that a dump capture kernel won't be - shot down by NMI - - autoconf= [IPV6] - See Documentation/networking/ipv6.txt. - - show_lapic= [APIC,X86] Advanced Programmable Interrupt Controller - Limit apic dumping. The parameter defines the maximal - number of local apics being dumped. Also it is possible - to set it to "all" by meaning -- no limit here. - Format: { 1 (default) | 2 | ... | all }. - The parameter valid if only apic=debug or - apic=verbose is specified. - Example: apic=debug show_lapic=all - - apm= [APM] Advanced Power Management - See header of arch/x86/kernel/apm_32.c. - - arcrimi= [HW,NET] ARCnet - "RIM I" (entirely mem-mapped) cards - Format: ,, - - ataflop= [HW,M68k] - - atarimouse= [HW,MOUSE] Atari Mouse - - atkbd.extra= [HW] Enable extra LEDs and keys on IBM RapidAccess, - EzKey and similar keyboards - - atkbd.reset= [HW] Reset keyboard during initialization - - atkbd.set= [HW] Select keyboard code set - Format: (2 = AT (default), 3 = PS/2) - - atkbd.scroll= [HW] Enable scroll wheel on MS Office and similar - keyboards - - atkbd.softraw= [HW] Choose between synthetic and real raw mode - Format: (0 = real, 1 = synthetic (default)) - - atkbd.softrepeat= [HW] - Use software keyboard repeat - - audit= [KNL] Enable the audit sub-system - Format: { "0" | "1" } (0 = disabled, 1 = enabled) - 0 - kernel audit is disabled and can not be enabled - until the next reboot - unset - kernel audit is initialized but disabled and - will be fully enabled by the userspace auditd. - 1 - kernel audit is initialized and partially enabled, - storing at most audit_backlog_limit messages in - RAM until it is fully enabled by the userspace - auditd. - Default: unset - - audit_backlog_limit= [KNL] Set the audit queue size limit. - Format: (must be >=0) - Default: 64 - - bau= [X86_UV] Enable the BAU on SGI UV. The default - behavior is to disable the BAU (i.e. bau=0). - Format: { "0" | "1" } - 0 - Disable the BAU. - 1 - Enable the BAU. - unset - Disable the BAU. - - baycom_epp= [HW,AX25] - Format: , - - baycom_par= [HW,AX25] BayCom Parallel Port AX.25 Modem - Format: , - See header of drivers/net/hamradio/baycom_par.c. - - baycom_ser_fdx= [HW,AX25] - BayCom Serial Port AX.25 Modem (Full Duplex Mode) - Format: ,,[,] - See header of drivers/net/hamradio/baycom_ser_fdx.c. - - baycom_ser_hdx= [HW,AX25] - BayCom Serial Port AX.25 Modem (Half Duplex Mode) - Format: ,, - See header of drivers/net/hamradio/baycom_ser_hdx.c. - - blkdevparts= Manual partition parsing of block device(s) for - embedded devices based on command line input. - See Documentation/block/cmdline-partition.txt - - boot_delay= Milliseconds to delay each printk during boot. - Values larger than 10 seconds (10000) are changed to - no delay (0). - Format: integer - - bootmem_debug [KNL] Enable bootmem allocator debug messages. - - bert_disable [ACPI] - Disable BERT OS support on buggy BIOSes. - - bttv.card= [HW,V4L] bttv (bt848 + bt878 based grabber cards) - bttv.radio= Most important insmod options are available as - kernel args too. - bttv.pll= See Documentation/video4linux/bttv/Insmod-options - bttv.tuner= - - bulk_remove=off [PPC] This parameter disables the use of the pSeries - firmware feature for flushing multiple hpte entries - at a time. - - c101= [NET] Moxa C101 synchronous serial card - - cachesize= [BUGS=X86-32] Override level 2 CPU cache size detection. - Sometimes CPU hardware bugs make them report the cache - size incorrectly. The kernel will attempt work arounds - to fix known problems, but for some CPUs it is not - possible to determine what the correct size should be. - This option provides an override for these situations. - - ca_keys= [KEYS] This parameter identifies a specific key(s) on - the system trusted keyring to be used for certificate - trust validation. - format: { id: | builtin } - - cca= [MIPS] Override the kernel pages' cache coherency - algorithm. Accepted values range from 0 to 7 - inclusive. See arch/mips/include/asm/pgtable-bits.h - for platform specific values (SB1, Loongson3 and - others). - - ccw_timeout_log [S390] - See Documentation/s390/CommonIO for details. - - cgroup_disable= [KNL] Disable a particular controller - Format: {name of the controller(s) to disable} - The effects of cgroup_disable=foo are: - - foo isn't auto-mounted if you mount all cgroups in - a single hierarchy - - foo isn't visible as an individually mountable - subsystem - {Currently only "memory" controller deal with this and - cut the overhead, others just disable the usage. So - only cgroup_disable=memory is actually worthy} - - cgroup_no_v1= [KNL] Disable one, multiple, all cgroup controllers in v1 - Format: { controller[,controller...] | "all" } - Like cgroup_disable, but only applies to cgroup v1; - the blacklisted controllers remain available in cgroup2. - - cgroup.memory= [KNL] Pass options to the cgroup memory controller. - Format: - nosocket -- Disable socket memory accounting. - nokmem -- Disable kernel memory accounting. - - checkreqprot [SELINUX] Set initial checkreqprot flag value. - Format: { "0" | "1" } - See security/selinux/Kconfig help text. - 0 -- check protection applied by kernel (includes - any implied execute protection). - 1 -- check protection requested by application. - Default value is set via a kernel config option. - Value can be changed at runtime via - /selinux/checkreqprot. - - cio_ignore= [S390] - See Documentation/s390/CommonIO for details. - clk_ignore_unused - [CLK] - Prevents the clock framework from automatically gating - clocks that have not been explicitly enabled by a Linux - device driver but are enabled in hardware at reset or - by the bootloader/firmware. Note that this does not - force such clocks to be always-on nor does it reserve - those clocks in any way. This parameter is useful for - debug and development, but should not be needed on a - platform with proper driver support. For more - information, see Documentation/clk.txt. - - clock= [BUGS=X86-32, HW] gettimeofday clocksource override. - [Deprecated] - Forces specified clocksource (if available) to be used - when calculating gettimeofday(). If specified - clocksource is not available, it defaults to PIT. - Format: { pit | tsc | cyclone | pmtmr } - - clocksource= Override the default clocksource - Format: - Override the default clocksource and use the clocksource - with the name specified. - Some clocksource names to choose from, depending on - the platform: - [all] jiffies (this is the base, fallback clocksource) - [ACPI] acpi_pm - [ARM] imx_timer1,OSTS,netx_timer,mpu_timer2, - pxa_timer,timer3,32k_counter,timer0_1 - [AVR32] avr32 - [X86-32] pit,hpet,tsc; - scx200_hrt on Geode; cyclone on IBM x440 - [MIPS] MIPS - [PARISC] cr16 - [S390] tod - [SH] SuperH - [SPARC64] tick - [X86-64] hpet,tsc - - clocksource.arm_arch_timer.evtstrm= - [ARM,ARM64] - Format: - Enable/disable the eventstream feature of the ARM - architected timer so that code using WFE-based polling - loops can be debugged more effectively on production - systems. - - clocksource.arm_arch_timer.fsl-a008585= - [ARM64] - Format: - Enable/disable the workaround of Freescale/NXP - erratum A-008585. This can be useful for KVM - guests, if the guest device tree doesn't show the - erratum. If unspecified, the workaround is - enabled based on the device tree. - - clearcpuid=BITNUM [X86] - Disable CPUID feature X for the kernel. See - arch/x86/include/asm/cpufeatures.h for the valid bit - numbers. Note the Linux specific bits are not necessarily - stable over kernel options, but the vendor specific - ones should be. - Also note that user programs calling CPUID directly - or using the feature without checking anything - will still see it. This just prevents it from - being used by the kernel or shown in /proc/cpuinfo. - Also note the kernel might malfunction if you disable - some critical bits. - - cma=nn[MG]@[start[MG][-end[MG]]] - [ARM,X86,KNL] - Sets the size of kernel global memory area for - contiguous memory allocations and optionally the - placement constraint by the physical address range of - memory allocations. A value of 0 disables CMA - altogether. For more information, see - include/linux/dma-contiguous.h - - cmo_free_hint= [PPC] Format: { yes | no } - Specify whether pages are marked as being inactive - when they are freed. This is used in CMO environments - to determine OS memory pressure for page stealing by - a hypervisor. - Default: yes - - coherent_pool=nn[KMG] [ARM,KNL] - Sets the size of memory pool for coherent, atomic dma - allocations, by default set to 256K. - - code_bytes [X86] How many bytes of object code to print - in an oops report. - Range: 0 - 8192 - Default: 64 - - com20020= [HW,NET] ARCnet - COM20020 chipset - Format: - [,[,[,[,[,]]]]] - - com90io= [HW,NET] ARCnet - COM90xx chipset (IO-mapped buffers) - Format: [,] - - com90xx= [HW,NET] - ARCnet - COM90xx chipset (memory-mapped buffers) - Format: [,[,]] - - condev= [HW,S390] console device - conmode= - - console= [KNL] Output console device and options. - - tty Use the virtual console device . - - ttyS[,options] - ttyUSB0[,options] - Use the specified serial port. The options are of - the form "bbbbpnf", where "bbbb" is the baud rate, - "p" is parity ("n", "o", or "e"), "n" is number of - bits, and "f" is flow control ("r" for RTS or - omit it). Default is "9600n8". - - See Documentation/serial-console.txt for more - information. See - Documentation/networking/netconsole.txt for an - alternative. - - uart[8250],io,[,options] - uart[8250],mmio,[,options] - uart[8250],mmio16,[,options] - uart[8250],mmio32,[,options] - uart[8250],0x[,options] - Start an early, polled-mode console on the 8250/16550 - UART at the specified I/O port or MMIO address, - switching to the matching ttyS device later. - MMIO inter-register address stride is either 8-bit - (mmio), 16-bit (mmio16), or 32-bit (mmio32). - If none of [io|mmio|mmio16|mmio32], is assumed - to be equivalent to 'mmio'. 'options' are specified in - the same format described for ttyS above; if unspecified, - the h/w is not re-initialized. - - hvc Use the hypervisor console device . This is for - both Xen and PowerPC hypervisors. - - If the device connected to the port is not a TTY but a braille - device, prepend "brl," before the device type, for instance - console=brl,ttyS0 - For now, only VisioBraille is supported. - - consoleblank= [KNL] The console blank (screen saver) timeout in - seconds. Defaults to 10*60 = 10mins. A value of 0 - disables the blank timer. - - coredump_filter= - [KNL] Change the default value for - /proc//coredump_filter. - See also Documentation/filesystems/proc.txt. - - cpuidle.off=1 [CPU_IDLE] - disable the cpuidle sub-system - - cpu_init_udelay=N - [X86] Delay for N microsec between assert and de-assert - of APIC INIT to start processors. This delay occurs - on every CPU online, such as boot, and resume from suspend. - Default: 10000 - - cpcihp_generic= [HW,PCI] Generic port I/O CompactPCI driver - Format: - ,,,[,] - - crashkernel=size[KMG][@offset[KMG]] - [KNL] Using kexec, Linux can switch to a 'crash kernel' - upon panic. This parameter reserves the physical - memory region [offset, offset + size] for that kernel - image. If '@offset' is omitted, then a suitable offset - is selected automatically. Check - Documentation/kdump/kdump.txt for further details. - - crashkernel=range1:size1[,range2:size2,...][@offset] - [KNL] Same as above, but depends on the memory - in the running system. The syntax of range is - start-[end] where start and end are both - a memory unit (amount[KMG]). See also - Documentation/kdump/kdump.txt for an example. - - crashkernel=size[KMG],high - [KNL, x86_64] range could be above 4G. Allow kernel - to allocate physical memory region from top, so could - be above 4G if system have more than 4G ram installed. - Otherwise memory region will be allocated below 4G, if - available. - It will be ignored if crashkernel=X is specified. - crashkernel=size[KMG],low - [KNL, x86_64] range under 4G. When crashkernel=X,high - is passed, kernel could allocate physical memory region - above 4G, that cause second kernel crash on system - that require some amount of low memory, e.g. swiotlb - requires at least 64M+32K low memory, also enough extra - low memory is needed to make sure DMA buffers for 32-bit - devices won't run out. Kernel would try to allocate at - at least 256M below 4G automatically. - This one let user to specify own low range under 4G - for second kernel instead. - 0: to disable low allocation. - It will be ignored when crashkernel=X,high is not used - or memory reserved is below 4G. - - cryptomgr.notests - [KNL] Disable crypto self-tests - - cs89x0_dma= [HW,NET] - Format: - - cs89x0_media= [HW,NET] - Format: { rj45 | aui | bnc } - - dasd= [HW,NET] - See header of drivers/s390/block/dasd_devmap.c. - - db9.dev[2|3]= [HW,JOY] Multisystem joystick support via parallel port - (one device per port) - Format: , - See also Documentation/input/joystick-parport.txt - - ddebug_query= [KNL,DYNAMIC_DEBUG] Enable debug messages at early boot - time. See Documentation/dynamic-debug-howto.txt for - details. Deprecated, see dyndbg. - - debug [KNL] Enable kernel debugging (events log level). - - debug_locks_verbose= - [KNL] verbose self-tests - Format=<0|1> - Print debugging info while doing the locking API - self-tests. - We default to 0 (no extra messages), setting it to - 1 will print _a lot_ more information - normally - only useful to kernel developers. - - debug_objects [KNL] Enable object debugging - - no_debug_objects - [KNL] Disable object debugging - - debug_guardpage_minorder= - [KNL] When CONFIG_DEBUG_PAGEALLOC is set, this - parameter allows control of the order of pages that will - be intentionally kept free (and hence protected) by the - buddy allocator. Bigger value increase the probability - of catching random memory corruption, but reduce the - amount of memory for normal system use. The maximum - possible value is MAX_ORDER/2. Setting this parameter - to 1 or 2 should be enough to identify most random - memory corruption problems caused by bugs in kernel or - driver code when a CPU writes to (or reads from) a - random memory location. Note that there exists a class - of memory corruptions problems caused by buggy H/W or - F/W or by drivers badly programing DMA (basically when - memory is written at bus level and the CPU MMU is - bypassed) which are not detectable by - CONFIG_DEBUG_PAGEALLOC, hence this option will not help - tracking down these problems. - - debug_pagealloc= - [KNL] When CONFIG_DEBUG_PAGEALLOC is set, this - parameter enables the feature at boot time. In - default, it is disabled. We can avoid allocating huge - chunk of memory for debug pagealloc if we don't enable - it at boot time and the system will work mostly same - with the kernel built without CONFIG_DEBUG_PAGEALLOC. - on: enable the feature - - debugpat [X86] Enable PAT debugging - - decnet.addr= [HW,NET] - Format: [,] - See also Documentation/networking/decnet.txt. - - default_hugepagesz= - [same as hugepagesz=] The size of the default - HugeTLB page size. This is the size represented by - the legacy /proc/ hugepages APIs, used for SHM, and - default size when mounting hugetlbfs filesystems. - Defaults to the default architecture's huge page size - if not specified. - - dhash_entries= [KNL] - Set number of hash buckets for dentry cache. - - disable_1tb_segments [PPC] - Disables the use of 1TB hash page table segments. This - causes the kernel to fall back to 256MB segments which - can be useful when debugging issues that require an SLB - miss to occur. - - disable= [IPV6] - See Documentation/networking/ipv6.txt. - - disable_radix [PPC] - Disable RADIX MMU mode on POWER9 - - disable_cpu_apicid= [X86,APIC,SMP] - Format: - The number of initial APIC ID for the - corresponding CPU to be disabled at boot, - mostly used for the kdump 2nd kernel to - disable BSP to wake up multiple CPUs without - causing system reset or hang due to sending - INIT from AP to BSP. - - disable_ddw [PPC/PSERIES] - Disable Dynamic DMA Window support. Use this if - to workaround buggy firmware. - - disable_ipv6= [IPV6] - See Documentation/networking/ipv6.txt. - - disable_mtrr_cleanup [X86] - The kernel tries to adjust MTRR layout from continuous - to discrete, to make X server driver able to add WB - entry later. This parameter disables that. - - disable_mtrr_trim [X86, Intel and AMD only] - By default the kernel will trim any uncacheable - memory out of your available memory pool based on - MTRR settings. This parameter disables that behavior, - possibly causing your machine to run very slowly. - - disable_timer_pin_1 [X86] - Disable PIN 1 of APIC timer - Can be useful to work around chipset bugs. - - dis_ucode_ldr [X86] Disable the microcode loader. - - dma_debug=off If the kernel is compiled with DMA_API_DEBUG support, - this option disables the debugging code at boot. - - dma_debug_entries= - This option allows to tune the number of preallocated - entries for DMA-API debugging code. One entry is - required per DMA-API allocation. Use this if the - DMA-API debugging code disables itself because the - architectural default is too low. - - dma_debug_driver= - With this option the DMA-API debugging driver - filter feature can be enabled at boot time. Just - pass the driver to filter for as the parameter. - The filter can be disabled or changed to another - driver later using sysfs. - - drm_kms_helper.edid_firmware=[:][,[:]] - Broken monitors, graphic adapters, KVMs and EDIDless - panels may send no or incorrect EDID data sets. - This parameter allows to specify an EDID data sets - in the /lib/firmware directory that are used instead. - Generic built-in EDID data sets are used, if one of - edid/1024x768.bin, edid/1280x1024.bin, - edid/1680x1050.bin, or edid/1920x1080.bin is given - and no file with the same name exists. Details and - instructions how to build your own EDID data are - available in Documentation/EDID/HOWTO.txt. An EDID - data set will only be used for a particular connector, - if its name and a colon are prepended to the EDID - name. Each connector may use a unique EDID data - set by separating the files with a comma. An EDID - data set with no connector name will be used for - any connectors not explicitly specified. - - dscc4.setup= [NET] - - dyndbg[="val"] [KNL,DYNAMIC_DEBUG] - module.dyndbg[="val"] - Enable debug messages at boot time. See - Documentation/dynamic-debug-howto.txt for details. - - nompx [X86] Disables Intel Memory Protection Extensions. - See Documentation/x86/intel_mpx.txt for more - information about the feature. - - nopku [X86] Disable Memory Protection Keys CPU feature found - in some Intel CPUs. - - eagerfpu= [X86] - on enable eager fpu restore - off disable eager fpu restore - auto selects the default scheme, which automatically - enables eagerfpu restore for xsaveopt. - - module.async_probe [KNL] - Enable asynchronous probe on this module. - - early_ioremap_debug [KNL] - Enable debug messages in early_ioremap support. This - is useful for tracking down temporary early mappings - which are not unmapped. - - earlycon= [KNL] Output early console device and options. - - When used with no options, the early console is - determined by the stdout-path property in device - tree's chosen node. - - cdns,[,options] - Start an early, polled-mode console on a Cadence - (xuartps) serial port at the specified address. Only - supported option is baud rate. If baud rate is not - specified, the serial port must already be setup and - configured. - - uart[8250],io,[,options] - uart[8250],mmio,[,options] - uart[8250],mmio32,[,options] - uart[8250],mmio32be,[,options] - uart[8250],0x[,options] - Start an early, polled-mode console on the 8250/16550 - UART at the specified I/O port or MMIO address. - MMIO inter-register address stride is either 8-bit - (mmio) or 32-bit (mmio32 or mmio32be). - If none of [io|mmio|mmio32|mmio32be], is assumed - to be equivalent to 'mmio'. 'options' are specified - in the same format described for "console=ttyS"; if - unspecified, the h/w is not initialized. - - pl011, - pl011,mmio32, - Start an early, polled-mode console on a pl011 serial - port at the specified address. The pl011 serial port - must already be setup and configured. Options are not - yet supported. If 'mmio32' is specified, then only - the driver will use only 32-bit accessors to read/write - the device registers. - - meson, - Start an early, polled-mode console on a meson serial - port at the specified address. The serial port must - already be setup and configured. Options are not yet - supported. - - msm_serial, - Start an early, polled-mode console on an msm serial - port at the specified address. The serial port - must already be setup and configured. Options are not - yet supported. - - msm_serial_dm, - Start an early, polled-mode console on an msm serial - dm port at the specified address. The serial port - must already be setup and configured. Options are not - yet supported. - - smh Use ARM semihosting calls for early console. - - s3c2410, - s3c2412, - s3c2440, - s3c6400, - s5pv210, - exynos4210, - Use early console provided by serial driver available - on Samsung SoCs, requires selecting proper type and - a correct base address of the selected UART port. The - serial port must already be setup and configured. - Options are not yet supported. - - lpuart, - lpuart32, - Use early console provided by Freescale LP UART driver - found on Freescale Vybrid and QorIQ LS1021A processors. - A valid base address must be provided, and the serial - port must already be setup and configured. - - armada3700_uart, - Start an early, polled-mode console on the - Armada 3700 serial port at the specified - address. The serial port must already be setup - and configured. Options are not yet supported. - - earlyprintk= [X86,SH,BLACKFIN,ARM,M68k] - earlyprintk=vga - earlyprintk=efi - earlyprintk=xen - earlyprintk=serial[,ttySn[,baudrate]] - earlyprintk=serial[,0x...[,baudrate]] - earlyprintk=ttySn[,baudrate] - earlyprintk=dbgp[debugController#] - earlyprintk=pciserial,bus:device.function[,baudrate] - - earlyprintk is useful when the kernel crashes before - the normal console is initialized. It is not enabled by - default because it has some cosmetic problems. - - Append ",keep" to not disable it when the real console - takes over. - - Only one of vga, efi, serial, or usb debug port can - be used at a time. - - Currently only ttyS0 and ttyS1 may be specified by - name. Other I/O ports may be explicitly specified - on some architectures (x86 and arm at least) by - replacing ttySn with an I/O port address, like this: - earlyprintk=serial,0x1008,115200 - You can find the port for a given device in - /proc/tty/driver/serial: - 2: uart:ST16650V2 port:00001008 irq:18 ... - - Interaction with the standard serial driver is not - very good. - - The VGA and EFI output is eventually overwritten by - the real console. - - The xen output can only be used by Xen PV guests. - - edac_report= [HW,EDAC] Control how to report EDAC event - Format: {"on" | "off" | "force"} - on: enable EDAC to report H/W event. May be overridden - by other higher priority error reporting module. - off: disable H/W event reporting through EDAC. - force: enforce the use of EDAC to report H/W event. - default: on. - - ekgdboc= [X86,KGDB] Allow early kernel console debugging - ekgdboc=kbd - - This is designed to be used in conjunction with - the boot argument: earlyprintk=vga - - edd= [EDD] - Format: {"off" | "on" | "skip[mbr]"} - - efi= [EFI] - Format: { "old_map", "nochunk", "noruntime", "debug" } - old_map [X86-64]: switch to the old ioremap-based EFI - runtime services mapping. 32-bit still uses this one by - default. - nochunk: disable reading files in "chunks" in the EFI - boot stub, as chunking can cause problems with some - firmware implementations. - noruntime : disable EFI runtime services support - debug: enable misc debug output - - efi_no_storage_paranoia [EFI; X86] - Using this parameter you can use more than 50% of - your efi variable storage. Use this parameter only if - you are really sure that your UEFI does sane gc and - fulfills the spec otherwise your board may brick. - - efi_fake_mem= nn[KMG]@ss[KMG]:aa[,nn[KMG]@ss[KMG]:aa,..] [EFI; X86] - Add arbitrary attribute to specific memory range by - updating original EFI memory map. - Region of memory which aa attribute is added to is - from ss to ss+nn. - If efi_fake_mem=2G@4G:0x10000,2G@0x10a0000000:0x10000 - is specified, EFI_MEMORY_MORE_RELIABLE(0x10000) - attribute is added to range 0x100000000-0x180000000 and - 0x10a0000000-0x1120000000. - - Using this parameter you can do debugging of EFI memmap - related feature. For example, you can do debugging of - Address Range Mirroring feature even if your box - doesn't support it. - - efivar_ssdt= [EFI; X86] Name of an EFI variable that contains an SSDT - that is to be dynamically loaded by Linux. If there are - multiple variables with the same name but with different - vendor GUIDs, all of them will be loaded. See - Documentation/acpi/ssdt-overlays.txt for details. - - - eisa_irq_edge= [PARISC,HW] - See header of drivers/parisc/eisa.c. - - elanfreq= [X86-32] - See comment before function elanfreq_setup() in - arch/x86/kernel/cpu/cpufreq/elanfreq.c. - - elevator= [IOSCHED] - Format: {"cfq" | "deadline" | "noop"} - See Documentation/block/cfq-iosched.txt and - Documentation/block/deadline-iosched.txt for details. - - elfcorehdr=[size[KMG]@]offset[KMG] [IA64,PPC,SH,X86,S390] - Specifies physical address of start of kernel core - image elf header and optionally the size. Generally - kexec loader will pass this option to capture kernel. - See Documentation/kdump/kdump.txt for details. - - enable_mtrr_cleanup [X86] - The kernel tries to adjust MTRR layout from continuous - to discrete, to make X server driver able to add WB - entry later. This parameter enables that. - - enable_timer_pin_1 [X86] - Enable PIN 1 of APIC timer - Can be useful to work around chipset bugs - (in particular on some ATI chipsets). - The kernel tries to set a reasonable default. - - enforcing [SELINUX] Set initial enforcing status. - Format: {"0" | "1"} - See security/selinux/Kconfig help text. - 0 -- permissive (log only, no denials). - 1 -- enforcing (deny and log). - Default value is 0. - Value can be changed at runtime via /selinux/enforce. - - erst_disable [ACPI] - Disable Error Record Serialization Table (ERST) - support. - - ether= [HW,NET] Ethernet cards parameters - This option is obsoleted by the "netdev=" option, which - has equivalent usage. See its documentation for details. - - evm= [EVM] - Format: { "fix" } - Permit 'security.evm' to be updated regardless of - current integrity status. - - failslab= - fail_page_alloc= - fail_make_request=[KNL] - General fault injection mechanism. - Format: ,,, - See also Documentation/fault-injection/. - - floppy= [HW] - See Documentation/blockdev/floppy.txt. - - force_pal_cache_flush - [IA-64] Avoid check_sal_cache_flush which may hang on - buggy SAL_CACHE_FLUSH implementations. Using this - parameter will force ia64_sal_cache_flush to call - ia64_pal_cache_flush instead of SAL_CACHE_FLUSH. - - forcepae [X86-32] - Forcefully enable Physical Address Extension (PAE). - Many Pentium M systems disable PAE but may have a - functionally usable PAE implementation. - Warning: use of this parameter will taint the kernel - and may cause unknown problems. - - ftrace=[tracer] - [FTRACE] will set and start the specified tracer - as early as possible in order to facilitate early - boot debugging. - - ftrace_dump_on_oops[=orig_cpu] - [FTRACE] will dump the trace buffers on oops. - If no parameter is passed, ftrace will dump - buffers of all CPUs, but if you pass orig_cpu, it will - dump only the buffer of the CPU that triggered the - oops. - - ftrace_filter=[function-list] - [FTRACE] Limit the functions traced by the function - tracer at boot up. function-list is a comma separated - list of functions. This list can be changed at run - time by the set_ftrace_filter file in the debugfs - tracing directory. - - ftrace_notrace=[function-list] - [FTRACE] Do not trace the functions specified in - function-list. This list can be changed at run time - by the set_ftrace_notrace file in the debugfs - tracing directory. - - ftrace_graph_filter=[function-list] - [FTRACE] Limit the top level callers functions traced - by the function graph tracer at boot up. - function-list is a comma separated list of functions - that can be changed at run time by the - set_graph_function file in the debugfs tracing directory. - - ftrace_graph_notrace=[function-list] - [FTRACE] Do not trace from the functions specified in - function-list. This list is a comma separated list of - functions that can be changed at run time by the - set_graph_notrace file in the debugfs tracing directory. - - gamecon.map[2|3]= - [HW,JOY] Multisystem joystick and NES/SNES/PSX pad - support via parallel port (up to 5 devices per port) - Format: ,,,,, - See also Documentation/input/joystick-parport.txt - - gamma= [HW,DRM] - - gart_fix_e820= [X86_64] disable the fix e820 for K8 GART - Format: off | on - default: on - - gcov_persist= [GCOV] When non-zero (default), profiling data for - kernel modules is saved and remains accessible via - debugfs, even when the module is unloaded/reloaded. - When zero, profiling data is discarded and associated - debugfs files are removed at module unload time. - - gpt [EFI] Forces disk with valid GPT signature but - invalid Protective MBR to be treated as GPT. If the - primary GPT is corrupted, it enables the backup/alternate - GPT to be used instead. - - grcan.enable0= [HW] Configuration of physical interface 0. Determines - the "Enable 0" bit of the configuration register. - Format: 0 | 1 - Default: 0 - grcan.enable1= [HW] Configuration of physical interface 1. Determines - the "Enable 0" bit of the configuration register. - Format: 0 | 1 - Default: 0 - grcan.select= [HW] Select which physical interface to use. - Format: 0 | 1 - Default: 0 - grcan.txsize= [HW] Sets the size of the tx buffer. - Format: such that (txsize & ~0x1fffc0) == 0. - Default: 1024 - grcan.rxsize= [HW] Sets the size of the rx buffer. - Format: such that (rxsize & ~0x1fffc0) == 0. - Default: 1024 - - gpio-mockup.gpio_mockup_ranges - [HW] Sets the ranges of gpiochip of for this device. - Format: ,,,... - - hardlockup_all_cpu_backtrace= - [KNL] Should the hard-lockup detector generate - backtraces on all cpus. - Format: - - hashdist= [KNL,NUMA] Large hashes allocated during boot - are distributed across NUMA nodes. Defaults on - for 64-bit NUMA, off otherwise. - Format: 0 | 1 (for off | on) - - hcl= [IA-64] SGI's Hardware Graph compatibility layer - - hd= [EIDE] (E)IDE hard drive subsystem geometry - Format: ,, - - hest_disable [ACPI] - Disable Hardware Error Source Table (HEST) support; - corresponding firmware-first mode error processing - logic will be disabled. - - highmem=nn[KMG] [KNL,BOOT] forces the highmem zone to have an exact - size of . This works even on boxes that have no - highmem otherwise. This also works to reduce highmem - size on bigger boxes. - - highres= [KNL] Enable/disable high resolution timer mode. - Valid parameters: "on", "off" - Default: "on" - - hisax= [HW,ISDN] - See Documentation/isdn/README.HiSax. - - hlt [BUGS=ARM,SH] - - hpet= [X86-32,HPET] option to control HPET usage - Format: { enable (default) | disable | force | - verbose } - disable: disable HPET and use PIT instead - force: allow force enabled of undocumented chips (ICH4, - VIA, nVidia) - verbose: show contents of HPET registers during setup - - hpet_mmap= [X86, HPET_MMAP] Allow userspace to mmap HPET - registers. Default set by CONFIG_HPET_MMAP_DEFAULT. - - hugepages= [HW,X86-32,IA-64] HugeTLB pages to allocate at boot. - hugepagesz= [HW,IA-64,PPC,X86-64] The size of the HugeTLB pages. - On x86-64 and powerpc, this option can be specified - multiple times interleaved with hugepages= to reserve - huge pages of different sizes. Valid pages sizes on - x86-64 are 2M (when the CPU supports "pse") and 1G - (when the CPU supports the "pdpe1gb" cpuinfo flag). - - hvc_iucv= [S390] Number of z/VM IUCV hypervisor console (HVC) - terminal devices. Valid values: 0..8 - hvc_iucv_allow= [S390] Comma-separated list of z/VM user IDs. - If specified, z/VM IUCV HVC accepts connections - from listed z/VM user IDs only. - - hwthread_map= [METAG] Comma-separated list of Linux cpu id to - hardware thread id mappings. - Format: : - - keep_bootcon [KNL] - Do not unregister boot console at start. This is only - useful for debugging when something happens in the window - between unregistering the boot console and initializing - the real console. - - i2c_bus= [HW] Override the default board specific I2C bus speed - or register an additional I2C bus that is not - registered from board initialization code. - Format: - , - - i8042.debug [HW] Toggle i8042 debug mode - i8042.unmask_kbd_data - [HW] Enable printing of interrupt data from the KBD port - (disabled by default, and as a pre-condition - requires that i8042.debug=1 be enabled) - i8042.direct [HW] Put keyboard port into non-translated mode - i8042.dumbkbd [HW] Pretend that controller can only read data from - keyboard and cannot control its state - (Don't attempt to blink the leds) - i8042.noaux [HW] Don't check for auxiliary (== mouse) port - i8042.nokbd [HW] Don't check/create keyboard port - i8042.noloop [HW] Disable the AUX Loopback command while probing - for the AUX port - i8042.nomux [HW] Don't check presence of an active multiplexing - controller - i8042.nopnp [HW] Don't use ACPIPnP / PnPBIOS to discover KBD/AUX - controllers - i8042.notimeout [HW] Ignore timeout condition signalled by controller - i8042.reset [HW] Reset the controller during init, cleanup and - suspend-to-ram transitions, only during s2r - transitions, or never reset - Format: { 1 | Y | y | 0 | N | n } - 1, Y, y: always reset controller - 0, N, n: don't ever reset controller - Default: only on s2r transitions on x86; most other - architectures force reset to be always executed - i8042.unlock [HW] Unlock (ignore) the keylock - i8042.kbdreset [HW] Reset device connected to KBD port - - i810= [HW,DRM] - - i8k.ignore_dmi [HW] Continue probing hardware even if DMI data - indicates that the driver is running on unsupported - hardware. - i8k.force [HW] Activate i8k driver even if SMM BIOS signature - does not match list of supported models. - i8k.power_status - [HW] Report power status in /proc/i8k - (disabled by default) - i8k.restricted [HW] Allow controlling fans only if SYS_ADMIN - capability is set. - - i915.invert_brightness= - [DRM] Invert the sense of the variable that is used to - set the brightness of the panel backlight. Normally a - brightness value of 0 indicates backlight switched off, - and the maximum of the brightness value sets the backlight - to maximum brightness. If this parameter is set to 0 - (default) and the machine requires it, or this parameter - is set to 1, a brightness value of 0 sets the backlight - to maximum brightness, and the maximum of the brightness - value switches the backlight off. - -1 -- never invert brightness - 0 -- machine default - 1 -- force brightness inversion - - icn= [HW,ISDN] - Format: [,[,[,]]] - - ide-core.nodma= [HW] (E)IDE subsystem - Format: =0.0 to prevent dma on hda, =0.1 hdb =1.0 hdc - .vlb_clock .pci_clock .noflush .nohpa .noprobe .nowerr - .cdrom .chs .ignore_cable are additional options - See Documentation/ide/ide.txt. - - ide-generic.probe-mask= [HW] (E)IDE subsystem - Format: - Probe mask for legacy ISA IDE ports. Depending on - platform up to 6 ports are supported, enabled by - setting corresponding bits in the mask to 1. The - default value is 0x0, which has a special meaning. - On systems that have PCI, it triggers scanning the - PCI bus for the first and the second port, which - are then probed. On systems without PCI the value - of 0x0 enables probing the two first ports as if it - was 0x3. - - ide-pci-generic.all-generic-ide [HW] (E)IDE subsystem - Claim all unknown PCI IDE storage controllers. - - idle= [X86] - Format: idle=poll, idle=halt, idle=nomwait - Poll forces a polling idle loop that can slightly - improve the performance of waking up a idle CPU, but - will use a lot of power and make the system run hot. - Not recommended. - idle=halt: Halt is forced to be used for CPU idle. - In such case C2/C3 won't be used again. - idle=nomwait: Disable mwait for CPU C-states - - ieee754= [MIPS] Select IEEE Std 754 conformance mode - Format: { strict | legacy | 2008 | relaxed } - Default: strict - - Choose which programs will be accepted for execution - based on the IEEE 754 NaN encoding(s) supported by - the FPU and the NaN encoding requested with the value - of an ELF file header flag individually set by each - binary. Hardware implementations are permitted to - support either or both of the legacy and the 2008 NaN - encoding mode. - - Available settings are as follows: - strict accept binaries that request a NaN encoding - supported by the FPU - legacy only accept legacy-NaN binaries, if supported - by the FPU - 2008 only accept 2008-NaN binaries, if supported - by the FPU - relaxed accept any binaries regardless of whether - supported by the FPU - - The FPU emulator is always able to support both NaN - encodings, so if no FPU hardware is present or it has - been disabled with 'nofpu', then the settings of - 'legacy' and '2008' strap the emulator accordingly, - 'relaxed' straps the emulator for both legacy-NaN and - 2008-NaN, whereas 'strict' enables legacy-NaN only on - legacy processors and both NaN encodings on MIPS32 or - MIPS64 CPUs. - - The setting for ABS.fmt/NEG.fmt instruction execution - mode generally follows that for the NaN encoding, - except where unsupported by hardware. - - ignore_loglevel [KNL] - Ignore loglevel setting - this will print /all/ - kernel messages to the console. Useful for debugging. - We also add it as printk module parameter, so users - could change it dynamically, usually by - /sys/module/printk/parameters/ignore_loglevel. - - ignore_rlimit_data - Ignore RLIMIT_DATA setting for data mappings, - print warning at first misuse. Can be changed via - /sys/module/kernel/parameters/ignore_rlimit_data. - - ihash_entries= [KNL] - Set number of hash buckets for inode cache. - - ima_appraise= [IMA] appraise integrity measurements - Format: { "off" | "enforce" | "fix" | "log" } - default: "enforce" - - ima_appraise_tcb [IMA] - The builtin appraise policy appraises all files - owned by uid=0. - - ima_hash= [IMA] - Format: { md5 | sha1 | rmd160 | sha256 | sha384 - | sha512 | ... } - default: "sha1" - - The list of supported hash algorithms is defined - in crypto/hash_info.h. - - ima_policy= [IMA] - The builtin measurement policy to load during IMA - setup. Specyfing "tcb" as the value, measures all - programs exec'd, files mmap'd for exec, and all files - opened with the read mode bit set by either the - effective uid (euid=0) or uid=0. - Format: "tcb" - - ima_tcb [IMA] Deprecated. Use ima_policy= instead. - Load a policy which meets the needs of the Trusted - Computing Base. This means IMA will measure all - programs exec'd, files mmap'd for exec, and all files - opened for read by uid=0. - - ima_template= [IMA] - Select one of defined IMA measurements template formats. - Formats: { "ima" | "ima-ng" | "ima-sig" } - Default: "ima-ng" - - ima_template_fmt= - [IMA] Define a custom template format. - Format: { "field1|...|fieldN" } - - ima.ahash_minsize= [IMA] Minimum file size for asynchronous hash usage - Format: - Set the minimal file size for using asynchronous hash. - If left unspecified, ahash usage is disabled. - - ahash performance varies for different data sizes on - different crypto accelerators. This option can be used - to achieve the best performance for a particular HW. - - ima.ahash_bufsize= [IMA] Asynchronous hash buffer size - Format: - Set hashing buffer size. Default: 4k. - - ahash performance varies for different chunk sizes on - different crypto accelerators. This option can be used - to achieve best performance for particular HW. - - init= [KNL] - Format: - Run specified binary instead of /sbin/init as init - process. - - initcall_debug [KNL] Trace initcalls as they are executed. Useful - for working out where the kernel is dying during - startup. - - initcall_blacklist= [KNL] Do not execute a comma-separated list of - initcall functions. Useful for debugging built-in - modules and initcalls. - - initrd= [BOOT] Specify the location of the initial ramdisk - - init_pkru= [x86] Specify the default memory protection keys rights - register contents for all processes. 0x55555554 by - default (disallow access to all but pkey 0). Can - override in debugfs after boot. - - inport.irq= [HW] Inport (ATI XL and Microsoft) busmouse driver - Format: - - int_pln_enable [x86] Enable power limit notification interrupt - - integrity_audit=[IMA] - Format: { "0" | "1" } - 0 -- basic integrity auditing messages. (Default) - 1 -- additional integrity auditing messages. - - intel_iommu= [DMAR] Intel IOMMU driver (DMAR) option - on - Enable intel iommu driver. - off - Disable intel iommu driver. - igfx_off [Default Off] - By default, gfx is mapped as normal device. If a gfx - device has a dedicated DMAR unit, the DMAR unit is - bypassed by not enabling DMAR with this option. In - this case, gfx device will use physical address for - DMA. - forcedac [x86_64] - With this option iommu will not optimize to look - for io virtual address below 32-bit forcing dual - address cycle on pci bus for cards supporting greater - than 32-bit addressing. The default is to look - for translation below 32-bit and if not available - then look in the higher range. - strict [Default Off] - With this option on every unmap_single operation will - result in a hardware IOTLB flush operation as opposed - to batching them for performance. - sp_off [Default Off] - By default, super page will be supported if Intel IOMMU - has the capability. With this option, super page will - not be supported. - ecs_off [Default Off] - By default, extended context tables will be supported if - the hardware advertises that it has support both for the - extended tables themselves, and also PASID support. With - this option set, extended tables will not be used even - on hardware which claims to support them. - - intel_idle.max_cstate= [KNL,HW,ACPI,X86] - 0 disables intel_idle and fall back on acpi_idle. - 1 to 9 specify maximum depth of C-state. - - intel_pstate= [X86] - disable - Do not enable intel_pstate as the default - scaling driver for the supported processors - force - Enable intel_pstate on systems that prohibit it by default - in favor of acpi-cpufreq. Forcing the intel_pstate driver - instead of acpi-cpufreq may disable platform features, such - as thermal controls and power capping, that rely on ACPI - P-States information being indicated to OSPM and therefore - should be used with caution. This option does not work with - processors that aren't supported by the intel_pstate driver - or on platforms that use pcc-cpufreq instead of acpi-cpufreq. - no_hwp - Do not enable hardware P state control (HWP) - if available. - hwp_only - Only load intel_pstate on systems which support - hardware P state control (HWP) if available. - support_acpi_ppc - Enforce ACPI _PPC performance limits. If the Fixed ACPI - Description Table, specifies preferred power management - profile as "Enterprise Server" or "Performance Server", - then this feature is turned on by default. - - intremap= [X86-64, Intel-IOMMU] - on enable Interrupt Remapping (default) - off disable Interrupt Remapping - nosid disable Source ID checking - no_x2apic_optout - BIOS x2APIC opt-out request will be ignored - nopost disable Interrupt Posting - - iomem= Disable strict checking of access to MMIO memory - strict regions from userspace. - relaxed - - iommu= [x86] - off - force - noforce - biomerge - panic - nopanic - merge - nomerge - forcesac - soft - pt [x86, IA-64] - nobypass [PPC/POWERNV] - Disable IOMMU bypass, using IOMMU for PCI devices. - - - io7= [HW] IO7 for Marvel based alpha systems - See comment before marvel_specify_io7 in - arch/alpha/kernel/core_marvel.c. - - io_delay= [X86] I/O delay method - 0x80 - Standard port 0x80 based delay - 0xed - Alternate port 0xed based delay (needed on some systems) - udelay - Simple two microseconds delay - none - No delay - - ip= [IP_PNP] - See Documentation/filesystems/nfs/nfsroot.txt. - - irqaffinity= [SMP] Set the default irq affinity mask - The argument is a cpu list, as described above. - - irqfixup [HW] - When an interrupt is not handled search all handlers - for it. Intended to get systems with badly broken - firmware running. - - irqpoll [HW] - When an interrupt is not handled search all handlers - for it. Also check all handlers each timer - interrupt. Intended to get systems with badly broken - firmware running. - - isapnp= [ISAPNP] - Format: ,,, - - isolcpus= [KNL,SMP] Isolate CPUs from the general scheduler. - The argument is a cpu list, as described above. - - This option can be used to specify one or more CPUs - to isolate from the general SMP balancing and scheduling - algorithms. You can move a process onto or off an - "isolated" CPU via the CPU affinity syscalls or cpuset. - begins at 0 and the maximum value is - "number of CPUs in system - 1". - - This option is the preferred way to isolate CPUs. The - alternative -- manually setting the CPU mask of all - tasks in the system -- can cause problems and - suboptimal load balancer performance. - - iucv= [HW,NET] - - ivrs_ioapic [HW,X86_64] - Provide an override to the IOAPIC-ID<->DEVICE-ID - mapping provided in the IVRS ACPI table. For - example, to map IOAPIC-ID decimal 10 to - PCI device 00:14.0 write the parameter as: - ivrs_ioapic[10]=00:14.0 - - ivrs_hpet [HW,X86_64] - Provide an override to the HPET-ID<->DEVICE-ID - mapping provided in the IVRS ACPI table. For - example, to map HPET-ID decimal 0 to - PCI device 00:14.0 write the parameter as: - ivrs_hpet[0]=00:14.0 - - ivrs_acpihid [HW,X86_64] - Provide an override to the ACPI-HID:UID<->DEVICE-ID - mapping provided in the IVRS ACPI table. For - example, to map UART-HID:UID AMD0020:0 to - PCI device 00:14.5 write the parameter as: - ivrs_acpihid[00:14.5]=AMD0020:0 - - js= [HW,JOY] Analog joystick - See Documentation/input/joystick.txt. - - nokaslr [KNL] - When CONFIG_RANDOMIZE_BASE is set, this disables - kernel and module base offset ASLR (Address Space - Layout Randomization). - - keepinitrd [HW,ARM] - - kernelcore= [KNL,X86,IA-64,PPC] - Format: nn[KMGTPE] | "mirror" - This parameter - specifies the amount of memory usable by the kernel - for non-movable allocations. The requested amount is - spread evenly throughout all nodes in the system. The - remaining memory in each node is used for Movable - pages. In the event, a node is too small to have both - kernelcore and Movable pages, kernelcore pages will - take priority and other nodes will have a larger number - of Movable pages. The Movable zone is used for the - allocation of pages that may be reclaimed or moved - by the page migration subsystem. This means that - HugeTLB pages may not be allocated from this zone. - Note that allocations like PTEs-from-HighMem still - use the HighMem zone if it exists, and the Normal - zone if it does not. - - Instead of specifying the amount of memory (nn[KMGTPE]), - you can specify "mirror" option. In case "mirror" - option is specified, mirrored (reliable) memory is used - for non-movable allocations and remaining memory is used - for Movable pages. nn[KMGTPE] and "mirror" are exclusive, - so you can NOT specify nn[KMGTPE] and "mirror" at the same - time. - - kgdbdbgp= [KGDB,HW] kgdb over EHCI usb debug port. - Format: [,poll interval] - The controller # is the number of the ehci usb debug - port as it is probed via PCI. The poll interval is - optional and is the number seconds in between - each poll cycle to the debug port in case you need - the functionality for interrupting the kernel with - gdb or control-c on the dbgp connection. When - not using this parameter you use sysrq-g to break into - the kernel debugger. - - kgdboc= [KGDB,HW] kgdb over consoles. - Requires a tty driver that supports console polling, - or a supported polling keyboard driver (non-usb). - Serial only format: [,baud] - keyboard only format: kbd - keyboard and serial format: kbd,[,baud] - Optional Kernel mode setting: - kms, kbd format: kms,kbd - kms, kbd and serial format: kms,kbd,[,baud] - - kgdbwait [KGDB] Stop kernel execution and enter the - kernel debugger at the earliest opportunity. - - kmac= [MIPS] korina ethernet MAC address. - Configure the RouterBoard 532 series on-chip - Ethernet adapter MAC address. - - kmemleak= [KNL] Boot-time kmemleak enable/disable - Valid arguments: on, off - Default: on - Built with CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF=y, - the default is off. - - kmemcheck= [X86] Boot-time kmemcheck enable/disable/one-shot mode - Valid arguments: 0, 1, 2 - kmemcheck=0 (disabled) - kmemcheck=1 (enabled) - kmemcheck=2 (one-shot mode) - Default: 2 (one-shot mode) - - kstack=N [X86] Print N words from the kernel stack - in oops dumps. - - kvm.ignore_msrs=[KVM] Ignore guest accesses to unhandled MSRs. - Default is 0 (don't ignore, but inject #GP) - - kvm.mmu_audit= [KVM] This is a R/W parameter which allows audit - KVM MMU at runtime. - Default is 0 (off) - - kvm-amd.nested= [KVM,AMD] Allow nested virtualization in KVM/SVM. - Default is 1 (enabled) - - kvm-amd.npt= [KVM,AMD] Disable nested paging (virtualized MMU) - for all guests. - Default is 1 (enabled) if in 64-bit or 32-bit PAE mode. - - kvm-intel.ept= [KVM,Intel] Disable extended page tables - (virtualized MMU) support on capable Intel chips. - Default is 1 (enabled) - - kvm-intel.emulate_invalid_guest_state= - [KVM,Intel] Enable emulation of invalid guest states - Default is 0 (disabled) - - kvm-intel.flexpriority= - [KVM,Intel] Disable FlexPriority feature (TPR shadow). - Default is 1 (enabled) - - kvm-intel.nested= - [KVM,Intel] Enable VMX nesting (nVMX). - Default is 0 (disabled) - - kvm-intel.unrestricted_guest= - [KVM,Intel] Disable unrestricted guest feature - (virtualized real and unpaged mode) on capable - Intel chips. Default is 1 (enabled) - - kvm-intel.vpid= [KVM,Intel] Disable Virtual Processor Identification - feature (tagged TLBs) on capable Intel chips. - Default is 1 (enabled) - - l2cr= [PPC] - - l3cr= [PPC] - - lapic [X86-32,APIC] Enable the local APIC even if BIOS - disabled it. - - lapic= [x86,APIC] "notscdeadline" Do not use TSC deadline - value for LAPIC timer one-shot implementation. Default - back to the programmable timer unit in the LAPIC. - - lapic_timer_c2_ok [X86,APIC] trust the local apic timer - in C2 power state. - - libata.dma= [LIBATA] DMA control - libata.dma=0 Disable all PATA and SATA DMA - libata.dma=1 PATA and SATA Disk DMA only - libata.dma=2 ATAPI (CDROM) DMA only - libata.dma=4 Compact Flash DMA only - Combinations also work, so libata.dma=3 enables DMA - for disks and CDROMs, but not CFs. - - libata.ignore_hpa= [LIBATA] Ignore HPA limit - libata.ignore_hpa=0 keep BIOS limits (default) - libata.ignore_hpa=1 ignore limits, using full disk - - libata.noacpi [LIBATA] Disables use of ACPI in libata suspend/resume - when set. - Format: - - libata.force= [LIBATA] Force configurations. The format is comma - separated list of "[ID:]VAL" where ID is - PORT[.DEVICE]. PORT and DEVICE are decimal numbers - matching port, link or device. Basically, it matches - the ATA ID string printed on console by libata. If - the whole ID part is omitted, the last PORT and DEVICE - values are used. If ID hasn't been specified yet, the - configuration applies to all ports, links and devices. - - If only DEVICE is omitted, the parameter applies to - the port and all links and devices behind it. DEVICE - number of 0 either selects the first device or the - first fan-out link behind PMP device. It does not - select the host link. DEVICE number of 15 selects the - host link and device attached to it. - - The VAL specifies the configuration to force. As long - as there's no ambiguity shortcut notation is allowed. - For example, both 1.5 and 1.5G would work for 1.5Gbps. - The following configurations can be forced. - - * Cable type: 40c, 80c, short40c, unk, ign or sata. - Any ID with matching PORT is used. - - * SATA link speed limit: 1.5Gbps or 3.0Gbps. - - * Transfer mode: pio[0-7], mwdma[0-4] and udma[0-7]. - udma[/][16,25,33,44,66,100,133] notation is also - allowed. - - * [no]ncq: Turn on or off NCQ. - - * [no]ncqtrim: Turn off queued DSM TRIM. - - * nohrst, nosrst, norst: suppress hard, soft - and both resets. - - * rstonce: only attempt one reset during - hot-unplug link recovery - - * dump_id: dump IDENTIFY data. - - * atapi_dmadir: Enable ATAPI DMADIR bridge support - - * disable: Disable this device. - - If there are multiple matching configurations changing - the same attribute, the last one is used. - - memblock=debug [KNL] Enable memblock debug messages. - - load_ramdisk= [RAM] List of ramdisks to load from floppy - See Documentation/blockdev/ramdisk.txt. - - lockd.nlm_grace_period=P [NFS] Assign grace period. - Format: - - lockd.nlm_tcpport=N [NFS] Assign TCP port. - Format: - - lockd.nlm_timeout=T [NFS] Assign timeout value. - Format: - - lockd.nlm_udpport=M [NFS] Assign UDP port. - Format: - - locktorture.nreaders_stress= [KNL] - Set the number of locking read-acquisition kthreads. - Defaults to being automatically set based on the - number of online CPUs. - - locktorture.nwriters_stress= [KNL] - Set the number of locking write-acquisition kthreads. - - locktorture.onoff_holdoff= [KNL] - Set time (s) after boot for CPU-hotplug testing. - - locktorture.onoff_interval= [KNL] - Set time (s) between CPU-hotplug operations, or - zero to disable CPU-hotplug testing. - - locktorture.shuffle_interval= [KNL] - Set task-shuffle interval (jiffies). Shuffling - tasks allows some CPUs to go into dyntick-idle - mode during the locktorture test. - - locktorture.shutdown_secs= [KNL] - Set time (s) after boot system shutdown. This - is useful for hands-off automated testing. - - locktorture.stat_interval= [KNL] - Time (s) between statistics printk()s. - - locktorture.stutter= [KNL] - Time (s) to stutter testing, for example, - specifying five seconds causes the test to run for - five seconds, wait for five seconds, and so on. - This tests the locking primitive's ability to - transition abruptly to and from idle. - - locktorture.torture_runnable= [BOOT] - Start locktorture running at boot time. - - locktorture.torture_type= [KNL] - Specify the locking implementation to test. - - locktorture.verbose= [KNL] - Enable additional printk() statements. - - logibm.irq= [HW,MOUSE] Logitech Bus Mouse Driver - Format: - - loglevel= All Kernel Messages with a loglevel smaller than the - console loglevel will be printed to the console. It can - also be changed with klogd or other programs. The - loglevels are defined as follows: - - 0 (KERN_EMERG) system is unusable - 1 (KERN_ALERT) action must be taken immediately - 2 (KERN_CRIT) critical conditions - 3 (KERN_ERR) error conditions - 4 (KERN_WARNING) warning conditions - 5 (KERN_NOTICE) normal but significant condition - 6 (KERN_INFO) informational - 7 (KERN_DEBUG) debug-level messages - - log_buf_len=n[KMG] Sets the size of the printk ring buffer, - in bytes. n must be a power of two and greater - than the minimal size. The minimal size is defined - by LOG_BUF_SHIFT kernel config parameter. There is - also CONFIG_LOG_CPU_MAX_BUF_SHIFT config parameter - that allows to increase the default size depending on - the number of CPUs. See init/Kconfig for more details. - - logo.nologo [FB] Disables display of the built-in Linux logo. - This may be used to provide more screen space for - kernel log messages and is useful when debugging - kernel boot problems. - - lp=0 [LP] Specify parallel ports to use, e.g, - lp=port[,port...] lp=none,parport0 (lp0 not configured, lp1 uses - lp=reset first parallel port). 'lp=0' disables the - lp=auto printer driver. 'lp=reset' (which can be - specified in addition to the ports) causes - attached printers to be reset. Using - lp=port1,port2,... specifies the parallel ports - to associate lp devices with, starting with - lp0. A port specification may be 'none' to skip - that lp device, or a parport name such as - 'parport0'. Specifying 'lp=auto' instead of a - port specification list means that device IDs - from each port should be examined, to see if - an IEEE 1284-compliant printer is attached; if - so, the driver will manage that printer. - See also header of drivers/char/lp.c. - - lpj=n [KNL] - Sets loops_per_jiffy to given constant, thus avoiding - time-consuming boot-time autodetection (up to 250 ms per - CPU). 0 enables autodetection (default). To determine - the correct value for your kernel, boot with normal - autodetection and see what value is printed. Note that - on SMP systems the preset will be applied to all CPUs, - which is likely to cause problems if your CPUs need - significantly divergent settings. An incorrect value - will cause delays in the kernel to be wrong, leading to - unpredictable I/O errors and other breakage. Although - unlikely, in the extreme case this might damage your - hardware. - - ltpc= [NET] - Format: ,, - - machvec= [IA-64] Force the use of a particular machine-vector - (machvec) in a generic kernel. - Example: machvec=hpzx1_swiotlb - - machtype= [Loongson] Share the same kernel image file between different - yeeloong laptop. - Example: machtype=lemote-yeeloong-2f-7inch - - max_addr=nn[KMG] [KNL,BOOT,ia64] All physical memory greater - than or equal to this physical address is ignored. - - maxcpus= [SMP] Maximum number of processors that an SMP kernel - will bring up during bootup. maxcpus=n : n >= 0 limits - the kernel to bring up 'n' processors. Surely after - bootup you can bring up the other plugged cpu by executing - "echo 1 > /sys/devices/system/cpu/cpuX/online". So maxcpus - only takes effect during system bootup. - While n=0 is a special case, it is equivalent to "nosmp", - which also disables the IO APIC. - - max_loop= [LOOP] The number of loop block devices that get - (loop.max_loop) unconditionally pre-created at init time. The default - number is configured by BLK_DEV_LOOP_MIN_COUNT. Instead - of statically allocating a predefined number, loop - devices can be requested on-demand with the - /dev/loop-control interface. - - mce [X86-32] Machine Check Exception - - mce=option [X86-64] See Documentation/x86/x86_64/boot-options.txt - - md= [HW] RAID subsystems devices and level - See Documentation/md.txt. - - mdacon= [MDA] - Format: , - Specifies range of consoles to be captured by the MDA. - - mem=nn[KMG] [KNL,BOOT] Force usage of a specific amount of memory - Amount of memory to be used when the kernel is not able - to see the whole system memory or for test. - [X86] Work as limiting max address. Use together - with memmap= to avoid physical address space collisions. - Without memmap= PCI devices could be placed at addresses - belonging to unused RAM. - - mem=nopentium [BUGS=X86-32] Disable usage of 4MB pages for kernel - memory. - - memchunk=nn[KMG] - [KNL,SH] Allow user to override the default size for - per-device physically contiguous DMA buffers. - - memhp_default_state=online/offline - [KNL] Set the initial state for the memory hotplug - onlining policy. If not specified, the default value is - set according to the - CONFIG_MEMORY_HOTPLUG_DEFAULT_ONLINE kernel config - option. - See Documentation/memory-hotplug.txt. - - memmap=exactmap [KNL,X86] Enable setting of an exact - E820 memory map, as specified by the user. - Such memmap=exactmap lines can be constructed based on - BIOS output or other requirements. See the memmap=nn@ss - option description. - - memmap=nn[KMG]@ss[KMG] - [KNL] Force usage of a specific region of memory. - Region of memory to be used is from ss to ss+nn. - - memmap=nn[KMG]#ss[KMG] - [KNL,ACPI] Mark specific memory as ACPI data. - Region of memory to be marked is from ss to ss+nn. - - memmap=nn[KMG]$ss[KMG] - [KNL,ACPI] Mark specific memory as reserved. - Region of memory to be reserved is from ss to ss+nn. - Example: Exclude memory from 0x18690000-0x1869ffff - memmap=64K$0x18690000 - or - memmap=0x10000$0x18690000 - - memmap=nn[KMG]!ss[KMG] - [KNL,X86] Mark specific memory as protected. - Region of memory to be used, from ss to ss+nn. - The memory region may be marked as e820 type 12 (0xc) - and is NVDIMM or ADR memory. - - memory_corruption_check=0/1 [X86] - Some BIOSes seem to corrupt the first 64k of - memory when doing things like suspend/resume. - Setting this option will scan the memory - looking for corruption. Enabling this will - both detect corruption and prevent the kernel - from using the memory being corrupted. - However, its intended as a diagnostic tool; if - repeatable BIOS-originated corruption always - affects the same memory, you can use memmap= - to prevent the kernel from using that memory. - - memory_corruption_check_size=size [X86] - By default it checks for corruption in the low - 64k, making this memory unavailable for normal - use. Use this parameter to scan for - corruption in more or less memory. - - memory_corruption_check_period=seconds [X86] - By default it checks for corruption every 60 - seconds. Use this parameter to check at some - other rate. 0 disables periodic checking. - - memtest= [KNL,X86,ARM] Enable memtest - Format: - default : 0 - Specifies the number of memtest passes to be - performed. Each pass selects another test - pattern from a given set of patterns. Memtest - fills the memory with this pattern, validates - memory contents and reserves bad memory - regions that are detected. - - meye.*= [HW] Set MotionEye Camera parameters - See Documentation/video4linux/meye.txt. - - mfgpt_irq= [IA-32] Specify the IRQ to use for the - Multi-Function General Purpose Timers on AMD Geode - platforms. - - mfgptfix [X86-32] Fix MFGPT timers on AMD Geode platforms when - the BIOS has incorrectly applied a workaround. TinyBIOS - version 0.98 is known to be affected, 0.99 fixes the - problem by letting the user disable the workaround. - - mga= [HW,DRM] - - min_addr=nn[KMG] [KNL,BOOT,ia64] All physical memory below this - physical address is ignored. - - mini2440= [ARM,HW,KNL] - Format:[0..2][b][c][t] - Default: "0tb" - MINI2440 configuration specification: - 0 - The attached screen is the 3.5" TFT - 1 - The attached screen is the 7" TFT - 2 - The VGA Shield is attached (1024x768) - Leaving out the screen size parameter will not load - the TFT driver, and the framebuffer will be left - unconfigured. - b - Enable backlight. The TFT backlight pin will be - linked to the kernel VESA blanking code and a GPIO - LED. This parameter is not necessary when using the - VGA shield. - c - Enable the s3c camera interface. - t - Reserved for enabling touchscreen support. The - touchscreen support is not enabled in the mainstream - kernel as of 2.6.30, a preliminary port can be found - in the "bleeding edge" mini2440 support kernel at - http://repo.or.cz/w/linux-2.6/mini2440.git - - mminit_loglevel= - [KNL] When CONFIG_DEBUG_MEMORY_INIT is set, this - parameter allows control of the logging verbosity for - the additional memory initialisation checks. A value - of 0 disables mminit logging and a level of 4 will - log everything. Information is printed at KERN_DEBUG - so loglevel=8 may also need to be specified. - - module.sig_enforce - [KNL] When CONFIG_MODULE_SIG is set, this means that - modules without (valid) signatures will fail to load. - Note that if CONFIG_MODULE_SIG_FORCE is set, that - is always true, so this option does nothing. - - module_blacklist= [KNL] Do not load a comma-separated list of - modules. Useful for debugging problem modules. - - mousedev.tap_time= - [MOUSE] Maximum time between finger touching and - leaving touchpad surface for touch to be considered - a tap and be reported as a left button click (for - touchpads working in absolute mode only). - Format: - mousedev.xres= [MOUSE] Horizontal screen resolution, used for devices - reporting absolute coordinates, such as tablets - mousedev.yres= [MOUSE] Vertical screen resolution, used for devices - reporting absolute coordinates, such as tablets - - movablecore=nn[KMG] [KNL,X86,IA-64,PPC] This parameter - is similar to kernelcore except it specifies the - amount of memory used for migratable allocations. - If both kernelcore and movablecore is specified, - then kernelcore will be at *least* the specified - value but may be more. If movablecore on its own - is specified, the administrator must be careful - that the amount of memory usable for all allocations - is not too small. - - movable_node [KNL,X86] Boot-time switch to enable the effects - of CONFIG_MOVABLE_NODE=y. See mm/Kconfig for details. - - MTD_Partition= [MTD] - Format: ,,, - - MTD_Region= [MTD] Format: - ,[,,,,] - - mtdparts= [MTD] - See drivers/mtd/cmdlinepart.c. - - multitce=off [PPC] This parameter disables the use of the pSeries - firmware feature for updating multiple TCE entries - at a time. - - onenand.bdry= [HW,MTD] Flex-OneNAND Boundary Configuration - - Format: [die0_boundary][,die0_lock][,die1_boundary][,die1_lock] - - boundary - index of last SLC block on Flex-OneNAND. - The remaining blocks are configured as MLC blocks. - lock - Configure if Flex-OneNAND boundary should be locked. - Once locked, the boundary cannot be changed. - 1 indicates lock status, 0 indicates unlock status. - - mtdset= [ARM] - ARM/S3C2412 JIVE boot control - - See arch/arm/mach-s3c2412/mach-jive.c - - mtouchusb.raw_coordinates= - [HW] Make the MicroTouch USB driver use raw coordinates - ('y', default) or cooked coordinates ('n') - - mtrr_chunk_size=nn[KMG] [X86] - used for mtrr cleanup. It is largest continuous chunk - that could hold holes aka. UC entries. - - mtrr_gran_size=nn[KMG] [X86] - Used for mtrr cleanup. It is granularity of mtrr block. - Default is 1. - Large value could prevent small alignment from - using up MTRRs. - - mtrr_spare_reg_nr=n [X86] - Format: - Range: 0,7 : spare reg number - Default : 1 - Used for mtrr cleanup. It is spare mtrr entries number. - Set to 2 or more if your graphical card needs more. - - n2= [NET] SDL Inc. RISCom/N2 synchronous serial card - - netdev= [NET] Network devices parameters - Format: ,,,, - Note that mem_start is often overloaded to mean - something different and driver-specific. - This usage is only documented in each driver source - file if at all. - - nf_conntrack.acct= - [NETFILTER] Enable connection tracking flow accounting - 0 to disable accounting - 1 to enable accounting - Default value is 0. - - nfsaddrs= [NFS] Deprecated. Use ip= instead. - See Documentation/filesystems/nfs/nfsroot.txt. - - nfsroot= [NFS] nfs root filesystem for disk-less boxes. - See Documentation/filesystems/nfs/nfsroot.txt. - - nfsrootdebug [NFS] enable nfsroot debugging messages. - See Documentation/filesystems/nfs/nfsroot.txt. - - nfs.callback_nr_threads= - [NFSv4] set the total number of threads that the - NFS client will assign to service NFSv4 callback - requests. - - nfs.callback_tcpport= - [NFS] set the TCP port on which the NFSv4 callback - channel should listen. - - nfs.cache_getent= - [NFS] sets the pathname to the program which is used - to update the NFS client cache entries. - - nfs.cache_getent_timeout= - [NFS] sets the timeout after which an attempt to - update a cache entry is deemed to have failed. - - nfs.idmap_cache_timeout= - [NFS] set the maximum lifetime for idmapper cache - entries. - - nfs.enable_ino64= - [NFS] enable 64-bit inode numbers. - If zero, the NFS client will fake up a 32-bit inode - number for the readdir() and stat() syscalls instead - of returning the full 64-bit number. - The default is to return 64-bit inode numbers. - - nfs.max_session_cb_slots= - [NFSv4.1] Sets the maximum number of session - slots the client will assign to the callback - channel. This determines the maximum number of - callbacks the client will process in parallel for - a particular server. - - nfs.max_session_slots= - [NFSv4.1] Sets the maximum number of session slots - the client will attempt to negotiate with the server. - This limits the number of simultaneous RPC requests - that the client can send to the NFSv4.1 server. - Note that there is little point in setting this - value higher than the max_tcp_slot_table_limit. - - nfs.nfs4_disable_idmapping= - [NFSv4] When set to the default of '1', this option - ensures that both the RPC level authentication - scheme and the NFS level operations agree to use - numeric uids/gids if the mount is using the - 'sec=sys' security flavour. In effect it is - disabling idmapping, which can make migration from - legacy NFSv2/v3 systems to NFSv4 easier. - Servers that do not support this mode of operation - will be autodetected by the client, and it will fall - back to using the idmapper. - To turn off this behaviour, set the value to '0'. - nfs.nfs4_unique_id= - [NFS4] Specify an additional fixed unique ident- - ification string that NFSv4 clients can insert into - their nfs_client_id4 string. This is typically a - UUID that is generated at system install time. - - nfs.send_implementation_id = - [NFSv4.1] Send client implementation identification - information in exchange_id requests. - If zero, no implementation identification information - will be sent. - The default is to send the implementation identification - information. - - nfs.recover_lost_locks = - [NFSv4] Attempt to recover locks that were lost due - to a lease timeout on the server. Please note that - doing this risks data corruption, since there are - no guarantees that the file will remain unchanged - after the locks are lost. - If you want to enable the kernel legacy behaviour of - attempting to recover these locks, then set this - parameter to '1'. - The default parameter value of '0' causes the kernel - not to attempt recovery of lost locks. - - nfs4.layoutstats_timer = - [NFSv4.2] Change the rate at which the kernel sends - layoutstats to the pNFS metadata server. - - Setting this to value to 0 causes the kernel to use - whatever value is the default set by the layout - driver. A non-zero value sets the minimum interval - in seconds between layoutstats transmissions. - - nfsd.nfs4_disable_idmapping= - [NFSv4] When set to the default of '1', the NFSv4 - server will return only numeric uids and gids to - clients using auth_sys, and will accept numeric uids - and gids from such clients. This is intended to ease - migration from NFSv2/v3. - - objlayoutdriver.osd_login_prog= - [NFS] [OBJLAYOUT] sets the pathname to the program which - is used to automatically discover and login into new - osd-targets. Please see: - Documentation/filesystems/pnfs.txt for more explanations - - nmi_debug= [KNL,AVR32,SH] Specify one or more actions to take - when a NMI is triggered. - Format: [state][,regs][,debounce][,die] - - nmi_watchdog= [KNL,BUGS=X86] Debugging features for SMP kernels - Format: [panic,][nopanic,][num] - Valid num: 0 or 1 - 0 - turn hardlockup detector in nmi_watchdog off - 1 - turn hardlockup detector in nmi_watchdog on - When panic is specified, panic when an NMI watchdog - timeout occurs (or 'nopanic' to override the opposite - default). To disable both hard and soft lockup detectors, - please see 'nowatchdog'. - This is useful when you use a panic=... timeout and - need the box quickly up again. - - netpoll.carrier_timeout= - [NET] Specifies amount of time (in seconds) that - netpoll should wait for a carrier. By default netpoll - waits 4 seconds. - - no387 [BUGS=X86-32] Tells the kernel to use the 387 maths - emulation library even if a 387 maths coprocessor - is present. - - no_console_suspend - [HW] Never suspend the console - Disable suspending of consoles during suspend and - hibernate operations. Once disabled, debugging - messages can reach various consoles while the rest - of the system is being put to sleep (ie, while - debugging driver suspend/resume hooks). This may - not work reliably with all consoles, but is known - to work with serial and VGA consoles. - To facilitate more flexible debugging, we also add - console_suspend, a printk module parameter to control - it. Users could use console_suspend (usually - /sys/module/printk/parameters/console_suspend) to - turn on/off it dynamically. - - noaliencache [MM, NUMA, SLAB] Disables the allocation of alien - caches in the slab allocator. Saves per-node memory, - but will impact performance. - - noalign [KNL,ARM] - - noapic [SMP,APIC] Tells the kernel to not make use of any - IOAPICs that may be present in the system. - - noautogroup Disable scheduler automatic task group creation. - - nobats [PPC] Do not use BATs for mapping kernel lowmem - on "Classic" PPC cores. - - nocache [ARM] - - noclflush [BUGS=X86] Don't use the CLFLUSH instruction - - nodelayacct [KNL] Disable per-task delay accounting - - nodsp [SH] Disable hardware DSP at boot time. - - noefi Disable EFI runtime services support. - - noexec [IA-64] - - noexec [X86] - On X86-32 available only on PAE configured kernels. - noexec=on: enable non-executable mappings (default) - noexec=off: disable non-executable mappings - - nosmap [X86] - Disable SMAP (Supervisor Mode Access Prevention) - even if it is supported by processor. - - nosmep [X86] - Disable SMEP (Supervisor Mode Execution Prevention) - even if it is supported by processor. - - noexec32 [X86-64] - This affects only 32-bit executables. - noexec32=on: enable non-executable mappings (default) - read doesn't imply executable mappings - noexec32=off: disable non-executable mappings - read implies executable mappings - - nofpu [MIPS,SH] Disable hardware FPU at boot time. - - nofxsr [BUGS=X86-32] Disables x86 floating point extended - register save and restore. The kernel will only save - legacy floating-point registers on task switch. - - nohugeiomap [KNL,x86] Disable kernel huge I/O mappings. - - nosmt [KNL,S390] Disable symmetric multithreading (SMT). - Equivalent to smt=1. - - noxsave [BUGS=X86] Disables x86 extended register state save - and restore using xsave. The kernel will fallback to - enabling legacy floating-point and sse state. - - noxsaveopt [X86] Disables xsaveopt used in saving x86 extended - register states. The kernel will fall back to use - xsave to save the states. By using this parameter, - performance of saving the states is degraded because - xsave doesn't support modified optimization while - xsaveopt supports it on xsaveopt enabled systems. - - noxsaves [X86] Disables xsaves and xrstors used in saving and - restoring x86 extended register state in compacted - form of xsave area. The kernel will fall back to use - xsaveopt and xrstor to save and restore the states - in standard form of xsave area. By using this - parameter, xsave area per process might occupy more - memory on xsaves enabled systems. - - nohlt [BUGS=ARM,SH] Tells the kernel that the sleep(SH) or - wfi(ARM) instruction doesn't work correctly and not to - use it. This is also useful when using JTAG debugger. - - no_file_caps Tells the kernel not to honor file capabilities. The - only way then for a file to be executed with privilege - is to be setuid root or executed by root. - - nohalt [IA-64] Tells the kernel not to use the power saving - function PAL_HALT_LIGHT when idle. This increases - power-consumption. On the positive side, it reduces - interrupt wake-up latency, which may improve performance - in certain environments such as networked servers or - real-time systems. - - nohibernate [HIBERNATION] Disable hibernation and resume. - - nohz= [KNL] Boottime enable/disable dynamic ticks - Valid arguments: on, off - Default: on - - nohz_full= [KNL,BOOT] - The argument is a cpu list, as described above. - In kernels built with CONFIG_NO_HZ_FULL=y, set - the specified list of CPUs whose tick will be stopped - whenever possible. The boot CPU will be forced outside - the range to maintain the timekeeping. - The CPUs in this range must also be included in the - rcu_nocbs= set. - - noiotrap [SH] Disables trapped I/O port accesses. - - noirqdebug [X86-32] Disables the code which attempts to detect and - disable unhandled interrupt sources. - - no_timer_check [X86,APIC] Disables the code which tests for - broken timer IRQ sources. - - noisapnp [ISAPNP] Disables ISA PnP code. - - noinitrd [RAM] Tells the kernel not to load any configured - initial RAM disk. - - nointremap [X86-64, Intel-IOMMU] Do not enable interrupt - remapping. - [Deprecated - use intremap=off] - - nointroute [IA-64] - - noinvpcid [X86] Disable the INVPCID cpu feature. - - nojitter [IA-64] Disables jitter checking for ITC timers. - - no-kvmclock [X86,KVM] Disable paravirtualized KVM clock driver - - no-kvmapf [X86,KVM] Disable paravirtualized asynchronous page - fault handling. - - no-steal-acc [X86,KVM] Disable paravirtualized steal time accounting. - steal time is computed, but won't influence scheduler - behaviour - - nolapic [X86-32,APIC] Do not enable or use the local APIC. - - nolapic_timer [X86-32,APIC] Do not use the local APIC timer. - - noltlbs [PPC] Do not use large page/tlb entries for kernel - lowmem mapping on PPC40x and PPC8xx - - nomca [IA-64] Disable machine check abort handling - - nomce [X86-32] Disable Machine Check Exception - - nomfgpt [X86-32] Disable Multi-Function General Purpose - Timer usage (for AMD Geode machines). - - nonmi_ipi [X86] Disable using NMI IPIs during panic/reboot to - shutdown the other cpus. Instead use the REBOOT_VECTOR - irq. - - nomodule Disable module load - - nopat [X86] Disable PAT (page attribute table extension of - pagetables) support. - - norandmaps Don't use address space randomization. Equivalent to - echo 0 > /proc/sys/kernel/randomize_va_space - - noreplace-paravirt [X86,IA-64,PV_OPS] Don't patch paravirt_ops - - noreplace-smp [X86-32,SMP] Don't replace SMP instructions - with UP alternatives - - nordrand [X86] Disable kernel use of the RDRAND and - RDSEED instructions even if they are supported - by the processor. RDRAND and RDSEED are still - available to user space applications. - - noresume [SWSUSP] Disables resume and restores original swap - space. - - no-scroll [VGA] Disables scrollback. - This is required for the Braillex ib80-piezo Braille - reader made by F.H. Papenmeier (Germany). - - nosbagart [IA-64] - - nosep [BUGS=X86-32] Disables x86 SYSENTER/SYSEXIT support. - - nosmp [SMP] Tells an SMP kernel to act as a UP kernel, - and disable the IO APIC. legacy for "maxcpus=0". - - nosoftlockup [KNL] Disable the soft-lockup detector. - - nosync [HW,M68K] Disables sync negotiation for all devices. - - notsc [BUGS=X86-32] Disable Time Stamp Counter - - nowatchdog [KNL] Disable both lockup detectors, i.e. - soft-lockup and NMI watchdog (hard-lockup). - - nowb [ARM] - - nox2apic [X86-64,APIC] Do not enable x2APIC mode. - - cpu0_hotplug [X86] Turn on CPU0 hotplug feature when - CONFIG_BOOTPARAM_HOTPLUG_CPU0 is off. - Some features depend on CPU0. Known dependencies are: - 1. Resume from suspend/hibernate depends on CPU0. - Suspend/hibernate will fail if CPU0 is offline and you - need to online CPU0 before suspend/hibernate. - 2. PIC interrupts also depend on CPU0. CPU0 can't be - removed if a PIC interrupt is detected. - It's said poweroff/reboot may depend on CPU0 on some - machines although I haven't seen such issues so far - after CPU0 is offline on a few tested machines. - If the dependencies are under your control, you can - turn on cpu0_hotplug. - - nptcg= [IA-64] Override max number of concurrent global TLB - purges which is reported from either PAL_VM_SUMMARY or - SAL PALO. - - nr_cpus= [SMP] Maximum number of processors that an SMP kernel - could support. nr_cpus=n : n >= 1 limits the kernel to - support 'n' processors. It could be larger than the - number of already plugged CPU during bootup, later in - runtime you can physically add extra cpu until it reaches - n. So during boot up some boot time memory for per-cpu - variables need be pre-allocated for later physical cpu - hot plugging. - - nr_uarts= [SERIAL] maximum number of UARTs to be registered. - - numa_balancing= [KNL,X86] Enable or disable automatic NUMA balancing. - Allowed values are enable and disable - - numa_zonelist_order= [KNL, BOOT] Select zonelist order for NUMA. - one of ['zone', 'node', 'default'] can be specified - This can be set from sysctl after boot. - See Documentation/sysctl/vm.txt for details. - - ohci1394_dma=early [HW] enable debugging via the ohci1394 driver. - See Documentation/debugging-via-ohci1394.txt for more - info. - - olpc_ec_timeout= [OLPC] ms delay when issuing EC commands - Rather than timing out after 20 ms if an EC - command is not properly ACKed, override the length - of the timeout. We have interrupts disabled while - waiting for the ACK, so if this is set too high - interrupts *may* be lost! - - omap_mux= [OMAP] Override bootloader pin multiplexing. - Format: ... - For example, to override I2C bus2: - omap_mux=i2c2_scl.i2c2_scl=0x100,i2c2_sda.i2c2_sda=0x100 - - oprofile.timer= [HW] - Use timer interrupt instead of performance counters - - oprofile.cpu_type= Force an oprofile cpu type - This might be useful if you have an older oprofile - userland or if you want common events. - Format: { arch_perfmon } - arch_perfmon: [X86] Force use of architectural - perfmon on Intel CPUs instead of the - CPU specific event set. - timer: [X86] Force use of architectural NMI - timer mode (see also oprofile.timer - for generic hr timer mode) - - oops=panic Always panic on oopses. Default is to just kill the - process, but there is a small probability of - deadlocking the machine. - This will also cause panics on machine check exceptions. - Useful together with panic=30 to trigger a reboot. - - OSS [HW,OSS] - See Documentation/sound/oss/oss-parameters.txt - - page_owner= [KNL] Boot-time page_owner enabling option. - Storage of the information about who allocated - each page is disabled in default. With this switch, - we can turn it on. - on: enable the feature - - page_poison= [KNL] Boot-time parameter changing the state of - poisoning on the buddy allocator. - off: turn off poisoning - on: turn on poisoning - - panic= [KNL] Kernel behaviour on panic: delay - timeout > 0: seconds before rebooting - timeout = 0: wait forever - timeout < 0: reboot immediately - Format: - - panic_on_warn panic() instead of WARN(). Useful to cause kdump - on a WARN(). - - crash_kexec_post_notifiers - Run kdump after running panic-notifiers and dumping - kmsg. This only for the users who doubt kdump always - succeeds in any situation. - Note that this also increases risks of kdump failure, - because some panic notifiers can make the crashed - kernel more unstable. - - parkbd.port= [HW] Parallel port number the keyboard adapter is - connected to, default is 0. - Format: - parkbd.mode= [HW] Parallel port keyboard adapter mode of operation, - 0 for XT, 1 for AT (default is AT). - Format: - - parport= [HW,PPT] Specify parallel ports. 0 disables. - Format: { 0 | auto | 0xBBB[,IRQ[,DMA]] } - Use 'auto' to force the driver to use any - IRQ/DMA settings detected (the default is to - ignore detected IRQ/DMA settings because of - possible conflicts). You can specify the base - address, IRQ, and DMA settings; IRQ and DMA - should be numbers, or 'auto' (for using detected - settings on that particular port), or 'nofifo' - (to avoid using a FIFO even if it is detected). - Parallel ports are assigned in the order they - are specified on the command line, starting - with parport0. - - parport_init_mode= [HW,PPT] - Configure VIA parallel port to operate in - a specific mode. This is necessary on Pegasos - computer where firmware has no options for setting - up parallel port mode and sets it to spp. - Currently this function knows 686a and 8231 chips. - Format: [spp|ps2|epp|ecp|ecpepp] - - pause_on_oops= - Halt all CPUs after the first oops has been printed for - the specified number of seconds. This is to be used if - your oopses keep scrolling off the screen. - - pcbit= [HW,ISDN] - - pcd. [PARIDE] - See header of drivers/block/paride/pcd.c. - See also Documentation/blockdev/paride.txt. - - pci=option[,option...] [PCI] various PCI subsystem options: - earlydump [X86] dump PCI config space before the kernel - changes anything - off [X86] don't probe for the PCI bus - bios [X86-32] force use of PCI BIOS, don't access - the hardware directly. Use this if your machine - has a non-standard PCI host bridge. - nobios [X86-32] disallow use of PCI BIOS, only direct - hardware access methods are allowed. Use this - if you experience crashes upon bootup and you - suspect they are caused by the BIOS. - conf1 [X86] Force use of PCI Configuration Access - Mechanism 1 (config address in IO port 0xCF8, - data in IO port 0xCFC, both 32-bit). - conf2 [X86] Force use of PCI Configuration Access - Mechanism 2 (IO port 0xCF8 is an 8-bit port for - the function, IO port 0xCFA, also 8-bit, sets - bus number. The config space is then accessed - through ports 0xC000-0xCFFF). - See http://wiki.osdev.org/PCI for more info - on the configuration access mechanisms. - noaer [PCIE] If the PCIEAER kernel config parameter is - enabled, this kernel boot option can be used to - disable the use of PCIE advanced error reporting. - nodomains [PCI] Disable support for multiple PCI - root domains (aka PCI segments, in ACPI-speak). - nommconf [X86] Disable use of MMCONFIG for PCI - Configuration - check_enable_amd_mmconf [X86] check for and enable - properly configured MMIO access to PCI - config space on AMD family 10h CPU - nomsi [MSI] If the PCI_MSI kernel config parameter is - enabled, this kernel boot option can be used to - disable the use of MSI interrupts system-wide. - noioapicquirk [APIC] Disable all boot interrupt quirks. - Safety option to keep boot IRQs enabled. This - should never be necessary. - ioapicreroute [APIC] Enable rerouting of boot IRQs to the - primary IO-APIC for bridges that cannot disable - boot IRQs. This fixes a source of spurious IRQs - when the system masks IRQs. - noioapicreroute [APIC] Disable workaround that uses the - boot IRQ equivalent of an IRQ that connects to - a chipset where boot IRQs cannot be disabled. - The opposite of ioapicreroute. - biosirq [X86-32] Use PCI BIOS calls to get the interrupt - routing table. These calls are known to be buggy - on several machines and they hang the machine - when used, but on other computers it's the only - way to get the interrupt routing table. Try - this option if the kernel is unable to allocate - IRQs or discover secondary PCI buses on your - motherboard. - rom [X86] Assign address space to expansion ROMs. - Use with caution as certain devices share - address decoders between ROMs and other - resources. - norom [X86] Do not assign address space to - expansion ROMs that do not already have - BIOS assigned address ranges. - nobar [X86] Do not assign address space to the - BARs that weren't assigned by the BIOS. - irqmask=0xMMMM [X86] Set a bit mask of IRQs allowed to be - assigned automatically to PCI devices. You can - make the kernel exclude IRQs of your ISA cards - this way. - pirqaddr=0xAAAAA [X86] Specify the physical address - of the PIRQ table (normally generated - by the BIOS) if it is outside the - F0000h-100000h range. - lastbus=N [X86] Scan all buses thru bus #N. Can be - useful if the kernel is unable to find your - secondary buses and you want to tell it - explicitly which ones they are. - assign-busses [X86] Always assign all PCI bus - numbers ourselves, overriding - whatever the firmware may have done. - usepirqmask [X86] Honor the possible IRQ mask stored - in the BIOS $PIR table. This is needed on - some systems with broken BIOSes, notably - some HP Pavilion N5400 and Omnibook XE3 - notebooks. This will have no effect if ACPI - IRQ routing is enabled. - noacpi [X86] Do not use ACPI for IRQ routing - or for PCI scanning. - use_crs [X86] Use PCI host bridge window information - from ACPI. On BIOSes from 2008 or later, this - is enabled by default. If you need to use this, - please report a bug. - nocrs [X86] Ignore PCI host bridge windows from ACPI. - If you need to use this, please report a bug. - routeirq Do IRQ routing for all PCI devices. - This is normally done in pci_enable_device(), - so this option is a temporary workaround - for broken drivers that don't call it. - skip_isa_align [X86] do not align io start addr, so can - handle more pci cards - noearly [X86] Don't do any early type 1 scanning. - This might help on some broken boards which - machine check when some devices' config space - is read. But various workarounds are disabled - and some IOMMU drivers will not work. - bfsort Sort PCI devices into breadth-first order. - This sorting is done to get a device - order compatible with older (<= 2.4) kernels. - nobfsort Don't sort PCI devices into breadth-first order. - pcie_bus_tune_off Disable PCIe MPS (Max Payload Size) - tuning and use the BIOS-configured MPS defaults. - pcie_bus_safe Set every device's MPS to the largest value - supported by all devices below the root complex. - pcie_bus_perf Set device MPS to the largest allowable MPS - based on its parent bus. Also set MRRS (Max - Read Request Size) to the largest supported - value (no larger than the MPS that the device - or bus can support) for best performance. - pcie_bus_peer2peer Set every device's MPS to 128B, which - every device is guaranteed to support. This - configuration allows peer-to-peer DMA between - any pair of devices, possibly at the cost of - reduced performance. This also guarantees - that hot-added devices will work. - cbiosize=nn[KMG] The fixed amount of bus space which is - reserved for the CardBus bridge's IO window. - The default value is 256 bytes. - cbmemsize=nn[KMG] The fixed amount of bus space which is - reserved for the CardBus bridge's memory - window. The default value is 64 megabytes. - resource_alignment= - Format: - [@][:]:.[; ...] - [@]pci::\ - [::][; ...] - Specifies alignment and device to reassign - aligned memory resources. - If is not specified, - PAGE_SIZE is used as alignment. - PCI-PCI bridge can be specified, if resource - windows need to be expanded. - To specify the alignment for several - instances of a device, the PCI vendor, - device, subvendor, and subdevice may be - specified, e.g., 4096@pci:8086:9c22:103c:198f - ecrc= Enable/disable PCIe ECRC (transaction layer - end-to-end CRC checking). - bios: Use BIOS/firmware settings. This is the - the default. - off: Turn ECRC off - on: Turn ECRC on. - hpiosize=nn[KMG] The fixed amount of bus space which is - reserved for hotplug bridge's IO window. - Default size is 256 bytes. - hpmemsize=nn[KMG] The fixed amount of bus space which is - reserved for hotplug bridge's memory window. - Default size is 2 megabytes. - hpbussize=nn The minimum amount of additional bus numbers - reserved for buses below a hotplug bridge. - Default is 1. - realloc= Enable/disable reallocating PCI bridge resources - if allocations done by BIOS are too small to - accommodate resources required by all child - devices. - off: Turn realloc off - on: Turn realloc on - realloc same as realloc=on - noari do not use PCIe ARI. - pcie_scan_all Scan all possible PCIe devices. Otherwise we - only look for one device below a PCIe downstream - port. - - pcie_aspm= [PCIE] Forcibly enable or disable PCIe Active State Power - Management. - off Disable ASPM. - force Enable ASPM even on devices that claim not to support it. - WARNING: Forcing ASPM on may cause system lockups. - - pcie_hp= [PCIE] PCI Express Hotplug driver options: - nomsi Do not use MSI for PCI Express Native Hotplug (this - makes all PCIe ports use INTx for hotplug services). - - pcie_ports= [PCIE] PCIe ports handling: - auto Ask the BIOS whether or not to use native PCIe services - associated with PCIe ports (PME, hot-plug, AER). Use - them only if that is allowed by the BIOS. - native Use native PCIe services associated with PCIe ports - unconditionally. - compat Treat PCIe ports as PCI-to-PCI bridges, disable the PCIe - ports driver. - - pcie_port_pm= [PCIE] PCIe port power management handling: - off Disable power management of all PCIe ports - force Forcibly enable power management of all PCIe ports - - pcie_pme= [PCIE,PM] Native PCIe PME signaling options: - nomsi Do not use MSI for native PCIe PME signaling (this makes - all PCIe root ports use INTx for all services). - - pcmv= [HW,PCMCIA] BadgePAD 4 - - pd_ignore_unused - [PM] - Keep all power-domains already enabled by bootloader on, - even if no driver has claimed them. This is useful - for debug and development, but should not be - needed on a platform with proper driver support. - - pd. [PARIDE] - See Documentation/blockdev/paride.txt. - - pdcchassis= [PARISC,HW] Disable/Enable PDC Chassis Status codes at - boot time. - Format: { 0 | 1 } - See arch/parisc/kernel/pdc_chassis.c - - percpu_alloc= Select which percpu first chunk allocator to use. - Currently supported values are "embed" and "page". - Archs may support subset or none of the selections. - See comments in mm/percpu.c for details on each - allocator. This parameter is primarily for debugging - and performance comparison. - - pf. [PARIDE] - See Documentation/blockdev/paride.txt. - - pg. [PARIDE] - See Documentation/blockdev/paride.txt. - - pirq= [SMP,APIC] Manual mp-table setup - See Documentation/x86/i386/IO-APIC.txt. - - plip= [PPT,NET] Parallel port network link - Format: { parport | timid | 0 } - See also Documentation/parport.txt. - - pmtmr= [X86] Manual setup of pmtmr I/O Port. - Override pmtimer IOPort with a hex value. - e.g. pmtmr=0x508 - - pnp.debug=1 [PNP] - Enable PNP debug messages (depends on the - CONFIG_PNP_DEBUG_MESSAGES option). Change at run-time - via /sys/module/pnp/parameters/debug. We always show - current resource usage; turning this on also shows - possible settings and some assignment information. - - pnpacpi= [ACPI] - { off } - - pnpbios= [ISAPNP] - { on | off | curr | res | no-curr | no-res } - - pnp_reserve_irq= - [ISAPNP] Exclude IRQs for the autoconfiguration - - pnp_reserve_dma= - [ISAPNP] Exclude DMAs for the autoconfiguration - - pnp_reserve_io= [ISAPNP] Exclude I/O ports for the autoconfiguration - Ranges are in pairs (I/O port base and size). - - pnp_reserve_mem= - [ISAPNP] Exclude memory regions for the - autoconfiguration. - Ranges are in pairs (memory base and size). - - ports= [IP_VS_FTP] IPVS ftp helper module - Default is 21. - Up to 8 (IP_VS_APP_MAX_PORTS) ports - may be specified. - Format: ,.... - - ppc_strict_facility_enable - [PPC] This option catches any kernel floating point, - Altivec, VSX and SPE outside of regions specifically - allowed (eg kernel_enable_fpu()/kernel_disable_fpu()). - There is some performance impact when enabling this. - - print-fatal-signals= - [KNL] debug: print fatal signals - - If enabled, warn about various signal handling - related application anomalies: too many signals, - too many POSIX.1 timers, fatal signals causing a - coredump - etc. - - If you hit the warning due to signal overflow, - you might want to try "ulimit -i unlimited". - - default: off. - - printk.always_kmsg_dump= - Trigger kmsg_dump for cases other than kernel oops or - panics - Format: (1/Y/y=enable, 0/N/n=disable) - default: disabled - - printk.devkmsg={on,off,ratelimit} - Control writing to /dev/kmsg. - on - unlimited logging to /dev/kmsg from userspace - off - logging to /dev/kmsg disabled - ratelimit - ratelimit the logging - Default: ratelimit - - printk.time= Show timing data prefixed to each printk message line - Format: (1/Y/y=enable, 0/N/n=disable) - - processor.max_cstate= [HW,ACPI] - Limit processor to maximum C-state - max_cstate=9 overrides any DMI blacklist limit. - - processor.nocst [HW,ACPI] - Ignore the _CST method to determine C-states, - instead using the legacy FADT method - - profile= [KNL] Enable kernel profiling via /proc/profile - Format: [schedule,] - Param: "schedule" - profile schedule points. - Param: - step/bucket size as a power of 2 for - statistical time based profiling. - Param: "sleep" - profile D-state sleeping (millisecs). - Requires CONFIG_SCHEDSTATS - Param: "kvm" - profile VM exits. - - prompt_ramdisk= [RAM] List of RAM disks to prompt for floppy disk - before loading. - See Documentation/blockdev/ramdisk.txt. - - psmouse.proto= [HW,MOUSE] Highest PS2 mouse protocol extension to - probe for; one of (bare|imps|exps|lifebook|any). - psmouse.rate= [HW,MOUSE] Set desired mouse report rate, in reports - per second. - psmouse.resetafter= [HW,MOUSE] - Try to reset the device after so many bad packets - (0 = never). - psmouse.resolution= - [HW,MOUSE] Set desired mouse resolution, in dpi. - psmouse.smartscroll= - [HW,MOUSE] Controls Logitech smartscroll autorepeat. - 0 = disabled, 1 = enabled (default). - - pstore.backend= Specify the name of the pstore backend to use - - pt. [PARIDE] - See Documentation/blockdev/paride.txt. - - pty.legacy_count= - [KNL] Number of legacy pty's. Overwrites compiled-in - default number. - - quiet [KNL] Disable most log messages - - r128= [HW,DRM] - - raid= [HW,RAID] - See Documentation/md.txt. - - ramdisk_size= [RAM] Sizes of RAM disks in kilobytes - See Documentation/blockdev/ramdisk.txt. - - rcu_nocbs= [KNL] - The argument is a cpu list, as described above. - - In kernels built with CONFIG_RCU_NOCB_CPU=y, set - the specified list of CPUs to be no-callback CPUs. - Invocation of these CPUs' RCU callbacks will - be offloaded to "rcuox/N" kthreads created for - that purpose, where "x" is "b" for RCU-bh, "p" - for RCU-preempt, and "s" for RCU-sched, and "N" - is the CPU number. This reduces OS jitter on the - offloaded CPUs, which can be useful for HPC and - real-time workloads. It can also improve energy - efficiency for asymmetric multiprocessors. - - rcu_nocb_poll [KNL] - Rather than requiring that offloaded CPUs - (specified by rcu_nocbs= above) explicitly - awaken the corresponding "rcuoN" kthreads, - make these kthreads poll for callbacks. - This improves the real-time response for the - offloaded CPUs by relieving them of the need to - wake up the corresponding kthread, but degrades - energy efficiency by requiring that the kthreads - periodically wake up to do the polling. - - rcutree.blimit= [KNL] - Set maximum number of finished RCU callbacks to - process in one batch. - - rcutree.dump_tree= [KNL] - Dump the structure of the rcu_node combining tree - out at early boot. This is used for diagnostic - purposes, to verify correct tree setup. - - rcutree.gp_cleanup_delay= [KNL] - Set the number of jiffies to delay each step of - RCU grace-period cleanup. This only has effect - when CONFIG_RCU_TORTURE_TEST_SLOW_CLEANUP is set. - - rcutree.gp_init_delay= [KNL] - Set the number of jiffies to delay each step of - RCU grace-period initialization. This only has - effect when CONFIG_RCU_TORTURE_TEST_SLOW_INIT - is set. - - rcutree.gp_preinit_delay= [KNL] - Set the number of jiffies to delay each step of - RCU grace-period pre-initialization, that is, - the propagation of recent CPU-hotplug changes up - the rcu_node combining tree. This only has effect - when CONFIG_RCU_TORTURE_TEST_SLOW_PREINIT is set. - - rcutree.rcu_fanout_exact= [KNL] - Disable autobalancing of the rcu_node combining - tree. This is used by rcutorture, and might - possibly be useful for architectures having high - cache-to-cache transfer latencies. - - rcutree.rcu_fanout_leaf= [KNL] - Change the number of CPUs assigned to each - leaf rcu_node structure. Useful for very - large systems, which will choose the value 64, - and for NUMA systems with large remote-access - latencies, which will choose a value aligned - with the appropriate hardware boundaries. - - rcutree.jiffies_till_sched_qs= [KNL] - Set required age in jiffies for a - given grace period before RCU starts - soliciting quiescent-state help from - rcu_note_context_switch(). - - rcutree.jiffies_till_first_fqs= [KNL] - Set delay from grace-period initialization to - first attempt to force quiescent states. - Units are jiffies, minimum value is zero, - and maximum value is HZ. - - rcutree.jiffies_till_next_fqs= [KNL] - Set delay between subsequent attempts to force - quiescent states. Units are jiffies, minimum - value is one, and maximum value is HZ. - - rcutree.kthread_prio= [KNL,BOOT] - Set the SCHED_FIFO priority of the RCU per-CPU - kthreads (rcuc/N). This value is also used for - the priority of the RCU boost threads (rcub/N) - and for the RCU grace-period kthreads (rcu_bh, - rcu_preempt, and rcu_sched). If RCU_BOOST is - set, valid values are 1-99 and the default is 1 - (the least-favored priority). Otherwise, when - RCU_BOOST is not set, valid values are 0-99 and - the default is zero (non-realtime operation). - - rcutree.rcu_nocb_leader_stride= [KNL] - Set the number of NOCB kthread groups, which - defaults to the square root of the number of - CPUs. Larger numbers reduces the wakeup overhead - on the per-CPU grace-period kthreads, but increases - that same overhead on each group's leader. - - rcutree.qhimark= [KNL] - Set threshold of queued RCU callbacks beyond which - batch limiting is disabled. - - rcutree.qlowmark= [KNL] - Set threshold of queued RCU callbacks below which - batch limiting is re-enabled. - - rcutree.rcu_idle_gp_delay= [KNL] - Set wakeup interval for idle CPUs that have - RCU callbacks (RCU_FAST_NO_HZ=y). - - rcutree.rcu_idle_lazy_gp_delay= [KNL] - Set wakeup interval for idle CPUs that have - only "lazy" RCU callbacks (RCU_FAST_NO_HZ=y). - Lazy RCU callbacks are those which RCU can - prove do nothing more than free memory. - - rcuperf.gp_exp= [KNL] - Measure performance of expedited synchronous - grace-period primitives. - - rcuperf.holdoff= [KNL] - Set test-start holdoff period. The purpose of - this parameter is to delay the start of the - test until boot completes in order to avoid - interference. - - rcuperf.nreaders= [KNL] - Set number of RCU readers. The value -1 selects - N, where N is the number of CPUs. A value - "n" less than -1 selects N-n+1, where N is again - the number of CPUs. For example, -2 selects N - (the number of CPUs), -3 selects N+1, and so on. - A value of "n" less than or equal to -N selects - a single reader. - - rcuperf.nwriters= [KNL] - Set number of RCU writers. The values operate - the same as for rcuperf.nreaders. - N, where N is the number of CPUs - - rcuperf.perf_runnable= [BOOT] - Start rcuperf running at boot time. - - rcuperf.shutdown= [KNL] - Shut the system down after performance tests - complete. This is useful for hands-off automated - testing. - - rcuperf.perf_type= [KNL] - Specify the RCU implementation to test. - - rcuperf.verbose= [KNL] - Enable additional printk() statements. - - rcutorture.cbflood_inter_holdoff= [KNL] - Set holdoff time (jiffies) between successive - callback-flood tests. - - rcutorture.cbflood_intra_holdoff= [KNL] - Set holdoff time (jiffies) between successive - bursts of callbacks within a given callback-flood - test. - - rcutorture.cbflood_n_burst= [KNL] - Set the number of bursts making up a given - callback-flood test. Set this to zero to - disable callback-flood testing. - - rcutorture.cbflood_n_per_burst= [KNL] - Set the number of callbacks to be registered - in a given burst of a callback-flood test. - - rcutorture.fqs_duration= [KNL] - Set duration of force_quiescent_state bursts - in microseconds. - - rcutorture.fqs_holdoff= [KNL] - Set holdoff time within force_quiescent_state bursts - in microseconds. - - rcutorture.fqs_stutter= [KNL] - Set wait time between force_quiescent_state bursts - in seconds. - - rcutorture.gp_cond= [KNL] - Use conditional/asynchronous update-side - primitives, if available. - - rcutorture.gp_exp= [KNL] - Use expedited update-side primitives, if available. - - rcutorture.gp_normal= [KNL] - Use normal (non-expedited) asynchronous - update-side primitives, if available. - - rcutorture.gp_sync= [KNL] - Use normal (non-expedited) synchronous - update-side primitives, if available. If all - of rcutorture.gp_cond=, rcutorture.gp_exp=, - rcutorture.gp_normal=, and rcutorture.gp_sync= - are zero, rcutorture acts as if is interpreted - they are all non-zero. - - rcutorture.n_barrier_cbs= [KNL] - Set callbacks/threads for rcu_barrier() testing. - - rcutorture.nfakewriters= [KNL] - Set number of concurrent RCU writers. These just - stress RCU, they don't participate in the actual - test, hence the "fake". - - rcutorture.nreaders= [KNL] - Set number of RCU readers. The value -1 selects - N-1, where N is the number of CPUs. A value - "n" less than -1 selects N-n-2, where N is again - the number of CPUs. For example, -2 selects N - (the number of CPUs), -3 selects N+1, and so on. - - rcutorture.object_debug= [KNL] - Enable debug-object double-call_rcu() testing. - - rcutorture.onoff_holdoff= [KNL] - Set time (s) after boot for CPU-hotplug testing. - - rcutorture.onoff_interval= [KNL] - Set time (s) between CPU-hotplug operations, or - zero to disable CPU-hotplug testing. - - rcutorture.shuffle_interval= [KNL] - Set task-shuffle interval (s). Shuffling tasks - allows some CPUs to go into dyntick-idle mode - during the rcutorture test. - - rcutorture.shutdown_secs= [KNL] - Set time (s) after boot system shutdown. This - is useful for hands-off automated testing. - - rcutorture.stall_cpu= [KNL] - Duration of CPU stall (s) to test RCU CPU stall - warnings, zero to disable. - - rcutorture.stall_cpu_holdoff= [KNL] - Time to wait (s) after boot before inducing stall. - - rcutorture.stat_interval= [KNL] - Time (s) between statistics printk()s. - - rcutorture.stutter= [KNL] - Time (s) to stutter testing, for example, specifying - five seconds causes the test to run for five seconds, - wait for five seconds, and so on. This tests RCU's - ability to transition abruptly to and from idle. - - rcutorture.test_boost= [KNL] - Test RCU priority boosting? 0=no, 1=maybe, 2=yes. - "Maybe" means test if the RCU implementation - under test support RCU priority boosting. - - rcutorture.test_boost_duration= [KNL] - Duration (s) of each individual boost test. - - rcutorture.test_boost_interval= [KNL] - Interval (s) between each boost test. - - rcutorture.test_no_idle_hz= [KNL] - Test RCU's dyntick-idle handling. See also the - rcutorture.shuffle_interval parameter. - - rcutorture.torture_runnable= [BOOT] - Start rcutorture running at boot time. - - rcutorture.torture_type= [KNL] - Specify the RCU implementation to test. - - rcutorture.verbose= [KNL] - Enable additional printk() statements. - - rcupdate.rcu_cpu_stall_suppress= [KNL] - Suppress RCU CPU stall warning messages. - - rcupdate.rcu_cpu_stall_timeout= [KNL] - Set timeout for RCU CPU stall warning messages. - - rcupdate.rcu_expedited= [KNL] - Use expedited grace-period primitives, for - example, synchronize_rcu_expedited() instead - of synchronize_rcu(). This reduces latency, - but can increase CPU utilization, degrade - real-time latency, and degrade energy efficiency. - No effect on CONFIG_TINY_RCU kernels. - - rcupdate.rcu_normal= [KNL] - Use only normal grace-period primitives, - for example, synchronize_rcu() instead of - synchronize_rcu_expedited(). This improves - real-time latency, CPU utilization, and - energy efficiency, but can expose users to - increased grace-period latency. This parameter - overrides rcupdate.rcu_expedited. No effect on - CONFIG_TINY_RCU kernels. - - rcupdate.rcu_normal_after_boot= [KNL] - Once boot has completed (that is, after - rcu_end_inkernel_boot() has been invoked), use - only normal grace-period primitives. No effect - on CONFIG_TINY_RCU kernels. - - rcupdate.rcu_task_stall_timeout= [KNL] - Set timeout in jiffies for RCU task stall warning - messages. Disable with a value less than or equal - to zero. - - rcupdate.rcu_self_test= [KNL] - Run the RCU early boot self tests - - rcupdate.rcu_self_test_bh= [KNL] - Run the RCU bh early boot self tests - - rcupdate.rcu_self_test_sched= [KNL] - Run the RCU sched early boot self tests - - rdinit= [KNL] - Format: - Run specified binary instead of /init from the ramdisk, - used for early userspace startup. See initrd. - - reboot= [KNL] - Format (x86 or x86_64): - [w[arm] | c[old] | h[ard] | s[oft] | g[pio]] \ - [[,]s[mp]#### \ - [[,]b[ios] | a[cpi] | k[bd] | t[riple] | e[fi] | p[ci]] \ - [[,]f[orce] - Where reboot_mode is one of warm (soft) or cold (hard) or gpio, - reboot_type is one of bios, acpi, kbd, triple, efi, or pci, - reboot_force is either force or not specified, - reboot_cpu is s[mp]#### with #### being the processor - to be used for rebooting. - - relax_domain_level= - [KNL, SMP] Set scheduler's default relax_domain_level. - See Documentation/cgroup-v1/cpusets.txt. - - relative_sleep_states= - [SUSPEND] Use sleep state labeling where the deepest - state available other than hibernation is always "mem". - Format: { "0" | "1" } - 0 -- Traditional sleep state labels. - 1 -- Relative sleep state labels. - - reserve= [KNL,BUGS] Force the kernel to ignore some iomem area - - reservetop= [X86-32] - Format: nn[KMG] - Reserves a hole at the top of the kernel virtual - address space. - - reservelow= [X86] - Format: nn[K] - Set the amount of memory to reserve for BIOS at - the bottom of the address space. - - reset_devices [KNL] Force drivers to reset the underlying device - during initialization. - - resume= [SWSUSP] - Specify the partition device for software suspend - Format: - {/dev/ | PARTUUID= | : | } - - resume_offset= [SWSUSP] - Specify the offset from the beginning of the partition - given by "resume=" at which the swap header is located, - in units (needed only for swap files). - See Documentation/power/swsusp-and-swap-files.txt - - resumedelay= [HIBERNATION] Delay (in seconds) to pause before attempting to - read the resume files - - resumewait [HIBERNATION] Wait (indefinitely) for resume device to show up. - Useful for devices that are detected asynchronously - (e.g. USB and MMC devices). - - hibernate= [HIBERNATION] - noresume Don't check if there's a hibernation image - present during boot. - nocompress Don't compress/decompress hibernation images. - no Disable hibernation and resume. - protect_image Turn on image protection during restoration - (that will set all pages holding image data - during restoration read-only). - - retain_initrd [RAM] Keep initrd memory after extraction - - rfkill.default_state= - 0 "airplane mode". All wifi, bluetooth, wimax, gps, fm, - etc. communication is blocked by default. - 1 Unblocked. - - rfkill.master_switch_mode= - 0 The "airplane mode" button does nothing. - 1 The "airplane mode" button toggles between everything - blocked and the previous configuration. - 2 The "airplane mode" button toggles between everything - blocked and everything unblocked. - - rhash_entries= [KNL,NET] - Set number of hash buckets for route cache - - ro [KNL] Mount root device read-only on boot - - rodata= [KNL] - on Mark read-only kernel memory as read-only (default). - off Leave read-only kernel memory writable for debugging. - - rockchip.usb_uart - Enable the uart passthrough on the designated usb port - on Rockchip SoCs. When active, the signals of the - debug-uart get routed to the D+ and D- pins of the usb - port and the regular usb controller gets disabled. - - root= [KNL] Root filesystem - See name_to_dev_t comment in init/do_mounts.c. - - rootdelay= [KNL] Delay (in seconds) to pause before attempting to - mount the root filesystem - - rootflags= [KNL] Set root filesystem mount option string - - rootfstype= [KNL] Set root filesystem type - - rootwait [KNL] Wait (indefinitely) for root device to show up. - Useful for devices that are detected asynchronously - (e.g. USB and MMC devices). - - rproc_mem=nn[KMG][@address] - [KNL,ARM,CMA] Remoteproc physical memory block. - Memory area to be used by remote processor image, - managed by CMA. - - rw [KNL] Mount root device read-write on boot - - S [KNL] Run init in single mode - - s390_iommu= [HW,S390] - Set s390 IOTLB flushing mode - strict - With strict flushing every unmap operation will result in - an IOTLB flush. Default is lazy flushing before reuse, - which is faster. - - sa1100ir [NET] - See drivers/net/irda/sa1100_ir.c. - - sbni= [NET] Granch SBNI12 leased line adapter - - sched_debug [KNL] Enables verbose scheduler debug messages. - - schedstats= [KNL,X86] Enable or disable scheduled statistics. - Allowed values are enable and disable. This feature - incurs a small amount of overhead in the scheduler - but is useful for debugging and performance tuning. - - skew_tick= [KNL] Offset the periodic timer tick per cpu to mitigate - xtime_lock contention on larger systems, and/or RCU lock - contention on all systems with CONFIG_MAXSMP set. - Format: { "0" | "1" } - 0 -- disable. (may be 1 via CONFIG_CMDLINE="skew_tick=1" - 1 -- enable. - Note: increases power consumption, thus should only be - enabled if running jitter sensitive (HPC/RT) workloads. - - security= [SECURITY] Choose a security module to enable at boot. - If this boot parameter is not specified, only the first - security module asking for security registration will be - loaded. An invalid security module name will be treated - as if no module has been chosen. - - selinux= [SELINUX] Disable or enable SELinux at boot time. - Format: { "0" | "1" } - See security/selinux/Kconfig help text. - 0 -- disable. - 1 -- enable. - Default value is set via kernel config option. - If enabled at boot time, /selinux/disable can be used - later to disable prior to initial policy load. - - apparmor= [APPARMOR] Disable or enable AppArmor at boot time - Format: { "0" | "1" } - See security/apparmor/Kconfig help text - 0 -- disable. - 1 -- enable. - Default value is set via kernel config option. - - serialnumber [BUGS=X86-32] - - shapers= [NET] - Maximal number of shapers. - - show_msr= [x86] show boot-time MSR settings - Format: { } - Show boot-time (BIOS-initialized) MSR settings. - The parameter means the number of CPUs to show, - for example 1 means boot CPU only. - - simeth= [IA-64] - simscsi= - - slram= [HW,MTD] - - slab_nomerge [MM] - Disable merging of slabs with similar size. May be - necessary if there is some reason to distinguish - allocs to different slabs. Debug options disable - merging on their own. - For more information see Documentation/vm/slub.txt. - - slab_max_order= [MM, SLAB] - Determines the maximum allowed order for slabs. - A high setting may cause OOMs due to memory - fragmentation. Defaults to 1 for systems with - more than 32MB of RAM, 0 otherwise. - - slub_debug[=options[,slabs]] [MM, SLUB] - Enabling slub_debug allows one to determine the - culprit if slab objects become corrupted. Enabling - slub_debug can create guard zones around objects and - may poison objects when not in use. Also tracks the - last alloc / free. For more information see - Documentation/vm/slub.txt. - - slub_max_order= [MM, SLUB] - Determines the maximum allowed order for slabs. - A high setting may cause OOMs due to memory - fragmentation. For more information see - Documentation/vm/slub.txt. - - slub_min_objects= [MM, SLUB] - The minimum number of objects per slab. SLUB will - increase the slab order up to slub_max_order to - generate a sufficiently large slab able to contain - the number of objects indicated. The higher the number - of objects the smaller the overhead of tracking slabs - and the less frequently locks need to be acquired. - For more information see Documentation/vm/slub.txt. - - slub_min_order= [MM, SLUB] - Determines the minimum page order for slabs. Must be - lower than slub_max_order. - For more information see Documentation/vm/slub.txt. - - slub_nomerge [MM, SLUB] - Same with slab_nomerge. This is supported for legacy. - See slab_nomerge for more information. - - smart2= [HW] - Format: [,[,...,]] - - smsc-ircc2.nopnp [HW] Don't use PNP to discover SMC devices - smsc-ircc2.ircc_cfg= [HW] Device configuration I/O port - smsc-ircc2.ircc_sir= [HW] SIR base I/O port - smsc-ircc2.ircc_fir= [HW] FIR base I/O port - smsc-ircc2.ircc_irq= [HW] IRQ line - smsc-ircc2.ircc_dma= [HW] DMA channel - smsc-ircc2.ircc_transceiver= [HW] Transceiver type: - 0: Toshiba Satellite 1800 (GP data pin select) - 1: Fast pin select (default) - 2: ATC IRMode - - smt [KNL,S390] Set the maximum number of threads (logical - CPUs) to use per physical CPU on systems capable of - symmetric multithreading (SMT). Will be capped to the - actual hardware limit. - Format: - Default: -1 (no limit) - - softlockup_panic= - [KNL] Should the soft-lockup detector generate panics. - Format: - - softlockup_all_cpu_backtrace= - [KNL] Should the soft-lockup detector generate - backtraces on all cpus. - Format: - - sonypi.*= [HW] Sony Programmable I/O Control Device driver - See Documentation/laptops/sonypi.txt - - spia_io_base= [HW,MTD] - spia_fio_base= - spia_pedr= - spia_peddr= - - stacktrace [FTRACE] - Enabled the stack tracer on boot up. - - stacktrace_filter=[function-list] - [FTRACE] Limit the functions that the stack tracer - will trace at boot up. function-list is a comma separated - list of functions. This list can be changed at run - time by the stack_trace_filter file in the debugfs - tracing directory. Note, this enables stack tracing - and the stacktrace above is not needed. - - sti= [PARISC,HW] - Format: - Set the STI (builtin display/keyboard on the HP-PARISC - machines) console (graphic card) which should be used - as the initial boot-console. - See also comment in drivers/video/console/sticore.c. - - sti_font= [HW] - See comment in drivers/video/console/sticore.c. - - stifb= [HW] - Format: bpp:[:[:...]] - - sunrpc.min_resvport= - sunrpc.max_resvport= - [NFS,SUNRPC] - SunRPC servers often require that client requests - originate from a privileged port (i.e. a port in the - range 0 < portnr < 1024). - An administrator who wishes to reserve some of these - ports for other uses may adjust the range that the - kernel's sunrpc client considers to be privileged - using these two parameters to set the minimum and - maximum port values. - - sunrpc.svc_rpc_per_connection_limit= - [NFS,SUNRPC] - Limit the number of requests that the server will - process in parallel from a single connection. - The default value is 0 (no limit). - - sunrpc.pool_mode= - [NFS] - Control how the NFS server code allocates CPUs to - service thread pools. Depending on how many NICs - you have and where their interrupts are bound, this - option will affect which CPUs will do NFS serving. - Note: this parameter cannot be changed while the - NFS server is running. - - auto the server chooses an appropriate mode - automatically using heuristics - global a single global pool contains all CPUs - percpu one pool for each CPU - pernode one pool for each NUMA node (equivalent - to global on non-NUMA machines) - - sunrpc.tcp_slot_table_entries= - sunrpc.udp_slot_table_entries= - [NFS,SUNRPC] - Sets the upper limit on the number of simultaneous - RPC calls that can be sent from the client to a - server. Increasing these values may allow you to - improve throughput, but will also increase the - amount of memory reserved for use by the client. - - suspend.pm_test_delay= - [SUSPEND] - Sets the number of seconds to remain in a suspend test - mode before resuming the system (see - /sys/power/pm_test). Only available when CONFIG_PM_DEBUG - is set. Default value is 5. - - swapaccount=[0|1] - [KNL] Enable accounting of swap in memory resource - controller if no parameter or 1 is given or disable - it if 0 is given (See Documentation/cgroup-v1/memory.txt) - - swiotlb= [ARM,IA-64,PPC,MIPS,X86] - Format: { | force } - -- Number of I/O TLB slabs - force -- force using of bounce buffers even if they - wouldn't be automatically used by the kernel - - switches= [HW,M68k] - - sysfs.deprecated=0|1 [KNL] - Enable/disable old style sysfs layout for old udev - on older distributions. When this option is enabled - very new udev will not work anymore. When this option - is disabled (or CONFIG_SYSFS_DEPRECATED not compiled) - in older udev will not work anymore. - Default depends on CONFIG_SYSFS_DEPRECATED_V2 set in - the kernel configuration. - - sysrq_always_enabled - [KNL] - Ignore sysrq setting - this boot parameter will - neutralize any effect of /proc/sys/kernel/sysrq. - Useful for debugging. - - tcpmhash_entries= [KNL,NET] - Set the number of tcp_metrics_hash slots. - Default value is 8192 or 16384 depending on total - ram pages. This is used to specify the TCP metrics - cache size. See Documentation/networking/ip-sysctl.txt - "tcp_no_metrics_save" section for more details. - - tdfx= [HW,DRM] - - test_suspend= [SUSPEND][,N] - Specify "mem" (for Suspend-to-RAM) or "standby" (for - standby suspend) or "freeze" (for suspend type freeze) - as the system sleep state during system startup with - the optional capability to repeat N number of times. - The system is woken from this state using a - wakeup-capable RTC alarm. - - thash_entries= [KNL,NET] - Set number of hash buckets for TCP connection - - thermal.act= [HW,ACPI] - -1: disable all active trip points in all thermal zones - : override all lowest active trip points - - thermal.crt= [HW,ACPI] - -1: disable all critical trip points in all thermal zones - : override all critical trip points - - thermal.nocrt= [HW,ACPI] - Set to disable actions on ACPI thermal zone - critical and hot trip points. - - thermal.off= [HW,ACPI] - 1: disable ACPI thermal control - - thermal.psv= [HW,ACPI] - -1: disable all passive trip points - : override all passive trip points to this - value - - thermal.tzp= [HW,ACPI] - Specify global default ACPI thermal zone polling rate - : poll all this frequency - 0: no polling (default) - - threadirqs [KNL] - Force threading of all interrupt handlers except those - marked explicitly IRQF_NO_THREAD. - - tmem [KNL,XEN] - Enable the Transcendent memory driver if built-in. - - tmem.cleancache=0|1 [KNL, XEN] - Default is on (1). Disable the usage of the cleancache - API to send anonymous pages to the hypervisor. - - tmem.frontswap=0|1 [KNL, XEN] - Default is on (1). Disable the usage of the frontswap - API to send swap pages to the hypervisor. If disabled - the selfballooning and selfshrinking are force disabled. - - tmem.selfballooning=0|1 [KNL, XEN] - Default is on (1). Disable the driving of swap pages - to the hypervisor. - - tmem.selfshrinking=0|1 [KNL, XEN] - Default is on (1). Partial swapoff that immediately - transfers pages from Xen hypervisor back to the - kernel based on different criteria. - - topology= [S390] - Format: {off | on} - Specify if the kernel should make use of the cpu - topology information if the hardware supports this. - The scheduler will make use of this information and - e.g. base its process migration decisions on it. - Default is on. - - topology_updates= [KNL, PPC, NUMA] - Format: {off} - Specify if the kernel should ignore (off) - topology updates sent by the hypervisor to this - LPAR. - - tp720= [HW,PS2] - - tpm_suspend_pcr=[HW,TPM] - Format: integer pcr id - Specify that at suspend time, the tpm driver - should extend the specified pcr with zeros, - as a workaround for some chips which fail to - flush the last written pcr on TPM_SaveState. - This will guarantee that all the other pcrs - are saved. - - trace_buf_size=nn[KMG] - [FTRACE] will set tracing buffer size on each cpu. - - trace_event=[event-list] - [FTRACE] Set and start specified trace events in order - 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. - The option-list is a comma delimited list of options - that can be enabled or disabled just as if you were - to echo the option name into - - /sys/kernel/debug/tracing/trace_options - - For example, to enable stacktrace option (to dump the - stack trace of each event), add to the command line: - - trace_options=stacktrace - - See also Documentation/trace/ftrace.txt "trace options" - section. - - tp_printk[FTRACE] - Have the tracepoints sent to printk as well as the - tracing ring buffer. This is useful for early boot up - where the system hangs or reboots and does not give the - option for reading the tracing buffer or performing a - ftrace_dump_on_oops. - - To turn off having tracepoints sent to printk, - echo 0 > /proc/sys/kernel/tracepoint_printk - Note, echoing 1 into this file without the - tracepoint_printk kernel cmdline option has no effect. - - ** CAUTION ** - - Having tracepoints sent to printk() and activating high - frequency tracepoints such as irq or sched, can cause - the system to live lock. - - traceoff_on_warning - [FTRACE] enable this option to disable tracing when a - warning is hit. This turns off "tracing_on". Tracing can - be enabled again by echoing '1' into the "tracing_on" - file located in /sys/kernel/debug/tracing/ - - This option is useful, as it disables the trace before - the WARNING dump is called, which prevents the trace to - be filled with content caused by the warning output. - - This option can also be set at run time via the sysctl - option: kernel/traceoff_on_warning - - transparent_hugepage= - [KNL] - Format: [always|madvise|never] - Can be used to control the default behavior of the system - with respect to transparent hugepages. - See Documentation/vm/transhuge.txt for more details. - - tsc= Disable clocksource stability checks for TSC. - Format: - [x86] reliable: mark tsc clocksource as reliable, this - disables clocksource verification at runtime, as well - as the stability checks done at bootup. Used to enable - high-resolution timer mode on older hardware, and in - virtualized environment. - [x86] noirqtime: Do not use TSC to do irq accounting. - Used to run time disable IRQ_TIME_ACCOUNTING on any - platforms where RDTSC is slow and this accounting - can add overhead. - - turbografx.map[2|3]= [HW,JOY] - TurboGraFX parallel port interface - Format: - ,,,,,,, - See also Documentation/input/joystick-parport.txt - - udbg-immortal [PPC] When debugging early kernel crashes that - happen after console_init() and before a proper - console driver takes over, this boot options might - help "seeing" what's going on. - - uhash_entries= [KNL,NET] - Set number of hash buckets for UDP/UDP-Lite connections - - uhci-hcd.ignore_oc= - [USB] Ignore overcurrent events (default N). - Some badly-designed motherboards generate lots of - bogus events, for ports that aren't wired to - anything. Set this parameter to avoid log spamming. - Note that genuine overcurrent events won't be - reported either. - - unknown_nmi_panic - [X86] Cause panic on unknown NMI. - - usbcore.authorized_default= - [USB] Default USB device authorization: - (default -1 = authorized except for wireless USB, - 0 = not authorized, 1 = authorized) - - usbcore.autosuspend= - [USB] The autosuspend time delay (in seconds) used - for newly-detected USB devices (default 2). This - is the time required before an idle device will be - autosuspended. Devices for which the delay is set - to a negative value won't be autosuspended at all. - - usbcore.usbfs_snoop= - [USB] Set to log all usbfs traffic (default 0 = off). - - usbcore.usbfs_snoop_max= - [USB] Maximum number of bytes to snoop in each URB - (default = 65536). - - usbcore.blinkenlights= - [USB] Set to cycle leds on hubs (default 0 = off). - - usbcore.old_scheme_first= - [USB] Start with the old device initialization - scheme (default 0 = off). - - usbcore.usbfs_memory_mb= - [USB] Memory limit (in MB) for buffers allocated by - usbfs (default = 16, 0 = max = 2047). - - usbcore.use_both_schemes= - [USB] Try the other device initialization scheme - if the first one fails (default 1 = enabled). - - usbcore.initial_descriptor_timeout= - [USB] Specifies timeout for the initial 64-byte - USB_REQ_GET_DESCRIPTOR request in milliseconds - (default 5000 = 5.0 seconds). - - usbcore.nousb [USB] Disable the USB subsystem - - usbhid.mousepoll= - [USBHID] The interval which mice are to be polled at. - - usb-storage.delay_use= - [UMS] The delay in seconds before a new device is - scanned for Logical Units (default 1). - - usb-storage.quirks= - [UMS] A list of quirks entries to supplement or - override the built-in unusual_devs list. List - entries are separated by commas. Each entry has - the form VID:PID:Flags where VID and PID are Vendor - and Product ID values (4-digit hex numbers) and - Flags is a set of characters, each corresponding - to a common usb-storage quirk flag as follows: - a = SANE_SENSE (collect more than 18 bytes - of sense data); - b = BAD_SENSE (don't collect more than 18 - bytes of sense data); - c = FIX_CAPACITY (decrease the reported - device capacity by one sector); - d = NO_READ_DISC_INFO (don't use - READ_DISC_INFO command); - e = NO_READ_CAPACITY_16 (don't use - READ_CAPACITY_16 command); - f = NO_REPORT_OPCODES (don't use report opcodes - command, uas only); - g = MAX_SECTORS_240 (don't transfer more than - 240 sectors at a time, uas only); - h = CAPACITY_HEURISTICS (decrease the - reported device capacity by one - sector if the number is odd); - i = IGNORE_DEVICE (don't bind to this - device); - j = NO_REPORT_LUNS (don't use report luns - command, uas only); - l = NOT_LOCKABLE (don't try to lock and - unlock ejectable media); - m = MAX_SECTORS_64 (don't transfer more - than 64 sectors = 32 KB at a time); - n = INITIAL_READ10 (force a retry of the - initial READ(10) command); - o = CAPACITY_OK (accept the capacity - reported by the device); - p = WRITE_CACHE (the device cache is ON - by default); - r = IGNORE_RESIDUE (the device reports - bogus residue values); - s = SINGLE_LUN (the device has only one - Logical Unit); - t = NO_ATA_1X (don't allow ATA(12) and ATA(16) - commands, uas only); - u = IGNORE_UAS (don't bind to the uas driver); - w = NO_WP_DETECT (don't test whether the - medium is write-protected). - y = ALWAYS_SYNC (issue a SYNCHRONIZE_CACHE - even if the device claims no cache) - Example: quirks=0419:aaf5:rl,0421:0433:rc - - user_debug= [KNL,ARM] - Format: - See arch/arm/Kconfig.debug help text. - 1 - undefined instruction events - 2 - system calls - 4 - invalid data aborts - 8 - SIGSEGV faults - 16 - SIGBUS faults - Example: user_debug=31 - - userpte= - [X86] Flags controlling user PTE allocations. - - nohigh = do not allocate PTE pages in - HIGHMEM regardless of setting - of CONFIG_HIGHPTE. - - vdso= [X86,SH] - On X86_32, this is an alias for vdso32=. Otherwise: - - vdso=1: enable VDSO (the default) - vdso=0: disable VDSO mapping - - vdso32= [X86] Control the 32-bit vDSO - vdso32=1: enable 32-bit VDSO - vdso32=0 or vdso32=2: disable 32-bit VDSO - - See the help text for CONFIG_COMPAT_VDSO for more - details. If CONFIG_COMPAT_VDSO is set, the default is - vdso32=0; otherwise, the default is vdso32=1. - - For compatibility with older kernels, vdso32=2 is an - alias for vdso32=0. - - Try vdso32=0 if you encounter an error that says: - dl_main: Assertion `(void *) ph->p_vaddr == _rtld_local._dl_sysinfo_dso' failed! - - vector= [IA-64,SMP] - vector=percpu: enable percpu vector domain - - video= [FB] Frame buffer configuration - See Documentation/fb/modedb.txt. - - video.brightness_switch_enabled= [0,1] - If set to 1, on receiving an ACPI notify event - generated by hotkey, video driver will adjust brightness - level and then send out the event to user space through - the allocated input device; If set to 0, video driver - will only send out the event without touching backlight - brightness level. - default: 1 - - virtio_mmio.device= - [VMMIO] Memory mapped virtio (platform) device. - - @:[:] - where: - := size (can use standard suffixes - like K, M and G) - := physical base address - := interrupt number (as passed to - request_irq()) - := (optional) platform device id - example: - virtio_mmio.device=1K@0x100b0000:48:7 - - Can be used multiple times for multiple devices. - - vga= [BOOT,X86-32] Select a particular video mode - See Documentation/x86/boot.txt and - Documentation/svga.txt. - Use vga=ask for menu. - This is actually a boot loader parameter; the value is - passed to the kernel using a special protocol. - - vmalloc=nn[KMG] [KNL,BOOT] Forces the vmalloc area to have an exact - size of . This can be used to increase the - minimum size (128MB on x86). It can also be used to - decrease the size and leave more room for directly - mapped kernel RAM. - - vmhalt= [KNL,S390] Perform z/VM CP command after system halt. - Format: - - vmpanic= [KNL,S390] Perform z/VM CP command after kernel panic. - Format: - - vmpoff= [KNL,S390] Perform z/VM CP command after power off. - Format: - - vsyscall= [X86-64] - Controls the behavior of vsyscalls (i.e. calls to - fixed addresses of 0xffffffffff600x00 from legacy - code). Most statically-linked binaries and older - versions of glibc use these calls. Because these - functions are at fixed addresses, they make nice - targets for exploits that can control RIP. - - emulate [default] Vsyscalls turn into traps and are - emulated reasonably safely. - - native Vsyscalls are native syscall instructions. - This is a little bit faster than trapping - and makes a few dynamic recompilers work - better than they would in emulation mode. - It also makes exploits much easier to write. - - none Vsyscalls don't work at all. This makes - them quite hard to use for exploits but - might break your system. - - vt.color= [VT] Default text color. - Format: 0xYX, X = foreground, Y = background. - Default: 0x07 = light gray on black. - - vt.cur_default= [VT] Default cursor shape. - Format: 0xCCBBAA, where AA, BB, and CC are the same as - the parameters of the [?A;B;Cc escape sequence; - see VGA-softcursor.txt. Default: 2 = underline. - - vt.default_blu= [VT] - Format: ,,,..., - Change the default blue palette of the console. - This is a 16-member array composed of values - ranging from 0-255. - - vt.default_grn= [VT] - Format: ,,,..., - Change the default green palette of the console. - This is a 16-member array composed of values - ranging from 0-255. - - vt.default_red= [VT] - Format: ,,,..., - Change the default red palette of the console. - This is a 16-member array composed of values - ranging from 0-255. - - vt.default_utf8= - [VT] - Format=<0|1> - Set system-wide default UTF-8 mode for all tty's. - Default is 1, i.e. UTF-8 mode is enabled for all - newly opened terminals. - - vt.global_cursor_default= - [VT] - Format=<-1|0|1> - Set system-wide default for whether a cursor - is shown on new VTs. Default is -1, - i.e. cursors will be created by default unless - overridden by individual drivers. 0 will hide - cursors, 1 will display them. - - vt.italic= [VT] Default color for italic text; 0-15. - Default: 2 = green. - - vt.underline= [VT] Default color for underlined text; 0-15. - Default: 3 = cyan. - - watchdog timers [HW,WDT] For information on watchdog timers, - see Documentation/watchdog/watchdog-parameters.txt - or other driver-specific files in the - Documentation/watchdog/ directory. - - workqueue.watchdog_thresh= - If CONFIG_WQ_WATCHDOG is configured, workqueue can - warn stall conditions and dump internal state to - help debugging. 0 disables workqueue stall - detection; otherwise, it's the stall threshold - duration in seconds. The default value is 30 and - it can be updated at runtime by writing to the - corresponding sysfs file. - - workqueue.disable_numa - By default, all work items queued to unbound - workqueues are affine to the NUMA nodes they're - issued on, which results in better behavior in - general. If NUMA affinity needs to be disabled for - whatever reason, this option can be used. Note - that this also can be controlled per-workqueue for - workqueues visible under /sys/bus/workqueue/. - - workqueue.power_efficient - Per-cpu workqueues are generally preferred because - they show better performance thanks to cache - locality; unfortunately, per-cpu workqueues tend to - be more power hungry than unbound workqueues. - - Enabling this makes the per-cpu workqueues which - were observed to contribute significantly to power - consumption unbound, leading to measurably lower - power usage at the cost of small performance - overhead. - - The default value of this parameter is determined by - the config option CONFIG_WQ_POWER_EFFICIENT_DEFAULT. - - workqueue.debug_force_rr_cpu - Workqueue used to implicitly guarantee that work - items queued without explicit CPU specified are put - on the local CPU. This guarantee is no longer true - and while local CPU is still preferred work items - may be put on foreign CPUs. This debug option - forces round-robin CPU selection to flush out - usages which depend on the now broken guarantee. - When enabled, memory and cache locality will be - impacted. - - x2apic_phys [X86-64,APIC] Use x2apic physical mode instead of - default x2apic cluster mode on platforms - supporting x2apic. - - x86_intel_mid_timer= [X86-32,APBT] - Choose timer option for x86 Intel MID platform. - Two valid options are apbt timer only and lapic timer - plus one apbt timer for broadcast timer. - x86_intel_mid_timer=apbt_only | lapic_and_apbt - - xen_512gb_limit [KNL,X86-64,XEN] - Restricts the kernel running paravirtualized under Xen - to use only up to 512 GB of RAM. The reason to do so is - crash analysis tools and Xen tools for doing domain - save/restore/migration must be enabled to handle larger - domains. - - xen_emul_unplug= [HW,X86,XEN] - Unplug Xen emulated devices - Format: [unplug0,][unplug1] - ide-disks -- unplug primary master IDE devices - aux-ide-disks -- unplug non-primary-master IDE devices - nics -- unplug network devices - all -- unplug all emulated devices (NICs and IDE disks) - unnecessary -- unplugging emulated devices is - unnecessary even if the host did not respond to - the unplug protocol - never -- do not unplug even if version check succeeds - - xen_nopvspin [X86,XEN] - Disables the ticketlock slowpath using Xen PV - optimizations. - - xen_nopv [X86] - Disables the PV optimizations forcing the HVM guest to - run as generic HVM guest with no PV drivers. - - xirc2ps_cs= [NET,PCMCIA] - Format: - ,,,,,[,[,[,]]] - ------------------------- - -Todo ----- - - Add more DRM drivers. diff --git a/Documentation/md.txt b/Documentation/md.txt deleted file mode 100644 index e449fb5f277c..000000000000 --- a/Documentation/md.txt +++ /dev/null @@ -1,727 +0,0 @@ -RAID arrays -=========== - -Boot time assembly of RAID arrays ---------------------------------- - -Tools that manage md devices can be found at - http://www.kernel.org/pub/linux/utils/raid/ - - -You can boot with your md device with the following kernel command -lines: - -for old raid arrays without persistent superblocks:: - - md=,,,,dev0,dev1,...,devn - -for raid arrays with persistent superblocks:: - - md=,dev0,dev1,...,devn - -or, to assemble a partitionable array:: - - md=d,dev0,dev1,...,devn - -``md device no.`` -+++++++++++++++++ - -The number of the md device - -================= ========= -``md device no.`` device -================= ========= - 0 md0 - 1 md1 - 2 md2 - 3 md3 - 4 md4 -================= ========= - -``raid level`` -++++++++++++++ - -level of the RAID array - -=============== ============= -``raid level`` level -=============== ============= --1 linear mode -0 striped mode -=============== ============= - -other modes are only supported with persistent super blocks - -``chunk size factor`` -+++++++++++++++++++++ - -(raid-0 and raid-1 only) - -Set the chunk size as 4k << n. - -``fault level`` -+++++++++++++++ - -Totally ignored - -``dev0`` to ``devn`` -++++++++++++++++++++ - -e.g. ``/dev/hda1``, ``/dev/hdc1``, ``/dev/sda1``, ``/dev/sdb1`` - -A possible loadlin line (Harald Hoyer ) looks like this:: - - e:\loadlin\loadlin e:\zimage root=/dev/md0 md=0,0,4,0,/dev/hdb2,/dev/hdc3 ro - - -Boot time autodetection of RAID arrays --------------------------------------- - -When md is compiled into the kernel (not as module), partitions of -type 0xfd are scanned and automatically assembled into RAID arrays. -This autodetection may be suppressed with the kernel parameter -``raid=noautodetect``. As of kernel 2.6.9, only drives with a type 0 -superblock can be autodetected and run at boot time. - -The kernel parameter ``raid=partitionable`` (or ``raid=part``) means -that all auto-detected arrays are assembled as partitionable. - -Boot time assembly of degraded/dirty arrays -------------------------------------------- - -If a raid5 or raid6 array is both dirty and degraded, it could have -undetectable data corruption. This is because the fact that it is -``dirty`` means that the parity cannot be trusted, and the fact that it -is degraded means that some datablocks are missing and cannot reliably -be reconstructed (due to no parity). - -For this reason, md will normally refuse to start such an array. This -requires the sysadmin to take action to explicitly start the array -despite possible corruption. This is normally done with:: - - mdadm --assemble --force .... - -This option is not really available if the array has the root -filesystem on it. In order to support this booting from such an -array, md supports a module parameter ``start_dirty_degraded`` which, -when set to 1, bypassed the checks and will allows dirty degraded -arrays to be started. - -So, to boot with a root filesystem of a dirty degraded raid 5 or 6, use:: - - md-mod.start_dirty_degraded=1 - - -Superblock formats ------------------- - -The md driver can support a variety of different superblock formats. -Currently, it supports superblock formats ``0.90.0`` and the ``md-1`` format -introduced in the 2.5 development series. - -The kernel will autodetect which format superblock is being used. - -Superblock format ``0`` is treated differently to others for legacy -reasons - it is the original superblock format. - - -General Rules - apply for all superblock formats ------------------------------------------------- - -An array is ``created`` by writing appropriate superblocks to all -devices. - -It is ``assembled`` by associating each of these devices with an -particular md virtual device. Once it is completely assembled, it can -be accessed. - -An array should be created by a user-space tool. This will write -superblocks to all devices. It will usually mark the array as -``unclean``, or with some devices missing so that the kernel md driver -can create appropriate redundancy (copying in raid 1, parity -calculation in raid 4/5). - -When an array is assembled, it is first initialized with the -SET_ARRAY_INFO ioctl. This contains, in particular, a major and minor -version number. The major version number selects which superblock -format is to be used. The minor number might be used to tune handling -of the format, such as suggesting where on each device to look for the -superblock. - -Then each device is added using the ADD_NEW_DISK ioctl. This -provides, in particular, a major and minor number identifying the -device to add. - -The array is started with the RUN_ARRAY ioctl. - -Once started, new devices can be added. They should have an -appropriate superblock written to them, and then be passed in with -ADD_NEW_DISK. - -Devices that have failed or are not yet active can be detached from an -array using HOT_REMOVE_DISK. - - -Specific Rules that apply to format-0 super block arrays, and arrays with no superblock (non-persistent) --------------------------------------------------------------------------------------------------------- - -An array can be ``created`` by describing the array (level, chunksize -etc) in a SET_ARRAY_INFO ioctl. This must have ``major_version==0`` and -``raid_disks != 0``. - -Then uninitialized devices can be added with ADD_NEW_DISK. The -structure passed to ADD_NEW_DISK must specify the state of the device -and its role in the array. - -Once started with RUN_ARRAY, uninitialized spares can be added with -HOT_ADD_DISK. - - -MD devices in sysfs -------------------- - -md devices appear in sysfs (``/sys``) as regular block devices, -e.g.:: - - /sys/block/md0 - -Each ``md`` device will contain a subdirectory called ``md`` which -contains further md-specific information about the device. - -All md devices contain: - - level - a text file indicating the ``raid level``. e.g. raid0, raid1, - raid5, linear, multipath, faulty. - If no raid level has been set yet (array is still being - assembled), the value will reflect whatever has been written - to it, which may be a name like the above, or may be a number - such as ``0``, ``5``, etc. - - raid_disks - a text file with a simple number indicating the number of devices - in a fully functional array. If this is not yet known, the file - will be empty. If an array is being resized this will contain - the new number of devices. - Some raid levels allow this value to be set while the array is - active. This will reconfigure the array. Otherwise it can only - be set while assembling an array. - A change to this attribute will not be permitted if it would - reduce the size of the array. To reduce the number of drives - in an e.g. raid5, the array size must first be reduced by - setting the ``array_size`` attribute. - - chunk_size - This is the size in bytes for ``chunks`` and is only relevant to - raid levels that involve striping (0,4,5,6,10). The address space - of the array is conceptually divided into chunks and consecutive - chunks are striped onto neighbouring devices. - The size should be at least PAGE_SIZE (4k) and should be a power - of 2. This can only be set while assembling an array - - layout - The ``layout`` for the array for the particular level. This is - simply a number that is interpretted differently by different - levels. It can be written while assembling an array. - - array_size - This can be used to artificially constrain the available space in - the array to be less than is actually available on the combined - devices. Writing a number (in Kilobytes) which is less than - the available size will set the size. Any reconfiguration of the - array (e.g. adding devices) will not cause the size to change. - Writing the word ``default`` will cause the effective size of the - array to be whatever size is actually available based on - ``level``, ``chunk_size`` and ``component_size``. - - This can be used to reduce the size of the array before reducing - the number of devices in a raid4/5/6, or to support external - metadata formats which mandate such clipping. - - reshape_position - This is either ``none`` or a sector number within the devices of - the array where ``reshape`` is up to. If this is set, the three - attributes mentioned above (raid_disks, chunk_size, layout) can - potentially have 2 values, an old and a new value. If these - values differ, reading the attribute returns:: - - new (old) - - and writing will effect the ``new`` value, leaving the ``old`` - unchanged. - - component_size - For arrays with data redundancy (i.e. not raid0, linear, faulty, - multipath), all components must be the same size - or at least - there must a size that they all provide space for. This is a key - part or the geometry of the array. It is measured in sectors - and can be read from here. Writing to this value may resize - the array if the personality supports it (raid1, raid5, raid6), - and if the component drives are large enough. - - metadata_version - This indicates the format that is being used to record metadata - about the array. It can be 0.90 (traditional format), 1.0, 1.1, - 1.2 (newer format in varying locations) or ``none`` indicating that - the kernel isn't managing metadata at all. - Alternately it can be ``external:`` followed by a string which - is set by user-space. This indicates that metadata is managed - by a user-space program. Any device failure or other event that - requires a metadata update will cause array activity to be - suspended until the event is acknowledged. - - resync_start - The point at which resync should start. If no resync is needed, - this will be a very large number (or ``none`` since 2.6.30-rc1). At - array creation it will default to 0, though starting the array as - ``clean`` will set it much larger. - - new_dev - This file can be written but not read. The value written should - be a block device number as major:minor. e.g. 8:0 - This will cause that device to be attached to the array, if it is - available. It will then appear at md/dev-XXX (depending on the - name of the device) and further configuration is then possible. - - safe_mode_delay - When an md array has seen no write requests for a certain period - of time, it will be marked as ``clean``. When another write - request arrives, the array is marked as ``dirty`` before the write - commences. This is known as ``safe_mode``. - The ``certain period`` is controlled by this file which stores the - period as a number of seconds. The default is 200msec (0.200). - Writing a value of 0 disables safemode. - - array_state - This file contains a single word which describes the current - state of the array. In many cases, the state can be set by - writing the word for the desired state, however some states - cannot be explicitly set, and some transitions are not allowed. - - Select/poll works on this file. All changes except between - Active_idle and active (which can be frequent and are not - very interesting) are notified. active->active_idle is - reported if the metadata is externally managed. - - clear - No devices, no size, no level - - Writing is equivalent to STOP_ARRAY ioctl - - inactive - May have some settings, but array is not active - all IO results in error - - When written, doesn't tear down array, but just stops it - - suspended (not supported yet) - All IO requests will block. The array can be reconfigured. - - Writing this, if accepted, will block until array is quiessent - - readonly - no resync can happen. no superblocks get written. - - Write requests fail - - read-auto - like readonly, but behaves like ``clean`` on a write request. - - clean - no pending writes, but otherwise active. - - When written to inactive array, starts without resync - - If a write request arrives then - if metadata is known, mark ``dirty`` and switch to ``active``. - if not known, block and switch to write-pending - - If written to an active array that has pending writes, then fails. - active - fully active: IO and resync can be happening. - When written to inactive array, starts with resync - - write-pending - clean, but writes are blocked waiting for ``active`` to be written. - - active-idle - like active, but no writes have been seen for a while (safe_mode_delay). - - bitmap/location - This indicates where the write-intent bitmap for the array is - stored. - - It can be one of ``none``, ``file`` or ``[+-]N``. - ``file`` may later be extended to ``file:/file/name`` - ``[+-]N`` means that many sectors from the start of the metadata. - - This is replicated on all devices. For arrays with externally - managed metadata, the offset is from the beginning of the - device. - - bitmap/chunksize - The size, in bytes, of the chunk which will be represented by a - single bit. For RAID456, it is a portion of an individual - device. For RAID10, it is a portion of the array. For RAID1, it - is both (they come to the same thing). - - bitmap/time_base - The time, in seconds, between looking for bits in the bitmap to - be cleared. In the current implementation, a bit will be cleared - between 2 and 3 times ``time_base`` after all the covered blocks - are known to be in-sync. - - bitmap/backlog - When write-mostly devices are active in a RAID1, write requests - to those devices proceed in the background - the filesystem (or - other user of the device) does not have to wait for them. - ``backlog`` sets a limit on the number of concurrent background - writes. If there are more than this, new writes will by - synchronous. - - bitmap/metadata - This can be either ``internal`` or ``external``. - - ``internal`` - is the default and means the metadata for the bitmap - is stored in the first 256 bytes of the allocated space and is - managed by the md module. - - ``external`` - means that bitmap metadata is managed externally to - the kernel (i.e. by some userspace program) - - bitmap/can_clear - This is either ``true`` or ``false``. If ``true``, then bits in the - bitmap will be cleared when the corresponding blocks are thought - to be in-sync. If ``false``, bits will never be cleared. - This is automatically set to ``false`` if a write happens on a - degraded array, or if the array becomes degraded during a write. - When metadata is managed externally, it should be set to true - once the array becomes non-degraded, and this fact has been - recorded in the metadata. - - - - -As component devices are added to an md array, they appear in the ``md`` -directory as new directories named:: - - dev-XXX - -where ``XXX`` is a name that the kernel knows for the device, e.g. hdb1. -Each directory contains: - - block - a symlink to the block device in /sys/block, e.g.:: - - /sys/block/md0/md/dev-hdb1/block -> ../../../../block/hdb/hdb1 - - super - A file containing an image of the superblock read from, or - written to, that device. - - state - A file recording the current state of the device in the array - which can be a comma separated list of: - - faulty - device has been kicked from active use due to - a detected fault, or it has unacknowledged bad - blocks - - in_sync - device is a fully in-sync member of the array - - writemostly - device will only be subject to read - requests if there are no other options. - - This applies only to raid1 arrays. - - blocked - device has failed, and the failure hasn't been - acknowledged yet by the metadata handler. - - Writes that would write to this device if - it were not faulty are blocked. - - spare - device is working, but not a full member. - - This includes spares that are in the process - of being recovered to - - write_error - device has ever seen a write error. - - want_replacement - device is (mostly) working but probably - should be replaced, either due to errors or - due to user request. - - replacement - device is a replacement for another active - device with same raid_disk. - - - This list may grow in future. - - This can be written to. - - Writing ``faulty`` simulates a failure on the device. - - Writing ``remove`` removes the device from the array. - - Writing ``writemostly`` sets the writemostly flag. - - Writing ``-writemostly`` clears the writemostly flag. - - Writing ``blocked`` sets the ``blocked`` flag. - - Writing ``-blocked`` clears the ``blocked`` flags and allows writes - to complete and possibly simulates an error. - - Writing ``in_sync`` sets the in_sync flag. - - Writing ``write_error`` sets writeerrorseen flag. - - Writing ``-write_error`` clears writeerrorseen flag. - - Writing ``want_replacement`` is allowed at any time except to a - replacement device or a spare. It sets the flag. - - Writing ``-want_replacement`` is allowed at any time. It clears - the flag. - - Writing ``replacement`` or ``-replacement`` is only allowed before - starting the array. It sets or clears the flag. - - - This file responds to select/poll. Any change to ``faulty`` - or ``blocked`` causes an event. - - errors - An approximate count of read errors that have been detected on - this device but have not caused the device to be evicted from - the array (either because they were corrected or because they - happened while the array was read-only). When using version-1 - metadata, this value persists across restarts of the array. - - This value can be written while assembling an array thus - providing an ongoing count for arrays with metadata managed by - userspace. - - slot - This gives the role that the device has in the array. It will - either be ``none`` if the device is not active in the array - (i.e. is a spare or has failed) or an integer less than the - ``raid_disks`` number for the array indicating which position - it currently fills. This can only be set while assembling an - array. A device for which this is set is assumed to be working. - - offset - This gives the location in the device (in sectors from the - start) where data from the array will be stored. Any part of - the device before this offset is not touched, unless it is - used for storing metadata (Formats 1.1 and 1.2). - - size - The amount of the device, after the offset, that can be used - for storage of data. This will normally be the same as the - component_size. This can be written while assembling an - array. If a value less than the current component_size is - written, it will be rejected. - - recovery_start - When the device is not ``in_sync``, this records the number of - sectors from the start of the device which are known to be - correct. This is normally zero, but during a recovery - operation it will steadily increase, and if the recovery is - interrupted, restoring this value can cause recovery to - avoid repeating the earlier blocks. With v1.x metadata, this - value is saved and restored automatically. - - This can be set whenever the device is not an active member of - the array, either before the array is activated, or before - the ``slot`` is set. - - Setting this to ``none`` is equivalent to setting ``in_sync``. - Setting to any other value also clears the ``in_sync`` flag. - - bad_blocks - This gives the list of all known bad blocks in the form of - start address and length (in sectors respectively). If output - is too big to fit in a page, it will be truncated. Writing - ``sector length`` to this file adds new acknowledged (i.e. - recorded to disk safely) bad blocks. - - unacknowledged_bad_blocks - This gives the list of known-but-not-yet-saved-to-disk bad - blocks in the same form of ``bad_blocks``. If output is too big - to fit in a page, it will be truncated. Writing to this file - adds bad blocks without acknowledging them. This is largely - for testing. - - - -An active md device will also contain an entry for each active device -in the array. These are named:: - - rdNN - -where ``NN`` is the position in the array, starting from 0. -So for a 3 drive array there will be rd0, rd1, rd2. -These are symbolic links to the appropriate ``dev-XXX`` entry. -Thus, for example:: - - cat /sys/block/md*/md/rd*/state - -will show ``in_sync`` on every line. - - - -Active md devices for levels that support data redundancy (1,4,5,6,10) -also have - - sync_action - a text file that can be used to monitor and control the rebuild - process. It contains one word which can be one of: - - resync - redundancy is being recalculated after unclean - shutdown or creation - - recover - a hot spare is being built to replace a - failed/missing device - - idle - nothing is happening - check - A full check of redundancy was requested and is - happening. This reads all blocks and checks - them. A repair may also happen for some raid - levels. - - repair - A full check and repair is happening. This is - similar to ``resync``, but was requested by the - user, and the write-intent bitmap is NOT used to - optimise the process. - - This file is writable, and each of the strings that could be - read are meaningful for writing. - - ``idle`` will stop an active resync/recovery etc. There is no - guarantee that another resync/recovery may not be automatically - started again, though some event will be needed to trigger - this. - - ``resync`` or ``recovery`` can be used to restart the - corresponding operation if it was stopped with ``idle``. - - ``check`` and ``repair`` will start the appropriate process - providing the current state is ``idle``. - - This file responds to select/poll. Any important change in the value - triggers a poll event. Sometimes the value will briefly be - ``recover`` if a recovery seems to be needed, but cannot be - achieved. In that case, the transition to ``recover`` isn't - notified, but the transition away is. - - degraded - This contains a count of the number of devices by which the - arrays is degraded. So an optimal array will show ``0``. A - single failed/missing drive will show ``1``, etc. - - This file responds to select/poll, any increase or decrease - in the count of missing devices will trigger an event. - - mismatch_count - When performing ``check`` and ``repair``, and possibly when - performing ``resync``, md will count the number of errors that are - found. The count in ``mismatch_cnt`` is the number of sectors - that were re-written, or (for ``check``) would have been - re-written. As most raid levels work in units of pages rather - than sectors, this may be larger than the number of actual errors - by a factor of the number of sectors in a page. - - bitmap_set_bits - If the array has a write-intent bitmap, then writing to this - attribute can set bits in the bitmap, indicating that a resync - would need to check the corresponding blocks. Either individual - numbers or start-end pairs can be written. Multiple numbers - can be separated by a space. - - Note that the numbers are ``bit`` numbers, not ``block`` numbers. - They should be scaled by the bitmap_chunksize. - - sync_speed_min, sync_speed_max - This are similar to ``/proc/sys/dev/raid/speed_limit_{min,max}`` - however they only apply to the particular array. - - If no value has been written to these, or if the word ``system`` - is written, then the system-wide value is used. If a value, - in kibibytes-per-second is written, then it is used. - - When the files are read, they show the currently active value - followed by ``(local)`` or ``(system)`` depending on whether it is - a locally set or system-wide value. - - sync_completed - This shows the number of sectors that have been completed of - whatever the current sync_action is, followed by the number of - sectors in total that could need to be processed. The two - numbers are separated by a ``/`` thus effectively showing one - value, a fraction of the process that is complete. - - A ``select`` on this attribute will return when resync completes, - when it reaches the current sync_max (below) and possibly at - other times. - - sync_speed - This shows the current actual speed, in K/sec, of the current - sync_action. It is averaged over the last 30 seconds. - - suspend_lo, suspend_hi - The two values, given as numbers of sectors, indicate a range - within the array where IO will be blocked. This is currently - only supported for raid4/5/6. - - sync_min, sync_max - The two values, given as numbers of sectors, indicate a range - within the array where ``check``/``repair`` will operate. Must be - a multiple of chunk_size. When it reaches ``sync_max`` it will - pause, rather than complete. - You can use ``select`` or ``poll`` on ``sync_completed`` to wait for - that number to reach sync_max. Then you can either increase - ``sync_max``, or can write ``idle`` to ``sync_action``. - - The value of ``max`` for ``sync_max`` effectively disables the limit. - When a resync is active, the value can only ever be increased, - never decreased. - The value of ``0`` is the minimum for ``sync_min``. - - - -Each active md device may also have attributes specific to the -personality module that manages it. -These are specific to the implementation of the module and could -change substantially if the implementation changes. - -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, 17). Default is 256. - - strip_cache_active (currently raid5 only) - number of active entries in the stripe cache - - preread_bypass_threshold (currently raid5 only) - number of times a stripe requiring preread will be bypassed by - a stripe that does not require preread. For fairness defaults - to 1. Setting this to 0 disables bypass accounting and - requires preread stripes to wait until all full-width stripe- - writes are complete. Valid values are 0 to stripe_cache_size. diff --git a/Documentation/mono.txt b/Documentation/mono.txt deleted file mode 100644 index 9a9744ca0cf3..000000000000 --- a/Documentation/mono.txt +++ /dev/null @@ -1,68 +0,0 @@ -Mono(tm) Binary Kernel Support for Linux ------------------------------------------ - -To configure Linux to automatically execute Mono-based .NET binaries -(in the form of .exe files) without the need to use the mono CLR -wrapper, you can use the BINFMT_MISC kernel support. - -This will allow you to execute Mono-based .NET binaries just like any -other program after you have done the following: - -1) You MUST FIRST install the Mono CLR support, either by downloading - a binary package, a source tarball or by installing from CVS. Binary - packages for several distributions can be found at: - - http://go-mono.com/download.html - - Instructions for compiling Mono can be found at: - - http://www.go-mono.com/compiling.html - - Once the Mono CLR support has been installed, just check that - ``/usr/bin/mono`` (which could be located elsewhere, for example - ``/usr/local/bin/mono``) is working. - -2) You have to compile BINFMT_MISC either as a module or into - the kernel (``CONFIG_BINFMT_MISC``) and set it up properly. - If you choose to compile it as a module, you will have - to insert it manually with modprobe/insmod, as kmod - cannot be easily supported with binfmt_misc. - Read the file ``binfmt_misc.txt`` in this directory to know - more about the configuration process. - -3) Add the following entries to ``/etc/rc.local`` or similar script - to be run at system startup:: - - # Insert BINFMT_MISC module into the kernel - if [ ! -e /proc/sys/fs/binfmt_misc/register ]; then - /sbin/modprobe binfmt_misc - # Some distributions, like Fedora Core, perform - # the following command automatically when the - # binfmt_misc module is loaded into the kernel - # or during normal boot up (systemd-based systems). - # Thus, it is possible that the following line - # is not needed at all. - mount -t binfmt_misc none /proc/sys/fs/binfmt_misc - fi - - # Register support for .NET CLR binaries - if [ -e /proc/sys/fs/binfmt_misc/register ]; then - # Replace /usr/bin/mono with the correct pathname to - # the Mono CLR runtime (usually /usr/local/bin/mono - # when compiling from sources or CVS). - echo ':CLR:M::MZ::/usr/bin/mono:' > /proc/sys/fs/binfmt_misc/register - else - echo "No binfmt_misc support" - exit 1 - fi - -4) Check that ``.exe`` binaries can be ran without the need of a - wrapper script, simply by launching the ``.exe`` file directly - from a command prompt, for example:: - - /usr/bin/xsd.exe - - .. note:: - - If this fails with a permission denied error, check - that the ``.exe`` file has execute permissions. diff --git a/Documentation/oops-tracing.txt b/Documentation/oops-tracing.txt deleted file mode 100644 index 3e25ea7349ee..000000000000 --- a/Documentation/oops-tracing.txt +++ /dev/null @@ -1,300 +0,0 @@ -OOPS tracing -============ - -.. note:: - - ``ksymoops`` is useless on 2.6 or upper. Please use the Oops in its original - format (from ``dmesg``, etc). Ignore any references in this or other docs to - "decoding the Oops" or "running it through ksymoops". - If you post an Oops from 2.6+ that has been run through ``ksymoops``, - people will just tell you to repost it. - -Quick Summary -------------- - -Find the Oops and send it to the maintainer of the kernel area that seems to be -involved with the problem. Don't worry too much about getting the wrong person. -If you are unsure send it to the person responsible for the code relevant to -what you were doing. If it occurs repeatably try and describe how to recreate -it. That's worth even more than the oops. - -If you are totally stumped as to whom to send the report, send it to -linux-kernel@vger.kernel.org. Thanks for your help in making Linux as -stable as humanly possible. - -Where is the Oops? ----------------------- - -Normally the Oops text is read from the kernel buffers by klogd and -handed to ``syslogd`` which writes it to a syslog file, typically -``/var/log/messages`` (depends on ``/etc/syslog.conf``). Sometimes ``klogd`` -dies, in which case you can run ``dmesg > file`` to read the data from the -kernel buffers and save it. Or you can ``cat /proc/kmsg > file``, however you -have to break in to stop the transfer, ``kmsg`` is a "never ending file". -If the machine has crashed so badly that you cannot enter commands or -the disk is not available then you have three options : - -(1) Hand copy the text from the screen and type it in after the machine - has restarted. Messy but it is the only option if you have not - planned for a crash. Alternatively, you can take a picture of - the screen with a digital camera - not nice, but better than - nothing. If the messages scroll off the top of the console, you - may find that booting with a higher resolution (eg, ``vga=791``) - will allow you to read more of the text. (Caveat: This needs ``vesafb``, - so won't help for 'early' oopses) - -(2) Boot with a serial console (see - :ref:`Documentation/serial-console.txt `), - run a null modem to a second machine and capture the output there - using your favourite communication program. Minicom works well. - -(3) Use Kdump (see Documentation/kdump/kdump.txt), - extract the kernel ring buffer from old memory with using dmesg - gdbmacro in Documentation/kdump/gdbmacros.txt. - - -Full Information ----------------- - -.. note:: - - the message from Linus below applies to 2.4 kernel. I have preserved it - for historical reasons, and because some of the information in it still - applies. Especially, please ignore any references to ksymoops. - - :: - - From: Linus Torvalds - - How to track down an Oops.. [originally a mail to linux-kernel] - - The main trick is having 5 years of experience with those pesky oops - messages ;-) - -Actually, there are things you can do that make this easier. I have two -separate approaches:: - - gdb /usr/src/linux/vmlinux - gdb> disassemble - -That's the easy way to find the problem, at least if the bug-report is -well made (like this one was - run through ``ksymoops`` to get the -information of which function and the offset in the function that it -happened in). - -Oh, it helps if the report happens on a kernel that is compiled with the -same compiler and similar setups. - -The other thing to do is disassemble the "Code:" part of the bug report: -ksymoops will do this too with the correct tools, but if you don't have -the tools you can just do a silly program:: - - char str[] = "\xXX\xXX\xXX..."; - main(){} - -and compile it with ``gcc -g`` and then do ``disassemble str`` (where the ``XX`` -stuff are the values reported by the Oops - you can just cut-and-paste -and do a replace of spaces to ``\x`` - that's what I do, as I'm too lazy -to write a program to automate this all). - -Alternatively, you can use the shell script in ``scripts/decodecode``. -Its usage is:: - - decodecode < oops.txt - -The hex bytes that follow "Code:" may (in some architectures) have a series -of bytes that precede the current instruction pointer as well as bytes at and -following the current instruction pointer. In some cases, one instruction -byte or word is surrounded by ``<>`` or ``()``, as in ``<86>`` or ``(f00d)``. -These ``<>`` or ``()`` markings indicate the current instruction pointer. - -Example from i386, split into multiple lines for readability:: - - Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1 - 64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54 - 7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0 - -Finally, if you want to see where the code comes from, you can do:: - - cd /usr/src/linux - make fs/buffer.s # or whatever file the bug happened in - -and then you get a better idea of what happens than with the gdb -disassembly. - -Now, the trick is just then to combine all the data you have: the C -sources (and general knowledge of what it **should** do), the assembly -listing and the code disassembly (and additionally the register dump you -also get from the "oops" message - that can be useful to see **what** the -corrupted pointers were, and when you have the assembler listing you can -also match the other registers to whatever C expressions they were used -for). - -Essentially, you just look at what doesn't match (in this case it was the -"Code" disassembly that didn't match with what the compiler generated). -Then you need to find out **why** they don't match. Often it's simple - you -see that the code uses a NULL pointer and then you look at the code and -wonder how the NULL pointer got there, and if it's a valid thing to do -you just check against it.. - -Now, if somebody gets the idea that this is time-consuming and requires -some small amount of concentration, you're right. Which is why I will -mostly just ignore any panic reports that don't have the symbol table -info etc looked up: it simply gets too hard to look it up (I have some -programs to search for specific patterns in the kernel code segment, and -sometimes I have been able to look up those kinds of panics too, but -that really requires pretty good knowledge of the kernel just to be able -to pick out the right sequences etc..) - -**Sometimes** it happens that I just see the disassembled code sequence -from the panic, and I know immediately where it's coming from. That's when -I get worried that I've been doing this for too long ;-) - - Linus - - ---------------------------------------------------------------------------- - -Notes on Oops tracing with ``klogd`` ------------------------------------- - -In order to help Linus and the other kernel developers there has been -substantial support incorporated into ``klogd`` for processing protection -faults. In order to have full support for address resolution at least -version 1.3-pl3 of the ``sysklogd`` package should be used. - -When a protection fault occurs the ``klogd`` daemon automatically -translates important addresses in the kernel log messages to their -symbolic equivalents. This translated kernel message is then -forwarded through whatever reporting mechanism ``klogd`` is using. The -protection fault message can be simply cut out of the message files -and forwarded to the kernel developers. - -Two types of address resolution are performed by ``klogd``. The first is -static translation and the second is dynamic translation. Static -translation uses the System.map file in much the same manner that -ksymoops does. In order to do static translation the ``klogd`` daemon -must be able to find a system map file at daemon initialization time. -See the klogd man page for information on how ``klogd`` searches for map -files. - -Dynamic address translation is important when kernel loadable modules -are being used. Since memory for kernel modules is allocated from the -kernel's dynamic memory pools there are no fixed locations for either -the start of the module or for functions and symbols in the module. - -The kernel supports system calls which allow a program to determine -which modules are loaded and their location in memory. Using these -system calls the klogd daemon builds a symbol table which can be used -to debug a protection fault which occurs in a loadable kernel module. - -At the very minimum klogd will provide the name of the module which -generated the protection fault. There may be additional symbolic -information available if the developer of the loadable module chose to -export symbol information from the module. - -Since the kernel module environment can be dynamic there must be a -mechanism for notifying the ``klogd`` daemon when a change in module -environment occurs. There are command line options available which -allow klogd to signal the currently executing daemon that symbol -information should be refreshed. See the ``klogd`` manual page for more -information. - -A patch is included with the sysklogd distribution which modifies the -``modules-2.0.0`` package to automatically signal klogd whenever a module -is loaded or unloaded. Applying this patch provides essentially -seamless support for debugging protection faults which occur with -kernel loadable modules. - -The following is an example of a protection fault in a loadable module -processed by ``klogd``:: - - Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc - Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 - Aug 29 09:51:01 blizard kernel: *pde = 00000000 - Aug 29 09:51:01 blizard kernel: Oops: 0002 - Aug 29 09:51:01 blizard kernel: CPU: 0 - Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] - Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 - Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c - Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c - Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 - Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) - Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 - Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 - Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 - Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] - Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 - ---------------------------------------------------------------------------- - -:: - - Dr. G.W. Wettstein Oncology Research Div. Computing Facility - Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com - 820 4th St. N. - Fargo, ND 58122 - Phone: 701-234-7556 - - ---------------------------------------------------------------------------- - -Tainted kernels ---------------- - -Some oops reports contain the string **'Tainted: '** after the program -counter. This indicates that the kernel has been tainted by some -mechanism. The string is followed by a series of position-sensitive -characters, each representing a particular tainted value. - - 1) 'G' if all modules loaded have a GPL or compatible license, 'P' if - any proprietary module has been loaded. Modules without a - MODULE_LICENSE or with a MODULE_LICENSE that is not recognised by - insmod as GPL compatible are assumed to be proprietary. - - 2) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all - modules were loaded normally. - - 3) ``S`` if the oops occurred on an SMP kernel running on hardware that - hasn't been certified as safe to run multiprocessor. - Currently this occurs only on various Athlons that are not - SMP capable. - - 4) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all - modules were unloaded normally. - - 5) ``M`` if any processor has reported a Machine Check Exception, - ``' '`` if no Machine Check Exceptions have occurred. - - 6) ``B`` if a page-release function has found a bad page reference or - some unexpected page flags. - - 7) ``U`` if a user or user application specifically requested that the - Tainted flag be set, ``' '`` otherwise. - - 8) ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG. - - 9) ``A`` if the ACPI table has been overridden. - - 10) ``W`` if a warning has previously been issued by the kernel. - (Though some warnings may set more specific taint flags.) - - 11) ``C`` if a staging driver has been loaded. - - 12) ``I`` if the kernel is working around a severe bug in the platform - firmware (BIOS or similar). - - 13) ``O`` if an externally-built ("out-of-tree") module has been loaded. - - 14) ``E`` if an unsigned module has been loaded in a kernel supporting - module signature. - - 15) ``L`` if a soft lockup has previously occurred on the system. - - 16) ``K`` if the kernel has been live patched. - -The primary reason for the **'Tainted: '** string is to tell kernel -debuggers if this is a clean kernel or if anything unusual has -occurred. Tainting is permanent: even if an offending module is -unloaded, the tainted value remains to indicate that the kernel is not -trustworthy. diff --git a/Documentation/parport.txt b/Documentation/parport.txt deleted file mode 100644 index ad3f9b8a11e1..000000000000 --- a/Documentation/parport.txt +++ /dev/null @@ -1,286 +0,0 @@ -Parport -+++++++ - -The ``parport`` code provides parallel-port support under Linux. This -includes the ability to share one port between multiple device -drivers. - -You can pass parameters to the ``parport`` code to override its automatic -detection of your hardware. This is particularly useful if you want -to use IRQs, since in general these can't be autoprobed successfully. -By default IRQs are not used even if they **can** be probed. This is -because there are a lot of people using the same IRQ for their -parallel port and a sound card or network card. - -The ``parport`` code is split into two parts: generic (which deals with -port-sharing) and architecture-dependent (which deals with actually -using the port). - - -Parport as modules -================== - -If you load the `parport`` code as a module, say:: - - # insmod parport - -to load the generic ``parport`` code. You then must load the -architecture-dependent code with (for example):: - - # insmod parport_pc io=0x3bc,0x378,0x278 irq=none,7,auto - -to tell the ``parport`` code that you want three PC-style ports, one at -0x3bc with no IRQ, one at 0x378 using IRQ 7, and one at 0x278 with an -auto-detected IRQ. Currently, PC-style (``parport_pc``), Sun ``bpp``, -Amiga, Atari, and MFC3 hardware is supported. - -PCI parallel I/O card support comes from ``parport_pc``. Base I/O -addresses should not be specified for supported PCI cards since they -are automatically detected. - - -modprobe --------- - -If you use modprobe , you will find it useful to add lines as below to a -configuration file in /etc/modprobe.d/ directory:: - - alias parport_lowlevel parport_pc - options parport_pc io=0x378,0x278 irq=7,auto - -modprobe will load ``parport_pc`` (with the options ``io=0x378,0x278 irq=7,auto``) -whenever a parallel port device driver (such as ``lp``) is loaded. - -Note that these are example lines only! You shouldn't in general need -to specify any options to ``parport_pc`` in order to be able to use a -parallel port. - - -Parport probe [optional] ------------------------- - -In 2.2 kernels there was a module called ``parport_probe``, which was used -for collecting IEEE 1284 device ID information. This has now been -enhanced and now lives with the IEEE 1284 support. When a parallel -port is detected, the devices that are connected to it are analysed, -and information is logged like this:: - - parport0: Printer, BJC-210 (Canon) - -The probe information is available from files in ``/proc/sys/dev/parport/``. - - -Parport linked into the kernel statically -========================================= - -If you compile the ``parport`` code into the kernel, then you can use -kernel boot parameters to get the same effect. Add something like the -following to your LILO command line:: - - parport=0x3bc parport=0x378,7 parport=0x278,auto,nofifo - -You can have many ``parport=...`` statements, one for each port you want -to add. Adding ``parport=0`` to the kernel command-line will disable -parport support entirely. Adding ``parport=auto`` to the kernel -command-line will make ``parport`` use any IRQ lines or DMA channels that -it auto-detects. - - -Files in /proc -============== - -If you have configured the ``/proc`` filesystem into your kernel, you will -see a new directory entry: ``/proc/sys/dev/parport``. In there will be a -directory entry for each parallel port for which parport is -configured. In each of those directories are a collection of files -describing that parallel port. - -The ``/proc/sys/dev/parport`` directory tree looks like:: - - parport - |-- default - | |-- spintime - | `-- timeslice - |-- parport0 - | |-- autoprobe - | |-- autoprobe0 - | |-- autoprobe1 - | |-- autoprobe2 - | |-- autoprobe3 - | |-- devices - | | |-- active - | | `-- lp - | | `-- timeslice - | |-- base-addr - | |-- irq - | |-- dma - | |-- modes - | `-- spintime - `-- parport1 - |-- autoprobe - |-- autoprobe0 - |-- autoprobe1 - |-- autoprobe2 - |-- autoprobe3 - |-- devices - | |-- active - | `-- ppa - | `-- timeslice - |-- base-addr - |-- irq - |-- dma - |-- modes - `-- spintime - -.. tabularcolumns:: |p{4.0cm}|p{13.5cm}| - -======================= ======================================================= -File Contents -======================= ======================================================= -``devices/active`` A list of the device drivers using that port. A "+" - will appear by the name of the device currently using - the port (it might not appear against any). The - string "none" means that there are no device drivers - using that port. - -``base-addr`` Parallel port's base address, or addresses if the port - has more than one in which case they are separated - with tabs. These values might not have any sensible - meaning for some ports. - -``irq`` Parallel port's IRQ, or -1 if none is being used. - -``dma`` Parallel port's DMA channel, or -1 if none is being - used. - -``modes`` Parallel port's hardware modes, comma-separated, - meaning: - - - PCSPP - PC-style SPP registers are available. - - - TRISTATE - Port is bidirectional. - - - COMPAT - Hardware acceleration for printers is - available and will be used. - - - EPP - Hardware acceleration for EPP protocol - is available and will be used. - - - ECP - Hardware acceleration for ECP protocol - is available and will be used. - - - DMA - DMA is available and will be used. - - Note that the current implementation will only take - advantage of COMPAT and ECP modes if it has an IRQ - line to use. - -``autoprobe`` Any IEEE-1284 device ID information that has been - acquired from the (non-IEEE 1284.3) device. - -``autoprobe[0-3]`` IEEE 1284 device ID information retrieved from - daisy-chain devices that conform to IEEE 1284.3. - -``spintime`` The number of microseconds to busy-loop while waiting - for the peripheral to respond. You might find that - adjusting this improves performance, depending on your - peripherals. This is a port-wide setting, i.e. it - applies to all devices on a particular port. - -``timeslice`` The number of milliseconds that a device driver is - allowed to keep a port claimed for. This is advisory, - and driver can ignore it if it must. - -``default/*`` The defaults for spintime and timeslice. When a new - port is registered, it picks up the default spintime. - When a new device is registered, it picks up the - default timeslice. -======================= ======================================================= - -Device drivers -============== - -Once the parport code is initialised, you can attach device drivers to -specific ports. Normally this happens automatically; if the lp driver -is loaded it will create one lp device for each port found. You can -override this, though, by using parameters either when you load the lp -driver:: - - # insmod lp parport=0,2 - -or on the LILO command line:: - - lp=parport0 lp=parport2 - -Both the above examples would inform lp that you want ``/dev/lp0`` to be -the first parallel port, and /dev/lp1 to be the **third** parallel port, -with no lp device associated with the second port (parport1). Note -that this is different to the way older kernels worked; there used to -be a static association between the I/O port address and the device -name, so ``/dev/lp0`` was always the port at 0x3bc. This is no longer the -case - if you only have one port, it will default to being ``/dev/lp0``, -regardless of base address. - -Also: - - * If you selected the IEEE 1284 support at compile time, you can say - ``lp=auto`` on the kernel command line, and lp will create devices - only for those ports that seem to have printers attached. - - * If you give PLIP the ``timid`` parameter, either with ``plip=timid`` on - the command line, or with ``insmod plip timid=1`` when using modules, - it will avoid any ports that seem to be in use by other devices. - - * IRQ autoprobing works only for a few port types at the moment. - -Reporting printer problems with parport -======================================= - -If you are having problems printing, please go through these steps to -try to narrow down where the problem area is. - -When reporting problems with parport, really you need to give all of -the messages that ``parport_pc`` spits out when it initialises. There are -several code paths: - -- polling -- interrupt-driven, protocol in software -- interrupt-driven, protocol in hardware using PIO -- interrupt-driven, protocol in hardware using DMA - -The kernel messages that ``parport_pc`` logs give an indication of which -code path is being used. (They could be a lot better actually..) - -For normal printer protocol, having IEEE 1284 modes enabled or not -should not make a difference. - -To turn off the 'protocol in hardware' code paths, disable -``CONFIG_PARPORT_PC_FIFO``. Note that when they are enabled they are not -necessarily **used**; it depends on whether the hardware is available, -enabled by the BIOS, and detected by the driver. - -So, to start with, disable ``CONFIG_PARPORT_PC_FIFO``, and load ``parport_pc`` -with ``irq=none``. See if printing works then. It really should, -because this is the simplest code path. - -If that works fine, try with ``io=0x378 irq=7`` (adjust for your -hardware), to make it use interrupt-driven in-software protocol. - -If **that** works fine, then one of the hardware modes isn't working -right. Enable ``CONFIG_FIFO`` (no, it isn't a module option, -and yes, it should be), set the port to ECP mode in the BIOS and note -the DMA channel, and try with:: - - io=0x378 irq=7 dma=none (for PIO) - io=0x378 irq=7 dma=3 (for DMA) - ----------- - -philb@gnu.org -tim@cyberelk.net diff --git a/Documentation/ramoops.txt b/Documentation/ramoops.txt deleted file mode 100644 index 7eaf1e71c083..000000000000 --- a/Documentation/ramoops.txt +++ /dev/null @@ -1,154 +0,0 @@ -Ramoops oops/panic logger -========================= - -Sergiu Iordache - -Updated: 17 November 2011 - -Introduction ------------- - -Ramoops is an oops/panic logger that writes its logs to RAM before the system -crashes. It works by logging oopses and panics in a circular buffer. Ramoops -needs a system with persistent RAM so that the content of that area can -survive after a restart. - -Ramoops concepts ----------------- - -Ramoops uses a predefined memory area to store the dump. The start and size -and type of the memory area are set using three variables: - - * ``mem_address`` for the start - * ``mem_size`` for the size. The memory size will be rounded down to a - power of two. - * ``mem_type`` to specifiy if the memory type (default is pgprot_writecombine). - -Typically the default value of ``mem_type=0`` should be used as that sets the pstore -mapping to pgprot_writecombine. Setting ``mem_type=1`` attempts to use -``pgprot_noncached``, which only works on some platforms. This is because pstore -depends on atomic operations. At least on ARM, pgprot_noncached causes the -memory to be mapped strongly ordered, and atomic operations on strongly ordered -memory are implementation defined, and won't work on many ARMs such as omaps. - -The memory area is divided into ``record_size`` chunks (also rounded down to -power of two) and each oops/panic writes a ``record_size`` chunk of -information. - -Dumping both oopses and panics can be done by setting 1 in the ``dump_oops`` -variable while setting 0 in that variable dumps only the panics. - -The module uses a counter to record multiple dumps but the counter gets reset -on restart (i.e. new dumps after the restart will overwrite old ones). - -Ramoops also supports software ECC protection of persistent memory regions. -This might be useful when a hardware reset was used to bring the machine back -to life (i.e. a watchdog triggered). In such cases, RAM may be somewhat -corrupt, but usually it is restorable. - -Setting the parameters ----------------------- - -Setting the ramoops parameters can be done in several different manners: - - A. Use the module parameters (which have the names of the variables described - as before). For quick debugging, you can also reserve parts of memory during - boot and then use the reserved memory for ramoops. For example, assuming a - machine with > 128 MB of memory, the following kernel command line will tell - the kernel to use only the first 128 MB of memory, and place ECC-protected - ramoops region at 128 MB boundary:: - - mem=128M ramoops.mem_address=0x8000000 ramoops.ecc=1 - - B. Use Device Tree bindings, as described in - ``Documentation/device-tree/bindings/reserved-memory/ramoops.txt``. - For example:: - - reserved-memory { - #address-cells = <2>; - #size-cells = <2>; - ranges; - - ramoops@8f000000 { - compatible = "ramoops"; - reg = <0 0x8f000000 0 0x100000>; - record-size = <0x4000>; - console-size = <0x4000>; - }; - }; - - C. Use a platform device and set the platform data. The parameters can then - be set through that platform data. An example of doing that is:: - - #include - [...] - - static struct ramoops_platform_data ramoops_data = { - .mem_size = <...>, - .mem_address = <...>, - .mem_type = <...>, - .record_size = <...>, - .dump_oops = <...>, - .ecc = <...>, - }; - - static struct platform_device ramoops_dev = { - .name = "ramoops", - .dev = { - .platform_data = &ramoops_data, - }, - }; - - [... inside a function ...] - int ret; - - ret = platform_device_register(&ramoops_dev); - if (ret) { - printk(KERN_ERR "unable to register platform device\n"); - return ret; - } - -You can specify either RAM memory or peripheral devices' memory. However, when -specifying RAM, be sure to reserve the memory by issuing memblock_reserve() -very early in the architecture code, e.g.:: - - #include - - memblock_reserve(ramoops_data.mem_address, ramoops_data.mem_size); - -Dump format ------------ - -The data dump begins with a header, currently defined as ``====`` followed by a -timestamp and a new line. The dump then continues with the actual data. - -Reading the data ----------------- - -The dump data can be read from the pstore filesystem. The format for these -files is ``dmesg-ramoops-N``, where N is the record number in memory. To delete -a stored record from RAM, simply unlink the respective pstore file. - -Persistent function tracing ---------------------------- - -Persistent function tracing might be useful for debugging software or hardware -related hangs. The functions call chain log is stored in a ``ftrace-ramoops`` -file. Here is an example of usage:: - - # mount -t debugfs debugfs /sys/kernel/debug/ - # echo 1 > /sys/kernel/debug/pstore/record_ftrace - # reboot -f - [...] - # mount -t pstore pstore /mnt/ - # tail /mnt/ftrace-ramoops - 0 ffffffff8101ea64 ffffffff8101bcda native_apic_mem_read <- disconnect_bsp_APIC+0x6a/0xc0 - 0 ffffffff8101ea44 ffffffff8101bcf6 native_apic_mem_write <- disconnect_bsp_APIC+0x86/0xc0 - 0 ffffffff81020084 ffffffff8101a4b5 hpet_disable <- native_machine_shutdown+0x75/0x90 - 0 ffffffff81005f94 ffffffff8101a4bb iommu_shutdown_noop <- native_machine_shutdown+0x7b/0x90 - 0 ffffffff8101a6a1 ffffffff8101a437 native_machine_emergency_restart <- native_machine_restart+0x37/0x40 - 0 ffffffff811f9876 ffffffff8101a73a acpi_reboot <- native_machine_emergency_restart+0xaa/0x1e0 - 0 ffffffff8101a514 ffffffff8101a772 mach_reboot_fixups <- native_machine_emergency_restart+0xe2/0x1e0 - 0 ffffffff811d9c54 ffffffff8101a7a0 __const_udelay <- native_machine_emergency_restart+0x110/0x1e0 - 0 ffffffff811d9c34 ffffffff811d9c80 __delay <- __const_udelay+0x30/0x40 - 0 ffffffff811d9d14 ffffffff811d9c3f delay_tsc <- __delay+0xf/0x20 diff --git a/Documentation/serial-console.txt b/Documentation/serial-console.txt deleted file mode 100644 index a8d1e36b627a..000000000000 --- a/Documentation/serial-console.txt +++ /dev/null @@ -1,115 +0,0 @@ -.. _serial_console: - -Linux Serial Console -==================== - -To use a serial port as console you need to compile the support into your -kernel - by default it is not compiled in. For PC style serial ports -it's the config option next to menu option: - -:menuselection:`Character devices --> Serial drivers --> 8250/16550 and compatible serial support --> Console on 8250/16550 and compatible serial port` - -You must compile serial support into the kernel and not as a module. - -It is possible to specify multiple devices for console output. You can -define a new kernel command line option to select which device(s) to -use for console output. - -The format of this option is:: - - console=device,options - - device: tty0 for the foreground virtual console - ttyX for any other virtual console - ttySx for a serial port - lp0 for the first parallel port - ttyUSB0 for the first USB serial device - - options: depend on the driver. For the serial port this - defines the baudrate/parity/bits/flow control of - the port, in the format BBBBPNF, where BBBB is the - speed, P is parity (n/o/e), N is number of bits, - and F is flow control ('r' for RTS). Default is - 9600n8. The maximum baudrate is 115200. - -You can specify multiple console= options on the kernel command line. -Output will appear on all of them. The last device will be used when -you open ``/dev/console``. So, for example:: - - console=ttyS1,9600 console=tty0 - -defines that opening ``/dev/console`` will get you the current foreground -virtual console, and kernel messages will appear on both the VGA -console and the 2nd serial port (ttyS1 or COM2) at 9600 baud. - -Note that you can only define one console per device type (serial, video). - -If no console device is specified, the first device found capable of -acting as a system console will be used. At this time, the system -first looks for a VGA card and then for a serial port. So if you don't -have a VGA card in your system the first serial port will automatically -become the console. - -You will need to create a new device to use ``/dev/console``. The official -``/dev/console`` is now character device 5,1. - -(You can also use a network device as a console. See -``Documentation/networking/netconsole.txt`` for information on that.) - -Here's an example that will use ``/dev/ttyS1`` (COM2) as the console. -Replace the sample values as needed. - -1. Create ``/dev/console`` (real console) and ``/dev/tty0`` (master virtual - console):: - - cd /dev - rm -f console tty0 - mknod -m 622 console c 5 1 - mknod -m 622 tty0 c 4 0 - -2. LILO can also take input from a serial device. This is a very - useful option. To tell LILO to use the serial port: - In lilo.conf (global section):: - - serial = 1,9600n8 (ttyS1, 9600 bd, no parity, 8 bits) - -3. Adjust to kernel flags for the new kernel, - again in lilo.conf (kernel section):: - - append = "console=ttyS1,9600" - -4. Make sure a getty runs on the serial port so that you can login to - it once the system is done booting. This is done by adding a line - like this to ``/etc/inittab`` (exact syntax depends on your getty):: - - S1:23:respawn:/sbin/getty -L ttyS1 9600 vt100 - -5. Init and ``/etc/ioctl.save`` - - Sysvinit remembers its stty settings in a file in ``/etc``, called - ``/etc/ioctl.save``. REMOVE THIS FILE before using the serial - console for the first time, because otherwise init will probably - set the baudrate to 38400 (baudrate of the virtual console). - -6. ``/dev/console`` and X - Programs that want to do something with the virtual console usually - open ``/dev/console``. If you have created the new ``/dev/console`` device, - and your console is NOT the virtual console some programs will fail. - Those are programs that want to access the VT interface, and use - ``/dev/console instead of /dev/tty0``. Some of those programs are:: - - Xfree86, svgalib, gpm, SVGATextMode - - It should be fixed in modern versions of these programs though. - - Note that if you boot without a ``console=`` option (or with - ``console=/dev/tty0``), ``/dev/console`` is the same as ``/dev/tty0``. - In that case everything will still work. - -7. Thanks - - Thanks to Geert Uytterhoeven - for porting the patches from 2.1.4x to 2.1.6x for taking care of - the integration of these patches into m68k, ppc and alpha. - -Miquel van Smoorenburg , 11-Jun-2000 diff --git a/Documentation/sysfs-rules.txt b/Documentation/sysfs-rules.txt deleted file mode 100644 index 04bdd52cba1d..000000000000 --- a/Documentation/sysfs-rules.txt +++ /dev/null @@ -1,192 +0,0 @@ -Rules on how to access information in the Linux kernel sysfs -============================================================ - -The kernel-exported sysfs exports internal kernel implementation details -and depends on internal kernel structures and layout. It is agreed upon -by the kernel developers that the Linux kernel does not provide a stable -internal API. Therefore, there are aspects of the sysfs interface that -may not be stable across kernel releases. - -To minimize the risk of breaking users of sysfs, which are in most cases -low-level userspace applications, with a new kernel release, the users -of sysfs must follow some rules to use an as-abstract-as-possible way to -access this filesystem. The current udev and HAL programs already -implement this and users are encouraged to plug, if possible, into the -abstractions these programs provide instead of accessing sysfs directly. - -But if you really do want or need to access sysfs directly, please follow -the following rules and then your programs should work with future -versions of the sysfs interface. - -- Do not use libsysfs - It makes assumptions about sysfs which are not true. Its API does not - offer any abstraction, it exposes all the kernel driver-core - implementation details in its own API. Therefore it is not better than - reading directories and opening the files yourself. - Also, it is not actively maintained, in the sense of reflecting the - current kernel development. The goal of providing a stable interface - to sysfs has failed; it causes more problems than it solves. It - violates many of the rules in this document. - -- sysfs is always at ``/sys`` - Parsing ``/proc/mounts`` is a waste of time. Other mount points are a - system configuration bug you should not try to solve. For test cases, - possibly support a ``SYSFS_PATH`` environment variable to overwrite the - application's behavior, but never try to search for sysfs. Never try - to mount it, if you are not an early boot script. - -- devices are only "devices" - There is no such thing like class-, bus-, physical devices, - interfaces, and such that you can rely on in userspace. Everything is - just simply a "device". Class-, bus-, physical, ... types are just - kernel implementation details which should not be expected by - applications that look for devices in sysfs. - - The properties of a device are: - - - devpath (``/devices/pci0000:00/0000:00:1d.1/usb2/2-2/2-2:1.0``) - - - identical to the DEVPATH value in the event sent from the kernel - at device creation and removal - - the unique key to the device at that point in time - - the kernel's path to the device directory without the leading - ``/sys``, and always starting with a slash - - all elements of a devpath must be real directories. Symlinks - pointing to /sys/devices must always be resolved to their real - target and the target path must be used to access the device. - That way the devpath to the device matches the devpath of the - kernel used at event time. - - using or exposing symlink values as elements in a devpath string - is a bug in the application - - - kernel name (``sda``, ``tty``, ``0000:00:1f.2``, ...) - - - a directory name, identical to the last element of the devpath - - applications need to handle spaces and characters like ``!`` in - the name - - - subsystem (``block``, ``tty``, ``pci``, ...) - - - simple string, never a path or a link - - retrieved by reading the "subsystem"-link and using only the - last element of the target path - - - driver (``tg3``, ``ata_piix``, ``uhci_hcd``) - - - a simple string, which may contain spaces, never a path or a - link - - it is retrieved by reading the "driver"-link and using only the - last element of the target path - - devices which do not have "driver"-link just do not have a - driver; copying the driver value in a child device context is a - bug in the application - - - attributes - - - the files in the device directory or files below subdirectories - of the same device directory - - accessing attributes reached by a symlink pointing to another device, - like the "device"-link, is a bug in the application - - Everything else is just a kernel driver-core implementation detail - that should not be assumed to be stable across kernel releases. - -- Properties of parent devices never belong into a child device. - Always look at the parent devices themselves for determining device - context properties. If the device ``eth0`` or ``sda`` does not have a - "driver"-link, then this device does not have a driver. Its value is empty. - Never copy any property of the parent-device into a child-device. Parent - device properties may change dynamically without any notice to the - child device. - -- Hierarchy in a single device tree - There is only one valid place in sysfs where hierarchy can be examined - and this is below: ``/sys/devices.`` - It is planned that all device directories will end up in the tree - below this directory. - -- Classification by subsystem - There are currently three places for classification of devices: - ``/sys/block,`` ``/sys/class`` and ``/sys/bus.`` It is planned that these will - not contain any device directories themselves, but only flat lists of - symlinks pointing to the unified ``/sys/devices`` tree. - All three places have completely different rules on how to access - device information. It is planned to merge all three - classification directories into one place at ``/sys/subsystem``, - following the layout of the bus directories. All buses and - classes, including the converted block subsystem, will show up - there. - The devices belonging to a subsystem will create a symlink in the - "devices" directory at ``/sys/subsystem//devices``, - - If ``/sys/subsystem`` exists, ``/sys/bus``, ``/sys/class`` and ``/sys/block`` - can be ignored. If it does not exist, you always have to scan all three - places, as the kernel is free to move a subsystem from one place to - the other, as long as the devices are still reachable by the same - subsystem name. - - Assuming ``/sys/class/`` and ``/sys/bus/``, or - ``/sys/block`` and ``/sys/class/block`` are not interchangeable is a bug in - the application. - -- Block - The converted block subsystem at ``/sys/class/block`` or - ``/sys/subsystem/block`` will contain the links for disks and partitions - at the same level, never in a hierarchy. Assuming the block subsystem to - contain only disks and not partition devices in the same flat list is - a bug in the application. - -- "device"-link and :-links - Never depend on the "device"-link. The "device"-link is a workaround - for the old layout, where class devices are not created in - ``/sys/devices/`` like the bus devices. If the link-resolving of a - device directory does not end in ``/sys/devices/``, you can use the - "device"-link to find the parent devices in ``/sys/devices/``, That is the - single valid use of the "device"-link; it must never appear in any - path as an element. Assuming the existence of the "device"-link for - a device in ``/sys/devices/`` is a bug in the application. - Accessing ``/sys/class/net/eth0/device`` is a bug in the application. - - Never depend on the class-specific links back to the ``/sys/class`` - directory. These links are also a workaround for the design mistake - that class devices are not created in ``/sys/devices.`` If a device - directory does not contain directories for child devices, these links - may be used to find the child devices in ``/sys/class.`` That is the single - valid use of these links; they must never appear in any path as an - element. Assuming the existence of these links for devices which are - real child device directories in the ``/sys/devices`` tree is a bug in - the application. - - It is planned to remove all these links when all class device - directories live in ``/sys/devices.`` - -- Position of devices along device chain can change. - Never depend on a specific parent device position in the devpath, - or the chain of parent devices. The kernel is free to insert devices into - the chain. You must always request the parent device you are looking for - by its subsystem value. You need to walk up the chain until you find - the device that matches the expected subsystem. Depending on a specific - position of a parent device or exposing relative paths using ``../`` to - access the chain of parents is a bug in the application. - -- When reading and writing sysfs device attribute files, avoid dependency - on specific error codes wherever possible. This minimizes coupling to - the error handling implementation within the kernel. - - In general, failures to read or write sysfs device attributes shall - propagate errors wherever possible. Common errors include, but are not - limited to: - - ``-EIO``: The read or store operation is not supported, typically - returned by the sysfs system itself if the read or store pointer - is ``NULL``. - - ``-ENXIO``: The read or store operation failed - - Error codes will not be changed without good reason, and should a change - to error codes result in user-space breakage, it will be fixed, or the - the offending change will be reverted. - - Userspace applications can, however, expect the format and contents of - the attribute files to remain consistent in the absence of a version - attribute change in the context of a given attribute. diff --git a/Documentation/sysrq.txt b/Documentation/sysrq.txt deleted file mode 100644 index d1712ea2d314..000000000000 --- a/Documentation/sysrq.txt +++ /dev/null @@ -1,289 +0,0 @@ -Linux Magic System Request Key Hacks -==================================== - -Documentation for sysrq.c - -What is the magic SysRq key? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -It is a 'magical' key combo you can hit which the kernel will respond to -regardless of whatever else it is doing, unless it is completely locked up. - -How do I enable the magic SysRq key? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You need to say "yes" to 'Magic SysRq key (CONFIG_MAGIC_SYSRQ)' when -configuring the kernel. When running a kernel with SysRq compiled in, -/proc/sys/kernel/sysrq controls the functions allowed to be invoked via -the SysRq key. The default value in this file is set by the -CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE config symbol, which itself defaults -to 1. Here is the list of possible values in /proc/sys/kernel/sysrq: - - - 0 - disable sysrq completely - - 1 - enable all functions of sysrq - - >1 - bitmask of allowed sysrq functions (see below for detailed function - description):: - - 2 = 0x2 - enable control of console logging level - 4 = 0x4 - enable control of keyboard (SAK, unraw) - 8 = 0x8 - enable debugging dumps of processes etc. - 16 = 0x10 - enable sync command - 32 = 0x20 - enable remount read-only - 64 = 0x40 - enable signalling of processes (term, kill, oom-kill) - 128 = 0x80 - allow reboot/poweroff - 256 = 0x100 - allow nicing of all RT tasks - -You can set the value in the file by the following command:: - - echo "number" >/proc/sys/kernel/sysrq - -The number may be written here either as decimal or as hexadecimal -with the 0x prefix. CONFIG_MAGIC_SYSRQ_DEFAULT_ENABLE must always be -written in hexadecimal. - -Note that the value of ``/proc/sys/kernel/sysrq`` influences only the invocation -via a keyboard. Invocation of any operation via ``/proc/sysrq-trigger`` is -always allowed (by a user with admin privileges). - -How do I use the magic SysRq key? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -On x86 - You press the key combo :kbd:`ALT-SysRq-`. - -.. note:: - Some - keyboards may not have a key labeled 'SysRq'. The 'SysRq' key is - also known as the 'Print Screen' key. Also some keyboards cannot - handle so many keys being pressed at the same time, so you might - have better luck with press :kbd:`Alt`, press :kbd:`SysRq`, - release :kbd:`SysRq`, press :kbd:``, release everything. - -On SPARC - You press :kbd:`ALT-STOP-`, I believe. - -On the serial console (PC style standard serial ports only) - You send a ``BREAK``, then within 5 seconds a command key. Sending - ``BREAK`` twice is interpreted as a normal BREAK. - -On PowerPC - Press :kbd:`ALT - Print Screen` (or :kbd:`F13`) - :kbd:``, - :kbd:`Print Screen` (or :kbd:`F13`) - :kbd:`` may suffice. - -On other - If you know of the key combos for other architectures, please - let me know so I can add them to this section. - -On all - write a character to /proc/sysrq-trigger. e.g.:: - - echo t > /proc/sysrq-trigger - -What are the 'command' keys? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -=========== =================================================================== -Command Function -=========== =================================================================== -``b`` Will immediately reboot the system without syncing or unmounting - your disks. - -``c`` Will perform a system crash by a NULL pointer dereference. - A crashdump will be taken if configured. - -``d`` Shows all locks that are held. - -``e`` Send a SIGTERM to all processes, except for init. - -``f`` Will call the oom killer to kill a memory hog process, but do not - panic if nothing can be killed. - -``g`` Used by kgdb (kernel debugger) - -``h`` Will display help (actually any other key than those listed - here will display help. but ``h`` is easy to remember :-) - -``i`` Send a SIGKILL to all processes, except for init. - -``j`` Forcibly "Just thaw it" - filesystems frozen by the FIFREEZE ioctl. - -``k`` Secure Access Key (SAK) Kills all programs on the current virtual - console. NOTE: See important comments below in SAK section. - -``l`` Shows a stack backtrace for all active CPUs. - -``m`` Will dump current memory info to your console. - -``n`` Used to make RT tasks nice-able - -``o`` Will shut your system off (if configured and supported). - -``p`` Will dump the current registers and flags to your console. - -``q`` Will dump per CPU lists of all armed hrtimers (but NOT regular - timer_list timers) and detailed information about all - clockevent devices. - -``r`` Turns off keyboard raw mode and sets it to XLATE. - -``s`` Will attempt to sync all mounted filesystems. - -``t`` Will dump a list of current tasks and their information to your - console. - -``u`` Will attempt to remount all mounted filesystems read-only. - -``v`` Forcefully restores framebuffer console -``v`` Causes ETM buffer dump [ARM-specific] - -``w`` Dumps tasks that are in uninterruptable (blocked) state. - -``x`` Used by xmon interface on ppc/powerpc platforms. - Show global PMU Registers on sparc64. - Dump all TLB entries on MIPS. - -``y`` Show global CPU Registers [SPARC-64 specific] - -``z`` Dump the ftrace buffer - -``0``-``9`` Sets the console log level, controlling which kernel messages - will be printed to your console. (``0``, for example would make - it so that only emergency messages like PANICs or OOPSes would - make it to your console.) -=========== =================================================================== - -Okay, so what can I use them for? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Well, unraw(r) is very handy when your X server or a svgalib program crashes. - -sak(k) (Secure Access Key) is useful when you want to be sure there is no -trojan program running at console which could grab your password -when you would try to login. It will kill all programs on given console, -thus letting you make sure that the login prompt you see is actually -the one from init, not some trojan program. - -.. important:: - - In its true form it is not a true SAK like the one in a - c2 compliant system, and it should not be mistaken as - such. - -It seems others find it useful as (System Attention Key) which is -useful when you want to exit a program that will not let you switch consoles. -(For example, X or a svgalib program.) - -``reboot(b)`` is good when you're unable to shut down. But you should also -``sync(s)`` and ``umount(u)`` first. - -``crash(c)`` can be used to manually trigger a crashdump when the system is hung. -Note that this just triggers a crash if there is no dump mechanism available. - -``sync(s)`` is great when your system is locked up, it allows you to sync your -disks and will certainly lessen the chance of data loss and fscking. Note -that the sync hasn't taken place until you see the "OK" and "Done" appear -on the screen. (If the kernel is really in strife, you may not ever get the -OK or Done message...) - -``umount(u)`` is basically useful in the same ways as ``sync(s)``. I generally -``sync(s)``, ``umount(u)``, then ``reboot(b)`` when my system locks. It's saved -me many a fsck. Again, the unmount (remount read-only) hasn't taken place until -you see the "OK" and "Done" message appear on the screen. - -The loglevels ``0``-``9`` are useful when your console is being flooded with -kernel messages you do not want to see. Selecting ``0`` will prevent all but -the most urgent kernel messages from reaching your console. (They will -still be logged if syslogd/klogd are alive, though.) - -``term(e)`` and ``kill(i)`` are useful if you have some sort of runaway process -you are unable to kill any other way, especially if it's spawning other -processes. - -"just thaw ``it(j)``" is useful if your system becomes unresponsive due to a -frozen (probably root) filesystem via the FIFREEZE ioctl. - -Sometimes SysRq seems to get 'stuck' after using it, what can I do? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -That happens to me, also. I've found that tapping shift, alt, and control -on both sides of the keyboard, and hitting an invalid sysrq sequence again -will fix the problem. (i.e., something like :kbd:`alt-sysrq-z`). Switching to -another virtual console (:kbd:`ALT+Fn`) and then back again should also help. - -I hit SysRq, but nothing seems to happen, what's wrong? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -There are some keyboards that produce a different keycode for SysRq than the -pre-defined value of 99 (see ``KEY_SYSRQ`` in ``include/linux/input.h``), or -which don't have a SysRq key at all. In these cases, run ``showkey -s`` to find -an appropriate scancode sequence, and use ``setkeycodes 99`` to map -this sequence to the usual SysRq code (e.g., ``setkeycodes e05b 99``). It's -probably best to put this command in a boot script. Oh, and by the way, you -exit ``showkey`` by not typing anything for ten seconds. - -I want to add SysRQ key events to a module, how does it work? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In order to register a basic function with the table, you must first include -the header ``include/linux/sysrq.h``, this will define everything else you need. -Next, you must create a ``sysrq_key_op`` struct, and populate it with A) the key -handler function you will use, B) a help_msg string, that will print when SysRQ -prints help, and C) an action_msg string, that will print right before your -handler is called. Your handler must conform to the prototype in 'sysrq.h'. - -After the ``sysrq_key_op`` is created, you can call the kernel function -``register_sysrq_key(int key, struct sysrq_key_op *op_p);`` this will -register the operation pointed to by ``op_p`` at table key 'key', -if that slot in the table is blank. At module unload time, you must call -the function ``unregister_sysrq_key(int key, struct sysrq_key_op *op_p)``, which -will remove the key op pointed to by 'op_p' from the key 'key', if and only if -it is currently registered in that slot. This is in case the slot has been -overwritten since you registered it. - -The Magic SysRQ system works by registering key operations against a key op -lookup table, which is defined in 'drivers/tty/sysrq.c'. This key table has -a number of operations registered into it at compile time, but is mutable, -and 2 functions are exported for interface to it:: - - register_sysrq_key and unregister_sysrq_key. - -Of course, never ever leave an invalid pointer in the table. I.e., when -your module that called register_sysrq_key() exits, it must call -unregister_sysrq_key() to clean up the sysrq key table entry that it used. -Null pointers in the table are always safe. :) - -If for some reason you feel the need to call the handle_sysrq function from -within a function called by handle_sysrq, you must be aware that you are in -a lock (you are also in an interrupt handler, which means don't sleep!), so -you must call ``__handle_sysrq_nolock`` instead. - -When I hit a SysRq key combination only the header appears on the console? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Sysrq output is subject to the same console loglevel control as all -other console output. This means that if the kernel was booted 'quiet' -as is common on distro kernels the output may not appear on the actual -console, even though it will appear in the dmesg buffer, and be accessible -via the dmesg command and to the consumers of ``/proc/kmsg``. As a specific -exception the header line from the sysrq command is passed to all console -consumers as if the current loglevel was maximum. If only the header -is emitted it is almost certain that the kernel loglevel is too low. -Should you require the output on the console channel then you will need -to temporarily up the console loglevel using :kbd:`alt-sysrq-8` or:: - - echo 8 > /proc/sysrq-trigger - -Remember to return the loglevel to normal after triggering the sysrq -command you are interested in. - -I have more questions, who can I ask? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Just ask them on the linux-kernel mailing list: - linux-kernel@vger.kernel.org - -Credits -~~~~~~~ - -Written by Mydraal -Updated by Adam Sulmicki -Updated by Jeremy M. Dolan 2001/01/28 10:15:59 -Added to by Crutcher Dunnavant diff --git a/Documentation/unicode.txt b/Documentation/unicode.txt deleted file mode 100644 index 012e8e895842..000000000000 --- a/Documentation/unicode.txt +++ /dev/null @@ -1,189 +0,0 @@ -Unicode support -=============== - - Last update: 2005-01-17, version 1.4 - -This file is maintained by H. Peter Anvin as part -of the Linux Assigned Names And Numbers Authority (LANANA) project. -The current version can be found at: - - http://www.lanana.org/docs/unicode/unicode.txt - -Introdution ------------ - -The Linux kernel code has been rewritten to use Unicode to map -characters to fonts. By downloading a single Unicode-to-font table, -both the eight-bit character sets and UTF-8 mode are changed to use -the font as indicated. - -This changes the semantics of the eight-bit character tables subtly. -The four character tables are now: - -=============== =============================== ================ -Map symbol Map name Escape code (G0) -=============== =============================== ================ -LAT1_MAP Latin-1 (ISO 8859-1) ESC ( B -GRAF_MAP DEC VT100 pseudographics ESC ( 0 -IBMPC_MAP IBM code page 437 ESC ( U -USER_MAP User defined ESC ( K -=============== =============================== ================ - -In particular, ESC ( U is no longer "straight to font", since the font -might be completely different than the IBM character set. This -permits for example the use of block graphics even with a Latin-1 font -loaded. - -Note that although these codes are similar to ISO 2022, neither the -codes nor their uses match ISO 2022; Linux has two 8-bit codes (G0 and -G1), whereas ISO 2022 has four 7-bit codes (G0-G3). - -In accordance with the Unicode standard/ISO 10646 the range U+F000 to -U+F8FF has been reserved for OS-wide allocation (the Unicode Standard -refers to this as a "Corporate Zone", since this is inaccurate for -Linux we call it the "Linux Zone"). U+F000 was picked as the starting -point since it lets the direct-mapping area start on a large power of -two (in case 1024- or 2048-character fonts ever become necessary). -This leaves U+E000 to U+EFFF as End User Zone. - -[v1.2]: The Unicodes range from U+F000 and up to U+F7FF have been -hard-coded to map directly to the loaded font, bypassing the -translation table. The user-defined map now defaults to U+F000 to -U+F0FF, emulating the previous behaviour. In practice, this range -might be shorter; for example, vgacon can only handle 256-character -(U+F000..U+F0FF) or 512-character (U+F000..U+F1FF) fonts. - - -Actual characters assigned in the Linux Zone --------------------------------------------- - -In addition, the following characters not present in Unicode 1.1.4 -have been defined; these are used by the DEC VT graphics map. [v1.2] -THIS USE IS OBSOLETE AND SHOULD NO LONGER BE USED; PLEASE SEE BELOW. - -====== ====================================== -U+F800 DEC VT GRAPHICS HORIZONTAL LINE SCAN 1 -U+F801 DEC VT GRAPHICS HORIZONTAL LINE SCAN 3 -U+F803 DEC VT GRAPHICS HORIZONTAL LINE SCAN 7 -U+F804 DEC VT GRAPHICS HORIZONTAL LINE SCAN 9 -====== ====================================== - -The DEC VT220 uses a 6x10 character matrix, and these characters form -a smooth progression in the DEC VT graphics character set. I have -omitted the scan 5 line, since it is also used as a block-graphics -character, and hence has been coded as U+2500 FORMS LIGHT HORIZONTAL. - -[v1.3]: These characters have been officially added to Unicode 3.2.0; -they are added at U+23BA, U+23BB, U+23BC, U+23BD. Linux now uses the -new values. - -[v1.2]: The following characters have been added to represent common -keyboard symbols that are unlikely to ever be added to Unicode proper -since they are horribly vendor-specific. This, of course, is an -excellent example of horrible design. - -====== ====================================== -U+F810 KEYBOARD SYMBOL FLYING FLAG -U+F811 KEYBOARD SYMBOL PULLDOWN MENU -U+F812 KEYBOARD SYMBOL OPEN APPLE -U+F813 KEYBOARD SYMBOL SOLID APPLE -====== ====================================== - -Klingon language support ------------------------- - -In 1996, Linux was the first operating system in the world to add -support for the artificial language Klingon, created by Marc Okrand -for the "Star Trek" television series. This encoding was later -adopted by the ConScript Unicode Registry and proposed (but ultimately -rejected) for inclusion in Unicode Plane 1. Thus, it remains as a -Linux/CSUR private assignment in the Linux Zone. - -This encoding has been endorsed by the Klingon Language Institute. -For more information, contact them at: - - http://www.kli.org/ - -Since the characters in the beginning of the Linux CZ have been more -of the dingbats/symbols/forms type and this is a language, I have -located it at the end, on a 16-cell boundary in keeping with standard -Unicode practice. - -.. note:: - - This range is now officially managed by the ConScript Unicode - Registry. The normative reference is at: - - http://www.evertype.com/standards/csur/klingon.html - -Klingon has an alphabet of 26 characters, a positional numeric writing -system with 10 digits, and is written left-to-right, top-to-bottom. - -Several glyph forms for the Klingon alphabet have been proposed. -However, since the set of symbols appear to be consistent throughout, -with only the actual shapes being different, in keeping with standard -Unicode practice these differences are considered font variants. - -====== ======================================================= -U+F8D0 KLINGON LETTER A -U+F8D1 KLINGON LETTER B -U+F8D2 KLINGON LETTER CH -U+F8D3 KLINGON LETTER D -U+F8D4 KLINGON LETTER E -U+F8D5 KLINGON LETTER GH -U+F8D6 KLINGON LETTER H -U+F8D7 KLINGON LETTER I -U+F8D8 KLINGON LETTER J -U+F8D9 KLINGON LETTER L -U+F8DA KLINGON LETTER M -U+F8DB KLINGON LETTER N -U+F8DC KLINGON LETTER NG -U+F8DD KLINGON LETTER O -U+F8DE KLINGON LETTER P -U+F8DF KLINGON LETTER Q - - Written in standard Okrand Latin transliteration -U+F8E0 KLINGON LETTER QH - - Written in standard Okrand Latin transliteration -U+F8E1 KLINGON LETTER R -U+F8E2 KLINGON LETTER S -U+F8E3 KLINGON LETTER T -U+F8E4 KLINGON LETTER TLH -U+F8E5 KLINGON LETTER U -U+F8E6 KLINGON LETTER V -U+F8E7 KLINGON LETTER W -U+F8E8 KLINGON LETTER Y -U+F8E9 KLINGON LETTER GLOTTAL STOP - -U+F8F0 KLINGON DIGIT ZERO -U+F8F1 KLINGON DIGIT ONE -U+F8F2 KLINGON DIGIT TWO -U+F8F3 KLINGON DIGIT THREE -U+F8F4 KLINGON DIGIT FOUR -U+F8F5 KLINGON DIGIT FIVE -U+F8F6 KLINGON DIGIT SIX -U+F8F7 KLINGON DIGIT SEVEN -U+F8F8 KLINGON DIGIT EIGHT -U+F8F9 KLINGON DIGIT NINE - -U+F8FD KLINGON COMMA -U+F8FE KLINGON FULL STOP -U+F8FF KLINGON SYMBOL FOR EMPIRE -====== ======================================================= - -Other Fictional and Artificial Scripts --------------------------------------- - -Since the assignment of the Klingon Linux Unicode block, a registry of -fictional and artificial scripts has been established by John Cowan - and Michael Everson . -The ConScript Unicode Registry is accessible at: - - http://www.evertype.com/standards/csur/ - -The ranges used fall at the low end of the End User Zone and can hence -not be normatively assigned, but it is recommended that people who -wish to encode fictional scripts use these codes, in the interest of -interoperability. For Klingon, CSUR has adopted the Linux encoding. -The CSUR people are driving adding Tengwar and Cirth into Unicode -Plane 1; the addition of Klingon to Unicode Plane 1 has been rejected -and so the above encoding remains official. diff --git a/README b/README deleted file mode 100644 index 3335b3b2973a..000000000000 --- a/README +++ /dev/null @@ -1,411 +0,0 @@ -Linux kernel release 4.x -============================================= - -These are the release notes for Linux version 4. Read them carefully, -as they tell you what this is all about, explain how to install the -kernel, and what to do if something goes wrong. - -What is Linux? --------------- - - Linux is a clone of the operating system Unix, written from scratch by - Linus Torvalds with assistance from a loosely-knit team of hackers across - the Net. It aims towards POSIX and Single UNIX Specification compliance. - - It has all the features you would expect in a modern fully-fledged Unix, - including true multitasking, virtual memory, shared libraries, demand - loading, shared copy-on-write executables, proper memory management, - and multistack networking including IPv4 and IPv6. - - It is distributed under the GNU General Public License - see the - accompanying COPYING file for more details. - -On what hardware does it run? ------------------------------ - - Although originally developed first for 32-bit x86-based PCs (386 or higher), - today Linux also runs on (at least) the Compaq Alpha AXP, Sun SPARC and - UltraSPARC, Motorola 68000, PowerPC, PowerPC64, ARM, Hitachi SuperH, Cell, - IBM S/390, MIPS, HP PA-RISC, Intel IA-64, DEC VAX, AMD x86-64, AXIS CRIS, - Xtensa, Tilera TILE, AVR32, ARC and Renesas M32R architectures. - - Linux is easily portable to most general-purpose 32- or 64-bit architectures - as long as they have a paged memory management unit (PMMU) and a port of the - GNU C compiler (gcc) (part of The GNU Compiler Collection, GCC). Linux has - also been ported to a number of architectures without a PMMU, although - functionality is then obviously somewhat limited. - Linux has also been ported to itself. You can now run the kernel as a - userspace application - this is called UserMode Linux (UML). - -Documentation -------------- - - - There is a lot of documentation available both in electronic form on - the Internet and in books, both Linux-specific and pertaining to - general UNIX questions. I'd recommend looking into the documentation - subdirectories on any Linux FTP site for the LDP (Linux Documentation - Project) books. This README is not meant to be documentation on the - system: there are much better sources available. - - - There are various README files in the Documentation/ subdirectory: - these typically contain kernel-specific installation notes for some - drivers for example. See Documentation/00-INDEX for a list of what - is contained in each file. Please read the Changes file, as it - contains information about the problems, which may result by upgrading - your kernel. - - - The Documentation/DocBook/ subdirectory contains several guides for - kernel developers and users. These guides can be rendered in a - number of formats: PostScript (.ps), PDF, HTML, & man-pages, among others. - After installation, ``make psdocs``, ``make pdfdocs``, ``make htmldocs``, - or ``make mandocs`` will render the documentation in the requested format. - -Installing the kernel source ----------------------------- - - - If you install the full sources, put the kernel tarball in a - directory where you have permissions (e.g. your home directory) and - unpack it:: - - xz -cd linux-4.X.tar.xz | tar xvf - - - Replace "X" with the version number of the latest kernel. - - Do NOT use the /usr/src/linux area! This area has a (usually - incomplete) set of kernel headers that are used by the library header - files. They should match the library, and not get messed up by - whatever the kernel-du-jour happens to be. - - - You can also upgrade between 4.x releases by patching. Patches are - distributed in the xz format. To install by patching, get all the - newer patch files, enter the top level directory of the kernel source - (linux-4.X) and execute:: - - xz -cd ../patch-4.x.xz | patch -p1 - - Replace "x" for all versions bigger than the version "X" of your current - source tree, **in_order**, and you should be ok. You may want to remove - the backup files (some-file-name~ or some-file-name.orig), and make sure - that there are no failed patches (some-file-name# or some-file-name.rej). - If there are, either you or I have made a mistake. - - Unlike patches for the 4.x kernels, patches for the 4.x.y kernels - (also known as the -stable kernels) are not incremental but instead apply - directly to the base 4.x kernel. For example, if your base kernel is 4.0 - and you want to apply the 4.0.3 patch, you must not first apply the 4.0.1 - and 4.0.2 patches. Similarly, if you are running kernel version 4.0.2 and - want to jump to 4.0.3, you must first reverse the 4.0.2 patch (that is, - patch -R) **before** applying the 4.0.3 patch. You can read more on this in - :ref:`Documentation/applying-patches.txt `. - - Alternatively, the script patch-kernel can be used to automate this - process. It determines the current kernel version and applies any - patches found:: - - linux/scripts/patch-kernel linux - - The first argument in the command above is the location of the - kernel source. Patches are applied from the current directory, but - an alternative directory can be specified as the second argument. - - - Make sure you have no stale .o files and dependencies lying around:: - - cd linux - make mrproper - - You should now have the sources correctly installed. - -Software requirements ---------------------- - - Compiling and running the 4.x kernels requires up-to-date - versions of various software packages. Consult - :ref:`Documentation/Changes ` for the minimum version numbers - required and how to get updates for these packages. Beware that using - excessively old versions of these packages can cause indirect - errors that are very difficult to track down, so don't assume that - you can just update packages when obvious problems arise during - build or operation. - -Build directory for the kernel ------------------------------- - - When compiling the kernel, all output files will per default be - stored together with the kernel source code. - Using the option ``make O=output/dir`` allows you to specify an alternate - place for the output files (including .config). - Example:: - - kernel source code: /usr/src/linux-4.X - build directory: /home/name/build/kernel - - To configure and build the kernel, use:: - - cd /usr/src/linux-4.X - make O=/home/name/build/kernel menuconfig - make O=/home/name/build/kernel - sudo make O=/home/name/build/kernel modules_install install - - Please note: If the ``O=output/dir`` option is used, then it must be - used for all invocations of make. - -Configuring the kernel ----------------------- - - Do not skip this step even if you are only upgrading one minor - version. New configuration options are added in each release, and - odd problems will turn up if the configuration files are not set up - as expected. If you want to carry your existing configuration to a - new version with minimal work, use ``make oldconfig``, which will - only ask you for the answers to new questions. - - - Alternative configuration commands are:: - - "make config" Plain text interface. - - "make menuconfig" Text based color menus, radiolists & dialogs. - - "make nconfig" Enhanced text based color menus. - - "make xconfig" Qt based configuration tool. - - "make gconfig" GTK+ based configuration tool. - - "make oldconfig" Default all questions based on the contents of - your existing ./.config file and asking about - new config symbols. - - "make silentoldconfig" - Like above, but avoids cluttering the screen - with questions already answered. - Additionally updates the dependencies. - - "make olddefconfig" - Like above, but sets new symbols to their default - values without prompting. - - "make defconfig" Create a ./.config file by using the default - symbol values from either arch/$ARCH/defconfig - or arch/$ARCH/configs/${PLATFORM}_defconfig, - depending on the architecture. - - "make ${PLATFORM}_defconfig" - Create a ./.config file by using the default - symbol values from - arch/$ARCH/configs/${PLATFORM}_defconfig. - Use "make help" to get a list of all available - platforms of your architecture. - - "make allyesconfig" - Create a ./.config file by setting symbol - values to 'y' as much as possible. - - "make allmodconfig" - Create a ./.config file by setting symbol - values to 'm' as much as possible. - - "make allnoconfig" Create a ./.config file by setting symbol - values to 'n' as much as possible. - - "make randconfig" Create a ./.config file by setting symbol - values to random values. - - "make localmodconfig" Create a config based on current config and - loaded modules (lsmod). Disables any module - option that is not needed for the loaded modules. - - To create a localmodconfig for another machine, - store the lsmod of that machine into a file - and pass it in as a LSMOD parameter. - - target$ lsmod > /tmp/mylsmod - target$ scp /tmp/mylsmod host:/tmp - - host$ make LSMOD=/tmp/mylsmod localmodconfig - - The above also works when cross compiling. - - "make localyesconfig" Similar to localmodconfig, except it will convert - all module options to built in (=y) options. - - You can find more information on using the Linux kernel config tools - in Documentation/kbuild/kconfig.txt. - - - NOTES on ``make config``: - - - Having unnecessary drivers will make the kernel bigger, and can - under some circumstances lead to problems: probing for a - nonexistent controller card may confuse your other controllers - - - A kernel with math-emulation compiled in will still use the - coprocessor if one is present: the math emulation will just - never get used in that case. The kernel will be slightly larger, - but will work on different machines regardless of whether they - have a math coprocessor or not. - - - The "kernel hacking" configuration details usually result in a - bigger or slower kernel (or both), and can even make the kernel - less stable by configuring some routines to actively try to - break bad code to find kernel problems (kmalloc()). Thus you - should probably answer 'n' to the questions for "development", - "experimental", or "debugging" features. - -Compiling the kernel --------------------- - - - Make sure you have at least gcc 3.2 available. - For more information, refer to :ref:`Documentation/Changes `. - - Please note that you can still run a.out user programs with this kernel. - - - Do a ``make`` to create a compressed kernel image. It is also - possible to do ``make install`` if you have lilo installed to suit the - kernel makefiles, but you may want to check your particular lilo setup first. - - To do the actual install, you have to be root, but none of the normal - build should require that. Don't take the name of root in vain. - - - If you configured any of the parts of the kernel as ``modules``, you - will also have to do ``make modules_install``. - - - Verbose kernel compile/build output: - - Normally, the kernel build system runs in a fairly quiet mode (but not - totally silent). However, sometimes you or other kernel developers need - to see compile, link, or other commands exactly as they are executed. - For this, use "verbose" build mode. This is done by passing - ``V=1`` to the ``make`` command, e.g.:: - - make V=1 all - - To have the build system also tell the reason for the rebuild of each - target, use ``V=2``. The default is ``V=0``. - - - Keep a backup kernel handy in case something goes wrong. This is - especially true for the development releases, since each new release - contains new code which has not been debugged. Make sure you keep a - backup of the modules corresponding to that kernel, as well. If you - are installing a new kernel with the same version number as your - working kernel, make a backup of your modules directory before you - do a ``make modules_install``. - - Alternatively, before compiling, use the kernel config option - "LOCALVERSION" to append a unique suffix to the regular kernel version. - LOCALVERSION can be set in the "General Setup" menu. - - - In order to boot your new kernel, you'll need to copy the kernel - image (e.g. .../linux/arch/x86/boot/bzImage after compilation) - to the place where your regular bootable kernel is found. - - - Booting a kernel directly from a floppy without the assistance of a - bootloader such as LILO, is no longer supported. - - If you boot Linux from the hard drive, chances are you use LILO, which - uses the kernel image as specified in the file /etc/lilo.conf. The - kernel image file is usually /vmlinuz, /boot/vmlinuz, /bzImage or - /boot/bzImage. To use the new kernel, save a copy of the old image - and copy the new image over the old one. Then, you MUST RERUN LILO - to update the loading map! If you don't, you won't be able to boot - the new kernel image. - - Reinstalling LILO is usually a matter of running /sbin/lilo. - You may wish to edit /etc/lilo.conf to specify an entry for your - old kernel image (say, /vmlinux.old) in case the new one does not - work. See the LILO docs for more information. - - After reinstalling LILO, you should be all set. Shutdown the system, - reboot, and enjoy! - - If you ever need to change the default root device, video mode, - ramdisk size, etc. in the kernel image, use the ``rdev`` program (or - alternatively the LILO boot options when appropriate). No need to - recompile the kernel to change these parameters. - - - Reboot with the new kernel and enjoy. - -If something goes wrong ------------------------ - - - If you have problems that seem to be due to kernel bugs, please check - the file MAINTAINERS to see if there is a particular person associated - with the part of the kernel that you are having trouble with. If there - isn't anyone listed there, then the second best thing is to mail - them to me (torvalds@linux-foundation.org), and possibly to any other - relevant mailing-list or to the newsgroup. - - - In all bug-reports, *please* tell what kernel you are talking about, - how to duplicate the problem, and what your setup is (use your common - sense). If the problem is new, tell me so, and if the problem is - old, please try to tell me when you first noticed it. - - - If the bug results in a message like:: - - unable to handle kernel paging request at address C0000010 - Oops: 0002 - EIP: 0010:XXXXXXXX - eax: xxxxxxxx ebx: xxxxxxxx ecx: xxxxxxxx edx: xxxxxxxx - esi: xxxxxxxx edi: xxxxxxxx ebp: xxxxxxxx - ds: xxxx es: xxxx fs: xxxx gs: xxxx - Pid: xx, process nr: xx - xx xx xx xx xx xx xx xx xx xx - - or similar kernel debugging information on your screen or in your - system log, please duplicate it *exactly*. The dump may look - incomprehensible to you, but it does contain information that may - help debugging the problem. The text above the dump is also - important: it tells something about why the kernel dumped code (in - the above example, it's due to a bad kernel pointer). More information - on making sense of the dump is in Documentation/oops-tracing.txt - - - If you compiled the kernel with CONFIG_KALLSYMS you can send the dump - as is, otherwise you will have to use the ``ksymoops`` program to make - sense of the dump (but compiling with CONFIG_KALLSYMS is usually preferred). - This utility can be downloaded from - ftp://ftp..kernel.org/pub/linux/utils/kernel/ksymoops/ . - Alternatively, you can do the dump lookup by hand: - - - In debugging dumps like the above, it helps enormously if you can - look up what the EIP value means. The hex value as such doesn't help - me or anybody else very much: it will depend on your particular - kernel setup. What you should do is take the hex value from the EIP - line (ignore the ``0010:``), and look it up in the kernel namelist to - see which kernel function contains the offending address. - - To find out the kernel function name, you'll need to find the system - binary associated with the kernel that exhibited the symptom. This is - the file 'linux/vmlinux'. To extract the namelist and match it against - the EIP from the kernel crash, do:: - - nm vmlinux | sort | less - - This will give you a list of kernel addresses sorted in ascending - order, from which it is simple to find the function that contains the - offending address. Note that the address given by the kernel - debugging messages will not necessarily match exactly with the - function addresses (in fact, that is very unlikely), so you can't - just 'grep' the list: the list will, however, give you the starting - point of each kernel function, so by looking for the function that - has a starting address lower than the one you are searching for but - is followed by a function with a higher address you will find the one - you want. In fact, it may be a good idea to include a bit of - "context" in your problem report, giving a few lines around the - interesting one. - - If you for some reason cannot do the above (you have a pre-compiled - kernel image or similar), telling me as much about your setup as - possible will help. Please read the :ref:`REPORTING-BUGS ` - document for details. - - - Alternatively, you can use gdb on a running kernel. (read-only; i.e. you - cannot change values or set break points.) To do this, first compile the - kernel with -g; edit arch/x86/Makefile appropriately, then do a ``make - clean``. You'll also need to enable CONFIG_PROC_FS (via ``make config``). - - After you've rebooted with the new kernel, do ``gdb vmlinux /proc/kcore``. - You can now use all the usual gdb commands. The command to look up the - point where your system crashed is ``l *0xXXXXXXXX``. (Replace the XXXes - with the EIP value.) - - gdb'ing a non-running kernel currently fails because ``gdb`` (wrongly) - disregards the starting offset for which the kernel is compiled. - diff --git a/REPORTING-BUGS b/REPORTING-BUGS deleted file mode 100644 index 05c53ac7fa76..000000000000 --- a/REPORTING-BUGS +++ /dev/null @@ -1,182 +0,0 @@ -.. _reportingbugs: - -Reporting bugs -++++++++++++++ - -Background -========== - -The upstream Linux kernel maintainers only fix bugs for specific kernel -versions. Those versions include the current "release candidate" (or -rc) -kernel, any "stable" kernel versions, and any "long term" kernels. - -Please see https://www.kernel.org/ for a list of supported kernels. Any -kernel marked with [EOL] is "end of life" and will not have any fixes -backported to it. - -If you've found a bug on a kernel version that isn't listed on kernel.org, -contact your Linux distribution or embedded vendor for support. -Alternatively, you can attempt to run one of the supported stable or -rc -kernels, and see if you can reproduce the bug on that. It's preferable -to reproduce the bug on the latest -rc kernel. - - -How to report Linux kernel bugs -=============================== - - -Identify the problematic subsystem ----------------------------------- - -Identifying which part of the Linux kernel might be causing your issue -increases your chances of getting your bug fixed. Simply posting to the -generic linux-kernel mailing list (LKML) may cause your bug report to be -lost in the noise of a mailing list that gets 1000+ emails a day. - -Instead, try to figure out which kernel subsystem is causing the issue, -and email that subsystem's maintainer and mailing list. If the subsystem -maintainer doesn't answer, then expand your scope to mailing lists like -LKML. - - -Identify who to notify ----------------------- - -Once you know the subsystem that is causing the issue, you should send a -bug report. Some maintainers prefer bugs to be reported via bugzilla -(https://bugzilla.kernel.org), while others prefer that bugs be reported -via the subsystem mailing list. - -To find out where to send an emailed bug report, find your subsystem or -device driver in the MAINTAINERS file. Search in the file for relevant -entries, and send your bug report to the person(s) listed in the "M:" -lines, making sure to Cc the mailing list(s) in the "L:" lines. When the -maintainer replies to you, make sure to 'Reply-all' in order to keep the -public mailing list(s) in the email thread. - -If you know which driver is causing issues, you can pass one of the driver -files to the get_maintainer.pl script:: - - perl scripts/get_maintainer.pl -f - -If it is a security bug, please copy the Security Contact listed in the -MAINTAINERS file. They can help coordinate bugfix and disclosure. See -:ref:`Documentation/SecurityBugs ` for more information. - -If you can't figure out which subsystem caused the issue, you should file -a bug in kernel.org bugzilla and send email to -linux-kernel@vger.kernel.org, referencing the bugzilla URL. (For more -information on the linux-kernel mailing list see -http://www.tux.org/lkml/). - - -Tips for reporting bugs ------------------------ - -If you haven't reported a bug before, please read: - - http://www.chiark.greenend.org.uk/~sgtatham/bugs.html - - http://www.catb.org/esr/faqs/smart-questions.html - -It's REALLY important to report bugs that seem unrelated as separate email -threads or separate bugzilla entries. If you report several unrelated -bugs at once, it's difficult for maintainers to tease apart the relevant -data. - - -Gather information ------------------- - -The most important information in a bug report is how to reproduce the -bug. This includes system information, and (most importantly) -step-by-step instructions for how a user can trigger the bug. - -If the failure includes an "OOPS:", take a picture of the screen, capture -a netconsole trace, or type the message from your screen into the bug -report. Please read "Documentation/oops-tracing.txt" before posting your -bug report. This explains what you should do with the "Oops" information -to make it useful to the recipient. - -This is a suggested format for a bug report sent via email or bugzilla. -Having a standardized bug report form makes it easier for you not to -overlook things, and easier for the developers to find the pieces of -information they're really interested in. If some information is not -relevant to your bug, feel free to exclude it. - -First run the ver_linux script included as scripts/ver_linux, which -reports the version of some important subsystems. Run this script with -the command ``sh scripts/ver_linux``. - -Use that information to fill in all fields of the bug report form, and -post it to the mailing list with a subject of "PROBLEM: " for easy identification by the developers:: - - [1.] One line summary of the problem: - [2.] Full description of the problem/report: - [3.] Keywords (i.e., modules, networking, kernel): - [4.] Kernel information - [4.1.] Kernel version (from /proc/version): - [4.2.] Kernel .config file: - [5.] Most recent kernel version which did not have the bug: - [6.] Output of Oops.. message (if applicable) with symbolic information - resolved (see Documentation/oops-tracing.txt) - [7.] A small shell script or example program which triggers the - problem (if possible) - [8.] Environment - [8.1.] Software (add the output of the ver_linux script here) - [8.2.] Processor information (from /proc/cpuinfo): - [8.3.] Module information (from /proc/modules): - [8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem) - [8.5.] PCI information ('lspci -vvv' as root) - [8.6.] SCSI information (from /proc/scsi/scsi) - [8.7.] Other information that might be relevant to the problem - (please look in /proc and include all information that you - think to be relevant): - [X.] Other notes, patches, fixes, workarounds: - - -Follow up -========= - -Expectations for bug reporters ------------------------------- - -Linux kernel maintainers expect bug reporters to be able to follow up on -bug reports. That may include running new tests, applying patches, -recompiling your kernel, and/or re-triggering your bug. The most -frustrating thing for maintainers is for someone to report a bug, and then -never follow up on a request to try out a fix. - -That said, it's still useful for a kernel maintainer to know a bug exists -on a supported kernel, even if you can't follow up with retests. Follow -up reports, such as replying to the email thread with "I tried the latest -kernel and I can't reproduce my bug anymore" are also helpful, because -maintainers have to assume silence means things are still broken. - -Expectations for kernel maintainers ------------------------------------ - -Linux kernel maintainers are busy, overworked human beings. Some times -they may not be able to address your bug in a day, a week, or two weeks. -If they don't answer your email, they may be on vacation, or at a Linux -conference. Check the conference schedule at https://LWN.net for more info: - - https://lwn.net/Calendar/ - -In general, kernel maintainers take 1 to 5 business days to respond to -bugs. The majority of kernel maintainers are employed to work on the -kernel, and they may not work on the weekends. Maintainers are scattered -around the world, and they may not work in your time zone. Unless you -have a high priority bug, please wait at least a week after the first bug -report before sending the maintainer a reminder email. - -The exceptions to this rule are regressions, kernel crashes, security holes, -or userspace breakage caused by new kernel behavior. Those bugs should be -addressed by the maintainers ASAP. If you suspect a maintainer is not -responding to these types of bugs in a timely manner (especially during a -merge window), escalate the bug to LKML and Linus Torvalds. - -Thank you! - -[Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ] -- cgit v1.2.3 From 8c27ceff3604b249a9efafbd1bd8b141b79e619d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 10:12:27 -0200 Subject: docs: fix locations of several documents that got moved The previous patch renamed several files that are cross-referenced along the Kernel documentation. Adjust the links to point to the right places. Signed-off-by: Mauro Carvalho Chehab --- Documentation/00-INDEX | 54 +++++++++++----------- Documentation/ABI/README | 2 +- Documentation/ABI/testing/sysfs-kernel-slab | 2 +- Documentation/DocBook/kernel-hacking.tmpl | 4 +- Documentation/acpi/video_extension.txt | 2 +- Documentation/admin-guide/README.rst | 13 +++--- Documentation/admin-guide/bad-memory.rst | 2 +- Documentation/admin-guide/binfmt-misc.rst | 4 +- Documentation/admin-guide/braille-console.rst | 6 +-- Documentation/admin-guide/bug-hunting.rst | 7 +-- Documentation/admin-guide/devices.rst | 2 +- Documentation/admin-guide/kernel-parameters.rst | 6 +-- Documentation/admin-guide/oops-tracing.rst | 2 +- Documentation/admin-guide/ramoops.rst | 2 +- Documentation/admin-guide/reporting-bugs.rst | 6 +-- Documentation/admin-guide/security-bugs.rst | 2 +- Documentation/admin-guide/unicode.rst | 2 +- Documentation/arm/Booting | 2 +- Documentation/atomic_ops.txt | 2 +- Documentation/blockdev/ramdisk.txt | 2 +- Documentation/cgroup-v1/00-INDEX | 2 +- .../devicetree/bindings/rtc/maxim,ds3231.txt | 2 +- Documentation/devicetree/bindings/rtc/pcf8563.txt | 2 +- .../devicetree/bindings/submitting-patches.txt | 2 +- Documentation/filesystems/locks.txt | 2 +- Documentation/filesystems/nfs/nfsroot.txt | 4 +- Documentation/frv/booting.txt | 2 +- Documentation/hwmon/submitting-patches | 8 ++-- Documentation/isdn/README | 2 +- Documentation/ja_JP/HOWTO | 24 +++++----- Documentation/ja_JP/SubmitChecklist | 8 ++-- Documentation/ja_JP/SubmittingPatches | 18 ++++---- Documentation/ja_JP/stable_api_nonsense.txt | 4 +- Documentation/ja_JP/stable_kernel_rules.txt | 6 +-- Documentation/kernel-per-CPU-kthreads.txt | 2 +- Documentation/ko_KR/HOWTO | 30 ++++++------ Documentation/ko_KR/stable_api_nonsense.txt | 4 +- Documentation/lockup-watchdogs.txt | 4 +- Documentation/m68k/kernel-options.txt | 2 +- Documentation/media/uapi/v4l/diff-v4l.rst | 4 +- Documentation/media/v4l-drivers/bttv.rst | 4 +- Documentation/memory-hotplug.txt | 2 +- Documentation/networking/netconsole.txt | 2 +- Documentation/networking/netdev-FAQ.txt | 8 ++-- Documentation/networking/vortex.txt | 2 +- Documentation/power/00-INDEX | 2 +- Documentation/power/pci.txt | 10 ++-- Documentation/power/runtime_pm.txt | 2 +- Documentation/power/swsusp-dmcrypt.txt | 2 +- Documentation/process/4.Coding.rst | 4 +- Documentation/process/5.Posting.rst | 12 ++--- Documentation/process/8.Conclusion.rst | 6 +-- Documentation/process/adding-syscalls.rst | 2 +- Documentation/process/coding-style.rst | 2 +- Documentation/process/howto.rst | 24 +++++----- Documentation/process/management-style.rst | 2 +- Documentation/process/stable-kernel-rules.rst | 4 +- Documentation/process/submit-checklist.rst | 6 +-- Documentation/process/submitting-drivers.rst | 8 ++-- Documentation/process/submitting-patches.rst | 14 +++--- Documentation/rfkill.txt | 2 +- Documentation/scsi/scsi-parameters.txt | 2 +- Documentation/scsi/scsi_mid_low_api.txt | 2 +- Documentation/scsi/sym53c8xx_2.txt | 2 +- Documentation/sound/alsa/alsa-parameters.txt | 2 +- Documentation/sound/oss/oss-parameters.txt | 2 +- Documentation/sysctl/kernel.txt | 4 +- Documentation/virtual/kvm/review-checklist.txt | 4 +- Documentation/vm/numa | 2 +- .../watchdog/convert_drivers_to_kernel_api.txt | 2 +- Documentation/watchdog/watchdog-parameters.txt | 2 +- Documentation/x86/boot.txt | 2 +- Documentation/zh_CN/CodingStyle | 6 +-- Documentation/zh_CN/HOWTO | 30 ++++++------ Documentation/zh_CN/SecurityBugs | 6 +-- Documentation/zh_CN/SubmittingDrivers | 12 ++--- Documentation/zh_CN/SubmittingPatches | 14 +++--- Documentation/zh_CN/arm/Booting | 2 +- Documentation/zh_CN/email-clients.txt | 4 +- Documentation/zh_CN/oops-tracing.txt | 6 +-- Documentation/zh_CN/stable_api_nonsense.txt | 4 +- Documentation/zh_CN/stable_kernel_rules.txt | 6 +-- .../zh_CN/volatile-considered-harmful.txt | 4 +- MAINTAINERS | 10 ++-- arch/x86/Kconfig | 2 +- drivers/acpi/Kconfig | 2 +- drivers/ata/libata-core.c | 2 +- drivers/char/pcmcia/cm4000_cs.c | 4 +- drivers/net/can/grcan.c | 2 +- drivers/nvdimm/Kconfig | 2 +- drivers/staging/vme/devices/vme_user.c | 2 +- drivers/video/fbdev/skeletonfb.c | 8 ++-- drivers/virtio/Kconfig | 2 +- fs/Kconfig.binfmt | 4 +- fs/pstore/Kconfig | 2 +- include/linux/device.h | 2 +- include/linux/pm.h | 2 +- include/uapi/linux/major.h | 2 +- init/Kconfig | 2 +- init/main.c | 2 +- lib/Kconfig.debug | 2 +- scripts/checkpatch.pl | 6 +-- tools/testing/selftests/futex/README | 2 +- 103 files changed, 280 insertions(+), 278 deletions(-) diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index d07575a8499e..39caa6544d1f 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -15,11 +15,11 @@ Following translations are available on the WWW: ABI/ - info on kernel <-> userspace ABI and relative interface stability. -BUG-HUNTING +admin-guide/bug-hunting.rst - brute force method of doing binary search of patches to find bug. -Changes +process/changes.rst - list of changes that break older software packages. -CodingStyle +process/coding-style.rst - how the maintainers expect the C code in the kernel to look. DMA-API.txt - DMA API, pci_ API & extensions for non-consistent memory machines. @@ -33,7 +33,7 @@ DocBook/ - directory with DocBook templates etc. for kernel documentation. EDID/ - directory with info on customizing EDID for broken gfx/displays. -HOWTO +process/howto.rst - the process and procedures of how to do Linux kernel development. IPMI.txt - info on Linux Intelligent Platform Management Interface (IPMI) Driver. @@ -48,7 +48,7 @@ Intel-IOMMU.txt Makefile - This file does nothing. Removing it breaks make htmldocs and make distclean. -ManagementStyle +process/management-style.rst - how to (attempt to) manage kernel hackers. RCU/ - directory with info on RCU (read-copy update). @@ -56,13 +56,13 @@ SAK.txt - info on Secure Attention Keys. SM501.txt - Silicon Motion SM501 multimedia companion chip -SecurityBugs +admin-guide/security-bugs.rst - procedure for reporting security bugs found in the kernel. -SubmitChecklist +process/submit-checklist.rst - Linux kernel patch submission checklist. -SubmittingDrivers +process/submitting-drivers.rst - procedure to get a new driver source included into the kernel tree. -SubmittingPatches +process/submitting-patches.rst - procedure to get a source patch included into the kernel tree. VGA-softcursor.txt - how to change your VGA cursor from a blinking underscore. @@ -72,7 +72,7 @@ acpi/ - info on ACPI-specific hooks in the kernel. aoe/ - description of AoE (ATA over Ethernet) along with config examples. -applying-patches.txt +process/applying-patches.rst - description of various trees and how to apply their patches. arm/ - directory with info about Linux on the ARM architecture. @@ -86,7 +86,7 @@ auxdisplay/ - misc. LCD driver documentation (cfag12864b, ks0108). backlight/ - directory with info on controlling backlights in flat panel displays -bad_memory.txt +admin-guide/bad-memory.rst - how to use kernel parameters to exclude bad RAM regions. basic_profiling.txt - basic instructions for those who wants to profile Linux kernel. @@ -154,7 +154,7 @@ process/ - how to work with the mainline kernel development process. device-mapper/ - directory with info on Device Mapper. -devices.txt +admin-guide/devices.rst - plain ASCII listing of all the nodes in /dev/ with major minor #'s. devicetree/ - directory with info on device tree files used by OF/PowerPC/ARM @@ -178,7 +178,7 @@ efi-stub.txt - How to use the EFI boot stub to bypass GRUB or elilo on EFI systems. eisa.txt - info on EISA bus support. -email-clients.txt +process/email-clients.rst - info on how to use e-mail to send un-mangled (git) patches. extcon/ - directory with porting guide for Android kernel switch driver. @@ -226,9 +226,9 @@ ia64/ - directory with info about Linux on Intel 64 bit architecture. infiniband/ - directory with documents concerning Linux InfiniBand support. -init.txt +admin-guide/init.rst - what to do when the kernel can't find the 1st process to run. -initrd.txt +admin-guide/initrd.rst - how to use the RAM disk as an initial/temporary root filesystem. input/ - info on Linux input device support. @@ -248,7 +248,7 @@ isapnp.txt - info on Linux ISA Plug & Play support. isdn/ - directory with info on the Linux ISDN support, and supported cards. -java.txt +admin-guide/java.rst - info on the in-kernel binary support for Java(tm). ja_JP/ - directory with Japanese translations of various documents @@ -256,11 +256,11 @@ kbuild/ - directory with info about the kernel build process. kdump/ - directory with mini HowTo on getting the crash dump code to work. -kernel-docs.txt +process/kernel-docs.rst - listing of various WWW + books that document kernel internals. kernel-documentation.rst - how to write and format reStructuredText kernel documentation -kernel-parameters.txt +admin-guide/kernel-parameters.rst - summary listing of command line / boot prompt args for the kernel. kernel-per-CPU-kthreads.txt - List of all per-CPU kthreads and how they introduce jitter. @@ -302,7 +302,7 @@ magic-number.txt - list of magic numbers used to mark/protect kernel data structures. mailbox.txt - How to write drivers for the common mailbox framework (IPC). -md.txt +admin-guide/md.rst - info on boot arguments for the multiple devices driver. media-framework.txt - info on media framework, its data structures, functions and usage. @@ -326,7 +326,7 @@ module-signing.txt - Kernel module signing for increased security when loading modules. mtd/ - directory with info about memory technology devices (flash) -mono.txt +admin-guide/mono.rst - how to execute Mono-based .NET binaries with the help of BINFMT_MISC. namespaces/ - directory with various information about namespaces @@ -340,7 +340,7 @@ nommu-mmap.txt - documentation about no-mmu memory mapping support. numastat.txt - info on how to read Numa policy hit/miss statistics in sysfs. -oops-tracing.txt +admin-guide/oops-tracing.rst - how to decode those nasty internal kernel error dump messages. padata.txt - An introduction to the "padata" parallel execution API @@ -378,7 +378,7 @@ ptp/ - directory with info on support for IEEE 1588 PTP clocks in Linux. pwm.txt - info on the pulse width modulation driver subsystem -ramoops.txt +admin-guide/ramoops.rst - documentation of the ramoops oops/panic logging module. rapidio/ - directory with info on RapidIO packet-based fabric interconnect @@ -406,7 +406,7 @@ security/ - directory that contains security-related info serial/ - directory with info on the low level serial API. -serial-console.txt +admin-guide/serial-console.rst - how to set up Linux with a serial line console as the default. sgi-ioc4.txt - description of the SGI IOC4 PCI (multi function) device. @@ -420,9 +420,9 @@ sparse.txt - info on how to obtain and use the sparse tool for typechecking. spi/ - overview of Linux kernel Serial Peripheral Interface (SPI) support. -stable_api_nonsense.txt +process/stable-api-nonsense.rst - info on why the kernel does not have a stable in-kernel api or abi. -stable_kernel_rules.txt +process/stable-kernel-rules.rst - rules and procedures for the -stable kernel releases. static-keys.txt - info on how static keys allow debug code in hotpaths via patching @@ -444,7 +444,7 @@ trace/ - directory with info on tracing technologies within linux unaligned-memory-access.txt - info on how to avoid arch breaking unaligned memory access in code. -unicode.txt +admin-guide/unicode.rst - info on the Unicode character/font mapping used in Linux. unshare.txt - description of the Linux unshare system call. @@ -466,7 +466,7 @@ vm/ - directory with info on the Linux vm code. vme_api.txt - file relating info on the VME bus API in linux -volatile-considered-harmful.txt +process/volatile-considered-harmful.rst - Why the "volatile" type class should not be used w1/ - directory with documents regarding the 1-wire (w1) subsystem. diff --git a/Documentation/ABI/README b/Documentation/ABI/README index 1fafc4b0753b..3121029dce21 100644 --- a/Documentation/ABI/README +++ b/Documentation/ABI/README @@ -84,4 +84,4 @@ stable: - Kernel-internal symbols. Do not rely on the presence, absence, location, or type of any kernel symbol, either in System.map files or the kernel binary - itself. See Documentation/stable_api_nonsense.txt. + itself. See Documentation/process/stable-api-nonsense.rst. diff --git a/Documentation/ABI/testing/sysfs-kernel-slab b/Documentation/ABI/testing/sysfs-kernel-slab index 91bd6ca5440f..2cc0a72b64be 100644 --- a/Documentation/ABI/testing/sysfs-kernel-slab +++ b/Documentation/ABI/testing/sysfs-kernel-slab @@ -347,7 +347,7 @@ Description: because of fragmentation, SLUB will retry with the minimum order possible depending on its characteristics. When debug_guardpage_minorder=N (N > 0) parameter is specified - (see Documentation/kernel-parameters.txt), the minimum possible + (see Documentation/admin-guide/kernel-parameters.rst), the minimum possible order is used and this sysfs entry can not be used to change the order at run time. diff --git a/Documentation/DocBook/kernel-hacking.tmpl b/Documentation/DocBook/kernel-hacking.tmpl index 2a272275c81b..da5c087462b1 100644 --- a/Documentation/DocBook/kernel-hacking.tmpl +++ b/Documentation/DocBook/kernel-hacking.tmpl @@ -1208,8 +1208,8 @@ static struct block_device_operations opt_fops = { - Finally, don't forget to read Documentation/SubmittingPatches - and possibly Documentation/SubmittingDrivers. + Finally, don't forget to read Documentation/process/submitting-patches.rst + and possibly Documentation/process/submitting-drivers.rst. diff --git a/Documentation/acpi/video_extension.txt b/Documentation/acpi/video_extension.txt index 78b32ac02466..79bf6a4921be 100644 --- a/Documentation/acpi/video_extension.txt +++ b/Documentation/acpi/video_extension.txt @@ -101,6 +101,6 @@ received a notification, it will set the backlight level accordingly. This does not affect the sending of event to user space, they are always sent to user space regardless of whether or not the video module controls the backlight level directly. This behaviour can be controlled through the brightness_switch_enabled -module parameter as documented in kernel-parameters.txt. It is recommended to +module parameter as documented in admin-guide/kernel-parameters.rst. It is recommended to disable this behaviour once a GUI environment starts up and wants to have full control of the backlight level. diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst index 05aad8543340..1b6dfb2b3adb 100644 --- a/Documentation/admin-guide/README.rst +++ b/Documentation/admin-guide/README.rst @@ -50,7 +50,8 @@ Documentation - There are various README files in the Documentation/ subdirectory: these typically contain kernel-specific installation notes for some drivers for example. See Documentation/00-INDEX for a list of what - is contained in each file. Please read the Changes file, as it + is contained in each file. Please read the + :ref:`Documentation/process/changes.rst ` file, as it contains information about the problems, which may result by upgrading your kernel. @@ -96,7 +97,7 @@ Installing the kernel source and 4.0.2 patches. Similarly, if you are running kernel version 4.0.2 and want to jump to 4.0.3, you must first reverse the 4.0.2 patch (that is, patch -R) **before** applying the 4.0.3 patch. You can read more on this in - :ref:`Documentation/applying-patches.txt `. + :ref:`Documentation/process/applying-patches.rst `. Alternatively, the script patch-kernel can be used to automate this process. It determines the current kernel version and applies any @@ -120,7 +121,7 @@ Software requirements Compiling and running the 4.x kernels requires up-to-date versions of various software packages. Consult - :ref:`Documentation/Changes ` for the minimum version numbers + :ref:`Documentation/process/changes.rst ` for the minimum version numbers required and how to get updates for these packages. Beware that using excessively old versions of these packages can cause indirect errors that are very difficult to track down, so don't assume that @@ -254,7 +255,7 @@ Compiling the kernel -------------------- - Make sure you have at least gcc 3.2 available. - For more information, refer to :ref:`Documentation/Changes `. + For more information, refer to :ref:`Documentation/process/changes.rst `. Please note that you can still run a.out user programs with this kernel. @@ -355,7 +356,7 @@ If something goes wrong help debugging the problem. The text above the dump is also important: it tells something about why the kernel dumped code (in the above example, it's due to a bad kernel pointer). More information - on making sense of the dump is in Documentation/oops-tracing.txt + on making sense of the dump is in Documentation/admin-guide/oops-tracing.rst - If you compiled the kernel with CONFIG_KALLSYMS you can send the dump as is, otherwise you will have to use the ``ksymoops`` program to make @@ -393,7 +394,7 @@ If something goes wrong If you for some reason cannot do the above (you have a pre-compiled kernel image or similar), telling me as much about your setup as - possible will help. Please read the :ref:`REPORTING-BUGS ` + possible will help. Please read the :ref:`admin-guide/reporting-bugs.rst ` document for details. - Alternatively, you can use gdb on a running kernel. (read-only; i.e. you diff --git a/Documentation/admin-guide/bad-memory.rst b/Documentation/admin-guide/bad-memory.rst index 017fc86430c3..a5c0e25e496f 100644 --- a/Documentation/admin-guide/bad-memory.rst +++ b/Documentation/admin-guide/bad-memory.rst @@ -33,7 +33,7 @@ memmap is already in the kernel and usable as kernel-parameter at boot-time. Its syntax is slightly strange and you may need to calculate the values by yourself! -Syntax to exclude a memory area (see kernel-parameters.txt for details):: +Syntax to exclude a memory area (see admin-guide/kernel-parameters.rst for details):: memmap=$
diff --git a/Documentation/admin-guide/binfmt-misc.rst b/Documentation/admin-guide/binfmt-misc.rst index 9c5ff8f260bf..97b0d7927078 100644 --- a/Documentation/admin-guide/binfmt-misc.rst +++ b/Documentation/admin-guide/binfmt-misc.rst @@ -124,7 +124,7 @@ A few examples (assumed you are in ``/proc/sys/fs/binfmt_misc``): echo ':DOSWin:M::MZ::/usr/local/bin/wine:' > register -For java support see Documentation/java.txt +For java support see Documentation/admin-guide/java.rst You can enable/disable binfmt_misc or one binary type by echoing 0 (to disable) @@ -140,7 +140,7 @@ Hints ----- If you want to pass special arguments to your interpreter, you can -write a wrapper script for it. See Documentation/java.txt for an +write a wrapper script for it. See Documentation/admin-guide/java.rst for an example. Your interpreter should NOT look in the PATH for the filename; the kernel diff --git a/Documentation/admin-guide/braille-console.rst b/Documentation/admin-guide/braille-console.rst index fa3702dc04ab..18e79337dcfd 100644 --- a/Documentation/admin-guide/braille-console.rst +++ b/Documentation/admin-guide/braille-console.rst @@ -3,7 +3,7 @@ Linux Braille Console To get early boot messages on a braille device (before userspace screen readers can start), you first need to compile the support for the usual serial -console (see :ref:`Documentation/serial-console.txt `), and +console (see :ref:`Documentation/admin-guide/serial-console.rst `), and for braille device (in :menuselection:`Device Drivers --> Accessibility support --> Console on braille device`). @@ -13,7 +13,7 @@ format is:: console=brl,serial_options... where ``serial_options...`` are the same as described in -:ref:`Documentation/serial-console.txt `. +:ref:`Documentation/admin-guide/serial-console.rst `. So for instance you can use ``console=brl,ttyS0`` if the braille device is connected to the first serial port, and ``console=brl,ttyS0,115200`` to override the baud rate to 115200, etc. @@ -31,7 +31,7 @@ parameter. For simplicity, only one braille console can be enabled, other uses of ``console=brl,...`` will be discarded. Also note that it does not interfere with the console selection mechanism described in -:ref:`Documentation/serial-console.txt `. +:ref:`Documentation/admin-guide/serial-console.rst `. For now, only the VisioBraille device is supported. diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst index a8ef794aadae..d35dd9fd1af0 100644 --- a/Documentation/admin-guide/bug-hunting.rst +++ b/Documentation/admin-guide/bug-hunting.rst @@ -15,7 +15,7 @@ give up. Report as much as you have found to the relevant maintainer. See MAINTAINERS for who that is for the subsystem you have worked on. Before you submit a bug report read -:ref:`Documentation/REPORTING-BUGS `. +:ref:`Documentation/admin-guide/reporting-bugs.rst `. Devices not appearing ===================== @@ -244,5 +244,6 @@ Once you have worked out a fix please submit it upstream. After all open source is about sharing what you do and don't you want to be recognised for your genius? -Please do read :ref:`Documentation/SubmittingPatches ` -though to help your code get accepted. +Please do read +ref:`Documentation/process/submitting-patches.rst ` though +to help your code get accepted. diff --git a/Documentation/admin-guide/devices.rst b/Documentation/admin-guide/devices.rst index b29555041531..89db341fba7a 100644 --- a/Documentation/admin-guide/devices.rst +++ b/Documentation/admin-guide/devices.rst @@ -10,7 +10,7 @@ The LaTeX version of this document is no longer maintained, nor is the document that used to reside at lanana.org. This version in the mainline Linux kernel is the master document. Updates shall be sent as patches to the kernel maintainers (see the -:ref:`Documentation/SubmittingPatches ` document). +:ref:`Documentation/process/submitting-patches.rst ` document). Specifically explore the sections titled "CHAR and MISC DRIVERS", and "BLOCK LAYER" in the MAINTAINERS file to find the right maintainers to involve for character and block devices. diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index b0804273b6e3..d2f2725f032e 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -815,7 +815,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted:: bits, and "f" is flow control ("r" for RTS or omit it). Default is "9600n8". - See Documentation/serial-console.txt for more + See Documentation/admin-guide/serial-console.rst for more information. See Documentation/networking/netconsole.txt for an alternative. @@ -2239,7 +2239,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted:: mce=option [X86-64] See Documentation/x86/x86_64/boot-options.txt md= [HW] RAID subsystems devices and level - See Documentation/md.txt. + See Documentation/admin-guide/md.rst. mdacon= [MDA] Format: , @@ -3322,7 +3322,7 @@ bytes respectively. Such letter suffixes can also be entirely omitted:: r128= [HW,DRM] raid= [HW,RAID] - See Documentation/md.txt. + See Documentation/admin-guide/md.rst. ramdisk_size= [RAM] Sizes of RAM disks in kilobytes See Documentation/blockdev/ramdisk.txt. diff --git a/Documentation/admin-guide/oops-tracing.rst b/Documentation/admin-guide/oops-tracing.rst index 3e25ea7349ee..13be8d7bcfe7 100644 --- a/Documentation/admin-guide/oops-tracing.rst +++ b/Documentation/admin-guide/oops-tracing.rst @@ -44,7 +44,7 @@ the disk is not available then you have three options : so won't help for 'early' oopses) (2) Boot with a serial console (see - :ref:`Documentation/serial-console.txt `), + :ref:`Documentation/admin-guide/serial-console.rst `), run a null modem to a second machine and capture the output there using your favourite communication program. Minicom works well. diff --git a/Documentation/admin-guide/ramoops.rst b/Documentation/admin-guide/ramoops.rst index 7eaf1e71c083..fe95c027e37c 100644 --- a/Documentation/admin-guide/ramoops.rst +++ b/Documentation/admin-guide/ramoops.rst @@ -61,7 +61,7 @@ Setting the ramoops parameters can be done in several different manners: mem=128M ramoops.mem_address=0x8000000 ramoops.ecc=1 B. Use Device Tree bindings, as described in - ``Documentation/device-tree/bindings/reserved-memory/ramoops.txt``. + ``Documentation/device-tree/bindings/reserved-memory/admin-guide/ramoops.rst``. For example:: reserved-memory { diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst index 05c53ac7fa76..0c0f2698ec5a 100644 --- a/Documentation/admin-guide/reporting-bugs.rst +++ b/Documentation/admin-guide/reporting-bugs.rst @@ -61,7 +61,7 @@ files to the get_maintainer.pl script:: If it is a security bug, please copy the Security Contact listed in the MAINTAINERS file. They can help coordinate bugfix and disclosure. See -:ref:`Documentation/SecurityBugs ` for more information. +:ref:`Documentation/admin-guide/security-bugs.rst ` for more information. If you can't figure out which subsystem caused the issue, you should file a bug in kernel.org bugzilla and send email to @@ -94,7 +94,7 @@ step-by-step instructions for how a user can trigger the bug. If the failure includes an "OOPS:", take a picture of the screen, capture a netconsole trace, or type the message from your screen into the bug -report. Please read "Documentation/oops-tracing.txt" before posting your +report. Please read "Documentation/admin-guide/oops-tracing.rst" before posting your bug report. This explains what you should do with the "Oops" information to make it useful to the recipient. @@ -120,7 +120,7 @@ summary from [1.]>" for easy identification by the developers:: [4.2.] Kernel .config file: [5.] Most recent kernel version which did not have the bug: [6.] Output of Oops.. message (if applicable) with symbolic information - resolved (see Documentation/oops-tracing.txt) + resolved (see Documentation/admin-guide/oops-tracing.rst) [7.] A small shell script or example program which triggers the problem (if possible) [8.] Environment diff --git a/Documentation/admin-guide/security-bugs.rst b/Documentation/admin-guide/security-bugs.rst index df795e22d08b..4f7414cad586 100644 --- a/Documentation/admin-guide/security-bugs.rst +++ b/Documentation/admin-guide/security-bugs.rst @@ -19,7 +19,7 @@ area maintainers to understand and fix the security vulnerability. As it is with any bug, the more information provided the easier it will be to diagnose and fix. Please review the procedure outlined in -REPORTING-BUGS if you are unclear about what information is helpful. +admin-guide/reporting-bugs.rst if you are unclear about what information is helpful. Any exploit code is very helpful and will not be released without consent from the reporter unless it has already been made public. diff --git a/Documentation/admin-guide/unicode.rst b/Documentation/admin-guide/unicode.rst index 012e8e895842..4e5c3df9d55f 100644 --- a/Documentation/admin-guide/unicode.rst +++ b/Documentation/admin-guide/unicode.rst @@ -7,7 +7,7 @@ This file is maintained by H. Peter Anvin as part of the Linux Assigned Names And Numbers Authority (LANANA) project. The current version can be found at: - http://www.lanana.org/docs/unicode/unicode.txt + http://www.lanana.org/docs/unicode/admin-guide/unicode.rst Introdution ----------- diff --git a/Documentation/arm/Booting b/Documentation/arm/Booting index 83c1df2fc758..259f00af3ab3 100644 --- a/Documentation/arm/Booting +++ b/Documentation/arm/Booting @@ -51,7 +51,7 @@ As an alternative, the boot loader can pass the relevant 'console=' option to the kernel via the tagged lists specifying the port, and serial format options as described in - Documentation/kernel-parameters.txt. + Documentation/admin-guide/kernel-parameters.rst. 3. Detect the machine type diff --git a/Documentation/atomic_ops.txt b/Documentation/atomic_ops.txt index c9d1cacb4395..7281bf939779 100644 --- a/Documentation/atomic_ops.txt +++ b/Documentation/atomic_ops.txt @@ -16,7 +16,7 @@ will fail. Something like the following should suffice: typedef struct { long counter; } atomic_long_t; Historically, counter has been declared volatile. This is now discouraged. -See Documentation/volatile-considered-harmful.txt for the complete rationale. +See Documentation/process/volatile-considered-harmful.rst for the complete rationale. local_t is very similar to atomic_t. If the counter is per CPU and only updated by one CPU, local_t is probably more appropriate. Please see diff --git a/Documentation/blockdev/ramdisk.txt b/Documentation/blockdev/ramdisk.txt index fe2ef978d85a..501e12e0323e 100644 --- a/Documentation/blockdev/ramdisk.txt +++ b/Documentation/blockdev/ramdisk.txt @@ -14,7 +14,7 @@ Contents: The RAM disk driver is a way to use main system memory as a block device. It is required for initrd, an initial filesystem used if you need to load modules -in order to access the root filesystem (see Documentation/initrd.txt). It can +in order to access the root filesystem (see Documentation/admin-guide/initrd.rst). It can also be used for a temporary filesystem for crypto work, since the contents are erased on reboot. diff --git a/Documentation/cgroup-v1/00-INDEX b/Documentation/cgroup-v1/00-INDEX index 106885ad670d..13e0c85e7b35 100644 --- a/Documentation/cgroup-v1/00-INDEX +++ b/Documentation/cgroup-v1/00-INDEX @@ -8,7 +8,7 @@ cpuacct.txt - CPU Accounting Controller; account CPU usage for groups of tasks. cpusets.txt - documents the cpusets feature; assign CPUs and Mem to a set of tasks. -devices.txt +admin-guide/devices.rst - Device Whitelist Controller; description, interface and security. freezer-subsystem.txt - checkpointing; rationale to not use signals, interface. diff --git a/Documentation/devicetree/bindings/rtc/maxim,ds3231.txt b/Documentation/devicetree/bindings/rtc/maxim,ds3231.txt index ddef330d2709..1ad4c1c2b3b3 100644 --- a/Documentation/devicetree/bindings/rtc/maxim,ds3231.txt +++ b/Documentation/devicetree/bindings/rtc/maxim,ds3231.txt @@ -1,7 +1,7 @@ * Maxim DS3231 Real Time Clock Required properties: -see: Documentation/devicetree/bindings/i2c/trivial-devices.txt +see: Documentation/devicetree/bindings/i2c/trivial-admin-guide/devices.rst Optional property: - #clock-cells: Should be 1. diff --git a/Documentation/devicetree/bindings/rtc/pcf8563.txt b/Documentation/devicetree/bindings/rtc/pcf8563.txt index 72f6d2c9665e..086c998c5561 100644 --- a/Documentation/devicetree/bindings/rtc/pcf8563.txt +++ b/Documentation/devicetree/bindings/rtc/pcf8563.txt @@ -3,7 +3,7 @@ Philips PCF8563/Epson RTC8564 Real Time Clock Required properties: -see: Documentation/devicetree/bindings/i2c/trivial-devices.txt +see: Documentation/devicetree/bindings/i2c/trivial-admin-guide/devices.rst Optional property: - #clock-cells: Should be 0. diff --git a/Documentation/devicetree/bindings/submitting-patches.txt b/Documentation/devicetree/bindings/submitting-patches.txt index 7d44eae7ab0b..274058c583dd 100644 --- a/Documentation/devicetree/bindings/submitting-patches.txt +++ b/Documentation/devicetree/bindings/submitting-patches.txt @@ -3,7 +3,7 @@ I. For patch submitters - 0) Normal patch submission rules from Documentation/SubmittingPatches + 0) Normal patch submission rules from Documentation/process/submitting-patches.rst applies. 1) The Documentation/ portion of the patch should be a separate patch. diff --git a/Documentation/filesystems/locks.txt b/Documentation/filesystems/locks.txt index 2cf81082581d..5368690f412e 100644 --- a/Documentation/filesystems/locks.txt +++ b/Documentation/filesystems/locks.txt @@ -19,7 +19,7 @@ forever. This should not cause problems for anybody, since everybody using a 2.1.x kernel should have updated their C library to a suitable version -anyway (see the file "Documentation/Changes".) +anyway (see the file "Documentation/process/changes.rst".) 1.2 Allow Mixed Locks Again --------------------------- diff --git a/Documentation/filesystems/nfs/nfsroot.txt b/Documentation/filesystems/nfs/nfsroot.txt index 0b2883b17d4c..5efae00f6c7f 100644 --- a/Documentation/filesystems/nfs/nfsroot.txt +++ b/Documentation/filesystems/nfs/nfsroot.txt @@ -11,7 +11,7 @@ Updated 2006 by Horms In order to use a diskless system, such as an X-terminal or printer server for example, it is necessary for the root filesystem to be present on a non-disk device. This may be an initramfs (see Documentation/filesystems/ -ramfs-rootfs-initramfs.txt), a ramdisk (see Documentation/initrd.txt) or a +ramfs-rootfs-initramfs.txt), a ramdisk (see Documentation/admin-guide/initrd.rst) or a filesystem mounted via NFS. The following text describes on how to use NFS for the root filesystem. For the rest of this text 'client' means the diskless system, and 'server' means the NFS server. @@ -284,7 +284,7 @@ They depend on various facilities being available: "kernel ". The nfsroot parameters are passed to the kernel by adding them to the "append" line. It is common to use serial console in conjunction with pxeliunx, - see Documentation/serial-console.txt for more information. + see Documentation/admin-guide/serial-console.rst for more information. For more information on isolinux, including how to create bootdisks for prebuilt kernels, see http://syslinux.zytor.com/ diff --git a/Documentation/frv/booting.txt b/Documentation/frv/booting.txt index 9bdf4b46e741..cd9dc1dfb144 100644 --- a/Documentation/frv/booting.txt +++ b/Documentation/frv/booting.txt @@ -119,7 +119,7 @@ separated by spaces: 253:0 Device with major 253 and minor 0 Authoritative information can be found in - "Documentation/kernel-parameters.txt". + "Documentation/admin-guide/kernel-parameters.rst". (*) rw diff --git a/Documentation/hwmon/submitting-patches b/Documentation/hwmon/submitting-patches index 57f60307accc..f88221b46153 100644 --- a/Documentation/hwmon/submitting-patches +++ b/Documentation/hwmon/submitting-patches @@ -10,10 +10,10 @@ increase the chances of your change being accepted. ---------- * It should be unnecessary to mention, but please read and follow - Documentation/SubmitChecklist - Documentation/SubmittingDrivers - Documentation/SubmittingPatches - Documentation/CodingStyle + Documentation/process/submit-checklist.rst + Documentation/process/submitting-drivers.rst + Documentation/process/submitting-patches.rst + Documentation/process/coding-style.rst * Please run your patch through 'checkpatch --strict'. There should be no errors, no warnings, and few if any check messages. If there are any diff --git a/Documentation/isdn/README b/Documentation/isdn/README index cfb1884342ee..32d4e80c2c03 100644 --- a/Documentation/isdn/README +++ b/Documentation/isdn/README @@ -332,7 +332,7 @@ README for the ISDN-subsystem 4. Device-inodes The major and minor numbers and their names are described in - Documentation/devices.txt. The major numbers are: + Documentation/admin-guide/devices.rst. The major numbers are: 43 for the ISDN-tty's. 44 for the ISDN-callout-tty's. diff --git a/Documentation/ja_JP/HOWTO b/Documentation/ja_JP/HOWTO index 581c14bdd7be..b03fc8047f03 100644 --- a/Documentation/ja_JP/HOWTO +++ b/Documentation/ja_JP/HOWTO @@ -127,15 +127,15 @@ linux-api@ver.kernel.org に送ることを勧めます。 小限のレベルで必要な数々のソフトウェアパッケージの一覧を示してい ます。 - Documentation/CodingStyle + Documentation/process/coding-style.rst これは Linux カーネルのコーディングスタイルと背景にある理由を記述 しています。全ての新しいコードはこのドキュメントにあるガイドライン に従っていることを期待されています。大部分のメンテナはこれらのルー ルに従っているものだけを受け付け、多くの人は正しいスタイルのコード だけをレビューします。 - Documentation/SubmittingPatches - Documentation/SubmittingDrivers + Documentation/process/submitting-patches.rst + Documentation/process/submitting-drivers.rst これらのファイルには、どうやってうまくパッチを作って投稿するかに ついて非常に詳しく書かれており、以下を含みます(これだけに限らない けれども) @@ -153,7 +153,7 @@ linux-api@ver.kernel.org に送ることを勧めます。 "Linux kernel patch submission format" http://linux.yyz.us/patch-format.html - Documentation/stable_api_nonsense.txt + Documentation/process/stable-api-nonsense.rst このファイルはカーネルの中に不変のAPIを持たないことにした意識的な 決断の背景にある理由について書かれています。以下のようなことを含 んでいます- @@ -164,29 +164,29 @@ linux-api@ver.kernel.org に送ることを勧めます。 このドキュメントは Linux 開発の思想を理解するのに非常に重要です。 そして、他のOSでの開発者が Linux に移る時にとても重要です。 - Documentation/SecurityBugs + Documentation/admin-guide/security-bugs.rst もし Linux カーネルでセキュリティ問題を発見したように思ったら、こ のドキュメントのステップに従ってカーネル開発者に連絡し、問題解決を 支援してください。 - Documentation/ManagementStyle + Documentation/process/management-style.rst このドキュメントは Linux カーネルのメンテナ達がどう行動するか、 彼らの手法の背景にある共有されている精神について記述しています。こ れはカーネル開発の初心者なら（もしくは、単に興味があるだけの人でも） 重要です。なぜならこのドキュメントは、カーネルメンテナ達の独特な 行動についての多くの誤解や混乱を解消するからです。 - Documentation/stable_kernel_rules.txt + Documentation/process/stable-kernel-rules.rst このファイルはどのように stable カーネルのリリースが行われるかのルー ルが記述されています。そしてこれらのリリースの中のどこかで変更を取 り入れてもらいたい場合に何をすれば良いかが示されています。 - Documentation/kernel-docs.txt + Documentation/process/kernel-docs.rst 　　カーネル開発に付随する外部ドキュメントのリストです。もしあなたが 探しているものがカーネル内のドキュメントでみつからなかった場合、 このリストをあたってみてください。 - Documentation/applying-patches.txt + Documentation/process/applying-patches.rst パッチとはなにか、パッチをどうやって様々なカーネルの開発ブランチに 適用するのかについて正確に記述した良い入門書です。 @@ -314,7 +314,7 @@ Andrew Morton が Linux-kernel メーリングリストにカーネルリリー た問題がなければもう少し長くなることもあります。セキュリティ関連の問題 の場合はこれに対してだいたいの場合、すぐにリリースがされます。 -カーネルツリーに入っている、Documentation/stable_kernel_rules.txt ファ +カーネルツリーに入っている、Documentation/process/stable-kernel-rules.rst ファ イルにはどのような種類の変更が -stable ツリーに受け入れ可能か、またリ リースプロセスがどう動くかが記述されています。 @@ -372,7 +372,7 @@ bugzilla.kernel.org は Linux カーネル開発者がカーネルのバグを 場所です。ユーザは見つけたバグの全てをこのツールで報告すべきです。 どう kernel bugzilla を使うかの詳細は、以下を参照してください- http://bugzilla.kernel.org/page.cgi?id=faq.html -メインカーネルソースディレクトリにあるファイル REPORTING-BUGS はカーネ +メインカーネルソースディレクトリにあるファイル admin-guide/reporting-bugs.rst はカーネ ルバグらしいものについてどうレポートするかの良いテンプレートであり、問 題の追跡を助けるためにカーネル開発者にとってどんな情報が必要なのかの詳 細が書かれています。 @@ -438,7 +438,7 @@ MAINTAINERS ファイルにリストがありますので参照してくださ メールの先頭でなく、各引用行の間にあなたの言いたいことを追加するべきで す。 -もしパッチをメールに付ける場合は、Documentation/SubmittingPatches に提 +もしパッチをメールに付ける場合は、Documentation/process/submitting-patches.rst に提 示されているように、それは プレーンな可読テキストにすることを忘れない ようにしましょう。カーネル開発者は 添付や圧縮したパッチを扱いたがりま せん- diff --git a/Documentation/ja_JP/SubmitChecklist b/Documentation/ja_JP/SubmitChecklist index cb5507b1ac81..60c7c35ac517 100644 --- a/Documentation/ja_JP/SubmitChecklist +++ b/Documentation/ja_JP/SubmitChecklist @@ -1,5 +1,5 @@ NOTE: -This is a version of Documentation/SubmitChecklist into Japanese. +This is a version of Documentation/process/submit-checklist.rst into Japanese. This document is maintained by Takenori Nagano and the JF Project team . If you find any difference between this document and the original file @@ -14,7 +14,7 @@ to update the original English file first. Last Updated: 2008/07/14 ================================== これは、 -linux-2.6.26/Documentation/SubmitChecklist の和訳です。 +linux-2.6.26/Documentation/process/submit-checklist.rst の和訳です。 翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > 翻訳日： 2008/07/14 @@ -27,7 +27,7 @@ Linux カーネルパッチ投稿者向けチェックリスト ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 本書では、パッチをより素早く取り込んでもらいたい開発者が実践すべき基本的な事柄 -をいくつか紹介します。ここにある全ての事柄は、Documentation/SubmittingPatches +をいくつか紹介します。ここにある全ての事柄は、Documentation/process/submitting-patches.rst などのLinuxカーネルパッチ投稿に際しての心得を補足するものです。 1: 妥当なCONFIGオプションや変更されたCONFIGオプション、つまり =y, =m, =n @@ -84,7 +84,7 @@ Linux カーネルパッチ投稿者向けチェックリスト 必ずドキュメントを追加してください。 17: 新しいブートパラメータを追加した場合には、 - 必ずDocumentation/kernel-parameters.txt に説明を追加してください。 + 必ずDocumentation/admin-guide/kernel-parameters.rst に説明を追加してください。 18: 新しくmoduleにパラメータを追加した場合には、MODULE_PARM_DESC()を 利用して必ずその説明を記述してください。 diff --git a/Documentation/ja_JP/SubmittingPatches b/Documentation/ja_JP/SubmittingPatches index 5d6ae639bfa0..02139656463e 100644 --- a/Documentation/ja_JP/SubmittingPatches +++ b/Documentation/ja_JP/SubmittingPatches @@ -1,5 +1,5 @@ NOTE: -This is a version of Documentation/SubmittingPatches into Japanese. +This is a version of Documentation/process/submitting-patches.rst into Japanese. This document is maintained by Keiichi KII and the JF Project team . If you find any difference between this document and the original file @@ -15,7 +15,7 @@ Last Updated: 2011/06/09 ================================== これは、 -linux-2.6.39/Documentation/SubmittingPatches の和訳 +linux-2.6.39/Documentation/process/submitting-patches.rst の和訳 です。 翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > 翻訳日： 2011/06/09 @@ -34,9 +34,9 @@ Linux カーネルに変更を加えたいと思っている個人又は会社 おじけづかせることもあります。この文章はあなたの変更を大いに受け入れ てもらえやすくする提案を集めたものです。 -コードを投稿する前に、Documentation/SubmitChecklist の項目リストに目 +コードを投稿する前に、Documentation/process/submit-checklist.rst の項目リストに目 を通してチェックしてください。もしあなたがドライバーを投稿しようとし -ているなら、Documentation/SubmittingDrivers にも目を通してください。 +ているなら、Documentation/process/submitting-drivers.rst にも目を通してください。 -------------------------------------------- セクション1 パッチの作り方と送り方 @@ -148,7 +148,7 @@ http://savannah.nongnu.org/projects/quilt 4) パッチのスタイルチェック あなたのパッチが基本的な( Linux カーネルの)コーディングスタイルに違反し -ていないかをチェックして下さい。その詳細を Documentation/CodingStyle で +ていないかをチェックして下さい。その詳細を Documentation/process/coding-style.rst で 見つけることができます。コーディングスタイルの違反はレビューする人の 時間を無駄にするだけなので、恐らくあなたのパッチは読まれることすらなく 拒否されるでしょう。 @@ -246,7 +246,7 @@ MIME 形式の添付ファイルは Linus に手間を取らせることにな あれば、誰かが MIME 形式のパッチを再送するよう求めるかもしれません。 余計な変更を加えずにあなたのパッチを送信するための電子メールクライアントの設定 -のヒントについては Documentation/email-clients.txt を参照してください。 +のヒントについては Documentation/process/email-clients.rst を参照してください。 8) 電子メールのサイズ @@ -609,7 +609,7 @@ diffstat の結果を生成するために「 git diff -M --stat --summary 」 し例外を適用するには、本当に妥当な理由が不可欠です。あなたは恐らくこの セクションを Linus のコンピュータ・サイエンス101と呼ぶでしょう。 -1) Documentation/CodingStyleを参照 +1) Documentation/process/coding-style.rstを参照 言うまでもなく、あなたのコードがこのコーディングスタイルからあまりに も逸脱していると、レビューやコメントなしに受け取ってもらえないかもし @@ -704,8 +704,8 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! -Kernel Documentation/CodingStyle: - +Kernel Documentation/process/coding-style.rst: + Linus Torvalds's mail on the canonical patch format: diff --git a/Documentation/ja_JP/stable_api_nonsense.txt b/Documentation/ja_JP/stable_api_nonsense.txt index 7653b5cbfed2..a3b40a4bdcfd 100644 --- a/Documentation/ja_JP/stable_api_nonsense.txt +++ b/Documentation/ja_JP/stable_api_nonsense.txt @@ -1,5 +1,5 @@ NOTE: -This is a version of Documentation/stable_api_nonsense.txt into Japanese. +This is a version of Documentation/process/stable-api-nonsense.rst into Japanese. This document is maintained by IKEDA, Munehiro and the JF Project team . If you find any difference between this document and the original file @@ -14,7 +14,7 @@ to update the original English file first. Last Updated: 2007/07/18 ================================== これは、 -linux-2.6.22-rc4/Documentation/stable_api_nonsense.txt の和訳 +linux-2.6.22-rc4/Documentation/process/stable-api-nonsense.rst の和訳 です。 翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > 翻訳日 ： 2007/06/11 diff --git a/Documentation/ja_JP/stable_kernel_rules.txt b/Documentation/ja_JP/stable_kernel_rules.txt index 9dbda9b5d21e..f9249aecba64 100644 --- a/Documentation/ja_JP/stable_kernel_rules.txt +++ b/Documentation/ja_JP/stable_kernel_rules.txt @@ -1,5 +1,5 @@ NOTE: -This is Japanese translated version of "Documentation/stable_kernel_rules.txt". +This is Japanese translated version of "Documentation/process/stable-kernel-rules.rst". This one is maintained by Tsugikazu Shibata and JF Project team . If you find difference with original file or problem in translation, @@ -12,7 +12,7 @@ file at first. ================================== これは、 -linux-2.6.29/Documentation/stable_kernel_rules.txt +linux-2.6.29/Documentation/process/stable-kernel-rules.rst の和訳です。 翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ > @@ -43,7 +43,7 @@ linux-2.6.29/Documentation/stable_kernel_rules.txt "理論的には競合状態になる"ようなものは不可。 - いかなる些細な修正も含めることはできない。(スペルの修正、空白のクリー ンアップなど) - - Documentation/SubmittingPatches の規則に従ったものでなければならない。 + - Documentation/process/submitting-patches.rst の規則に従ったものでなければならない。 - パッチ自体か同等の修正が Linus のツリーに既に存在しなければならない。 　 Linus のツリーでのコミットID を -stable へのパッチ投稿の際に引用す ること。 diff --git a/Documentation/kernel-per-CPU-kthreads.txt b/Documentation/kernel-per-CPU-kthreads.txt index bbc3a8b8cff4..df31e30b6a02 100644 --- a/Documentation/kernel-per-CPU-kthreads.txt +++ b/Documentation/kernel-per-CPU-kthreads.txt @@ -264,7 +264,7 @@ To reduce its OS jitter, do at least one of the following: kthreads from being created in the first place. 2. Boot with "nosoftlockup=0", which will also prevent these kthreads from being created. Other related watchdog and softlockup boot - parameters may be found in Documentation/kernel-parameters.txt + parameters may be found in Documentation/admin-guide/kernel-parameters.rst and Documentation/watchdog/watchdog-parameters.txt. 3. Echo a zero to /proc/sys/kernel/watchdog to disable the watchdog timer. diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index 9a3e65924d54..025252731af5 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -1,5 +1,5 @@ NOTE: -This is a version of Documentation/HOWTO translated into korean +This is a version of Documentation/process/howto.rst translated into korean This document is maintained by Minchan Kim If you find any difference between this document and the original file or a problem with the translation, please contact the maintainer of this file. @@ -11,7 +11,7 @@ try to update the original English file first. ================================== 이 문서는 -Documentation/HOWTO +Documentation/process/howto.rst 의 한글 번역입니다. 역자： 김민찬 @@ -98,18 +98,18 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. 빌드하기 위해 필요한 것을 설명한다. 커널에 입문하는 사람들은 여기서 시작해야 한다. - Documentation/Changes + Documentation/process/changes.rst 이 파일은 커널을 성공적으로 빌드하고 실행시키기 위해 필요한 다양한 소프트웨어 패키지들의 최소 버젼을 나열한다. - Documentation/CodingStyle + Documentation/process/coding-style.rst 이 문서는 리눅스 커널 코딩 스타일과 그렇게 한 몇몇 이유를 설명한다. 모든 새로운 코드는 이 문서에 가이드라인들을 따라야 한다. 대부분의 메인테이너들은 이 규칙을 따르는 패치들만을 받아들일 것이고 많은 사람들이 그 패치가 올바른 스타일일 경우만 코드를 검토할 것이다. - Documentation/SubmittingPatches - Documentation/SubmittingDrivers + Documentation/process/submitting-patches.rst + Documentation/process/submitting-drivers.rst 이 파일들은 성공적으로 패치를 만들고 보내는 법을 다음의 내용들로 굉장히 상세히 설명하고 있다(그러나 다음으로 한정되진 않는다). - Email 내용들 @@ -126,7 +126,7 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. "Linux kernel patch submission format" http://linux.yyz.us/patch-format.html - Documentation/stable_api_nonsense.txt + Documentation/process/stable-api-nonsense.rst 이 문서는 의도적으로 커널이 불변하는 API를 갖지 않도록 결정한 이유를 설명하며 다음과 같은 것들을 포함한다. - 서브시스템 shim-layer(호환성을 위해?) @@ -136,12 +136,12 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. 리눅스로 전향하는 사람들에게는 매우 중요하다. - Documentation/SecurityBugs + Documentation/admin-guide/security-bugs.rst 여러분들이 리눅스 커널의 보안 문제를 발견했다고 생각한다면 이 문서에 나온 단계에 따라서 커널 개발자들에게 알리고 그 문제를 해결할 수 있도록 도와 달라. - Documentation/ManagementStyle + Documentation/process/management-style.rst 이 문서는 리눅스 커널 메인테이너들이 그들의 방법론에 녹아 있는 정신을 어떻게 공유하고 운영하는지를 설명한다. 이것은 커널 개발에 입문하는 모든 사람들(또는 커널 개발에 작은 호기심이라도 있는 사람들)이 @@ -149,17 +149,17 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. 독특한 행동에 관하여 흔히 있는 오해들과 혼란들을 해소하고 있기 때문이다. - Documentation/stable_kernel_rules.txt + Documentation/process/stable-kernel-rules.rst 이 문서는 안정적인 커널 배포가 이루어지는 규칙을 설명하고 있으며 여러분들이 이러한 배포들 중 하나에 변경을 하길 원한다면 무엇을 해야 하는지를 설명한다. - Documentation/kernel-docs.txt + Documentation/process/kernel-docs.rst 커널 개발에 관계된 외부 문서의 리스트이다. 커널 내의 포함된 문서들 중에 여러분이 찾고 싶은 문서를 발견하지 못할 경우 이 리스트를 살펴보라. - Documentation/applying-patches.txt + Documentation/process/applying-patches.rst 패치가 무엇이며 그것을 커널의 다른 개발 브랜치들에 어떻게 적용하는지에 관하여 자세히 설명하고 있는 좋은 입문서이다. @@ -276,7 +276,7 @@ Andrew Morton의 글이 있다. 4.x.y는 "stable" 팀에 의해 관리되며 거의 매번 격주로 배포된다. -커널 트리 문서들 내에 Documentation/stable_kernel_rules.txt 파일은 어떤 +커널 트리 문서들 내에 Documentation/process/stable-kernel-rules.rst 파일은 어떤 종류의 변경들이 -stable 트리로 들어왔는지와 배포 프로세스가 어떻게 진행되는지를 설명한다. @@ -328,7 +328,7 @@ bugzilla.kernel.org는 리눅스 커널 개발자들이 커널의 버그를 추 kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라. http://test.kernel.org/bugzilla/faq.html -메인 커널 소스 디렉토리에 있는 REPORTING-BUGS 파일은 커널 버그라고 생각되는 +메인 커널 소스 디렉토리에 있는 admin-guide/reporting-bugs.rst 파일은 커널 버그라고 생각되는 것을 보고하는 방법에 관한 좋은 템플릿이며 문제를 추적하기 위해서 커널 개발자들이 필요로 하는 정보가 무엇들인지를 상세히 설명하고 있다. @@ -391,7 +391,7 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메 "John 커널해커는 작성했다...."를 유지하며 여러분들의 의견을 그 메일의 윗부분에 작성하지 말고 각 인용한 단락들 사이에 넣어라. -여러분들이 패치들을 메일에 넣는다면 그것들은 Documentation/SubmittingPatches에 +여러분들이 패치들을 메일에 넣는다면 그것들은 Documentation/process/submitting-patches.rst에 나와있는데로 명백히(plain) 읽을 수 있는 텍스트여야 한다. 커널 개발자들은 첨부파일이나 압축된 패치들을 원하지 않는다. 그들은 여러분들의 패치의 각 라인 단위로 코멘트를 하길 원하며 압축하거나 첨부하지 않고 보내는 것이 diff --git a/Documentation/ko_KR/stable_api_nonsense.txt b/Documentation/ko_KR/stable_api_nonsense.txt index 3ba10b11d556..4d93af1efd61 100644 --- a/Documentation/ko_KR/stable_api_nonsense.txt +++ b/Documentation/ko_KR/stable_api_nonsense.txt @@ -1,5 +1,5 @@ NOTE: -This is a version of Documentation/stable_api_nonsense.txt translated +This is a version of Documentation/process/stable-api-nonsense.rst translated into korean This document is maintained by Minchan Kim If you find any difference between this document and the original file or @@ -12,7 +12,7 @@ try to update the original English file first. ================================== 이 문서는 -Documentation/stable_api_nonsense.txt +Documentation/process/stable-api-nonsense.rst 의 한글 번역입니다. 역자： 김민찬 diff --git a/Documentation/lockup-watchdogs.txt b/Documentation/lockup-watchdogs.txt index 4a6e33e1af61..c8b8378513d6 100644 --- a/Documentation/lockup-watchdogs.txt +++ b/Documentation/lockup-watchdogs.txt @@ -11,7 +11,7 @@ details), without giving other tasks a chance to run. The current stack trace is displayed upon detection and, by default, the system will stay locked up. Alternatively, the kernel can be configured to panic; a sysctl, "kernel.softlockup_panic", a kernel parameter, -"softlockup_panic" (see "Documentation/kernel-parameters.txt" for +"softlockup_panic" (see "Documentation/admin-guide/kernel-parameters.rst" for details), and a compile option, "BOOTPARAM_SOFTLOCKUP_PANIC", are provided for this. @@ -23,7 +23,7 @@ upon detection and the system will stay locked up unless the default behavior is changed, which can be done through a sysctl, 'hardlockup_panic', a compile time knob, "BOOTPARAM_HARDLOCKUP_PANIC", and a kernel parameter, "nmi_watchdog" -(see "Documentation/kernel-parameters.txt" for details). +(see "Documentation/admin-guide/kernel-parameters.rst" for details). The panic option can be used in combination with panic_timeout (this timeout is set through the confusingly named "kernel.panic" sysctl), diff --git a/Documentation/m68k/kernel-options.txt b/Documentation/m68k/kernel-options.txt index eaf32a1fd0b1..79d21246c75a 100644 --- a/Documentation/m68k/kernel-options.txt +++ b/Documentation/m68k/kernel-options.txt @@ -139,7 +139,7 @@ follows: PARTUUID=00112233-4455-6677-8899-AABBCCDDEEFF/PARTNROFF=-2 Authoritative information can be found in -"Documentation/kernel-parameters.txt". +"Documentation/admin-guide/kernel-parameters.rst". 2.2) ro, rw diff --git a/Documentation/media/uapi/v4l/diff-v4l.rst b/Documentation/media/uapi/v4l/diff-v4l.rst index 76b2ecab8657..8209eeb63dd2 100644 --- a/Documentation/media/uapi/v4l/diff-v4l.rst +++ b/Documentation/media/uapi/v4l/diff-v4l.rst @@ -648,12 +648,12 @@ microcode programming. A new interface for MPEG compression and playback devices is documented in :ref:`extended-controls`. .. [#f1] - According to Documentation/devices.txt these should be symbolic links + According to Documentation/admin-guide/devices.rst these should be symbolic links to ``/dev/video0``. Note the original bttv interface is not compatible with V4L or V4L2. .. [#f2] - According to ``Documentation/devices.txt`` a symbolic link to + According to ``Documentation/admin-guide/devices.rst`` a symbolic link to ``/dev/radio0``. .. [#f3] diff --git a/Documentation/media/v4l-drivers/bttv.rst b/Documentation/media/v4l-drivers/bttv.rst index 7abc1c9a261b..bc63b12efafd 100644 --- a/Documentation/media/v4l-drivers/bttv.rst +++ b/Documentation/media/v4l-drivers/bttv.rst @@ -304,10 +304,10 @@ bug. It is very helpful if you can tell where exactly it broke With a hard freeze you probably doesn't find anything in the logfiles. The only way to capture any kernel messages is to hook up a serial console and let some terminal application log the messages. /me uses -screen. See Documentation/serial-console.txt for details on setting +screen. See Documentation/admin-guide/serial-console.rst for details on setting up a serial console. -Read Documentation/oops-tracing.txt to learn how to get any useful +Read Documentation/admin-guide/oops-tracing.rst to learn how to get any useful information out of a register+stack dump printed by the kernel on protection faults (so-called "kernel oops"). diff --git a/Documentation/memory-hotplug.txt b/Documentation/memory-hotplug.txt index 0d7cb955aa01..5de846d3ecc0 100644 --- a/Documentation/memory-hotplug.txt +++ b/Documentation/memory-hotplug.txt @@ -324,7 +324,7 @@ guarantee that the memory block contains only migratable pages. Now, a boot option for making a memory block which consists of migratable pages is supported. By specifying "kernelcore=" or "movablecore=" boot option, you can create ZONE_MOVABLE...a zone which is just used for movable pages. -(See also Documentation/kernel-parameters.txt) +(See also Documentation/admin-guide/kernel-parameters.rst) Assume the system has "TOTAL" amount of memory at boot time, this boot option creates ZONE_MOVABLE as following. diff --git a/Documentation/networking/netconsole.txt b/Documentation/networking/netconsole.txt index 30409a36e95d..296ea00fd3eb 100644 --- a/Documentation/networking/netconsole.txt +++ b/Documentation/networking/netconsole.txt @@ -200,7 +200,7 @@ priority messages to the console. You can change this at runtime using: or by specifying "debug" on the kernel command line at boot, to send all kernel messages to the console. A specific value for this parameter can also be set using the "loglevel" kernel boot option. See the -dmesg(8) man page and Documentation/kernel-parameters.txt for details. +dmesg(8) man page and Documentation/admin-guide/kernel-parameters.rst for details. Netconsole was designed to be as instantaneous as possible, to enable the logging of even the most critical kernel bugs. It works diff --git a/Documentation/networking/netdev-FAQ.txt b/Documentation/networking/netdev-FAQ.txt index 0fe1c6e0dbcd..cdebc5c8705f 100644 --- a/Documentation/networking/netdev-FAQ.txt +++ b/Documentation/networking/netdev-FAQ.txt @@ -136,14 +136,14 @@ A: Normally Greg Kroah-Hartman collects stable commits himself, but Q: I see a network patch and I think it should be backported to stable. Should I request it via "stable@vger.kernel.org" like the references in - the kernel's Documentation/stable_kernel_rules.txt file say? + the kernel's Documentation/process/stable-kernel-rules.rst file say? A: No, not for networking. Check the stable queues as per above 1st to see if it is already queued. If not, then send a mail to netdev, listing the upstream commit ID and why you think it should be a stable candidate. Before you jump to go do the above, do note that the normal stable rules - in Documentation/stable_kernel_rules.txt still apply. So you need to + in Documentation/process/stable-kernel-rules.rst still apply. So you need to explicitly indicate why it is a critical fix and exactly what users are impacted. In addition, you need to convince yourself that you _really_ think it has been overlooked, vs. having been considered and rejected. @@ -165,7 +165,7 @@ A: No. See above answer. In short, if you think it really belongs in If you think there is some valid information relating to it being in stable that does _not_ belong in the commit log, then use the three - dash marker line as described in Documentation/SubmittingPatches to + dash marker line as described in Documentation/process/submitting-patches.rst to temporarily embed that information into the patch that you send. Q: Someone said that the comment style and coding convention is different @@ -220,5 +220,5 @@ A: Attention to detail. Re-read your own work as if you were the If it is your first patch, mail it to yourself so you can test apply it to an unpatched tree to confirm infrastructure didn't mangle it. - Finally, go back and read Documentation/SubmittingPatches to be + Finally, go back and read Documentation/process/submitting-patches.rst to be sure you are not repeating some common mistake documented there. diff --git a/Documentation/networking/vortex.txt b/Documentation/networking/vortex.txt index 97282da82b75..ad3dead052a4 100644 --- a/Documentation/networking/vortex.txt +++ b/Documentation/networking/vortex.txt @@ -364,7 +364,7 @@ steps you should take: - The contents of your report will vary a lot depending upon the problem. If it's a kernel crash then you should refer to the - REPORTING-BUGS file. + admin-guide/reporting-bugs.rst file. But for most problems it is useful to provide the following: diff --git a/Documentation/power/00-INDEX b/Documentation/power/00-INDEX index ad04cc8097ed..7cb6085839f3 100644 --- a/Documentation/power/00-INDEX +++ b/Documentation/power/00-INDEX @@ -6,7 +6,7 @@ basic-pm-debugging.txt - Debugging suspend and resume charger-manager.txt - Battery charger management. -devices.txt +admin-guide/devices.rst - How drivers interact with system-wide power management drivers-testing.txt - Testing suspend and resume support in device drivers diff --git a/Documentation/power/pci.txt b/Documentation/power/pci.txt index 44558882aa60..85c746cbab2c 100644 --- a/Documentation/power/pci.txt +++ b/Documentation/power/pci.txt @@ -8,7 +8,7 @@ management. Based on previous work by Patrick Mochel This document only covers the aspects of power management specific to PCI devices. For general description of the kernel's interfaces related to device -power management refer to Documentation/power/devices.txt and +power management refer to Documentation/power/admin-guide/devices.rst and Documentation/power/runtime_pm.txt. --------------------------------------------------------------------------- @@ -417,7 +417,7 @@ pm->runtime_idle() callback. 2.4. System-Wide Power Transitions ---------------------------------- There are a few different types of system-wide power transitions, described in -Documentation/power/devices.txt. Each of them requires devices to be handled +Documentation/power/admin-guide/devices.rst. Each of them requires devices to be handled in a specific way and the PM core executes subsystem-level power management callbacks for this purpose. They are executed in phases such that each phase involves executing the same subsystem-level callback for every device belonging @@ -623,7 +623,7 @@ System restore requires a hibernation image to be loaded into memory and the pre-hibernation memory contents to be restored before the pre-hibernation system activity can be resumed. -As described in Documentation/power/devices.txt, the hibernation image is loaded +As described in Documentation/power/admin-guide/devices.rst, the hibernation image is loaded into memory by a fresh instance of the kernel, called the boot kernel, which in turn is loaded and run by a boot loader in the usual way. After the boot kernel has loaded the image, it needs to replace its own code and data with the code @@ -677,7 +677,7 @@ controlling the runtime power management of their devices. At the time of this writing there are two ways to define power management callbacks for a PCI device driver, the recommended one, based on using a -dev_pm_ops structure described in Documentation/power/devices.txt, and the +dev_pm_ops structure described in Documentation/power/admin-guide/devices.rst, and the "legacy" one, in which the .suspend(), .suspend_late(), .resume_early(), and .resume() callbacks from struct pci_driver are used. The legacy approach, however, doesn't allow one to define runtime power management callbacks and is @@ -1046,5 +1046,5 @@ PCI Local Bus Specification, Rev. 3.0 PCI Bus Power Management Interface Specification, Rev. 1.2 Advanced Configuration and Power Interface (ACPI) Specification, Rev. 3.0b PCI Express Base Specification, Rev. 2.0 -Documentation/power/devices.txt +Documentation/power/admin-guide/devices.rst Documentation/power/runtime_pm.txt diff --git a/Documentation/power/runtime_pm.txt b/Documentation/power/runtime_pm.txt index 1fd1fbe9ce95..4870980e967e 100644 --- a/Documentation/power/runtime_pm.txt +++ b/Documentation/power/runtime_pm.txt @@ -674,7 +674,7 @@ left in runtime suspend. If that happens, the PM core will not execute any system suspend and resume callbacks for all of those devices, except for the complete callback, which is then entirely responsible for handling the device as appropriate. This only applies to system suspend transitions that are not -related to hibernation (see Documentation/power/devices.txt for more +related to hibernation (see Documentation/power/admin-guide/devices.rst for more information). The PM core does its best to reduce the probability of race conditions between diff --git a/Documentation/power/swsusp-dmcrypt.txt b/Documentation/power/swsusp-dmcrypt.txt index 59931b46ff7e..b802fbfd95ef 100644 --- a/Documentation/power/swsusp-dmcrypt.txt +++ b/Documentation/power/swsusp-dmcrypt.txt @@ -8,7 +8,7 @@ Some prerequisites: You know how dm-crypt works. If not, visit the following web page: http://www.saout.de/misc/dm-crypt/ You have read Documentation/power/swsusp.txt and understand it. -You did read Documentation/initrd.txt and know how an initrd works. +You did read Documentation/admin-guide/initrd.rst and know how an initrd works. You know how to create or how to modify an initrd. Now your system is properly set up, your disk is encrypted except for diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst index 9d5cef996f7f..983d628c1112 100644 --- a/Documentation/process/4.Coding.rst +++ b/Documentation/process/4.Coding.rst @@ -22,7 +22,7 @@ Coding style ************ The kernel has long had a standard coding style, described in -Documentation/CodingStyle. For much of that time, the policies described +Documentation/process/coding-style.rst. For much of that time, the policies described in that file were taken as being, at most, advisory. As a result, there is a substantial amount of code in the kernel which does not meet the coding style guidelines. The presence of that code leads to two independent @@ -343,7 +343,7 @@ user-space developers to know what they are working with. See Documentation/ABI/README for a description of how this documentation should be formatted and what information needs to be provided. -The file Documentation/kernel-parameters.txt describes all of the kernel's +The file Documentation/admin-guide/kernel-parameters.rst describes all of the kernel's boot-time parameters. Any patch which adds new parameters should add the appropriate entries to this file. diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst index b511ddf7e82a..1b7728b19ea7 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -9,8 +9,8 @@ kernel. Unsurprisingly, the kernel development community has evolved a set of conventions and procedures which are used in the posting of patches; following them will make life much easier for everybody involved. This document will attempt to cover these expectations in reasonable detail; -more information can also be found in the files SubmittingPatches, -SubmittingDrivers, and SubmitChecklist in the kernel documentation +more information can also be found in the files process/submitting-patches.rst, +process/submitting-drivers.rst, and process/submit-checklist.rst in the kernel documentation directory. @@ -198,7 +198,7 @@ pass it to diff with the "-X" option. The tags mentioned above are used to describe how various developers have been associated with the development of this patch. They are described in -detail in the SubmittingPatches document; what follows here is a brief +detail in the process/submitting-patches.rst document; what follows here is a brief summary. Each of these lines has the format: :: @@ -210,7 +210,7 @@ The tags in common use are: - Signed-off-by: this is a developer's certification that he or she has the right to submit the patch for inclusion into the kernel. It is an agreement to the Developer's Certificate of Origin, the full text of - which can be found in Documentation/SubmittingPatches. Code without a + which can be found in Documentation/process/submitting-patches.rst. Code without a proper signoff cannot be merged into the mainline. - Acked-by: indicates an agreement by another developer (often a @@ -221,7 +221,7 @@ The tags in common use are: it to work. - Reviewed-by: the named developer has reviewed the patch for correctness; - see the reviewer's statement in Documentation/SubmittingPatches for more + see the reviewer's statement in Documentation/process/submitting-patches.rst for more detail. - Reported-by: names a user who reported a problem which is fixed by this @@ -248,7 +248,7 @@ take care of: be examined in any detail. If there is any doubt at all, mail the patch to yourself and convince yourself that it shows up intact. - Documentation/email-clients.txt has some helpful hints on making + Documentation/process/email-clients.rst has some helpful hints on making specific mail clients work for sending patches. - Are you sure your patch is free of silly mistakes? You should always diff --git a/Documentation/process/8.Conclusion.rst b/Documentation/process/8.Conclusion.rst index 23ec7cbc2d2b..1c7f54cd0261 100644 --- a/Documentation/process/8.Conclusion.rst +++ b/Documentation/process/8.Conclusion.rst @@ -5,9 +5,9 @@ For more information There are numerous sources of information on Linux kernel development and related topics. First among those will always be the Documentation -directory found in the kernel source distribution. The top-level HOWTO -file is an important starting point; SubmittingPatches and -SubmittingDrivers are also something which all kernel developers should +directory found in the kernel source distribution. The top-level process/howto.rst +file is an important starting point; process/submitting-patches.rst and +process/submitting-drivers.rst are also something which all kernel developers should read. Many internal kernel APIs are documented using the kerneldoc mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those documents in HTML or PDF format (though the version of TeX shipped by some diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst index f5b5b1aa51b3..8cc25a06f353 100644 --- a/Documentation/process/adding-syscalls.rst +++ b/Documentation/process/adding-syscalls.rst @@ -3,7 +3,7 @@ Adding a New System Call This document describes what's involved in adding a new system call to the Linux kernel, over and above the normal submission advice in -:ref:`Documentation/SubmittingPatches `. +:ref:`Documentation/process/submitting-patches.rst `. System Call Alternatives diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 9c61c039ccd9..968808bec407 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -1058,5 +1058,5 @@ gcc internals and indent, all available from http://www.gnu.org/manual/ WG14 is the international standardization working group for the programming language C, URL: http://www.open-std.org/JTC1/SC22/WG14/ -Kernel CodingStyle, by greg@kroah.com at OLS 2002: +Kernel process/coding-style.rst, by greg@kroah.com at OLS 2002: http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index 5f042349f987..3f66a1980726 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -90,19 +90,19 @@ required reading: what is necessary to do to configure and build the kernel. People who are new to the kernel should start here. - :ref:`Documentation/Changes ` + :ref:`Documentation/process/changes.rst ` This file gives a list of the minimum levels of various software packages that are necessary to build and run the kernel successfully. - :ref:`Documentation/CodingStyle ` + :ref:`Documentation/process/coding-style.rst ` This describes the Linux kernel coding style, and some of the rationale behind it. All new code is expected to follow the guidelines in this document. Most maintainers will only accept patches if these rules are followed, and many people will only review code if it is in the proper style. - :ref:`Documentation/SubmittingPatches ` and :ref:`Documentation/SubmittingDrivers ` + :ref:`Documentation/process/submitting-patches.rst ` and :ref:`Documentation/process/submitting-drivers.rst ` These files describe in explicit detail how to successfully create and send a patch, including (but not limited to): @@ -122,7 +122,7 @@ required reading: "Linux kernel patch submission format" http://linux.yyz.us/patch-format.html - :ref:`Documentation/stable_api_nonsense.txt ` + :ref:`Documentation/process/stable-api-nonsense.rst ` This file describes the rationale behind the conscious decision to not have a stable API within the kernel, including things like: @@ -135,29 +135,29 @@ required reading: philosophy and is very important for people moving to Linux from development on other Operating Systems. - :ref:`Documentation/SecurityBugs ` + :ref:`Documentation/admin-guide/security-bugs.rst ` If you feel you have found a security problem in the Linux kernel, please follow the steps in this document to help notify the kernel developers, and help solve the issue. - :ref:`Documentation/ManagementStyle ` + :ref:`Documentation/process/management-style.rst ` This document describes how Linux kernel maintainers operate and the shared ethos behind their methodologies. This is important reading for anyone new to kernel development (or anyone simply curious about it), as it resolves a lot of common misconceptions and confusion about the unique behavior of kernel maintainers. - :ref:`Documentation/stable_kernel_rules.txt ` + :ref:`Documentation/process/stable-kernel-rules.rst ` This file describes the rules on how the stable kernel releases happen, and what to do if you want to get a change into one of these releases. - :ref:`Documentation/kernel-docs.txt ` + :ref:`Documentation/process/kernel-docs.rst ` A list of external documentation that pertains to kernel development. Please consult this list if you do not find what you are looking for within the in-kernel documentation. - :ref:`Documentation/applying-patches.txt ` + :ref:`Documentation/process/applying-patches.rst ` A good introduction describing exactly what a patch is and how to apply it to the different development branches of the kernel. @@ -307,7 +307,7 @@ two weeks, but it can be longer if there are no pressing problems. A security-related problem, instead, can cause a release to happen almost instantly. -The file Documentation/stable_kernel_rules.txt in the kernel tree +The file Documentation/process/stable-kernel-rules.rst in the kernel tree documents what kinds of changes are acceptable for the -stable tree, and how the release process works. @@ -366,7 +366,7 @@ tool. For details on how to use the kernel bugzilla, please see: https://bugzilla.kernel.org/page.cgi?id=faq.html -The file REPORTING-BUGS in the main kernel source directory has a good +The file admin-guide/reporting-bugs.rst in the main kernel source directory has a good template for how to report a possible kernel bug, and details what kind of information is needed by the kernel developers to help track down the problem. @@ -440,7 +440,7 @@ add your statements between the individual quoted sections instead of writing at the top of the mail. If you add patches to your mail, make sure they are plain readable text -as stated in Documentation/SubmittingPatches. +as stated in Documentation/process/submitting-patches.rst. Kernel developers don't want to deal with attachments or compressed patches; they may want to comment on individual lines of your patch, which works only that way. Make sure you diff --git a/Documentation/process/management-style.rst b/Documentation/process/management-style.rst index dea2e66c9a10..45595fd8a66b 100644 --- a/Documentation/process/management-style.rst +++ b/Documentation/process/management-style.rst @@ -5,7 +5,7 @@ Linux kernel management style This is a short document describing the preferred (or made up, depending on who you ask) management style for the linux kernel. It's meant to -mirror the CodingStyle document to some degree, and mainly written to +mirror the process/coding-style.rst document to some degree, and mainly written to avoid answering [#f1]_ the same (or similar) questions over and over again. Management style is very personal and much harder to quantify than diff --git a/Documentation/process/stable-kernel-rules.rst b/Documentation/process/stable-kernel-rules.rst index 4d82e31b7958..11ec2d93a5e0 100644 --- a/Documentation/process/stable-kernel-rules.rst +++ b/Documentation/process/stable-kernel-rules.rst @@ -27,7 +27,7 @@ Rules on what kind of patches are accepted, and which ones are not, into the - It cannot contain any "trivial" fixes in it (spelling changes, whitespace cleanups, etc). - It must follow the - :ref:`Documentation/SubmittingPatches ` + :ref:`Documentation/process/submitting-patches.rst ` rules. - It or an equivalent fix must already exist in Linus' tree (upstream). @@ -40,7 +40,7 @@ Procedure for submitting patches to the -stable tree Documentation/networking/netdev-FAQ.txt - Security patches should not be handled (solely) by the -stable review process but should follow the procedures in - :ref:`Documentation/SecurityBugs `. + :ref:`Documentation/admin-guide/security-bugs.rst `. For all other submissions, choose one of the following procedures ----------------------------------------------------------------- diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index 894289b22b15..a0d9d34bfb6d 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -7,7 +7,7 @@ Here are some basic things that developers should do if they want to see their kernel patch submissions accepted more quickly. These are all above and beyond the documentation that is provided in -:ref:`Documentation/SubmittingPatches ` +:ref:`Documentation/process/submitting-patches.rst ` and elsewhere regarding submitting Linux kernel patches. @@ -31,7 +31,7 @@ and elsewhere regarding submitting Linux kernel patches. tends to use ``unsigned long`` for 64-bit quantities. 5) Check your patch for general style as detailed in - :ref:`Documentation/CodingStyle `. + :ref:`Documentation/process/coding-style.rst `. Check for trivial violations with the patch style checker prior to submission (``scripts/checkpatch.pl``). You should be able to justify all violations that remain in @@ -78,7 +78,7 @@ and elsewhere regarding submitting Linux kernel patches. 16) All new ``/proc`` entries are documented under ``Documentation/`` 17) All new kernel boot parameters are documented in - ``Documentation/kernel-parameters.txt``. + ``Documentation/admin-guide/kernel-parameters.rst``. 18) All new module parameters are documented with ``MODULE_PARM_DESC()`` diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst index 252b77a23fad..0939d018c289 100644 --- a/Documentation/process/submitting-drivers.rst +++ b/Documentation/process/submitting-drivers.rst @@ -8,7 +8,7 @@ various kernel trees. Note that if you are interested in video card drivers you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org (http://x.org/) instead. -Also read the Documentation/SubmittingPatches document. +Also read the Documentation/process/submitting-patches.rst document. Allocating Device Numbers @@ -19,7 +19,7 @@ by the Linux assigned name and number authority (currently this is Torben Mathiasen). The site is http://www.lanana.org/. This also deals with allocating numbers for devices that are not going to be submitted to the mainstream kernel. -See Documentation/devices.txt for more information on this. +See Documentation/admin-guide/devices.rst for more information on this. If you don't use assigned numbers then when your device is submitted it will be given an assigned number even if that is different from values you may @@ -73,7 +73,7 @@ Interfaces: Code: Please use the Linux style of code formatting as documented - in :ref:`Documentation/CodingStyle `. + in :ref:`Documentation/process/coding-style.rst `. If you have sections of code that need to be in other formats, for example because they are shared with a windows driver kit and you want to @@ -109,7 +109,7 @@ PM support: anything. For the driver testing instructions see Documentation/power/drivers-testing.txt and for a relatively complete overview of the power management issues related to - drivers see Documentation/power/devices.txt . + drivers see Documentation/power/admin-guide/devices.rst . Control: In general if there is active maintenance of a driver by diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 4cc20b2c6df3..b4cf8f375184 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -11,10 +11,10 @@ can greatly increase the chances of your change being accepted. This document contains a large number of suggestions in a relatively terse format. For detailed information on how the kernel development process works, see :ref:`Documentation/process `. -Also, read :ref:`Documentation/SubmitChecklist ` +Also, read :ref:`Documentation/process/submit-checklist.rst ` for a list of items to check before submitting code. If you are submitting a driver, also read -:ref:`Documentation/SubmittingDrivers `; +:ref:`Documentation/process/submitting-drivers.rst `; for device tree binding patches, read Documentation/devicetree/bindings/submitting-patches.txt. @@ -238,7 +238,7 @@ then only post say 15 or so at a time and wait for review and integration. Check your patch for basic style violations, details of which can be found in -:ref:`Documentation/CodingStyle `. +:ref:`Documentation/process/coding-style.rst `. Failure to do so simply wastes the reviewers time and will get your patch rejected, probably without even being read. @@ -305,7 +305,7 @@ toward the stable maintainers by putting a line like this:: into the sign-off area of your patch (note, NOT an email recipient). You should also read -:ref:`Documentation/stable_kernel_rules.txt ` +:ref:`Documentation/process/stable-kernel-rules.rst ` in addition to this file. Note, however, that some subsystem maintainers want to come to their own @@ -363,7 +363,7 @@ decreasing the likelihood of your MIME-attached change being accepted. Exception: If your mailer is mangling patches then someone may ask you to re-send them using MIME. -See :ref:`Documentation/email-clients.txt ` +See :ref:`Documentation/process/email-clients.rst ` for hints about configuring your e-mail client so that it sends your patches untouched. @@ -828,8 +828,8 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! -Kernel Documentation/CodingStyle: - :ref:`Documentation/CodingStyle ` +Kernel Documentation/process/coding-style.rst: + :ref:`Documentation/process/coding-style.rst ` Linus Torvalds's mail on the canonical patch format: diff --git a/Documentation/rfkill.txt b/Documentation/rfkill.txt index 1f0c27049340..8c174063b3f0 100644 --- a/Documentation/rfkill.txt +++ b/Documentation/rfkill.txt @@ -26,7 +26,7 @@ whether they can be changed or not: the system software. The rfkill subsystem has two parameters, rfkill.default_state and -rfkill.master_switch_mode, which are documented in kernel-parameters.txt. +rfkill.master_switch_mode, which are documented in admin-guide/kernel-parameters.rst. 2. Implementation details diff --git a/Documentation/scsi/scsi-parameters.txt b/Documentation/scsi/scsi-parameters.txt index 8e66dafa41e1..8477655c0e46 100644 --- a/Documentation/scsi/scsi-parameters.txt +++ b/Documentation/scsi/scsi-parameters.txt @@ -1,7 +1,7 @@ SCSI Kernel Parameters ~~~~~~~~~~~~~~~~~~~~~~ -See Documentation/kernel-parameters.txt for general information on +See Documentation/admin-guide/kernel-parameters.rst for general information on specifying module parameters. This document may not be entirely up to date and comprehensive. The command diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt index 255075157511..6338400eed73 100644 --- a/Documentation/scsi/scsi_mid_low_api.txt +++ b/Documentation/scsi/scsi_mid_low_api.txt @@ -336,7 +336,7 @@ in parallel by these functions. Conventions =========== First, Linus Torvalds's thoughts on C coding style can be found in the -Documentation/CodingStyle file. +Documentation/process/coding-style.rst file. Next, there is a movement to "outlaw" typedefs introducing synonyms for struct tags. Both can be still found in the SCSI subsystem, but diff --git a/Documentation/scsi/sym53c8xx_2.txt b/Documentation/scsi/sym53c8xx_2.txt index 6af8f7a7770f..d28186553fb0 100644 --- a/Documentation/scsi/sym53c8xx_2.txt +++ b/Documentation/scsi/sym53c8xx_2.txt @@ -427,7 +427,7 @@ Synchronous transfers frequency (default answer: 80) 10.1 Syntax Setup commands can be passed to the driver either at boot time or as -parameters to modprobe, as described in Documentation/kernel-parameters.txt +parameters to modprobe, as described in Documentation/admin-guide/kernel-parameters.rst Example of boot setup command under lilo prompt: diff --git a/Documentation/sound/alsa/alsa-parameters.txt b/Documentation/sound/alsa/alsa-parameters.txt index 0fa40679b080..72eced86f035 100644 --- a/Documentation/sound/alsa/alsa-parameters.txt +++ b/Documentation/sound/alsa/alsa-parameters.txt @@ -1,7 +1,7 @@ ALSA Kernel Parameters ~~~~~~~~~~~~~~~~~~~~~~ -See Documentation/kernel-parameters.txt for general information on +See Documentation/admin-guide/kernel-parameters.rst for general information on specifying module parameters. This document may not be entirely up to date and comprehensive. The command diff --git a/Documentation/sound/oss/oss-parameters.txt b/Documentation/sound/oss/oss-parameters.txt index 3ab391e7c295..cc675f25eee4 100644 --- a/Documentation/sound/oss/oss-parameters.txt +++ b/Documentation/sound/oss/oss-parameters.txt @@ -1,7 +1,7 @@ OSS Kernel Parameters ~~~~~~~~~~~~~~~~~~~~~ -See Documentation/kernel-parameters.txt for general information on +See Documentation/admin-guide/kernel-parameters.rst for general information on specifying module parameters. This document may not be entirely up to date and comprehensive. The command diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index ffab8b5caa60..6bb78f872929 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -71,7 +71,7 @@ show up in /proc/sys/kernel: - printk_ratelimit_burst - pty ==> Documentation/filesystems/devpts.txt - randomize_va_space -- real-root-dev ==> Documentation/initrd.txt +- real-root-dev ==> Documentation/admin-guide/initrd.rst - reboot-cmd [ SPARC only ] - rtsig-max - rtsig-nr @@ -453,7 +453,7 @@ in a KVM virtual machine. This default can be overridden by adding nmi_watchdog=1 -to the guest kernel command line (see Documentation/kernel-parameters.txt). +to the guest kernel command line (see Documentation/admin-guide/kernel-parameters.rst). ============================================================== diff --git a/Documentation/virtual/kvm/review-checklist.txt b/Documentation/virtual/kvm/review-checklist.txt index a850986ed684..a83b27635fdd 100644 --- a/Documentation/virtual/kvm/review-checklist.txt +++ b/Documentation/virtual/kvm/review-checklist.txt @@ -1,8 +1,8 @@ Review checklist for kvm patches ================================ -1. The patch must follow Documentation/CodingStyle and - Documentation/SubmittingPatches. +1. The patch must follow Documentation/process/coding-style.rst and + Documentation/process/submitting-patches.rst. 2. Patches should be against kvm.git master branch. diff --git a/Documentation/vm/numa b/Documentation/vm/numa index e0b58c0e6b49..a08f71647714 100644 --- a/Documentation/vm/numa +++ b/Documentation/vm/numa @@ -82,7 +82,7 @@ such as DMA or DMA32, represent relatively scarce resources. Linux chooses a default zonelist order based on the sizes of the various zone types relative to the total memory of the node and the total memory of the system. The default zonelist order may be overridden using the numa_zonelist_order kernel -boot parameter or sysctl. [see Documentation/kernel-parameters.txt and +boot parameter or sysctl. [see Documentation/admin-guide/kernel-parameters.rst and Documentation/sysctl/vm.txt] By default, Linux will attempt to satisfy memory allocation requests from the diff --git a/Documentation/watchdog/convert_drivers_to_kernel_api.txt b/Documentation/watchdog/convert_drivers_to_kernel_api.txt index 271b8850dde7..9fffb2958d13 100644 --- a/Documentation/watchdog/convert_drivers_to_kernel_api.txt +++ b/Documentation/watchdog/convert_drivers_to_kernel_api.txt @@ -213,6 +213,6 @@ The entry for the driver now needs to select WATCHDOG_CORE: Create a patch and send it to upstream -------------------------------------- -Make sure you understood Documentation/SubmittingPatches and send your patch to +Make sure you understood Documentation/process/submitting-patches.rst and send your patch to linux-watchdog@vger.kernel.org. We are looking forward to it :) diff --git a/Documentation/watchdog/watchdog-parameters.txt b/Documentation/watchdog/watchdog-parameters.txt index a8d364227a77..e21850e270a0 100644 --- a/Documentation/watchdog/watchdog-parameters.txt +++ b/Documentation/watchdog/watchdog-parameters.txt @@ -4,7 +4,7 @@ be listed here unless the driver has its own driver-specific information file. -See Documentation/kernel-parameters.txt for information on +See Documentation/admin-guide/kernel-parameters.rst for information on providing kernel parameters for builtin drivers versus loadable modules. diff --git a/Documentation/x86/boot.txt b/Documentation/x86/boot.txt index 9da6f3512249..5e9b826b5f62 100644 --- a/Documentation/x86/boot.txt +++ b/Documentation/x86/boot.txt @@ -921,7 +921,7 @@ They should normally not be deleted from the kernel command line even though not all of them are actually meaningful to the kernel. Boot loader authors who need additional command line options for the boot loader itself should get them registered in -Documentation/kernel-parameters.txt to make sure they will not +Documentation/admin-guide/kernel-parameters.rst to make sure they will not conflict with actual kernel options now or in the future. vga= diff --git a/Documentation/zh_CN/CodingStyle b/Documentation/zh_CN/CodingStyle index 12717791baac..b02738042799 100644 --- a/Documentation/zh_CN/CodingStyle +++ b/Documentation/zh_CN/CodingStyle @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/CodingStyle +Chinese translated version of Documentation/process/coding-style.rst If you have any comment or update to the content, please post to LKML directly. However, if you have problem communicating in English you can also ask the @@ -7,7 +7,7 @@ translation is outdated or there is problem with translation. Chinese maintainer: Zhang Le --------------------------------------------------------------------- -Documentation/CodingStyle的中文翻译 +Documentation/process/coding-style.rst的中文翻译 如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可 以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。 @@ -809,5 +809,5 @@ GNU 手册 - 遵循 K&R 标准和此文本 - cpp, gcc, gcc internals and indent, WG14是C语言的国际标准化工作组，URL: http://www.open-std.org/JTC1/SC22/WG14/ -Kernel CodingStyle，作者 greg@kroah.com 发表于OLS 2002： +Kernel process/coding-style.rst，作者 greg@kroah.com 发表于OLS 2002： http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ diff --git a/Documentation/zh_CN/HOWTO b/Documentation/zh_CN/HOWTO index f0613b92e0be..11be075ba5fa 100644 --- a/Documentation/zh_CN/HOWTO +++ b/Documentation/zh_CN/HOWTO @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/HOWTO +Chinese translated version of Documentation/process/howto.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -9,7 +9,7 @@ or if there is a problem with the translation. Maintainer: Greg Kroah-Hartman Chinese maintainer: Li Yang --------------------------------------------------------------------- -Documentation/HOWTO 的中文翻译 +Documentation/process/howto.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 @@ -93,16 +93,16 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与 文件简要介绍了Linux内核的背景，并且描述了如何配置和编译内核。内核的 新用户应该从这里开始。 - Documentation/Changes + Documentation/process/changes.rst 文件给出了用来编译和使用内核所需要的最小软件包列表。 - Documentation/CodingStyle + Documentation/process/coding-style.rst 描述Linux内核的代码风格和理由。所有新代码需要遵守这篇文档中定义的规 范。大多数维护者只会接收符合规定的补丁，很多人也只会帮忙检查符合风格 的代码。 - Documentation/SubmittingPatches - Documentation/SubmittingDrivers + Documentation/process/submitting-patches.rst + Documentation/process/submitting-drivers.rst 这两份文档明确描述如何创建和发送补丁，其中包括（但不仅限于)： - 邮件内容 - 邮件格式 @@ -116,7 +116,7 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与 "Linux kernel patch submission format" http://linux.yyz.us/patch-format.html - Documentation/stable_api_nonsense.txt + Documentation/process/stable-api-nonsense.rst 论证内核为什么特意不包括稳定的内核内部API，也就是说不包括像这样的特 性： - 子系统中间层（为了兼容性？） @@ -125,23 +125,23 @@ Linux内核代码中包含有大量的文档。这些文档对于学习如何与 这篇文档对于理解Linux的开发哲学至关重要。对于将开发平台从其他操作系 统转移到Linux的人来说也很重要。 - Documentation/SecurityBugs + Documentation/admin-guide/security-bugs.rst 如果你认为自己发现了Linux内核的安全性问题，请根据这篇文档中的步骤来 提醒其他内核开发者并帮助解决这个问题。 - Documentation/ManagementStyle + Documentation/process/management-style.rst 描述内核维护者的工作方法及其共有特点。这对于刚刚接触内核开发（或者对 它感到好奇）的人来说很重要，因为它解释了很多对于内核维护者独特行为的 普遍误解与迷惑。 - Documentation/stable_kernel_rules.txt + Documentation/process/stable-kernel-rules.rst 解释了稳定版内核发布的规则，以及如何将改动放入这些版本的步骤。 - Documentation/kernel-docs.txt + Documentation/process/kernel-docs.rst 有助于内核开发的外部文档列表。如果你在内核自带的文档中没有找到你想找 的内容，可以查看这些文档。 - Documentation/applying-patches.txt + Documentation/process/applying-patches.rst 关于补丁是什么以及如何将它打在不同内核开发分支上的好介绍 内核还拥有大量从代码自动生成的文档。它包含内核内部API的全面介绍以及如何 @@ -238,7 +238,7 @@ kernel.org网站的pub/linux/kernel/v2.6/目录下找到它。它的开发遵循 2.6.x.y版本由“稳定版”小组（邮件地址）维护，一般隔周发 布新版本。 -内核源码中的Documentation/stable_kernel_rules.txt文件具体描述了可被稳定 +内核源码中的Documentation/process/stable-kernel-rules.rst文件具体描述了可被稳定 版内核接受的修改类型以及发布的流程。 @@ -329,7 +329,7 @@ bugzilla.kernel.org是Linux内核开发者们用来跟踪内核Bug的网站。 户在这个工具中报告找到的所有bug。如何使用内核bugzilla的细节请访问： http://test.kernel.org/bugzilla/faq.html -内核源码主目录中的REPORTING-BUGS文件里有一个很好的模板。它指导用户如何报 +内核源码主目录中的admin-guide/reporting-bugs.rst文件里有一个很好的模板。它指导用户如何报 告可能的内核bug以及需要提供哪些信息来帮助内核开发者们找到问题的根源。 @@ -380,7 +380,7 @@ MAINTAINERS文件中可以找到不同话题对应的邮件列表。 这几行。将你的评论加在被引用的段落之间而不要放在邮件的顶部。 如果你在邮件中附带补丁，请确认它们是可以直接阅读的纯文本（如 -Documentation/SubmittingPatches文档中所述）。内核开发者们不希望遇到附件 +Documentation/process/submitting-patches.rst文档中所述）。内核开发者们不希望遇到附件 或者被压缩了的补丁。只有这样才能保证他们可以直接评论你的每行代码。请确保 你使用的邮件发送程序不会修改空格和制表符。一个防范性的测试方法是先将邮件 发送给自己，然后自己尝试是否可以顺利地打上收到的补丁。如果测试不成功，请 diff --git a/Documentation/zh_CN/SecurityBugs b/Documentation/zh_CN/SecurityBugs index d21eb07fe943..2d0fffd122ce 100644 --- a/Documentation/zh_CN/SecurityBugs +++ b/Documentation/zh_CN/SecurityBugs @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/SecurityBugs +Chinese translated version of Documentation/admin-guide/security-bugs.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -8,7 +8,7 @@ or if there is a problem with the translation. Chinese maintainer: Harry Wei --------------------------------------------------------------------- -Documentation/SecurityBugs 的中文翻译 +Documentation/admin-guide/security-bugs.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 @@ -31,7 +31,7 @@ linux内核安全团队可以通过email来联系。这是 一组独立的安全工作人员，可以帮助改善漏洞报告并且公布和取消一个修复。安 全团队有可能会从部分的维护者那里引进额外的帮助来了解并且修复安全漏洞。 当遇到任何漏洞，所能提供的信息越多就越能诊断和修复。如果你不清楚什么 -是有帮助的信息，那就请重温一下REPORTING-BUGS文件中的概述过程。任 +是有帮助的信息，那就请重温一下admin-guide/reporting-bugs.rst文件中的概述过程。任 何攻击性的代码都是非常有用的，未经报告者的同意不会被取消，除非它已经 被公布于众。 diff --git a/Documentation/zh_CN/SubmittingDrivers b/Documentation/zh_CN/SubmittingDrivers index d313f5d8448d..929385e4b194 100644 --- a/Documentation/zh_CN/SubmittingDrivers +++ b/Documentation/zh_CN/SubmittingDrivers @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/SubmittingDrivers +Chinese translated version of Documentation/process/submitting-drivers.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -8,7 +8,7 @@ or if there is a problem with the translation. Chinese maintainer: Li Yang --------------------------------------------------------------------- -Documentation/SubmittingDrivers 的中文翻译 +Documentation/process/submitting-drivers.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 @@ -30,7 +30,7 @@ Documentation/SubmittingDrivers 的中文翻译 兴趣的是显卡驱动程序，你也许应该访问 XFree86 项目(http://www.xfree86.org/) 和／或 X.org 项目 (http://x.org)。 -另请参阅 Documentation/SubmittingPatches 文档。 +另请参阅 Documentation/process/submitting-patches.rst 文档。 分配设备号 @@ -39,7 +39,7 @@ Documentation/SubmittingDrivers 的中文翻译 块设备和字符设备的主设备号与从设备号是由 Linux 命名编号分配权威 LANANA（ 现在是 Torben Mathiasen）负责分配。申请的网址是 http://www.lanana.org/。 即使不准备提交到主流内核的设备驱动也需要在这里分配设备号。有关详细信息， -请参阅 Documentation/devices.txt。 +请参阅 Documentation/admin-guide/devices.rst。 如果你使用的不是已经分配的设备号，那么当你提交设备驱动的时候，它将会被强 制分配一个新的设备号，即便这个设备号和你之前发给客户的截然不同。 @@ -81,7 +81,7 @@ Linux 2.6: 如果你需要一个 Linux 和 NT 的通用驱动接口，那么请在用 户空间实现它。 -代码： 请使用 Documentation/CodingStyle 中所描述的 Linux 代码风 +代码： 请使用 Documentation/process/coding-style.rst 中所描述的 Linux 代码风 格。如果你的某些代码段（例如那些与 Windows 驱动程序包共 享的代码段）需要使用其他格式，而你却只希望维护一份代码， 那么请将它们很好地区分出来，并且注明原因。 @@ -107,7 +107,7 @@ Linux 2.6: 程序测试的指导，请参阅 Documentation/power/drivers-testing.txt。有关驱动程序电 源管理问题相对全面的概述，请参阅 - Documentation/power/devices.txt。 + Documentation/power/admin-guide/devices.rst。 管理： 如果一个驱动程序的作者还在进行有效的维护，那么通常除了那 些明显正确且不需要任何检查的补丁以外，其他所有的补丁都会 diff --git a/Documentation/zh_CN/SubmittingPatches b/Documentation/zh_CN/SubmittingPatches index 1d3a10f8746b..e9098da8f1a4 100644 --- a/Documentation/zh_CN/SubmittingPatches +++ b/Documentation/zh_CN/SubmittingPatches @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/SubmittingPatches +Chinese translated version of Documentation/process/submitting-patches.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -8,7 +8,7 @@ or if there is a problem with the translation. Chinese maintainer: TripleX Chung --------------------------------------------------------------------- -Documentation/SubmittingPatches 的中文翻译 +Documentation/process/submitting-patches.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 @@ -30,9 +30,9 @@ Documentation/SubmittingPatches 的中文翻译 对于想要将改动提交到 Linux 内核的个人或者公司来说，如果不熟悉“规矩”， 提交的流程会让人畏惧。本文档收集了一系列建议，这些建议可以大大的提高你 的改动被接受的机会。 -阅读 Documentation/SubmitChecklist 来获得在提交代码前需要检查的项目的列 +阅读 Documentation/process/submit-checklist.rst 来获得在提交代码前需要检查的项目的列 表。如果你在提交一个驱动程序，那么同时阅读一下 -Documentation/SubmittingDrivers 。 +Documentation/process/submitting-drivers.rst 。 -------------------------- @@ -338,7 +338,7 @@ e-mail 标题中的“一句话概述”扼要的描述 e-mail 中的补丁。 本节包含很多和提交到内核的代码有关的通常的"规则"。事情永远有例外...但是 你必须真的有好的理由这样做。你可以把本节叫做Linus的计算机科学入门课。 -1) 读 Document/CodingStyle +1) 读 Document/process/coding-style.rst Nuff 说过，如果你的代码和这个偏离太多，那么它有可能会被拒绝，没有更多的 审查，没有更多的评价。 @@ -404,8 +404,8 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! -Kernel Documentation/CodingStyle: - +Kernel Documentation/process/coding-style.rst: + Linus Torvalds's mail on the canonical patch format: diff --git a/Documentation/zh_CN/arm/Booting b/Documentation/zh_CN/arm/Booting index 6158a64df80c..1fe866f8218f 100644 --- a/Documentation/zh_CN/arm/Booting +++ b/Documentation/zh_CN/arm/Booting @@ -68,7 +68,7 @@ RAM，或可能使用对这个设备已知的 RAM 信息，还可能使用任何 作为替代方案，引导加载程序也可以通过标签列表传递相关的'console=' 选项给内核以指定某个串口，而串口数据格式的选项在以下文档中描述： - Documentation/kernel-parameters.txt。 + Documentation/admin-guide/kernel-parameters.rst。 3、检测机器类型 diff --git a/Documentation/zh_CN/email-clients.txt b/Documentation/zh_CN/email-clients.txt index b9a1a3e6c78d..ec31d97e8d0e 100644 --- a/Documentation/zh_CN/email-clients.txt +++ b/Documentation/zh_CN/email-clients.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/email-clients.txt +Chinese translated version of Documentation/process/email-clients.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -8,7 +8,7 @@ or if there is a problem with the translation. Chinese maintainer: Harry Wei --------------------------------------------------------------------- -Documentation/email-clients.txt 的中文翻译 +Documentation/process/email-clients.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 diff --git a/Documentation/zh_CN/oops-tracing.txt b/Documentation/zh_CN/oops-tracing.txt index 9312608ffb8d..41ab53cc0e83 100644 --- a/Documentation/zh_CN/oops-tracing.txt +++ b/Documentation/zh_CN/oops-tracing.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/oops-tracing.txt +Chinese translated version of Documentation/admin-guide/oops-tracing.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -8,7 +8,7 @@ or if there is a problem with the translation. Chinese maintainer: Dave Young --------------------------------------------------------------------- -Documentation/oops-tracing.txt 的中文翻译 +Documentation/admin-guide/oops-tracing.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 @@ -50,7 +50,7 @@ cat /proc/kmsg > file， 然而你必须介入中止传输， kmsg是一个“ 息滚动到了终端的上面，你会发现以高分辩率启动（比如，vga=791）会让你读到更多的文 本。（注意：这需要vesafb，所以对‘早期’的oops没有帮助） -（2）用串口终端启动（请参看Documentation/serial-console.txt），运行一个null +（2）用串口终端启动（请参看Documentation/admin-guide/serial-console.rst），运行一个null modem到另一台机器并用你喜欢的通讯工具获取输出。Minicom工作地很好。 （3）使用Kdump（请参看Documentation/kdump/kdump.txt）， diff --git a/Documentation/zh_CN/stable_api_nonsense.txt b/Documentation/zh_CN/stable_api_nonsense.txt index c26a27d1ee7d..a2b27fab382c 100644 --- a/Documentation/zh_CN/stable_api_nonsense.txt +++ b/Documentation/zh_CN/stable_api_nonsense.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/stable_api_nonsense.txt +Chinese translated version of Documentation/process/stable-api-nonsense.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have problem @@ -9,7 +9,7 @@ is problem with translation. Maintainer: Greg Kroah-Hartman Chinese maintainer: TripleX Chung --------------------------------------------------------------------- -Documentation/stable_api_nonsense.txt 的中文翻译 +Documentation/process/stable-api-nonsense.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 diff --git a/Documentation/zh_CN/stable_kernel_rules.txt b/Documentation/zh_CN/stable_kernel_rules.txt index 26ea5ed7cd9c..db4ba5a0c39a 100644 --- a/Documentation/zh_CN/stable_kernel_rules.txt +++ b/Documentation/zh_CN/stable_kernel_rules.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/stable_kernel_rules.txt +Chinese translated version of Documentation/process/stable-kernel-rules.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -8,7 +8,7 @@ or if there is a problem with the translation. Chinese maintainer: TripleX Chung --------------------------------------------------------------------- -Documentation/stable_kernel_rules.txt 的中文翻译 +Documentation/process/stable-kernel-rules.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 @@ -38,7 +38,7 @@ Documentation/stable_kernel_rules.txt 的中文翻译 - 没有“理论上的竞争条件”，除非能给出竞争条件如何被利用的解释。 - 不能存在任何的“琐碎的”修正（拼写修正，去掉多余空格之类的）。 - 必须被相关子系统的维护者接受。 - - 必须遵循Documentation/SubmittingPatches里的规则。 + - 必须遵循Documentation/process/submitting-patches.rst里的规则。 向稳定版代码树提交补丁的过程： diff --git a/Documentation/zh_CN/volatile-considered-harmful.txt b/Documentation/zh_CN/volatile-considered-harmful.txt index ba8149d2233a..475125967197 100644 --- a/Documentation/zh_CN/volatile-considered-harmful.txt +++ b/Documentation/zh_CN/volatile-considered-harmful.txt @@ -1,4 +1,4 @@ -Chinese translated version of Documentation/volatile-considered-harmful.txt +Chinese translated version of Documentation/process/volatile-considered-harmful.rst If you have any comment or update to the content, please contact the original document maintainer directly. However, if you have a problem @@ -9,7 +9,7 @@ or if there is a problem with the translation. Maintainer: Jonathan Corbet Chinese maintainer: Bryan Wu --------------------------------------------------------------------- -Documentation/volatile-considered-harmful.txt 的中文翻译 +Documentation/process/volatile-considered-harmful.rst 的中文翻译 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 diff --git a/MAINTAINERS b/MAINTAINERS index de0451df542f..69820b75b2e0 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -35,13 +35,13 @@ trivial patch so apply some common sense. PLEASE check your patch with the automated style checker (scripts/checkpatch.pl) to catch trivial style violations. - See Documentation/CodingStyle for guidance here. + See Documentation/process/coding-style.rst for guidance here. PLEASE CC: the maintainers and mailing lists that are generated by scripts/get_maintainer.pl. The results returned by the script will be best if you have git installed and are making your changes in a branch derived from Linus' latest git tree. - See Documentation/SubmittingPatches for details. + See Documentation/process/submitting-patches.rst for details. PLEASE try to include any credit lines you want added with the patch. It avoids people being missed off by mistake and makes @@ -54,7 +54,7 @@ trivial patch so apply some common sense. of the Linux Foundation certificate of contribution and should include a Signed-off-by: line. The current version of this "Developer's Certificate of Origin" (DCO) is listed in the file - Documentation/SubmittingPatches. + Documentation/process/submitting-patches.rst. 6. Make sure you have the right to send any changes you make. If you do changes at work you may find your employer owns the patch @@ -2924,7 +2924,7 @@ CAPELLA MICROSYSTEMS LIGHT SENSOR DRIVER M: Kevin Tsai S: Maintained F: drivers/iio/light/cm* -F: Documentation/devicetree/bindings/i2c/trivial-devices.txt +F: Documentation/devicetree/bindings/i2c/trivial-admin-guide/devices.rst CAVIUM I2C DRIVER M: Jan Glauber @@ -11438,7 +11438,7 @@ STABLE BRANCH M: Greg Kroah-Hartman L: stable@vger.kernel.org S: Supported -F: Documentation/stable_kernel_rules.txt +F: Documentation/process/stable-kernel-rules.rst STAGING SUBSYSTEM M: Greg Kroah-Hartman diff --git a/arch/x86/Kconfig b/arch/x86/Kconfig index bada636d1065..19d237b0737d 100644 --- a/arch/x86/Kconfig +++ b/arch/x86/Kconfig @@ -1525,7 +1525,7 @@ config X86_CHECK_BIOS_CORRUPTION line. By default it scans the low 64k of memory every 60 seconds; see the memory_corruption_check_size and memory_corruption_check_period parameters in - Documentation/kernel-parameters.txt to adjust this. + Documentation/admin-guide/kernel-parameters.rst to adjust this. When enabled with the default parameters, this option has almost no overhead, as it reserves a relatively small amount diff --git a/drivers/acpi/Kconfig b/drivers/acpi/Kconfig index 535e7828445a..c5f9cbe0ae21 100644 --- a/drivers/acpi/Kconfig +++ b/drivers/acpi/Kconfig @@ -342,7 +342,7 @@ config ACPI_DEBUG Use the acpi.debug_layer and acpi.debug_level kernel command-line parameters documented in Documentation/acpi/debug.txt and - Documentation/kernel-parameters.txt to control the type and + Documentation/admin-guide/kernel-parameters.rst to control the type and amount of debug output. config ACPI_PCI_SLOT diff --git a/drivers/ata/libata-core.c b/drivers/ata/libata-core.c index 223a770f78f3..59ce0dd50701 100644 --- a/drivers/ata/libata-core.c +++ b/drivers/ata/libata-core.c @@ -129,7 +129,7 @@ static int ata_force_tbl_size; static char ata_force_param_buf[PAGE_SIZE] __initdata; /* param_buf is thrown away after initialization, disallow read */ module_param_string(force, ata_force_param_buf, sizeof(ata_force_param_buf), 0); -MODULE_PARM_DESC(force, "Force ATA configurations including cable type, link speed and transfer mode (see Documentation/kernel-parameters.txt for details)"); +MODULE_PARM_DESC(force, "Force ATA configurations including cable type, link speed and transfer mode (see Documentation/admin-guide/kernel-parameters.rst for details)"); static int atapi_enabled = 1; module_param(atapi_enabled, int, 0444); diff --git a/drivers/char/pcmcia/cm4000_cs.c b/drivers/char/pcmcia/cm4000_cs.c index c115217c79ae..e051fc8aa7d7 100644 --- a/drivers/char/pcmcia/cm4000_cs.c +++ b/drivers/char/pcmcia/cm4000_cs.c @@ -14,7 +14,7 @@ * (C) 2000,2001,2002,2003,2004 Omnikey AG * * (C) 2005-2006 Harald Welte - * - Adhere to Kernel CodingStyle + * - Adhere to Kernel process/coding-style.rst * - Port to 2.6.13 "new" style PCMCIA * - Check for copy_{from,to}_user return values * - Use nonseekable_open() @@ -151,7 +151,7 @@ static struct pcmcia_device *dev_table[CM4000_MAX_DEV]; static struct class *cmm_class; /* This table doesn't use spaces after the comma between fields and thus - * violates CodingStyle. However, I don't really think wrapping it around will + * violates process/coding-style.rst. However, I don't really think wrapping it around will * make it any clearer to read -HW */ static unsigned char fi_di_table[10][14] = { /*FI 00 01 02 03 04 05 06 07 08 09 10 11 12 13 */ diff --git a/drivers/net/can/grcan.c b/drivers/net/can/grcan.c index db9538d4b358..a7be12d9a139 100644 --- a/drivers/net/can/grcan.c +++ b/drivers/net/can/grcan.c @@ -15,7 +15,7 @@ * See "Documentation/ABI/testing/sysfs-class-net-grcan" for information on the * sysfs interface. * - * See "Documentation/kernel-parameters.txt" for information on the module + * See "Documentation/admin-guide/kernel-parameters.rst" for information on the module * parameters. * * This program is free software; you can redistribute it and/or modify it diff --git a/drivers/nvdimm/Kconfig b/drivers/nvdimm/Kconfig index 8b2b740d6679..b20ce7da1ee4 100644 --- a/drivers/nvdimm/Kconfig +++ b/drivers/nvdimm/Kconfig @@ -28,7 +28,7 @@ config BLK_DEV_PMEM non-standard OEM-specific E820 memory type (type-12, see CONFIG_X86_PMEM_LEGACY), or it is manually specified by the 'memmap=nn[KMG]!ss[KMG]' kernel command line (see - Documentation/kernel-parameters.txt). This driver converts + Documentation/admin-guide/kernel-parameters.rst). This driver converts these persistent memory ranges into block devices that are capable of DAX (direct-access) file system mappings. See Documentation/nvdimm/nvdimm.txt for more details. diff --git a/drivers/staging/vme/devices/vme_user.c b/drivers/staging/vme/devices/vme_user.c index 5dd430f8f921..d84dffb894f4 100644 --- a/drivers/staging/vme/devices/vme_user.c +++ b/drivers/staging/vme/devices/vme_user.c @@ -47,7 +47,7 @@ static const char driver_name[] = "vme_user"; static int bus[VME_USER_BUS_MAX]; static unsigned int bus_num; -/* Currently Documentation/devices.txt defines the following for VME: +/* Currently Documentation/admin-guide/devices.rst defines the following for VME: * * 221 char VME bus * 0 = /dev/bus/vme/m0 First master image diff --git a/drivers/video/fbdev/skeletonfb.c b/drivers/video/fbdev/skeletonfb.c index f948baa16d82..e219a0a22077 100644 --- a/drivers/video/fbdev/skeletonfb.c +++ b/drivers/video/fbdev/skeletonfb.c @@ -836,7 +836,7 @@ static void xxxfb_remove(struct pci_dev *dev) * @dev: PCI device * @msg: the suspend event code. * - * See Documentation/power/devices.txt for more information + * See Documentation/power/admin-guide/devices.rst for more information */ static int xxxfb_suspend(struct pci_dev *dev, pm_message_t msg) { @@ -851,7 +851,7 @@ static int xxxfb_suspend(struct pci_dev *dev, pm_message_t msg) * xxxfb_resume - Optional but recommended function. Resume the device. * @dev: PCI device * - * See Documentation/power/devices.txt for more information + * See Documentation/power/admin-guide/devices.rst for more information */ static int xxxfb_resume(struct pci_dev *dev) { @@ -915,7 +915,7 @@ static void __exit xxxfb_exit(void) * @dev: platform device * @msg: the suspend event code. * - * See Documentation/power/devices.txt for more information + * See Documentation/power/admin-guide/devices.rst for more information */ static int xxxfb_suspend(struct platform_device *dev, pm_message_t msg) { @@ -930,7 +930,7 @@ static int xxxfb_suspend(struct platform_device *dev, pm_message_t msg) * xxxfb_resume - Optional but recommended function. Resume the device. * @dev: platform device * - * See Documentation/power/devices.txt for more information + * See Documentation/power/admin-guide/devices.rst for more information */ static int xxxfb_resume(struct platform_dev *dev) { diff --git a/drivers/virtio/Kconfig b/drivers/virtio/Kconfig index 77590320d44c..623f72334fa5 100644 --- a/drivers/virtio/Kconfig +++ b/drivers/virtio/Kconfig @@ -75,7 +75,7 @@ config VIRTIO_MMIO_CMDLINE_DEVICES Allow virtio-mmio devices instantiation via the kernel command line or module parameters. Be aware that using incorrect parameters (base address in particular) can crash your system - you have been warned. - See Documentation/kernel-parameters.txt for details. + See Documentation/admin-guide/kernel-parameters.rst for details. If unsure, say 'N'. diff --git a/fs/Kconfig.binfmt b/fs/Kconfig.binfmt index 4c09d93d9569..b2f82cf6bf86 100644 --- a/fs/Kconfig.binfmt +++ b/fs/Kconfig.binfmt @@ -170,8 +170,8 @@ config BINFMT_MISC You can do other nice things, too. Read the file to learn how to use this - feature, for information about how - to include Java support. and for + feature, for information about how + to include Java support. and for information about how to include Mono-based .NET support. To use binfmt_misc, you will need to mount it: diff --git a/fs/pstore/Kconfig b/fs/pstore/Kconfig index be40813eff52..b42e5bd6d8ff 100644 --- a/fs/pstore/Kconfig +++ b/fs/pstore/Kconfig @@ -86,4 +86,4 @@ config PSTORE_RAM Note that for historical reasons, the module will be named "ramoops.ko". - For more information, see Documentation/ramoops.txt. + For more information, see Documentation/admin-guide/ramoops.rst. diff --git a/include/linux/device.h b/include/linux/device.h index bc41e87a969b..36d3a9867da9 100644 --- a/include/linux/device.h +++ b/include/linux/device.h @@ -733,7 +733,7 @@ struct device_dma_parameters { * minimizes board-specific #ifdefs in drivers. * @driver_data: Private pointer for driver specific info. * @power: For device power management. - * See Documentation/power/devices.txt for details. + * See Documentation/power/admin-guide/devices.rst for details. * @pm_domain: Provide callbacks that are executed during system suspend, * hibernation, system resume and during runtime PM transitions * along with subsystem-level and driver-level callbacks. diff --git a/include/linux/pm.h b/include/linux/pm.h index 06eb353182ab..efa67b2dfee9 100644 --- a/include/linux/pm.h +++ b/include/linux/pm.h @@ -258,7 +258,7 @@ typedef struct pm_message { * example, if it detects that a child was unplugged while the system was * asleep). * - * Refer to Documentation/power/devices.txt for more information about the role + * Refer to Documentation/power/admin-guide/devices.rst for more information about the role * of the above callbacks in the system suspend process. * * There also are callbacks related to runtime power management of devices. diff --git a/include/uapi/linux/major.h b/include/uapi/linux/major.h index 620252e69b44..19e195bee990 100644 --- a/include/uapi/linux/major.h +++ b/include/uapi/linux/major.h @@ -3,7 +3,7 @@ /* * This file has definitions for major device numbers. - * For the device number assignments, see Documentation/devices.txt. + * For the device number assignments, see Documentation/admin-guide/devices.rst. */ #define UNNAMED_MAJOR 0 diff --git a/init/Kconfig b/init/Kconfig index 34407f15e6d3..172f80ea0d58 100644 --- a/init/Kconfig +++ b/init/Kconfig @@ -1306,7 +1306,7 @@ config BLK_DEV_INITRD boot loader (loadlin or lilo) and that is mounted as root before the normal boot procedure. It is typically used to load modules needed to mount the "real" root file system, - etc. See for details. + etc. See for details. If RAM disk support (BLK_DEV_RAM) is also included, this also enables initial RAM disk (initrd) support and adds diff --git a/init/main.c b/init/main.c index 2858be732f6d..691eb9351a83 100644 --- a/init/main.c +++ b/init/main.c @@ -980,7 +980,7 @@ static int __ref kernel_init(void *unused) return 0; panic("No working init found. Try passing init= option to kernel. " - "See Linux Documentation/init.txt for guidance."); + "See Linux Documentation/admin-guide/init.rst for guidance."); } static noinline void __init kernel_init_freeable(void) diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug index 33bc56cf60d7..d2df3a93284b 100644 --- a/lib/Kconfig.debug +++ b/lib/Kconfig.debug @@ -13,7 +13,7 @@ config PRINTK_TIME be included, not that the timestamp is recorded. The behavior is also controlled by the kernel command line - parameter printk.time=1. See Documentation/kernel-parameters.txt + parameter printk.time=1. See Documentation/admin-guide/kernel-parameters.rst config MESSAGE_LOGLEVEL_DEFAULT int "Default message log level (1-7)" diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl index a8368d1c4348..d0c729ccec20 100755 --- a/scripts/checkpatch.pl +++ b/scripts/checkpatch.pl @@ -2187,7 +2187,7 @@ sub process { if ($rawline=~/^\+\+\+\s+(\S+)/) { $setup_docs = 0; - if ($1 =~ m@Documentation/kernel-parameters.txt$@) { + if ($1 =~ m@Documentation/admin-guide/kernel-parameters.rst$@) { $setup_docs = 1; } #next; @@ -5102,7 +5102,7 @@ sub process { my $asm_volatile = qr{\b(__asm__|asm)\s+(__volatile__|volatile)\b}; if ($line =~ /\bvolatile\b/ && $line !~ /$asm_volatile/) { WARN("VOLATILE", - "Use of volatile is usually wrong: see Documentation/volatile-considered-harmful.txt\n" . $herecurr); + "Use of volatile is usually wrong: see Documentation/process/volatile-considered-harmful.rst\n" . $herecurr); } # Check for user-visible strings broken across lines, which breaks the ability @@ -5817,7 +5817,7 @@ sub process { if (!grep(/$name/, @setup_docs)) { CHK("UNDOCUMENTED_SETUP", - "__setup appears un-documented -- check Documentation/kernel-parameters.txt\n" . $herecurr); + "__setup appears un-documented -- check Documentation/admin-guide/kernel-parameters.rst\n" . $herecurr); } } diff --git a/tools/testing/selftests/futex/README b/tools/testing/selftests/futex/README index 0558bb9ce0a6..f3926c33ed4c 100644 --- a/tools/testing/selftests/futex/README +++ b/tools/testing/selftests/futex/README @@ -59,4 +59,4 @@ o FIXME: decide on a sane test naming scheme. Currently the tests are named Coding Style ------------ o The Futex Test project adheres to the coding standards set forth by Linux - kernel as defined in the Linux source Documentation/CodingStyle. + kernel as defined in the Linux source Documentation/process/coding-style.rst. -- cgit v1.2.3 From 08a9a8d44c1c0e1b6d765a627b6f895dc6202e9b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 09:22:55 -0200 Subject: doc: re-add CodingStyle and SubmittingPatches Those files got moved to Documentation/process, but as they're very well known files, add pointers to their new locations. PS.: I opted to not merge this patch with the previous one in order to make the diff of the previous one more consistent, as it will show only renames. Signed-off-by: Mauro Carvalho Chehab --- Documentation/CodingStyle | 1 + Documentation/SubmittingPatches | 1 + 2 files changed, 2 insertions(+) create mode 100644 Documentation/CodingStyle create mode 100644 Documentation/SubmittingPatches diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle new file mode 100644 index 000000000000..320983ca114e --- /dev/null +++ b/Documentation/CodingStyle @@ -0,0 +1 @@ +This file has moved to process/coding-style.rst diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches new file mode 100644 index 000000000000..81455705e4a6 --- /dev/null +++ b/Documentation/SubmittingPatches @@ -0,0 +1 @@ +This file has moved to process/submitting-patches.rst -- cgit v1.2.3 From 6bef44b9b969a8bcf49f28a3079400ab1dac5769 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 10:46:38 -0200 Subject: README: add a new README file, pointing to the Documentation/ As we moved the real README file to Documentation/admin-guide/README.rst, let's add a replacement, pointing to it, and giving the main directions about documentation. In the future, perhaps it would be worth to move the contents of Documentation/00-Index into this README. Signed-off-by: Mauro Carvalho Chehab --- README | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 README diff --git a/README b/README new file mode 100644 index 000000000000..b2ba4aaa3a71 --- /dev/null +++ b/README @@ -0,0 +1,18 @@ +Linux kernel +============ + +This file was moved to Documentation/admin-guide/README.rst + +Please notice that there are several guides for kernel developers and users. +These guides can be rendered in a number of formats, like HTML and PDF. + +In order to build the documentation, use ``make htmldocs`` or +``make pdfdocs``. + +There are various text files in the Documentation/ subdirectory, +several of them using the Restructured Text markup notation. +See Documentation/00-INDEX for a list of what is contained in each file. + +Please read the Documentation/process/changes.rst file, as it contains the +requirements for building and running the kernel, and information about +the problems which may result by upgrading your kernel. -- cgit v1.2.3 From 3cbd4b543bef00c638fd63f6f043006c0c432f23 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 12:31:12 -0200 Subject: Documentation/00-INDEX: remove legacy media directories The dvb/ and video4linux/ dirs were removed, as now, all media documentation is under media/. Signed-off-by: Mauro Carvalho Chehab --- Documentation/00-INDEX | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 39caa6544d1f..903ebc494f29 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -166,8 +166,6 @@ dontdiff - file containing a list of files that should never be diff'ed. driver-model/ - directory with info about Linux driver model. -dvb/ - - info on Linux Digital Video Broadcast (DVB) subsystem. dynamic-debug-howto.txt - how to use the dynamic debug (dyndbg) feature. early-userspace/ @@ -458,8 +456,6 @@ vgaarbiter.txt - info on enable/disable the legacy decoding on different VGA devices video-output.txt - sysfs class driver interface to enable/disable a video output device. -video4linux/ - - directory with info regarding video/TV/radio cards and linux. virtual/ - directory with information on the various linux virtualizations. vm/ -- cgit v1.2.3 From 7b855a120b2281e74c8533faf3436e5233d83601 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Fri, 21 Oct 2016 23:10:02 +0900 Subject: locking/Doc/ko_KR: Clarify limited control-dependency scope This commit applies upstream change, commit ebff09a6ff16 ("locking/Documentation: Clarify limited control-dependency scope"), to Korean translation. Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet --- Documentation/ko_KR/memory-barriers.txt | 36 +++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/Documentation/ko_KR/memory-barriers.txt b/Documentation/ko_KR/memory-barriers.txt index 34d3d380893d..a3228a676cc1 100644 --- a/Documentation/ko_KR/memory-barriers.txt +++ b/Documentation/ko_KR/memory-barriers.txt @@ -823,6 +823,38 @@ CPU 는 b 로부터의 로드 오퍼레이션이 a 로부터의 로드 오퍼레 오퍼레이션을 위한 코드를 정말로 만들도록 하지만, 컴파일러가 그렇게 만들어진 코드의 수행 결과를 사용하도록 강제하지는 않습니다. +또한, 컨트롤 의존성은 if 문의 then 절과 else 절에 대해서만 적용됩니다. 상세히 +말해서, 컨트롤 의존성은 if 문을 뒤따르는 코드에는 적용되지 않습니다: + + q = READ_ONCE(a); + if (q) { + WRITE_ONCE(b, p); + } else { + WRITE_ONCE(b, r); + } + WRITE_ONCE(c, 1); /* BUG: No ordering against the read from "a". */ + +컴파일러는 volatile 타입에 대한 액세스를 재배치 할 수 없고 이 조건 하의 "b" +로의 쓰기를 재배치 할 수 없기 때문에 여기에 순서 규칙이 존재한다고 주장하고 +싶을 겁니다. 불행히도 이 경우에, 컴파일러는 다음의 가상의 pseudo-assembly 언어 +코드처럼 "b" 로의 두개의 쓰기 오퍼레이션을 conditional-move 인스트럭션으로 +번역할 수 있습니다: + + ld r1,a + ld r2,p + ld r3,r + cmp r1,$0 + cmov,ne r4,r2 + cmov,eq r4,r3 + st r4,b + st $1,c + +완화된 순서 규칙의 CPU 는 "a" 로부터의 로드와 "c" 로의 스토어 사이에 어떤 +종류의 의존성도 갖지 않을 겁니다. 이 컨트롤 의존성은 두개의 cmov 인스트럭션과 +거기에 의존하는 스토어 에게만 적용될 겁니다. 짧게 말하자면, 컨트롤 의존성은 +주어진 if 문의 then 절과 else 절에게만 (그리고 이 두 절 내에서 호출되는 +함수들에게까지) 적용되지, 이 if 문을 뒤따르는 코드에는 적용되지 않습니다. + 마지막으로, 컨트롤 의존성은 이행성 (transitivity) 을 제공하지 -않습니다-. 이건 x 와 y 가 둘 다 0 이라는 초기값을 가졌다는 가정 하의 두개의 예제로 보이겠습니다: @@ -883,6 +915,10 @@ http://www.cl.cam.ac.uk/users/pes20/ppc-supplemental/test6.pdf 와 의존성이 사라지지 않게 하는데 도움을 줄 수 있습니다. 더 많은 정보를 위해선 "컴파일러 배리어" 섹션을 참고하시기 바랍니다. + (*) 컨트롤 의존성은 컨트롤 의존성을 갖는 if 문의 then 절과 else 절과 이 두 절 + 내에서 호출되는 함수들에만 적용됩니다. 컨트롤 의존성은 컨트롤 의존성을 + 갖는 if 문을 뒤따르는 코드에는 적용되지 -않습니다-. + (*) 컨트롤 의존성은 보통 다른 타입의 배리어들과 짝을 맞춰 사용됩니다. (*) 컨트롤 의존성은 이행성을 제공하지 -않습니다-. 이행성이 필요하다면, -- cgit v1.2.3 From bb118c56fda53fbca71ee8f35ff870d35370c969 Mon Sep 17 00:00:00 2001 From: Igor Vuk Date: Tue, 25 Oct 2016 21:00:31 +0200 Subject: Documentation: cpu-hotplug: Fix typos Fix some minor spelling errors and capitalization issues. Signed-off-by: Igor Vuk Signed-off-by: Jonathan Corbet --- Documentation/cpu-hotplug.txt | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/Documentation/cpu-hotplug.txt b/Documentation/cpu-hotplug.txt index dd68821c22d4..d02e8a451872 100644 --- a/Documentation/cpu-hotplug.txt +++ b/Documentation/cpu-hotplug.txt @@ -84,9 +84,9 @@ are added or removed anytime. Trimming it accurately for your system needs upfront can save some boot time memory. See below for how we use heuristics in x86_64 case to keep this under check. -cpu_online_mask: Bitmap of all CPUs currently online. Its set in __cpu_up() -after a cpu is available for kernel scheduling and ready to receive -interrupts from devices. Its cleared when a cpu is brought down using +cpu_online_mask: Bitmap of all CPUs currently online. It's set in __cpu_up() +after a CPU is available for kernel scheduling and ready to receive +interrupts from devices. It's cleared when a CPU is brought down using __cpu_disable(), before which all OS services including interrupts are migrated to another target CPU. @@ -181,7 +181,7 @@ To support physical addition/removal, one would need some BIOS hooks and the platform should have something like an attention button in PCI hotplug. CONFIG_ACPI_HOTPLUG_CPU enables ACPI support for physical add/remove of CPUs. -Q: How do i logically offline a CPU? +Q: How do I logically offline a CPU? A: Do the following. #echo 0 > /sys/devices/system/cpu/cpuX/online @@ -191,15 +191,15 @@ Once the logical offline is successful, check #cat /proc/interrupts You should now not see the CPU that you removed. Also online file will report -the state as 0 when a cpu if offline and 1 when its online. +the state as 0 when a CPU is offline and 1 when it's online. #To display the current cpu state. #cat /sys/devices/system/cpu/cpuX/online -Q: Why can't i remove CPU0 on some systems? +Q: Why can't I remove CPU0 on some systems? A: Some architectures may have some special dependency on a certain CPU. -For e.g in IA64 platforms we have ability to sent platform interrupts to the +For e.g in IA64 platforms we have ability to send platform interrupts to the OS. a.k.a Corrected Platform Error Interrupts (CPEI). In current ACPI specifications, we didn't have a way to change the target CPU. Hence if the current ACPI version doesn't support such re-direction, we disable that CPU @@ -231,7 +231,7 @@ either by CONFIG_BOOTPARAM_HOTPLUG_CPU0 or by kernel parameter cpu0_hotplug. --Fenghua Yu -Q: How do i find out if a particular CPU is not removable? +Q: How do I find out if a particular CPU is not removable? A: Depending on the implementation, some architectures may show this by the absence of the "online" file. This is done if it can be determined ahead of time that this CPU cannot be removed. @@ -250,7 +250,7 @@ A: The following happen, listed in no particular order :-) - All processes are migrated away from this outgoing CPU to new CPUs. The new CPU is chosen from each process' current cpuset, which may be a subset of all online CPUs. -- All interrupts targeted to this CPU is migrated to a new CPU +- All interrupts targeted to this CPU are migrated to a new CPU - timers/bottom half/task lets are also migrated to a new CPU - Once all services are migrated, kernel calls an arch specific routine __cpu_disable() to perform arch specific cleanup. @@ -259,10 +259,10 @@ A: The following happen, listed in no particular order :-) CPU is being offlined). "It is expected that each service cleans up when the CPU_DOWN_PREPARE - notifier is called, when CPU_DEAD is called its expected there is nothing + notifier is called, when CPU_DEAD is called it's expected there is nothing running on behalf of this CPU that was offlined" -Q: If i have some kernel code that needs to be aware of CPU arrival and +Q: If I have some kernel code that needs to be aware of CPU arrival and departure, how to i arrange for proper notification? A: This is what you would need in your kernel code to receive notifications. @@ -311,7 +311,7 @@ things will happen if a notifier in path sent a BAD notify code. Q: I don't see my action being called for all CPUs already up and running? A: Yes, CPU notifiers are called only when new CPUs are on-lined or offlined. - If you need to perform some action for each cpu already in the system, then + If you need to perform some action for each CPU already in the system, then do this: for_each_online_cpu(i) { @@ -363,8 +363,8 @@ A: Yes, CPU notifiers are called only when new CPUs are on-lined or offlined. callbacks as well as initialize the already online CPUs. -Q: If i would like to develop cpu hotplug support for a new architecture, - what do i need at a minimum? +Q: If I would like to develop CPU hotplug support for a new architecture, + what do I need at a minimum? A: The following are what is required for CPU hotplug infrastructure to work correctly. @@ -382,8 +382,8 @@ A: The following are what is required for CPU hotplug infrastructure to work per_cpu state to be set, to ensure the processor dead routine is called to be sure positively. -Q: I need to ensure that a particular cpu is not removed when there is some - work specific to this cpu is in progress. +Q: I need to ensure that a particular CPU is not removed when there is some + work specific to this CPU in progress. A: There are two ways. If your code can be run in interrupt context, use smp_call_function_single(), otherwise use work_on_cpu(). Note that work_on_cpu() is slow, and can fail due to out of memory: -- cgit v1.2.3 From 452a256898e7ca88115aa02d3851e67994ce3e19 Mon Sep 17 00:00:00 2001 From: anish kumar Date: Sun, 23 Oct 2016 21:03:53 -0700 Subject: ASoC: Codec to codec dai link description Signed-off-by: anish kumar Acked-by: Charles Keepax Signed-off-by: Mark Brown --- Documentation/sound/alsa/soc/codec_to_codec.txt | 103 ++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 Documentation/sound/alsa/soc/codec_to_codec.txt diff --git a/Documentation/sound/alsa/soc/codec_to_codec.txt b/Documentation/sound/alsa/soc/codec_to_codec.txt new file mode 100644 index 000000000000..704a6483652c --- /dev/null +++ b/Documentation/sound/alsa/soc/codec_to_codec.txt @@ -0,0 +1,103 @@ +Creating codec to codec dai link for ALSA dapm +=================================================== + +Mostly the flow of audio is always from CPU to codec so your system +will look as below: + + --------- --------- +| | dai | | + CPU -------> codec +| | | | + --------- --------- + +In case your system looks as below: + --------- + | | + codec-2 + | | + --------- + | + dai-2 + | + ---------- --------- +| | dai-1 | | + CPU -------> codec-1 +| | | | + ---------- --------- + | + dai-3 + | + --------- + | | + codec-3 + | | + --------- + +Suppose codec-2 is a bluetooth chip and codec-3 is connected to +a speaker and you have a below scenario: +codec-2 will receive the audio data and the user wants to play that +audio through codec-3 without involving the CPU.This +aforementioned case is the ideal case when codec to codec +connection should be used. + +Your dai_link should appear as below in your machine +file: + +/* + * this pcm stream only supports 24 bit, 2 channel and + * 48k sampling rate. + */ +static const struct snd_soc_pcm_stream dsp_codec_params = { + .formats = SNDRV_PCM_FMTBIT_S24_LE, + .rate_min = 48000, + .rate_max = 48000, + .channels_min = 2, + .channels_max = 2, +}; + +{ + .name = "CPU-DSP", + .stream_name = "CPU-DSP", + .cpu_dai_name = "samsung-i2s.0", + .codec_name = "codec-2, + .codec_dai_name = "codec-2-dai_name", + .platform_name = "samsung-i2s.0", + .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF + | SND_SOC_DAIFMT_CBM_CFM, + .ignore_suspend = 1, + .params = &dsp_codec_params, +}, +{ + .name = "DSP-CODEC", + .stream_name = "DSP-CODEC", + .cpu_dai_name = "wm0010-sdi2", + .codec_name = "codec-3, + .codec_dai_name = "codec-3-dai_name", + .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF + | SND_SOC_DAIFMT_CBM_CFM, + .ignore_suspend = 1, + .params = &dsp_codec_params, +}, + +Above code snippet is motivated from sound/soc/samsung/speyside.c. + +Note the "params" callback which lets the dapm know that this +dai_link is a codec to codec connection. + +In dapm core a route is created between cpu_dai playback widget +and codec_dai capture widget for playback path and vice-versa is +true for capture path. In order for this aforementioned route to get +triggered, DAPM needs to find a valid endpoint which could be either +a sink or source widget corresponding to playback and capture path +respectively. + +In order to trigger this dai_link widget, a thin codec driver for +the speaker amp can be created as demonstrated in wm8727.c file, it +sets appropriate constraints for the device even if it needs no control. + +Make sure to name your corresponding cpu and codec playback and capture +dai names ending with "Playback" and "Capture" respectively as dapm core +will link and power those dais based on the name. + +Note that in current device tree there is no way to mark a dai_link +as codec to codec. However, it may change in future. -- cgit v1.2.3 From c289312f964b6e8851d0812b65f59c8b0387e78d Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 26 Oct 2016 08:23:14 +0200 Subject: doc-rst: make dev-tools folder buildable stand-alone Add minimal conf.py and moved dev-tools/tools.rst to dev-tools/index.rst makes the dev-tools folder buildable stand-alone. To build only this folder run:: make SPHINXDIRS=dev-tools htmldocs make SPHINXDIRS=dev-tools pdfdocs Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/dev-tools/conf.py | 10 ++++++++++ Documentation/dev-tools/index.rst | 33 +++++++++++++++++++++++++++++++++ Documentation/dev-tools/tools.rst | 25 ------------------------- Documentation/index.rst | 2 +- 4 files changed, 44 insertions(+), 26 deletions(-) create mode 100644 Documentation/dev-tools/conf.py create mode 100644 Documentation/dev-tools/index.rst delete mode 100644 Documentation/dev-tools/tools.rst diff --git a/Documentation/dev-tools/conf.py b/Documentation/dev-tools/conf.py new file mode 100644 index 000000000000..7faafa3f7888 --- /dev/null +++ b/Documentation/dev-tools/conf.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8; mode: python -*- + +project = "Development tools for the kernel" + +tags.add("subproject") + +latex_documents = [ + ('index', 'dev-tools.tex', project, + 'The kernel development community', 'manual'), +] diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst new file mode 100644 index 000000000000..07d881147ef3 --- /dev/null +++ b/Documentation/dev-tools/index.rst @@ -0,0 +1,33 @@ +================================ +Development tools for the kernel +================================ + +This document is a collection of documents about development tools that can +be used to work on the kernel. For now, the documents have been pulled +together without any significant effot to integrate them into a coherent +whole; patches welcome! + +.. class:: toc-title + + Table of contents + +.. toctree:: + :maxdepth: 2 + + coccinelle + sparse + kcov + gcov + kasan + ubsan + kmemleak + kmemcheck + gdb-kernel-debugging + + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/dev-tools/tools.rst b/Documentation/dev-tools/tools.rst deleted file mode 100644 index 824ae8e54dd5..000000000000 --- a/Documentation/dev-tools/tools.rst +++ /dev/null @@ -1,25 +0,0 @@ -================================ -Development tools for the kernel -================================ - -This document is a collection of documents about development tools that can -be used to work on the kernel. For now, the documents have been pulled -together without any significant effot to integrate them into a coherent -whole; patches welcome! - -.. class:: toc-title - - Table of contents - -.. toctree:: - :maxdepth: 2 - - coccinelle - sparse - kcov - gcov - kasan - ubsan - kmemleak - kmemcheck - gdb-kernel-debugging diff --git a/Documentation/index.rst b/Documentation/index.rst index f6a3d4766495..0f98823126f2 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -14,7 +14,7 @@ Contents: admin-guide/index kernel-documentation process/index - dev-tools/tools + dev-tools/index driver-api/index media/index gpu/index -- cgit v1.2.3 From 241a8021c60fb19d9d8524d2f6d0d5a52a1e056f Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 26 Oct 2016 08:23:15 +0200 Subject: doc-rst: make driver-api folder buildable stand-alone Add minimal conf.py makes the driver-api folder buildable stand-alone. To build only this folder run:: make SPHINXDIRS=driver-api htmldocs make SPHINXDIRS=driver-api pdfdocs Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/driver-api/conf.py | 10 ++++++++++ Documentation/driver-api/index.rst | 8 ++++++++ 2 files changed, 18 insertions(+) create mode 100644 Documentation/driver-api/conf.py diff --git a/Documentation/driver-api/conf.py b/Documentation/driver-api/conf.py new file mode 100644 index 000000000000..202726d20088 --- /dev/null +++ b/Documentation/driver-api/conf.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8; mode: python -*- + +project = "The Linux driver implementer's API guide" + +tags.add("subproject") + +latex_documents = [ + ('index', 'driver-api.tex', project, + 'The kernel development community', 'manual'), +] diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index b567907db350..e18135b513e2 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -25,3 +25,11 @@ available subsections can be seen below. hsi miscellaneous vme + + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` -- cgit v1.2.3 From 6f2ec3a9d5489e2b54c63ca648bb00d0857c7a96 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 26 Oct 2016 08:23:16 +0200 Subject: doc-rst: include index only in subproject AND html The index should only be included if the build of the sub-folder is done with the html-builder (HTML output). Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/80211/index.rst | 2 +- Documentation/admin-guide/index.rst | 8 ++++++++ Documentation/gpu/index.rst | 2 +- Documentation/process/index.rst | 8 ++++++++ 4 files changed, 18 insertions(+), 2 deletions(-) diff --git a/Documentation/80211/index.rst b/Documentation/80211/index.rst index 90bba476f442..af210859d3e1 100644 --- a/Documentation/80211/index.rst +++ b/Documentation/80211/index.rst @@ -9,7 +9,7 @@ Linux 802.11 Driver Developer's Guide mac80211 mac80211-advanced -.. only:: subproject +.. only:: subproject and html Indices ======= diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 4e5abbb4bbd5..fb779e67097b 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -32,3 +32,11 @@ Contents: java bad-memory basic-profiling + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` + diff --git a/Documentation/gpu/index.rst b/Documentation/gpu/index.rst index be0dafcf5556..367d7c36b8e9 100644 --- a/Documentation/gpu/index.rst +++ b/Documentation/gpu/index.rst @@ -14,7 +14,7 @@ Linux GPU Driver Developer's Guide vga-switcheroo vgaarbiter -.. only:: subproject +.. only:: subproject and html Indices ======= diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 6ee818752474..cddf580671e7 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -30,3 +30,11 @@ Contents: volatile-considered-harmful development-process + + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` -- cgit v1.2.3 From fdd91a3dfadfa73bbb54702f1e951e7c17a507d6 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 26 Oct 2016 08:23:17 +0200 Subject: doc-rst: build PDF of 80211 and gpu sub-project This allows to build PDF of only the sub-projects, which reduce the roundtrip compared to build the PDF from the main documentation. Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/80211/conf.py | 5 +++++ Documentation/gpu/conf.py | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/Documentation/80211/conf.py b/Documentation/80211/conf.py index 20c7c275ef4a..4424b4b0b9c3 100644 --- a/Documentation/80211/conf.py +++ b/Documentation/80211/conf.py @@ -3,3 +3,8 @@ project = "Linux 802.11 Driver Developer's Guide" tags.add("subproject") + +latex_documents = [ + ('index', '80211.tex', project, + 'The kernel development community', 'manual'), +] diff --git a/Documentation/gpu/conf.py b/Documentation/gpu/conf.py index 6314d1708230..1757b040fb32 100644 --- a/Documentation/gpu/conf.py +++ b/Documentation/gpu/conf.py @@ -3,3 +3,8 @@ project = "Linux GPU Driver Developer's Guide" tags.add("subproject") + +latex_documents = [ + ('index', 'gpu.tex', project, + 'The kernel development community', 'manual'), +] -- cgit v1.2.3 From b51208d41c6a4e7fc2f05e63df49f1834cd3c208 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 15:43:00 -0600 Subject: docs: Tweak the top-level Sphinx page This will be the initial landing point for readers, so give them a bit of introductory material. Also split the TOC into area-specific chunks to make the whole thing a bit more approachable. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 45 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 41 insertions(+), 4 deletions(-) diff --git a/Documentation/index.rst b/Documentation/index.rst index f6a3d4766495..7cec8432ce7a 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -3,18 +3,55 @@ 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! -============================================ +Welcome to The Linux Kernel's documentation +=========================================== -Contents: +This is the top level of the kernel's documentation tree. Kernel +documentation, like the kernel itself, is very much a work in progress; +that is especially true as we work to integrate our many scattered +documents into a coherent whole. Please note that improvements to the +documentation are welcome; join the linux-doc list at vger.kernel.org if +you want to help out. + +User-oriented documentation +--------------------------- + +The following manuals are written for *users* of the kernel — those who are +trying to get it to work optimally on a given system. .. toctree:: :maxdepth: 2 admin-guide/index - kernel-documentation + +Introduction to kernel development +---------------------------------- + +These manuals contain overall information about how to develop the kernel. +The kernel community is quite large, with thousands of developers +contributing over the course of a year. As with any large community, +knowing how things are done will make the process of getting your changes +merged much easier. + +.. toctree:: + :maxdepth: 2 + process/index dev-tools/tools + kernel-documentation + +Kernel API documentation +------------------------ + +These books get into the details of how specific kernel subsystems work +from the point of view of a kernel developer. Much of the information here +is taken directly from the kernel source, with supplemental material added +as needed (or at least as we managed to add it — probably *not* all that is +needed). + +.. toctree:: + :maxdepth: 2 + driver-api/index media/index gpu/index -- cgit v1.2.3 From 555af62431e69105b4d20628181acf414759a70d Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 15:55:20 -0600 Subject: docs: retitle the kernel-documentation.rst Let's make the title of this document (which shows up in the top page) better describe its contents. Cc: Jani Nikula Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/kernel-documentation.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst index 10cc7ddb6235..c66ab937c2ca 100644 --- a/Documentation/kernel-documentation.rst +++ b/Documentation/kernel-documentation.rst @@ -1,6 +1,6 @@ -========================== -Linux Kernel Documentation -========================== +================================= +How to write kernel documentation +================================= Introduction ============ -- cgit v1.2.3 From 7358bb2f3293461737a61850c56523695f5b2219 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:14:52 -0600 Subject: docs: Clean up and organize the admin guide a bit The admin guide is a good start, but it's time to turn it into something better than an unordered blob of files. This is a first step in that direction. The TOC has been split up and annotated, the guides have been reordered, and minor tweaks have been applied to a few of them. One consequence of splitting up the TOC is that we don't really want to use :numbered: anymore, since the count resets every time and there doesn't seem to be a way to change that. Eventually we probably want to group the documents into sub-books, at which point we can go back to a single TOC, but it's probably early to do that. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/index.rst | 50 +++++++++++++++++++------ Documentation/admin-guide/kernel-parameters.rst | 4 +- Documentation/admin-guide/sysfs-rules.rst | 4 +- Documentation/admin-guide/vga-softcursor.rst | 4 +- 4 files changed, 45 insertions(+), 17 deletions(-) diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 4e5abbb4bbd5..2ce2bf02824b 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -1,22 +1,52 @@ -Linux Kernel User's Documentation -================================= +The Linux kernel user's and administrator's guide +================================================= -Contents: +The following is a collection of user-oriented documents that have been +added to the kernel over time. There is, as yet, little overall order or +organization here — this material was not written to be a single, coherent +document! With luck things will improve quickly over time. + +This initial section contains overall information, including the README +file describing the kernel as a whole, documentation on kernel parameters, +etc. .. toctree:: - :maxdepth: 2 - :numbered: + :maxdepth: 1 README + kernel-parameters + devices + +Here is a set of documents aimed at users who are trying to track down +problems and bugs in particular. + +.. toctree:: + :maxdepth: 1 + reporting-bugs + security-bugs bug-hunting oops-tracing ramoops - initrd - init dynamic-debug-howto - security-bugs - kernel-parameters + init + +This is the beginning of a section with information of interest to +application developers. Documents covering various aspects of the kernel +ABI will be found here. + +.. toctree:: + :maxdepth: 1 + + sysfs-rules + +The rest of this manual consists of various unordered guides on how to +configure specific aspects of kernel behavior to your liking. + +.. toctree:: + :maxdepth: 1 + + initrd serial-console braille-console parport @@ -25,8 +55,6 @@ Contents: sysrq unicode vga-softcursor - sysfs-rules - devices binfmt-misc mono java diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index d2f2725f032e..37105aedb2e4 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -1,5 +1,5 @@ -Kernel Parameters -~~~~~~~~~~~~~~~~~ +The kernel's command-line parameters +==================================== The following is a consolidated list of the kernel parameters as implemented by the __setup(), core_param() and module_param() macros diff --git a/Documentation/admin-guide/sysfs-rules.rst b/Documentation/admin-guide/sysfs-rules.rst index 04bdd52cba1d..abad33526aca 100644 --- a/Documentation/admin-guide/sysfs-rules.rst +++ b/Documentation/admin-guide/sysfs-rules.rst @@ -1,5 +1,5 @@ -Rules on how to access information in the Linux kernel sysfs -============================================================ +Rules on how to access information in sysfs +=========================================== The kernel-exported sysfs exports internal kernel implementation details and depends on internal kernel structures and layout. It is agreed upon diff --git a/Documentation/admin-guide/vga-softcursor.rst b/Documentation/admin-guide/vga-softcursor.rst index 9eac6744b3a1..a663a745cff4 100644 --- a/Documentation/admin-guide/vga-softcursor.rst +++ b/Documentation/admin-guide/vga-softcursor.rst @@ -50,8 +50,8 @@ third parameter .. [#f1] see ``#define TRIDENT_GLITCH`` in ``drivers/video/vgacon.c``. -Examples: -========= +Examples +-------- To get normal blinking underline, use:: -- cgit v1.2.3 From 2c79dcafd8ecdfd44ee4c509a9c55785b022eba9 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:20:27 -0600 Subject: docs: Get rid of the badRAM guide The last release of this tool was for 2.6.28; it's hard to see how it has any relevance to current kernels. Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/bad-memory.rst | 50 -------------------------------- Documentation/admin-guide/index.rst | 1 - 2 files changed, 51 deletions(-) delete mode 100644 Documentation/admin-guide/bad-memory.rst diff --git a/Documentation/admin-guide/bad-memory.rst b/Documentation/admin-guide/bad-memory.rst deleted file mode 100644 index a5c0e25e496f..000000000000 --- a/Documentation/admin-guide/bad-memory.rst +++ /dev/null @@ -1,50 +0,0 @@ -How to deal with bad memory e.g. reported by memtest86+ ? -========================================================= - -March 2008 -Jan-Simon Moeller, dl9pf@gmx.de - - - -There are three possibilities I know of: - -1) Reinsert/swap the memory modules - -2) Buy new modules (best!) or try to exchange the memory - if you have spare-parts - -3) Use BadRAM or memmap - -This Howto is about number 3) . - - -BadRAM -###### - -BadRAM is the actively developed and available as kernel-patch -here: http://rick.vanrein.org/linux/badram/ - -For more details see the BadRAM documentation. - -memmap -###### - -memmap is already in the kernel and usable as kernel-parameter at -boot-time. Its syntax is slightly strange and you may need to -calculate the values by yourself! - -Syntax to exclude a memory area (see admin-guide/kernel-parameters.rst for details):: - - memmap=$
- -Example: memtest86+ reported here errors at address 0x18691458, 0x18698424 and -some others. All had 0x1869xxxx in common, so I chose a pattern of -0x18690000,0xffff0000. - -With the numbers of the example above:: - - memmap=64K$0x18690000 - -or:: - - memmap=0x10000$0x18690000 diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 2ce2bf02824b..d737ae71efc6 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -58,5 +58,4 @@ configure specific aspects of kernel behavior to your liking. binfmt-misc mono java - bad-memory basic-profiling -- cgit v1.2.3 From 5700d1974818a98983e018efa01da9bc81b84e1a Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:22:01 -0600 Subject: docs: Get rid of the "basic profiling" guide The document has not been touched in over 11 years and doesn't reflect how profiling is done in the perf era. Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/basic-profiling.rst | 68 --------------------------- Documentation/admin-guide/index.rst | 1 - 2 files changed, 69 deletions(-) delete mode 100644 Documentation/admin-guide/basic-profiling.rst diff --git a/Documentation/admin-guide/basic-profiling.rst b/Documentation/admin-guide/basic-profiling.rst deleted file mode 100644 index 72babc71b771..000000000000 --- a/Documentation/admin-guide/basic-profiling.rst +++ /dev/null @@ -1,68 +0,0 @@ -Basic kernel profiling -====================== - - -These instructions are deliberately very basic. If you want something clever, -go read the real docs ;-) - -Please don't add more stuff, but feel free to -correct my mistakes ;-) (mbligh@aracnet.com) - -Thanks to John Levon, Dave Hansen, et al. for help writing this. - -```` is the thing you're trying to measure. -Make sure you have the correct ``System.map`` / ``vmlinux`` referenced! - -It is probably easiest to use ``make install`` for linux and hack -``/sbin/installkernel`` to copy ``vmlinux`` to ``/boot``, in addition to -``vmlinuz``, ``config``, ``System.map``, which are usually installed by default. - -Readprofile ------------ - -A recent ``readprofile`` command is needed for 2.6, such as found in util-linux -2.12a, which can be downloaded from: - - http://www.kernel.org/pub/linux/utils/util-linux/ - -Most distributions will ship it already. - -Add ``profile=2`` to the kernel command line. - -Some ``readprofile`` commands:: - - clear readprofile -r - - dump output readprofile -m /boot/System.map > captured_profile - -Oprofile --------- - -Get the source (see Changes for required version) from -http://oprofile.sourceforge.net/ and add ``idle=poll`` to the kernel command -line. - -Configure with ``CONFIG_PROFILING=y`` and ``CONFIG_OPROFILE=y`` & reboot on new kernel:: - - ./configure --with-kernel-support - make install - -For superior results, be sure to enable the local APIC. If opreport sees -a 0Hz CPU, APIC was not on. Be aware that idle=poll may mean a performance -penalty. - -One time setup:: - - opcontrol --setup --vmlinux=/boot/vmlinux - -Some ``opcontrol`` commands:: - - clear opcontrol --reset - start opcontrol --start - - stop opcontrol --stop - dump output opreport > output_file - -To only report on the kernel, run ``opreport -l /boot/vmlinux > output_file`` - -A reset is needed to clear old statistics, which survive a reboot. diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index d737ae71efc6..2872c0c70ea4 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -58,4 +58,3 @@ configure specific aspects of kernel behavior to your liking. binfmt-misc mono java - basic-profiling -- cgit v1.2.3 From 9b4ebd98da9112f974a6db58555a33eb1bd7c0b0 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:34:09 -0600 Subject: docs: Apply some basic organization to the process guide Put like documents together, with the essential ones at the top, and split the TOC into sections. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/process/changes.rst | 2 +- Documentation/process/index.rst | 37 ++++++++++++++++++++++++++++--------- 2 files changed, 29 insertions(+), 10 deletions(-) diff --git a/Documentation/process/changes.rst b/Documentation/process/changes.rst index 22797a15dc24..56ce66114665 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -1,6 +1,6 @@ .. _changes: -Minimal requerements to compile the Kernel +Minimal requirements to compile the Kernel ++++++++++++++++++++++++++++++++++++++++++ Intro diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 6ee818752474..0cbc62adbbb1 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -4,29 +4,48 @@ \renewcommand\thesubsection* -Linux Kernel Development Documentation -====================================== +Working with the kernel development community +============================================= -Contents: +So you want to be a Linux kernel developer? Welcome! While there is a lot +to be learned about the kernel in a technical sense, it is also important +to learn about how our community works. Reading these documents will make +it much easier for you to get your changes merged with a minimum of +trouble. + +Below are the essential guides that every developer should read. .. toctree:: :maxdepth: 2 howto - changes - coding-style + code-of-conflict + development-process submitting-patches + coding-style + email-clients + +Other guides to the community that are of interest to most developers are: + +.. toctree:: + :maxdepth: 2 + + changes submitting-drivers stable-api-nonsense management-style stable-kernel-rules + submit-checklist kernel-docs + +These are some overall technical guides that have been put here for now for +lack of a better place. + +.. toctree:: + :maxdepth: 2 + applying-patches - email-clients - submit-checklist - code-of-conflict adding-syscalls magic-number volatile-considered-harmful - development-process -- cgit v1.2.3 From 89edeedd61e8faa4e092f3797606739317abeb6c Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:37:53 -0600 Subject: docs: Tweak submitting-patches.rst formatting The main goal here was to get the subsections to show in the TOC as they do for all the other documents. Also call out the DCO in the section title since it's important. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/process/submitting-patches.rst | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index b4cf8f375184..3e10719fee35 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -1,7 +1,7 @@ .. _submittingpatches: -How to Get Your Change Into the Linux Kernel or Care And Operation Of Your Linus Torvalds -========================================================================================= +Submitting patches: the essential guide to getting your code into the kernel +============================================================================ For a person or company who wishes to submit a change to the Linux kernel, the process can sometimes be daunting if you're not familiar @@ -24,10 +24,6 @@ of the mechanical work done for you, though you'll still need to prepare and document a sensible set of patches. In general, use of ``git`` will make your life as a kernel developer easier. -Creating and Sending your Change -******************************** - - 0) Obtain a current source tree ------------------------------- @@ -417,8 +413,8 @@ e-mail discussions. -11) Sign your work ------------------- +11) Sign your work — the Developer's Certificate of Origin +---------------------------------------------------------- To improve tracking of who did what, especially with patches that can percolate to their final resting place in the kernel through several @@ -803,8 +799,8 @@ command like this will do the trick:: git request-pull master git://my.public.tree/linux.git my-signed-tag -REFERENCES -********** +References +---------- Andrew Morton, "The perfect patch" (tpp). -- cgit v1.2.3 From be4612447b3721a9a9f14ea5189217d69bc83078 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:41:05 -0600 Subject: docs: Collapse the process guide TOC I believe this makes the page as a whole more approachable. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/process/index.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index 0cbc62adbbb1..0557144cef2b 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -16,7 +16,7 @@ trouble. Below are the essential guides that every developer should read. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 howto code-of-conflict @@ -28,7 +28,7 @@ Below are the essential guides that every developer should read. Other guides to the community that are of interest to most developers are: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 changes submitting-drivers @@ -42,7 +42,7 @@ These are some overall technical guides that have been put here for now for lack of a better place. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 applying-patches adding-syscalls -- cgit v1.2.3 From 31b24bee33572031632c33091bb73ed0e949c53a Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:45:29 -0600 Subject: docs: add a warning to submitting-drivers.rst This is crufty stuff and should maybe just be deleted, but I'm not quite ready to do that yet. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/process/submitting-drivers.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst index 0939d018c289..afb82ee0cbea 100644 --- a/Documentation/process/submitting-drivers.rst +++ b/Documentation/process/submitting-drivers.rst @@ -8,6 +8,14 @@ various kernel trees. Note that if you are interested in video card drivers you should probably talk to XFree86 (http://www.xfree86.org/) and/or X.Org (http://x.org/) instead. +.. note:: + + This document is old and has seen little maintenance in recent years; it + should probably be updated or, perhaps better, just deleted. Most of + what is here can be found in the other development documents anyway. + + Oh, and we don't really recommend submitting changes to XFree86 :) + Also read the Documentation/process/submitting-patches.rst document. -- cgit v1.2.3 From 67972a539e9ff1a3ed794c463c4e544442df693e Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:48:36 -0600 Subject: docs: Add a warning to applying-patches.rst This is ancient stuff and we don't do things this way anymore. In the absence of simply deleting the document, at least add a warning to it. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/process/applying-patches.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/process/applying-patches.rst b/Documentation/process/applying-patches.rst index abd7dc7ae240..87825cf96f33 100644 --- a/Documentation/process/applying-patches.rst +++ b/Documentation/process/applying-patches.rst @@ -9,6 +9,10 @@ Original by: Last update: 2016-09-14 +.. note:: + + This document is obsolete. In most cases, rather than using ``patch`` + manually, you'll almost certainly want to look at using Git instead. A frequently asked question on the Linux Kernel Mailing List is how to apply a patch to the kernel or, more specifically, what base kernel a patch for -- cgit v1.2.3 From 2797cd03f5cca4d9fb2875c9f9c995737ce73469 Mon Sep 17 00:00:00 2001 From: Oliver Neukum Date: Thu, 20 Oct 2016 15:15:00 +0200 Subject: USB: update intro of documentation It does no good to mention The 2.4 kernel series and neglect USB 3.x and XHCI. Also with type C and micro/mini USB we better not talk about the shape of connectors. Signed-off-by: Oliver Neukum Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- Documentation/DocBook/usb.tmpl | 68 +++++++++++++++++++----------------------- 1 file changed, 30 insertions(+), 38 deletions(-) diff --git a/Documentation/DocBook/usb.tmpl b/Documentation/DocBook/usb.tmpl index bc776be0f19c..8ec4d595b218 100644 --- a/Documentation/DocBook/usb.tmpl +++ b/Documentation/DocBook/usb.tmpl @@ -47,39 +47,24 @@ root (the system's master), hubs as interior nodes, and peripherals as leaves (and slaves). Modern PCs support several such trees of USB devices, usually - one USB 2.0 tree (480 Mbit/sec each) with - a few USB 1.1 trees (12 Mbit/sec each) that are used when you - connect a USB 1.1 device directly to the machine's "root hub". + a few USB 3.0 (5 GBit/s) or USB 3.1 (10 GBit/s) and some legacy + USB 2.0 (480 MBit/s) busses just in case. That master/slave asymmetry was designed-in for a number of reasons, one being ease of use. It is not physically possible to - assemble (legal) USB cables incorrectly: all upstream "to the host" - connectors are the rectangular type (matching the sockets on - root hubs), and all downstream connectors are the squarish type + mistake upstream and downstream or it does not matter with a type C + plug (or they are built into the peripheral). Also, the host software doesn't need to deal with distributed auto-configuration since the pre-designated master node manages all that. - And finally, at the electrical level, bus protocol overhead is reduced by - eliminating arbitration and moving scheduling into the host software. - - - USB 1.0 was announced in January 1996 and was revised - as USB 1.1 (with improvements in hub specification and - support for interrupt-out transfers) in September 1998. - USB 2.0 was released in April 2000, adding high-speed - transfers and transaction-translating hubs (used for USB 1.1 - and 1.0 backward compatibility). Kernel developers added USB support to Linux early in the 2.2 kernel - series, shortly before 2.3 development forked. Updates from 2.3 were - regularly folded back into 2.2 releases, which improved reliability and - brought /sbin/hotplug support as well more drivers. - Such improvements were continued in the 2.5 kernel series, where they added - USB 2.0 support, improved performance, and made the host controller drivers - (HCDs) more consistent. They also simplified the API (to make bugs less - likely) and added internal "kerneldoc" documentation. + series and have been developing it further since then. Besides support + for each new generation of USB, various host controllers gained support, + new drivers for peripherals have been added and advanced features for latency + measurement and improved power management introduced. Linux can run inside USB devices as well as on @@ -121,12 +106,17 @@ The device description model includes one or more "configurations" per device, only one of which is active at a time. - Devices that are capable of high-speed operation must also support - full-speed configurations, along with a way to ask about the - "other speed" configurations which might be used. + Devices are supposed to be capable of operating at lower than their top + speeds and may provide a BOS descriptor showing the lowest speed they + remain fully operational at. + + + From USB 3.0 on configurations have one or more "functions", which + provide a common functionality and are grouped together for purposes + of power management. - Configurations have one or more "interfaces", each + Configurations or functions have one or more "interfaces", each of which may have "alternate settings". Interfaces may be standardized by USB "Class" specifications, or may be specific to a vendor or device. @@ -135,7 +125,7 @@ Think of them as "interface drivers", though you may not see many devices where the distinction is important. Most USB devices are simple, with only one configuration, - one interface, and one alternate setting. + one function, one interface, and one alternate setting. Interfaces have one or more "endpoints", each of @@ -161,26 +151,25 @@ Accordingly, the USB Core API exposed to device drivers covers quite a lot of territory. You'll probably need to consult - the USB 2.0 specification, available online from www.usb.org at + the USB 3.0 specification, available online from www.usb.org at no cost, as well as class or device specifications. The only host-side drivers that actually touch hardware (reading/writing registers, handling IRQs, and so on) are the HCDs. In theory, all HCDs provide the same functionality through the same - API. In practice, that's becoming more true on the 2.5 kernels, + API. In practice, that's becoming mostly true, but there are still differences that crop up especially with - fault handling. Different controllers don't necessarily report + fault handling on the less common controllers. + Different controllers don't necessarily report the same aspects of failures, and recovery from faults (including software-induced ones like unlinking an URB) isn't yet fully consistent. Device driver authors should make a point of doing disconnect testing (while the device is active) with each different host controller driver, to make sure drivers don't have bugs of - their own as well as to make sure they aren't relying on some + thei1r own as well as to make sure they aren't relying on some HCD-specific behavior. - (You will need external USB 1.1 and/or - USB 2.0 hubs to perform all those tests.) @@ -216,7 +205,7 @@ There are two basic I/O models in the USB API. The most elemental one is asynchronous: drivers submit requests in the form of an URB, and the URB's completion callback - handle the next step. + handles the next step. All USB transfer types support that model, although there are special cases for control URBs (which always have setup and status stages, but may not have a data stage) and @@ -252,7 +241,7 @@ These APIs are only for use by host controller drivers, most of which implement standard register interfaces such as - EHCI, OHCI, or UHCI. + XHCI, EHCI, OHCI, or UHCI. UHCI was one of the first interfaces, designed by Intel and also used by VIA; it doesn't do much in hardware. OHCI was designed later, to have the hardware do more work @@ -260,13 +249,16 @@ EHCI was designed with USB 2.0; its design has features that resemble OHCI (hardware does much more work) as well as UHCI (some parts of ISO support, TD list processing). + XHCI was designed with USB 3.0. It continues to shift support + for functionality into hardware. There are host controllers other than the "big three", although most PCI based controllers (and a few non-PCI based ones) use one of those interfaces. Not all host controllers use DMA; some use PIO, and there - is also a simulator. + is also a simulator and a virtual host controller to pipe + USB over the network. The same basic APIs are available to drivers for all @@ -275,7 +267,7 @@ struct usb_bus is a rather thin layer that became available in the 2.2 kernels, while struct usb_hcd is a more featureful - layer (available in later 2.4 kernels and in 2.5) that + layer that lets HCDs share common code, to shrink driver size and significantly reduce hcd-specific behaviors. -- cgit v1.2.3 From c950a1739eaef2ab64372fc35af7301fcef2c9a7 Mon Sep 17 00:00:00 2001 From: Silvio Fricke Date: Fri, 28 Oct 2016 10:14:08 +0200 Subject: kernel-doc: better parsing of named variable arguments Without this patch we get warnings for named variable arguments. warning: No description found for parameter '...' warning: Excess function parameter 'args' description in 'alloc_ordered_workqueue' Signed-off-by: Silvio Fricke Reviewed-by: Jani Nikula --- scripts/kernel-doc | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 93721f3c91bf..e10378f769f9 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -204,6 +204,7 @@ EOF ## init lots of data + my $errors = 0; my $warnings = 0; my $anon_struct_union = 0; @@ -211,7 +212,7 @@ my $anon_struct_union = 0; # match expressions used to find embedded type information my $type_constant = '\%([-_\w]+)'; my $type_func = '(\w+)\(\)'; -my $type_param = '\@(\w+)'; +my $type_param = '\@(\w+(\.\.\.)?)'; my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params my $type_struct = '\&((struct\s*)*[_\w]+)'; my $type_struct_xml = '\\&((struct\s*)*[_\w]+)'; @@ -2353,7 +2354,10 @@ sub push_parameter($$$) { if ($type eq "" && $param =~ /\.\.\.$/) { - $param = "..."; + if (!$param =~ /\w\.\.\.$/) { + # handles unnamed variable parameters + $param = "..."; + } if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") { $parameterdescs{$param} = "variable arguments"; } -- cgit v1.2.3 From 42412c3aae5d8ea57a46b8ff86bb67bc1a270d9c Mon Sep 17 00:00:00 2001 From: Silvio Fricke Date: Fri, 28 Oct 2016 10:14:09 +0200 Subject: workqueue: kerneldocify workqueue_attrs Only formating changes. Signed-off-by: Silvio Fricke Acked-by: Tejun Heo Signed-off-by: Jonathan Corbet --- include/linux/workqueue.h | 35 ++++++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/include/linux/workqueue.h b/include/linux/workqueue.h index fc6e22186405..d4f16cf6281c 100644 --- a/include/linux/workqueue.h +++ b/include/linux/workqueue.h @@ -119,18 +119,30 @@ struct delayed_work { int cpu; }; -/* - * A struct for workqueue attributes. This can be used to change - * attributes of an unbound workqueue. +/** + * struct workqueue_attrs - A struct for workqueue attributes. * - * Unlike other fields, ->no_numa isn't a property of a worker_pool. It - * only modifies how apply_workqueue_attrs() select pools and thus doesn't - * participate in pool hash calculations or equality comparisons. + * This can be used to change attributes of an unbound workqueue. */ struct workqueue_attrs { - int nice; /* nice level */ - cpumask_var_t cpumask; /* allowed CPUs */ - bool no_numa; /* disable NUMA affinity */ + /** + * @nice: nice level + */ + int nice; + + /** + * @cpumask: allowed CPUs + */ + cpumask_var_t cpumask; + + /** + * @no_numa: disable NUMA affinity + * + * Unlike other fields, ``no_numa`` isn't a property of a worker_pool. It + * only modifies how :c:func:`apply_workqueue_attrs` select pools and thus + * doesn't participate in pool hash calculations or equality comparisons. + */ + bool no_numa; }; static inline struct delayed_work *to_delayed_work(struct work_struct *work) @@ -272,7 +284,7 @@ static inline unsigned int work_static(struct work_struct *work) { return 0; } /* * Workqueue flags and constants. For details, please refer to - * Documentation/workqueue.txt. + * Documentation/core-api/workqueue.rst. */ enum { WQ_UNBOUND = 1 << 1, /* not bound to any cpu */ @@ -370,7 +382,8 @@ __alloc_workqueue_key(const char *fmt, unsigned int flags, int max_active, * @args...: args for @fmt * * Allocate a workqueue with the specified parameters. For detailed - * information on WQ_* flags, please refer to Documentation/workqueue.txt. + * information on WQ_* flags, please refer to + * Documentation/core-api/workqueue.rst. * * The __lock_name macro dance is to guarantee that single lock_class_key * doesn't end up with different namesm, which isn't allowed by lockdep. -- cgit v1.2.3 From 24755a55b01ffbf6ed128c1dd4028c05a2b0b1ef Mon Sep 17 00:00:00 2001 From: Silvio Fricke Date: Fri, 28 Oct 2016 10:14:10 +0200 Subject: Documentation/00-index: update for new core-api folder Signed-off-by: Silvio Fricke Signed-off-by: Jonathan Corbet --- Documentation/00-INDEX | 4 +++- Documentation/core-api/conf.py | 5 +++++ Documentation/core-api/index.rst | 15 +++++++++++++++ Documentation/index.rst | 1 + 4 files changed, 24 insertions(+), 1 deletion(-) create mode 100644 Documentation/core-api/conf.py create mode 100644 Documentation/core-api/index.rst diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 903ebc494f29..e2e74448d425 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -126,6 +126,8 @@ connector/ - docs on the netlink based userspace<->kernel space communication mod. console/ - documentation on Linux console drivers. +core-api/ + - documentation on kernel core components. cpu-freq/ - info on CPU frequency and voltage scaling. cpu-hotplug.txt @@ -470,7 +472,7 @@ watchdog/ - how to auto-reboot Linux if it has "fallen and can't get up". ;-) wimax/ - directory with info about Intel Wireless Wimax Connections -workqueue.txt +core-api/workqueue.rst - information on the Concurrency Managed Workqueue implementation x86/x86_64/ - directory with info on Linux support for AMD x86-64 (Hammer) machines. diff --git a/Documentation/core-api/conf.py b/Documentation/core-api/conf.py new file mode 100644 index 000000000000..fed87ab7f486 --- /dev/null +++ b/Documentation/core-api/conf.py @@ -0,0 +1,5 @@ +# -*- coding: utf-8; mode: python -*- + +project = "Core-API Documentation" + +tags.add("subproject") diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst new file mode 100644 index 000000000000..ed3eb6499e11 --- /dev/null +++ b/Documentation/core-api/index.rst @@ -0,0 +1,15 @@ +====================== +Core-API Documentation +====================== + +Kernel and driver related documentation. + +.. toctree:: + :maxdepth: 1 + +.. only:: subproject + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/index.rst b/Documentation/index.rst index 85a66270f96c..3bb82fb11a4d 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -53,6 +53,7 @@ needed). :maxdepth: 2 driver-api/index + core-api/index media/index gpu/index 80211/index -- cgit v1.2.3 From e7f08ffb1855c482b0220cac12669ea06039da6d Mon Sep 17 00:00:00 2001 From: Silvio Fricke Date: Fri, 28 Oct 2016 10:14:11 +0200 Subject: Documentation/workqueue.txt: convert to ReST markup ... and move to Documentation/core-api folder. Signed-off-by: Silvio Fricke Signed-off-by: Jonathan Corbet --- Documentation/core-api/index.rst | 2 + Documentation/core-api/workqueue.rst | 394 +++++++++++++++++++++++++++++++++++ Documentation/workqueue.txt | 388 ---------------------------------- MAINTAINERS | 2 +- 4 files changed, 397 insertions(+), 389 deletions(-) create mode 100644 Documentation/core-api/workqueue.rst delete mode 100644 Documentation/workqueue.txt diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index ed3eb6499e11..f7ef7fda5763 100644 --- a/Documentation/core-api/index.rst +++ b/Documentation/core-api/index.rst @@ -7,6 +7,8 @@ Kernel and driver related documentation. .. toctree:: :maxdepth: 1 + workqueue + .. only:: subproject Indices diff --git a/Documentation/core-api/workqueue.rst b/Documentation/core-api/workqueue.rst new file mode 100644 index 000000000000..ffdec94fbca1 --- /dev/null +++ b/Documentation/core-api/workqueue.rst @@ -0,0 +1,394 @@ +==================================== +Concurrency Managed Workqueue (cmwq) +==================================== + +:Date: September, 2010 +:Author: Tejun Heo +:Author: Florian Mickler + + +Introduction +============ + +There are many cases where an asynchronous process execution context +is needed and the workqueue (wq) API is the most commonly used +mechanism for such cases. + +When such an asynchronous execution context is needed, a work item +describing which function to execute is put on a queue. An +independent thread serves as the asynchronous execution context. The +queue is called workqueue and the thread is called worker. + +While there are work items on the workqueue the worker executes the +functions associated with the work items one after the other. When +there is no work item left on the workqueue the worker becomes idle. +When a new work item gets queued, the worker begins executing again. + + +Why cmwq? +========= + +In the original wq implementation, a multi threaded (MT) wq had one +worker thread per CPU and a single threaded (ST) wq had one worker +thread system-wide. A single MT wq needed to keep around the same +number of workers as the number of CPUs. The kernel grew a lot of MT +wq users over the years and with the number of CPU cores continuously +rising, some systems saturated the default 32k PID space just booting +up. + +Although MT wq wasted a lot of resource, the level of concurrency +provided was unsatisfactory. The limitation was common to both ST and +MT wq albeit less severe on MT. Each wq maintained its own separate +worker pool. A MT wq could provide only one execution context per CPU +while a ST wq one for the whole system. Work items had to compete for +those very limited execution contexts leading to various problems +including proneness to deadlocks around the single execution context. + +The tension between the provided level of concurrency and resource +usage also forced its users to make unnecessary tradeoffs like libata +choosing to use ST wq for polling PIOs and accepting an unnecessary +limitation that no two polling PIOs can progress at the same time. As +MT wq don't provide much better concurrency, users which require +higher level of concurrency, like async or fscache, had to implement +their own thread pool. + +Concurrency Managed Workqueue (cmwq) is a reimplementation of wq with +focus on the following goals. + +* Maintain compatibility with the original workqueue API. + +* Use per-CPU unified worker pools shared by all wq to provide + flexible level of concurrency on demand without wasting a lot of + resource. + +* Automatically regulate worker pool and level of concurrency so that + the API users don't need to worry about such details. + + +The Design +========== + +In order to ease the asynchronous execution of functions a new +abstraction, the work item, is introduced. + +A work item is a simple struct that holds a pointer to the function +that is to be executed asynchronously. Whenever a driver or subsystem +wants a function to be executed asynchronously it has to set up a work +item pointing to that function and queue that work item on a +workqueue. + +Special purpose threads, called worker threads, execute the functions +off of the queue, one after the other. If no work is queued, the +worker threads become idle. These worker threads are managed in so +called worker-pools. + +The cmwq design differentiates between the user-facing workqueues that +subsystems and drivers queue work items on and the backend mechanism +which manages worker-pools and processes the queued work items. + +There are two worker-pools, one for normal work items and the other +for high priority ones, for each possible CPU and some extra +worker-pools to serve work items queued on unbound workqueues - the +number of these backing pools is dynamic. + +Subsystems and drivers can create and queue work items through special +workqueue API functions as they see fit. They can influence some +aspects of the way the work items are executed by setting flags on the +workqueue they are putting the work item on. These flags include +things like CPU locality, concurrency limits, priority and more. To +get a detailed overview refer to the API description of +``alloc_workqueue()`` below. + +When a work item is queued to a workqueue, the target worker-pool is +determined according to the queue parameters and workqueue attributes +and appended on the shared worklist of the worker-pool. For example, +unless specifically overridden, a work item of a bound workqueue will +be queued on the worklist of either normal or highpri worker-pool that +is associated to the CPU the issuer is running on. + +For any worker pool implementation, managing the concurrency level +(how many execution contexts are active) is an important issue. cmwq +tries to keep the concurrency at a minimal but sufficient level. +Minimal to save resources and sufficient in that the system is used at +its full capacity. + +Each worker-pool bound to an actual CPU implements concurrency +management by hooking into the scheduler. The worker-pool is notified +whenever an active worker wakes up or sleeps and keeps track of the +number of the currently runnable workers. Generally, work items are +not expected to hog a CPU and consume many cycles. That means +maintaining just enough concurrency to prevent work processing from +stalling should be optimal. As long as there are one or more runnable +workers on the CPU, the worker-pool doesn't start execution of a new +work, but, when the last running worker goes to sleep, it immediately +schedules a new worker so that the CPU doesn't sit idle while there +are pending work items. This allows using a minimal number of workers +without losing execution bandwidth. + +Keeping idle workers around doesn't cost other than the memory space +for kthreads, so cmwq holds onto idle ones for a while before killing +them. + +For unbound workqueues, the number of backing pools is dynamic. +Unbound workqueue can be assigned custom attributes using +``apply_workqueue_attrs()`` and workqueue will automatically create +backing worker pools matching the attributes. The responsibility of +regulating concurrency level is on the users. There is also a flag to +mark a bound wq to ignore the concurrency management. Please refer to +the API section for details. + +Forward progress guarantee relies on that workers can be created when +more execution contexts are necessary, which in turn is guaranteed +through the use of rescue workers. All work items which might be used +on code paths that handle memory reclaim are required to be queued on +wq's that have a rescue-worker reserved for execution under memory +pressure. Else it is possible that the worker-pool deadlocks waiting +for execution contexts to free up. + + +Application Programming Interface (API) +======================================= + +``alloc_workqueue()`` allocates a wq. The original +``create_*workqueue()`` functions are deprecated and scheduled for +removal. ``alloc_workqueue()`` takes three arguments - @``name``, +``@flags`` and ``@max_active``. ``@name`` is the name of the wq and +also used as the name of the rescuer thread if there is one. + +A wq no longer manages execution resources but serves as a domain for +forward progress guarantee, flush and work item attributes. ``@flags`` +and ``@max_active`` control how work items are assigned execution +resources, scheduled and executed. + + +``flags`` +--------- + +``WQ_UNBOUND`` + Work items queued to an unbound wq are served by the special + 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 + possible. Unbound wq sacrifices locality but is useful for + the following cases. + + * Wide fluctuation in the concurrency level requirement is + expected and using bound wq may end up creating large number + of mostly unused workers across different CPUs as the issuer + hops through different CPUs. + + * Long running CPU intensive workloads which can be better + managed by the system scheduler. + +``WQ_FREEZABLE`` + A freezable wq participates in the freeze phase of the system + suspend operations. Work items on the wq are drained and no + new work item starts execution until thawed. + +``WQ_MEM_RECLAIM`` + All wq which might be used in the memory reclaim paths **MUST** + have this flag set. The wq is guaranteed to have at least one + execution context regardless of memory pressure. + +``WQ_HIGHPRI`` + Work items of a highpri wq are queued to the highpri + worker-pool of the target cpu. Highpri worker-pools are + served by worker threads with elevated nice level. + + Note that normal and highpri worker-pools don't interact with + each other. Each maintain its separate pool of workers and + implements concurrency management among its workers. + +``WQ_CPU_INTENSIVE`` + Work items of a CPU intensive wq do not contribute to the + concurrency level. In other words, runnable CPU intensive + work items will not prevent other work items in the same + worker-pool from starting execution. This is useful for bound + work items which are expected to hog CPU cycles so that their + execution is regulated by the system scheduler. + + Although CPU intensive work items don't contribute to the + concurrency level, start of their executions is still + regulated by the concurrency management and runnable + non-CPU-intensive work items can delay execution of CPU + intensive work items. + + This flag is meaningless for unbound wq. + +Note that the flag ``WQ_NON_REENTRANT`` no longer exists as all +workqueues are now non-reentrant - any work item is guaranteed to be +executed by at most one worker system-wide at any given time. + + +``max_active`` +-------------- + +``@max_active`` determines the maximum number of execution contexts +per CPU which can be assigned to the work items of a wq. For example, +with ``@max_active`` of 16, at most 16 work items of the wq can be +executing at the same time per CPU. + +Currently, for a bound wq, the maximum limit for ``@max_active`` is +512 and the default value used when 0 is specified is 256. For an +unbound wq, the limit is higher of 512 and 4 * +``num_possible_cpus()``. These values are chosen sufficiently high +such that they are not the limiting factor while providing protection +in runaway cases. + +The number of active work items of a wq is usually regulated by the +users of the wq, more specifically, by how many work items the users +may queue at the same time. Unless there is a specific need for +throttling the number of active work items, specifying '0' is +recommended. + +Some users depend on the strict execution ordering of ST wq. The +combination of ``@max_active`` of 1 and ``WQ_UNBOUND`` is used to +achieve this behavior. Work items on such wq are always queued to the +unbound worker-pools and only one work item can be active at any given +time thus achieving the same ordering property as ST wq. + + +Example Execution Scenarios +=========================== + +The following example execution scenarios try to illustrate how cmwq +behave under different configurations. + + Work items w0, w1, w2 are queued to a bound wq q0 on the same CPU. + w0 burns CPU for 5ms then sleeps for 10ms then burns CPU for 5ms + again before finishing. w1 and w2 burn CPU for 5ms then sleep for + 10ms. + +Ignoring all other tasks, works and processing overhead, and assuming +simple FIFO scheduling, the following is one highly simplified version +of possible sequences of events with the original wq. :: + + TIME IN MSECS EVENT + 0 w0 starts and burns CPU + 5 w0 sleeps + 15 w0 wakes up and burns CPU + 20 w0 finishes + 20 w1 starts and burns CPU + 25 w1 sleeps + 35 w1 wakes up and finishes + 35 w2 starts and burns CPU + 40 w2 sleeps + 50 w2 wakes up and finishes + +And with cmwq with ``@max_active`` >= 3, :: + + TIME IN MSECS EVENT + 0 w0 starts and burns CPU + 5 w0 sleeps + 5 w1 starts and burns CPU + 10 w1 sleeps + 10 w2 starts and burns CPU + 15 w2 sleeps + 15 w0 wakes up and burns CPU + 20 w0 finishes + 20 w1 wakes up and finishes + 25 w2 wakes up and finishes + +If ``@max_active`` == 2, :: + + TIME IN MSECS EVENT + 0 w0 starts and burns CPU + 5 w0 sleeps + 5 w1 starts and burns CPU + 10 w1 sleeps + 15 w0 wakes up and burns CPU + 20 w0 finishes + 20 w1 wakes up and finishes + 20 w2 starts and burns CPU + 25 w2 sleeps + 35 w2 wakes up and finishes + +Now, let's assume w1 and w2 are queued to a different wq q1 which has +``WQ_CPU_INTENSIVE`` set, :: + + TIME IN MSECS EVENT + 0 w0 starts and burns CPU + 5 w0 sleeps + 5 w1 and w2 start and burn CPU + 10 w1 sleeps + 15 w2 sleeps + 15 w0 wakes up and burns CPU + 20 w0 finishes + 20 w1 wakes up and finishes + 25 w2 wakes up and finishes + + +Guidelines +========== + +* Do not forget to use ``WQ_MEM_RECLAIM`` if a wq may process work + items which are used during memory reclaim. Each wq with + ``WQ_MEM_RECLAIM`` set has an execution context reserved for it. If + there is dependency among multiple work items used during memory + reclaim, they should be queued to separate wq each with + ``WQ_MEM_RECLAIM``. + +* Unless strict ordering is required, there is no need to use ST wq. + +* Unless there is a specific need, using 0 for @max_active is + recommended. In most use cases, concurrency level usually stays + well under the default limit. + +* A wq serves as a domain for forward progress guarantee + (``WQ_MEM_RECLAIM``, flush and work item attributes. Work items + which are not involved in memory reclaim and don't need to be + flushed as a part of a group of work items, and don't require any + special attribute, can use one of the system wq. There is no + difference in execution characteristics between using a dedicated wq + and a system wq. + +* Unless work items are expected to consume a huge amount of CPU + cycles, using a bound wq is usually beneficial due to the increased + level of locality in wq operations and work item execution. + + +Debugging +========= + +Because the work functions are executed by generic worker threads +there are a few tricks needed to shed some light on misbehaving +workqueue users. + +Worker threads show up in the process list as: :: + + root 5671 0.0 0.0 0 0 ? S 12:07 0:00 [kworker/0:1] + root 5672 0.0 0.0 0 0 ? S 12:07 0:00 [kworker/1:2] + root 5673 0.0 0.0 0 0 ? S 12:12 0:00 [kworker/0:0] + root 5674 0.0 0.0 0 0 ? S 12:13 0:00 [kworker/1:0] + +If kworkers are going crazy (using too much cpu), there are two types +of possible problems: + + 1. Something being scheduled in rapid succession + 2. A single work item that consumes lots of cpu cycles + +The first one can be tracked using tracing: :: + + $ echo workqueue:workqueue_queue_work > /sys/kernel/debug/tracing/set_event + $ cat /sys/kernel/debug/tracing/trace_pipe > out.txt + (wait a few secs) + ^C + +If something is busy looping on work queueing, it would be dominating +the output and the offender can be determined with the work item +function. + +For the second type of problems it should be possible to just check +the stack trace of the offending worker thread. :: + + $ cat /proc/THE_OFFENDING_KWORKER/stack + +The work item's function should be trivially visible in the stack +trace. + + +Kernel Inline Documentations Reference +====================================== + +.. kernel-doc:: include/linux/workqueue.h diff --git a/Documentation/workqueue.txt b/Documentation/workqueue.txt deleted file mode 100644 index c49e3178178d..000000000000 --- a/Documentation/workqueue.txt +++ /dev/null @@ -1,388 +0,0 @@ - -Concurrency Managed Workqueue (cmwq) - -September, 2010 Tejun Heo - Florian Mickler - -CONTENTS - -1. Introduction -2. Why cmwq? -3. The Design -4. Application Programming Interface (API) -5. Example Execution Scenarios -6. Guidelines -7. Debugging - - -1. Introduction - -There are many cases where an asynchronous process execution context -is needed and the workqueue (wq) API is the most commonly used -mechanism for such cases. - -When such an asynchronous execution context is needed, a work item -describing which function to execute is put on a queue. An -independent thread serves as the asynchronous execution context. The -queue is called workqueue and the thread is called worker. - -While there are work items on the workqueue the worker executes the -functions associated with the work items one after the other. When -there is no work item left on the workqueue the worker becomes idle. -When a new work item gets queued, the worker begins executing again. - - -2. Why cmwq? - -In the original wq implementation, a multi threaded (MT) wq had one -worker thread per CPU and a single threaded (ST) wq had one worker -thread system-wide. A single MT wq needed to keep around the same -number of workers as the number of CPUs. The kernel grew a lot of MT -wq users over the years and with the number of CPU cores continuously -rising, some systems saturated the default 32k PID space just booting -up. - -Although MT wq wasted a lot of resource, the level of concurrency -provided was unsatisfactory. The limitation was common to both ST and -MT wq albeit less severe on MT. Each wq maintained its own separate -worker pool. A MT wq could provide only one execution context per CPU -while a ST wq one for the whole system. Work items had to compete for -those very limited execution contexts leading to various problems -including proneness to deadlocks around the single execution context. - -The tension between the provided level of concurrency and resource -usage also forced its users to make unnecessary tradeoffs like libata -choosing to use ST wq for polling PIOs and accepting an unnecessary -limitation that no two polling PIOs can progress at the same time. As -MT wq don't provide much better concurrency, users which require -higher level of concurrency, like async or fscache, had to implement -their own thread pool. - -Concurrency Managed Workqueue (cmwq) is a reimplementation of wq with -focus on the following goals. - -* Maintain compatibility with the original workqueue API. - -* Use per-CPU unified worker pools shared by all wq to provide - flexible level of concurrency on demand without wasting a lot of - resource. - -* Automatically regulate worker pool and level of concurrency so that - the API users don't need to worry about such details. - - -3. The Design - -In order to ease the asynchronous execution of functions a new -abstraction, the work item, is introduced. - -A work item is a simple struct that holds a pointer to the function -that is to be executed asynchronously. Whenever a driver or subsystem -wants a function to be executed asynchronously it has to set up a work -item pointing to that function and queue that work item on a -workqueue. - -Special purpose threads, called worker threads, execute the functions -off of the queue, one after the other. If no work is queued, the -worker threads become idle. These worker threads are managed in so -called worker-pools. - -The cmwq design differentiates between the user-facing workqueues that -subsystems and drivers queue work items on and the backend mechanism -which manages worker-pools and processes the queued work items. - -There are two worker-pools, one for normal work items and the other -for high priority ones, for each possible CPU and some extra -worker-pools to serve work items queued on unbound workqueues - the -number of these backing pools is dynamic. - -Subsystems and drivers can create and queue work items through special -workqueue API functions as they see fit. They can influence some -aspects of the way the work items are executed by setting flags on the -workqueue they are putting the work item on. These flags include -things like CPU locality, concurrency limits, priority and more. To -get a detailed overview refer to the API description of -alloc_workqueue() below. - -When a work item is queued to a workqueue, the target worker-pool is -determined according to the queue parameters and workqueue attributes -and appended on the shared worklist of the worker-pool. For example, -unless specifically overridden, a work item of a bound workqueue will -be queued on the worklist of either normal or highpri worker-pool that -is associated to the CPU the issuer is running on. - -For any worker pool implementation, managing the concurrency level -(how many execution contexts are active) is an important issue. cmwq -tries to keep the concurrency at a minimal but sufficient level. -Minimal to save resources and sufficient in that the system is used at -its full capacity. - -Each worker-pool bound to an actual CPU implements concurrency -management by hooking into the scheduler. The worker-pool is notified -whenever an active worker wakes up or sleeps and keeps track of the -number of the currently runnable workers. Generally, work items are -not expected to hog a CPU and consume many cycles. That means -maintaining just enough concurrency to prevent work processing from -stalling should be optimal. As long as there are one or more runnable -workers on the CPU, the worker-pool doesn't start execution of a new -work, but, when the last running worker goes to sleep, it immediately -schedules a new worker so that the CPU doesn't sit idle while there -are pending work items. This allows using a minimal number of workers -without losing execution bandwidth. - -Keeping idle workers around doesn't cost other than the memory space -for kthreads, so cmwq holds onto idle ones for a while before killing -them. - -For unbound workqueues, the number of backing pools is dynamic. -Unbound workqueue can be assigned custom attributes using -apply_workqueue_attrs() and workqueue will automatically create -backing worker pools matching the attributes. The responsibility of -regulating concurrency level is on the users. There is also a flag to -mark a bound wq to ignore the concurrency management. Please refer to -the API section for details. - -Forward progress guarantee relies on that workers can be created when -more execution contexts are necessary, which in turn is guaranteed -through the use of rescue workers. All work items which might be used -on code paths that handle memory reclaim are required to be queued on -wq's that have a rescue-worker reserved for execution under memory -pressure. Else it is possible that the worker-pool deadlocks waiting -for execution contexts to free up. - - -4. Application Programming Interface (API) - -alloc_workqueue() allocates a wq. The original create_*workqueue() -functions are deprecated and scheduled for removal. alloc_workqueue() -takes three arguments - @name, @flags and @max_active. @name is the -name of the wq and also used as the name of the rescuer thread if -there is one. - -A wq no longer manages execution resources but serves as a domain for -forward progress guarantee, flush and work item attributes. @flags -and @max_active control how work items are assigned execution -resources, scheduled and executed. - -@flags: - - WQ_UNBOUND - - Work items queued to an unbound wq are served by the special - 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 - possible. Unbound wq sacrifices locality but is useful for - the following cases. - - * Wide fluctuation in the concurrency level requirement is - expected and using bound wq may end up creating large number - of mostly unused workers across different CPUs as the issuer - hops through different CPUs. - - * Long running CPU intensive workloads which can be better - managed by the system scheduler. - - WQ_FREEZABLE - - A freezable wq participates in the freeze phase of the system - suspend operations. Work items on the wq are drained and no - new work item starts execution until thawed. - - WQ_MEM_RECLAIM - - All wq which might be used in the memory reclaim paths _MUST_ - have this flag set. The wq is guaranteed to have at least one - execution context regardless of memory pressure. - - WQ_HIGHPRI - - Work items of a highpri wq are queued to the highpri - worker-pool of the target cpu. Highpri worker-pools are - served by worker threads with elevated nice level. - - Note that normal and highpri worker-pools don't interact with - each other. Each maintain its separate pool of workers and - implements concurrency management among its workers. - - WQ_CPU_INTENSIVE - - Work items of a CPU intensive wq do not contribute to the - concurrency level. In other words, runnable CPU intensive - work items will not prevent other work items in the same - worker-pool from starting execution. This is useful for bound - work items which are expected to hog CPU cycles so that their - execution is regulated by the system scheduler. - - Although CPU intensive work items don't contribute to the - concurrency level, start of their executions is still - regulated by the concurrency management and runnable - non-CPU-intensive work items can delay execution of CPU - intensive work items. - - This flag is meaningless for unbound wq. - -Note that the flag WQ_NON_REENTRANT no longer exists as all workqueues -are now non-reentrant - any work item is guaranteed to be executed by -at most one worker system-wide at any given time. - -@max_active: - -@max_active determines the maximum number of execution contexts per -CPU which can be assigned to the work items of a wq. For example, -with @max_active of 16, at most 16 work items of the wq can be -executing at the same time per CPU. - -Currently, for a bound wq, the maximum limit for @max_active is 512 -and the default value used when 0 is specified is 256. For an unbound -wq, the limit is higher of 512 and 4 * num_possible_cpus(). These -values are chosen sufficiently high such that they are not the -limiting factor while providing protection in runaway cases. - -The number of active work items of a wq is usually regulated by the -users of the wq, more specifically, by how many work items the users -may queue at the same time. Unless there is a specific need for -throttling the number of active work items, specifying '0' is -recommended. - -Some users depend on the strict execution ordering of ST wq. The -combination of @max_active of 1 and WQ_UNBOUND is used to achieve this -behavior. Work items on such wq are always queued to the unbound -worker-pools and only one work item can be active at any given time thus -achieving the same ordering property as ST wq. - - -5. Example Execution Scenarios - -The following example execution scenarios try to illustrate how cmwq -behave under different configurations. - - Work items w0, w1, w2 are queued to a bound wq q0 on the same CPU. - w0 burns CPU for 5ms then sleeps for 10ms then burns CPU for 5ms - again before finishing. w1 and w2 burn CPU for 5ms then sleep for - 10ms. - -Ignoring all other tasks, works and processing overhead, and assuming -simple FIFO scheduling, the following is one highly simplified version -of possible sequences of events with the original wq. - - TIME IN MSECS EVENT - 0 w0 starts and burns CPU - 5 w0 sleeps - 15 w0 wakes up and burns CPU - 20 w0 finishes - 20 w1 starts and burns CPU - 25 w1 sleeps - 35 w1 wakes up and finishes - 35 w2 starts and burns CPU - 40 w2 sleeps - 50 w2 wakes up and finishes - -And with cmwq with @max_active >= 3, - - TIME IN MSECS EVENT - 0 w0 starts and burns CPU - 5 w0 sleeps - 5 w1 starts and burns CPU - 10 w1 sleeps - 10 w2 starts and burns CPU - 15 w2 sleeps - 15 w0 wakes up and burns CPU - 20 w0 finishes - 20 w1 wakes up and finishes - 25 w2 wakes up and finishes - -If @max_active == 2, - - TIME IN MSECS EVENT - 0 w0 starts and burns CPU - 5 w0 sleeps - 5 w1 starts and burns CPU - 10 w1 sleeps - 15 w0 wakes up and burns CPU - 20 w0 finishes - 20 w1 wakes up and finishes - 20 w2 starts and burns CPU - 25 w2 sleeps - 35 w2 wakes up and finishes - -Now, let's assume w1 and w2 are queued to a different wq q1 which has -WQ_CPU_INTENSIVE set, - - TIME IN MSECS EVENT - 0 w0 starts and burns CPU - 5 w0 sleeps - 5 w1 and w2 start and burn CPU - 10 w1 sleeps - 15 w2 sleeps - 15 w0 wakes up and burns CPU - 20 w0 finishes - 20 w1 wakes up and finishes - 25 w2 wakes up and finishes - - -6. Guidelines - -* Do not forget to use WQ_MEM_RECLAIM if a wq may process work items - which are used during memory reclaim. Each wq with WQ_MEM_RECLAIM - set has an execution context reserved for it. If there is - dependency among multiple work items used during memory reclaim, - they should be queued to separate wq each with WQ_MEM_RECLAIM. - -* Unless strict ordering is required, there is no need to use ST wq. - -* Unless there is a specific need, using 0 for @max_active is - recommended. In most use cases, concurrency level usually stays - well under the default limit. - -* A wq serves as a domain for forward progress guarantee - (WQ_MEM_RECLAIM, flush and work item attributes. Work items which - are not involved in memory reclaim and don't need to be flushed as a - part of a group of work items, and don't require any special - attribute, can use one of the system wq. There is no difference in - execution characteristics between using a dedicated wq and a system - wq. - -* Unless work items are expected to consume a huge amount of CPU - cycles, using a bound wq is usually beneficial due to the increased - level of locality in wq operations and work item execution. - - -7. Debugging - -Because the work functions are executed by generic worker threads -there are a few tricks needed to shed some light on misbehaving -workqueue users. - -Worker threads show up in the process list as: - -root 5671 0.0 0.0 0 0 ? S 12:07 0:00 [kworker/0:1] -root 5672 0.0 0.0 0 0 ? S 12:07 0:00 [kworker/1:2] -root 5673 0.0 0.0 0 0 ? S 12:12 0:00 [kworker/0:0] -root 5674 0.0 0.0 0 0 ? S 12:13 0:00 [kworker/1:0] - -If kworkers are going crazy (using too much cpu), there are two types -of possible problems: - - 1. Something being scheduled in rapid succession - 2. A single work item that consumes lots of cpu cycles - -The first one can be tracked using tracing: - - $ echo workqueue:workqueue_queue_work > /sys/kernel/debug/tracing/set_event - $ cat /sys/kernel/debug/tracing/trace_pipe > out.txt - (wait a few secs) - ^C - -If something is busy looping on work queueing, it would be dominating -the output and the offender can be determined with the work item -function. - -For the second type of problems it should be possible to just check -the stack trace of the offending worker thread. - - $ cat /proc/THE_OFFENDING_KWORKER/stack - -The work item's function should be trivially visible in the stack -trace. diff --git a/MAINTAINERS b/MAINTAINERS index 69820b75b2e0..489a913a0bd4 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -13101,7 +13101,7 @@ T: git git://git.kernel.org/pub/scm/linux/kernel/git/tj/wq.git S: Maintained F: include/linux/workqueue.h F: kernel/workqueue.c -F: Documentation/workqueue.txt +F: Documentation/core-api/workqueue.rst X-POWERS MULTIFUNCTION PMIC DEVICE DRIVERS M: Chen-Yu Tsai -- cgit v1.2.3 From 1171a28bacee936be4da7c83de429e0258e647c3 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 2 Nov 2016 10:38:43 +0200 Subject: Documentation/sphinx: let the user specify PDFLATEX and LATEXOPTS Refer to xelatex and latex options via variables. This allows the user to override the pdflatex and latex options to use on the make command line for experimenting. As a side effect, this makes the makefile a bit tidier. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jani Nikula --- Documentation/Makefile.sphinx | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index 92deea30b183..1314e3ee31c4 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -10,6 +10,8 @@ _SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(src SPHINX_CONF = conf.py PAPER = BUILDDIR = $(obj)/output +PDFLATEX = xelatex +LATEXOPTS = -interaction=nonstopmode # User-friendly check for sphinx-build HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi) @@ -29,7 +31,7 @@ else ifneq ($(DOCBOOKS),) else # HAVE_SPHINX # User-friendly check for pdflatex -HAVE_PDFLATEX := $(shell if which xelatex >/dev/null 2>&1; then echo 1; else echo 0; fi) +HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi) # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 @@ -68,7 +70,7 @@ htmldocs: latexdocs: ifeq ($(HAVE_PDFLATEX),0) - $(warning The 'xelatex' command was not found. Make sure you have it installed and in PATH to produce PDF output.) + $(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.) @echo " SKIP Sphinx $@ target." else # HAVE_PDFLATEX @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) @@ -76,7 +78,8 @@ endif # HAVE_PDFLATEX pdfdocs: latexdocs ifneq ($(HAVE_PDFLATEX),0) - $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=xelatex LATEXOPTS="-interaction=nonstopmode" -C $(BUILDDIR)/$(var)/latex) + $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex) + endif # HAVE_PDFLATEX epubdocs: -- cgit v1.2.3 From 207fc55bc32f6baf0f4793afb5e79267d528e1ae Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 2 Nov 2016 11:13:19 +0200 Subject: Documentation/sphinx: make it possible to build latexdocs without pdflatex Building latexdocs doesn't actually require $(PDFLATEX). Move the checks for it to the pdfdocs target which does require it, and specifically outside of the target in order to not depend on latexdocs when we can't build pdfdocs anyway. Reviewed-by: Mauro Carvalho Chehab Tested-by: Markus Heiser Signed-off-by: Jani Nikula --- Documentation/Makefile.sphinx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index 1314e3ee31c4..4819638f7e21 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -69,15 +69,17 @@ htmldocs: @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var))) latexdocs: + @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) + ifeq ($(HAVE_PDFLATEX),0) + +pdfdocs: $(warning The '$(PDFLATEX)' command was not found. Make sure you have it installed and in PATH to produce PDF output.) @echo " SKIP Sphinx $@ target." + else # HAVE_PDFLATEX - @$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var))) -endif # HAVE_PDFLATEX pdfdocs: latexdocs -ifneq ($(HAVE_PDFLATEX),0) $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex) endif # HAVE_PDFLATEX -- cgit v1.2.3 From c8556966720f9b54104b55f648a7bbc6f01d7b43 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 2 Nov 2016 10:56:31 +0200 Subject: Documentation/sphinx: remove superfluous trailing ; from quiet_cmd_sphinx With the unnecessary ; removed, the terminal URL detection also works better. Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jani Nikula --- Documentation/Makefile.sphinx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index 4819638f7e21..4d3ff4b7a2a5 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -53,7 +53,7 @@ loop_cmd = $(echo-cmd) $(cmd_$(1)) # $5 reST source folder relative to $(srctree)/$(src), # e.g. "media" for the linux-tv book-set at ./Documentation/media -quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4); +quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media all;\ BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ $(SPHINXBUILD) \ -- cgit v1.2.3 From eaed1b25a783121ecd4fb4eccebe45b08675b915 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 2 Nov 2016 13:20:15 +0200 Subject: Documentation/sphinx: change pdflatex interaction mode to batchmode Radically reduce the noise on stdout. The full build logs will still be available under Documentatio/output/latex/*.log. Cc: Mauro Carvalho Chehab Reviewed-by: Mauro Carvalho Chehab Tested-by: Markus Heiser Signed-off-by: Jani Nikula --- Documentation/Makefile.sphinx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index 4d3ff4b7a2a5..d58d776d8d00 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -11,7 +11,7 @@ SPHINX_CONF = conf.py PAPER = BUILDDIR = $(obj)/output PDFLATEX = xelatex -LATEXOPTS = -interaction=nonstopmode +LATEXOPTS = -interaction=batchmode # User-friendly check for sphinx-build HAVE_SPHINX := $(shell if which $(SPHINXBUILD) >/dev/null 2>&1; then echo 1; else echo 0; fi) -- cgit v1.2.3 From 0af205ea6c35ad540d638351ce37457e3ee2bac8 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 2 Nov 2016 16:37:11 +0200 Subject: Documentation/sphinx: fix make SPHINXDIRS="dirs" pdfdocs for more than one dir Add missing semicolon to fix pdf build with more than one SPHINXDIRS directory specified. For example make SPHINXDIRS="gpu media" pdfdocs. Fixes: cd21379b1698 ("doc-rst: generic way to build PDF of sub-folders") Signed-off-by: Markus Heiser Signed-off-by: Jani Nikula --- Documentation/Makefile.sphinx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx index d58d776d8d00..ec0c77d028db 100644 --- a/Documentation/Makefile.sphinx +++ b/Documentation/Makefile.sphinx @@ -80,7 +80,7 @@ pdfdocs: else # HAVE_PDFLATEX pdfdocs: latexdocs - $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex) + $(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex;) endif # HAVE_PDFLATEX -- cgit v1.2.3 From 8d26d90ba3e1cfb75c4af2882045ca2c8120fbab Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 2 Nov 2016 13:05:59 +0200 Subject: Documentation/sphinx: include admin-guide in the latex/pdf build Fix the warning: WARNING: "latex_documents" config value references unknown document user/index Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jani Nikula --- Documentation/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index d9bad21dd427..7830051b6837 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -336,7 +336,7 @@ latex_elements = { # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - ('user/index', 'linux-user.tex', 'Linux Kernel User Documentation', + ('admin-guide/index', 'linux-user.tex', 'Linux Kernel User Documentation', 'The kernel development community', 'manual'), ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation', 'The kernel development community', 'manual'), -- cgit v1.2.3 From b459106ea4b7f317faa24b47e9a6b20c2f254d2d Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 3 Nov 2016 10:26:54 +0200 Subject: Documentation/sphinx: set literal block highlight language to none Set the default highlight language to "none", i.e. do not try to guess the language and do automatic syntax highlighting on literal blocks. Eyeballing around the generated documentation, we don't seem to actually have a lot of literal blocks that would benefit from syntax highlighting. The C code blocks we do have are typically very short, and most of the literal blocks are things that shouldn't be highlighted (or, do not have a pygments lexer). This seems to be true for literal blocks both in the rst source files and in source code comments. Not highlighting code is never wrong, but guessing the language wrong almost invariably leads to silly or confusing highlighting. At the time of writing, admin-guide/oops-tracing.rst and admin-guide/ramoops.rst contain good examples of 1) a small C code snippet not highlighted, 2) a hex dump highligted as who knows what, 3) device tree block highlighted as C or maybe Python, 4) a terminal interaction highlighted as code in some language, and finally, 5) some C code snippets correctly identified as C. I think we're better off disabling language guessing, and going by explicitly identified languages for longer code blocks. It is still possible to enable highlighting on an rst source file basis using the highlight directive: .. higlight:: language and on a literal block basis using the code-block directive: .. code-block:: language See http://www.sphinx-doc.org/en/latest/markup/code.html for details. Cc: Jonathan Corbet Cc: Mauro Carvalho Chehab Cc: Markus Heiser Signed-off-by: Jani Nikula --- Documentation/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 7830051b6837..bcb1af786e78 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -136,7 +136,7 @@ pygments_style = 'sphinx' todo_include_todos = False primary_domain = 'C' -highlight_language = 'guess' +highlight_language = 'none' # -- Options for HTML output ---------------------------------------------- -- cgit v1.2.3 From 07a37ba5835315f40431900dd1a8e80af4682294 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 3 Nov 2016 11:43:29 +0200 Subject: Documentation/admin-guide: use code-block with proper language Now that we don't have automatic syntax highlighting, use the code-block directive with the explicitly selected language, where appropriate. Signed-off-by: Jani Nikula --- Documentation/admin-guide/java.rst | 52 +++++++++++++++++++---------------- Documentation/admin-guide/mono.rst | 4 ++- Documentation/admin-guide/ramoops.rst | 4 ++- 3 files changed, 35 insertions(+), 25 deletions(-) diff --git a/Documentation/admin-guide/java.rst b/Documentation/admin-guide/java.rst index a0de7c1a1ed9..8744e272e6f8 100644 --- a/Documentation/admin-guide/java.rst +++ b/Documentation/admin-guide/java.rst @@ -66,7 +66,9 @@ other program after you have done the following: Both the javawrapper shellscript and the javaclassname program were supplied by Colin J. Watson . -Javawrapper shell script:: +Javawrapper shell script: + +.. code-block:: sh #!/bin/bash # /usr/local/bin/javawrapper - the wrapper for binfmt_misc/java @@ -155,29 +157,31 @@ Javawrapper shell script:: shift /usr/bin/java $FQCLASS "$@" -javaclassname.c:: +javaclassname.c: + +.. code-block:: c /* javaclassname.c - * - * Extracts the class name from a Java class file; intended for use in a Java - * wrapper of the type supported by the binfmt_misc option in the Linux kernel. - * - * Copyright (C) 1999 Colin J. Watson . - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - */ + * + * Extracts the class name from a Java class file; intended for use in a Java + * wrapper of the type supported by the binfmt_misc option in the Linux kernel. + * + * Copyright (C) 1999 Colin J. Watson . + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ #include #include @@ -378,7 +382,9 @@ added to your CLASSPATH during execution. To test your new setup, enter in the following simple Java app, and name -it "HelloWorld.java":: +it "HelloWorld.java": + +.. code-block:: java class HelloWorld { public static void main(String args[]) { diff --git a/Documentation/admin-guide/mono.rst b/Documentation/admin-guide/mono.rst index 9a9744ca0cf3..cdddc099af64 100644 --- a/Documentation/admin-guide/mono.rst +++ b/Documentation/admin-guide/mono.rst @@ -31,7 +31,9 @@ other program after you have done the following: more about the configuration process. 3) Add the following entries to ``/etc/rc.local`` or similar script - to be run at system startup:: + to be run at system startup: + + .. code-block:: sh # Insert BINFMT_MISC module into the kernel if [ ! -e /proc/sys/fs/binfmt_misc/register ]; then diff --git a/Documentation/admin-guide/ramoops.rst b/Documentation/admin-guide/ramoops.rst index fe95c027e37c..4efd7ce77565 100644 --- a/Documentation/admin-guide/ramoops.rst +++ b/Documentation/admin-guide/ramoops.rst @@ -78,7 +78,9 @@ Setting the ramoops parameters can be done in several different manners: }; C. Use a platform device and set the platform data. The parameters can then - be set through that platform data. An example of doing that is:: + be set through that platform data. An example of doing that is: + + .. code-block:: c #include [...] -- cgit v1.2.3 From 57131dd3fd9f51a6b54a917d7faa6ce59d7f3e48 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 3 Nov 2016 11:44:04 +0200 Subject: Documentation/dev-tools: use code-block with proper language Now that we don't have automatic syntax highlighting, use the code-block directive with the explicitly selected language, where appropriate. Signed-off-by: Jani Nikula --- Documentation/dev-tools/gcov.rst | 8 ++++++-- Documentation/dev-tools/kcov.rst | 4 +++- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/Documentation/dev-tools/gcov.rst b/Documentation/dev-tools/gcov.rst index 19eedfea8800..69a7d90c320a 100644 --- a/Documentation/dev-tools/gcov.rst +++ b/Documentation/dev-tools/gcov.rst @@ -201,7 +201,9 @@ Appendix A: gather_on_build.sh ------------------------------ Sample script to gather coverage meta files on the build machine -(see 6a):: +(see 6a): + +.. code-block:: sh #!/bin/bash @@ -232,7 +234,9 @@ Appendix B: gather_on_test.sh ----------------------------- Sample script to gather coverage data files on the test machine -(see 6b):: +(see 6b): + +.. code-block:: sh #!/bin/bash -e diff --git a/Documentation/dev-tools/kcov.rst b/Documentation/dev-tools/kcov.rst index aca0e27ca197..2c41b713841f 100644 --- a/Documentation/dev-tools/kcov.rst +++ b/Documentation/dev-tools/kcov.rst @@ -24,7 +24,9 @@ Profiling data will only become accessible once debugfs has been mounted:: mount -t debugfs none /sys/kernel/debug -The following program demonstrates kcov usage from within a test program:: +The following program demonstrates kcov usage from within a test program: + +.. code-block:: c #include #include -- cgit v1.2.3 From 29849a695ffefd0055e23f5c59659dd377e361fe Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 3 Nov 2016 11:44:23 +0200 Subject: Documentation/gpu: use code-block with proper language Now that we don't have automatic syntax highlighting, use the code-block directive with the explicitly selected language, where appropriate. Signed-off-by: Jani Nikula --- Documentation/gpu/drm-kms.rst | 2 +- Documentation/gpu/drm-mm.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst index 53b872c105d2..38af5d1cc59f 100644 --- a/Documentation/gpu/drm-kms.rst +++ b/Documentation/gpu/drm-kms.rst @@ -215,7 +215,7 @@ Connectors state change detection must be cleanup up with a call to Output discovery and initialization example ------------------------------------------- -:: +.. code-block:: c void intel_crt_init(struct drm_device *dev) { diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst index bca808535dfd..cb5daffcd6be 100644 --- a/Documentation/gpu/drm-mm.rst +++ b/Documentation/gpu/drm-mm.rst @@ -45,7 +45,7 @@ the radeon_ttm.c file for an example of usage. The ttm_global_reference structure is made up of several fields: -:: +.. code-block:: c struct ttm_global_reference { enum ttm_global_types global_type; -- cgit v1.2.3 From e52347bd66f6fb428464f84f4c867e68bcb4ad4e Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 3 Nov 2016 12:10:10 +0200 Subject: Documentation/admin-guide: split the kernel parameter list to a separate file Include the literal kernel parameter list from a separate file. This helps the pdf build. Signed-off-by: Jani Nikula --- Documentation/admin-guide/kernel-parameters.rst | 4374 +---------------------- Documentation/admin-guide/kernel-parameters.txt | 4367 ++++++++++++++++++++++ 2 files changed, 4370 insertions(+), 4371 deletions(-) create mode 100644 Documentation/admin-guide/kernel-parameters.txt diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index 37105aedb2e4..b516164999a8 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -198,4378 +198,10 @@ and is between 256 and 4096 characters. It is defined in the file Finally, the [KMG] suffix is commonly described after a number of kernel parameter values. These 'K', 'M', and 'G' letters represent the _binary_ multipliers 'Kilo', 'Mega', and 'Giga', equalling 2^10, 2^20, and 2^30 -bytes respectively. Such letter suffixes can also be entirely omitted:: +bytes respectively. Such letter suffixes can also be entirely omitted: - - acpi= [HW,ACPI,X86,ARM64] - Advanced Configuration and Power Interface - Format: { force | on | off | strict | noirq | rsdt | - copy_dsdt } - force -- enable ACPI if default was off - on -- enable ACPI but allow fallback to DT [arm64] - off -- disable ACPI if default was on - noirq -- do not use ACPI for IRQ routing - strict -- Be less tolerant of platforms that are not - strictly ACPI specification compliant. - rsdt -- prefer RSDT over (default) XSDT - copy_dsdt -- copy DSDT to memory - For ARM64, ONLY "acpi=off", "acpi=on" or "acpi=force" - are available - - See also Documentation/power/runtime_pm.txt, pci=noacpi - - acpi_apic_instance= [ACPI, IOAPIC] - Format: - 2: use 2nd APIC table, if available - 1,0: use 1st APIC table - default: 0 - - acpi_backlight= [HW,ACPI] - acpi_backlight=vendor - acpi_backlight=video - If set to vendor, prefer vendor specific driver - (e.g. thinkpad_acpi, sony_acpi, etc.) instead - of the ACPI video.ko driver. - - acpi_force_32bit_fadt_addr - force FADT to use 32 bit addresses rather than the - 64 bit X_* addresses. Some firmware have broken 64 - bit addresses for force ACPI ignore these and use - the older legacy 32 bit addresses. - - acpica_no_return_repair [HW, ACPI] - Disable AML predefined validation mechanism - This mechanism can repair the evaluation result to make - the return objects more ACPI specification compliant. - This option is useful for developers to identify the - root cause of an AML interpreter issue when the issue - has something to do with the repair mechanism. - - acpi.debug_layer= [HW,ACPI,ACPI_DEBUG] - acpi.debug_level= [HW,ACPI,ACPI_DEBUG] - Format: - CONFIG_ACPI_DEBUG must be enabled to produce any ACPI - debug output. Bits in debug_layer correspond to a - _COMPONENT in an ACPI source file, e.g., - #define _COMPONENT ACPI_PCI_COMPONENT - Bits in debug_level correspond to a level in - ACPI_DEBUG_PRINT statements, e.g., - ACPI_DEBUG_PRINT((ACPI_DB_INFO, ... - The debug_level mask defaults to "info". See - Documentation/acpi/debug.txt for more information about - debug layers and levels. - - Enable processor driver info messages: - acpi.debug_layer=0x20000000 - Enable PCI/PCI interrupt routing info messages: - acpi.debug_layer=0x400000 - Enable AML "Debug" output, i.e., stores to the Debug - object while interpreting AML: - acpi.debug_layer=0xffffffff acpi.debug_level=0x2 - Enable all messages related to ACPI hardware: - acpi.debug_layer=0x2 acpi.debug_level=0xffffffff - - Some values produce so much output that the system is - unusable. The "log_buf_len" parameter may be useful - if you need to capture more output. - - acpi_enforce_resources= [ACPI] - { strict | lax | no } - Check for resource conflicts between native drivers - and ACPI OperationRegions (SystemIO and SystemMemory - only). IO ports and memory declared in ACPI might be - used by the ACPI subsystem in arbitrary AML code and - can interfere with legacy drivers. - strict (default): access to resources claimed by ACPI - is denied; legacy drivers trying to access reserved - resources will fail to bind to device using them. - lax: access to resources claimed by ACPI is allowed; - legacy drivers trying to access reserved resources - will bind successfully but a warning message is logged. - no: ACPI OperationRegions are not marked as reserved, - no further checks are performed. - - acpi_force_table_verification [HW,ACPI] - Enable table checksum verification during early stage. - By default, this is disabled due to x86 early mapping - size limitation. - - acpi_irq_balance [HW,ACPI] - ACPI will balance active IRQs - default in APIC mode - - acpi_irq_nobalance [HW,ACPI] - ACPI will not move active IRQs (default) - default in PIC mode - - acpi_irq_isa= [HW,ACPI] If irq_balance, mark listed IRQs used by ISA - Format: ,... - - acpi_irq_pci= [HW,ACPI] If irq_balance, clear listed IRQs for - use by PCI - Format: ,... - - acpi_no_auto_serialize [HW,ACPI] - Disable auto-serialization of AML methods - AML control methods that contain the opcodes to create - named objects will be marked as "Serialized" by the - auto-serialization feature. - This feature is enabled by default. - This option allows to turn off the feature. - - acpi_no_memhotplug [ACPI] Disable memory hotplug. Useful for kdump - kernels. - - acpi_no_static_ssdt [HW,ACPI] - Disable installation of static SSDTs at early boot time - By default, SSDTs contained in the RSDT/XSDT will be - installed automatically and they will appear under - /sys/firmware/acpi/tables. - This option turns off this feature. - Note that specifying this option does not affect - dynamic table installation which will install SSDT - tables to /sys/firmware/acpi/tables/dynamic. - - acpi_rsdp= [ACPI,EFI,KEXEC] - Pass the RSDP address to the kernel, mostly used - on machines running EFI runtime service to boot the - second kernel for kdump. - - acpi_os_name= [HW,ACPI] Tell ACPI BIOS the name of the OS - Format: To spoof as Windows 98: ="Microsoft Windows" - - acpi_rev_override [ACPI] Override the _REV object to return 5 (instead - of 2 which is mandated by ACPI 6) as the supported ACPI - specification revision (when using this switch, it may - be necessary to carry out a cold reboot _twice_ in a - row to make it take effect on the platform firmware). - - acpi_osi= [HW,ACPI] Modify list of supported OS interface strings - acpi_osi="string1" # add string1 - acpi_osi="!string2" # remove string2 - acpi_osi=!* # remove all strings - acpi_osi=! # disable all built-in OS vendor - strings - acpi_osi=!! # enable all built-in OS vendor - strings - acpi_osi= # disable all strings - - 'acpi_osi=!' can be used in combination with single or - multiple 'acpi_osi="string1"' to support specific OS - vendor string(s). Note that such command can only - affect the default state of the OS vendor strings, thus - it cannot affect the default state of the feature group - strings and the current state of the OS vendor strings, - specifying it multiple times through kernel command line - is meaningless. This command is useful when one do not - care about the state of the feature group strings which - should be controlled by the OSPM. - Examples: - 1. 'acpi_osi=! acpi_osi="Windows 2000"' is equivalent - to 'acpi_osi="Windows 2000" acpi_osi=!', they all - can make '_OSI("Windows 2000")' TRUE. - - 'acpi_osi=' cannot be used in combination with other - 'acpi_osi=' command lines, the _OSI method will not - exist in the ACPI namespace. NOTE that such command can - only affect the _OSI support state, thus specifying it - multiple times through kernel command line is also - meaningless. - Examples: - 1. 'acpi_osi=' can make 'CondRefOf(_OSI, Local1)' - FALSE. - - 'acpi_osi=!*' can be used in combination with single or - multiple 'acpi_osi="string1"' to support specific - string(s). Note that such command can affect the - current state of both the OS vendor strings and the - feature group strings, thus specifying it multiple times - through kernel command line is meaningful. But it may - still not able to affect the final state of a string if - there are quirks related to this string. This command - is useful when one want to control the state of the - feature group strings to debug BIOS issues related to - the OSPM features. - Examples: - 1. 'acpi_osi="Module Device" acpi_osi=!*' can make - '_OSI("Module Device")' FALSE. - 2. 'acpi_osi=!* acpi_osi="Module Device"' can make - '_OSI("Module Device")' TRUE. - 3. 'acpi_osi=! acpi_osi=!* acpi_osi="Windows 2000"' is - equivalent to - 'acpi_osi=!* acpi_osi=! acpi_osi="Windows 2000"' - and - 'acpi_osi=!* acpi_osi="Windows 2000" acpi_osi=!', - they all will make '_OSI("Windows 2000")' TRUE. - - acpi_pm_good [X86] - Override the pmtimer bug detection: force the kernel - to assume that this machine's pmtimer latches its value - and always returns good values. - - acpi_sci= [HW,ACPI] ACPI System Control Interrupt trigger mode - Format: { level | edge | high | low } - - acpi_skip_timer_override [HW,ACPI] - Recognize and ignore IRQ0/pin2 Interrupt Override. - For broken nForce2 BIOS resulting in XT-PIC timer. - - acpi_sleep= [HW,ACPI] Sleep options - Format: { s3_bios, s3_mode, s3_beep, s4_nohwsig, - old_ordering, nonvs, sci_force_enable } - See Documentation/power/video.txt for information on - s3_bios and s3_mode. - s3_beep is for debugging; it makes the PC's speaker beep - as soon as the kernel's real-mode entry point is called. - s4_nohwsig prevents ACPI hardware signature from being - used during resume from hibernation. - old_ordering causes the ACPI 1.0 ordering of the _PTS - control method, with respect to putting devices into - low power states, to be enforced (the ACPI 2.0 ordering - of _PTS is used by default). - nonvs prevents the kernel from saving/restoring the - ACPI NVS memory during suspend/hibernation and resume. - sci_force_enable causes the kernel to set SCI_EN directly - on resume from S1/S3 (which is against the ACPI spec, - but some broken systems don't work without it). - - acpi_use_timer_override [HW,ACPI] - Use timer override. For some broken Nvidia NF5 boards - that require a timer override, but don't have HPET - - add_efi_memmap [EFI; X86] Include EFI memory map in - kernel's map of available physical RAM. - - agp= [AGP] - { off | try_unsupported } - off: disable AGP support - try_unsupported: try to drive unsupported chipsets - (may crash computer or cause data corruption) - - ALSA [HW,ALSA] - See Documentation/sound/alsa/alsa-parameters.txt - - alignment= [KNL,ARM] - Allow the default userspace alignment fault handler - behaviour to be specified. Bit 0 enables warnings, - bit 1 enables fixups, and bit 2 sends a segfault. - - align_va_addr= [X86-64] - Align virtual addresses by clearing slice [14:12] when - allocating a VMA at process creation time. This option - gives you up to 3% performance improvement on AMD F15h - machines (where it is enabled by default) for a - CPU-intensive style benchmark, and it can vary highly in - a microbenchmark depending on workload and compiler. - - 32: only for 32-bit processes - 64: only for 64-bit processes - on: enable for both 32- and 64-bit processes - off: disable for both 32- and 64-bit processes - - alloc_snapshot [FTRACE] - Allocate the ftrace snapshot buffer on boot up when the - main buffer is allocated. This is handy if debugging - and you need to use tracing_snapshot() on boot up, and - do not want to use tracing_snapshot_alloc() as it needs - to be done where GFP_KERNEL allocations are allowed. - - amd_iommu= [HW,X86-64] - Pass parameters to the AMD IOMMU driver in the system. - Possible values are: - fullflush - enable flushing of IO/TLB entries when - they are unmapped. Otherwise they are - flushed before they will be reused, which - is a lot of faster - off - do not initialize any AMD IOMMU found in - the system - force_isolation - Force device isolation for all - devices. The IOMMU driver is not - allowed anymore to lift isolation - requirements as needed. This option - does not override iommu=pt - - amd_iommu_dump= [HW,X86-64] - Enable AMD IOMMU driver option to dump the ACPI table - for AMD IOMMU. With this option enabled, AMD IOMMU - driver will print ACPI tables for AMD IOMMU during - IOMMU initialization. - - amd_iommu_intr= [HW,X86-64] - Specifies one of the following AMD IOMMU interrupt - remapping modes: - legacy - Use legacy interrupt remapping mode. - vapic - Use virtual APIC mode, which allows IOMMU - to inject interrupts directly into guest. - This mode requires kvm-amd.avic=1. - (Default when IOMMU HW support is present.) - - amijoy.map= [HW,JOY] Amiga joystick support - Map of devices attached to JOY0DAT and JOY1DAT - Format: , - See also Documentation/input/joystick.txt - - analog.map= [HW,JOY] Analog joystick and gamepad support - Specifies type or capabilities of an analog joystick - connected to one of 16 gameports - Format: ,,.. - - apc= [HW,SPARC] - Power management functions (SPARCstation-4/5 + deriv.) - Format: noidle - Disable APC CPU standby support. SPARCstation-Fox does - not play well with APC CPU idle - disable it if you have - APC and your system crashes randomly. - - apic= [APIC,X86-32] Advanced Programmable Interrupt Controller - Change the output verbosity whilst booting - Format: { quiet (default) | verbose | debug } - Change the amount of debugging information output - when initialising the APIC and IO-APIC components. - - apic_extnmi= [APIC,X86] External NMI delivery setting - Format: { bsp (default) | all | none } - bsp: External NMI is delivered only to CPU 0 - all: External NMIs are broadcast to all CPUs as a - backup of CPU 0 - none: External NMI is masked for all CPUs. This is - useful so that a dump capture kernel won't be - shot down by NMI - - autoconf= [IPV6] - See Documentation/networking/ipv6.txt. - - show_lapic= [APIC,X86] Advanced Programmable Interrupt Controller - Limit apic dumping. The parameter defines the maximal - number of local apics being dumped. Also it is possible - to set it to "all" by meaning -- no limit here. - Format: { 1 (default) | 2 | ... | all }. - The parameter valid if only apic=debug or - apic=verbose is specified. - Example: apic=debug show_lapic=all - - apm= [APM] Advanced Power Management - See header of arch/x86/kernel/apm_32.c. - - arcrimi= [HW,NET] ARCnet - "RIM I" (entirely mem-mapped) cards - Format: ,, - - ataflop= [HW,M68k] - - atarimouse= [HW,MOUSE] Atari Mouse - - atkbd.extra= [HW] Enable extra LEDs and keys on IBM RapidAccess, - EzKey and similar keyboards - - atkbd.reset= [HW] Reset keyboard during initialization - - atkbd.set= [HW] Select keyboard code set - Format: (2 = AT (default), 3 = PS/2) - - atkbd.scroll= [HW] Enable scroll wheel on MS Office and similar - keyboards - - atkbd.softraw= [HW] Choose between synthetic and real raw mode - Format: (0 = real, 1 = synthetic (default)) - - atkbd.softrepeat= [HW] - Use software keyboard repeat - - audit= [KNL] Enable the audit sub-system - Format: { "0" | "1" } (0 = disabled, 1 = enabled) - 0 - kernel audit is disabled and can not be enabled - until the next reboot - unset - kernel audit is initialized but disabled and - will be fully enabled by the userspace auditd. - 1 - kernel audit is initialized and partially enabled, - storing at most audit_backlog_limit messages in - RAM until it is fully enabled by the userspace - auditd. - Default: unset - - audit_backlog_limit= [KNL] Set the audit queue size limit. - Format: (must be >=0) - Default: 64 - - bau= [X86_UV] Enable the BAU on SGI UV. The default - behavior is to disable the BAU (i.e. bau=0). - Format: { "0" | "1" } - 0 - Disable the BAU. - 1 - Enable the BAU. - unset - Disable the BAU. - - baycom_epp= [HW,AX25] - Format: , - - baycom_par= [HW,AX25] BayCom Parallel Port AX.25 Modem - Format: , - See header of drivers/net/hamradio/baycom_par.c. - - baycom_ser_fdx= [HW,AX25] - BayCom Serial Port AX.25 Modem (Full Duplex Mode) - Format: ,,[,] - See header of drivers/net/hamradio/baycom_ser_fdx.c. - - baycom_ser_hdx= [HW,AX25] - BayCom Serial Port AX.25 Modem (Half Duplex Mode) - Format: ,, - See header of drivers/net/hamradio/baycom_ser_hdx.c. - - blkdevparts= Manual partition parsing of block device(s) for - embedded devices based on command line input. - See Documentation/block/cmdline-partition.txt - - boot_delay= Milliseconds to delay each printk during boot. - Values larger than 10 seconds (10000) are changed to - no delay (0). - Format: integer - - bootmem_debug [KNL] Enable bootmem allocator debug messages. - - bert_disable [ACPI] - Disable BERT OS support on buggy BIOSes. - - bttv.card= [HW,V4L] bttv (bt848 + bt878 based grabber cards) - bttv.radio= Most important insmod options are available as - kernel args too. - bttv.pll= See Documentation/video4linux/bttv/Insmod-options - bttv.tuner= - - bulk_remove=off [PPC] This parameter disables the use of the pSeries - firmware feature for flushing multiple hpte entries - at a time. - - c101= [NET] Moxa C101 synchronous serial card - - cachesize= [BUGS=X86-32] Override level 2 CPU cache size detection. - Sometimes CPU hardware bugs make them report the cache - size incorrectly. The kernel will attempt work arounds - to fix known problems, but for some CPUs it is not - possible to determine what the correct size should be. - This option provides an override for these situations. - - ca_keys= [KEYS] This parameter identifies a specific key(s) on - the system trusted keyring to be used for certificate - trust validation. - format: { id: | builtin } - - cca= [MIPS] Override the kernel pages' cache coherency - algorithm. Accepted values range from 0 to 7 - inclusive. See arch/mips/include/asm/pgtable-bits.h - for platform specific values (SB1, Loongson3 and - others). - - ccw_timeout_log [S390] - See Documentation/s390/CommonIO for details. - - cgroup_disable= [KNL] Disable a particular controller - Format: {name of the controller(s) to disable} - The effects of cgroup_disable=foo are: - - foo isn't auto-mounted if you mount all cgroups in - a single hierarchy - - foo isn't visible as an individually mountable - subsystem - {Currently only "memory" controller deal with this and - cut the overhead, others just disable the usage. So - only cgroup_disable=memory is actually worthy} - - cgroup_no_v1= [KNL] Disable one, multiple, all cgroup controllers in v1 - Format: { controller[,controller...] | "all" } - Like cgroup_disable, but only applies to cgroup v1; - the blacklisted controllers remain available in cgroup2. - - cgroup.memory= [KNL] Pass options to the cgroup memory controller. - Format: - nosocket -- Disable socket memory accounting. - nokmem -- Disable kernel memory accounting. - - checkreqprot [SELINUX] Set initial checkreqprot flag value. - Format: { "0" | "1" } - See security/selinux/Kconfig help text. - 0 -- check protection applied by kernel (includes - any implied execute protection). - 1 -- check protection requested by application. - Default value is set via a kernel config option. - Value can be changed at runtime via - /selinux/checkreqprot. - - cio_ignore= [S390] - See Documentation/s390/CommonIO for details. - clk_ignore_unused - [CLK] - Prevents the clock framework from automatically gating - clocks that have not been explicitly enabled by a Linux - device driver but are enabled in hardware at reset or - by the bootloader/firmware. Note that this does not - force such clocks to be always-on nor does it reserve - those clocks in any way. This parameter is useful for - debug and development, but should not be needed on a - platform with proper driver support. For more - information, see Documentation/clk.txt. - - clock= [BUGS=X86-32, HW] gettimeofday clocksource override. - [Deprecated] - Forces specified clocksource (if available) to be used - when calculating gettimeofday(). If specified - clocksource is not available, it defaults to PIT. - Format: { pit | tsc | cyclone | pmtmr } - - clocksource= Override the default clocksource - Format: - Override the default clocksource and use the clocksource - with the name specified. - Some clocksource names to choose from, depending on - the platform: - [all] jiffies (this is the base, fallback clocksource) - [ACPI] acpi_pm - [ARM] imx_timer1,OSTS,netx_timer,mpu_timer2, - pxa_timer,timer3,32k_counter,timer0_1 - [AVR32] avr32 - [X86-32] pit,hpet,tsc; - scx200_hrt on Geode; cyclone on IBM x440 - [MIPS] MIPS - [PARISC] cr16 - [S390] tod - [SH] SuperH - [SPARC64] tick - [X86-64] hpet,tsc - - clocksource.arm_arch_timer.evtstrm= - [ARM,ARM64] - Format: - Enable/disable the eventstream feature of the ARM - architected timer so that code using WFE-based polling - loops can be debugged more effectively on production - systems. - - clocksource.arm_arch_timer.fsl-a008585= - [ARM64] - Format: - Enable/disable the workaround of Freescale/NXP - erratum A-008585. This can be useful for KVM - guests, if the guest device tree doesn't show the - erratum. If unspecified, the workaround is - enabled based on the device tree. - - clearcpuid=BITNUM [X86] - Disable CPUID feature X for the kernel. See - arch/x86/include/asm/cpufeatures.h for the valid bit - numbers. Note the Linux specific bits are not necessarily - stable over kernel options, but the vendor specific - ones should be. - Also note that user programs calling CPUID directly - or using the feature without checking anything - will still see it. This just prevents it from - being used by the kernel or shown in /proc/cpuinfo. - Also note the kernel might malfunction if you disable - some critical bits. - - cma=nn[MG]@[start[MG][-end[MG]]] - [ARM,X86,KNL] - Sets the size of kernel global memory area for - contiguous memory allocations and optionally the - placement constraint by the physical address range of - memory allocations. A value of 0 disables CMA - altogether. For more information, see - include/linux/dma-contiguous.h - - cmo_free_hint= [PPC] Format: { yes | no } - Specify whether pages are marked as being inactive - when they are freed. This is used in CMO environments - to determine OS memory pressure for page stealing by - a hypervisor. - Default: yes - - coherent_pool=nn[KMG] [ARM,KNL] - Sets the size of memory pool for coherent, atomic dma - allocations, by default set to 256K. - - code_bytes [X86] How many bytes of object code to print - in an oops report. - Range: 0 - 8192 - Default: 64 - - com20020= [HW,NET] ARCnet - COM20020 chipset - Format: - [,[,[,[,[,]]]]] - - com90io= [HW,NET] ARCnet - COM90xx chipset (IO-mapped buffers) - Format: [,] - - com90xx= [HW,NET] - ARCnet - COM90xx chipset (memory-mapped buffers) - Format: [,[,]] - - condev= [HW,S390] console device - conmode= - - console= [KNL] Output console device and options. - - tty Use the virtual console device . - - ttyS[,options] - ttyUSB0[,options] - Use the specified serial port. The options are of - the form "bbbbpnf", where "bbbb" is the baud rate, - "p" is parity ("n", "o", or "e"), "n" is number of - bits, and "f" is flow control ("r" for RTS or - omit it). Default is "9600n8". - - See Documentation/admin-guide/serial-console.rst for more - information. See - Documentation/networking/netconsole.txt for an - alternative. - - uart[8250],io,[,options] - uart[8250],mmio,[,options] - uart[8250],mmio16,[,options] - uart[8250],mmio32,[,options] - uart[8250],0x[,options] - Start an early, polled-mode console on the 8250/16550 - UART at the specified I/O port or MMIO address, - switching to the matching ttyS device later. - MMIO inter-register address stride is either 8-bit - (mmio), 16-bit (mmio16), or 32-bit (mmio32). - If none of [io|mmio|mmio16|mmio32], is assumed - to be equivalent to 'mmio'. 'options' are specified in - the same format described for ttyS above; if unspecified, - the h/w is not re-initialized. - - hvc Use the hypervisor console device . This is for - both Xen and PowerPC hypervisors. - - If the device connected to the port is not a TTY but a braille - device, prepend "brl," before the device type, for instance - console=brl,ttyS0 - For now, only VisioBraille is supported. - - consoleblank= [KNL] The console blank (screen saver) timeout in - seconds. Defaults to 10*60 = 10mins. A value of 0 - disables the blank timer. - - coredump_filter= - [KNL] Change the default value for - /proc//coredump_filter. - See also Documentation/filesystems/proc.txt. - - cpuidle.off=1 [CPU_IDLE] - disable the cpuidle sub-system - - cpu_init_udelay=N - [X86] Delay for N microsec between assert and de-assert - of APIC INIT to start processors. This delay occurs - on every CPU online, such as boot, and resume from suspend. - Default: 10000 - - cpcihp_generic= [HW,PCI] Generic port I/O CompactPCI driver - Format: - ,,,[,] - - crashkernel=size[KMG][@offset[KMG]] - [KNL] Using kexec, Linux can switch to a 'crash kernel' - upon panic. This parameter reserves the physical - memory region [offset, offset + size] for that kernel - image. If '@offset' is omitted, then a suitable offset - is selected automatically. Check - Documentation/kdump/kdump.txt for further details. - - crashkernel=range1:size1[,range2:size2,...][@offset] - [KNL] Same as above, but depends on the memory - in the running system. The syntax of range is - start-[end] where start and end are both - a memory unit (amount[KMG]). See also - Documentation/kdump/kdump.txt for an example. - - crashkernel=size[KMG],high - [KNL, x86_64] range could be above 4G. Allow kernel - to allocate physical memory region from top, so could - be above 4G if system have more than 4G ram installed. - Otherwise memory region will be allocated below 4G, if - available. - It will be ignored if crashkernel=X is specified. - crashkernel=size[KMG],low - [KNL, x86_64] range under 4G. When crashkernel=X,high - is passed, kernel could allocate physical memory region - above 4G, that cause second kernel crash on system - that require some amount of low memory, e.g. swiotlb - requires at least 64M+32K low memory, also enough extra - low memory is needed to make sure DMA buffers for 32-bit - devices won't run out. Kernel would try to allocate at - at least 256M below 4G automatically. - This one let user to specify own low range under 4G - for second kernel instead. - 0: to disable low allocation. - It will be ignored when crashkernel=X,high is not used - or memory reserved is below 4G. - - cryptomgr.notests - [KNL] Disable crypto self-tests - - cs89x0_dma= [HW,NET] - Format: - - cs89x0_media= [HW,NET] - Format: { rj45 | aui | bnc } - - dasd= [HW,NET] - See header of drivers/s390/block/dasd_devmap.c. - - db9.dev[2|3]= [HW,JOY] Multisystem joystick support via parallel port - (one device per port) - Format: , - See also Documentation/input/joystick-parport.txt - - ddebug_query= [KNL,DYNAMIC_DEBUG] Enable debug messages at early boot - time. See Documentation/dynamic-debug-howto.txt for - details. Deprecated, see dyndbg. - - debug [KNL] Enable kernel debugging (events log level). - - debug_locks_verbose= - [KNL] verbose self-tests - Format=<0|1> - Print debugging info while doing the locking API - self-tests. - We default to 0 (no extra messages), setting it to - 1 will print _a lot_ more information - normally - only useful to kernel developers. - - debug_objects [KNL] Enable object debugging - - no_debug_objects - [KNL] Disable object debugging - - debug_guardpage_minorder= - [KNL] When CONFIG_DEBUG_PAGEALLOC is set, this - parameter allows control of the order of pages that will - be intentionally kept free (and hence protected) by the - buddy allocator. Bigger value increase the probability - of catching random memory corruption, but reduce the - amount of memory for normal system use. The maximum - possible value is MAX_ORDER/2. Setting this parameter - to 1 or 2 should be enough to identify most random - memory corruption problems caused by bugs in kernel or - driver code when a CPU writes to (or reads from) a - random memory location. Note that there exists a class - of memory corruptions problems caused by buggy H/W or - F/W or by drivers badly programing DMA (basically when - memory is written at bus level and the CPU MMU is - bypassed) which are not detectable by - CONFIG_DEBUG_PAGEALLOC, hence this option will not help - tracking down these problems. - - debug_pagealloc= - [KNL] When CONFIG_DEBUG_PAGEALLOC is set, this - parameter enables the feature at boot time. In - default, it is disabled. We can avoid allocating huge - chunk of memory for debug pagealloc if we don't enable - it at boot time and the system will work mostly same - with the kernel built without CONFIG_DEBUG_PAGEALLOC. - on: enable the feature - - debugpat [X86] Enable PAT debugging - - decnet.addr= [HW,NET] - Format: [,] - See also Documentation/networking/decnet.txt. - - default_hugepagesz= - [same as hugepagesz=] The size of the default - HugeTLB page size. This is the size represented by - the legacy /proc/ hugepages APIs, used for SHM, and - default size when mounting hugetlbfs filesystems. - Defaults to the default architecture's huge page size - if not specified. - - dhash_entries= [KNL] - Set number of hash buckets for dentry cache. - - disable_1tb_segments [PPC] - Disables the use of 1TB hash page table segments. This - causes the kernel to fall back to 256MB segments which - can be useful when debugging issues that require an SLB - miss to occur. - - disable= [IPV6] - See Documentation/networking/ipv6.txt. - - disable_radix [PPC] - Disable RADIX MMU mode on POWER9 - - disable_cpu_apicid= [X86,APIC,SMP] - Format: - The number of initial APIC ID for the - corresponding CPU to be disabled at boot, - mostly used for the kdump 2nd kernel to - disable BSP to wake up multiple CPUs without - causing system reset or hang due to sending - INIT from AP to BSP. - - disable_ddw [PPC/PSERIES] - Disable Dynamic DMA Window support. Use this if - to workaround buggy firmware. - - disable_ipv6= [IPV6] - See Documentation/networking/ipv6.txt. - - disable_mtrr_cleanup [X86] - The kernel tries to adjust MTRR layout from continuous - to discrete, to make X server driver able to add WB - entry later. This parameter disables that. - - disable_mtrr_trim [X86, Intel and AMD only] - By default the kernel will trim any uncacheable - memory out of your available memory pool based on - MTRR settings. This parameter disables that behavior, - possibly causing your machine to run very slowly. - - disable_timer_pin_1 [X86] - Disable PIN 1 of APIC timer - Can be useful to work around chipset bugs. - - dis_ucode_ldr [X86] Disable the microcode loader. - - dma_debug=off If the kernel is compiled with DMA_API_DEBUG support, - this option disables the debugging code at boot. - - dma_debug_entries= - This option allows to tune the number of preallocated - entries for DMA-API debugging code. One entry is - required per DMA-API allocation. Use this if the - DMA-API debugging code disables itself because the - architectural default is too low. - - dma_debug_driver= - With this option the DMA-API debugging driver - filter feature can be enabled at boot time. Just - pass the driver to filter for as the parameter. - The filter can be disabled or changed to another - driver later using sysfs. - - drm_kms_helper.edid_firmware=[:][,[:]] - Broken monitors, graphic adapters, KVMs and EDIDless - panels may send no or incorrect EDID data sets. - This parameter allows to specify an EDID data sets - in the /lib/firmware directory that are used instead. - Generic built-in EDID data sets are used, if one of - edid/1024x768.bin, edid/1280x1024.bin, - edid/1680x1050.bin, or edid/1920x1080.bin is given - and no file with the same name exists. Details and - instructions how to build your own EDID data are - available in Documentation/EDID/HOWTO.txt. An EDID - data set will only be used for a particular connector, - if its name and a colon are prepended to the EDID - name. Each connector may use a unique EDID data - set by separating the files with a comma. An EDID - data set with no connector name will be used for - any connectors not explicitly specified. - - dscc4.setup= [NET] - - dyndbg[="val"] [KNL,DYNAMIC_DEBUG] - module.dyndbg[="val"] - Enable debug messages at boot time. See - Documentation/dynamic-debug-howto.txt for details. - - nompx [X86] Disables Intel Memory Protection Extensions. - See Documentation/x86/intel_mpx.txt for more - information about the feature. - - nopku [X86] Disable Memory Protection Keys CPU feature found - in some Intel CPUs. - - eagerfpu= [X86] - on enable eager fpu restore - off disable eager fpu restore - auto selects the default scheme, which automatically - enables eagerfpu restore for xsaveopt. - - module.async_probe [KNL] - Enable asynchronous probe on this module. - - early_ioremap_debug [KNL] - Enable debug messages in early_ioremap support. This - is useful for tracking down temporary early mappings - which are not unmapped. - - earlycon= [KNL] Output early console device and options. - - When used with no options, the early console is - determined by the stdout-path property in device - tree's chosen node. - - cdns,[,options] - Start an early, polled-mode console on a Cadence - (xuartps) serial port at the specified address. Only - supported option is baud rate. If baud rate is not - specified, the serial port must already be setup and - configured. - - uart[8250],io,[,options] - uart[8250],mmio,[,options] - uart[8250],mmio32,[,options] - uart[8250],mmio32be,[,options] - uart[8250],0x[,options] - Start an early, polled-mode console on the 8250/16550 - UART at the specified I/O port or MMIO address. - MMIO inter-register address stride is either 8-bit - (mmio) or 32-bit (mmio32 or mmio32be). - If none of [io|mmio|mmio32|mmio32be], is assumed - to be equivalent to 'mmio'. 'options' are specified - in the same format described for "console=ttyS"; if - unspecified, the h/w is not initialized. - - pl011, - pl011,mmio32, - Start an early, polled-mode console on a pl011 serial - port at the specified address. The pl011 serial port - must already be setup and configured. Options are not - yet supported. If 'mmio32' is specified, then only - the driver will use only 32-bit accessors to read/write - the device registers. - - meson, - Start an early, polled-mode console on a meson serial - port at the specified address. The serial port must - already be setup and configured. Options are not yet - supported. - - msm_serial, - Start an early, polled-mode console on an msm serial - port at the specified address. The serial port - must already be setup and configured. Options are not - yet supported. - - msm_serial_dm, - Start an early, polled-mode console on an msm serial - dm port at the specified address. The serial port - must already be setup and configured. Options are not - yet supported. - - smh Use ARM semihosting calls for early console. - - s3c2410, - s3c2412, - s3c2440, - s3c6400, - s5pv210, - exynos4210, - Use early console provided by serial driver available - on Samsung SoCs, requires selecting proper type and - a correct base address of the selected UART port. The - serial port must already be setup and configured. - Options are not yet supported. - - lpuart, - lpuart32, - Use early console provided by Freescale LP UART driver - found on Freescale Vybrid and QorIQ LS1021A processors. - A valid base address must be provided, and the serial - port must already be setup and configured. - - armada3700_uart, - Start an early, polled-mode console on the - Armada 3700 serial port at the specified - address. The serial port must already be setup - and configured. Options are not yet supported. - - earlyprintk= [X86,SH,BLACKFIN,ARM,M68k] - earlyprintk=vga - earlyprintk=efi - earlyprintk=xen - earlyprintk=serial[,ttySn[,baudrate]] - earlyprintk=serial[,0x...[,baudrate]] - earlyprintk=ttySn[,baudrate] - earlyprintk=dbgp[debugController#] - earlyprintk=pciserial,bus:device.function[,baudrate] - - earlyprintk is useful when the kernel crashes before - the normal console is initialized. It is not enabled by - default because it has some cosmetic problems. - - Append ",keep" to not disable it when the real console - takes over. - - Only one of vga, efi, serial, or usb debug port can - be used at a time. - - Currently only ttyS0 and ttyS1 may be specified by - name. Other I/O ports may be explicitly specified - on some architectures (x86 and arm at least) by - replacing ttySn with an I/O port address, like this: - earlyprintk=serial,0x1008,115200 - You can find the port for a given device in - /proc/tty/driver/serial: - 2: uart:ST16650V2 port:00001008 irq:18 ... - - Interaction with the standard serial driver is not - very good. - - The VGA and EFI output is eventually overwritten by - the real console. - - The xen output can only be used by Xen PV guests. - - edac_report= [HW,EDAC] Control how to report EDAC event - Format: {"on" | "off" | "force"} - on: enable EDAC to report H/W event. May be overridden - by other higher priority error reporting module. - off: disable H/W event reporting through EDAC. - force: enforce the use of EDAC to report H/W event. - default: on. - - ekgdboc= [X86,KGDB] Allow early kernel console debugging - ekgdboc=kbd - - This is designed to be used in conjunction with - the boot argument: earlyprintk=vga - - edd= [EDD] - Format: {"off" | "on" | "skip[mbr]"} - - efi= [EFI] - Format: { "old_map", "nochunk", "noruntime", "debug" } - old_map [X86-64]: switch to the old ioremap-based EFI - runtime services mapping. 32-bit still uses this one by - default. - nochunk: disable reading files in "chunks" in the EFI - boot stub, as chunking can cause problems with some - firmware implementations. - noruntime : disable EFI runtime services support - debug: enable misc debug output - - efi_no_storage_paranoia [EFI; X86] - Using this parameter you can use more than 50% of - your efi variable storage. Use this parameter only if - you are really sure that your UEFI does sane gc and - fulfills the spec otherwise your board may brick. - - efi_fake_mem= nn[KMG]@ss[KMG]:aa[,nn[KMG]@ss[KMG]:aa,..] [EFI; X86] - Add arbitrary attribute to specific memory range by - updating original EFI memory map. - Region of memory which aa attribute is added to is - from ss to ss+nn. - If efi_fake_mem=2G@4G:0x10000,2G@0x10a0000000:0x10000 - is specified, EFI_MEMORY_MORE_RELIABLE(0x10000) - attribute is added to range 0x100000000-0x180000000 and - 0x10a0000000-0x1120000000. - - Using this parameter you can do debugging of EFI memmap - related feature. For example, you can do debugging of - Address Range Mirroring feature even if your box - doesn't support it. - - efivar_ssdt= [EFI; X86] Name of an EFI variable that contains an SSDT - that is to be dynamically loaded by Linux. If there are - multiple variables with the same name but with different - vendor GUIDs, all of them will be loaded. See - Documentation/acpi/ssdt-overlays.txt for details. - - - eisa_irq_edge= [PARISC,HW] - See header of drivers/parisc/eisa.c. - - elanfreq= [X86-32] - See comment before function elanfreq_setup() in - arch/x86/kernel/cpu/cpufreq/elanfreq.c. - - elevator= [IOSCHED] - Format: {"cfq" | "deadline" | "noop"} - See Documentation/block/cfq-iosched.txt and - Documentation/block/deadline-iosched.txt for details. - - elfcorehdr=[size[KMG]@]offset[KMG] [IA64,PPC,SH,X86,S390] - Specifies physical address of start of kernel core - image elf header and optionally the size. Generally - kexec loader will pass this option to capture kernel. - See Documentation/kdump/kdump.txt for details. - - enable_mtrr_cleanup [X86] - The kernel tries to adjust MTRR layout from continuous - to discrete, to make X server driver able to add WB - entry later. This parameter enables that. - - enable_timer_pin_1 [X86] - Enable PIN 1 of APIC timer - Can be useful to work around chipset bugs - (in particular on some ATI chipsets). - The kernel tries to set a reasonable default. - - enforcing [SELINUX] Set initial enforcing status. - Format: {"0" | "1"} - See security/selinux/Kconfig help text. - 0 -- permissive (log only, no denials). - 1 -- enforcing (deny and log). - Default value is 0. - Value can be changed at runtime via /selinux/enforce. - - erst_disable [ACPI] - Disable Error Record Serialization Table (ERST) - support. - - ether= [HW,NET] Ethernet cards parameters - This option is obsoleted by the "netdev=" option, which - has equivalent usage. See its documentation for details. - - evm= [EVM] - Format: { "fix" } - Permit 'security.evm' to be updated regardless of - current integrity status. - - failslab= - fail_page_alloc= - fail_make_request=[KNL] - General fault injection mechanism. - Format: ,,, - See also Documentation/fault-injection/. - - floppy= [HW] - See Documentation/blockdev/floppy.txt. - - force_pal_cache_flush - [IA-64] Avoid check_sal_cache_flush which may hang on - buggy SAL_CACHE_FLUSH implementations. Using this - parameter will force ia64_sal_cache_flush to call - ia64_pal_cache_flush instead of SAL_CACHE_FLUSH. - - forcepae [X86-32] - Forcefully enable Physical Address Extension (PAE). - Many Pentium M systems disable PAE but may have a - functionally usable PAE implementation. - Warning: use of this parameter will taint the kernel - and may cause unknown problems. - - ftrace=[tracer] - [FTRACE] will set and start the specified tracer - as early as possible in order to facilitate early - boot debugging. - - ftrace_dump_on_oops[=orig_cpu] - [FTRACE] will dump the trace buffers on oops. - If no parameter is passed, ftrace will dump - buffers of all CPUs, but if you pass orig_cpu, it will - dump only the buffer of the CPU that triggered the - oops. - - ftrace_filter=[function-list] - [FTRACE] Limit the functions traced by the function - tracer at boot up. function-list is a comma separated - list of functions. This list can be changed at run - time by the set_ftrace_filter file in the debugfs - tracing directory. - - ftrace_notrace=[function-list] - [FTRACE] Do not trace the functions specified in - function-list. This list can be changed at run time - by the set_ftrace_notrace file in the debugfs - tracing directory. - - ftrace_graph_filter=[function-list] - [FTRACE] Limit the top level callers functions traced - by the function graph tracer at boot up. - function-list is a comma separated list of functions - that can be changed at run time by the - set_graph_function file in the debugfs tracing directory. - - ftrace_graph_notrace=[function-list] - [FTRACE] Do not trace from the functions specified in - function-list. This list is a comma separated list of - functions that can be changed at run time by the - set_graph_notrace file in the debugfs tracing directory. - - gamecon.map[2|3]= - [HW,JOY] Multisystem joystick and NES/SNES/PSX pad - support via parallel port (up to 5 devices per port) - Format: ,,,,, - See also Documentation/input/joystick-parport.txt - - gamma= [HW,DRM] - - gart_fix_e820= [X86_64] disable the fix e820 for K8 GART - Format: off | on - default: on - - gcov_persist= [GCOV] When non-zero (default), profiling data for - kernel modules is saved and remains accessible via - debugfs, even when the module is unloaded/reloaded. - When zero, profiling data is discarded and associated - debugfs files are removed at module unload time. - - gpt [EFI] Forces disk with valid GPT signature but - invalid Protective MBR to be treated as GPT. If the - primary GPT is corrupted, it enables the backup/alternate - GPT to be used instead. - - grcan.enable0= [HW] Configuration of physical interface 0. Determines - the "Enable 0" bit of the configuration register. - Format: 0 | 1 - Default: 0 - grcan.enable1= [HW] Configuration of physical interface 1. Determines - the "Enable 0" bit of the configuration register. - Format: 0 | 1 - Default: 0 - grcan.select= [HW] Select which physical interface to use. - Format: 0 | 1 - Default: 0 - grcan.txsize= [HW] Sets the size of the tx buffer. - Format: such that (txsize & ~0x1fffc0) == 0. - Default: 1024 - grcan.rxsize= [HW] Sets the size of the rx buffer. - Format: such that (rxsize & ~0x1fffc0) == 0. - Default: 1024 - - gpio-mockup.gpio_mockup_ranges - [HW] Sets the ranges of gpiochip of for this device. - Format: ,,,... - - hardlockup_all_cpu_backtrace= - [KNL] Should the hard-lockup detector generate - backtraces on all cpus. - Format: - - hashdist= [KNL,NUMA] Large hashes allocated during boot - are distributed across NUMA nodes. Defaults on - for 64-bit NUMA, off otherwise. - Format: 0 | 1 (for off | on) - - hcl= [IA-64] SGI's Hardware Graph compatibility layer - - hd= [EIDE] (E)IDE hard drive subsystem geometry - Format: ,, - - hest_disable [ACPI] - Disable Hardware Error Source Table (HEST) support; - corresponding firmware-first mode error processing - logic will be disabled. - - highmem=nn[KMG] [KNL,BOOT] forces the highmem zone to have an exact - size of . This works even on boxes that have no - highmem otherwise. This also works to reduce highmem - size on bigger boxes. - - highres= [KNL] Enable/disable high resolution timer mode. - Valid parameters: "on", "off" - Default: "on" - - hisax= [HW,ISDN] - See Documentation/isdn/README.HiSax. - - hlt [BUGS=ARM,SH] - - hpet= [X86-32,HPET] option to control HPET usage - Format: { enable (default) | disable | force | - verbose } - disable: disable HPET and use PIT instead - force: allow force enabled of undocumented chips (ICH4, - VIA, nVidia) - verbose: show contents of HPET registers during setup - - hpet_mmap= [X86, HPET_MMAP] Allow userspace to mmap HPET - registers. Default set by CONFIG_HPET_MMAP_DEFAULT. - - hugepages= [HW,X86-32,IA-64] HugeTLB pages to allocate at boot. - hugepagesz= [HW,IA-64,PPC,X86-64] The size of the HugeTLB pages. - On x86-64 and powerpc, this option can be specified - multiple times interleaved with hugepages= to reserve - huge pages of different sizes. Valid pages sizes on - x86-64 are 2M (when the CPU supports "pse") and 1G - (when the CPU supports the "pdpe1gb" cpuinfo flag). - - hvc_iucv= [S390] Number of z/VM IUCV hypervisor console (HVC) - terminal devices. Valid values: 0..8 - hvc_iucv_allow= [S390] Comma-separated list of z/VM user IDs. - If specified, z/VM IUCV HVC accepts connections - from listed z/VM user IDs only. - - hwthread_map= [METAG] Comma-separated list of Linux cpu id to - hardware thread id mappings. - Format: : - - keep_bootcon [KNL] - Do not unregister boot console at start. This is only - useful for debugging when something happens in the window - between unregistering the boot console and initializing - the real console. - - i2c_bus= [HW] Override the default board specific I2C bus speed - or register an additional I2C bus that is not - registered from board initialization code. - Format: - , - - i8042.debug [HW] Toggle i8042 debug mode - i8042.unmask_kbd_data - [HW] Enable printing of interrupt data from the KBD port - (disabled by default, and as a pre-condition - requires that i8042.debug=1 be enabled) - i8042.direct [HW] Put keyboard port into non-translated mode - i8042.dumbkbd [HW] Pretend that controller can only read data from - keyboard and cannot control its state - (Don't attempt to blink the leds) - i8042.noaux [HW] Don't check for auxiliary (== mouse) port - i8042.nokbd [HW] Don't check/create keyboard port - i8042.noloop [HW] Disable the AUX Loopback command while probing - for the AUX port - i8042.nomux [HW] Don't check presence of an active multiplexing - controller - i8042.nopnp [HW] Don't use ACPIPnP / PnPBIOS to discover KBD/AUX - controllers - i8042.notimeout [HW] Ignore timeout condition signalled by controller - i8042.reset [HW] Reset the controller during init, cleanup and - suspend-to-ram transitions, only during s2r - transitions, or never reset - Format: { 1 | Y | y | 0 | N | n } - 1, Y, y: always reset controller - 0, N, n: don't ever reset controller - Default: only on s2r transitions on x86; most other - architectures force reset to be always executed - i8042.unlock [HW] Unlock (ignore) the keylock - i8042.kbdreset [HW] Reset device connected to KBD port - - i810= [HW,DRM] - - i8k.ignore_dmi [HW] Continue probing hardware even if DMI data - indicates that the driver is running on unsupported - hardware. - i8k.force [HW] Activate i8k driver even if SMM BIOS signature - does not match list of supported models. - i8k.power_status - [HW] Report power status in /proc/i8k - (disabled by default) - i8k.restricted [HW] Allow controlling fans only if SYS_ADMIN - capability is set. - - i915.invert_brightness= - [DRM] Invert the sense of the variable that is used to - set the brightness of the panel backlight. Normally a - brightness value of 0 indicates backlight switched off, - and the maximum of the brightness value sets the backlight - to maximum brightness. If this parameter is set to 0 - (default) and the machine requires it, or this parameter - is set to 1, a brightness value of 0 sets the backlight - to maximum brightness, and the maximum of the brightness - value switches the backlight off. - -1 -- never invert brightness - 0 -- machine default - 1 -- force brightness inversion - - icn= [HW,ISDN] - Format: [,[,[,]]] - - ide-core.nodma= [HW] (E)IDE subsystem - Format: =0.0 to prevent dma on hda, =0.1 hdb =1.0 hdc - .vlb_clock .pci_clock .noflush .nohpa .noprobe .nowerr - .cdrom .chs .ignore_cable are additional options - See Documentation/ide/ide.txt. - - ide-generic.probe-mask= [HW] (E)IDE subsystem - Format: - Probe mask for legacy ISA IDE ports. Depending on - platform up to 6 ports are supported, enabled by - setting corresponding bits in the mask to 1. The - default value is 0x0, which has a special meaning. - On systems that have PCI, it triggers scanning the - PCI bus for the first and the second port, which - are then probed. On systems without PCI the value - of 0x0 enables probing the two first ports as if it - was 0x3. - - ide-pci-generic.all-generic-ide [HW] (E)IDE subsystem - Claim all unknown PCI IDE storage controllers. - - idle= [X86] - Format: idle=poll, idle=halt, idle=nomwait - Poll forces a polling idle loop that can slightly - improve the performance of waking up a idle CPU, but - will use a lot of power and make the system run hot. - Not recommended. - idle=halt: Halt is forced to be used for CPU idle. - In such case C2/C3 won't be used again. - idle=nomwait: Disable mwait for CPU C-states - - ieee754= [MIPS] Select IEEE Std 754 conformance mode - Format: { strict | legacy | 2008 | relaxed } - Default: strict - - Choose which programs will be accepted for execution - based on the IEEE 754 NaN encoding(s) supported by - the FPU and the NaN encoding requested with the value - of an ELF file header flag individually set by each - binary. Hardware implementations are permitted to - support either or both of the legacy and the 2008 NaN - encoding mode. - - Available settings are as follows: - strict accept binaries that request a NaN encoding - supported by the FPU - legacy only accept legacy-NaN binaries, if supported - by the FPU - 2008 only accept 2008-NaN binaries, if supported - by the FPU - relaxed accept any binaries regardless of whether - supported by the FPU - - The FPU emulator is always able to support both NaN - encodings, so if no FPU hardware is present or it has - been disabled with 'nofpu', then the settings of - 'legacy' and '2008' strap the emulator accordingly, - 'relaxed' straps the emulator for both legacy-NaN and - 2008-NaN, whereas 'strict' enables legacy-NaN only on - legacy processors and both NaN encodings on MIPS32 or - MIPS64 CPUs. - - The setting for ABS.fmt/NEG.fmt instruction execution - mode generally follows that for the NaN encoding, - except where unsupported by hardware. - - ignore_loglevel [KNL] - Ignore loglevel setting - this will print /all/ - kernel messages to the console. Useful for debugging. - We also add it as printk module parameter, so users - could change it dynamically, usually by - /sys/module/printk/parameters/ignore_loglevel. - - ignore_rlimit_data - Ignore RLIMIT_DATA setting for data mappings, - print warning at first misuse. Can be changed via - /sys/module/kernel/parameters/ignore_rlimit_data. - - ihash_entries= [KNL] - Set number of hash buckets for inode cache. - - ima_appraise= [IMA] appraise integrity measurements - Format: { "off" | "enforce" | "fix" | "log" } - default: "enforce" - - ima_appraise_tcb [IMA] - The builtin appraise policy appraises all files - owned by uid=0. - - ima_hash= [IMA] - Format: { md5 | sha1 | rmd160 | sha256 | sha384 - | sha512 | ... } - default: "sha1" - - The list of supported hash algorithms is defined - in crypto/hash_info.h. - - ima_policy= [IMA] - The builtin measurement policy to load during IMA - setup. Specyfing "tcb" as the value, measures all - programs exec'd, files mmap'd for exec, and all files - opened with the read mode bit set by either the - effective uid (euid=0) or uid=0. - Format: "tcb" - - ima_tcb [IMA] Deprecated. Use ima_policy= instead. - Load a policy which meets the needs of the Trusted - Computing Base. This means IMA will measure all - programs exec'd, files mmap'd for exec, and all files - opened for read by uid=0. - - ima_template= [IMA] - Select one of defined IMA measurements template formats. - Formats: { "ima" | "ima-ng" | "ima-sig" } - Default: "ima-ng" - - ima_template_fmt= - [IMA] Define a custom template format. - Format: { "field1|...|fieldN" } - - ima.ahash_minsize= [IMA] Minimum file size for asynchronous hash usage - Format: - Set the minimal file size for using asynchronous hash. - If left unspecified, ahash usage is disabled. - - ahash performance varies for different data sizes on - different crypto accelerators. This option can be used - to achieve the best performance for a particular HW. - - ima.ahash_bufsize= [IMA] Asynchronous hash buffer size - Format: - Set hashing buffer size. Default: 4k. - - ahash performance varies for different chunk sizes on - different crypto accelerators. This option can be used - to achieve best performance for particular HW. - - init= [KNL] - Format: - Run specified binary instead of /sbin/init as init - process. - - initcall_debug [KNL] Trace initcalls as they are executed. Useful - for working out where the kernel is dying during - startup. - - initcall_blacklist= [KNL] Do not execute a comma-separated list of - initcall functions. Useful for debugging built-in - modules and initcalls. - - initrd= [BOOT] Specify the location of the initial ramdisk - - init_pkru= [x86] Specify the default memory protection keys rights - register contents for all processes. 0x55555554 by - default (disallow access to all but pkey 0). Can - override in debugfs after boot. - - inport.irq= [HW] Inport (ATI XL and Microsoft) busmouse driver - Format: - - int_pln_enable [x86] Enable power limit notification interrupt - - integrity_audit=[IMA] - Format: { "0" | "1" } - 0 -- basic integrity auditing messages. (Default) - 1 -- additional integrity auditing messages. - - intel_iommu= [DMAR] Intel IOMMU driver (DMAR) option - on - Enable intel iommu driver. - off - Disable intel iommu driver. - igfx_off [Default Off] - By default, gfx is mapped as normal device. If a gfx - device has a dedicated DMAR unit, the DMAR unit is - bypassed by not enabling DMAR with this option. In - this case, gfx device will use physical address for - DMA. - forcedac [x86_64] - With this option iommu will not optimize to look - for io virtual address below 32-bit forcing dual - address cycle on pci bus for cards supporting greater - than 32-bit addressing. The default is to look - for translation below 32-bit and if not available - then look in the higher range. - strict [Default Off] - With this option on every unmap_single operation will - result in a hardware IOTLB flush operation as opposed - to batching them for performance. - sp_off [Default Off] - By default, super page will be supported if Intel IOMMU - has the capability. With this option, super page will - not be supported. - ecs_off [Default Off] - By default, extended context tables will be supported if - the hardware advertises that it has support both for the - extended tables themselves, and also PASID support. With - this option set, extended tables will not be used even - on hardware which claims to support them. - - intel_idle.max_cstate= [KNL,HW,ACPI,X86] - 0 disables intel_idle and fall back on acpi_idle. - 1 to 9 specify maximum depth of C-state. - - intel_pstate= [X86] - disable - Do not enable intel_pstate as the default - scaling driver for the supported processors - force - Enable intel_pstate on systems that prohibit it by default - in favor of acpi-cpufreq. Forcing the intel_pstate driver - instead of acpi-cpufreq may disable platform features, such - as thermal controls and power capping, that rely on ACPI - P-States information being indicated to OSPM and therefore - should be used with caution. This option does not work with - processors that aren't supported by the intel_pstate driver - or on platforms that use pcc-cpufreq instead of acpi-cpufreq. - no_hwp - Do not enable hardware P state control (HWP) - if available. - hwp_only - Only load intel_pstate on systems which support - hardware P state control (HWP) if available. - support_acpi_ppc - Enforce ACPI _PPC performance limits. If the Fixed ACPI - Description Table, specifies preferred power management - profile as "Enterprise Server" or "Performance Server", - then this feature is turned on by default. - - intremap= [X86-64, Intel-IOMMU] - on enable Interrupt Remapping (default) - off disable Interrupt Remapping - nosid disable Source ID checking - no_x2apic_optout - BIOS x2APIC opt-out request will be ignored - nopost disable Interrupt Posting - - iomem= Disable strict checking of access to MMIO memory - strict regions from userspace. - relaxed - - iommu= [x86] - off - force - noforce - biomerge - panic - nopanic - merge - nomerge - forcesac - soft - pt [x86, IA-64] - nobypass [PPC/POWERNV] - Disable IOMMU bypass, using IOMMU for PCI devices. - - - io7= [HW] IO7 for Marvel based alpha systems - See comment before marvel_specify_io7 in - arch/alpha/kernel/core_marvel.c. - - io_delay= [X86] I/O delay method - 0x80 - Standard port 0x80 based delay - 0xed - Alternate port 0xed based delay (needed on some systems) - udelay - Simple two microseconds delay - none - No delay - - ip= [IP_PNP] - See Documentation/filesystems/nfs/nfsroot.txt. - - irqaffinity= [SMP] Set the default irq affinity mask - The argument is a cpu list, as described above. - - irqfixup [HW] - When an interrupt is not handled search all handlers - for it. Intended to get systems with badly broken - firmware running. - - irqpoll [HW] - When an interrupt is not handled search all handlers - for it. Also check all handlers each timer - interrupt. Intended to get systems with badly broken - firmware running. - - isapnp= [ISAPNP] - Format: ,,, - - isolcpus= [KNL,SMP] Isolate CPUs from the general scheduler. - The argument is a cpu list, as described above. - - This option can be used to specify one or more CPUs - to isolate from the general SMP balancing and scheduling - algorithms. You can move a process onto or off an - "isolated" CPU via the CPU affinity syscalls or cpuset. - begins at 0 and the maximum value is - "number of CPUs in system - 1". - - This option is the preferred way to isolate CPUs. The - alternative -- manually setting the CPU mask of all - tasks in the system -- can cause problems and - suboptimal load balancer performance. - - iucv= [HW,NET] - - ivrs_ioapic [HW,X86_64] - Provide an override to the IOAPIC-ID<->DEVICE-ID - mapping provided in the IVRS ACPI table. For - example, to map IOAPIC-ID decimal 10 to - PCI device 00:14.0 write the parameter as: - ivrs_ioapic[10]=00:14.0 - - ivrs_hpet [HW,X86_64] - Provide an override to the HPET-ID<->DEVICE-ID - mapping provided in the IVRS ACPI table. For - example, to map HPET-ID decimal 0 to - PCI device 00:14.0 write the parameter as: - ivrs_hpet[0]=00:14.0 - - ivrs_acpihid [HW,X86_64] - Provide an override to the ACPI-HID:UID<->DEVICE-ID - mapping provided in the IVRS ACPI table. For - example, to map UART-HID:UID AMD0020:0 to - PCI device 00:14.5 write the parameter as: - ivrs_acpihid[00:14.5]=AMD0020:0 - - js= [HW,JOY] Analog joystick - See Documentation/input/joystick.txt. - - nokaslr [KNL] - When CONFIG_RANDOMIZE_BASE is set, this disables - kernel and module base offset ASLR (Address Space - Layout Randomization). - - keepinitrd [HW,ARM] - - kernelcore= [KNL,X86,IA-64,PPC] - Format: nn[KMGTPE] | "mirror" - This parameter - specifies the amount of memory usable by the kernel - for non-movable allocations. The requested amount is - spread evenly throughout all nodes in the system. The - remaining memory in each node is used for Movable - pages. In the event, a node is too small to have both - kernelcore and Movable pages, kernelcore pages will - take priority and other nodes will have a larger number - of Movable pages. The Movable zone is used for the - allocation of pages that may be reclaimed or moved - by the page migration subsystem. This means that - HugeTLB pages may not be allocated from this zone. - Note that allocations like PTEs-from-HighMem still - use the HighMem zone if it exists, and the Normal - zone if it does not. - - Instead of specifying the amount of memory (nn[KMGTPE]), - you can specify "mirror" option. In case "mirror" - option is specified, mirrored (reliable) memory is used - for non-movable allocations and remaining memory is used - for Movable pages. nn[KMGTPE] and "mirror" are exclusive, - so you can NOT specify nn[KMGTPE] and "mirror" at the same - time. - - kgdbdbgp= [KGDB,HW] kgdb over EHCI usb debug port. - Format: [,poll interval] - The controller # is the number of the ehci usb debug - port as it is probed via PCI. The poll interval is - optional and is the number seconds in between - each poll cycle to the debug port in case you need - the functionality for interrupting the kernel with - gdb or control-c on the dbgp connection. When - not using this parameter you use sysrq-g to break into - the kernel debugger. - - kgdboc= [KGDB,HW] kgdb over consoles. - Requires a tty driver that supports console polling, - or a supported polling keyboard driver (non-usb). - Serial only format: [,baud] - keyboard only format: kbd - keyboard and serial format: kbd,[,baud] - Optional Kernel mode setting: - kms, kbd format: kms,kbd - kms, kbd and serial format: kms,kbd,[,baud] - - kgdbwait [KGDB] Stop kernel execution and enter the - kernel debugger at the earliest opportunity. - - kmac= [MIPS] korina ethernet MAC address. - Configure the RouterBoard 532 series on-chip - Ethernet adapter MAC address. - - kmemleak= [KNL] Boot-time kmemleak enable/disable - Valid arguments: on, off - Default: on - Built with CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF=y, - the default is off. - - kmemcheck= [X86] Boot-time kmemcheck enable/disable/one-shot mode - Valid arguments: 0, 1, 2 - kmemcheck=0 (disabled) - kmemcheck=1 (enabled) - kmemcheck=2 (one-shot mode) - Default: 2 (one-shot mode) - - kstack=N [X86] Print N words from the kernel stack - in oops dumps. - - kvm.ignore_msrs=[KVM] Ignore guest accesses to unhandled MSRs. - Default is 0 (don't ignore, but inject #GP) - - kvm.mmu_audit= [KVM] This is a R/W parameter which allows audit - KVM MMU at runtime. - Default is 0 (off) - - kvm-amd.nested= [KVM,AMD] Allow nested virtualization in KVM/SVM. - Default is 1 (enabled) - - kvm-amd.npt= [KVM,AMD] Disable nested paging (virtualized MMU) - for all guests. - Default is 1 (enabled) if in 64-bit or 32-bit PAE mode. - - kvm-intel.ept= [KVM,Intel] Disable extended page tables - (virtualized MMU) support on capable Intel chips. - Default is 1 (enabled) - - kvm-intel.emulate_invalid_guest_state= - [KVM,Intel] Enable emulation of invalid guest states - Default is 0 (disabled) - - kvm-intel.flexpriority= - [KVM,Intel] Disable FlexPriority feature (TPR shadow). - Default is 1 (enabled) - - kvm-intel.nested= - [KVM,Intel] Enable VMX nesting (nVMX). - Default is 0 (disabled) - - kvm-intel.unrestricted_guest= - [KVM,Intel] Disable unrestricted guest feature - (virtualized real and unpaged mode) on capable - Intel chips. Default is 1 (enabled) - - kvm-intel.vpid= [KVM,Intel] Disable Virtual Processor Identification - feature (tagged TLBs) on capable Intel chips. - Default is 1 (enabled) - - l2cr= [PPC] - - l3cr= [PPC] - - lapic [X86-32,APIC] Enable the local APIC even if BIOS - disabled it. - - lapic= [x86,APIC] "notscdeadline" Do not use TSC deadline - value for LAPIC timer one-shot implementation. Default - back to the programmable timer unit in the LAPIC. - - lapic_timer_c2_ok [X86,APIC] trust the local apic timer - in C2 power state. - - libata.dma= [LIBATA] DMA control - libata.dma=0 Disable all PATA and SATA DMA - libata.dma=1 PATA and SATA Disk DMA only - libata.dma=2 ATAPI (CDROM) DMA only - libata.dma=4 Compact Flash DMA only - Combinations also work, so libata.dma=3 enables DMA - for disks and CDROMs, but not CFs. - - libata.ignore_hpa= [LIBATA] Ignore HPA limit - libata.ignore_hpa=0 keep BIOS limits (default) - libata.ignore_hpa=1 ignore limits, using full disk - - libata.noacpi [LIBATA] Disables use of ACPI in libata suspend/resume - when set. - Format: - - libata.force= [LIBATA] Force configurations. The format is comma - separated list of "[ID:]VAL" where ID is - PORT[.DEVICE]. PORT and DEVICE are decimal numbers - matching port, link or device. Basically, it matches - the ATA ID string printed on console by libata. If - the whole ID part is omitted, the last PORT and DEVICE - values are used. If ID hasn't been specified yet, the - configuration applies to all ports, links and devices. - - If only DEVICE is omitted, the parameter applies to - the port and all links and devices behind it. DEVICE - number of 0 either selects the first device or the - first fan-out link behind PMP device. It does not - select the host link. DEVICE number of 15 selects the - host link and device attached to it. - - The VAL specifies the configuration to force. As long - as there's no ambiguity shortcut notation is allowed. - For example, both 1.5 and 1.5G would work for 1.5Gbps. - The following configurations can be forced. - - * Cable type: 40c, 80c, short40c, unk, ign or sata. - Any ID with matching PORT is used. - - * SATA link speed limit: 1.5Gbps or 3.0Gbps. - - * Transfer mode: pio[0-7], mwdma[0-4] and udma[0-7]. - udma[/][16,25,33,44,66,100,133] notation is also - allowed. - - * [no]ncq: Turn on or off NCQ. - - * [no]ncqtrim: Turn off queued DSM TRIM. - - * nohrst, nosrst, norst: suppress hard, soft - and both resets. - - * rstonce: only attempt one reset during - hot-unplug link recovery - - * dump_id: dump IDENTIFY data. - - * atapi_dmadir: Enable ATAPI DMADIR bridge support - - * disable: Disable this device. - - If there are multiple matching configurations changing - the same attribute, the last one is used. - - memblock=debug [KNL] Enable memblock debug messages. - - load_ramdisk= [RAM] List of ramdisks to load from floppy - See Documentation/blockdev/ramdisk.txt. - - lockd.nlm_grace_period=P [NFS] Assign grace period. - Format: - - lockd.nlm_tcpport=N [NFS] Assign TCP port. - Format: - - lockd.nlm_timeout=T [NFS] Assign timeout value. - Format: - - lockd.nlm_udpport=M [NFS] Assign UDP port. - Format: - - locktorture.nreaders_stress= [KNL] - Set the number of locking read-acquisition kthreads. - Defaults to being automatically set based on the - number of online CPUs. - - locktorture.nwriters_stress= [KNL] - Set the number of locking write-acquisition kthreads. - - locktorture.onoff_holdoff= [KNL] - Set time (s) after boot for CPU-hotplug testing. - - locktorture.onoff_interval= [KNL] - Set time (s) between CPU-hotplug operations, or - zero to disable CPU-hotplug testing. - - locktorture.shuffle_interval= [KNL] - Set task-shuffle interval (jiffies). Shuffling - tasks allows some CPUs to go into dyntick-idle - mode during the locktorture test. - - locktorture.shutdown_secs= [KNL] - Set time (s) after boot system shutdown. This - is useful for hands-off automated testing. - - locktorture.stat_interval= [KNL] - Time (s) between statistics printk()s. - - locktorture.stutter= [KNL] - Time (s) to stutter testing, for example, - specifying five seconds causes the test to run for - five seconds, wait for five seconds, and so on. - This tests the locking primitive's ability to - transition abruptly to and from idle. - - locktorture.torture_runnable= [BOOT] - Start locktorture running at boot time. - - locktorture.torture_type= [KNL] - Specify the locking implementation to test. - - locktorture.verbose= [KNL] - Enable additional printk() statements. - - logibm.irq= [HW,MOUSE] Logitech Bus Mouse Driver - Format: - - loglevel= All Kernel Messages with a loglevel smaller than the - console loglevel will be printed to the console. It can - also be changed with klogd or other programs. The - loglevels are defined as follows: - - 0 (KERN_EMERG) system is unusable - 1 (KERN_ALERT) action must be taken immediately - 2 (KERN_CRIT) critical conditions - 3 (KERN_ERR) error conditions - 4 (KERN_WARNING) warning conditions - 5 (KERN_NOTICE) normal but significant condition - 6 (KERN_INFO) informational - 7 (KERN_DEBUG) debug-level messages - - log_buf_len=n[KMG] Sets the size of the printk ring buffer, - in bytes. n must be a power of two and greater - than the minimal size. The minimal size is defined - by LOG_BUF_SHIFT kernel config parameter. There is - also CONFIG_LOG_CPU_MAX_BUF_SHIFT config parameter - that allows to increase the default size depending on - the number of CPUs. See init/Kconfig for more details. - - logo.nologo [FB] Disables display of the built-in Linux logo. - This may be used to provide more screen space for - kernel log messages and is useful when debugging - kernel boot problems. - - lp=0 [LP] Specify parallel ports to use, e.g, - lp=port[,port...] lp=none,parport0 (lp0 not configured, lp1 uses - lp=reset first parallel port). 'lp=0' disables the - lp=auto printer driver. 'lp=reset' (which can be - specified in addition to the ports) causes - attached printers to be reset. Using - lp=port1,port2,... specifies the parallel ports - to associate lp devices with, starting with - lp0. A port specification may be 'none' to skip - that lp device, or a parport name such as - 'parport0'. Specifying 'lp=auto' instead of a - port specification list means that device IDs - from each port should be examined, to see if - an IEEE 1284-compliant printer is attached; if - so, the driver will manage that printer. - See also header of drivers/char/lp.c. - - lpj=n [KNL] - Sets loops_per_jiffy to given constant, thus avoiding - time-consuming boot-time autodetection (up to 250 ms per - CPU). 0 enables autodetection (default). To determine - the correct value for your kernel, boot with normal - autodetection and see what value is printed. Note that - on SMP systems the preset will be applied to all CPUs, - which is likely to cause problems if your CPUs need - significantly divergent settings. An incorrect value - will cause delays in the kernel to be wrong, leading to - unpredictable I/O errors and other breakage. Although - unlikely, in the extreme case this might damage your - hardware. - - ltpc= [NET] - Format: ,, - - machvec= [IA-64] Force the use of a particular machine-vector - (machvec) in a generic kernel. - Example: machvec=hpzx1_swiotlb - - machtype= [Loongson] Share the same kernel image file between different - yeeloong laptop. - Example: machtype=lemote-yeeloong-2f-7inch - - max_addr=nn[KMG] [KNL,BOOT,ia64] All physical memory greater - than or equal to this physical address is ignored. - - maxcpus= [SMP] Maximum number of processors that an SMP kernel - will bring up during bootup. maxcpus=n : n >= 0 limits - the kernel to bring up 'n' processors. Surely after - bootup you can bring up the other plugged cpu by executing - "echo 1 > /sys/devices/system/cpu/cpuX/online". So maxcpus - only takes effect during system bootup. - While n=0 is a special case, it is equivalent to "nosmp", - which also disables the IO APIC. - - max_loop= [LOOP] The number of loop block devices that get - (loop.max_loop) unconditionally pre-created at init time. The default - number is configured by BLK_DEV_LOOP_MIN_COUNT. Instead - of statically allocating a predefined number, loop - devices can be requested on-demand with the - /dev/loop-control interface. - - mce [X86-32] Machine Check Exception - - mce=option [X86-64] See Documentation/x86/x86_64/boot-options.txt - - md= [HW] RAID subsystems devices and level - See Documentation/admin-guide/md.rst. - - mdacon= [MDA] - Format: , - Specifies range of consoles to be captured by the MDA. - - mem=nn[KMG] [KNL,BOOT] Force usage of a specific amount of memory - Amount of memory to be used when the kernel is not able - to see the whole system memory or for test. - [X86] Work as limiting max address. Use together - with memmap= to avoid physical address space collisions. - Without memmap= PCI devices could be placed at addresses - belonging to unused RAM. - - mem=nopentium [BUGS=X86-32] Disable usage of 4MB pages for kernel - memory. - - memchunk=nn[KMG] - [KNL,SH] Allow user to override the default size for - per-device physically contiguous DMA buffers. - - memhp_default_state=online/offline - [KNL] Set the initial state for the memory hotplug - onlining policy. If not specified, the default value is - set according to the - CONFIG_MEMORY_HOTPLUG_DEFAULT_ONLINE kernel config - option. - See Documentation/memory-hotplug.txt. - - memmap=exactmap [KNL,X86] Enable setting of an exact - E820 memory map, as specified by the user. - Such memmap=exactmap lines can be constructed based on - BIOS output or other requirements. See the memmap=nn@ss - option description. - - memmap=nn[KMG]@ss[KMG] - [KNL] Force usage of a specific region of memory. - Region of memory to be used is from ss to ss+nn. - - memmap=nn[KMG]#ss[KMG] - [KNL,ACPI] Mark specific memory as ACPI data. - Region of memory to be marked is from ss to ss+nn. - - memmap=nn[KMG]$ss[KMG] - [KNL,ACPI] Mark specific memory as reserved. - Region of memory to be reserved is from ss to ss+nn. - Example: Exclude memory from 0x18690000-0x1869ffff - memmap=64K$0x18690000 - or - memmap=0x10000$0x18690000 - - memmap=nn[KMG]!ss[KMG] - [KNL,X86] Mark specific memory as protected. - Region of memory to be used, from ss to ss+nn. - The memory region may be marked as e820 type 12 (0xc) - and is NVDIMM or ADR memory. - - memory_corruption_check=0/1 [X86] - Some BIOSes seem to corrupt the first 64k of - memory when doing things like suspend/resume. - Setting this option will scan the memory - looking for corruption. Enabling this will - both detect corruption and prevent the kernel - from using the memory being corrupted. - However, its intended as a diagnostic tool; if - repeatable BIOS-originated corruption always - affects the same memory, you can use memmap= - to prevent the kernel from using that memory. - - memory_corruption_check_size=size [X86] - By default it checks for corruption in the low - 64k, making this memory unavailable for normal - use. Use this parameter to scan for - corruption in more or less memory. - - memory_corruption_check_period=seconds [X86] - By default it checks for corruption every 60 - seconds. Use this parameter to check at some - other rate. 0 disables periodic checking. - - memtest= [KNL,X86,ARM] Enable memtest - Format: - default : 0 - Specifies the number of memtest passes to be - performed. Each pass selects another test - pattern from a given set of patterns. Memtest - fills the memory with this pattern, validates - memory contents and reserves bad memory - regions that are detected. - - meye.*= [HW] Set MotionEye Camera parameters - See Documentation/video4linux/meye.txt. - - mfgpt_irq= [IA-32] Specify the IRQ to use for the - Multi-Function General Purpose Timers on AMD Geode - platforms. - - mfgptfix [X86-32] Fix MFGPT timers on AMD Geode platforms when - the BIOS has incorrectly applied a workaround. TinyBIOS - version 0.98 is known to be affected, 0.99 fixes the - problem by letting the user disable the workaround. - - mga= [HW,DRM] - - min_addr=nn[KMG] [KNL,BOOT,ia64] All physical memory below this - physical address is ignored. - - mini2440= [ARM,HW,KNL] - Format:[0..2][b][c][t] - Default: "0tb" - MINI2440 configuration specification: - 0 - The attached screen is the 3.5" TFT - 1 - The attached screen is the 7" TFT - 2 - The VGA Shield is attached (1024x768) - Leaving out the screen size parameter will not load - the TFT driver, and the framebuffer will be left - unconfigured. - b - Enable backlight. The TFT backlight pin will be - linked to the kernel VESA blanking code and a GPIO - LED. This parameter is not necessary when using the - VGA shield. - c - Enable the s3c camera interface. - t - Reserved for enabling touchscreen support. The - touchscreen support is not enabled in the mainstream - kernel as of 2.6.30, a preliminary port can be found - in the "bleeding edge" mini2440 support kernel at - http://repo.or.cz/w/linux-2.6/mini2440.git - - mminit_loglevel= - [KNL] When CONFIG_DEBUG_MEMORY_INIT is set, this - parameter allows control of the logging verbosity for - the additional memory initialisation checks. A value - of 0 disables mminit logging and a level of 4 will - log everything. Information is printed at KERN_DEBUG - so loglevel=8 may also need to be specified. - - module.sig_enforce - [KNL] When CONFIG_MODULE_SIG is set, this means that - modules without (valid) signatures will fail to load. - Note that if CONFIG_MODULE_SIG_FORCE is set, that - is always true, so this option does nothing. - - module_blacklist= [KNL] Do not load a comma-separated list of - modules. Useful for debugging problem modules. - - mousedev.tap_time= - [MOUSE] Maximum time between finger touching and - leaving touchpad surface for touch to be considered - a tap and be reported as a left button click (for - touchpads working in absolute mode only). - Format: - mousedev.xres= [MOUSE] Horizontal screen resolution, used for devices - reporting absolute coordinates, such as tablets - mousedev.yres= [MOUSE] Vertical screen resolution, used for devices - reporting absolute coordinates, such as tablets - - movablecore=nn[KMG] [KNL,X86,IA-64,PPC] This parameter - is similar to kernelcore except it specifies the - amount of memory used for migratable allocations. - If both kernelcore and movablecore is specified, - then kernelcore will be at *least* the specified - value but may be more. If movablecore on its own - is specified, the administrator must be careful - that the amount of memory usable for all allocations - is not too small. - - movable_node [KNL,X86] Boot-time switch to enable the effects - of CONFIG_MOVABLE_NODE=y. See mm/Kconfig for details. - - MTD_Partition= [MTD] - Format: ,,, - - MTD_Region= [MTD] Format: - ,[,,,,] - - mtdparts= [MTD] - See drivers/mtd/cmdlinepart.c. - - multitce=off [PPC] This parameter disables the use of the pSeries - firmware feature for updating multiple TCE entries - at a time. - - onenand.bdry= [HW,MTD] Flex-OneNAND Boundary Configuration - - Format: [die0_boundary][,die0_lock][,die1_boundary][,die1_lock] - - boundary - index of last SLC block on Flex-OneNAND. - The remaining blocks are configured as MLC blocks. - lock - Configure if Flex-OneNAND boundary should be locked. - Once locked, the boundary cannot be changed. - 1 indicates lock status, 0 indicates unlock status. - - mtdset= [ARM] - ARM/S3C2412 JIVE boot control - - See arch/arm/mach-s3c2412/mach-jive.c - - mtouchusb.raw_coordinates= - [HW] Make the MicroTouch USB driver use raw coordinates - ('y', default) or cooked coordinates ('n') - - mtrr_chunk_size=nn[KMG] [X86] - used for mtrr cleanup. It is largest continuous chunk - that could hold holes aka. UC entries. - - mtrr_gran_size=nn[KMG] [X86] - Used for mtrr cleanup. It is granularity of mtrr block. - Default is 1. - Large value could prevent small alignment from - using up MTRRs. - - mtrr_spare_reg_nr=n [X86] - Format: - Range: 0,7 : spare reg number - Default : 1 - Used for mtrr cleanup. It is spare mtrr entries number. - Set to 2 or more if your graphical card needs more. - - n2= [NET] SDL Inc. RISCom/N2 synchronous serial card - - netdev= [NET] Network devices parameters - Format: ,,,, - Note that mem_start is often overloaded to mean - something different and driver-specific. - This usage is only documented in each driver source - file if at all. - - nf_conntrack.acct= - [NETFILTER] Enable connection tracking flow accounting - 0 to disable accounting - 1 to enable accounting - Default value is 0. - - nfsaddrs= [NFS] Deprecated. Use ip= instead. - See Documentation/filesystems/nfs/nfsroot.txt. - - nfsroot= [NFS] nfs root filesystem for disk-less boxes. - See Documentation/filesystems/nfs/nfsroot.txt. - - nfsrootdebug [NFS] enable nfsroot debugging messages. - See Documentation/filesystems/nfs/nfsroot.txt. - - nfs.callback_nr_threads= - [NFSv4] set the total number of threads that the - NFS client will assign to service NFSv4 callback - requests. - - nfs.callback_tcpport= - [NFS] set the TCP port on which the NFSv4 callback - channel should listen. - - nfs.cache_getent= - [NFS] sets the pathname to the program which is used - to update the NFS client cache entries. - - nfs.cache_getent_timeout= - [NFS] sets the timeout after which an attempt to - update a cache entry is deemed to have failed. - - nfs.idmap_cache_timeout= - [NFS] set the maximum lifetime for idmapper cache - entries. - - nfs.enable_ino64= - [NFS] enable 64-bit inode numbers. - If zero, the NFS client will fake up a 32-bit inode - number for the readdir() and stat() syscalls instead - of returning the full 64-bit number. - The default is to return 64-bit inode numbers. - - nfs.max_session_cb_slots= - [NFSv4.1] Sets the maximum number of session - slots the client will assign to the callback - channel. This determines the maximum number of - callbacks the client will process in parallel for - a particular server. - - nfs.max_session_slots= - [NFSv4.1] Sets the maximum number of session slots - the client will attempt to negotiate with the server. - This limits the number of simultaneous RPC requests - that the client can send to the NFSv4.1 server. - Note that there is little point in setting this - value higher than the max_tcp_slot_table_limit. - - nfs.nfs4_disable_idmapping= - [NFSv4] When set to the default of '1', this option - ensures that both the RPC level authentication - scheme and the NFS level operations agree to use - numeric uids/gids if the mount is using the - 'sec=sys' security flavour. In effect it is - disabling idmapping, which can make migration from - legacy NFSv2/v3 systems to NFSv4 easier. - Servers that do not support this mode of operation - will be autodetected by the client, and it will fall - back to using the idmapper. - To turn off this behaviour, set the value to '0'. - nfs.nfs4_unique_id= - [NFS4] Specify an additional fixed unique ident- - ification string that NFSv4 clients can insert into - their nfs_client_id4 string. This is typically a - UUID that is generated at system install time. - - nfs.send_implementation_id = - [NFSv4.1] Send client implementation identification - information in exchange_id requests. - If zero, no implementation identification information - will be sent. - The default is to send the implementation identification - information. - - nfs.recover_lost_locks = - [NFSv4] Attempt to recover locks that were lost due - to a lease timeout on the server. Please note that - doing this risks data corruption, since there are - no guarantees that the file will remain unchanged - after the locks are lost. - If you want to enable the kernel legacy behaviour of - attempting to recover these locks, then set this - parameter to '1'. - The default parameter value of '0' causes the kernel - not to attempt recovery of lost locks. - - nfs4.layoutstats_timer = - [NFSv4.2] Change the rate at which the kernel sends - layoutstats to the pNFS metadata server. - - Setting this to value to 0 causes the kernel to use - whatever value is the default set by the layout - driver. A non-zero value sets the minimum interval - in seconds between layoutstats transmissions. - - nfsd.nfs4_disable_idmapping= - [NFSv4] When set to the default of '1', the NFSv4 - server will return only numeric uids and gids to - clients using auth_sys, and will accept numeric uids - and gids from such clients. This is intended to ease - migration from NFSv2/v3. - - objlayoutdriver.osd_login_prog= - [NFS] [OBJLAYOUT] sets the pathname to the program which - is used to automatically discover and login into new - osd-targets. Please see: - Documentation/filesystems/pnfs.txt for more explanations - - nmi_debug= [KNL,AVR32,SH] Specify one or more actions to take - when a NMI is triggered. - Format: [state][,regs][,debounce][,die] - - nmi_watchdog= [KNL,BUGS=X86] Debugging features for SMP kernels - Format: [panic,][nopanic,][num] - Valid num: 0 or 1 - 0 - turn hardlockup detector in nmi_watchdog off - 1 - turn hardlockup detector in nmi_watchdog on - When panic is specified, panic when an NMI watchdog - timeout occurs (or 'nopanic' to override the opposite - default). To disable both hard and soft lockup detectors, - please see 'nowatchdog'. - This is useful when you use a panic=... timeout and - need the box quickly up again. - - netpoll.carrier_timeout= - [NET] Specifies amount of time (in seconds) that - netpoll should wait for a carrier. By default netpoll - waits 4 seconds. - - no387 [BUGS=X86-32] Tells the kernel to use the 387 maths - emulation library even if a 387 maths coprocessor - is present. - - no_console_suspend - [HW] Never suspend the console - Disable suspending of consoles during suspend and - hibernate operations. Once disabled, debugging - messages can reach various consoles while the rest - of the system is being put to sleep (ie, while - debugging driver suspend/resume hooks). This may - not work reliably with all consoles, but is known - to work with serial and VGA consoles. - To facilitate more flexible debugging, we also add - console_suspend, a printk module parameter to control - it. Users could use console_suspend (usually - /sys/module/printk/parameters/console_suspend) to - turn on/off it dynamically. - - noaliencache [MM, NUMA, SLAB] Disables the allocation of alien - caches in the slab allocator. Saves per-node memory, - but will impact performance. - - noalign [KNL,ARM] - - noapic [SMP,APIC] Tells the kernel to not make use of any - IOAPICs that may be present in the system. - - noautogroup Disable scheduler automatic task group creation. - - nobats [PPC] Do not use BATs for mapping kernel lowmem - on "Classic" PPC cores. - - nocache [ARM] - - noclflush [BUGS=X86] Don't use the CLFLUSH instruction - - nodelayacct [KNL] Disable per-task delay accounting - - nodsp [SH] Disable hardware DSP at boot time. - - noefi Disable EFI runtime services support. - - noexec [IA-64] - - noexec [X86] - On X86-32 available only on PAE configured kernels. - noexec=on: enable non-executable mappings (default) - noexec=off: disable non-executable mappings - - nosmap [X86] - Disable SMAP (Supervisor Mode Access Prevention) - even if it is supported by processor. - - nosmep [X86] - Disable SMEP (Supervisor Mode Execution Prevention) - even if it is supported by processor. - - noexec32 [X86-64] - This affects only 32-bit executables. - noexec32=on: enable non-executable mappings (default) - read doesn't imply executable mappings - noexec32=off: disable non-executable mappings - read implies executable mappings - - nofpu [MIPS,SH] Disable hardware FPU at boot time. - - nofxsr [BUGS=X86-32] Disables x86 floating point extended - register save and restore. The kernel will only save - legacy floating-point registers on task switch. - - nohugeiomap [KNL,x86] Disable kernel huge I/O mappings. - - nosmt [KNL,S390] Disable symmetric multithreading (SMT). - Equivalent to smt=1. - - noxsave [BUGS=X86] Disables x86 extended register state save - and restore using xsave. The kernel will fallback to - enabling legacy floating-point and sse state. - - noxsaveopt [X86] Disables xsaveopt used in saving x86 extended - register states. The kernel will fall back to use - xsave to save the states. By using this parameter, - performance of saving the states is degraded because - xsave doesn't support modified optimization while - xsaveopt supports it on xsaveopt enabled systems. - - noxsaves [X86] Disables xsaves and xrstors used in saving and - restoring x86 extended register state in compacted - form of xsave area. The kernel will fall back to use - xsaveopt and xrstor to save and restore the states - in standard form of xsave area. By using this - parameter, xsave area per process might occupy more - memory on xsaves enabled systems. - - nohlt [BUGS=ARM,SH] Tells the kernel that the sleep(SH) or - wfi(ARM) instruction doesn't work correctly and not to - use it. This is also useful when using JTAG debugger. - - no_file_caps Tells the kernel not to honor file capabilities. The - only way then for a file to be executed with privilege - is to be setuid root or executed by root. - - nohalt [IA-64] Tells the kernel not to use the power saving - function PAL_HALT_LIGHT when idle. This increases - power-consumption. On the positive side, it reduces - interrupt wake-up latency, which may improve performance - in certain environments such as networked servers or - real-time systems. - - nohibernate [HIBERNATION] Disable hibernation and resume. - - nohz= [KNL] Boottime enable/disable dynamic ticks - Valid arguments: on, off - Default: on - - nohz_full= [KNL,BOOT] - The argument is a cpu list, as described above. - In kernels built with CONFIG_NO_HZ_FULL=y, set - the specified list of CPUs whose tick will be stopped - whenever possible. The boot CPU will be forced outside - the range to maintain the timekeeping. - The CPUs in this range must also be included in the - rcu_nocbs= set. - - noiotrap [SH] Disables trapped I/O port accesses. - - noirqdebug [X86-32] Disables the code which attempts to detect and - disable unhandled interrupt sources. - - no_timer_check [X86,APIC] Disables the code which tests for - broken timer IRQ sources. - - noisapnp [ISAPNP] Disables ISA PnP code. - - noinitrd [RAM] Tells the kernel not to load any configured - initial RAM disk. - - nointremap [X86-64, Intel-IOMMU] Do not enable interrupt - remapping. - [Deprecated - use intremap=off] - - nointroute [IA-64] - - noinvpcid [X86] Disable the INVPCID cpu feature. - - nojitter [IA-64] Disables jitter checking for ITC timers. - - no-kvmclock [X86,KVM] Disable paravirtualized KVM clock driver - - no-kvmapf [X86,KVM] Disable paravirtualized asynchronous page - fault handling. - - no-steal-acc [X86,KVM] Disable paravirtualized steal time accounting. - steal time is computed, but won't influence scheduler - behaviour - - nolapic [X86-32,APIC] Do not enable or use the local APIC. - - nolapic_timer [X86-32,APIC] Do not use the local APIC timer. - - noltlbs [PPC] Do not use large page/tlb entries for kernel - lowmem mapping on PPC40x and PPC8xx - - nomca [IA-64] Disable machine check abort handling - - nomce [X86-32] Disable Machine Check Exception - - nomfgpt [X86-32] Disable Multi-Function General Purpose - Timer usage (for AMD Geode machines). - - nonmi_ipi [X86] Disable using NMI IPIs during panic/reboot to - shutdown the other cpus. Instead use the REBOOT_VECTOR - irq. - - nomodule Disable module load - - nopat [X86] Disable PAT (page attribute table extension of - pagetables) support. - - norandmaps Don't use address space randomization. Equivalent to - echo 0 > /proc/sys/kernel/randomize_va_space - - noreplace-paravirt [X86,IA-64,PV_OPS] Don't patch paravirt_ops - - noreplace-smp [X86-32,SMP] Don't replace SMP instructions - with UP alternatives - - nordrand [X86] Disable kernel use of the RDRAND and - RDSEED instructions even if they are supported - by the processor. RDRAND and RDSEED are still - available to user space applications. - - noresume [SWSUSP] Disables resume and restores original swap - space. - - no-scroll [VGA] Disables scrollback. - This is required for the Braillex ib80-piezo Braille - reader made by F.H. Papenmeier (Germany). - - nosbagart [IA-64] - - nosep [BUGS=X86-32] Disables x86 SYSENTER/SYSEXIT support. - - nosmp [SMP] Tells an SMP kernel to act as a UP kernel, - and disable the IO APIC. legacy for "maxcpus=0". - - nosoftlockup [KNL] Disable the soft-lockup detector. - - nosync [HW,M68K] Disables sync negotiation for all devices. - - notsc [BUGS=X86-32] Disable Time Stamp Counter - - nowatchdog [KNL] Disable both lockup detectors, i.e. - soft-lockup and NMI watchdog (hard-lockup). - - nowb [ARM] - - nox2apic [X86-64,APIC] Do not enable x2APIC mode. - - cpu0_hotplug [X86] Turn on CPU0 hotplug feature when - CONFIG_BOOTPARAM_HOTPLUG_CPU0 is off. - Some features depend on CPU0. Known dependencies are: - 1. Resume from suspend/hibernate depends on CPU0. - Suspend/hibernate will fail if CPU0 is offline and you - need to online CPU0 before suspend/hibernate. - 2. PIC interrupts also depend on CPU0. CPU0 can't be - removed if a PIC interrupt is detected. - It's said poweroff/reboot may depend on CPU0 on some - machines although I haven't seen such issues so far - after CPU0 is offline on a few tested machines. - If the dependencies are under your control, you can - turn on cpu0_hotplug. - - nptcg= [IA-64] Override max number of concurrent global TLB - purges which is reported from either PAL_VM_SUMMARY or - SAL PALO. - - nr_cpus= [SMP] Maximum number of processors that an SMP kernel - could support. nr_cpus=n : n >= 1 limits the kernel to - support 'n' processors. It could be larger than the - number of already plugged CPU during bootup, later in - runtime you can physically add extra cpu until it reaches - n. So during boot up some boot time memory for per-cpu - variables need be pre-allocated for later physical cpu - hot plugging. - - nr_uarts= [SERIAL] maximum number of UARTs to be registered. - - numa_balancing= [KNL,X86] Enable or disable automatic NUMA balancing. - Allowed values are enable and disable - - numa_zonelist_order= [KNL, BOOT] Select zonelist order for NUMA. - one of ['zone', 'node', 'default'] can be specified - This can be set from sysctl after boot. - See Documentation/sysctl/vm.txt for details. - - ohci1394_dma=early [HW] enable debugging via the ohci1394 driver. - See Documentation/debugging-via-ohci1394.txt for more - info. - - olpc_ec_timeout= [OLPC] ms delay when issuing EC commands - Rather than timing out after 20 ms if an EC - command is not properly ACKed, override the length - of the timeout. We have interrupts disabled while - waiting for the ACK, so if this is set too high - interrupts *may* be lost! - - omap_mux= [OMAP] Override bootloader pin multiplexing. - Format: ... - For example, to override I2C bus2: - omap_mux=i2c2_scl.i2c2_scl=0x100,i2c2_sda.i2c2_sda=0x100 - - oprofile.timer= [HW] - Use timer interrupt instead of performance counters - - oprofile.cpu_type= Force an oprofile cpu type - This might be useful if you have an older oprofile - userland or if you want common events. - Format: { arch_perfmon } - arch_perfmon: [X86] Force use of architectural - perfmon on Intel CPUs instead of the - CPU specific event set. - timer: [X86] Force use of architectural NMI - timer mode (see also oprofile.timer - for generic hr timer mode) - - oops=panic Always panic on oopses. Default is to just kill the - process, but there is a small probability of - deadlocking the machine. - This will also cause panics on machine check exceptions. - Useful together with panic=30 to trigger a reboot. - - OSS [HW,OSS] - See Documentation/sound/oss/oss-parameters.txt - - page_owner= [KNL] Boot-time page_owner enabling option. - Storage of the information about who allocated - each page is disabled in default. With this switch, - we can turn it on. - on: enable the feature - - page_poison= [KNL] Boot-time parameter changing the state of - poisoning on the buddy allocator. - off: turn off poisoning - on: turn on poisoning - - panic= [KNL] Kernel behaviour on panic: delay - timeout > 0: seconds before rebooting - timeout = 0: wait forever - timeout < 0: reboot immediately - Format: - - panic_on_warn panic() instead of WARN(). Useful to cause kdump - on a WARN(). - - crash_kexec_post_notifiers - Run kdump after running panic-notifiers and dumping - kmsg. This only for the users who doubt kdump always - succeeds in any situation. - Note that this also increases risks of kdump failure, - because some panic notifiers can make the crashed - kernel more unstable. - - parkbd.port= [HW] Parallel port number the keyboard adapter is - connected to, default is 0. - Format: - parkbd.mode= [HW] Parallel port keyboard adapter mode of operation, - 0 for XT, 1 for AT (default is AT). - Format: - - parport= [HW,PPT] Specify parallel ports. 0 disables. - Format: { 0 | auto | 0xBBB[,IRQ[,DMA]] } - Use 'auto' to force the driver to use any - IRQ/DMA settings detected (the default is to - ignore detected IRQ/DMA settings because of - possible conflicts). You can specify the base - address, IRQ, and DMA settings; IRQ and DMA - should be numbers, or 'auto' (for using detected - settings on that particular port), or 'nofifo' - (to avoid using a FIFO even if it is detected). - Parallel ports are assigned in the order they - are specified on the command line, starting - with parport0. - - parport_init_mode= [HW,PPT] - Configure VIA parallel port to operate in - a specific mode. This is necessary on Pegasos - computer where firmware has no options for setting - up parallel port mode and sets it to spp. - Currently this function knows 686a and 8231 chips. - Format: [spp|ps2|epp|ecp|ecpepp] - - pause_on_oops= - Halt all CPUs after the first oops has been printed for - the specified number of seconds. This is to be used if - your oopses keep scrolling off the screen. - - pcbit= [HW,ISDN] - - pcd. [PARIDE] - See header of drivers/block/paride/pcd.c. - See also Documentation/blockdev/paride.txt. - - pci=option[,option...] [PCI] various PCI subsystem options: - earlydump [X86] dump PCI config space before the kernel - changes anything - off [X86] don't probe for the PCI bus - bios [X86-32] force use of PCI BIOS, don't access - the hardware directly. Use this if your machine - has a non-standard PCI host bridge. - nobios [X86-32] disallow use of PCI BIOS, only direct - hardware access methods are allowed. Use this - if you experience crashes upon bootup and you - suspect they are caused by the BIOS. - conf1 [X86] Force use of PCI Configuration Access - Mechanism 1 (config address in IO port 0xCF8, - data in IO port 0xCFC, both 32-bit). - conf2 [X86] Force use of PCI Configuration Access - Mechanism 2 (IO port 0xCF8 is an 8-bit port for - the function, IO port 0xCFA, also 8-bit, sets - bus number. The config space is then accessed - through ports 0xC000-0xCFFF). - See http://wiki.osdev.org/PCI for more info - on the configuration access mechanisms. - noaer [PCIE] If the PCIEAER kernel config parameter is - enabled, this kernel boot option can be used to - disable the use of PCIE advanced error reporting. - nodomains [PCI] Disable support for multiple PCI - root domains (aka PCI segments, in ACPI-speak). - nommconf [X86] Disable use of MMCONFIG for PCI - Configuration - check_enable_amd_mmconf [X86] check for and enable - properly configured MMIO access to PCI - config space on AMD family 10h CPU - nomsi [MSI] If the PCI_MSI kernel config parameter is - enabled, this kernel boot option can be used to - disable the use of MSI interrupts system-wide. - noioapicquirk [APIC] Disable all boot interrupt quirks. - Safety option to keep boot IRQs enabled. This - should never be necessary. - ioapicreroute [APIC] Enable rerouting of boot IRQs to the - primary IO-APIC for bridges that cannot disable - boot IRQs. This fixes a source of spurious IRQs - when the system masks IRQs. - noioapicreroute [APIC] Disable workaround that uses the - boot IRQ equivalent of an IRQ that connects to - a chipset where boot IRQs cannot be disabled. - The opposite of ioapicreroute. - biosirq [X86-32] Use PCI BIOS calls to get the interrupt - routing table. These calls are known to be buggy - on several machines and they hang the machine - when used, but on other computers it's the only - way to get the interrupt routing table. Try - this option if the kernel is unable to allocate - IRQs or discover secondary PCI buses on your - motherboard. - rom [X86] Assign address space to expansion ROMs. - Use with caution as certain devices share - address decoders between ROMs and other - resources. - norom [X86] Do not assign address space to - expansion ROMs that do not already have - BIOS assigned address ranges. - nobar [X86] Do not assign address space to the - BARs that weren't assigned by the BIOS. - irqmask=0xMMMM [X86] Set a bit mask of IRQs allowed to be - assigned automatically to PCI devices. You can - make the kernel exclude IRQs of your ISA cards - this way. - pirqaddr=0xAAAAA [X86] Specify the physical address - of the PIRQ table (normally generated - by the BIOS) if it is outside the - F0000h-100000h range. - lastbus=N [X86] Scan all buses thru bus #N. Can be - useful if the kernel is unable to find your - secondary buses and you want to tell it - explicitly which ones they are. - assign-busses [X86] Always assign all PCI bus - numbers ourselves, overriding - whatever the firmware may have done. - usepirqmask [X86] Honor the possible IRQ mask stored - in the BIOS $PIR table. This is needed on - some systems with broken BIOSes, notably - some HP Pavilion N5400 and Omnibook XE3 - notebooks. This will have no effect if ACPI - IRQ routing is enabled. - noacpi [X86] Do not use ACPI for IRQ routing - or for PCI scanning. - use_crs [X86] Use PCI host bridge window information - from ACPI. On BIOSes from 2008 or later, this - is enabled by default. If you need to use this, - please report a bug. - nocrs [X86] Ignore PCI host bridge windows from ACPI. - If you need to use this, please report a bug. - routeirq Do IRQ routing for all PCI devices. - This is normally done in pci_enable_device(), - so this option is a temporary workaround - for broken drivers that don't call it. - skip_isa_align [X86] do not align io start addr, so can - handle more pci cards - noearly [X86] Don't do any early type 1 scanning. - This might help on some broken boards which - machine check when some devices' config space - is read. But various workarounds are disabled - and some IOMMU drivers will not work. - bfsort Sort PCI devices into breadth-first order. - This sorting is done to get a device - order compatible with older (<= 2.4) kernels. - nobfsort Don't sort PCI devices into breadth-first order. - pcie_bus_tune_off Disable PCIe MPS (Max Payload Size) - tuning and use the BIOS-configured MPS defaults. - pcie_bus_safe Set every device's MPS to the largest value - supported by all devices below the root complex. - pcie_bus_perf Set device MPS to the largest allowable MPS - based on its parent bus. Also set MRRS (Max - Read Request Size) to the largest supported - value (no larger than the MPS that the device - or bus can support) for best performance. - pcie_bus_peer2peer Set every device's MPS to 128B, which - every device is guaranteed to support. This - configuration allows peer-to-peer DMA between - any pair of devices, possibly at the cost of - reduced performance. This also guarantees - that hot-added devices will work. - cbiosize=nn[KMG] The fixed amount of bus space which is - reserved for the CardBus bridge's IO window. - The default value is 256 bytes. - cbmemsize=nn[KMG] The fixed amount of bus space which is - reserved for the CardBus bridge's memory - window. The default value is 64 megabytes. - resource_alignment= - Format: - [@][:]:.[; ...] - [@]pci::\ - [::][; ...] - Specifies alignment and device to reassign - aligned memory resources. - If is not specified, - PAGE_SIZE is used as alignment. - PCI-PCI bridge can be specified, if resource - windows need to be expanded. - To specify the alignment for several - instances of a device, the PCI vendor, - device, subvendor, and subdevice may be - specified, e.g., 4096@pci:8086:9c22:103c:198f - ecrc= Enable/disable PCIe ECRC (transaction layer - end-to-end CRC checking). - bios: Use BIOS/firmware settings. This is the - the default. - off: Turn ECRC off - on: Turn ECRC on. - hpiosize=nn[KMG] The fixed amount of bus space which is - reserved for hotplug bridge's IO window. - Default size is 256 bytes. - hpmemsize=nn[KMG] The fixed amount of bus space which is - reserved for hotplug bridge's memory window. - Default size is 2 megabytes. - hpbussize=nn The minimum amount of additional bus numbers - reserved for buses below a hotplug bridge. - Default is 1. - realloc= Enable/disable reallocating PCI bridge resources - if allocations done by BIOS are too small to - accommodate resources required by all child - devices. - off: Turn realloc off - on: Turn realloc on - realloc same as realloc=on - noari do not use PCIe ARI. - pcie_scan_all Scan all possible PCIe devices. Otherwise we - only look for one device below a PCIe downstream - port. - - pcie_aspm= [PCIE] Forcibly enable or disable PCIe Active State Power - Management. - off Disable ASPM. - force Enable ASPM even on devices that claim not to support it. - WARNING: Forcing ASPM on may cause system lockups. - - pcie_hp= [PCIE] PCI Express Hotplug driver options: - nomsi Do not use MSI for PCI Express Native Hotplug (this - makes all PCIe ports use INTx for hotplug services). - - pcie_ports= [PCIE] PCIe ports handling: - auto Ask the BIOS whether or not to use native PCIe services - associated with PCIe ports (PME, hot-plug, AER). Use - them only if that is allowed by the BIOS. - native Use native PCIe services associated with PCIe ports - unconditionally. - compat Treat PCIe ports as PCI-to-PCI bridges, disable the PCIe - ports driver. - - pcie_port_pm= [PCIE] PCIe port power management handling: - off Disable power management of all PCIe ports - force Forcibly enable power management of all PCIe ports - - pcie_pme= [PCIE,PM] Native PCIe PME signaling options: - nomsi Do not use MSI for native PCIe PME signaling (this makes - all PCIe root ports use INTx for all services). - - pcmv= [HW,PCMCIA] BadgePAD 4 - - pd_ignore_unused - [PM] - Keep all power-domains already enabled by bootloader on, - even if no driver has claimed them. This is useful - for debug and development, but should not be - needed on a platform with proper driver support. - - pd. [PARIDE] - See Documentation/blockdev/paride.txt. - - pdcchassis= [PARISC,HW] Disable/Enable PDC Chassis Status codes at - boot time. - Format: { 0 | 1 } - See arch/parisc/kernel/pdc_chassis.c - - percpu_alloc= Select which percpu first chunk allocator to use. - Currently supported values are "embed" and "page". - Archs may support subset or none of the selections. - See comments in mm/percpu.c for details on each - allocator. This parameter is primarily for debugging - and performance comparison. - - pf. [PARIDE] - See Documentation/blockdev/paride.txt. - - pg. [PARIDE] - See Documentation/blockdev/paride.txt. - - pirq= [SMP,APIC] Manual mp-table setup - See Documentation/x86/i386/IO-APIC.txt. - - plip= [PPT,NET] Parallel port network link - Format: { parport | timid | 0 } - See also Documentation/parport.txt. - - pmtmr= [X86] Manual setup of pmtmr I/O Port. - Override pmtimer IOPort with a hex value. - e.g. pmtmr=0x508 - - pnp.debug=1 [PNP] - Enable PNP debug messages (depends on the - CONFIG_PNP_DEBUG_MESSAGES option). Change at run-time - via /sys/module/pnp/parameters/debug. We always show - current resource usage; turning this on also shows - possible settings and some assignment information. - - pnpacpi= [ACPI] - { off } - - pnpbios= [ISAPNP] - { on | off | curr | res | no-curr | no-res } - - pnp_reserve_irq= - [ISAPNP] Exclude IRQs for the autoconfiguration - - pnp_reserve_dma= - [ISAPNP] Exclude DMAs for the autoconfiguration - - pnp_reserve_io= [ISAPNP] Exclude I/O ports for the autoconfiguration - Ranges are in pairs (I/O port base and size). - - pnp_reserve_mem= - [ISAPNP] Exclude memory regions for the - autoconfiguration. - Ranges are in pairs (memory base and size). - - ports= [IP_VS_FTP] IPVS ftp helper module - Default is 21. - Up to 8 (IP_VS_APP_MAX_PORTS) ports - may be specified. - Format: ,.... - - ppc_strict_facility_enable - [PPC] This option catches any kernel floating point, - Altivec, VSX and SPE outside of regions specifically - allowed (eg kernel_enable_fpu()/kernel_disable_fpu()). - There is some performance impact when enabling this. - - print-fatal-signals= - [KNL] debug: print fatal signals - - If enabled, warn about various signal handling - related application anomalies: too many signals, - too many POSIX.1 timers, fatal signals causing a - coredump - etc. - - If you hit the warning due to signal overflow, - you might want to try "ulimit -i unlimited". - - default: off. - - printk.always_kmsg_dump= - Trigger kmsg_dump for cases other than kernel oops or - panics - Format: (1/Y/y=enable, 0/N/n=disable) - default: disabled - - printk.devkmsg={on,off,ratelimit} - Control writing to /dev/kmsg. - on - unlimited logging to /dev/kmsg from userspace - off - logging to /dev/kmsg disabled - ratelimit - ratelimit the logging - Default: ratelimit - - printk.time= Show timing data prefixed to each printk message line - Format: (1/Y/y=enable, 0/N/n=disable) - - processor.max_cstate= [HW,ACPI] - Limit processor to maximum C-state - max_cstate=9 overrides any DMI blacklist limit. - - processor.nocst [HW,ACPI] - Ignore the _CST method to determine C-states, - instead using the legacy FADT method - - profile= [KNL] Enable kernel profiling via /proc/profile - Format: [schedule,] - Param: "schedule" - profile schedule points. - Param: - step/bucket size as a power of 2 for - statistical time based profiling. - Param: "sleep" - profile D-state sleeping (millisecs). - Requires CONFIG_SCHEDSTATS - Param: "kvm" - profile VM exits. - - prompt_ramdisk= [RAM] List of RAM disks to prompt for floppy disk - before loading. - See Documentation/blockdev/ramdisk.txt. - - psmouse.proto= [HW,MOUSE] Highest PS2 mouse protocol extension to - probe for; one of (bare|imps|exps|lifebook|any). - psmouse.rate= [HW,MOUSE] Set desired mouse report rate, in reports - per second. - psmouse.resetafter= [HW,MOUSE] - Try to reset the device after so many bad packets - (0 = never). - psmouse.resolution= - [HW,MOUSE] Set desired mouse resolution, in dpi. - psmouse.smartscroll= - [HW,MOUSE] Controls Logitech smartscroll autorepeat. - 0 = disabled, 1 = enabled (default). - - pstore.backend= Specify the name of the pstore backend to use - - pt. [PARIDE] - See Documentation/blockdev/paride.txt. - - pty.legacy_count= - [KNL] Number of legacy pty's. Overwrites compiled-in - default number. - - quiet [KNL] Disable most log messages - - r128= [HW,DRM] - - raid= [HW,RAID] - See Documentation/admin-guide/md.rst. - - ramdisk_size= [RAM] Sizes of RAM disks in kilobytes - See Documentation/blockdev/ramdisk.txt. - - rcu_nocbs= [KNL] - The argument is a cpu list, as described above. - - In kernels built with CONFIG_RCU_NOCB_CPU=y, set - the specified list of CPUs to be no-callback CPUs. - Invocation of these CPUs' RCU callbacks will - be offloaded to "rcuox/N" kthreads created for - that purpose, where "x" is "b" for RCU-bh, "p" - for RCU-preempt, and "s" for RCU-sched, and "N" - is the CPU number. This reduces OS jitter on the - offloaded CPUs, which can be useful for HPC and - real-time workloads. It can also improve energy - efficiency for asymmetric multiprocessors. - - rcu_nocb_poll [KNL] - Rather than requiring that offloaded CPUs - (specified by rcu_nocbs= above) explicitly - awaken the corresponding "rcuoN" kthreads, - make these kthreads poll for callbacks. - This improves the real-time response for the - offloaded CPUs by relieving them of the need to - wake up the corresponding kthread, but degrades - energy efficiency by requiring that the kthreads - periodically wake up to do the polling. - - rcutree.blimit= [KNL] - Set maximum number of finished RCU callbacks to - process in one batch. - - rcutree.dump_tree= [KNL] - Dump the structure of the rcu_node combining tree - out at early boot. This is used for diagnostic - purposes, to verify correct tree setup. - - rcutree.gp_cleanup_delay= [KNL] - Set the number of jiffies to delay each step of - RCU grace-period cleanup. This only has effect - when CONFIG_RCU_TORTURE_TEST_SLOW_CLEANUP is set. - - rcutree.gp_init_delay= [KNL] - Set the number of jiffies to delay each step of - RCU grace-period initialization. This only has - effect when CONFIG_RCU_TORTURE_TEST_SLOW_INIT - is set. - - rcutree.gp_preinit_delay= [KNL] - Set the number of jiffies to delay each step of - RCU grace-period pre-initialization, that is, - the propagation of recent CPU-hotplug changes up - the rcu_node combining tree. This only has effect - when CONFIG_RCU_TORTURE_TEST_SLOW_PREINIT is set. - - rcutree.rcu_fanout_exact= [KNL] - Disable autobalancing of the rcu_node combining - tree. This is used by rcutorture, and might - possibly be useful for architectures having high - cache-to-cache transfer latencies. - - rcutree.rcu_fanout_leaf= [KNL] - Change the number of CPUs assigned to each - leaf rcu_node structure. Useful for very - large systems, which will choose the value 64, - and for NUMA systems with large remote-access - latencies, which will choose a value aligned - with the appropriate hardware boundaries. - - rcutree.jiffies_till_sched_qs= [KNL] - Set required age in jiffies for a - given grace period before RCU starts - soliciting quiescent-state help from - rcu_note_context_switch(). - - rcutree.jiffies_till_first_fqs= [KNL] - Set delay from grace-period initialization to - first attempt to force quiescent states. - Units are jiffies, minimum value is zero, - and maximum value is HZ. - - rcutree.jiffies_till_next_fqs= [KNL] - Set delay between subsequent attempts to force - quiescent states. Units are jiffies, minimum - value is one, and maximum value is HZ. - - rcutree.kthread_prio= [KNL,BOOT] - Set the SCHED_FIFO priority of the RCU per-CPU - kthreads (rcuc/N). This value is also used for - the priority of the RCU boost threads (rcub/N) - and for the RCU grace-period kthreads (rcu_bh, - rcu_preempt, and rcu_sched). If RCU_BOOST is - set, valid values are 1-99 and the default is 1 - (the least-favored priority). Otherwise, when - RCU_BOOST is not set, valid values are 0-99 and - the default is zero (non-realtime operation). - - rcutree.rcu_nocb_leader_stride= [KNL] - Set the number of NOCB kthread groups, which - defaults to the square root of the number of - CPUs. Larger numbers reduces the wakeup overhead - on the per-CPU grace-period kthreads, but increases - that same overhead on each group's leader. - - rcutree.qhimark= [KNL] - Set threshold of queued RCU callbacks beyond which - batch limiting is disabled. - - rcutree.qlowmark= [KNL] - Set threshold of queued RCU callbacks below which - batch limiting is re-enabled. - - rcutree.rcu_idle_gp_delay= [KNL] - Set wakeup interval for idle CPUs that have - RCU callbacks (RCU_FAST_NO_HZ=y). - - rcutree.rcu_idle_lazy_gp_delay= [KNL] - Set wakeup interval for idle CPUs that have - only "lazy" RCU callbacks (RCU_FAST_NO_HZ=y). - Lazy RCU callbacks are those which RCU can - prove do nothing more than free memory. - - rcuperf.gp_exp= [KNL] - Measure performance of expedited synchronous - grace-period primitives. - - rcuperf.holdoff= [KNL] - Set test-start holdoff period. The purpose of - this parameter is to delay the start of the - test until boot completes in order to avoid - interference. - - rcuperf.nreaders= [KNL] - Set number of RCU readers. The value -1 selects - N, where N is the number of CPUs. A value - "n" less than -1 selects N-n+1, where N is again - the number of CPUs. For example, -2 selects N - (the number of CPUs), -3 selects N+1, and so on. - A value of "n" less than or equal to -N selects - a single reader. - - rcuperf.nwriters= [KNL] - Set number of RCU writers. The values operate - the same as for rcuperf.nreaders. - N, where N is the number of CPUs - - rcuperf.perf_runnable= [BOOT] - Start rcuperf running at boot time. - - rcuperf.shutdown= [KNL] - Shut the system down after performance tests - complete. This is useful for hands-off automated - testing. - - rcuperf.perf_type= [KNL] - Specify the RCU implementation to test. - - rcuperf.verbose= [KNL] - Enable additional printk() statements. - - rcutorture.cbflood_inter_holdoff= [KNL] - Set holdoff time (jiffies) between successive - callback-flood tests. - - rcutorture.cbflood_intra_holdoff= [KNL] - Set holdoff time (jiffies) between successive - bursts of callbacks within a given callback-flood - test. - - rcutorture.cbflood_n_burst= [KNL] - Set the number of bursts making up a given - callback-flood test. Set this to zero to - disable callback-flood testing. - - rcutorture.cbflood_n_per_burst= [KNL] - Set the number of callbacks to be registered - in a given burst of a callback-flood test. - - rcutorture.fqs_duration= [KNL] - Set duration of force_quiescent_state bursts - in microseconds. - - rcutorture.fqs_holdoff= [KNL] - Set holdoff time within force_quiescent_state bursts - in microseconds. - - rcutorture.fqs_stutter= [KNL] - Set wait time between force_quiescent_state bursts - in seconds. - - rcutorture.gp_cond= [KNL] - Use conditional/asynchronous update-side - primitives, if available. - - rcutorture.gp_exp= [KNL] - Use expedited update-side primitives, if available. - - rcutorture.gp_normal= [KNL] - Use normal (non-expedited) asynchronous - update-side primitives, if available. - - rcutorture.gp_sync= [KNL] - Use normal (non-expedited) synchronous - update-side primitives, if available. If all - of rcutorture.gp_cond=, rcutorture.gp_exp=, - rcutorture.gp_normal=, and rcutorture.gp_sync= - are zero, rcutorture acts as if is interpreted - they are all non-zero. - - rcutorture.n_barrier_cbs= [KNL] - Set callbacks/threads for rcu_barrier() testing. - - rcutorture.nfakewriters= [KNL] - Set number of concurrent RCU writers. These just - stress RCU, they don't participate in the actual - test, hence the "fake". - - rcutorture.nreaders= [KNL] - Set number of RCU readers. The value -1 selects - N-1, where N is the number of CPUs. A value - "n" less than -1 selects N-n-2, where N is again - the number of CPUs. For example, -2 selects N - (the number of CPUs), -3 selects N+1, and so on. - - rcutorture.object_debug= [KNL] - Enable debug-object double-call_rcu() testing. - - rcutorture.onoff_holdoff= [KNL] - Set time (s) after boot for CPU-hotplug testing. - - rcutorture.onoff_interval= [KNL] - Set time (s) between CPU-hotplug operations, or - zero to disable CPU-hotplug testing. - - rcutorture.shuffle_interval= [KNL] - Set task-shuffle interval (s). Shuffling tasks - allows some CPUs to go into dyntick-idle mode - during the rcutorture test. - - rcutorture.shutdown_secs= [KNL] - Set time (s) after boot system shutdown. This - is useful for hands-off automated testing. - - rcutorture.stall_cpu= [KNL] - Duration of CPU stall (s) to test RCU CPU stall - warnings, zero to disable. - - rcutorture.stall_cpu_holdoff= [KNL] - Time to wait (s) after boot before inducing stall. - - rcutorture.stat_interval= [KNL] - Time (s) between statistics printk()s. - - rcutorture.stutter= [KNL] - Time (s) to stutter testing, for example, specifying - five seconds causes the test to run for five seconds, - wait for five seconds, and so on. This tests RCU's - ability to transition abruptly to and from idle. - - rcutorture.test_boost= [KNL] - Test RCU priority boosting? 0=no, 1=maybe, 2=yes. - "Maybe" means test if the RCU implementation - under test support RCU priority boosting. - - rcutorture.test_boost_duration= [KNL] - Duration (s) of each individual boost test. - - rcutorture.test_boost_interval= [KNL] - Interval (s) between each boost test. - - rcutorture.test_no_idle_hz= [KNL] - Test RCU's dyntick-idle handling. See also the - rcutorture.shuffle_interval parameter. - - rcutorture.torture_runnable= [BOOT] - Start rcutorture running at boot time. - - rcutorture.torture_type= [KNL] - Specify the RCU implementation to test. - - rcutorture.verbose= [KNL] - Enable additional printk() statements. - - rcupdate.rcu_cpu_stall_suppress= [KNL] - Suppress RCU CPU stall warning messages. - - rcupdate.rcu_cpu_stall_timeout= [KNL] - Set timeout for RCU CPU stall warning messages. - - rcupdate.rcu_expedited= [KNL] - Use expedited grace-period primitives, for - example, synchronize_rcu_expedited() instead - of synchronize_rcu(). This reduces latency, - but can increase CPU utilization, degrade - real-time latency, and degrade energy efficiency. - No effect on CONFIG_TINY_RCU kernels. - - rcupdate.rcu_normal= [KNL] - Use only normal grace-period primitives, - for example, synchronize_rcu() instead of - synchronize_rcu_expedited(). This improves - real-time latency, CPU utilization, and - energy efficiency, but can expose users to - increased grace-period latency. This parameter - overrides rcupdate.rcu_expedited. No effect on - CONFIG_TINY_RCU kernels. - - rcupdate.rcu_normal_after_boot= [KNL] - Once boot has completed (that is, after - rcu_end_inkernel_boot() has been invoked), use - only normal grace-period primitives. No effect - on CONFIG_TINY_RCU kernels. - - rcupdate.rcu_task_stall_timeout= [KNL] - Set timeout in jiffies for RCU task stall warning - messages. Disable with a value less than or equal - to zero. - - rcupdate.rcu_self_test= [KNL] - Run the RCU early boot self tests - - rcupdate.rcu_self_test_bh= [KNL] - Run the RCU bh early boot self tests - - rcupdate.rcu_self_test_sched= [KNL] - Run the RCU sched early boot self tests - - rdinit= [KNL] - Format: - Run specified binary instead of /init from the ramdisk, - used for early userspace startup. See initrd. - - reboot= [KNL] - Format (x86 or x86_64): - [w[arm] | c[old] | h[ard] | s[oft] | g[pio]] \ - [[,]s[mp]#### \ - [[,]b[ios] | a[cpi] | k[bd] | t[riple] | e[fi] | p[ci]] \ - [[,]f[orce] - Where reboot_mode is one of warm (soft) or cold (hard) or gpio, - reboot_type is one of bios, acpi, kbd, triple, efi, or pci, - reboot_force is either force or not specified, - reboot_cpu is s[mp]#### with #### being the processor - to be used for rebooting. - - relax_domain_level= - [KNL, SMP] Set scheduler's default relax_domain_level. - See Documentation/cgroup-v1/cpusets.txt. - - relative_sleep_states= - [SUSPEND] Use sleep state labeling where the deepest - state available other than hibernation is always "mem". - Format: { "0" | "1" } - 0 -- Traditional sleep state labels. - 1 -- Relative sleep state labels. - - reserve= [KNL,BUGS] Force the kernel to ignore some iomem area - - reservetop= [X86-32] - Format: nn[KMG] - Reserves a hole at the top of the kernel virtual - address space. - - reservelow= [X86] - Format: nn[K] - Set the amount of memory to reserve for BIOS at - the bottom of the address space. - - reset_devices [KNL] Force drivers to reset the underlying device - during initialization. - - resume= [SWSUSP] - Specify the partition device for software suspend - Format: - {/dev/ | PARTUUID= | : | } - - resume_offset= [SWSUSP] - Specify the offset from the beginning of the partition - given by "resume=" at which the swap header is located, - in units (needed only for swap files). - See Documentation/power/swsusp-and-swap-files.txt - - resumedelay= [HIBERNATION] Delay (in seconds) to pause before attempting to - read the resume files - - resumewait [HIBERNATION] Wait (indefinitely) for resume device to show up. - Useful for devices that are detected asynchronously - (e.g. USB and MMC devices). - - hibernate= [HIBERNATION] - noresume Don't check if there's a hibernation image - present during boot. - nocompress Don't compress/decompress hibernation images. - no Disable hibernation and resume. - protect_image Turn on image protection during restoration - (that will set all pages holding image data - during restoration read-only). - - retain_initrd [RAM] Keep initrd memory after extraction - - rfkill.default_state= - 0 "airplane mode". All wifi, bluetooth, wimax, gps, fm, - etc. communication is blocked by default. - 1 Unblocked. - - rfkill.master_switch_mode= - 0 The "airplane mode" button does nothing. - 1 The "airplane mode" button toggles between everything - blocked and the previous configuration. - 2 The "airplane mode" button toggles between everything - blocked and everything unblocked. - - rhash_entries= [KNL,NET] - Set number of hash buckets for route cache - - ro [KNL] Mount root device read-only on boot - - rodata= [KNL] - on Mark read-only kernel memory as read-only (default). - off Leave read-only kernel memory writable for debugging. - - rockchip.usb_uart - Enable the uart passthrough on the designated usb port - on Rockchip SoCs. When active, the signals of the - debug-uart get routed to the D+ and D- pins of the usb - port and the regular usb controller gets disabled. - - root= [KNL] Root filesystem - See name_to_dev_t comment in init/do_mounts.c. - - rootdelay= [KNL] Delay (in seconds) to pause before attempting to - mount the root filesystem - - rootflags= [KNL] Set root filesystem mount option string - - rootfstype= [KNL] Set root filesystem type - - rootwait [KNL] Wait (indefinitely) for root device to show up. - Useful for devices that are detected asynchronously - (e.g. USB and MMC devices). - - rproc_mem=nn[KMG][@address] - [KNL,ARM,CMA] Remoteproc physical memory block. - Memory area to be used by remote processor image, - managed by CMA. - - rw [KNL] Mount root device read-write on boot - - S [KNL] Run init in single mode - - s390_iommu= [HW,S390] - Set s390 IOTLB flushing mode - strict - With strict flushing every unmap operation will result in - an IOTLB flush. Default is lazy flushing before reuse, - which is faster. - - sa1100ir [NET] - See drivers/net/irda/sa1100_ir.c. - - sbni= [NET] Granch SBNI12 leased line adapter - - sched_debug [KNL] Enables verbose scheduler debug messages. - - schedstats= [KNL,X86] Enable or disable scheduled statistics. - Allowed values are enable and disable. This feature - incurs a small amount of overhead in the scheduler - but is useful for debugging and performance tuning. - - skew_tick= [KNL] Offset the periodic timer tick per cpu to mitigate - xtime_lock contention on larger systems, and/or RCU lock - contention on all systems with CONFIG_MAXSMP set. - Format: { "0" | "1" } - 0 -- disable. (may be 1 via CONFIG_CMDLINE="skew_tick=1" - 1 -- enable. - Note: increases power consumption, thus should only be - enabled if running jitter sensitive (HPC/RT) workloads. - - security= [SECURITY] Choose a security module to enable at boot. - If this boot parameter is not specified, only the first - security module asking for security registration will be - loaded. An invalid security module name will be treated - as if no module has been chosen. - - selinux= [SELINUX] Disable or enable SELinux at boot time. - Format: { "0" | "1" } - See security/selinux/Kconfig help text. - 0 -- disable. - 1 -- enable. - Default value is set via kernel config option. - If enabled at boot time, /selinux/disable can be used - later to disable prior to initial policy load. - - apparmor= [APPARMOR] Disable or enable AppArmor at boot time - Format: { "0" | "1" } - See security/apparmor/Kconfig help text - 0 -- disable. - 1 -- enable. - Default value is set via kernel config option. - - serialnumber [BUGS=X86-32] - - shapers= [NET] - Maximal number of shapers. - - show_msr= [x86] show boot-time MSR settings - Format: { } - Show boot-time (BIOS-initialized) MSR settings. - The parameter means the number of CPUs to show, - for example 1 means boot CPU only. - - simeth= [IA-64] - simscsi= - - slram= [HW,MTD] - - slab_nomerge [MM] - Disable merging of slabs with similar size. May be - necessary if there is some reason to distinguish - allocs to different slabs. Debug options disable - merging on their own. - For more information see Documentation/vm/slub.txt. - - slab_max_order= [MM, SLAB] - Determines the maximum allowed order for slabs. - A high setting may cause OOMs due to memory - fragmentation. Defaults to 1 for systems with - more than 32MB of RAM, 0 otherwise. - - slub_debug[=options[,slabs]] [MM, SLUB] - Enabling slub_debug allows one to determine the - culprit if slab objects become corrupted. Enabling - slub_debug can create guard zones around objects and - may poison objects when not in use. Also tracks the - last alloc / free. For more information see - Documentation/vm/slub.txt. - - slub_max_order= [MM, SLUB] - Determines the maximum allowed order for slabs. - A high setting may cause OOMs due to memory - fragmentation. For more information see - Documentation/vm/slub.txt. - - slub_min_objects= [MM, SLUB] - The minimum number of objects per slab. SLUB will - increase the slab order up to slub_max_order to - generate a sufficiently large slab able to contain - the number of objects indicated. The higher the number - of objects the smaller the overhead of tracking slabs - and the less frequently locks need to be acquired. - For more information see Documentation/vm/slub.txt. - - slub_min_order= [MM, SLUB] - Determines the minimum page order for slabs. Must be - lower than slub_max_order. - For more information see Documentation/vm/slub.txt. - - slub_nomerge [MM, SLUB] - Same with slab_nomerge. This is supported for legacy. - See slab_nomerge for more information. - - smart2= [HW] - Format: [,[,...,]] - - smsc-ircc2.nopnp [HW] Don't use PNP to discover SMC devices - smsc-ircc2.ircc_cfg= [HW] Device configuration I/O port - smsc-ircc2.ircc_sir= [HW] SIR base I/O port - smsc-ircc2.ircc_fir= [HW] FIR base I/O port - smsc-ircc2.ircc_irq= [HW] IRQ line - smsc-ircc2.ircc_dma= [HW] DMA channel - smsc-ircc2.ircc_transceiver= [HW] Transceiver type: - 0: Toshiba Satellite 1800 (GP data pin select) - 1: Fast pin select (default) - 2: ATC IRMode - - smt [KNL,S390] Set the maximum number of threads (logical - CPUs) to use per physical CPU on systems capable of - symmetric multithreading (SMT). Will be capped to the - actual hardware limit. - Format: - Default: -1 (no limit) - - softlockup_panic= - [KNL] Should the soft-lockup detector generate panics. - Format: - - softlockup_all_cpu_backtrace= - [KNL] Should the soft-lockup detector generate - backtraces on all cpus. - Format: - - sonypi.*= [HW] Sony Programmable I/O Control Device driver - See Documentation/laptops/sonypi.txt - - spia_io_base= [HW,MTD] - spia_fio_base= - spia_pedr= - spia_peddr= - - stacktrace [FTRACE] - Enabled the stack tracer on boot up. - - stacktrace_filter=[function-list] - [FTRACE] Limit the functions that the stack tracer - will trace at boot up. function-list is a comma separated - list of functions. This list can be changed at run - time by the stack_trace_filter file in the debugfs - tracing directory. Note, this enables stack tracing - and the stacktrace above is not needed. - - sti= [PARISC,HW] - Format: - Set the STI (builtin display/keyboard on the HP-PARISC - machines) console (graphic card) which should be used - as the initial boot-console. - See also comment in drivers/video/console/sticore.c. - - sti_font= [HW] - See comment in drivers/video/console/sticore.c. - - stifb= [HW] - Format: bpp:[:[:...]] - - sunrpc.min_resvport= - sunrpc.max_resvport= - [NFS,SUNRPC] - SunRPC servers often require that client requests - originate from a privileged port (i.e. a port in the - range 0 < portnr < 1024). - An administrator who wishes to reserve some of these - ports for other uses may adjust the range that the - kernel's sunrpc client considers to be privileged - using these two parameters to set the minimum and - maximum port values. - - sunrpc.svc_rpc_per_connection_limit= - [NFS,SUNRPC] - Limit the number of requests that the server will - process in parallel from a single connection. - The default value is 0 (no limit). - - sunrpc.pool_mode= - [NFS] - Control how the NFS server code allocates CPUs to - service thread pools. Depending on how many NICs - you have and where their interrupts are bound, this - option will affect which CPUs will do NFS serving. - Note: this parameter cannot be changed while the - NFS server is running. - - auto the server chooses an appropriate mode - automatically using heuristics - global a single global pool contains all CPUs - percpu one pool for each CPU - pernode one pool for each NUMA node (equivalent - to global on non-NUMA machines) - - sunrpc.tcp_slot_table_entries= - sunrpc.udp_slot_table_entries= - [NFS,SUNRPC] - Sets the upper limit on the number of simultaneous - RPC calls that can be sent from the client to a - server. Increasing these values may allow you to - improve throughput, but will also increase the - amount of memory reserved for use by the client. - - suspend.pm_test_delay= - [SUSPEND] - Sets the number of seconds to remain in a suspend test - mode before resuming the system (see - /sys/power/pm_test). Only available when CONFIG_PM_DEBUG - is set. Default value is 5. - - swapaccount=[0|1] - [KNL] Enable accounting of swap in memory resource - controller if no parameter or 1 is given or disable - it if 0 is given (See Documentation/cgroup-v1/memory.txt) - - swiotlb= [ARM,IA-64,PPC,MIPS,X86] - Format: { | force } - -- Number of I/O TLB slabs - force -- force using of bounce buffers even if they - wouldn't be automatically used by the kernel - - switches= [HW,M68k] - - sysfs.deprecated=0|1 [KNL] - Enable/disable old style sysfs layout for old udev - on older distributions. When this option is enabled - very new udev will not work anymore. When this option - is disabled (or CONFIG_SYSFS_DEPRECATED not compiled) - in older udev will not work anymore. - Default depends on CONFIG_SYSFS_DEPRECATED_V2 set in - the kernel configuration. - - sysrq_always_enabled - [KNL] - Ignore sysrq setting - this boot parameter will - neutralize any effect of /proc/sys/kernel/sysrq. - Useful for debugging. - - tcpmhash_entries= [KNL,NET] - Set the number of tcp_metrics_hash slots. - Default value is 8192 or 16384 depending on total - ram pages. This is used to specify the TCP metrics - cache size. See Documentation/networking/ip-sysctl.txt - "tcp_no_metrics_save" section for more details. - - tdfx= [HW,DRM] - - test_suspend= [SUSPEND][,N] - Specify "mem" (for Suspend-to-RAM) or "standby" (for - standby suspend) or "freeze" (for suspend type freeze) - as the system sleep state during system startup with - the optional capability to repeat N number of times. - The system is woken from this state using a - wakeup-capable RTC alarm. - - thash_entries= [KNL,NET] - Set number of hash buckets for TCP connection - - thermal.act= [HW,ACPI] - -1: disable all active trip points in all thermal zones - : override all lowest active trip points - - thermal.crt= [HW,ACPI] - -1: disable all critical trip points in all thermal zones - : override all critical trip points - - thermal.nocrt= [HW,ACPI] - Set to disable actions on ACPI thermal zone - critical and hot trip points. - - thermal.off= [HW,ACPI] - 1: disable ACPI thermal control - - thermal.psv= [HW,ACPI] - -1: disable all passive trip points - : override all passive trip points to this - value - - thermal.tzp= [HW,ACPI] - Specify global default ACPI thermal zone polling rate - : poll all this frequency - 0: no polling (default) - - threadirqs [KNL] - Force threading of all interrupt handlers except those - marked explicitly IRQF_NO_THREAD. - - tmem [KNL,XEN] - Enable the Transcendent memory driver if built-in. - - tmem.cleancache=0|1 [KNL, XEN] - Default is on (1). Disable the usage of the cleancache - API to send anonymous pages to the hypervisor. - - tmem.frontswap=0|1 [KNL, XEN] - Default is on (1). Disable the usage of the frontswap - API to send swap pages to the hypervisor. If disabled - the selfballooning and selfshrinking are force disabled. - - tmem.selfballooning=0|1 [KNL, XEN] - Default is on (1). Disable the driving of swap pages - to the hypervisor. - - tmem.selfshrinking=0|1 [KNL, XEN] - Default is on (1). Partial swapoff that immediately - transfers pages from Xen hypervisor back to the - kernel based on different criteria. - - topology= [S390] - Format: {off | on} - Specify if the kernel should make use of the cpu - topology information if the hardware supports this. - The scheduler will make use of this information and - e.g. base its process migration decisions on it. - Default is on. - - topology_updates= [KNL, PPC, NUMA] - Format: {off} - Specify if the kernel should ignore (off) - topology updates sent by the hypervisor to this - LPAR. - - tp720= [HW,PS2] - - tpm_suspend_pcr=[HW,TPM] - Format: integer pcr id - Specify that at suspend time, the tpm driver - should extend the specified pcr with zeros, - as a workaround for some chips which fail to - flush the last written pcr on TPM_SaveState. - This will guarantee that all the other pcrs - are saved. - - trace_buf_size=nn[KMG] - [FTRACE] will set tracing buffer size on each cpu. - - trace_event=[event-list] - [FTRACE] Set and start specified trace events in order - 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. - The option-list is a comma delimited list of options - that can be enabled or disabled just as if you were - to echo the option name into - - /sys/kernel/debug/tracing/trace_options - - For example, to enable stacktrace option (to dump the - stack trace of each event), add to the command line: - - trace_options=stacktrace - - See also Documentation/trace/ftrace.txt "trace options" - section. - - tp_printk[FTRACE] - Have the tracepoints sent to printk as well as the - tracing ring buffer. This is useful for early boot up - where the system hangs or reboots and does not give the - option for reading the tracing buffer or performing a - ftrace_dump_on_oops. - - To turn off having tracepoints sent to printk, - echo 0 > /proc/sys/kernel/tracepoint_printk - Note, echoing 1 into this file without the - tracepoint_printk kernel cmdline option has no effect. - - ** CAUTION ** - - Having tracepoints sent to printk() and activating high - frequency tracepoints such as irq or sched, can cause - the system to live lock. - - traceoff_on_warning - [FTRACE] enable this option to disable tracing when a - warning is hit. This turns off "tracing_on". Tracing can - be enabled again by echoing '1' into the "tracing_on" - file located in /sys/kernel/debug/tracing/ - - This option is useful, as it disables the trace before - the WARNING dump is called, which prevents the trace to - be filled with content caused by the warning output. - - This option can also be set at run time via the sysctl - option: kernel/traceoff_on_warning - - transparent_hugepage= - [KNL] - Format: [always|madvise|never] - Can be used to control the default behavior of the system - with respect to transparent hugepages. - See Documentation/vm/transhuge.txt for more details. - - tsc= Disable clocksource stability checks for TSC. - Format: - [x86] reliable: mark tsc clocksource as reliable, this - disables clocksource verification at runtime, as well - as the stability checks done at bootup. Used to enable - high-resolution timer mode on older hardware, and in - virtualized environment. - [x86] noirqtime: Do not use TSC to do irq accounting. - Used to run time disable IRQ_TIME_ACCOUNTING on any - platforms where RDTSC is slow and this accounting - can add overhead. - - turbografx.map[2|3]= [HW,JOY] - TurboGraFX parallel port interface - Format: - ,,,,,,, - See also Documentation/input/joystick-parport.txt - - udbg-immortal [PPC] When debugging early kernel crashes that - happen after console_init() and before a proper - console driver takes over, this boot options might - help "seeing" what's going on. - - uhash_entries= [KNL,NET] - Set number of hash buckets for UDP/UDP-Lite connections - - uhci-hcd.ignore_oc= - [USB] Ignore overcurrent events (default N). - Some badly-designed motherboards generate lots of - bogus events, for ports that aren't wired to - anything. Set this parameter to avoid log spamming. - Note that genuine overcurrent events won't be - reported either. - - unknown_nmi_panic - [X86] Cause panic on unknown NMI. - - usbcore.authorized_default= - [USB] Default USB device authorization: - (default -1 = authorized except for wireless USB, - 0 = not authorized, 1 = authorized) - - usbcore.autosuspend= - [USB] The autosuspend time delay (in seconds) used - for newly-detected USB devices (default 2). This - is the time required before an idle device will be - autosuspended. Devices for which the delay is set - to a negative value won't be autosuspended at all. - - usbcore.usbfs_snoop= - [USB] Set to log all usbfs traffic (default 0 = off). - - usbcore.usbfs_snoop_max= - [USB] Maximum number of bytes to snoop in each URB - (default = 65536). - - usbcore.blinkenlights= - [USB] Set to cycle leds on hubs (default 0 = off). - - usbcore.old_scheme_first= - [USB] Start with the old device initialization - scheme (default 0 = off). - - usbcore.usbfs_memory_mb= - [USB] Memory limit (in MB) for buffers allocated by - usbfs (default = 16, 0 = max = 2047). - - usbcore.use_both_schemes= - [USB] Try the other device initialization scheme - if the first one fails (default 1 = enabled). - - usbcore.initial_descriptor_timeout= - [USB] Specifies timeout for the initial 64-byte - USB_REQ_GET_DESCRIPTOR request in milliseconds - (default 5000 = 5.0 seconds). - - usbcore.nousb [USB] Disable the USB subsystem - - usbhid.mousepoll= - [USBHID] The interval which mice are to be polled at. - - usb-storage.delay_use= - [UMS] The delay in seconds before a new device is - scanned for Logical Units (default 1). - - usb-storage.quirks= - [UMS] A list of quirks entries to supplement or - override the built-in unusual_devs list. List - entries are separated by commas. Each entry has - the form VID:PID:Flags where VID and PID are Vendor - and Product ID values (4-digit hex numbers) and - Flags is a set of characters, each corresponding - to a common usb-storage quirk flag as follows: - a = SANE_SENSE (collect more than 18 bytes - of sense data); - b = BAD_SENSE (don't collect more than 18 - bytes of sense data); - c = FIX_CAPACITY (decrease the reported - device capacity by one sector); - d = NO_READ_DISC_INFO (don't use - READ_DISC_INFO command); - e = NO_READ_CAPACITY_16 (don't use - READ_CAPACITY_16 command); - f = NO_REPORT_OPCODES (don't use report opcodes - command, uas only); - g = MAX_SECTORS_240 (don't transfer more than - 240 sectors at a time, uas only); - h = CAPACITY_HEURISTICS (decrease the - reported device capacity by one - sector if the number is odd); - i = IGNORE_DEVICE (don't bind to this - device); - j = NO_REPORT_LUNS (don't use report luns - command, uas only); - l = NOT_LOCKABLE (don't try to lock and - unlock ejectable media); - m = MAX_SECTORS_64 (don't transfer more - than 64 sectors = 32 KB at a time); - n = INITIAL_READ10 (force a retry of the - initial READ(10) command); - o = CAPACITY_OK (accept the capacity - reported by the device); - p = WRITE_CACHE (the device cache is ON - by default); - r = IGNORE_RESIDUE (the device reports - bogus residue values); - s = SINGLE_LUN (the device has only one - Logical Unit); - t = NO_ATA_1X (don't allow ATA(12) and ATA(16) - commands, uas only); - u = IGNORE_UAS (don't bind to the uas driver); - w = NO_WP_DETECT (don't test whether the - medium is write-protected). - y = ALWAYS_SYNC (issue a SYNCHRONIZE_CACHE - even if the device claims no cache) - Example: quirks=0419:aaf5:rl,0421:0433:rc - - user_debug= [KNL,ARM] - Format: - See arch/arm/Kconfig.debug help text. - 1 - undefined instruction events - 2 - system calls - 4 - invalid data aborts - 8 - SIGSEGV faults - 16 - SIGBUS faults - Example: user_debug=31 - - userpte= - [X86] Flags controlling user PTE allocations. - - nohigh = do not allocate PTE pages in - HIGHMEM regardless of setting - of CONFIG_HIGHPTE. - - vdso= [X86,SH] - On X86_32, this is an alias for vdso32=. Otherwise: - - vdso=1: enable VDSO (the default) - vdso=0: disable VDSO mapping - - vdso32= [X86] Control the 32-bit vDSO - vdso32=1: enable 32-bit VDSO - vdso32=0 or vdso32=2: disable 32-bit VDSO - - See the help text for CONFIG_COMPAT_VDSO for more - details. If CONFIG_COMPAT_VDSO is set, the default is - vdso32=0; otherwise, the default is vdso32=1. - - For compatibility with older kernels, vdso32=2 is an - alias for vdso32=0. - - Try vdso32=0 if you encounter an error that says: - dl_main: Assertion `(void *) ph->p_vaddr == _rtld_local._dl_sysinfo_dso' failed! - - vector= [IA-64,SMP] - vector=percpu: enable percpu vector domain - - video= [FB] Frame buffer configuration - See Documentation/fb/modedb.txt. - - video.brightness_switch_enabled= [0,1] - If set to 1, on receiving an ACPI notify event - generated by hotkey, video driver will adjust brightness - level and then send out the event to user space through - the allocated input device; If set to 0, video driver - will only send out the event without touching backlight - brightness level. - default: 1 - - virtio_mmio.device= - [VMMIO] Memory mapped virtio (platform) device. - - @:[:] - where: - := size (can use standard suffixes - like K, M and G) - := physical base address - := interrupt number (as passed to - request_irq()) - := (optional) platform device id - example: - virtio_mmio.device=1K@0x100b0000:48:7 - - Can be used multiple times for multiple devices. - - vga= [BOOT,X86-32] Select a particular video mode - See Documentation/x86/boot.txt and - Documentation/svga.txt. - Use vga=ask for menu. - This is actually a boot loader parameter; the value is - passed to the kernel using a special protocol. - - vmalloc=nn[KMG] [KNL,BOOT] Forces the vmalloc area to have an exact - size of . This can be used to increase the - minimum size (128MB on x86). It can also be used to - decrease the size and leave more room for directly - mapped kernel RAM. - - vmhalt= [KNL,S390] Perform z/VM CP command after system halt. - Format: - - vmpanic= [KNL,S390] Perform z/VM CP command after kernel panic. - Format: - - vmpoff= [KNL,S390] Perform z/VM CP command after power off. - Format: - - vsyscall= [X86-64] - Controls the behavior of vsyscalls (i.e. calls to - fixed addresses of 0xffffffffff600x00 from legacy - code). Most statically-linked binaries and older - versions of glibc use these calls. Because these - functions are at fixed addresses, they make nice - targets for exploits that can control RIP. - - emulate [default] Vsyscalls turn into traps and are - emulated reasonably safely. - - native Vsyscalls are native syscall instructions. - This is a little bit faster than trapping - and makes a few dynamic recompilers work - better than they would in emulation mode. - It also makes exploits much easier to write. - - none Vsyscalls don't work at all. This makes - them quite hard to use for exploits but - might break your system. - - vt.color= [VT] Default text color. - Format: 0xYX, X = foreground, Y = background. - Default: 0x07 = light gray on black. - - vt.cur_default= [VT] Default cursor shape. - Format: 0xCCBBAA, where AA, BB, and CC are the same as - the parameters of the [?A;B;Cc escape sequence; - see VGA-softcursor.txt. Default: 2 = underline. - - vt.default_blu= [VT] - Format: ,,,..., - Change the default blue palette of the console. - This is a 16-member array composed of values - ranging from 0-255. - - vt.default_grn= [VT] - Format: ,,,..., - Change the default green palette of the console. - This is a 16-member array composed of values - ranging from 0-255. - - vt.default_red= [VT] - Format: ,,,..., - Change the default red palette of the console. - This is a 16-member array composed of values - ranging from 0-255. - - vt.default_utf8= - [VT] - Format=<0|1> - Set system-wide default UTF-8 mode for all tty's. - Default is 1, i.e. UTF-8 mode is enabled for all - newly opened terminals. - - vt.global_cursor_default= - [VT] - Format=<-1|0|1> - Set system-wide default for whether a cursor - is shown on new VTs. Default is -1, - i.e. cursors will be created by default unless - overridden by individual drivers. 0 will hide - cursors, 1 will display them. - - vt.italic= [VT] Default color for italic text; 0-15. - Default: 2 = green. - - vt.underline= [VT] Default color for underlined text; 0-15. - Default: 3 = cyan. - - watchdog timers [HW,WDT] For information on watchdog timers, - see Documentation/watchdog/watchdog-parameters.txt - or other driver-specific files in the - Documentation/watchdog/ directory. - - workqueue.watchdog_thresh= - If CONFIG_WQ_WATCHDOG is configured, workqueue can - warn stall conditions and dump internal state to - help debugging. 0 disables workqueue stall - detection; otherwise, it's the stall threshold - duration in seconds. The default value is 30 and - it can be updated at runtime by writing to the - corresponding sysfs file. - - workqueue.disable_numa - By default, all work items queued to unbound - workqueues are affine to the NUMA nodes they're - issued on, which results in better behavior in - general. If NUMA affinity needs to be disabled for - whatever reason, this option can be used. Note - that this also can be controlled per-workqueue for - workqueues visible under /sys/bus/workqueue/. - - workqueue.power_efficient - Per-cpu workqueues are generally preferred because - they show better performance thanks to cache - locality; unfortunately, per-cpu workqueues tend to - be more power hungry than unbound workqueues. - - Enabling this makes the per-cpu workqueues which - were observed to contribute significantly to power - consumption unbound, leading to measurably lower - power usage at the cost of small performance - overhead. - - The default value of this parameter is determined by - the config option CONFIG_WQ_POWER_EFFICIENT_DEFAULT. - - workqueue.debug_force_rr_cpu - Workqueue used to implicitly guarantee that work - items queued without explicit CPU specified are put - on the local CPU. This guarantee is no longer true - and while local CPU is still preferred work items - may be put on foreign CPUs. This debug option - forces round-robin CPU selection to flush out - usages which depend on the now broken guarantee. - When enabled, memory and cache locality will be - impacted. - - x2apic_phys [X86-64,APIC] Use x2apic physical mode instead of - default x2apic cluster mode on platforms - supporting x2apic. - - x86_intel_mid_timer= [X86-32,APBT] - Choose timer option for x86 Intel MID platform. - Two valid options are apbt timer only and lapic timer - plus one apbt timer for broadcast timer. - x86_intel_mid_timer=apbt_only | lapic_and_apbt - - xen_512gb_limit [KNL,X86-64,XEN] - Restricts the kernel running paravirtualized under Xen - to use only up to 512 GB of RAM. The reason to do so is - crash analysis tools and Xen tools for doing domain - save/restore/migration must be enabled to handle larger - domains. - - xen_emul_unplug= [HW,X86,XEN] - Unplug Xen emulated devices - Format: [unplug0,][unplug1] - ide-disks -- unplug primary master IDE devices - aux-ide-disks -- unplug non-primary-master IDE devices - nics -- unplug network devices - all -- unplug all emulated devices (NICs and IDE disks) - unnecessary -- unplugging emulated devices is - unnecessary even if the host did not respond to - the unplug protocol - never -- do not unplug even if version check succeeds - - xen_nopvspin [X86,XEN] - Disables the ticketlock slowpath using Xen PV - optimizations. - - xen_nopv [X86] - Disables the PV optimizations forcing the HVM guest to - run as generic HVM guest with no PV drivers. - - xirc2ps_cs= [NET,PCMCIA] - Format: - ,,,,,[,[,[,]]] - ------------------------- +.. include:: kernel-parameters.txt + :literal: Todo ---- diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt new file mode 100644 index 000000000000..e48c5632bd6c --- /dev/null +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -0,0 +1,4367 @@ + acpi= [HW,ACPI,X86,ARM64] + Advanced Configuration and Power Interface + Format: { force | on | off | strict | noirq | rsdt | + copy_dsdt } + force -- enable ACPI if default was off + on -- enable ACPI but allow fallback to DT [arm64] + off -- disable ACPI if default was on + noirq -- do not use ACPI for IRQ routing + strict -- Be less tolerant of platforms that are not + strictly ACPI specification compliant. + rsdt -- prefer RSDT over (default) XSDT + copy_dsdt -- copy DSDT to memory + For ARM64, ONLY "acpi=off", "acpi=on" or "acpi=force" + are available + + See also Documentation/power/runtime_pm.txt, pci=noacpi + + acpi_apic_instance= [ACPI, IOAPIC] + Format: + 2: use 2nd APIC table, if available + 1,0: use 1st APIC table + default: 0 + + acpi_backlight= [HW,ACPI] + acpi_backlight=vendor + acpi_backlight=video + If set to vendor, prefer vendor specific driver + (e.g. thinkpad_acpi, sony_acpi, etc.) instead + of the ACPI video.ko driver. + + acpi_force_32bit_fadt_addr + force FADT to use 32 bit addresses rather than the + 64 bit X_* addresses. Some firmware have broken 64 + bit addresses for force ACPI ignore these and use + the older legacy 32 bit addresses. + + acpica_no_return_repair [HW, ACPI] + Disable AML predefined validation mechanism + This mechanism can repair the evaluation result to make + the return objects more ACPI specification compliant. + This option is useful for developers to identify the + root cause of an AML interpreter issue when the issue + has something to do with the repair mechanism. + + acpi.debug_layer= [HW,ACPI,ACPI_DEBUG] + acpi.debug_level= [HW,ACPI,ACPI_DEBUG] + Format: + CONFIG_ACPI_DEBUG must be enabled to produce any ACPI + debug output. Bits in debug_layer correspond to a + _COMPONENT in an ACPI source file, e.g., + #define _COMPONENT ACPI_PCI_COMPONENT + Bits in debug_level correspond to a level in + ACPI_DEBUG_PRINT statements, e.g., + ACPI_DEBUG_PRINT((ACPI_DB_INFO, ... + The debug_level mask defaults to "info". See + Documentation/acpi/debug.txt for more information about + debug layers and levels. + + Enable processor driver info messages: + acpi.debug_layer=0x20000000 + Enable PCI/PCI interrupt routing info messages: + acpi.debug_layer=0x400000 + Enable AML "Debug" output, i.e., stores to the Debug + object while interpreting AML: + acpi.debug_layer=0xffffffff acpi.debug_level=0x2 + Enable all messages related to ACPI hardware: + acpi.debug_layer=0x2 acpi.debug_level=0xffffffff + + Some values produce so much output that the system is + unusable. The "log_buf_len" parameter may be useful + if you need to capture more output. + + acpi_enforce_resources= [ACPI] + { strict | lax | no } + Check for resource conflicts between native drivers + and ACPI OperationRegions (SystemIO and SystemMemory + only). IO ports and memory declared in ACPI might be + used by the ACPI subsystem in arbitrary AML code and + can interfere with legacy drivers. + strict (default): access to resources claimed by ACPI + is denied; legacy drivers trying to access reserved + resources will fail to bind to device using them. + lax: access to resources claimed by ACPI is allowed; + legacy drivers trying to access reserved resources + will bind successfully but a warning message is logged. + no: ACPI OperationRegions are not marked as reserved, + no further checks are performed. + + acpi_force_table_verification [HW,ACPI] + Enable table checksum verification during early stage. + By default, this is disabled due to x86 early mapping + size limitation. + + acpi_irq_balance [HW,ACPI] + ACPI will balance active IRQs + default in APIC mode + + acpi_irq_nobalance [HW,ACPI] + ACPI will not move active IRQs (default) + default in PIC mode + + acpi_irq_isa= [HW,ACPI] If irq_balance, mark listed IRQs used by ISA + Format: ,... + + acpi_irq_pci= [HW,ACPI] If irq_balance, clear listed IRQs for + use by PCI + Format: ,... + + acpi_no_auto_serialize [HW,ACPI] + Disable auto-serialization of AML methods + AML control methods that contain the opcodes to create + named objects will be marked as "Serialized" by the + auto-serialization feature. + This feature is enabled by default. + This option allows to turn off the feature. + + acpi_no_memhotplug [ACPI] Disable memory hotplug. Useful for kdump + kernels. + + acpi_no_static_ssdt [HW,ACPI] + Disable installation of static SSDTs at early boot time + By default, SSDTs contained in the RSDT/XSDT will be + installed automatically and they will appear under + /sys/firmware/acpi/tables. + This option turns off this feature. + Note that specifying this option does not affect + dynamic table installation which will install SSDT + tables to /sys/firmware/acpi/tables/dynamic. + + acpi_rsdp= [ACPI,EFI,KEXEC] + Pass the RSDP address to the kernel, mostly used + on machines running EFI runtime service to boot the + second kernel for kdump. + + acpi_os_name= [HW,ACPI] Tell ACPI BIOS the name of the OS + Format: To spoof as Windows 98: ="Microsoft Windows" + + acpi_rev_override [ACPI] Override the _REV object to return 5 (instead + of 2 which is mandated by ACPI 6) as the supported ACPI + specification revision (when using this switch, it may + be necessary to carry out a cold reboot _twice_ in a + row to make it take effect on the platform firmware). + + acpi_osi= [HW,ACPI] Modify list of supported OS interface strings + acpi_osi="string1" # add string1 + acpi_osi="!string2" # remove string2 + acpi_osi=!* # remove all strings + acpi_osi=! # disable all built-in OS vendor + strings + acpi_osi=!! # enable all built-in OS vendor + strings + acpi_osi= # disable all strings + + 'acpi_osi=!' can be used in combination with single or + multiple 'acpi_osi="string1"' to support specific OS + vendor string(s). Note that such command can only + affect the default state of the OS vendor strings, thus + it cannot affect the default state of the feature group + strings and the current state of the OS vendor strings, + specifying it multiple times through kernel command line + is meaningless. This command is useful when one do not + care about the state of the feature group strings which + should be controlled by the OSPM. + Examples: + 1. 'acpi_osi=! acpi_osi="Windows 2000"' is equivalent + to 'acpi_osi="Windows 2000" acpi_osi=!', they all + can make '_OSI("Windows 2000")' TRUE. + + 'acpi_osi=' cannot be used in combination with other + 'acpi_osi=' command lines, the _OSI method will not + exist in the ACPI namespace. NOTE that such command can + only affect the _OSI support state, thus specifying it + multiple times through kernel command line is also + meaningless. + Examples: + 1. 'acpi_osi=' can make 'CondRefOf(_OSI, Local1)' + FALSE. + + 'acpi_osi=!*' can be used in combination with single or + multiple 'acpi_osi="string1"' to support specific + string(s). Note that such command can affect the + current state of both the OS vendor strings and the + feature group strings, thus specifying it multiple times + through kernel command line is meaningful. But it may + still not able to affect the final state of a string if + there are quirks related to this string. This command + is useful when one want to control the state of the + feature group strings to debug BIOS issues related to + the OSPM features. + Examples: + 1. 'acpi_osi="Module Device" acpi_osi=!*' can make + '_OSI("Module Device")' FALSE. + 2. 'acpi_osi=!* acpi_osi="Module Device"' can make + '_OSI("Module Device")' TRUE. + 3. 'acpi_osi=! acpi_osi=!* acpi_osi="Windows 2000"' is + equivalent to + 'acpi_osi=!* acpi_osi=! acpi_osi="Windows 2000"' + and + 'acpi_osi=!* acpi_osi="Windows 2000" acpi_osi=!', + they all will make '_OSI("Windows 2000")' TRUE. + + acpi_pm_good [X86] + Override the pmtimer bug detection: force the kernel + to assume that this machine's pmtimer latches its value + and always returns good values. + + acpi_sci= [HW,ACPI] ACPI System Control Interrupt trigger mode + Format: { level | edge | high | low } + + acpi_skip_timer_override [HW,ACPI] + Recognize and ignore IRQ0/pin2 Interrupt Override. + For broken nForce2 BIOS resulting in XT-PIC timer. + + acpi_sleep= [HW,ACPI] Sleep options + Format: { s3_bios, s3_mode, s3_beep, s4_nohwsig, + old_ordering, nonvs, sci_force_enable } + See Documentation/power/video.txt for information on + s3_bios and s3_mode. + s3_beep is for debugging; it makes the PC's speaker beep + as soon as the kernel's real-mode entry point is called. + s4_nohwsig prevents ACPI hardware signature from being + used during resume from hibernation. + old_ordering causes the ACPI 1.0 ordering of the _PTS + control method, with respect to putting devices into + low power states, to be enforced (the ACPI 2.0 ordering + of _PTS is used by default). + nonvs prevents the kernel from saving/restoring the + ACPI NVS memory during suspend/hibernation and resume. + sci_force_enable causes the kernel to set SCI_EN directly + on resume from S1/S3 (which is against the ACPI spec, + but some broken systems don't work without it). + + acpi_use_timer_override [HW,ACPI] + Use timer override. For some broken Nvidia NF5 boards + that require a timer override, but don't have HPET + + add_efi_memmap [EFI; X86] Include EFI memory map in + kernel's map of available physical RAM. + + agp= [AGP] + { off | try_unsupported } + off: disable AGP support + try_unsupported: try to drive unsupported chipsets + (may crash computer or cause data corruption) + + ALSA [HW,ALSA] + See Documentation/sound/alsa/alsa-parameters.txt + + alignment= [KNL,ARM] + Allow the default userspace alignment fault handler + behaviour to be specified. Bit 0 enables warnings, + bit 1 enables fixups, and bit 2 sends a segfault. + + align_va_addr= [X86-64] + Align virtual addresses by clearing slice [14:12] when + allocating a VMA at process creation time. This option + gives you up to 3% performance improvement on AMD F15h + machines (where it is enabled by default) for a + CPU-intensive style benchmark, and it can vary highly in + a microbenchmark depending on workload and compiler. + + 32: only for 32-bit processes + 64: only for 64-bit processes + on: enable for both 32- and 64-bit processes + off: disable for both 32- and 64-bit processes + + alloc_snapshot [FTRACE] + Allocate the ftrace snapshot buffer on boot up when the + main buffer is allocated. This is handy if debugging + and you need to use tracing_snapshot() on boot up, and + do not want to use tracing_snapshot_alloc() as it needs + to be done where GFP_KERNEL allocations are allowed. + + amd_iommu= [HW,X86-64] + Pass parameters to the AMD IOMMU driver in the system. + Possible values are: + fullflush - enable flushing of IO/TLB entries when + they are unmapped. Otherwise they are + flushed before they will be reused, which + is a lot of faster + off - do not initialize any AMD IOMMU found in + the system + force_isolation - Force device isolation for all + devices. The IOMMU driver is not + allowed anymore to lift isolation + requirements as needed. This option + does not override iommu=pt + + amd_iommu_dump= [HW,X86-64] + Enable AMD IOMMU driver option to dump the ACPI table + for AMD IOMMU. With this option enabled, AMD IOMMU + driver will print ACPI tables for AMD IOMMU during + IOMMU initialization. + + amd_iommu_intr= [HW,X86-64] + Specifies one of the following AMD IOMMU interrupt + remapping modes: + legacy - Use legacy interrupt remapping mode. + vapic - Use virtual APIC mode, which allows IOMMU + to inject interrupts directly into guest. + This mode requires kvm-amd.avic=1. + (Default when IOMMU HW support is present.) + + amijoy.map= [HW,JOY] Amiga joystick support + Map of devices attached to JOY0DAT and JOY1DAT + Format: , + See also Documentation/input/joystick.txt + + analog.map= [HW,JOY] Analog joystick and gamepad support + Specifies type or capabilities of an analog joystick + connected to one of 16 gameports + Format: ,,.. + + apc= [HW,SPARC] + Power management functions (SPARCstation-4/5 + deriv.) + Format: noidle + Disable APC CPU standby support. SPARCstation-Fox does + not play well with APC CPU idle - disable it if you have + APC and your system crashes randomly. + + apic= [APIC,X86-32] Advanced Programmable Interrupt Controller + Change the output verbosity whilst booting + Format: { quiet (default) | verbose | debug } + Change the amount of debugging information output + when initialising the APIC and IO-APIC components. + + apic_extnmi= [APIC,X86] External NMI delivery setting + Format: { bsp (default) | all | none } + bsp: External NMI is delivered only to CPU 0 + all: External NMIs are broadcast to all CPUs as a + backup of CPU 0 + none: External NMI is masked for all CPUs. This is + useful so that a dump capture kernel won't be + shot down by NMI + + autoconf= [IPV6] + See Documentation/networking/ipv6.txt. + + show_lapic= [APIC,X86] Advanced Programmable Interrupt Controller + Limit apic dumping. The parameter defines the maximal + number of local apics being dumped. Also it is possible + to set it to "all" by meaning -- no limit here. + Format: { 1 (default) | 2 | ... | all }. + The parameter valid if only apic=debug or + apic=verbose is specified. + Example: apic=debug show_lapic=all + + apm= [APM] Advanced Power Management + See header of arch/x86/kernel/apm_32.c. + + arcrimi= [HW,NET] ARCnet - "RIM I" (entirely mem-mapped) cards + Format: ,, + + ataflop= [HW,M68k] + + atarimouse= [HW,MOUSE] Atari Mouse + + atkbd.extra= [HW] Enable extra LEDs and keys on IBM RapidAccess, + EzKey and similar keyboards + + atkbd.reset= [HW] Reset keyboard during initialization + + atkbd.set= [HW] Select keyboard code set + Format: (2 = AT (default), 3 = PS/2) + + atkbd.scroll= [HW] Enable scroll wheel on MS Office and similar + keyboards + + atkbd.softraw= [HW] Choose between synthetic and real raw mode + Format: (0 = real, 1 = synthetic (default)) + + atkbd.softrepeat= [HW] + Use software keyboard repeat + + audit= [KNL] Enable the audit sub-system + Format: { "0" | "1" } (0 = disabled, 1 = enabled) + 0 - kernel audit is disabled and can not be enabled + until the next reboot + unset - kernel audit is initialized but disabled and + will be fully enabled by the userspace auditd. + 1 - kernel audit is initialized and partially enabled, + storing at most audit_backlog_limit messages in + RAM until it is fully enabled by the userspace + auditd. + Default: unset + + audit_backlog_limit= [KNL] Set the audit queue size limit. + Format: (must be >=0) + Default: 64 + + bau= [X86_UV] Enable the BAU on SGI UV. The default + behavior is to disable the BAU (i.e. bau=0). + Format: { "0" | "1" } + 0 - Disable the BAU. + 1 - Enable the BAU. + unset - Disable the BAU. + + baycom_epp= [HW,AX25] + Format: , + + baycom_par= [HW,AX25] BayCom Parallel Port AX.25 Modem + Format: , + See header of drivers/net/hamradio/baycom_par.c. + + baycom_ser_fdx= [HW,AX25] + BayCom Serial Port AX.25 Modem (Full Duplex Mode) + Format: ,,[,] + See header of drivers/net/hamradio/baycom_ser_fdx.c. + + baycom_ser_hdx= [HW,AX25] + BayCom Serial Port AX.25 Modem (Half Duplex Mode) + Format: ,, + See header of drivers/net/hamradio/baycom_ser_hdx.c. + + blkdevparts= Manual partition parsing of block device(s) for + embedded devices based on command line input. + See Documentation/block/cmdline-partition.txt + + boot_delay= Milliseconds to delay each printk during boot. + Values larger than 10 seconds (10000) are changed to + no delay (0). + Format: integer + + bootmem_debug [KNL] Enable bootmem allocator debug messages. + + bert_disable [ACPI] + Disable BERT OS support on buggy BIOSes. + + bttv.card= [HW,V4L] bttv (bt848 + bt878 based grabber cards) + bttv.radio= Most important insmod options are available as + kernel args too. + bttv.pll= See Documentation/video4linux/bttv/Insmod-options + bttv.tuner= + + bulk_remove=off [PPC] This parameter disables the use of the pSeries + firmware feature for flushing multiple hpte entries + at a time. + + c101= [NET] Moxa C101 synchronous serial card + + cachesize= [BUGS=X86-32] Override level 2 CPU cache size detection. + Sometimes CPU hardware bugs make them report the cache + size incorrectly. The kernel will attempt work arounds + to fix known problems, but for some CPUs it is not + possible to determine what the correct size should be. + This option provides an override for these situations. + + ca_keys= [KEYS] This parameter identifies a specific key(s) on + the system trusted keyring to be used for certificate + trust validation. + format: { id: | builtin } + + cca= [MIPS] Override the kernel pages' cache coherency + algorithm. Accepted values range from 0 to 7 + inclusive. See arch/mips/include/asm/pgtable-bits.h + for platform specific values (SB1, Loongson3 and + others). + + ccw_timeout_log [S390] + See Documentation/s390/CommonIO for details. + + cgroup_disable= [KNL] Disable a particular controller + Format: {name of the controller(s) to disable} + The effects of cgroup_disable=foo are: + - foo isn't auto-mounted if you mount all cgroups in + a single hierarchy + - foo isn't visible as an individually mountable + subsystem + {Currently only "memory" controller deal with this and + cut the overhead, others just disable the usage. So + only cgroup_disable=memory is actually worthy} + + cgroup_no_v1= [KNL] Disable one, multiple, all cgroup controllers in v1 + Format: { controller[,controller...] | "all" } + Like cgroup_disable, but only applies to cgroup v1; + the blacklisted controllers remain available in cgroup2. + + cgroup.memory= [KNL] Pass options to the cgroup memory controller. + Format: + nosocket -- Disable socket memory accounting. + nokmem -- Disable kernel memory accounting. + + checkreqprot [SELINUX] Set initial checkreqprot flag value. + Format: { "0" | "1" } + See security/selinux/Kconfig help text. + 0 -- check protection applied by kernel (includes + any implied execute protection). + 1 -- check protection requested by application. + Default value is set via a kernel config option. + Value can be changed at runtime via + /selinux/checkreqprot. + + cio_ignore= [S390] + See Documentation/s390/CommonIO for details. + clk_ignore_unused + [CLK] + Prevents the clock framework from automatically gating + clocks that have not been explicitly enabled by a Linux + device driver but are enabled in hardware at reset or + by the bootloader/firmware. Note that this does not + force such clocks to be always-on nor does it reserve + those clocks in any way. This parameter is useful for + debug and development, but should not be needed on a + platform with proper driver support. For more + information, see Documentation/clk.txt. + + clock= [BUGS=X86-32, HW] gettimeofday clocksource override. + [Deprecated] + Forces specified clocksource (if available) to be used + when calculating gettimeofday(). If specified + clocksource is not available, it defaults to PIT. + Format: { pit | tsc | cyclone | pmtmr } + + clocksource= Override the default clocksource + Format: + Override the default clocksource and use the clocksource + with the name specified. + Some clocksource names to choose from, depending on + the platform: + [all] jiffies (this is the base, fallback clocksource) + [ACPI] acpi_pm + [ARM] imx_timer1,OSTS,netx_timer,mpu_timer2, + pxa_timer,timer3,32k_counter,timer0_1 + [AVR32] avr32 + [X86-32] pit,hpet,tsc; + scx200_hrt on Geode; cyclone on IBM x440 + [MIPS] MIPS + [PARISC] cr16 + [S390] tod + [SH] SuperH + [SPARC64] tick + [X86-64] hpet,tsc + + clocksource.arm_arch_timer.evtstrm= + [ARM,ARM64] + Format: + Enable/disable the eventstream feature of the ARM + architected timer so that code using WFE-based polling + loops can be debugged more effectively on production + systems. + + clocksource.arm_arch_timer.fsl-a008585= + [ARM64] + Format: + Enable/disable the workaround of Freescale/NXP + erratum A-008585. This can be useful for KVM + guests, if the guest device tree doesn't show the + erratum. If unspecified, the workaround is + enabled based on the device tree. + + clearcpuid=BITNUM [X86] + Disable CPUID feature X for the kernel. See + arch/x86/include/asm/cpufeatures.h for the valid bit + numbers. Note the Linux specific bits are not necessarily + stable over kernel options, but the vendor specific + ones should be. + Also note that user programs calling CPUID directly + or using the feature without checking anything + will still see it. This just prevents it from + being used by the kernel or shown in /proc/cpuinfo. + Also note the kernel might malfunction if you disable + some critical bits. + + cma=nn[MG]@[start[MG][-end[MG]]] + [ARM,X86,KNL] + Sets the size of kernel global memory area for + contiguous memory allocations and optionally the + placement constraint by the physical address range of + memory allocations. A value of 0 disables CMA + altogether. For more information, see + include/linux/dma-contiguous.h + + cmo_free_hint= [PPC] Format: { yes | no } + Specify whether pages are marked as being inactive + when they are freed. This is used in CMO environments + to determine OS memory pressure for page stealing by + a hypervisor. + Default: yes + + coherent_pool=nn[KMG] [ARM,KNL] + Sets the size of memory pool for coherent, atomic dma + allocations, by default set to 256K. + + code_bytes [X86] How many bytes of object code to print + in an oops report. + Range: 0 - 8192 + Default: 64 + + com20020= [HW,NET] ARCnet - COM20020 chipset + Format: + [,[,[,[,[,]]]]] + + com90io= [HW,NET] ARCnet - COM90xx chipset (IO-mapped buffers) + Format: [,] + + com90xx= [HW,NET] + ARCnet - COM90xx chipset (memory-mapped buffers) + Format: [,[,]] + + condev= [HW,S390] console device + conmode= + + console= [KNL] Output console device and options. + + tty Use the virtual console device . + + ttyS[,options] + ttyUSB0[,options] + Use the specified serial port. The options are of + the form "bbbbpnf", where "bbbb" is the baud rate, + "p" is parity ("n", "o", or "e"), "n" is number of + bits, and "f" is flow control ("r" for RTS or + omit it). Default is "9600n8". + + See Documentation/admin-guide/serial-console.rst for more + information. See + Documentation/networking/netconsole.txt for an + alternative. + + uart[8250],io,[,options] + uart[8250],mmio,[,options] + uart[8250],mmio16,[,options] + uart[8250],mmio32,[,options] + uart[8250],0x[,options] + Start an early, polled-mode console on the 8250/16550 + UART at the specified I/O port or MMIO address, + switching to the matching ttyS device later. + MMIO inter-register address stride is either 8-bit + (mmio), 16-bit (mmio16), or 32-bit (mmio32). + If none of [io|mmio|mmio16|mmio32], is assumed + to be equivalent to 'mmio'. 'options' are specified in + the same format described for ttyS above; if unspecified, + the h/w is not re-initialized. + + hvc Use the hypervisor console device . This is for + both Xen and PowerPC hypervisors. + + If the device connected to the port is not a TTY but a braille + device, prepend "brl," before the device type, for instance + console=brl,ttyS0 + For now, only VisioBraille is supported. + + consoleblank= [KNL] The console blank (screen saver) timeout in + seconds. Defaults to 10*60 = 10mins. A value of 0 + disables the blank timer. + + coredump_filter= + [KNL] Change the default value for + /proc//coredump_filter. + See also Documentation/filesystems/proc.txt. + + cpuidle.off=1 [CPU_IDLE] + disable the cpuidle sub-system + + cpu_init_udelay=N + [X86] Delay for N microsec between assert and de-assert + of APIC INIT to start processors. This delay occurs + on every CPU online, such as boot, and resume from suspend. + Default: 10000 + + cpcihp_generic= [HW,PCI] Generic port I/O CompactPCI driver + Format: + ,,,[,] + + crashkernel=size[KMG][@offset[KMG]] + [KNL] Using kexec, Linux can switch to a 'crash kernel' + upon panic. This parameter reserves the physical + memory region [offset, offset + size] for that kernel + image. If '@offset' is omitted, then a suitable offset + is selected automatically. Check + Documentation/kdump/kdump.txt for further details. + + crashkernel=range1:size1[,range2:size2,...][@offset] + [KNL] Same as above, but depends on the memory + in the running system. The syntax of range is + start-[end] where start and end are both + a memory unit (amount[KMG]). See also + Documentation/kdump/kdump.txt for an example. + + crashkernel=size[KMG],high + [KNL, x86_64] range could be above 4G. Allow kernel + to allocate physical memory region from top, so could + be above 4G if system have more than 4G ram installed. + Otherwise memory region will be allocated below 4G, if + available. + It will be ignored if crashkernel=X is specified. + crashkernel=size[KMG],low + [KNL, x86_64] range under 4G. When crashkernel=X,high + is passed, kernel could allocate physical memory region + above 4G, that cause second kernel crash on system + that require some amount of low memory, e.g. swiotlb + requires at least 64M+32K low memory, also enough extra + low memory is needed to make sure DMA buffers for 32-bit + devices won't run out. Kernel would try to allocate at + at least 256M below 4G automatically. + This one let user to specify own low range under 4G + for second kernel instead. + 0: to disable low allocation. + It will be ignored when crashkernel=X,high is not used + or memory reserved is below 4G. + + cryptomgr.notests + [KNL] Disable crypto self-tests + + cs89x0_dma= [HW,NET] + Format: + + cs89x0_media= [HW,NET] + Format: { rj45 | aui | bnc } + + dasd= [HW,NET] + See header of drivers/s390/block/dasd_devmap.c. + + db9.dev[2|3]= [HW,JOY] Multisystem joystick support via parallel port + (one device per port) + Format: , + See also Documentation/input/joystick-parport.txt + + ddebug_query= [KNL,DYNAMIC_DEBUG] Enable debug messages at early boot + time. See Documentation/dynamic-debug-howto.txt for + details. Deprecated, see dyndbg. + + debug [KNL] Enable kernel debugging (events log level). + + debug_locks_verbose= + [KNL] verbose self-tests + Format=<0|1> + Print debugging info while doing the locking API + self-tests. + We default to 0 (no extra messages), setting it to + 1 will print _a lot_ more information - normally + only useful to kernel developers. + + debug_objects [KNL] Enable object debugging + + no_debug_objects + [KNL] Disable object debugging + + debug_guardpage_minorder= + [KNL] When CONFIG_DEBUG_PAGEALLOC is set, this + parameter allows control of the order of pages that will + be intentionally kept free (and hence protected) by the + buddy allocator. Bigger value increase the probability + of catching random memory corruption, but reduce the + amount of memory for normal system use. The maximum + possible value is MAX_ORDER/2. Setting this parameter + to 1 or 2 should be enough to identify most random + memory corruption problems caused by bugs in kernel or + driver code when a CPU writes to (or reads from) a + random memory location. Note that there exists a class + of memory corruptions problems caused by buggy H/W or + F/W or by drivers badly programing DMA (basically when + memory is written at bus level and the CPU MMU is + bypassed) which are not detectable by + CONFIG_DEBUG_PAGEALLOC, hence this option will not help + tracking down these problems. + + debug_pagealloc= + [KNL] When CONFIG_DEBUG_PAGEALLOC is set, this + parameter enables the feature at boot time. In + default, it is disabled. We can avoid allocating huge + chunk of memory for debug pagealloc if we don't enable + it at boot time and the system will work mostly same + with the kernel built without CONFIG_DEBUG_PAGEALLOC. + on: enable the feature + + debugpat [X86] Enable PAT debugging + + decnet.addr= [HW,NET] + Format: [,] + See also Documentation/networking/decnet.txt. + + default_hugepagesz= + [same as hugepagesz=] The size of the default + HugeTLB page size. This is the size represented by + the legacy /proc/ hugepages APIs, used for SHM, and + default size when mounting hugetlbfs filesystems. + Defaults to the default architecture's huge page size + if not specified. + + dhash_entries= [KNL] + Set number of hash buckets for dentry cache. + + disable_1tb_segments [PPC] + Disables the use of 1TB hash page table segments. This + causes the kernel to fall back to 256MB segments which + can be useful when debugging issues that require an SLB + miss to occur. + + disable= [IPV6] + See Documentation/networking/ipv6.txt. + + disable_radix [PPC] + Disable RADIX MMU mode on POWER9 + + disable_cpu_apicid= [X86,APIC,SMP] + Format: + The number of initial APIC ID for the + corresponding CPU to be disabled at boot, + mostly used for the kdump 2nd kernel to + disable BSP to wake up multiple CPUs without + causing system reset or hang due to sending + INIT from AP to BSP. + + disable_ddw [PPC/PSERIES] + Disable Dynamic DMA Window support. Use this if + to workaround buggy firmware. + + disable_ipv6= [IPV6] + See Documentation/networking/ipv6.txt. + + disable_mtrr_cleanup [X86] + The kernel tries to adjust MTRR layout from continuous + to discrete, to make X server driver able to add WB + entry later. This parameter disables that. + + disable_mtrr_trim [X86, Intel and AMD only] + By default the kernel will trim any uncacheable + memory out of your available memory pool based on + MTRR settings. This parameter disables that behavior, + possibly causing your machine to run very slowly. + + disable_timer_pin_1 [X86] + Disable PIN 1 of APIC timer + Can be useful to work around chipset bugs. + + dis_ucode_ldr [X86] Disable the microcode loader. + + dma_debug=off If the kernel is compiled with DMA_API_DEBUG support, + this option disables the debugging code at boot. + + dma_debug_entries= + This option allows to tune the number of preallocated + entries for DMA-API debugging code. One entry is + required per DMA-API allocation. Use this if the + DMA-API debugging code disables itself because the + architectural default is too low. + + dma_debug_driver= + With this option the DMA-API debugging driver + filter feature can be enabled at boot time. Just + pass the driver to filter for as the parameter. + The filter can be disabled or changed to another + driver later using sysfs. + + drm_kms_helper.edid_firmware=[:][,[:]] + Broken monitors, graphic adapters, KVMs and EDIDless + panels may send no or incorrect EDID data sets. + This parameter allows to specify an EDID data sets + in the /lib/firmware directory that are used instead. + Generic built-in EDID data sets are used, if one of + edid/1024x768.bin, edid/1280x1024.bin, + edid/1680x1050.bin, or edid/1920x1080.bin is given + and no file with the same name exists. Details and + instructions how to build your own EDID data are + available in Documentation/EDID/HOWTO.txt. An EDID + data set will only be used for a particular connector, + if its name and a colon are prepended to the EDID + name. Each connector may use a unique EDID data + set by separating the files with a comma. An EDID + data set with no connector name will be used for + any connectors not explicitly specified. + + dscc4.setup= [NET] + + dyndbg[="val"] [KNL,DYNAMIC_DEBUG] + module.dyndbg[="val"] + Enable debug messages at boot time. See + Documentation/dynamic-debug-howto.txt for details. + + nompx [X86] Disables Intel Memory Protection Extensions. + See Documentation/x86/intel_mpx.txt for more + information about the feature. + + nopku [X86] Disable Memory Protection Keys CPU feature found + in some Intel CPUs. + + eagerfpu= [X86] + on enable eager fpu restore + off disable eager fpu restore + auto selects the default scheme, which automatically + enables eagerfpu restore for xsaveopt. + + module.async_probe [KNL] + Enable asynchronous probe on this module. + + early_ioremap_debug [KNL] + Enable debug messages in early_ioremap support. This + is useful for tracking down temporary early mappings + which are not unmapped. + + earlycon= [KNL] Output early console device and options. + + When used with no options, the early console is + determined by the stdout-path property in device + tree's chosen node. + + cdns,[,options] + Start an early, polled-mode console on a Cadence + (xuartps) serial port at the specified address. Only + supported option is baud rate. If baud rate is not + specified, the serial port must already be setup and + configured. + + uart[8250],io,[,options] + uart[8250],mmio,[,options] + uart[8250],mmio32,[,options] + uart[8250],mmio32be,[,options] + uart[8250],0x[,options] + Start an early, polled-mode console on the 8250/16550 + UART at the specified I/O port or MMIO address. + MMIO inter-register address stride is either 8-bit + (mmio) or 32-bit (mmio32 or mmio32be). + If none of [io|mmio|mmio32|mmio32be], is assumed + to be equivalent to 'mmio'. 'options' are specified + in the same format described for "console=ttyS"; if + unspecified, the h/w is not initialized. + + pl011, + pl011,mmio32, + Start an early, polled-mode console on a pl011 serial + port at the specified address. The pl011 serial port + must already be setup and configured. Options are not + yet supported. If 'mmio32' is specified, then only + the driver will use only 32-bit accessors to read/write + the device registers. + + meson, + Start an early, polled-mode console on a meson serial + port at the specified address. The serial port must + already be setup and configured. Options are not yet + supported. + + msm_serial, + Start an early, polled-mode console on an msm serial + port at the specified address. The serial port + must already be setup and configured. Options are not + yet supported. + + msm_serial_dm, + Start an early, polled-mode console on an msm serial + dm port at the specified address. The serial port + must already be setup and configured. Options are not + yet supported. + + smh Use ARM semihosting calls for early console. + + s3c2410, + s3c2412, + s3c2440, + s3c6400, + s5pv210, + exynos4210, + Use early console provided by serial driver available + on Samsung SoCs, requires selecting proper type and + a correct base address of the selected UART port. The + serial port must already be setup and configured. + Options are not yet supported. + + lpuart, + lpuart32, + Use early console provided by Freescale LP UART driver + found on Freescale Vybrid and QorIQ LS1021A processors. + A valid base address must be provided, and the serial + port must already be setup and configured. + + armada3700_uart, + Start an early, polled-mode console on the + Armada 3700 serial port at the specified + address. The serial port must already be setup + and configured. Options are not yet supported. + + earlyprintk= [X86,SH,BLACKFIN,ARM,M68k] + earlyprintk=vga + earlyprintk=efi + earlyprintk=xen + earlyprintk=serial[,ttySn[,baudrate]] + earlyprintk=serial[,0x...[,baudrate]] + earlyprintk=ttySn[,baudrate] + earlyprintk=dbgp[debugController#] + earlyprintk=pciserial,bus:device.function[,baudrate] + + earlyprintk is useful when the kernel crashes before + the normal console is initialized. It is not enabled by + default because it has some cosmetic problems. + + Append ",keep" to not disable it when the real console + takes over. + + Only one of vga, efi, serial, or usb debug port can + be used at a time. + + Currently only ttyS0 and ttyS1 may be specified by + name. Other I/O ports may be explicitly specified + on some architectures (x86 and arm at least) by + replacing ttySn with an I/O port address, like this: + earlyprintk=serial,0x1008,115200 + You can find the port for a given device in + /proc/tty/driver/serial: + 2: uart:ST16650V2 port:00001008 irq:18 ... + + Interaction with the standard serial driver is not + very good. + + The VGA and EFI output is eventually overwritten by + the real console. + + The xen output can only be used by Xen PV guests. + + edac_report= [HW,EDAC] Control how to report EDAC event + Format: {"on" | "off" | "force"} + on: enable EDAC to report H/W event. May be overridden + by other higher priority error reporting module. + off: disable H/W event reporting through EDAC. + force: enforce the use of EDAC to report H/W event. + default: on. + + ekgdboc= [X86,KGDB] Allow early kernel console debugging + ekgdboc=kbd + + This is designed to be used in conjunction with + the boot argument: earlyprintk=vga + + edd= [EDD] + Format: {"off" | "on" | "skip[mbr]"} + + efi= [EFI] + Format: { "old_map", "nochunk", "noruntime", "debug" } + old_map [X86-64]: switch to the old ioremap-based EFI + runtime services mapping. 32-bit still uses this one by + default. + nochunk: disable reading files in "chunks" in the EFI + boot stub, as chunking can cause problems with some + firmware implementations. + noruntime : disable EFI runtime services support + debug: enable misc debug output + + efi_no_storage_paranoia [EFI; X86] + Using this parameter you can use more than 50% of + your efi variable storage. Use this parameter only if + you are really sure that your UEFI does sane gc and + fulfills the spec otherwise your board may brick. + + efi_fake_mem= nn[KMG]@ss[KMG]:aa[,nn[KMG]@ss[KMG]:aa,..] [EFI; X86] + Add arbitrary attribute to specific memory range by + updating original EFI memory map. + Region of memory which aa attribute is added to is + from ss to ss+nn. + If efi_fake_mem=2G@4G:0x10000,2G@0x10a0000000:0x10000 + is specified, EFI_MEMORY_MORE_RELIABLE(0x10000) + attribute is added to range 0x100000000-0x180000000 and + 0x10a0000000-0x1120000000. + + Using this parameter you can do debugging of EFI memmap + related feature. For example, you can do debugging of + Address Range Mirroring feature even if your box + doesn't support it. + + efivar_ssdt= [EFI; X86] Name of an EFI variable that contains an SSDT + that is to be dynamically loaded by Linux. If there are + multiple variables with the same name but with different + vendor GUIDs, all of them will be loaded. See + Documentation/acpi/ssdt-overlays.txt for details. + + + eisa_irq_edge= [PARISC,HW] + See header of drivers/parisc/eisa.c. + + elanfreq= [X86-32] + See comment before function elanfreq_setup() in + arch/x86/kernel/cpu/cpufreq/elanfreq.c. + + elevator= [IOSCHED] + Format: {"cfq" | "deadline" | "noop"} + See Documentation/block/cfq-iosched.txt and + Documentation/block/deadline-iosched.txt for details. + + elfcorehdr=[size[KMG]@]offset[KMG] [IA64,PPC,SH,X86,S390] + Specifies physical address of start of kernel core + image elf header and optionally the size. Generally + kexec loader will pass this option to capture kernel. + See Documentation/kdump/kdump.txt for details. + + enable_mtrr_cleanup [X86] + The kernel tries to adjust MTRR layout from continuous + to discrete, to make X server driver able to add WB + entry later. This parameter enables that. + + enable_timer_pin_1 [X86] + Enable PIN 1 of APIC timer + Can be useful to work around chipset bugs + (in particular on some ATI chipsets). + The kernel tries to set a reasonable default. + + enforcing [SELINUX] Set initial enforcing status. + Format: {"0" | "1"} + See security/selinux/Kconfig help text. + 0 -- permissive (log only, no denials). + 1 -- enforcing (deny and log). + Default value is 0. + Value can be changed at runtime via /selinux/enforce. + + erst_disable [ACPI] + Disable Error Record Serialization Table (ERST) + support. + + ether= [HW,NET] Ethernet cards parameters + This option is obsoleted by the "netdev=" option, which + has equivalent usage. See its documentation for details. + + evm= [EVM] + Format: { "fix" } + Permit 'security.evm' to be updated regardless of + current integrity status. + + failslab= + fail_page_alloc= + fail_make_request=[KNL] + General fault injection mechanism. + Format: ,,, + See also Documentation/fault-injection/. + + floppy= [HW] + See Documentation/blockdev/floppy.txt. + + force_pal_cache_flush + [IA-64] Avoid check_sal_cache_flush which may hang on + buggy SAL_CACHE_FLUSH implementations. Using this + parameter will force ia64_sal_cache_flush to call + ia64_pal_cache_flush instead of SAL_CACHE_FLUSH. + + forcepae [X86-32] + Forcefully enable Physical Address Extension (PAE). + Many Pentium M systems disable PAE but may have a + functionally usable PAE implementation. + Warning: use of this parameter will taint the kernel + and may cause unknown problems. + + ftrace=[tracer] + [FTRACE] will set and start the specified tracer + as early as possible in order to facilitate early + boot debugging. + + ftrace_dump_on_oops[=orig_cpu] + [FTRACE] will dump the trace buffers on oops. + If no parameter is passed, ftrace will dump + buffers of all CPUs, but if you pass orig_cpu, it will + dump only the buffer of the CPU that triggered the + oops. + + ftrace_filter=[function-list] + [FTRACE] Limit the functions traced by the function + tracer at boot up. function-list is a comma separated + list of functions. This list can be changed at run + time by the set_ftrace_filter file in the debugfs + tracing directory. + + ftrace_notrace=[function-list] + [FTRACE] Do not trace the functions specified in + function-list. This list can be changed at run time + by the set_ftrace_notrace file in the debugfs + tracing directory. + + ftrace_graph_filter=[function-list] + [FTRACE] Limit the top level callers functions traced + by the function graph tracer at boot up. + function-list is a comma separated list of functions + that can be changed at run time by the + set_graph_function file in the debugfs tracing directory. + + ftrace_graph_notrace=[function-list] + [FTRACE] Do not trace from the functions specified in + function-list. This list is a comma separated list of + functions that can be changed at run time by the + set_graph_notrace file in the debugfs tracing directory. + + gamecon.map[2|3]= + [HW,JOY] Multisystem joystick and NES/SNES/PSX pad + support via parallel port (up to 5 devices per port) + Format: ,,,,, + See also Documentation/input/joystick-parport.txt + + gamma= [HW,DRM] + + gart_fix_e820= [X86_64] disable the fix e820 for K8 GART + Format: off | on + default: on + + gcov_persist= [GCOV] When non-zero (default), profiling data for + kernel modules is saved and remains accessible via + debugfs, even when the module is unloaded/reloaded. + When zero, profiling data is discarded and associated + debugfs files are removed at module unload time. + + gpt [EFI] Forces disk with valid GPT signature but + invalid Protective MBR to be treated as GPT. If the + primary GPT is corrupted, it enables the backup/alternate + GPT to be used instead. + + grcan.enable0= [HW] Configuration of physical interface 0. Determines + the "Enable 0" bit of the configuration register. + Format: 0 | 1 + Default: 0 + grcan.enable1= [HW] Configuration of physical interface 1. Determines + the "Enable 0" bit of the configuration register. + Format: 0 | 1 + Default: 0 + grcan.select= [HW] Select which physical interface to use. + Format: 0 | 1 + Default: 0 + grcan.txsize= [HW] Sets the size of the tx buffer. + Format: such that (txsize & ~0x1fffc0) == 0. + Default: 1024 + grcan.rxsize= [HW] Sets the size of the rx buffer. + Format: such that (rxsize & ~0x1fffc0) == 0. + Default: 1024 + + gpio-mockup.gpio_mockup_ranges + [HW] Sets the ranges of gpiochip of for this device. + Format: ,,,... + + hardlockup_all_cpu_backtrace= + [KNL] Should the hard-lockup detector generate + backtraces on all cpus. + Format: + + hashdist= [KNL,NUMA] Large hashes allocated during boot + are distributed across NUMA nodes. Defaults on + for 64-bit NUMA, off otherwise. + Format: 0 | 1 (for off | on) + + hcl= [IA-64] SGI's Hardware Graph compatibility layer + + hd= [EIDE] (E)IDE hard drive subsystem geometry + Format: ,, + + hest_disable [ACPI] + Disable Hardware Error Source Table (HEST) support; + corresponding firmware-first mode error processing + logic will be disabled. + + highmem=nn[KMG] [KNL,BOOT] forces the highmem zone to have an exact + size of . This works even on boxes that have no + highmem otherwise. This also works to reduce highmem + size on bigger boxes. + + highres= [KNL] Enable/disable high resolution timer mode. + Valid parameters: "on", "off" + Default: "on" + + hisax= [HW,ISDN] + See Documentation/isdn/README.HiSax. + + hlt [BUGS=ARM,SH] + + hpet= [X86-32,HPET] option to control HPET usage + Format: { enable (default) | disable | force | + verbose } + disable: disable HPET and use PIT instead + force: allow force enabled of undocumented chips (ICH4, + VIA, nVidia) + verbose: show contents of HPET registers during setup + + hpet_mmap= [X86, HPET_MMAP] Allow userspace to mmap HPET + registers. Default set by CONFIG_HPET_MMAP_DEFAULT. + + hugepages= [HW,X86-32,IA-64] HugeTLB pages to allocate at boot. + hugepagesz= [HW,IA-64,PPC,X86-64] The size of the HugeTLB pages. + On x86-64 and powerpc, this option can be specified + multiple times interleaved with hugepages= to reserve + huge pages of different sizes. Valid pages sizes on + x86-64 are 2M (when the CPU supports "pse") and 1G + (when the CPU supports the "pdpe1gb" cpuinfo flag). + + hvc_iucv= [S390] Number of z/VM IUCV hypervisor console (HVC) + terminal devices. Valid values: 0..8 + hvc_iucv_allow= [S390] Comma-separated list of z/VM user IDs. + If specified, z/VM IUCV HVC accepts connections + from listed z/VM user IDs only. + + hwthread_map= [METAG] Comma-separated list of Linux cpu id to + hardware thread id mappings. + Format: : + + keep_bootcon [KNL] + Do not unregister boot console at start. This is only + useful for debugging when something happens in the window + between unregistering the boot console and initializing + the real console. + + i2c_bus= [HW] Override the default board specific I2C bus speed + or register an additional I2C bus that is not + registered from board initialization code. + Format: + , + + i8042.debug [HW] Toggle i8042 debug mode + i8042.unmask_kbd_data + [HW] Enable printing of interrupt data from the KBD port + (disabled by default, and as a pre-condition + requires that i8042.debug=1 be enabled) + i8042.direct [HW] Put keyboard port into non-translated mode + i8042.dumbkbd [HW] Pretend that controller can only read data from + keyboard and cannot control its state + (Don't attempt to blink the leds) + i8042.noaux [HW] Don't check for auxiliary (== mouse) port + i8042.nokbd [HW] Don't check/create keyboard port + i8042.noloop [HW] Disable the AUX Loopback command while probing + for the AUX port + i8042.nomux [HW] Don't check presence of an active multiplexing + controller + i8042.nopnp [HW] Don't use ACPIPnP / PnPBIOS to discover KBD/AUX + controllers + i8042.notimeout [HW] Ignore timeout condition signalled by controller + i8042.reset [HW] Reset the controller during init, cleanup and + suspend-to-ram transitions, only during s2r + transitions, or never reset + Format: { 1 | Y | y | 0 | N | n } + 1, Y, y: always reset controller + 0, N, n: don't ever reset controller + Default: only on s2r transitions on x86; most other + architectures force reset to be always executed + i8042.unlock [HW] Unlock (ignore) the keylock + i8042.kbdreset [HW] Reset device connected to KBD port + + i810= [HW,DRM] + + i8k.ignore_dmi [HW] Continue probing hardware even if DMI data + indicates that the driver is running on unsupported + hardware. + i8k.force [HW] Activate i8k driver even if SMM BIOS signature + does not match list of supported models. + i8k.power_status + [HW] Report power status in /proc/i8k + (disabled by default) + i8k.restricted [HW] Allow controlling fans only if SYS_ADMIN + capability is set. + + i915.invert_brightness= + [DRM] Invert the sense of the variable that is used to + set the brightness of the panel backlight. Normally a + brightness value of 0 indicates backlight switched off, + and the maximum of the brightness value sets the backlight + to maximum brightness. If this parameter is set to 0 + (default) and the machine requires it, or this parameter + is set to 1, a brightness value of 0 sets the backlight + to maximum brightness, and the maximum of the brightness + value switches the backlight off. + -1 -- never invert brightness + 0 -- machine default + 1 -- force brightness inversion + + icn= [HW,ISDN] + Format: [,[,[,]]] + + ide-core.nodma= [HW] (E)IDE subsystem + Format: =0.0 to prevent dma on hda, =0.1 hdb =1.0 hdc + .vlb_clock .pci_clock .noflush .nohpa .noprobe .nowerr + .cdrom .chs .ignore_cable are additional options + See Documentation/ide/ide.txt. + + ide-generic.probe-mask= [HW] (E)IDE subsystem + Format: + Probe mask for legacy ISA IDE ports. Depending on + platform up to 6 ports are supported, enabled by + setting corresponding bits in the mask to 1. The + default value is 0x0, which has a special meaning. + On systems that have PCI, it triggers scanning the + PCI bus for the first and the second port, which + are then probed. On systems without PCI the value + of 0x0 enables probing the two first ports as if it + was 0x3. + + ide-pci-generic.all-generic-ide [HW] (E)IDE subsystem + Claim all unknown PCI IDE storage controllers. + + idle= [X86] + Format: idle=poll, idle=halt, idle=nomwait + Poll forces a polling idle loop that can slightly + improve the performance of waking up a idle CPU, but + will use a lot of power and make the system run hot. + Not recommended. + idle=halt: Halt is forced to be used for CPU idle. + In such case C2/C3 won't be used again. + idle=nomwait: Disable mwait for CPU C-states + + ieee754= [MIPS] Select IEEE Std 754 conformance mode + Format: { strict | legacy | 2008 | relaxed } + Default: strict + + Choose which programs will be accepted for execution + based on the IEEE 754 NaN encoding(s) supported by + the FPU and the NaN encoding requested with the value + of an ELF file header flag individually set by each + binary. Hardware implementations are permitted to + support either or both of the legacy and the 2008 NaN + encoding mode. + + Available settings are as follows: + strict accept binaries that request a NaN encoding + supported by the FPU + legacy only accept legacy-NaN binaries, if supported + by the FPU + 2008 only accept 2008-NaN binaries, if supported + by the FPU + relaxed accept any binaries regardless of whether + supported by the FPU + + The FPU emulator is always able to support both NaN + encodings, so if no FPU hardware is present or it has + been disabled with 'nofpu', then the settings of + 'legacy' and '2008' strap the emulator accordingly, + 'relaxed' straps the emulator for both legacy-NaN and + 2008-NaN, whereas 'strict' enables legacy-NaN only on + legacy processors and both NaN encodings on MIPS32 or + MIPS64 CPUs. + + The setting for ABS.fmt/NEG.fmt instruction execution + mode generally follows that for the NaN encoding, + except where unsupported by hardware. + + ignore_loglevel [KNL] + Ignore loglevel setting - this will print /all/ + kernel messages to the console. Useful for debugging. + We also add it as printk module parameter, so users + could change it dynamically, usually by + /sys/module/printk/parameters/ignore_loglevel. + + ignore_rlimit_data + Ignore RLIMIT_DATA setting for data mappings, + print warning at first misuse. Can be changed via + /sys/module/kernel/parameters/ignore_rlimit_data. + + ihash_entries= [KNL] + Set number of hash buckets for inode cache. + + ima_appraise= [IMA] appraise integrity measurements + Format: { "off" | "enforce" | "fix" | "log" } + default: "enforce" + + ima_appraise_tcb [IMA] + The builtin appraise policy appraises all files + owned by uid=0. + + ima_hash= [IMA] + Format: { md5 | sha1 | rmd160 | sha256 | sha384 + | sha512 | ... } + default: "sha1" + + The list of supported hash algorithms is defined + in crypto/hash_info.h. + + ima_policy= [IMA] + The builtin measurement policy to load during IMA + setup. Specyfing "tcb" as the value, measures all + programs exec'd, files mmap'd for exec, and all files + opened with the read mode bit set by either the + effective uid (euid=0) or uid=0. + Format: "tcb" + + ima_tcb [IMA] Deprecated. Use ima_policy= instead. + Load a policy which meets the needs of the Trusted + Computing Base. This means IMA will measure all + programs exec'd, files mmap'd for exec, and all files + opened for read by uid=0. + + ima_template= [IMA] + Select one of defined IMA measurements template formats. + Formats: { "ima" | "ima-ng" | "ima-sig" } + Default: "ima-ng" + + ima_template_fmt= + [IMA] Define a custom template format. + Format: { "field1|...|fieldN" } + + ima.ahash_minsize= [IMA] Minimum file size for asynchronous hash usage + Format: + Set the minimal file size for using asynchronous hash. + If left unspecified, ahash usage is disabled. + + ahash performance varies for different data sizes on + different crypto accelerators. This option can be used + to achieve the best performance for a particular HW. + + ima.ahash_bufsize= [IMA] Asynchronous hash buffer size + Format: + Set hashing buffer size. Default: 4k. + + ahash performance varies for different chunk sizes on + different crypto accelerators. This option can be used + to achieve best performance for particular HW. + + init= [KNL] + Format: + Run specified binary instead of /sbin/init as init + process. + + initcall_debug [KNL] Trace initcalls as they are executed. Useful + for working out where the kernel is dying during + startup. + + initcall_blacklist= [KNL] Do not execute a comma-separated list of + initcall functions. Useful for debugging built-in + modules and initcalls. + + initrd= [BOOT] Specify the location of the initial ramdisk + + init_pkru= [x86] Specify the default memory protection keys rights + register contents for all processes. 0x55555554 by + default (disallow access to all but pkey 0). Can + override in debugfs after boot. + + inport.irq= [HW] Inport (ATI XL and Microsoft) busmouse driver + Format: + + int_pln_enable [x86] Enable power limit notification interrupt + + integrity_audit=[IMA] + Format: { "0" | "1" } + 0 -- basic integrity auditing messages. (Default) + 1 -- additional integrity auditing messages. + + intel_iommu= [DMAR] Intel IOMMU driver (DMAR) option + on + Enable intel iommu driver. + off + Disable intel iommu driver. + igfx_off [Default Off] + By default, gfx is mapped as normal device. If a gfx + device has a dedicated DMAR unit, the DMAR unit is + bypassed by not enabling DMAR with this option. In + this case, gfx device will use physical address for + DMA. + forcedac [x86_64] + With this option iommu will not optimize to look + for io virtual address below 32-bit forcing dual + address cycle on pci bus for cards supporting greater + than 32-bit addressing. The default is to look + for translation below 32-bit and if not available + then look in the higher range. + strict [Default Off] + With this option on every unmap_single operation will + result in a hardware IOTLB flush operation as opposed + to batching them for performance. + sp_off [Default Off] + By default, super page will be supported if Intel IOMMU + has the capability. With this option, super page will + not be supported. + ecs_off [Default Off] + By default, extended context tables will be supported if + the hardware advertises that it has support both for the + extended tables themselves, and also PASID support. With + this option set, extended tables will not be used even + on hardware which claims to support them. + + intel_idle.max_cstate= [KNL,HW,ACPI,X86] + 0 disables intel_idle and fall back on acpi_idle. + 1 to 9 specify maximum depth of C-state. + + intel_pstate= [X86] + disable + Do not enable intel_pstate as the default + scaling driver for the supported processors + force + Enable intel_pstate on systems that prohibit it by default + in favor of acpi-cpufreq. Forcing the intel_pstate driver + instead of acpi-cpufreq may disable platform features, such + as thermal controls and power capping, that rely on ACPI + P-States information being indicated to OSPM and therefore + should be used with caution. This option does not work with + processors that aren't supported by the intel_pstate driver + or on platforms that use pcc-cpufreq instead of acpi-cpufreq. + no_hwp + Do not enable hardware P state control (HWP) + if available. + hwp_only + Only load intel_pstate on systems which support + hardware P state control (HWP) if available. + support_acpi_ppc + Enforce ACPI _PPC performance limits. If the Fixed ACPI + Description Table, specifies preferred power management + profile as "Enterprise Server" or "Performance Server", + then this feature is turned on by default. + + intremap= [X86-64, Intel-IOMMU] + on enable Interrupt Remapping (default) + off disable Interrupt Remapping + nosid disable Source ID checking + no_x2apic_optout + BIOS x2APIC opt-out request will be ignored + nopost disable Interrupt Posting + + iomem= Disable strict checking of access to MMIO memory + strict regions from userspace. + relaxed + + iommu= [x86] + off + force + noforce + biomerge + panic + nopanic + merge + nomerge + forcesac + soft + pt [x86, IA-64] + nobypass [PPC/POWERNV] + Disable IOMMU bypass, using IOMMU for PCI devices. + + + io7= [HW] IO7 for Marvel based alpha systems + See comment before marvel_specify_io7 in + arch/alpha/kernel/core_marvel.c. + + io_delay= [X86] I/O delay method + 0x80 + Standard port 0x80 based delay + 0xed + Alternate port 0xed based delay (needed on some systems) + udelay + Simple two microseconds delay + none + No delay + + ip= [IP_PNP] + See Documentation/filesystems/nfs/nfsroot.txt. + + irqaffinity= [SMP] Set the default irq affinity mask + The argument is a cpu list, as described above. + + irqfixup [HW] + When an interrupt is not handled search all handlers + for it. Intended to get systems with badly broken + firmware running. + + irqpoll [HW] + When an interrupt is not handled search all handlers + for it. Also check all handlers each timer + interrupt. Intended to get systems with badly broken + firmware running. + + isapnp= [ISAPNP] + Format: ,,, + + isolcpus= [KNL,SMP] Isolate CPUs from the general scheduler. + The argument is a cpu list, as described above. + + This option can be used to specify one or more CPUs + to isolate from the general SMP balancing and scheduling + algorithms. You can move a process onto or off an + "isolated" CPU via the CPU affinity syscalls or cpuset. + begins at 0 and the maximum value is + "number of CPUs in system - 1". + + This option is the preferred way to isolate CPUs. The + alternative -- manually setting the CPU mask of all + tasks in the system -- can cause problems and + suboptimal load balancer performance. + + iucv= [HW,NET] + + ivrs_ioapic [HW,X86_64] + Provide an override to the IOAPIC-ID<->DEVICE-ID + mapping provided in the IVRS ACPI table. For + example, to map IOAPIC-ID decimal 10 to + PCI device 00:14.0 write the parameter as: + ivrs_ioapic[10]=00:14.0 + + ivrs_hpet [HW,X86_64] + Provide an override to the HPET-ID<->DEVICE-ID + mapping provided in the IVRS ACPI table. For + example, to map HPET-ID decimal 0 to + PCI device 00:14.0 write the parameter as: + ivrs_hpet[0]=00:14.0 + + ivrs_acpihid [HW,X86_64] + Provide an override to the ACPI-HID:UID<->DEVICE-ID + mapping provided in the IVRS ACPI table. For + example, to map UART-HID:UID AMD0020:0 to + PCI device 00:14.5 write the parameter as: + ivrs_acpihid[00:14.5]=AMD0020:0 + + js= [HW,JOY] Analog joystick + See Documentation/input/joystick.txt. + + nokaslr [KNL] + When CONFIG_RANDOMIZE_BASE is set, this disables + kernel and module base offset ASLR (Address Space + Layout Randomization). + + keepinitrd [HW,ARM] + + kernelcore= [KNL,X86,IA-64,PPC] + Format: nn[KMGTPE] | "mirror" + This parameter + specifies the amount of memory usable by the kernel + for non-movable allocations. The requested amount is + spread evenly throughout all nodes in the system. The + remaining memory in each node is used for Movable + pages. In the event, a node is too small to have both + kernelcore and Movable pages, kernelcore pages will + take priority and other nodes will have a larger number + of Movable pages. The Movable zone is used for the + allocation of pages that may be reclaimed or moved + by the page migration subsystem. This means that + HugeTLB pages may not be allocated from this zone. + Note that allocations like PTEs-from-HighMem still + use the HighMem zone if it exists, and the Normal + zone if it does not. + + Instead of specifying the amount of memory (nn[KMGTPE]), + you can specify "mirror" option. In case "mirror" + option is specified, mirrored (reliable) memory is used + for non-movable allocations and remaining memory is used + for Movable pages. nn[KMGTPE] and "mirror" are exclusive, + so you can NOT specify nn[KMGTPE] and "mirror" at the same + time. + + kgdbdbgp= [KGDB,HW] kgdb over EHCI usb debug port. + Format: [,poll interval] + The controller # is the number of the ehci usb debug + port as it is probed via PCI. The poll interval is + optional and is the number seconds in between + each poll cycle to the debug port in case you need + the functionality for interrupting the kernel with + gdb or control-c on the dbgp connection. When + not using this parameter you use sysrq-g to break into + the kernel debugger. + + kgdboc= [KGDB,HW] kgdb over consoles. + Requires a tty driver that supports console polling, + or a supported polling keyboard driver (non-usb). + Serial only format: [,baud] + keyboard only format: kbd + keyboard and serial format: kbd,[,baud] + Optional Kernel mode setting: + kms, kbd format: kms,kbd + kms, kbd and serial format: kms,kbd,[,baud] + + kgdbwait [KGDB] Stop kernel execution and enter the + kernel debugger at the earliest opportunity. + + kmac= [MIPS] korina ethernet MAC address. + Configure the RouterBoard 532 series on-chip + Ethernet adapter MAC address. + + kmemleak= [KNL] Boot-time kmemleak enable/disable + Valid arguments: on, off + Default: on + Built with CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF=y, + the default is off. + + kmemcheck= [X86] Boot-time kmemcheck enable/disable/one-shot mode + Valid arguments: 0, 1, 2 + kmemcheck=0 (disabled) + kmemcheck=1 (enabled) + kmemcheck=2 (one-shot mode) + Default: 2 (one-shot mode) + + kstack=N [X86] Print N words from the kernel stack + in oops dumps. + + kvm.ignore_msrs=[KVM] Ignore guest accesses to unhandled MSRs. + Default is 0 (don't ignore, but inject #GP) + + kvm.mmu_audit= [KVM] This is a R/W parameter which allows audit + KVM MMU at runtime. + Default is 0 (off) + + kvm-amd.nested= [KVM,AMD] Allow nested virtualization in KVM/SVM. + Default is 1 (enabled) + + kvm-amd.npt= [KVM,AMD] Disable nested paging (virtualized MMU) + for all guests. + Default is 1 (enabled) if in 64-bit or 32-bit PAE mode. + + kvm-intel.ept= [KVM,Intel] Disable extended page tables + (virtualized MMU) support on capable Intel chips. + Default is 1 (enabled) + + kvm-intel.emulate_invalid_guest_state= + [KVM,Intel] Enable emulation of invalid guest states + Default is 0 (disabled) + + kvm-intel.flexpriority= + [KVM,Intel] Disable FlexPriority feature (TPR shadow). + Default is 1 (enabled) + + kvm-intel.nested= + [KVM,Intel] Enable VMX nesting (nVMX). + Default is 0 (disabled) + + kvm-intel.unrestricted_guest= + [KVM,Intel] Disable unrestricted guest feature + (virtualized real and unpaged mode) on capable + Intel chips. Default is 1 (enabled) + + kvm-intel.vpid= [KVM,Intel] Disable Virtual Processor Identification + feature (tagged TLBs) on capable Intel chips. + Default is 1 (enabled) + + l2cr= [PPC] + + l3cr= [PPC] + + lapic [X86-32,APIC] Enable the local APIC even if BIOS + disabled it. + + lapic= [x86,APIC] "notscdeadline" Do not use TSC deadline + value for LAPIC timer one-shot implementation. Default + back to the programmable timer unit in the LAPIC. + + lapic_timer_c2_ok [X86,APIC] trust the local apic timer + in C2 power state. + + libata.dma= [LIBATA] DMA control + libata.dma=0 Disable all PATA and SATA DMA + libata.dma=1 PATA and SATA Disk DMA only + libata.dma=2 ATAPI (CDROM) DMA only + libata.dma=4 Compact Flash DMA only + Combinations also work, so libata.dma=3 enables DMA + for disks and CDROMs, but not CFs. + + libata.ignore_hpa= [LIBATA] Ignore HPA limit + libata.ignore_hpa=0 keep BIOS limits (default) + libata.ignore_hpa=1 ignore limits, using full disk + + libata.noacpi [LIBATA] Disables use of ACPI in libata suspend/resume + when set. + Format: + + libata.force= [LIBATA] Force configurations. The format is comma + separated list of "[ID:]VAL" where ID is + PORT[.DEVICE]. PORT and DEVICE are decimal numbers + matching port, link or device. Basically, it matches + the ATA ID string printed on console by libata. If + the whole ID part is omitted, the last PORT and DEVICE + values are used. If ID hasn't been specified yet, the + configuration applies to all ports, links and devices. + + If only DEVICE is omitted, the parameter applies to + the port and all links and devices behind it. DEVICE + number of 0 either selects the first device or the + first fan-out link behind PMP device. It does not + select the host link. DEVICE number of 15 selects the + host link and device attached to it. + + The VAL specifies the configuration to force. As long + as there's no ambiguity shortcut notation is allowed. + For example, both 1.5 and 1.5G would work for 1.5Gbps. + The following configurations can be forced. + + * Cable type: 40c, 80c, short40c, unk, ign or sata. + Any ID with matching PORT is used. + + * SATA link speed limit: 1.5Gbps or 3.0Gbps. + + * Transfer mode: pio[0-7], mwdma[0-4] and udma[0-7]. + udma[/][16,25,33,44,66,100,133] notation is also + allowed. + + * [no]ncq: Turn on or off NCQ. + + * [no]ncqtrim: Turn off queued DSM TRIM. + + * nohrst, nosrst, norst: suppress hard, soft + and both resets. + + * rstonce: only attempt one reset during + hot-unplug link recovery + + * dump_id: dump IDENTIFY data. + + * atapi_dmadir: Enable ATAPI DMADIR bridge support + + * disable: Disable this device. + + If there are multiple matching configurations changing + the same attribute, the last one is used. + + memblock=debug [KNL] Enable memblock debug messages. + + load_ramdisk= [RAM] List of ramdisks to load from floppy + See Documentation/blockdev/ramdisk.txt. + + lockd.nlm_grace_period=P [NFS] Assign grace period. + Format: + + lockd.nlm_tcpport=N [NFS] Assign TCP port. + Format: + + lockd.nlm_timeout=T [NFS] Assign timeout value. + Format: + + lockd.nlm_udpport=M [NFS] Assign UDP port. + Format: + + locktorture.nreaders_stress= [KNL] + Set the number of locking read-acquisition kthreads. + Defaults to being automatically set based on the + number of online CPUs. + + locktorture.nwriters_stress= [KNL] + Set the number of locking write-acquisition kthreads. + + locktorture.onoff_holdoff= [KNL] + Set time (s) after boot for CPU-hotplug testing. + + locktorture.onoff_interval= [KNL] + Set time (s) between CPU-hotplug operations, or + zero to disable CPU-hotplug testing. + + locktorture.shuffle_interval= [KNL] + Set task-shuffle interval (jiffies). Shuffling + tasks allows some CPUs to go into dyntick-idle + mode during the locktorture test. + + locktorture.shutdown_secs= [KNL] + Set time (s) after boot system shutdown. This + is useful for hands-off automated testing. + + locktorture.stat_interval= [KNL] + Time (s) between statistics printk()s. + + locktorture.stutter= [KNL] + Time (s) to stutter testing, for example, + specifying five seconds causes the test to run for + five seconds, wait for five seconds, and so on. + This tests the locking primitive's ability to + transition abruptly to and from idle. + + locktorture.torture_runnable= [BOOT] + Start locktorture running at boot time. + + locktorture.torture_type= [KNL] + Specify the locking implementation to test. + + locktorture.verbose= [KNL] + Enable additional printk() statements. + + logibm.irq= [HW,MOUSE] Logitech Bus Mouse Driver + Format: + + loglevel= All Kernel Messages with a loglevel smaller than the + console loglevel will be printed to the console. It can + also be changed with klogd or other programs. The + loglevels are defined as follows: + + 0 (KERN_EMERG) system is unusable + 1 (KERN_ALERT) action must be taken immediately + 2 (KERN_CRIT) critical conditions + 3 (KERN_ERR) error conditions + 4 (KERN_WARNING) warning conditions + 5 (KERN_NOTICE) normal but significant condition + 6 (KERN_INFO) informational + 7 (KERN_DEBUG) debug-level messages + + log_buf_len=n[KMG] Sets the size of the printk ring buffer, + in bytes. n must be a power of two and greater + than the minimal size. The minimal size is defined + by LOG_BUF_SHIFT kernel config parameter. There is + also CONFIG_LOG_CPU_MAX_BUF_SHIFT config parameter + that allows to increase the default size depending on + the number of CPUs. See init/Kconfig for more details. + + logo.nologo [FB] Disables display of the built-in Linux logo. + This may be used to provide more screen space for + kernel log messages and is useful when debugging + kernel boot problems. + + lp=0 [LP] Specify parallel ports to use, e.g, + lp=port[,port...] lp=none,parport0 (lp0 not configured, lp1 uses + lp=reset first parallel port). 'lp=0' disables the + lp=auto printer driver. 'lp=reset' (which can be + specified in addition to the ports) causes + attached printers to be reset. Using + lp=port1,port2,... specifies the parallel ports + to associate lp devices with, starting with + lp0. A port specification may be 'none' to skip + that lp device, or a parport name such as + 'parport0'. Specifying 'lp=auto' instead of a + port specification list means that device IDs + from each port should be examined, to see if + an IEEE 1284-compliant printer is attached; if + so, the driver will manage that printer. + See also header of drivers/char/lp.c. + + lpj=n [KNL] + Sets loops_per_jiffy to given constant, thus avoiding + time-consuming boot-time autodetection (up to 250 ms per + CPU). 0 enables autodetection (default). To determine + the correct value for your kernel, boot with normal + autodetection and see what value is printed. Note that + on SMP systems the preset will be applied to all CPUs, + which is likely to cause problems if your CPUs need + significantly divergent settings. An incorrect value + will cause delays in the kernel to be wrong, leading to + unpredictable I/O errors and other breakage. Although + unlikely, in the extreme case this might damage your + hardware. + + ltpc= [NET] + Format: ,, + + machvec= [IA-64] Force the use of a particular machine-vector + (machvec) in a generic kernel. + Example: machvec=hpzx1_swiotlb + + machtype= [Loongson] Share the same kernel image file between different + yeeloong laptop. + Example: machtype=lemote-yeeloong-2f-7inch + + max_addr=nn[KMG] [KNL,BOOT,ia64] All physical memory greater + than or equal to this physical address is ignored. + + maxcpus= [SMP] Maximum number of processors that an SMP kernel + will bring up during bootup. maxcpus=n : n >= 0 limits + the kernel to bring up 'n' processors. Surely after + bootup you can bring up the other plugged cpu by executing + "echo 1 > /sys/devices/system/cpu/cpuX/online". So maxcpus + only takes effect during system bootup. + While n=0 is a special case, it is equivalent to "nosmp", + which also disables the IO APIC. + + max_loop= [LOOP] The number of loop block devices that get + (loop.max_loop) unconditionally pre-created at init time. The default + number is configured by BLK_DEV_LOOP_MIN_COUNT. Instead + of statically allocating a predefined number, loop + devices can be requested on-demand with the + /dev/loop-control interface. + + mce [X86-32] Machine Check Exception + + mce=option [X86-64] See Documentation/x86/x86_64/boot-options.txt + + md= [HW] RAID subsystems devices and level + See Documentation/admin-guide/md.rst. + + mdacon= [MDA] + Format: , + Specifies range of consoles to be captured by the MDA. + + mem=nn[KMG] [KNL,BOOT] Force usage of a specific amount of memory + Amount of memory to be used when the kernel is not able + to see the whole system memory or for test. + [X86] Work as limiting max address. Use together + with memmap= to avoid physical address space collisions. + Without memmap= PCI devices could be placed at addresses + belonging to unused RAM. + + mem=nopentium [BUGS=X86-32] Disable usage of 4MB pages for kernel + memory. + + memchunk=nn[KMG] + [KNL,SH] Allow user to override the default size for + per-device physically contiguous DMA buffers. + + memhp_default_state=online/offline + [KNL] Set the initial state for the memory hotplug + onlining policy. If not specified, the default value is + set according to the + CONFIG_MEMORY_HOTPLUG_DEFAULT_ONLINE kernel config + option. + See Documentation/memory-hotplug.txt. + + memmap=exactmap [KNL,X86] Enable setting of an exact + E820 memory map, as specified by the user. + Such memmap=exactmap lines can be constructed based on + BIOS output or other requirements. See the memmap=nn@ss + option description. + + memmap=nn[KMG]@ss[KMG] + [KNL] Force usage of a specific region of memory. + Region of memory to be used is from ss to ss+nn. + + memmap=nn[KMG]#ss[KMG] + [KNL,ACPI] Mark specific memory as ACPI data. + Region of memory to be marked is from ss to ss+nn. + + memmap=nn[KMG]$ss[KMG] + [KNL,ACPI] Mark specific memory as reserved. + Region of memory to be reserved is from ss to ss+nn. + Example: Exclude memory from 0x18690000-0x1869ffff + memmap=64K$0x18690000 + or + memmap=0x10000$0x18690000 + + memmap=nn[KMG]!ss[KMG] + [KNL,X86] Mark specific memory as protected. + Region of memory to be used, from ss to ss+nn. + The memory region may be marked as e820 type 12 (0xc) + and is NVDIMM or ADR memory. + + memory_corruption_check=0/1 [X86] + Some BIOSes seem to corrupt the first 64k of + memory when doing things like suspend/resume. + Setting this option will scan the memory + looking for corruption. Enabling this will + both detect corruption and prevent the kernel + from using the memory being corrupted. + However, its intended as a diagnostic tool; if + repeatable BIOS-originated corruption always + affects the same memory, you can use memmap= + to prevent the kernel from using that memory. + + memory_corruption_check_size=size [X86] + By default it checks for corruption in the low + 64k, making this memory unavailable for normal + use. Use this parameter to scan for + corruption in more or less memory. + + memory_corruption_check_period=seconds [X86] + By default it checks for corruption every 60 + seconds. Use this parameter to check at some + other rate. 0 disables periodic checking. + + memtest= [KNL,X86,ARM] Enable memtest + Format: + default : 0 + Specifies the number of memtest passes to be + performed. Each pass selects another test + pattern from a given set of patterns. Memtest + fills the memory with this pattern, validates + memory contents and reserves bad memory + regions that are detected. + + meye.*= [HW] Set MotionEye Camera parameters + See Documentation/video4linux/meye.txt. + + mfgpt_irq= [IA-32] Specify the IRQ to use for the + Multi-Function General Purpose Timers on AMD Geode + platforms. + + mfgptfix [X86-32] Fix MFGPT timers on AMD Geode platforms when + the BIOS has incorrectly applied a workaround. TinyBIOS + version 0.98 is known to be affected, 0.99 fixes the + problem by letting the user disable the workaround. + + mga= [HW,DRM] + + min_addr=nn[KMG] [KNL,BOOT,ia64] All physical memory below this + physical address is ignored. + + mini2440= [ARM,HW,KNL] + Format:[0..2][b][c][t] + Default: "0tb" + MINI2440 configuration specification: + 0 - The attached screen is the 3.5" TFT + 1 - The attached screen is the 7" TFT + 2 - The VGA Shield is attached (1024x768) + Leaving out the screen size parameter will not load + the TFT driver, and the framebuffer will be left + unconfigured. + b - Enable backlight. The TFT backlight pin will be + linked to the kernel VESA blanking code and a GPIO + LED. This parameter is not necessary when using the + VGA shield. + c - Enable the s3c camera interface. + t - Reserved for enabling touchscreen support. The + touchscreen support is not enabled in the mainstream + kernel as of 2.6.30, a preliminary port can be found + in the "bleeding edge" mini2440 support kernel at + http://repo.or.cz/w/linux-2.6/mini2440.git + + mminit_loglevel= + [KNL] When CONFIG_DEBUG_MEMORY_INIT is set, this + parameter allows control of the logging verbosity for + the additional memory initialisation checks. A value + of 0 disables mminit logging and a level of 4 will + log everything. Information is printed at KERN_DEBUG + so loglevel=8 may also need to be specified. + + module.sig_enforce + [KNL] When CONFIG_MODULE_SIG is set, this means that + modules without (valid) signatures will fail to load. + Note that if CONFIG_MODULE_SIG_FORCE is set, that + is always true, so this option does nothing. + + module_blacklist= [KNL] Do not load a comma-separated list of + modules. Useful for debugging problem modules. + + mousedev.tap_time= + [MOUSE] Maximum time between finger touching and + leaving touchpad surface for touch to be considered + a tap and be reported as a left button click (for + touchpads working in absolute mode only). + Format: + mousedev.xres= [MOUSE] Horizontal screen resolution, used for devices + reporting absolute coordinates, such as tablets + mousedev.yres= [MOUSE] Vertical screen resolution, used for devices + reporting absolute coordinates, such as tablets + + movablecore=nn[KMG] [KNL,X86,IA-64,PPC] This parameter + is similar to kernelcore except it specifies the + amount of memory used for migratable allocations. + If both kernelcore and movablecore is specified, + then kernelcore will be at *least* the specified + value but may be more. If movablecore on its own + is specified, the administrator must be careful + that the amount of memory usable for all allocations + is not too small. + + movable_node [KNL,X86] Boot-time switch to enable the effects + of CONFIG_MOVABLE_NODE=y. See mm/Kconfig for details. + + MTD_Partition= [MTD] + Format: ,,, + + MTD_Region= [MTD] Format: + ,[,,,,] + + mtdparts= [MTD] + See drivers/mtd/cmdlinepart.c. + + multitce=off [PPC] This parameter disables the use of the pSeries + firmware feature for updating multiple TCE entries + at a time. + + onenand.bdry= [HW,MTD] Flex-OneNAND Boundary Configuration + + Format: [die0_boundary][,die0_lock][,die1_boundary][,die1_lock] + + boundary - index of last SLC block on Flex-OneNAND. + The remaining blocks are configured as MLC blocks. + lock - Configure if Flex-OneNAND boundary should be locked. + Once locked, the boundary cannot be changed. + 1 indicates lock status, 0 indicates unlock status. + + mtdset= [ARM] + ARM/S3C2412 JIVE boot control + + See arch/arm/mach-s3c2412/mach-jive.c + + mtouchusb.raw_coordinates= + [HW] Make the MicroTouch USB driver use raw coordinates + ('y', default) or cooked coordinates ('n') + + mtrr_chunk_size=nn[KMG] [X86] + used for mtrr cleanup. It is largest continuous chunk + that could hold holes aka. UC entries. + + mtrr_gran_size=nn[KMG] [X86] + Used for mtrr cleanup. It is granularity of mtrr block. + Default is 1. + Large value could prevent small alignment from + using up MTRRs. + + mtrr_spare_reg_nr=n [X86] + Format: + Range: 0,7 : spare reg number + Default : 1 + Used for mtrr cleanup. It is spare mtrr entries number. + Set to 2 or more if your graphical card needs more. + + n2= [NET] SDL Inc. RISCom/N2 synchronous serial card + + netdev= [NET] Network devices parameters + Format: ,,,, + Note that mem_start is often overloaded to mean + something different and driver-specific. + This usage is only documented in each driver source + file if at all. + + nf_conntrack.acct= + [NETFILTER] Enable connection tracking flow accounting + 0 to disable accounting + 1 to enable accounting + Default value is 0. + + nfsaddrs= [NFS] Deprecated. Use ip= instead. + See Documentation/filesystems/nfs/nfsroot.txt. + + nfsroot= [NFS] nfs root filesystem for disk-less boxes. + See Documentation/filesystems/nfs/nfsroot.txt. + + nfsrootdebug [NFS] enable nfsroot debugging messages. + See Documentation/filesystems/nfs/nfsroot.txt. + + nfs.callback_nr_threads= + [NFSv4] set the total number of threads that the + NFS client will assign to service NFSv4 callback + requests. + + nfs.callback_tcpport= + [NFS] set the TCP port on which the NFSv4 callback + channel should listen. + + nfs.cache_getent= + [NFS] sets the pathname to the program which is used + to update the NFS client cache entries. + + nfs.cache_getent_timeout= + [NFS] sets the timeout after which an attempt to + update a cache entry is deemed to have failed. + + nfs.idmap_cache_timeout= + [NFS] set the maximum lifetime for idmapper cache + entries. + + nfs.enable_ino64= + [NFS] enable 64-bit inode numbers. + If zero, the NFS client will fake up a 32-bit inode + number for the readdir() and stat() syscalls instead + of returning the full 64-bit number. + The default is to return 64-bit inode numbers. + + nfs.max_session_cb_slots= + [NFSv4.1] Sets the maximum number of session + slots the client will assign to the callback + channel. This determines the maximum number of + callbacks the client will process in parallel for + a particular server. + + nfs.max_session_slots= + [NFSv4.1] Sets the maximum number of session slots + the client will attempt to negotiate with the server. + This limits the number of simultaneous RPC requests + that the client can send to the NFSv4.1 server. + Note that there is little point in setting this + value higher than the max_tcp_slot_table_limit. + + nfs.nfs4_disable_idmapping= + [NFSv4] When set to the default of '1', this option + ensures that both the RPC level authentication + scheme and the NFS level operations agree to use + numeric uids/gids if the mount is using the + 'sec=sys' security flavour. In effect it is + disabling idmapping, which can make migration from + legacy NFSv2/v3 systems to NFSv4 easier. + Servers that do not support this mode of operation + will be autodetected by the client, and it will fall + back to using the idmapper. + To turn off this behaviour, set the value to '0'. + nfs.nfs4_unique_id= + [NFS4] Specify an additional fixed unique ident- + ification string that NFSv4 clients can insert into + their nfs_client_id4 string. This is typically a + UUID that is generated at system install time. + + nfs.send_implementation_id = + [NFSv4.1] Send client implementation identification + information in exchange_id requests. + If zero, no implementation identification information + will be sent. + The default is to send the implementation identification + information. + + nfs.recover_lost_locks = + [NFSv4] Attempt to recover locks that were lost due + to a lease timeout on the server. Please note that + doing this risks data corruption, since there are + no guarantees that the file will remain unchanged + after the locks are lost. + If you want to enable the kernel legacy behaviour of + attempting to recover these locks, then set this + parameter to '1'. + The default parameter value of '0' causes the kernel + not to attempt recovery of lost locks. + + nfs4.layoutstats_timer = + [NFSv4.2] Change the rate at which the kernel sends + layoutstats to the pNFS metadata server. + + Setting this to value to 0 causes the kernel to use + whatever value is the default set by the layout + driver. A non-zero value sets the minimum interval + in seconds between layoutstats transmissions. + + nfsd.nfs4_disable_idmapping= + [NFSv4] When set to the default of '1', the NFSv4 + server will return only numeric uids and gids to + clients using auth_sys, and will accept numeric uids + and gids from such clients. This is intended to ease + migration from NFSv2/v3. + + objlayoutdriver.osd_login_prog= + [NFS] [OBJLAYOUT] sets the pathname to the program which + is used to automatically discover and login into new + osd-targets. Please see: + Documentation/filesystems/pnfs.txt for more explanations + + nmi_debug= [KNL,AVR32,SH] Specify one or more actions to take + when a NMI is triggered. + Format: [state][,regs][,debounce][,die] + + nmi_watchdog= [KNL,BUGS=X86] Debugging features for SMP kernels + Format: [panic,][nopanic,][num] + Valid num: 0 or 1 + 0 - turn hardlockup detector in nmi_watchdog off + 1 - turn hardlockup detector in nmi_watchdog on + When panic is specified, panic when an NMI watchdog + timeout occurs (or 'nopanic' to override the opposite + default). To disable both hard and soft lockup detectors, + please see 'nowatchdog'. + This is useful when you use a panic=... timeout and + need the box quickly up again. + + netpoll.carrier_timeout= + [NET] Specifies amount of time (in seconds) that + netpoll should wait for a carrier. By default netpoll + waits 4 seconds. + + no387 [BUGS=X86-32] Tells the kernel to use the 387 maths + emulation library even if a 387 maths coprocessor + is present. + + no_console_suspend + [HW] Never suspend the console + Disable suspending of consoles during suspend and + hibernate operations. Once disabled, debugging + messages can reach various consoles while the rest + of the system is being put to sleep (ie, while + debugging driver suspend/resume hooks). This may + not work reliably with all consoles, but is known + to work with serial and VGA consoles. + To facilitate more flexible debugging, we also add + console_suspend, a printk module parameter to control + it. Users could use console_suspend (usually + /sys/module/printk/parameters/console_suspend) to + turn on/off it dynamically. + + noaliencache [MM, NUMA, SLAB] Disables the allocation of alien + caches in the slab allocator. Saves per-node memory, + but will impact performance. + + noalign [KNL,ARM] + + noapic [SMP,APIC] Tells the kernel to not make use of any + IOAPICs that may be present in the system. + + noautogroup Disable scheduler automatic task group creation. + + nobats [PPC] Do not use BATs for mapping kernel lowmem + on "Classic" PPC cores. + + nocache [ARM] + + noclflush [BUGS=X86] Don't use the CLFLUSH instruction + + nodelayacct [KNL] Disable per-task delay accounting + + nodsp [SH] Disable hardware DSP at boot time. + + noefi Disable EFI runtime services support. + + noexec [IA-64] + + noexec [X86] + On X86-32 available only on PAE configured kernels. + noexec=on: enable non-executable mappings (default) + noexec=off: disable non-executable mappings + + nosmap [X86] + Disable SMAP (Supervisor Mode Access Prevention) + even if it is supported by processor. + + nosmep [X86] + Disable SMEP (Supervisor Mode Execution Prevention) + even if it is supported by processor. + + noexec32 [X86-64] + This affects only 32-bit executables. + noexec32=on: enable non-executable mappings (default) + read doesn't imply executable mappings + noexec32=off: disable non-executable mappings + read implies executable mappings + + nofpu [MIPS,SH] Disable hardware FPU at boot time. + + nofxsr [BUGS=X86-32] Disables x86 floating point extended + register save and restore. The kernel will only save + legacy floating-point registers on task switch. + + nohugeiomap [KNL,x86] Disable kernel huge I/O mappings. + + nosmt [KNL,S390] Disable symmetric multithreading (SMT). + Equivalent to smt=1. + + noxsave [BUGS=X86] Disables x86 extended register state save + and restore using xsave. The kernel will fallback to + enabling legacy floating-point and sse state. + + noxsaveopt [X86] Disables xsaveopt used in saving x86 extended + register states. The kernel will fall back to use + xsave to save the states. By using this parameter, + performance of saving the states is degraded because + xsave doesn't support modified optimization while + xsaveopt supports it on xsaveopt enabled systems. + + noxsaves [X86] Disables xsaves and xrstors used in saving and + restoring x86 extended register state in compacted + form of xsave area. The kernel will fall back to use + xsaveopt and xrstor to save and restore the states + in standard form of xsave area. By using this + parameter, xsave area per process might occupy more + memory on xsaves enabled systems. + + nohlt [BUGS=ARM,SH] Tells the kernel that the sleep(SH) or + wfi(ARM) instruction doesn't work correctly and not to + use it. This is also useful when using JTAG debugger. + + no_file_caps Tells the kernel not to honor file capabilities. The + only way then for a file to be executed with privilege + is to be setuid root or executed by root. + + nohalt [IA-64] Tells the kernel not to use the power saving + function PAL_HALT_LIGHT when idle. This increases + power-consumption. On the positive side, it reduces + interrupt wake-up latency, which may improve performance + in certain environments such as networked servers or + real-time systems. + + nohibernate [HIBERNATION] Disable hibernation and resume. + + nohz= [KNL] Boottime enable/disable dynamic ticks + Valid arguments: on, off + Default: on + + nohz_full= [KNL,BOOT] + The argument is a cpu list, as described above. + In kernels built with CONFIG_NO_HZ_FULL=y, set + the specified list of CPUs whose tick will be stopped + whenever possible. The boot CPU will be forced outside + the range to maintain the timekeeping. + The CPUs in this range must also be included in the + rcu_nocbs= set. + + noiotrap [SH] Disables trapped I/O port accesses. + + noirqdebug [X86-32] Disables the code which attempts to detect and + disable unhandled interrupt sources. + + no_timer_check [X86,APIC] Disables the code which tests for + broken timer IRQ sources. + + noisapnp [ISAPNP] Disables ISA PnP code. + + noinitrd [RAM] Tells the kernel not to load any configured + initial RAM disk. + + nointremap [X86-64, Intel-IOMMU] Do not enable interrupt + remapping. + [Deprecated - use intremap=off] + + nointroute [IA-64] + + noinvpcid [X86] Disable the INVPCID cpu feature. + + nojitter [IA-64] Disables jitter checking for ITC timers. + + no-kvmclock [X86,KVM] Disable paravirtualized KVM clock driver + + no-kvmapf [X86,KVM] Disable paravirtualized asynchronous page + fault handling. + + no-steal-acc [X86,KVM] Disable paravirtualized steal time accounting. + steal time is computed, but won't influence scheduler + behaviour + + nolapic [X86-32,APIC] Do not enable or use the local APIC. + + nolapic_timer [X86-32,APIC] Do not use the local APIC timer. + + noltlbs [PPC] Do not use large page/tlb entries for kernel + lowmem mapping on PPC40x and PPC8xx + + nomca [IA-64] Disable machine check abort handling + + nomce [X86-32] Disable Machine Check Exception + + nomfgpt [X86-32] Disable Multi-Function General Purpose + Timer usage (for AMD Geode machines). + + nonmi_ipi [X86] Disable using NMI IPIs during panic/reboot to + shutdown the other cpus. Instead use the REBOOT_VECTOR + irq. + + nomodule Disable module load + + nopat [X86] Disable PAT (page attribute table extension of + pagetables) support. + + norandmaps Don't use address space randomization. Equivalent to + echo 0 > /proc/sys/kernel/randomize_va_space + + noreplace-paravirt [X86,IA-64,PV_OPS] Don't patch paravirt_ops + + noreplace-smp [X86-32,SMP] Don't replace SMP instructions + with UP alternatives + + nordrand [X86] Disable kernel use of the RDRAND and + RDSEED instructions even if they are supported + by the processor. RDRAND and RDSEED are still + available to user space applications. + + noresume [SWSUSP] Disables resume and restores original swap + space. + + no-scroll [VGA] Disables scrollback. + This is required for the Braillex ib80-piezo Braille + reader made by F.H. Papenmeier (Germany). + + nosbagart [IA-64] + + nosep [BUGS=X86-32] Disables x86 SYSENTER/SYSEXIT support. + + nosmp [SMP] Tells an SMP kernel to act as a UP kernel, + and disable the IO APIC. legacy for "maxcpus=0". + + nosoftlockup [KNL] Disable the soft-lockup detector. + + nosync [HW,M68K] Disables sync negotiation for all devices. + + notsc [BUGS=X86-32] Disable Time Stamp Counter + + nowatchdog [KNL] Disable both lockup detectors, i.e. + soft-lockup and NMI watchdog (hard-lockup). + + nowb [ARM] + + nox2apic [X86-64,APIC] Do not enable x2APIC mode. + + cpu0_hotplug [X86] Turn on CPU0 hotplug feature when + CONFIG_BOOTPARAM_HOTPLUG_CPU0 is off. + Some features depend on CPU0. Known dependencies are: + 1. Resume from suspend/hibernate depends on CPU0. + Suspend/hibernate will fail if CPU0 is offline and you + need to online CPU0 before suspend/hibernate. + 2. PIC interrupts also depend on CPU0. CPU0 can't be + removed if a PIC interrupt is detected. + It's said poweroff/reboot may depend on CPU0 on some + machines although I haven't seen such issues so far + after CPU0 is offline on a few tested machines. + If the dependencies are under your control, you can + turn on cpu0_hotplug. + + nptcg= [IA-64] Override max number of concurrent global TLB + purges which is reported from either PAL_VM_SUMMARY or + SAL PALO. + + nr_cpus= [SMP] Maximum number of processors that an SMP kernel + could support. nr_cpus=n : n >= 1 limits the kernel to + support 'n' processors. It could be larger than the + number of already plugged CPU during bootup, later in + runtime you can physically add extra cpu until it reaches + n. So during boot up some boot time memory for per-cpu + variables need be pre-allocated for later physical cpu + hot plugging. + + nr_uarts= [SERIAL] maximum number of UARTs to be registered. + + numa_balancing= [KNL,X86] Enable or disable automatic NUMA balancing. + Allowed values are enable and disable + + numa_zonelist_order= [KNL, BOOT] Select zonelist order for NUMA. + one of ['zone', 'node', 'default'] can be specified + This can be set from sysctl after boot. + See Documentation/sysctl/vm.txt for details. + + ohci1394_dma=early [HW] enable debugging via the ohci1394 driver. + See Documentation/debugging-via-ohci1394.txt for more + info. + + olpc_ec_timeout= [OLPC] ms delay when issuing EC commands + Rather than timing out after 20 ms if an EC + command is not properly ACKed, override the length + of the timeout. We have interrupts disabled while + waiting for the ACK, so if this is set too high + interrupts *may* be lost! + + omap_mux= [OMAP] Override bootloader pin multiplexing. + Format: ... + For example, to override I2C bus2: + omap_mux=i2c2_scl.i2c2_scl=0x100,i2c2_sda.i2c2_sda=0x100 + + oprofile.timer= [HW] + Use timer interrupt instead of performance counters + + oprofile.cpu_type= Force an oprofile cpu type + This might be useful if you have an older oprofile + userland or if you want common events. + Format: { arch_perfmon } + arch_perfmon: [X86] Force use of architectural + perfmon on Intel CPUs instead of the + CPU specific event set. + timer: [X86] Force use of architectural NMI + timer mode (see also oprofile.timer + for generic hr timer mode) + + oops=panic Always panic on oopses. Default is to just kill the + process, but there is a small probability of + deadlocking the machine. + This will also cause panics on machine check exceptions. + Useful together with panic=30 to trigger a reboot. + + OSS [HW,OSS] + See Documentation/sound/oss/oss-parameters.txt + + page_owner= [KNL] Boot-time page_owner enabling option. + Storage of the information about who allocated + each page is disabled in default. With this switch, + we can turn it on. + on: enable the feature + + page_poison= [KNL] Boot-time parameter changing the state of + poisoning on the buddy allocator. + off: turn off poisoning + on: turn on poisoning + + panic= [KNL] Kernel behaviour on panic: delay + timeout > 0: seconds before rebooting + timeout = 0: wait forever + timeout < 0: reboot immediately + Format: + + panic_on_warn panic() instead of WARN(). Useful to cause kdump + on a WARN(). + + crash_kexec_post_notifiers + Run kdump after running panic-notifiers and dumping + kmsg. This only for the users who doubt kdump always + succeeds in any situation. + Note that this also increases risks of kdump failure, + because some panic notifiers can make the crashed + kernel more unstable. + + parkbd.port= [HW] Parallel port number the keyboard adapter is + connected to, default is 0. + Format: + parkbd.mode= [HW] Parallel port keyboard adapter mode of operation, + 0 for XT, 1 for AT (default is AT). + Format: + + parport= [HW,PPT] Specify parallel ports. 0 disables. + Format: { 0 | auto | 0xBBB[,IRQ[,DMA]] } + Use 'auto' to force the driver to use any + IRQ/DMA settings detected (the default is to + ignore detected IRQ/DMA settings because of + possible conflicts). You can specify the base + address, IRQ, and DMA settings; IRQ and DMA + should be numbers, or 'auto' (for using detected + settings on that particular port), or 'nofifo' + (to avoid using a FIFO even if it is detected). + Parallel ports are assigned in the order they + are specified on the command line, starting + with parport0. + + parport_init_mode= [HW,PPT] + Configure VIA parallel port to operate in + a specific mode. This is necessary on Pegasos + computer where firmware has no options for setting + up parallel port mode and sets it to spp. + Currently this function knows 686a and 8231 chips. + Format: [spp|ps2|epp|ecp|ecpepp] + + pause_on_oops= + Halt all CPUs after the first oops has been printed for + the specified number of seconds. This is to be used if + your oopses keep scrolling off the screen. + + pcbit= [HW,ISDN] + + pcd. [PARIDE] + See header of drivers/block/paride/pcd.c. + See also Documentation/blockdev/paride.txt. + + pci=option[,option...] [PCI] various PCI subsystem options: + earlydump [X86] dump PCI config space before the kernel + changes anything + off [X86] don't probe for the PCI bus + bios [X86-32] force use of PCI BIOS, don't access + the hardware directly. Use this if your machine + has a non-standard PCI host bridge. + nobios [X86-32] disallow use of PCI BIOS, only direct + hardware access methods are allowed. Use this + if you experience crashes upon bootup and you + suspect they are caused by the BIOS. + conf1 [X86] Force use of PCI Configuration Access + Mechanism 1 (config address in IO port 0xCF8, + data in IO port 0xCFC, both 32-bit). + conf2 [X86] Force use of PCI Configuration Access + Mechanism 2 (IO port 0xCF8 is an 8-bit port for + the function, IO port 0xCFA, also 8-bit, sets + bus number. The config space is then accessed + through ports 0xC000-0xCFFF). + See http://wiki.osdev.org/PCI for more info + on the configuration access mechanisms. + noaer [PCIE] If the PCIEAER kernel config parameter is + enabled, this kernel boot option can be used to + disable the use of PCIE advanced error reporting. + nodomains [PCI] Disable support for multiple PCI + root domains (aka PCI segments, in ACPI-speak). + nommconf [X86] Disable use of MMCONFIG for PCI + Configuration + check_enable_amd_mmconf [X86] check for and enable + properly configured MMIO access to PCI + config space on AMD family 10h CPU + nomsi [MSI] If the PCI_MSI kernel config parameter is + enabled, this kernel boot option can be used to + disable the use of MSI interrupts system-wide. + noioapicquirk [APIC] Disable all boot interrupt quirks. + Safety option to keep boot IRQs enabled. This + should never be necessary. + ioapicreroute [APIC] Enable rerouting of boot IRQs to the + primary IO-APIC for bridges that cannot disable + boot IRQs. This fixes a source of spurious IRQs + when the system masks IRQs. + noioapicreroute [APIC] Disable workaround that uses the + boot IRQ equivalent of an IRQ that connects to + a chipset where boot IRQs cannot be disabled. + The opposite of ioapicreroute. + biosirq [X86-32] Use PCI BIOS calls to get the interrupt + routing table. These calls are known to be buggy + on several machines and they hang the machine + when used, but on other computers it's the only + way to get the interrupt routing table. Try + this option if the kernel is unable to allocate + IRQs or discover secondary PCI buses on your + motherboard. + rom [X86] Assign address space to expansion ROMs. + Use with caution as certain devices share + address decoders between ROMs and other + resources. + norom [X86] Do not assign address space to + expansion ROMs that do not already have + BIOS assigned address ranges. + nobar [X86] Do not assign address space to the + BARs that weren't assigned by the BIOS. + irqmask=0xMMMM [X86] Set a bit mask of IRQs allowed to be + assigned automatically to PCI devices. You can + make the kernel exclude IRQs of your ISA cards + this way. + pirqaddr=0xAAAAA [X86] Specify the physical address + of the PIRQ table (normally generated + by the BIOS) if it is outside the + F0000h-100000h range. + lastbus=N [X86] Scan all buses thru bus #N. Can be + useful if the kernel is unable to find your + secondary buses and you want to tell it + explicitly which ones they are. + assign-busses [X86] Always assign all PCI bus + numbers ourselves, overriding + whatever the firmware may have done. + usepirqmask [X86] Honor the possible IRQ mask stored + in the BIOS $PIR table. This is needed on + some systems with broken BIOSes, notably + some HP Pavilion N5400 and Omnibook XE3 + notebooks. This will have no effect if ACPI + IRQ routing is enabled. + noacpi [X86] Do not use ACPI for IRQ routing + or for PCI scanning. + use_crs [X86] Use PCI host bridge window information + from ACPI. On BIOSes from 2008 or later, this + is enabled by default. If you need to use this, + please report a bug. + nocrs [X86] Ignore PCI host bridge windows from ACPI. + If you need to use this, please report a bug. + routeirq Do IRQ routing for all PCI devices. + This is normally done in pci_enable_device(), + so this option is a temporary workaround + for broken drivers that don't call it. + skip_isa_align [X86] do not align io start addr, so can + handle more pci cards + noearly [X86] Don't do any early type 1 scanning. + This might help on some broken boards which + machine check when some devices' config space + is read. But various workarounds are disabled + and some IOMMU drivers will not work. + bfsort Sort PCI devices into breadth-first order. + This sorting is done to get a device + order compatible with older (<= 2.4) kernels. + nobfsort Don't sort PCI devices into breadth-first order. + pcie_bus_tune_off Disable PCIe MPS (Max Payload Size) + tuning and use the BIOS-configured MPS defaults. + pcie_bus_safe Set every device's MPS to the largest value + supported by all devices below the root complex. + pcie_bus_perf Set device MPS to the largest allowable MPS + based on its parent bus. Also set MRRS (Max + Read Request Size) to the largest supported + value (no larger than the MPS that the device + or bus can support) for best performance. + pcie_bus_peer2peer Set every device's MPS to 128B, which + every device is guaranteed to support. This + configuration allows peer-to-peer DMA between + any pair of devices, possibly at the cost of + reduced performance. This also guarantees + that hot-added devices will work. + cbiosize=nn[KMG] The fixed amount of bus space which is + reserved for the CardBus bridge's IO window. + The default value is 256 bytes. + cbmemsize=nn[KMG] The fixed amount of bus space which is + reserved for the CardBus bridge's memory + window. The default value is 64 megabytes. + resource_alignment= + Format: + [@][:]:.[; ...] + [@]pci::\ + [::][; ...] + Specifies alignment and device to reassign + aligned memory resources. + If is not specified, + PAGE_SIZE is used as alignment. + PCI-PCI bridge can be specified, if resource + windows need to be expanded. + To specify the alignment for several + instances of a device, the PCI vendor, + device, subvendor, and subdevice may be + specified, e.g., 4096@pci:8086:9c22:103c:198f + ecrc= Enable/disable PCIe ECRC (transaction layer + end-to-end CRC checking). + bios: Use BIOS/firmware settings. This is the + the default. + off: Turn ECRC off + on: Turn ECRC on. + hpiosize=nn[KMG] The fixed amount of bus space which is + reserved for hotplug bridge's IO window. + Default size is 256 bytes. + hpmemsize=nn[KMG] The fixed amount of bus space which is + reserved for hotplug bridge's memory window. + Default size is 2 megabytes. + hpbussize=nn The minimum amount of additional bus numbers + reserved for buses below a hotplug bridge. + Default is 1. + realloc= Enable/disable reallocating PCI bridge resources + if allocations done by BIOS are too small to + accommodate resources required by all child + devices. + off: Turn realloc off + on: Turn realloc on + realloc same as realloc=on + noari do not use PCIe ARI. + pcie_scan_all Scan all possible PCIe devices. Otherwise we + only look for one device below a PCIe downstream + port. + + pcie_aspm= [PCIE] Forcibly enable or disable PCIe Active State Power + Management. + off Disable ASPM. + force Enable ASPM even on devices that claim not to support it. + WARNING: Forcing ASPM on may cause system lockups. + + pcie_hp= [PCIE] PCI Express Hotplug driver options: + nomsi Do not use MSI for PCI Express Native Hotplug (this + makes all PCIe ports use INTx for hotplug services). + + pcie_ports= [PCIE] PCIe ports handling: + auto Ask the BIOS whether or not to use native PCIe services + associated with PCIe ports (PME, hot-plug, AER). Use + them only if that is allowed by the BIOS. + native Use native PCIe services associated with PCIe ports + unconditionally. + compat Treat PCIe ports as PCI-to-PCI bridges, disable the PCIe + ports driver. + + pcie_port_pm= [PCIE] PCIe port power management handling: + off Disable power management of all PCIe ports + force Forcibly enable power management of all PCIe ports + + pcie_pme= [PCIE,PM] Native PCIe PME signaling options: + nomsi Do not use MSI for native PCIe PME signaling (this makes + all PCIe root ports use INTx for all services). + + pcmv= [HW,PCMCIA] BadgePAD 4 + + pd_ignore_unused + [PM] + Keep all power-domains already enabled by bootloader on, + even if no driver has claimed them. This is useful + for debug and development, but should not be + needed on a platform with proper driver support. + + pd. [PARIDE] + See Documentation/blockdev/paride.txt. + + pdcchassis= [PARISC,HW] Disable/Enable PDC Chassis Status codes at + boot time. + Format: { 0 | 1 } + See arch/parisc/kernel/pdc_chassis.c + + percpu_alloc= Select which percpu first chunk allocator to use. + Currently supported values are "embed" and "page". + Archs may support subset or none of the selections. + See comments in mm/percpu.c for details on each + allocator. This parameter is primarily for debugging + and performance comparison. + + pf. [PARIDE] + See Documentation/blockdev/paride.txt. + + pg. [PARIDE] + See Documentation/blockdev/paride.txt. + + pirq= [SMP,APIC] Manual mp-table setup + See Documentation/x86/i386/IO-APIC.txt. + + plip= [PPT,NET] Parallel port network link + Format: { parport | timid | 0 } + See also Documentation/parport.txt. + + pmtmr= [X86] Manual setup of pmtmr I/O Port. + Override pmtimer IOPort with a hex value. + e.g. pmtmr=0x508 + + pnp.debug=1 [PNP] + Enable PNP debug messages (depends on the + CONFIG_PNP_DEBUG_MESSAGES option). Change at run-time + via /sys/module/pnp/parameters/debug. We always show + current resource usage; turning this on also shows + possible settings and some assignment information. + + pnpacpi= [ACPI] + { off } + + pnpbios= [ISAPNP] + { on | off | curr | res | no-curr | no-res } + + pnp_reserve_irq= + [ISAPNP] Exclude IRQs for the autoconfiguration + + pnp_reserve_dma= + [ISAPNP] Exclude DMAs for the autoconfiguration + + pnp_reserve_io= [ISAPNP] Exclude I/O ports for the autoconfiguration + Ranges are in pairs (I/O port base and size). + + pnp_reserve_mem= + [ISAPNP] Exclude memory regions for the + autoconfiguration. + Ranges are in pairs (memory base and size). + + ports= [IP_VS_FTP] IPVS ftp helper module + Default is 21. + Up to 8 (IP_VS_APP_MAX_PORTS) ports + may be specified. + Format: ,.... + + ppc_strict_facility_enable + [PPC] This option catches any kernel floating point, + Altivec, VSX and SPE outside of regions specifically + allowed (eg kernel_enable_fpu()/kernel_disable_fpu()). + There is some performance impact when enabling this. + + print-fatal-signals= + [KNL] debug: print fatal signals + + If enabled, warn about various signal handling + related application anomalies: too many signals, + too many POSIX.1 timers, fatal signals causing a + coredump - etc. + + If you hit the warning due to signal overflow, + you might want to try "ulimit -i unlimited". + + default: off. + + printk.always_kmsg_dump= + Trigger kmsg_dump for cases other than kernel oops or + panics + Format: (1/Y/y=enable, 0/N/n=disable) + default: disabled + + printk.devkmsg={on,off,ratelimit} + Control writing to /dev/kmsg. + on - unlimited logging to /dev/kmsg from userspace + off - logging to /dev/kmsg disabled + ratelimit - ratelimit the logging + Default: ratelimit + + printk.time= Show timing data prefixed to each printk message line + Format: (1/Y/y=enable, 0/N/n=disable) + + processor.max_cstate= [HW,ACPI] + Limit processor to maximum C-state + max_cstate=9 overrides any DMI blacklist limit. + + processor.nocst [HW,ACPI] + Ignore the _CST method to determine C-states, + instead using the legacy FADT method + + profile= [KNL] Enable kernel profiling via /proc/profile + Format: [schedule,] + Param: "schedule" - profile schedule points. + Param: - step/bucket size as a power of 2 for + statistical time based profiling. + Param: "sleep" - profile D-state sleeping (millisecs). + Requires CONFIG_SCHEDSTATS + Param: "kvm" - profile VM exits. + + prompt_ramdisk= [RAM] List of RAM disks to prompt for floppy disk + before loading. + See Documentation/blockdev/ramdisk.txt. + + psmouse.proto= [HW,MOUSE] Highest PS2 mouse protocol extension to + probe for; one of (bare|imps|exps|lifebook|any). + psmouse.rate= [HW,MOUSE] Set desired mouse report rate, in reports + per second. + psmouse.resetafter= [HW,MOUSE] + Try to reset the device after so many bad packets + (0 = never). + psmouse.resolution= + [HW,MOUSE] Set desired mouse resolution, in dpi. + psmouse.smartscroll= + [HW,MOUSE] Controls Logitech smartscroll autorepeat. + 0 = disabled, 1 = enabled (default). + + pstore.backend= Specify the name of the pstore backend to use + + pt. [PARIDE] + See Documentation/blockdev/paride.txt. + + pty.legacy_count= + [KNL] Number of legacy pty's. Overwrites compiled-in + default number. + + quiet [KNL] Disable most log messages + + r128= [HW,DRM] + + raid= [HW,RAID] + See Documentation/admin-guide/md.rst. + + ramdisk_size= [RAM] Sizes of RAM disks in kilobytes + See Documentation/blockdev/ramdisk.txt. + + rcu_nocbs= [KNL] + The argument is a cpu list, as described above. + + In kernels built with CONFIG_RCU_NOCB_CPU=y, set + the specified list of CPUs to be no-callback CPUs. + Invocation of these CPUs' RCU callbacks will + be offloaded to "rcuox/N" kthreads created for + that purpose, where "x" is "b" for RCU-bh, "p" + for RCU-preempt, and "s" for RCU-sched, and "N" + is the CPU number. This reduces OS jitter on the + offloaded CPUs, which can be useful for HPC and + real-time workloads. It can also improve energy + efficiency for asymmetric multiprocessors. + + rcu_nocb_poll [KNL] + Rather than requiring that offloaded CPUs + (specified by rcu_nocbs= above) explicitly + awaken the corresponding "rcuoN" kthreads, + make these kthreads poll for callbacks. + This improves the real-time response for the + offloaded CPUs by relieving them of the need to + wake up the corresponding kthread, but degrades + energy efficiency by requiring that the kthreads + periodically wake up to do the polling. + + rcutree.blimit= [KNL] + Set maximum number of finished RCU callbacks to + process in one batch. + + rcutree.dump_tree= [KNL] + Dump the structure of the rcu_node combining tree + out at early boot. This is used for diagnostic + purposes, to verify correct tree setup. + + rcutree.gp_cleanup_delay= [KNL] + Set the number of jiffies to delay each step of + RCU grace-period cleanup. This only has effect + when CONFIG_RCU_TORTURE_TEST_SLOW_CLEANUP is set. + + rcutree.gp_init_delay= [KNL] + Set the number of jiffies to delay each step of + RCU grace-period initialization. This only has + effect when CONFIG_RCU_TORTURE_TEST_SLOW_INIT + is set. + + rcutree.gp_preinit_delay= [KNL] + Set the number of jiffies to delay each step of + RCU grace-period pre-initialization, that is, + the propagation of recent CPU-hotplug changes up + the rcu_node combining tree. This only has effect + when CONFIG_RCU_TORTURE_TEST_SLOW_PREINIT is set. + + rcutree.rcu_fanout_exact= [KNL] + Disable autobalancing of the rcu_node combining + tree. This is used by rcutorture, and might + possibly be useful for architectures having high + cache-to-cache transfer latencies. + + rcutree.rcu_fanout_leaf= [KNL] + Change the number of CPUs assigned to each + leaf rcu_node structure. Useful for very + large systems, which will choose the value 64, + and for NUMA systems with large remote-access + latencies, which will choose a value aligned + with the appropriate hardware boundaries. + + rcutree.jiffies_till_sched_qs= [KNL] + Set required age in jiffies for a + given grace period before RCU starts + soliciting quiescent-state help from + rcu_note_context_switch(). + + rcutree.jiffies_till_first_fqs= [KNL] + Set delay from grace-period initialization to + first attempt to force quiescent states. + Units are jiffies, minimum value is zero, + and maximum value is HZ. + + rcutree.jiffies_till_next_fqs= [KNL] + Set delay between subsequent attempts to force + quiescent states. Units are jiffies, minimum + value is one, and maximum value is HZ. + + rcutree.kthread_prio= [KNL,BOOT] + Set the SCHED_FIFO priority of the RCU per-CPU + kthreads (rcuc/N). This value is also used for + the priority of the RCU boost threads (rcub/N) + and for the RCU grace-period kthreads (rcu_bh, + rcu_preempt, and rcu_sched). If RCU_BOOST is + set, valid values are 1-99 and the default is 1 + (the least-favored priority). Otherwise, when + RCU_BOOST is not set, valid values are 0-99 and + the default is zero (non-realtime operation). + + rcutree.rcu_nocb_leader_stride= [KNL] + Set the number of NOCB kthread groups, which + defaults to the square root of the number of + CPUs. Larger numbers reduces the wakeup overhead + on the per-CPU grace-period kthreads, but increases + that same overhead on each group's leader. + + rcutree.qhimark= [KNL] + Set threshold of queued RCU callbacks beyond which + batch limiting is disabled. + + rcutree.qlowmark= [KNL] + Set threshold of queued RCU callbacks below which + batch limiting is re-enabled. + + rcutree.rcu_idle_gp_delay= [KNL] + Set wakeup interval for idle CPUs that have + RCU callbacks (RCU_FAST_NO_HZ=y). + + rcutree.rcu_idle_lazy_gp_delay= [KNL] + Set wakeup interval for idle CPUs that have + only "lazy" RCU callbacks (RCU_FAST_NO_HZ=y). + Lazy RCU callbacks are those which RCU can + prove do nothing more than free memory. + + rcuperf.gp_exp= [KNL] + Measure performance of expedited synchronous + grace-period primitives. + + rcuperf.holdoff= [KNL] + Set test-start holdoff period. The purpose of + this parameter is to delay the start of the + test until boot completes in order to avoid + interference. + + rcuperf.nreaders= [KNL] + Set number of RCU readers. The value -1 selects + N, where N is the number of CPUs. A value + "n" less than -1 selects N-n+1, where N is again + the number of CPUs. For example, -2 selects N + (the number of CPUs), -3 selects N+1, and so on. + A value of "n" less than or equal to -N selects + a single reader. + + rcuperf.nwriters= [KNL] + Set number of RCU writers. The values operate + the same as for rcuperf.nreaders. + N, where N is the number of CPUs + + rcuperf.perf_runnable= [BOOT] + Start rcuperf running at boot time. + + rcuperf.shutdown= [KNL] + Shut the system down after performance tests + complete. This is useful for hands-off automated + testing. + + rcuperf.perf_type= [KNL] + Specify the RCU implementation to test. + + rcuperf.verbose= [KNL] + Enable additional printk() statements. + + rcutorture.cbflood_inter_holdoff= [KNL] + Set holdoff time (jiffies) between successive + callback-flood tests. + + rcutorture.cbflood_intra_holdoff= [KNL] + Set holdoff time (jiffies) between successive + bursts of callbacks within a given callback-flood + test. + + rcutorture.cbflood_n_burst= [KNL] + Set the number of bursts making up a given + callback-flood test. Set this to zero to + disable callback-flood testing. + + rcutorture.cbflood_n_per_burst= [KNL] + Set the number of callbacks to be registered + in a given burst of a callback-flood test. + + rcutorture.fqs_duration= [KNL] + Set duration of force_quiescent_state bursts + in microseconds. + + rcutorture.fqs_holdoff= [KNL] + Set holdoff time within force_quiescent_state bursts + in microseconds. + + rcutorture.fqs_stutter= [KNL] + Set wait time between force_quiescent_state bursts + in seconds. + + rcutorture.gp_cond= [KNL] + Use conditional/asynchronous update-side + primitives, if available. + + rcutorture.gp_exp= [KNL] + Use expedited update-side primitives, if available. + + rcutorture.gp_normal= [KNL] + Use normal (non-expedited) asynchronous + update-side primitives, if available. + + rcutorture.gp_sync= [KNL] + Use normal (non-expedited) synchronous + update-side primitives, if available. If all + of rcutorture.gp_cond=, rcutorture.gp_exp=, + rcutorture.gp_normal=, and rcutorture.gp_sync= + are zero, rcutorture acts as if is interpreted + they are all non-zero. + + rcutorture.n_barrier_cbs= [KNL] + Set callbacks/threads for rcu_barrier() testing. + + rcutorture.nfakewriters= [KNL] + Set number of concurrent RCU writers. These just + stress RCU, they don't participate in the actual + test, hence the "fake". + + rcutorture.nreaders= [KNL] + Set number of RCU readers. The value -1 selects + N-1, where N is the number of CPUs. A value + "n" less than -1 selects N-n-2, where N is again + the number of CPUs. For example, -2 selects N + (the number of CPUs), -3 selects N+1, and so on. + + rcutorture.object_debug= [KNL] + Enable debug-object double-call_rcu() testing. + + rcutorture.onoff_holdoff= [KNL] + Set time (s) after boot for CPU-hotplug testing. + + rcutorture.onoff_interval= [KNL] + Set time (s) between CPU-hotplug operations, or + zero to disable CPU-hotplug testing. + + rcutorture.shuffle_interval= [KNL] + Set task-shuffle interval (s). Shuffling tasks + allows some CPUs to go into dyntick-idle mode + during the rcutorture test. + + rcutorture.shutdown_secs= [KNL] + Set time (s) after boot system shutdown. This + is useful for hands-off automated testing. + + rcutorture.stall_cpu= [KNL] + Duration of CPU stall (s) to test RCU CPU stall + warnings, zero to disable. + + rcutorture.stall_cpu_holdoff= [KNL] + Time to wait (s) after boot before inducing stall. + + rcutorture.stat_interval= [KNL] + Time (s) between statistics printk()s. + + rcutorture.stutter= [KNL] + Time (s) to stutter testing, for example, specifying + five seconds causes the test to run for five seconds, + wait for five seconds, and so on. This tests RCU's + ability to transition abruptly to and from idle. + + rcutorture.test_boost= [KNL] + Test RCU priority boosting? 0=no, 1=maybe, 2=yes. + "Maybe" means test if the RCU implementation + under test support RCU priority boosting. + + rcutorture.test_boost_duration= [KNL] + Duration (s) of each individual boost test. + + rcutorture.test_boost_interval= [KNL] + Interval (s) between each boost test. + + rcutorture.test_no_idle_hz= [KNL] + Test RCU's dyntick-idle handling. See also the + rcutorture.shuffle_interval parameter. + + rcutorture.torture_runnable= [BOOT] + Start rcutorture running at boot time. + + rcutorture.torture_type= [KNL] + Specify the RCU implementation to test. + + rcutorture.verbose= [KNL] + Enable additional printk() statements. + + rcupdate.rcu_cpu_stall_suppress= [KNL] + Suppress RCU CPU stall warning messages. + + rcupdate.rcu_cpu_stall_timeout= [KNL] + Set timeout for RCU CPU stall warning messages. + + rcupdate.rcu_expedited= [KNL] + Use expedited grace-period primitives, for + example, synchronize_rcu_expedited() instead + of synchronize_rcu(). This reduces latency, + but can increase CPU utilization, degrade + real-time latency, and degrade energy efficiency. + No effect on CONFIG_TINY_RCU kernels. + + rcupdate.rcu_normal= [KNL] + Use only normal grace-period primitives, + for example, synchronize_rcu() instead of + synchronize_rcu_expedited(). This improves + real-time latency, CPU utilization, and + energy efficiency, but can expose users to + increased grace-period latency. This parameter + overrides rcupdate.rcu_expedited. No effect on + CONFIG_TINY_RCU kernels. + + rcupdate.rcu_normal_after_boot= [KNL] + Once boot has completed (that is, after + rcu_end_inkernel_boot() has been invoked), use + only normal grace-period primitives. No effect + on CONFIG_TINY_RCU kernels. + + rcupdate.rcu_task_stall_timeout= [KNL] + Set timeout in jiffies for RCU task stall warning + messages. Disable with a value less than or equal + to zero. + + rcupdate.rcu_self_test= [KNL] + Run the RCU early boot self tests + + rcupdate.rcu_self_test_bh= [KNL] + Run the RCU bh early boot self tests + + rcupdate.rcu_self_test_sched= [KNL] + Run the RCU sched early boot self tests + + rdinit= [KNL] + Format: + Run specified binary instead of /init from the ramdisk, + used for early userspace startup. See initrd. + + reboot= [KNL] + Format (x86 or x86_64): + [w[arm] | c[old] | h[ard] | s[oft] | g[pio]] \ + [[,]s[mp]#### \ + [[,]b[ios] | a[cpi] | k[bd] | t[riple] | e[fi] | p[ci]] \ + [[,]f[orce] + Where reboot_mode is one of warm (soft) or cold (hard) or gpio, + reboot_type is one of bios, acpi, kbd, triple, efi, or pci, + reboot_force is either force or not specified, + reboot_cpu is s[mp]#### with #### being the processor + to be used for rebooting. + + relax_domain_level= + [KNL, SMP] Set scheduler's default relax_domain_level. + See Documentation/cgroup-v1/cpusets.txt. + + relative_sleep_states= + [SUSPEND] Use sleep state labeling where the deepest + state available other than hibernation is always "mem". + Format: { "0" | "1" } + 0 -- Traditional sleep state labels. + 1 -- Relative sleep state labels. + + reserve= [KNL,BUGS] Force the kernel to ignore some iomem area + + reservetop= [X86-32] + Format: nn[KMG] + Reserves a hole at the top of the kernel virtual + address space. + + reservelow= [X86] + Format: nn[K] + Set the amount of memory to reserve for BIOS at + the bottom of the address space. + + reset_devices [KNL] Force drivers to reset the underlying device + during initialization. + + resume= [SWSUSP] + Specify the partition device for software suspend + Format: + {/dev/ | PARTUUID= | : | } + + resume_offset= [SWSUSP] + Specify the offset from the beginning of the partition + given by "resume=" at which the swap header is located, + in units (needed only for swap files). + See Documentation/power/swsusp-and-swap-files.txt + + resumedelay= [HIBERNATION] Delay (in seconds) to pause before attempting to + read the resume files + + resumewait [HIBERNATION] Wait (indefinitely) for resume device to show up. + Useful for devices that are detected asynchronously + (e.g. USB and MMC devices). + + hibernate= [HIBERNATION] + noresume Don't check if there's a hibernation image + present during boot. + nocompress Don't compress/decompress hibernation images. + no Disable hibernation and resume. + protect_image Turn on image protection during restoration + (that will set all pages holding image data + during restoration read-only). + + retain_initrd [RAM] Keep initrd memory after extraction + + rfkill.default_state= + 0 "airplane mode". All wifi, bluetooth, wimax, gps, fm, + etc. communication is blocked by default. + 1 Unblocked. + + rfkill.master_switch_mode= + 0 The "airplane mode" button does nothing. + 1 The "airplane mode" button toggles between everything + blocked and the previous configuration. + 2 The "airplane mode" button toggles between everything + blocked and everything unblocked. + + rhash_entries= [KNL,NET] + Set number of hash buckets for route cache + + ro [KNL] Mount root device read-only on boot + + rodata= [KNL] + on Mark read-only kernel memory as read-only (default). + off Leave read-only kernel memory writable for debugging. + + rockchip.usb_uart + Enable the uart passthrough on the designated usb port + on Rockchip SoCs. When active, the signals of the + debug-uart get routed to the D+ and D- pins of the usb + port and the regular usb controller gets disabled. + + root= [KNL] Root filesystem + See name_to_dev_t comment in init/do_mounts.c. + + rootdelay= [KNL] Delay (in seconds) to pause before attempting to + mount the root filesystem + + rootflags= [KNL] Set root filesystem mount option string + + rootfstype= [KNL] Set root filesystem type + + rootwait [KNL] Wait (indefinitely) for root device to show up. + Useful for devices that are detected asynchronously + (e.g. USB and MMC devices). + + rproc_mem=nn[KMG][@address] + [KNL,ARM,CMA] Remoteproc physical memory block. + Memory area to be used by remote processor image, + managed by CMA. + + rw [KNL] Mount root device read-write on boot + + S [KNL] Run init in single mode + + s390_iommu= [HW,S390] + Set s390 IOTLB flushing mode + strict + With strict flushing every unmap operation will result in + an IOTLB flush. Default is lazy flushing before reuse, + which is faster. + + sa1100ir [NET] + See drivers/net/irda/sa1100_ir.c. + + sbni= [NET] Granch SBNI12 leased line adapter + + sched_debug [KNL] Enables verbose scheduler debug messages. + + schedstats= [KNL,X86] Enable or disable scheduled statistics. + Allowed values are enable and disable. This feature + incurs a small amount of overhead in the scheduler + but is useful for debugging and performance tuning. + + skew_tick= [KNL] Offset the periodic timer tick per cpu to mitigate + xtime_lock contention on larger systems, and/or RCU lock + contention on all systems with CONFIG_MAXSMP set. + Format: { "0" | "1" } + 0 -- disable. (may be 1 via CONFIG_CMDLINE="skew_tick=1" + 1 -- enable. + Note: increases power consumption, thus should only be + enabled if running jitter sensitive (HPC/RT) workloads. + + security= [SECURITY] Choose a security module to enable at boot. + If this boot parameter is not specified, only the first + security module asking for security registration will be + loaded. An invalid security module name will be treated + as if no module has been chosen. + + selinux= [SELINUX] Disable or enable SELinux at boot time. + Format: { "0" | "1" } + See security/selinux/Kconfig help text. + 0 -- disable. + 1 -- enable. + Default value is set via kernel config option. + If enabled at boot time, /selinux/disable can be used + later to disable prior to initial policy load. + + apparmor= [APPARMOR] Disable or enable AppArmor at boot time + Format: { "0" | "1" } + See security/apparmor/Kconfig help text + 0 -- disable. + 1 -- enable. + Default value is set via kernel config option. + + serialnumber [BUGS=X86-32] + + shapers= [NET] + Maximal number of shapers. + + show_msr= [x86] show boot-time MSR settings + Format: { } + Show boot-time (BIOS-initialized) MSR settings. + The parameter means the number of CPUs to show, + for example 1 means boot CPU only. + + simeth= [IA-64] + simscsi= + + slram= [HW,MTD] + + slab_nomerge [MM] + Disable merging of slabs with similar size. May be + necessary if there is some reason to distinguish + allocs to different slabs. Debug options disable + merging on their own. + For more information see Documentation/vm/slub.txt. + + slab_max_order= [MM, SLAB] + Determines the maximum allowed order for slabs. + A high setting may cause OOMs due to memory + fragmentation. Defaults to 1 for systems with + more than 32MB of RAM, 0 otherwise. + + slub_debug[=options[,slabs]] [MM, SLUB] + Enabling slub_debug allows one to determine the + culprit if slab objects become corrupted. Enabling + slub_debug can create guard zones around objects and + may poison objects when not in use. Also tracks the + last alloc / free. For more information see + Documentation/vm/slub.txt. + + slub_max_order= [MM, SLUB] + Determines the maximum allowed order for slabs. + A high setting may cause OOMs due to memory + fragmentation. For more information see + Documentation/vm/slub.txt. + + slub_min_objects= [MM, SLUB] + The minimum number of objects per slab. SLUB will + increase the slab order up to slub_max_order to + generate a sufficiently large slab able to contain + the number of objects indicated. The higher the number + of objects the smaller the overhead of tracking slabs + and the less frequently locks need to be acquired. + For more information see Documentation/vm/slub.txt. + + slub_min_order= [MM, SLUB] + Determines the minimum page order for slabs. Must be + lower than slub_max_order. + For more information see Documentation/vm/slub.txt. + + slub_nomerge [MM, SLUB] + Same with slab_nomerge. This is supported for legacy. + See slab_nomerge for more information. + + smart2= [HW] + Format: [,[,...,]] + + smsc-ircc2.nopnp [HW] Don't use PNP to discover SMC devices + smsc-ircc2.ircc_cfg= [HW] Device configuration I/O port + smsc-ircc2.ircc_sir= [HW] SIR base I/O port + smsc-ircc2.ircc_fir= [HW] FIR base I/O port + smsc-ircc2.ircc_irq= [HW] IRQ line + smsc-ircc2.ircc_dma= [HW] DMA channel + smsc-ircc2.ircc_transceiver= [HW] Transceiver type: + 0: Toshiba Satellite 1800 (GP data pin select) + 1: Fast pin select (default) + 2: ATC IRMode + + smt [KNL,S390] Set the maximum number of threads (logical + CPUs) to use per physical CPU on systems capable of + symmetric multithreading (SMT). Will be capped to the + actual hardware limit. + Format: + Default: -1 (no limit) + + softlockup_panic= + [KNL] Should the soft-lockup detector generate panics. + Format: + + softlockup_all_cpu_backtrace= + [KNL] Should the soft-lockup detector generate + backtraces on all cpus. + Format: + + sonypi.*= [HW] Sony Programmable I/O Control Device driver + See Documentation/laptops/sonypi.txt + + spia_io_base= [HW,MTD] + spia_fio_base= + spia_pedr= + spia_peddr= + + stacktrace [FTRACE] + Enabled the stack tracer on boot up. + + stacktrace_filter=[function-list] + [FTRACE] Limit the functions that the stack tracer + will trace at boot up. function-list is a comma separated + list of functions. This list can be changed at run + time by the stack_trace_filter file in the debugfs + tracing directory. Note, this enables stack tracing + and the stacktrace above is not needed. + + sti= [PARISC,HW] + Format: + Set the STI (builtin display/keyboard on the HP-PARISC + machines) console (graphic card) which should be used + as the initial boot-console. + See also comment in drivers/video/console/sticore.c. + + sti_font= [HW] + See comment in drivers/video/console/sticore.c. + + stifb= [HW] + Format: bpp:[:[:...]] + + sunrpc.min_resvport= + sunrpc.max_resvport= + [NFS,SUNRPC] + SunRPC servers often require that client requests + originate from a privileged port (i.e. a port in the + range 0 < portnr < 1024). + An administrator who wishes to reserve some of these + ports for other uses may adjust the range that the + kernel's sunrpc client considers to be privileged + using these two parameters to set the minimum and + maximum port values. + + sunrpc.svc_rpc_per_connection_limit= + [NFS,SUNRPC] + Limit the number of requests that the server will + process in parallel from a single connection. + The default value is 0 (no limit). + + sunrpc.pool_mode= + [NFS] + Control how the NFS server code allocates CPUs to + service thread pools. Depending on how many NICs + you have and where their interrupts are bound, this + option will affect which CPUs will do NFS serving. + Note: this parameter cannot be changed while the + NFS server is running. + + auto the server chooses an appropriate mode + automatically using heuristics + global a single global pool contains all CPUs + percpu one pool for each CPU + pernode one pool for each NUMA node (equivalent + to global on non-NUMA machines) + + sunrpc.tcp_slot_table_entries= + sunrpc.udp_slot_table_entries= + [NFS,SUNRPC] + Sets the upper limit on the number of simultaneous + RPC calls that can be sent from the client to a + server. Increasing these values may allow you to + improve throughput, but will also increase the + amount of memory reserved for use by the client. + + suspend.pm_test_delay= + [SUSPEND] + Sets the number of seconds to remain in a suspend test + mode before resuming the system (see + /sys/power/pm_test). Only available when CONFIG_PM_DEBUG + is set. Default value is 5. + + swapaccount=[0|1] + [KNL] Enable accounting of swap in memory resource + controller if no parameter or 1 is given or disable + it if 0 is given (See Documentation/cgroup-v1/memory.txt) + + swiotlb= [ARM,IA-64,PPC,MIPS,X86] + Format: { | force } + -- Number of I/O TLB slabs + force -- force using of bounce buffers even if they + wouldn't be automatically used by the kernel + + switches= [HW,M68k] + + sysfs.deprecated=0|1 [KNL] + Enable/disable old style sysfs layout for old udev + on older distributions. When this option is enabled + very new udev will not work anymore. When this option + is disabled (or CONFIG_SYSFS_DEPRECATED not compiled) + in older udev will not work anymore. + Default depends on CONFIG_SYSFS_DEPRECATED_V2 set in + the kernel configuration. + + sysrq_always_enabled + [KNL] + Ignore sysrq setting - this boot parameter will + neutralize any effect of /proc/sys/kernel/sysrq. + Useful for debugging. + + tcpmhash_entries= [KNL,NET] + Set the number of tcp_metrics_hash slots. + Default value is 8192 or 16384 depending on total + ram pages. This is used to specify the TCP metrics + cache size. See Documentation/networking/ip-sysctl.txt + "tcp_no_metrics_save" section for more details. + + tdfx= [HW,DRM] + + test_suspend= [SUSPEND][,N] + Specify "mem" (for Suspend-to-RAM) or "standby" (for + standby suspend) or "freeze" (for suspend type freeze) + as the system sleep state during system startup with + the optional capability to repeat N number of times. + The system is woken from this state using a + wakeup-capable RTC alarm. + + thash_entries= [KNL,NET] + Set number of hash buckets for TCP connection + + thermal.act= [HW,ACPI] + -1: disable all active trip points in all thermal zones + : override all lowest active trip points + + thermal.crt= [HW,ACPI] + -1: disable all critical trip points in all thermal zones + : override all critical trip points + + thermal.nocrt= [HW,ACPI] + Set to disable actions on ACPI thermal zone + critical and hot trip points. + + thermal.off= [HW,ACPI] + 1: disable ACPI thermal control + + thermal.psv= [HW,ACPI] + -1: disable all passive trip points + : override all passive trip points to this + value + + thermal.tzp= [HW,ACPI] + Specify global default ACPI thermal zone polling rate + : poll all this frequency + 0: no polling (default) + + threadirqs [KNL] + Force threading of all interrupt handlers except those + marked explicitly IRQF_NO_THREAD. + + tmem [KNL,XEN] + Enable the Transcendent memory driver if built-in. + + tmem.cleancache=0|1 [KNL, XEN] + Default is on (1). Disable the usage of the cleancache + API to send anonymous pages to the hypervisor. + + tmem.frontswap=0|1 [KNL, XEN] + Default is on (1). Disable the usage of the frontswap + API to send swap pages to the hypervisor. If disabled + the selfballooning and selfshrinking are force disabled. + + tmem.selfballooning=0|1 [KNL, XEN] + Default is on (1). Disable the driving of swap pages + to the hypervisor. + + tmem.selfshrinking=0|1 [KNL, XEN] + Default is on (1). Partial swapoff that immediately + transfers pages from Xen hypervisor back to the + kernel based on different criteria. + + topology= [S390] + Format: {off | on} + Specify if the kernel should make use of the cpu + topology information if the hardware supports this. + The scheduler will make use of this information and + e.g. base its process migration decisions on it. + Default is on. + + topology_updates= [KNL, PPC, NUMA] + Format: {off} + Specify if the kernel should ignore (off) + topology updates sent by the hypervisor to this + LPAR. + + tp720= [HW,PS2] + + tpm_suspend_pcr=[HW,TPM] + Format: integer pcr id + Specify that at suspend time, the tpm driver + should extend the specified pcr with zeros, + as a workaround for some chips which fail to + flush the last written pcr on TPM_SaveState. + This will guarantee that all the other pcrs + are saved. + + trace_buf_size=nn[KMG] + [FTRACE] will set tracing buffer size on each cpu. + + trace_event=[event-list] + [FTRACE] Set and start specified trace events in order + 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. + The option-list is a comma delimited list of options + that can be enabled or disabled just as if you were + to echo the option name into + + /sys/kernel/debug/tracing/trace_options + + For example, to enable stacktrace option (to dump the + stack trace of each event), add to the command line: + + trace_options=stacktrace + + See also Documentation/trace/ftrace.txt "trace options" + section. + + tp_printk[FTRACE] + Have the tracepoints sent to printk as well as the + tracing ring buffer. This is useful for early boot up + where the system hangs or reboots and does not give the + option for reading the tracing buffer or performing a + ftrace_dump_on_oops. + + To turn off having tracepoints sent to printk, + echo 0 > /proc/sys/kernel/tracepoint_printk + Note, echoing 1 into this file without the + tracepoint_printk kernel cmdline option has no effect. + + ** CAUTION ** + + Having tracepoints sent to printk() and activating high + frequency tracepoints such as irq or sched, can cause + the system to live lock. + + traceoff_on_warning + [FTRACE] enable this option to disable tracing when a + warning is hit. This turns off "tracing_on". Tracing can + be enabled again by echoing '1' into the "tracing_on" + file located in /sys/kernel/debug/tracing/ + + This option is useful, as it disables the trace before + the WARNING dump is called, which prevents the trace to + be filled with content caused by the warning output. + + This option can also be set at run time via the sysctl + option: kernel/traceoff_on_warning + + transparent_hugepage= + [KNL] + Format: [always|madvise|never] + Can be used to control the default behavior of the system + with respect to transparent hugepages. + See Documentation/vm/transhuge.txt for more details. + + tsc= Disable clocksource stability checks for TSC. + Format: + [x86] reliable: mark tsc clocksource as reliable, this + disables clocksource verification at runtime, as well + as the stability checks done at bootup. Used to enable + high-resolution timer mode on older hardware, and in + virtualized environment. + [x86] noirqtime: Do not use TSC to do irq accounting. + Used to run time disable IRQ_TIME_ACCOUNTING on any + platforms where RDTSC is slow and this accounting + can add overhead. + + turbografx.map[2|3]= [HW,JOY] + TurboGraFX parallel port interface + Format: + ,,,,,,, + See also Documentation/input/joystick-parport.txt + + udbg-immortal [PPC] When debugging early kernel crashes that + happen after console_init() and before a proper + console driver takes over, this boot options might + help "seeing" what's going on. + + uhash_entries= [KNL,NET] + Set number of hash buckets for UDP/UDP-Lite connections + + uhci-hcd.ignore_oc= + [USB] Ignore overcurrent events (default N). + Some badly-designed motherboards generate lots of + bogus events, for ports that aren't wired to + anything. Set this parameter to avoid log spamming. + Note that genuine overcurrent events won't be + reported either. + + unknown_nmi_panic + [X86] Cause panic on unknown NMI. + + usbcore.authorized_default= + [USB] Default USB device authorization: + (default -1 = authorized except for wireless USB, + 0 = not authorized, 1 = authorized) + + usbcore.autosuspend= + [USB] The autosuspend time delay (in seconds) used + for newly-detected USB devices (default 2). This + is the time required before an idle device will be + autosuspended. Devices for which the delay is set + to a negative value won't be autosuspended at all. + + usbcore.usbfs_snoop= + [USB] Set to log all usbfs traffic (default 0 = off). + + usbcore.usbfs_snoop_max= + [USB] Maximum number of bytes to snoop in each URB + (default = 65536). + + usbcore.blinkenlights= + [USB] Set to cycle leds on hubs (default 0 = off). + + usbcore.old_scheme_first= + [USB] Start with the old device initialization + scheme (default 0 = off). + + usbcore.usbfs_memory_mb= + [USB] Memory limit (in MB) for buffers allocated by + usbfs (default = 16, 0 = max = 2047). + + usbcore.use_both_schemes= + [USB] Try the other device initialization scheme + if the first one fails (default 1 = enabled). + + usbcore.initial_descriptor_timeout= + [USB] Specifies timeout for the initial 64-byte + USB_REQ_GET_DESCRIPTOR request in milliseconds + (default 5000 = 5.0 seconds). + + usbcore.nousb [USB] Disable the USB subsystem + + usbhid.mousepoll= + [USBHID] The interval which mice are to be polled at. + + usb-storage.delay_use= + [UMS] The delay in seconds before a new device is + scanned for Logical Units (default 1). + + usb-storage.quirks= + [UMS] A list of quirks entries to supplement or + override the built-in unusual_devs list. List + entries are separated by commas. Each entry has + the form VID:PID:Flags where VID and PID are Vendor + and Product ID values (4-digit hex numbers) and + Flags is a set of characters, each corresponding + to a common usb-storage quirk flag as follows: + a = SANE_SENSE (collect more than 18 bytes + of sense data); + b = BAD_SENSE (don't collect more than 18 + bytes of sense data); + c = FIX_CAPACITY (decrease the reported + device capacity by one sector); + d = NO_READ_DISC_INFO (don't use + READ_DISC_INFO command); + e = NO_READ_CAPACITY_16 (don't use + READ_CAPACITY_16 command); + f = NO_REPORT_OPCODES (don't use report opcodes + command, uas only); + g = MAX_SECTORS_240 (don't transfer more than + 240 sectors at a time, uas only); + h = CAPACITY_HEURISTICS (decrease the + reported device capacity by one + sector if the number is odd); + i = IGNORE_DEVICE (don't bind to this + device); + j = NO_REPORT_LUNS (don't use report luns + command, uas only); + l = NOT_LOCKABLE (don't try to lock and + unlock ejectable media); + m = MAX_SECTORS_64 (don't transfer more + than 64 sectors = 32 KB at a time); + n = INITIAL_READ10 (force a retry of the + initial READ(10) command); + o = CAPACITY_OK (accept the capacity + reported by the device); + p = WRITE_CACHE (the device cache is ON + by default); + r = IGNORE_RESIDUE (the device reports + bogus residue values); + s = SINGLE_LUN (the device has only one + Logical Unit); + t = NO_ATA_1X (don't allow ATA(12) and ATA(16) + commands, uas only); + u = IGNORE_UAS (don't bind to the uas driver); + w = NO_WP_DETECT (don't test whether the + medium is write-protected). + y = ALWAYS_SYNC (issue a SYNCHRONIZE_CACHE + even if the device claims no cache) + Example: quirks=0419:aaf5:rl,0421:0433:rc + + user_debug= [KNL,ARM] + Format: + See arch/arm/Kconfig.debug help text. + 1 - undefined instruction events + 2 - system calls + 4 - invalid data aborts + 8 - SIGSEGV faults + 16 - SIGBUS faults + Example: user_debug=31 + + userpte= + [X86] Flags controlling user PTE allocations. + + nohigh = do not allocate PTE pages in + HIGHMEM regardless of setting + of CONFIG_HIGHPTE. + + vdso= [X86,SH] + On X86_32, this is an alias for vdso32=. Otherwise: + + vdso=1: enable VDSO (the default) + vdso=0: disable VDSO mapping + + vdso32= [X86] Control the 32-bit vDSO + vdso32=1: enable 32-bit VDSO + vdso32=0 or vdso32=2: disable 32-bit VDSO + + See the help text for CONFIG_COMPAT_VDSO for more + details. If CONFIG_COMPAT_VDSO is set, the default is + vdso32=0; otherwise, the default is vdso32=1. + + For compatibility with older kernels, vdso32=2 is an + alias for vdso32=0. + + Try vdso32=0 if you encounter an error that says: + dl_main: Assertion `(void *) ph->p_vaddr == _rtld_local._dl_sysinfo_dso' failed! + + vector= [IA-64,SMP] + vector=percpu: enable percpu vector domain + + video= [FB] Frame buffer configuration + See Documentation/fb/modedb.txt. + + video.brightness_switch_enabled= [0,1] + If set to 1, on receiving an ACPI notify event + generated by hotkey, video driver will adjust brightness + level and then send out the event to user space through + the allocated input device; If set to 0, video driver + will only send out the event without touching backlight + brightness level. + default: 1 + + virtio_mmio.device= + [VMMIO] Memory mapped virtio (platform) device. + + @:[:] + where: + := size (can use standard suffixes + like K, M and G) + := physical base address + := interrupt number (as passed to + request_irq()) + := (optional) platform device id + example: + virtio_mmio.device=1K@0x100b0000:48:7 + + Can be used multiple times for multiple devices. + + vga= [BOOT,X86-32] Select a particular video mode + See Documentation/x86/boot.txt and + Documentation/svga.txt. + Use vga=ask for menu. + This is actually a boot loader parameter; the value is + passed to the kernel using a special protocol. + + vmalloc=nn[KMG] [KNL,BOOT] Forces the vmalloc area to have an exact + size of . This can be used to increase the + minimum size (128MB on x86). It can also be used to + decrease the size and leave more room for directly + mapped kernel RAM. + + vmhalt= [KNL,S390] Perform z/VM CP command after system halt. + Format: + + vmpanic= [KNL,S390] Perform z/VM CP command after kernel panic. + Format: + + vmpoff= [KNL,S390] Perform z/VM CP command after power off. + Format: + + vsyscall= [X86-64] + Controls the behavior of vsyscalls (i.e. calls to + fixed addresses of 0xffffffffff600x00 from legacy + code). Most statically-linked binaries and older + versions of glibc use these calls. Because these + functions are at fixed addresses, they make nice + targets for exploits that can control RIP. + + emulate [default] Vsyscalls turn into traps and are + emulated reasonably safely. + + native Vsyscalls are native syscall instructions. + This is a little bit faster than trapping + and makes a few dynamic recompilers work + better than they would in emulation mode. + It also makes exploits much easier to write. + + none Vsyscalls don't work at all. This makes + them quite hard to use for exploits but + might break your system. + + vt.color= [VT] Default text color. + Format: 0xYX, X = foreground, Y = background. + Default: 0x07 = light gray on black. + + vt.cur_default= [VT] Default cursor shape. + Format: 0xCCBBAA, where AA, BB, and CC are the same as + the parameters of the [?A;B;Cc escape sequence; + see VGA-softcursor.txt. Default: 2 = underline. + + vt.default_blu= [VT] + Format: ,,,..., + Change the default blue palette of the console. + This is a 16-member array composed of values + ranging from 0-255. + + vt.default_grn= [VT] + Format: ,,,..., + Change the default green palette of the console. + This is a 16-member array composed of values + ranging from 0-255. + + vt.default_red= [VT] + Format: ,,,..., + Change the default red palette of the console. + This is a 16-member array composed of values + ranging from 0-255. + + vt.default_utf8= + [VT] + Format=<0|1> + Set system-wide default UTF-8 mode for all tty's. + Default is 1, i.e. UTF-8 mode is enabled for all + newly opened terminals. + + vt.global_cursor_default= + [VT] + Format=<-1|0|1> + Set system-wide default for whether a cursor + is shown on new VTs. Default is -1, + i.e. cursors will be created by default unless + overridden by individual drivers. 0 will hide + cursors, 1 will display them. + + vt.italic= [VT] Default color for italic text; 0-15. + Default: 2 = green. + + vt.underline= [VT] Default color for underlined text; 0-15. + Default: 3 = cyan. + + watchdog timers [HW,WDT] For information on watchdog timers, + see Documentation/watchdog/watchdog-parameters.txt + or other driver-specific files in the + Documentation/watchdog/ directory. + + workqueue.watchdog_thresh= + If CONFIG_WQ_WATCHDOG is configured, workqueue can + warn stall conditions and dump internal state to + help debugging. 0 disables workqueue stall + detection; otherwise, it's the stall threshold + duration in seconds. The default value is 30 and + it can be updated at runtime by writing to the + corresponding sysfs file. + + workqueue.disable_numa + By default, all work items queued to unbound + workqueues are affine to the NUMA nodes they're + issued on, which results in better behavior in + general. If NUMA affinity needs to be disabled for + whatever reason, this option can be used. Note + that this also can be controlled per-workqueue for + workqueues visible under /sys/bus/workqueue/. + + workqueue.power_efficient + Per-cpu workqueues are generally preferred because + they show better performance thanks to cache + locality; unfortunately, per-cpu workqueues tend to + be more power hungry than unbound workqueues. + + Enabling this makes the per-cpu workqueues which + were observed to contribute significantly to power + consumption unbound, leading to measurably lower + power usage at the cost of small performance + overhead. + + The default value of this parameter is determined by + the config option CONFIG_WQ_POWER_EFFICIENT_DEFAULT. + + workqueue.debug_force_rr_cpu + Workqueue used to implicitly guarantee that work + items queued without explicit CPU specified are put + on the local CPU. This guarantee is no longer true + and while local CPU is still preferred work items + may be put on foreign CPUs. This debug option + forces round-robin CPU selection to flush out + usages which depend on the now broken guarantee. + When enabled, memory and cache locality will be + impacted. + + x2apic_phys [X86-64,APIC] Use x2apic physical mode instead of + default x2apic cluster mode on platforms + supporting x2apic. + + x86_intel_mid_timer= [X86-32,APBT] + Choose timer option for x86 Intel MID platform. + Two valid options are apbt timer only and lapic timer + plus one apbt timer for broadcast timer. + x86_intel_mid_timer=apbt_only | lapic_and_apbt + + xen_512gb_limit [KNL,X86-64,XEN] + Restricts the kernel running paravirtualized under Xen + to use only up to 512 GB of RAM. The reason to do so is + crash analysis tools and Xen tools for doing domain + save/restore/migration must be enabled to handle larger + domains. + + xen_emul_unplug= [HW,X86,XEN] + Unplug Xen emulated devices + Format: [unplug0,][unplug1] + ide-disks -- unplug primary master IDE devices + aux-ide-disks -- unplug non-primary-master IDE devices + nics -- unplug network devices + all -- unplug all emulated devices (NICs and IDE disks) + unnecessary -- unplugging emulated devices is + unnecessary even if the host did not respond to + the unplug protocol + never -- do not unplug even if version check succeeds + + xen_nopvspin [X86,XEN] + Disables the ticketlock slowpath using Xen PV + optimizations. + + xen_nopv [X86] + Disables the PV optimizations forcing the HVM guest to + run as generic HVM guest with no PV drivers. + + xirc2ps_cs= [NET,PCMCIA] + Format: + ,,,,,[,[,[,]]] -- cgit v1.2.3 From 07c7e30c1885393b07efcaf62d51b219755b6bf5 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 3 Nov 2016 12:11:50 +0200 Subject: Documentation/admin-guide: split the device list to a separate file Include the literal device list from a separate file. This helps the pdf build. Signed-off-by: Jani Nikula --- Documentation/admin-guide/devices.rst | 3086 +-------------------------------- Documentation/admin-guide/devices.txt | 3081 ++++++++++++++++++++++++++++++++ 2 files changed, 3083 insertions(+), 3084 deletions(-) create mode 100644 Documentation/admin-guide/devices.txt diff --git a/Documentation/admin-guide/devices.rst b/Documentation/admin-guide/devices.rst index 89db341fba7a..7fadc05330dd 100644 --- a/Documentation/admin-guide/devices.rst +++ b/Documentation/admin-guide/devices.rst @@ -56,3090 +56,8 @@ an unreasonable effort. Your cooperation is appreciated. -:: - - 0 Unnamed devices (e.g. non-device mounts) - 0 = reserved as null device number - See block major 144, 145, 146 for expansion areas. - - 1 char Memory devices - 1 = /dev/mem Physical memory access - 2 = /dev/kmem Kernel virtual memory access - 3 = /dev/null Null device - 4 = /dev/port I/O port access - 5 = /dev/zero Null byte source - 6 = /dev/core OBSOLETE - replaced by /proc/kcore - 7 = /dev/full Returns ENOSPC on write - 8 = /dev/random Nondeterministic random number gen. - 9 = /dev/urandom Faster, less secure random number gen. - 10 = /dev/aio Asynchronous I/O notification interface - 11 = /dev/kmsg Writes to this come out as printk's, reads - export the buffered printk records. - 12 = /dev/oldmem OBSOLETE - replaced by /proc/vmcore - - 1 block RAM disk - 0 = /dev/ram0 First RAM disk - 1 = /dev/ram1 Second RAM disk - ... - 250 = /dev/initrd Initial RAM disk - - Older kernels had /dev/ramdisk (1, 1) here. - /dev/initrd refers to a RAM disk which was preloaded - by the boot loader; newer kernels use /dev/ram0 for - the initrd. - - 2 char Pseudo-TTY masters - 0 = /dev/ptyp0 First PTY master - 1 = /dev/ptyp1 Second PTY master - ... - 255 = /dev/ptyef 256th PTY master - - Pseudo-tty's are named as follows: - * Masters are "pty", slaves are "tty"; - * the fourth letter is one of pqrstuvwxyzabcde indicating - the 1st through 16th series of 16 pseudo-ttys each, and - * the fifth letter is one of 0123456789abcdef indicating - the position within the series. - - These are the old-style (BSD) PTY devices; Unix98 - devices are on major 128 and above and use the PTY - master multiplex (/dev/ptmx) to acquire a PTY on - demand. - - 2 block Floppy disks - 0 = /dev/fd0 Controller 0, drive 0, autodetect - 1 = /dev/fd1 Controller 0, drive 1, autodetect - 2 = /dev/fd2 Controller 0, drive 2, autodetect - 3 = /dev/fd3 Controller 0, drive 3, autodetect - 128 = /dev/fd4 Controller 1, drive 0, autodetect - 129 = /dev/fd5 Controller 1, drive 1, autodetect - 130 = /dev/fd6 Controller 1, drive 2, autodetect - 131 = /dev/fd7 Controller 1, drive 3, autodetect - - To specify format, add to the autodetect device number: - 0 = /dev/fd? Autodetect format - 4 = /dev/fd?d360 5.25" 360K in a 360K drive(1) - 20 = /dev/fd?h360 5.25" 360K in a 1200K drive(1) - 48 = /dev/fd?h410 5.25" 410K in a 1200K drive - 64 = /dev/fd?h420 5.25" 420K in a 1200K drive - 24 = /dev/fd?h720 5.25" 720K in a 1200K drive - 80 = /dev/fd?h880 5.25" 880K in a 1200K drive(1) - 8 = /dev/fd?h1200 5.25" 1200K in a 1200K drive(1) - 40 = /dev/fd?h1440 5.25" 1440K in a 1200K drive(1) - 56 = /dev/fd?h1476 5.25" 1476K in a 1200K drive - 72 = /dev/fd?h1494 5.25" 1494K in a 1200K drive - 92 = /dev/fd?h1600 5.25" 1600K in a 1200K drive(1) - - 12 = /dev/fd?u360 3.5" 360K Double Density(2) - 16 = /dev/fd?u720 3.5" 720K Double Density(1) - 120 = /dev/fd?u800 3.5" 800K Double Density(2) - 52 = /dev/fd?u820 3.5" 820K Double Density - 68 = /dev/fd?u830 3.5" 830K Double Density - 84 = /dev/fd?u1040 3.5" 1040K Double Density(1) - 88 = /dev/fd?u1120 3.5" 1120K Double Density(1) - 28 = /dev/fd?u1440 3.5" 1440K High Density(1) - 124 = /dev/fd?u1600 3.5" 1600K High Density(1) - 44 = /dev/fd?u1680 3.5" 1680K High Density(3) - 60 = /dev/fd?u1722 3.5" 1722K High Density - 76 = /dev/fd?u1743 3.5" 1743K High Density - 96 = /dev/fd?u1760 3.5" 1760K High Density - 116 = /dev/fd?u1840 3.5" 1840K High Density(3) - 100 = /dev/fd?u1920 3.5" 1920K High Density(1) - 32 = /dev/fd?u2880 3.5" 2880K Extra Density(1) - 104 = /dev/fd?u3200 3.5" 3200K Extra Density - 108 = /dev/fd?u3520 3.5" 3520K Extra Density - 112 = /dev/fd?u3840 3.5" 3840K Extra Density(1) - - 36 = /dev/fd?CompaQ Compaq 2880K drive; obsolete? - - (1) Autodetectable format - (2) Autodetectable format in a Double Density (720K) drive only - (3) Autodetectable format in a High Density (1440K) drive only - - NOTE: The letter in the device name (d, q, h or u) - signifies the type of drive: 5.25" Double Density (d), - 5.25" Quad Density (q), 5.25" High Density (h) or 3.5" - (any model, u). The use of the capital letters D, H - and E for the 3.5" models have been deprecated, since - the drive type is insignificant for these devices. - - 3 char Pseudo-TTY slaves - 0 = /dev/ttyp0 First PTY slave - 1 = /dev/ttyp1 Second PTY slave - ... - 255 = /dev/ttyef 256th PTY slave - - These are the old-style (BSD) PTY devices; Unix98 - devices are on major 136 and above. - - 3 block First MFM, RLL and IDE hard disk/CD-ROM interface - 0 = /dev/hda Master: whole disk (or CD-ROM) - 64 = /dev/hdb Slave: whole disk (or CD-ROM) - - For partitions, add to the whole disk device number: - 0 = /dev/hd? Whole disk - 1 = /dev/hd?1 First partition - 2 = /dev/hd?2 Second partition - ... - 63 = /dev/hd?63 63rd partition - - For Linux/i386, partitions 1-4 are the primary - partitions, and 5 and above are logical partitions. - Other versions of Linux use partitioning schemes - appropriate to their respective architectures. - - 4 char TTY devices - 0 = /dev/tty0 Current virtual console - - 1 = /dev/tty1 First virtual console - ... - 63 = /dev/tty63 63rd virtual console - 64 = /dev/ttyS0 First UART serial port - ... - 255 = /dev/ttyS191 192nd UART serial port - - UART serial ports refer to 8250/16450/16550 series devices. - - Older versions of the Linux kernel used this major - number for BSD PTY devices. As of Linux 2.1.115, this - is no longer supported. Use major numbers 2 and 3. - - 4 block Aliases for dynamically allocated major devices to be used - when its not possible to create the real device nodes - because the root filesystem is mounted read-only. - - 0 = /dev/root - - 5 char Alternate TTY devices - 0 = /dev/tty Current TTY device - 1 = /dev/console System console - 2 = /dev/ptmx PTY master multiplex - 3 = /dev/ttyprintk User messages via printk TTY device - 64 = /dev/cua0 Callout device for ttyS0 - ... - 255 = /dev/cua191 Callout device for ttyS191 - - (5,1) is /dev/console starting with Linux 2.1.71. See - the section on terminal devices for more information - on /dev/console. - - 6 char Parallel printer devices - 0 = /dev/lp0 Parallel printer on parport0 - 1 = /dev/lp1 Parallel printer on parport1 - ... - - Current Linux kernels no longer have a fixed mapping - between parallel ports and I/O addresses. Instead, - they are redirected through the parport multiplex layer. - - 7 char Virtual console capture devices - 0 = /dev/vcs Current vc text contents - 1 = /dev/vcs1 tty1 text contents - ... - 63 = /dev/vcs63 tty63 text contents - 128 = /dev/vcsa Current vc text/attribute contents - 129 = /dev/vcsa1 tty1 text/attribute contents - ... - 191 = /dev/vcsa63 tty63 text/attribute contents - - NOTE: These devices permit both read and write access. - - 7 block Loopback devices - 0 = /dev/loop0 First loop device - 1 = /dev/loop1 Second loop device - ... - - The loop devices are used to mount filesystems not - associated with block devices. The binding to the - loop devices is handled by mount(8) or losetup(8). - - 8 block SCSI disk devices (0-15) - 0 = /dev/sda First SCSI disk whole disk - 16 = /dev/sdb Second SCSI disk whole disk - 32 = /dev/sdc Third SCSI disk whole disk - ... - 240 = /dev/sdp Sixteenth SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 9 char SCSI tape devices - 0 = /dev/st0 First SCSI tape, mode 0 - 1 = /dev/st1 Second SCSI tape, mode 0 - ... - 32 = /dev/st0l First SCSI tape, mode 1 - 33 = /dev/st1l Second SCSI tape, mode 1 - ... - 64 = /dev/st0m First SCSI tape, mode 2 - 65 = /dev/st1m Second SCSI tape, mode 2 - ... - 96 = /dev/st0a First SCSI tape, mode 3 - 97 = /dev/st1a Second SCSI tape, mode 3 - ... - 128 = /dev/nst0 First SCSI tape, mode 0, no rewind - 129 = /dev/nst1 Second SCSI tape, mode 0, no rewind - ... - 160 = /dev/nst0l First SCSI tape, mode 1, no rewind - 161 = /dev/nst1l Second SCSI tape, mode 1, no rewind - ... - 192 = /dev/nst0m First SCSI tape, mode 2, no rewind - 193 = /dev/nst1m Second SCSI tape, mode 2, no rewind - ... - 224 = /dev/nst0a First SCSI tape, mode 3, no rewind - 225 = /dev/nst1a Second SCSI tape, mode 3, no rewind - ... - - "No rewind" refers to the omission of the default - automatic rewind on device close. The MTREW or MTOFFL - ioctl()'s can be used to rewind the tape regardless of - the device used to access it. - - 9 block Metadisk (RAID) devices - 0 = /dev/md0 First metadisk group - 1 = /dev/md1 Second metadisk group - ... - - The metadisk driver is used to span a - filesystem across multiple physical disks. - - 10 char Non-serial mice, misc features - 0 = /dev/logibm Logitech bus mouse - 1 = /dev/psaux PS/2-style mouse port - 2 = /dev/inportbm Microsoft Inport bus mouse - 3 = /dev/atibm ATI XL bus mouse - 4 = /dev/jbm J-mouse - 4 = /dev/amigamouse Amiga mouse (68k/Amiga) - 5 = /dev/atarimouse Atari mouse - 6 = /dev/sunmouse Sun mouse - 7 = /dev/amigamouse1 Second Amiga mouse - 8 = /dev/smouse Simple serial mouse driver - 9 = /dev/pc110pad IBM PC-110 digitizer pad - 10 = /dev/adbmouse Apple Desktop Bus mouse - 11 = /dev/vrtpanel Vr41xx embedded touch panel - 13 = /dev/vpcmouse Connectix Virtual PC Mouse - 14 = /dev/touchscreen/ucb1x00 UCB 1x00 touchscreen - 15 = /dev/touchscreen/mk712 MK712 touchscreen - 128 = /dev/beep Fancy beep device - 129 = - 130 = /dev/watchdog Watchdog timer port - 131 = /dev/temperature Machine internal temperature - 132 = /dev/hwtrap Hardware fault trap - 133 = /dev/exttrp External device trap - 134 = /dev/apm_bios Advanced Power Management BIOS - 135 = /dev/rtc Real Time Clock - 137 = /dev/vhci Bluetooth virtual HCI driver - 139 = /dev/openprom SPARC OpenBoot PROM - 140 = /dev/relay8 Berkshire Products Octal relay card - 141 = /dev/relay16 Berkshire Products ISO-16 relay card - 142 = - 143 = /dev/pciconf PCI configuration space - 144 = /dev/nvram Non-volatile configuration RAM - 145 = /dev/hfmodem Soundcard shortwave modem control - 146 = /dev/graphics Linux/SGI graphics device - 147 = /dev/opengl Linux/SGI OpenGL pipe - 148 = /dev/gfx Linux/SGI graphics effects device - 149 = /dev/input/mouse Linux/SGI Irix emulation mouse - 150 = /dev/input/keyboard Linux/SGI Irix emulation keyboard - 151 = /dev/led Front panel LEDs - 152 = /dev/kpoll Kernel Poll Driver - 153 = /dev/mergemem Memory merge device - 154 = /dev/pmu Macintosh PowerBook power manager - 155 = /dev/isictl MultiTech ISICom serial control - 156 = /dev/lcd Front panel LCD display - 157 = /dev/ac Applicom Intl Profibus card - 158 = /dev/nwbutton Netwinder external button - 159 = /dev/nwdebug Netwinder debug interface - 160 = /dev/nwflash Netwinder flash memory - 161 = /dev/userdma User-space DMA access - 162 = /dev/smbus System Management Bus - 163 = /dev/lik Logitech Internet Keyboard - 164 = /dev/ipmo Intel Intelligent Platform Management - 165 = /dev/vmmon VMware virtual machine monitor - 166 = /dev/i2o/ctl I2O configuration manager - 167 = /dev/specialix_sxctl Specialix serial control - 168 = /dev/tcldrv Technology Concepts serial control - 169 = /dev/specialix_rioctl Specialix RIO serial control - 170 = /dev/thinkpad/thinkpad IBM Thinkpad devices - 171 = /dev/srripc QNX4 API IPC manager - 172 = /dev/usemaclone Semaphore clone device - 173 = /dev/ipmikcs Intelligent Platform Management - 174 = /dev/uctrl SPARCbook 3 microcontroller - 175 = /dev/agpgart AGP Graphics Address Remapping Table - 176 = /dev/gtrsc Gorgy Timing radio clock - 177 = /dev/cbm Serial CBM bus - 178 = /dev/jsflash JavaStation OS flash SIMM - 179 = /dev/xsvc High-speed shared-mem/semaphore service - 180 = /dev/vrbuttons Vr41xx button input device - 181 = /dev/toshiba Toshiba laptop SMM support - 182 = /dev/perfctr Performance-monitoring counters - 183 = /dev/hwrng Generic random number generator - 184 = /dev/cpu/microcode CPU microcode update interface - 186 = /dev/atomicps Atomic shapshot of process state data - 187 = /dev/irnet IrNET device - 188 = /dev/smbusbios SMBus BIOS - 189 = /dev/ussp_ctl User space serial port control - 190 = /dev/crash Mission Critical Linux crash dump facility - 191 = /dev/pcl181 - 192 = /dev/nas_xbus NAS xbus LCD/buttons access - 193 = /dev/d7s SPARC 7-segment display - 194 = /dev/zkshim Zero-Knowledge network shim control - 195 = /dev/elographics/e2201 Elographics touchscreen E271-2201 - 196 = /dev/vfio/vfio VFIO userspace driver interface - 197 = /dev/pxa3xx-gcu PXA3xx graphics controller unit driver - 198 = /dev/sexec Signed executable interface - 199 = /dev/scanners/cuecat :CueCat barcode scanner - 200 = /dev/net/tun TAP/TUN network device - 201 = /dev/button/gulpb Transmeta GULP-B buttons - 202 = /dev/emd/ctl Enhanced Metadisk RAID (EMD) control - 203 = /dev/cuse Cuse (character device in user-space) - 204 = /dev/video/em8300 EM8300 DVD decoder control - 205 = /dev/video/em8300_mv EM8300 DVD decoder video - 206 = /dev/video/em8300_ma EM8300 DVD decoder audio - 207 = /dev/video/em8300_sp EM8300 DVD decoder subpicture - 208 = /dev/compaq/cpqphpc Compaq PCI Hot Plug Controller - 209 = /dev/compaq/cpqrid Compaq Remote Insight Driver - 210 = /dev/impi/bt IMPI coprocessor block transfer - 211 = /dev/impi/smic IMPI coprocessor stream interface - 212 = /dev/watchdogs/0 First watchdog device - 213 = /dev/watchdogs/1 Second watchdog device - 214 = /dev/watchdogs/2 Third watchdog device - 215 = /dev/watchdogs/3 Fourth watchdog device - 216 = /dev/fujitsu/apanel Fujitsu/Siemens application panel - 217 = /dev/ni/natmotn National Instruments Motion - 218 = /dev/kchuid Inter-process chuid control - 219 = /dev/modems/mwave MWave modem firmware upload - 220 = /dev/mptctl Message passing technology (MPT) control - 221 = /dev/mvista/hssdsi Montavista PICMG hot swap system driver - 222 = /dev/mvista/hasi Montavista PICMG high availability - 223 = /dev/input/uinput User level driver support for input - 224 = /dev/tpm TCPA TPM driver - 225 = /dev/pps Pulse Per Second driver - 226 = /dev/systrace Systrace device - 227 = /dev/mcelog X86_64 Machine Check Exception driver - 228 = /dev/hpet HPET driver - 229 = /dev/fuse Fuse (virtual filesystem in user-space) - 230 = /dev/midishare MidiShare driver - 231 = /dev/snapshot System memory snapshot device - 232 = /dev/kvm Kernel-based virtual machine (hardware virtualization extensions) - 233 = /dev/kmview View-OS A process with a view - 234 = /dev/btrfs-control Btrfs control device - 235 = /dev/autofs Autofs control device - 236 = /dev/mapper/control Device-Mapper control device - 237 = /dev/loop-control Loopback control device - 238 = /dev/vhost-net Host kernel accelerator for virtio net - 239 = /dev/uhid User-space I/O driver support for HID subsystem - - 240-254 Reserved for local use - 255 Reserved for MISC_DYNAMIC_MINOR - - 11 char Raw keyboard device (Linux/SPARC only) - 0 = /dev/kbd Raw keyboard device - - 11 char Serial Mux device (Linux/PA-RISC only) - 0 = /dev/ttyB0 First mux port - 1 = /dev/ttyB1 Second mux port - ... - - 11 block SCSI CD-ROM devices - 0 = /dev/scd0 First SCSI CD-ROM - 1 = /dev/scd1 Second SCSI CD-ROM - ... - - The prefix /dev/sr (instead of /dev/scd) has been deprecated. - - 12 char QIC-02 tape - 2 = /dev/ntpqic11 QIC-11, no rewind-on-close - 3 = /dev/tpqic11 QIC-11, rewind-on-close - 4 = /dev/ntpqic24 QIC-24, no rewind-on-close - 5 = /dev/tpqic24 QIC-24, rewind-on-close - 6 = /dev/ntpqic120 QIC-120, no rewind-on-close - 7 = /dev/tpqic120 QIC-120, rewind-on-close - 8 = /dev/ntpqic150 QIC-150, no rewind-on-close - 9 = /dev/tpqic150 QIC-150, rewind-on-close - - The device names specified are proposed -- if there - are "standard" names for these devices, please let me know. - - 12 block - - 13 char Input core - 0 = /dev/input/js0 First joystick - 1 = /dev/input/js1 Second joystick - ... - 32 = /dev/input/mouse0 First mouse - 33 = /dev/input/mouse1 Second mouse - ... - 63 = /dev/input/mice Unified mouse - 64 = /dev/input/event0 First event queue - 65 = /dev/input/event1 Second event queue - ... - - Each device type has 5 bits (32 minors). - - 13 block Previously used for the XT disk (/dev/xdN) - Deleted in kernel v3.9. - - 14 char Open Sound System (OSS) - 0 = /dev/mixer Mixer control - 1 = /dev/sequencer Audio sequencer - 2 = /dev/midi00 First MIDI port - 3 = /dev/dsp Digital audio - 4 = /dev/audio Sun-compatible digital audio - 6 = - 7 = /dev/audioctl SPARC audio control device - 8 = /dev/sequencer2 Sequencer -- alternate device - 16 = /dev/mixer1 Second soundcard mixer control - 17 = /dev/patmgr0 Sequencer patch manager - 18 = /dev/midi01 Second MIDI port - 19 = /dev/dsp1 Second soundcard digital audio - 20 = /dev/audio1 Second soundcard Sun digital audio - 33 = /dev/patmgr1 Sequencer patch manager - 34 = /dev/midi02 Third MIDI port - 50 = /dev/midi03 Fourth MIDI port - - 14 block - - 15 char Joystick - 0 = /dev/js0 First analog joystick - 1 = /dev/js1 Second analog joystick - ... - 128 = /dev/djs0 First digital joystick - 129 = /dev/djs1 Second digital joystick - ... - 15 block Sony CDU-31A/CDU-33A CD-ROM - 0 = /dev/sonycd Sony CDU-31a CD-ROM - - 16 char Non-SCSI scanners - 0 = /dev/gs4500 Genius 4500 handheld scanner - - 16 block GoldStar CD-ROM - 0 = /dev/gscd GoldStar CD-ROM - - 17 char OBSOLETE (was Chase serial card) - 0 = /dev/ttyH0 First Chase port - 1 = /dev/ttyH1 Second Chase port - ... - 17 block Optics Storage CD-ROM - 0 = /dev/optcd Optics Storage CD-ROM - - 18 char OBSOLETE (was Chase serial card - alternate devices) - 0 = /dev/cuh0 Callout device for ttyH0 - 1 = /dev/cuh1 Callout device for ttyH1 - ... - 18 block Sanyo CD-ROM - 0 = /dev/sjcd Sanyo CD-ROM - - 19 char Cyclades serial card - 0 = /dev/ttyC0 First Cyclades port - ... - 31 = /dev/ttyC31 32nd Cyclades port - - 19 block "Double" compressed disk - 0 = /dev/double0 First compressed disk - ... - 7 = /dev/double7 Eighth compressed disk - 128 = /dev/cdouble0 Mirror of first compressed disk - ... - 135 = /dev/cdouble7 Mirror of eighth compressed disk - - See the Double documentation for the meaning of the - mirror devices. - - 20 char Cyclades serial card - alternate devices - 0 = /dev/cub0 Callout device for ttyC0 - ... - 31 = /dev/cub31 Callout device for ttyC31 - - 20 block Hitachi CD-ROM (under development) - 0 = /dev/hitcd Hitachi CD-ROM - - 21 char Generic SCSI access - 0 = /dev/sg0 First generic SCSI device - 1 = /dev/sg1 Second generic SCSI device - ... - - Most distributions name these /dev/sga, /dev/sgb...; - this sets an unnecessary limit of 26 SCSI devices in - the system and is counter to standard Linux - device-naming practice. - - 21 block Acorn MFM hard drive interface - 0 = /dev/mfma First MFM drive whole disk - 64 = /dev/mfmb Second MFM drive whole disk - - This device is used on the ARM-based Acorn RiscPC. - Partitions are handled the same way as for IDE disks - (see major number 3). - - 22 char Digiboard serial card - 0 = /dev/ttyD0 First Digiboard port - 1 = /dev/ttyD1 Second Digiboard port - ... - 22 block Second IDE hard disk/CD-ROM interface - 0 = /dev/hdc Master: whole disk (or CD-ROM) - 64 = /dev/hdd Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 23 char Digiboard serial card - alternate devices - 0 = /dev/cud0 Callout device for ttyD0 - 1 = /dev/cud1 Callout device for ttyD1 - ... - 23 block Mitsumi proprietary CD-ROM - 0 = /dev/mcd Mitsumi CD-ROM - - 24 char Stallion serial card - 0 = /dev/ttyE0 Stallion port 0 card 0 - 1 = /dev/ttyE1 Stallion port 1 card 0 - ... - 64 = /dev/ttyE64 Stallion port 0 card 1 - 65 = /dev/ttyE65 Stallion port 1 card 1 - ... - 128 = /dev/ttyE128 Stallion port 0 card 2 - 129 = /dev/ttyE129 Stallion port 1 card 2 - ... - 192 = /dev/ttyE192 Stallion port 0 card 3 - 193 = /dev/ttyE193 Stallion port 1 card 3 - ... - 24 block Sony CDU-535 CD-ROM - 0 = /dev/cdu535 Sony CDU-535 CD-ROM - - 25 char Stallion serial card - alternate devices - 0 = /dev/cue0 Callout device for ttyE0 - 1 = /dev/cue1 Callout device for ttyE1 - ... - 64 = /dev/cue64 Callout device for ttyE64 - 65 = /dev/cue65 Callout device for ttyE65 - ... - 128 = /dev/cue128 Callout device for ttyE128 - 129 = /dev/cue129 Callout device for ttyE129 - ... - 192 = /dev/cue192 Callout device for ttyE192 - 193 = /dev/cue193 Callout device for ttyE193 - ... - 25 block First Matsushita (Panasonic/SoundBlaster) CD-ROM - 0 = /dev/sbpcd0 Panasonic CD-ROM controller 0 unit 0 - 1 = /dev/sbpcd1 Panasonic CD-ROM controller 0 unit 1 - 2 = /dev/sbpcd2 Panasonic CD-ROM controller 0 unit 2 - 3 = /dev/sbpcd3 Panasonic CD-ROM controller 0 unit 3 - - 26 char - - 26 block Second Matsushita (Panasonic/SoundBlaster) CD-ROM - 0 = /dev/sbpcd4 Panasonic CD-ROM controller 1 unit 0 - 1 = /dev/sbpcd5 Panasonic CD-ROM controller 1 unit 1 - 2 = /dev/sbpcd6 Panasonic CD-ROM controller 1 unit 2 - 3 = /dev/sbpcd7 Panasonic CD-ROM controller 1 unit 3 - - 27 char QIC-117 tape - 0 = /dev/qft0 Unit 0, rewind-on-close - 1 = /dev/qft1 Unit 1, rewind-on-close - 2 = /dev/qft2 Unit 2, rewind-on-close - 3 = /dev/qft3 Unit 3, rewind-on-close - 4 = /dev/nqft0 Unit 0, no rewind-on-close - 5 = /dev/nqft1 Unit 1, no rewind-on-close - 6 = /dev/nqft2 Unit 2, no rewind-on-close - 7 = /dev/nqft3 Unit 3, no rewind-on-close - 16 = /dev/zqft0 Unit 0, rewind-on-close, compression - 17 = /dev/zqft1 Unit 1, rewind-on-close, compression - 18 = /dev/zqft2 Unit 2, rewind-on-close, compression - 19 = /dev/zqft3 Unit 3, rewind-on-close, compression - 20 = /dev/nzqft0 Unit 0, no rewind-on-close, compression - 21 = /dev/nzqft1 Unit 1, no rewind-on-close, compression - 22 = /dev/nzqft2 Unit 2, no rewind-on-close, compression - 23 = /dev/nzqft3 Unit 3, no rewind-on-close, compression - 32 = /dev/rawqft0 Unit 0, rewind-on-close, no file marks - 33 = /dev/rawqft1 Unit 1, rewind-on-close, no file marks - 34 = /dev/rawqft2 Unit 2, rewind-on-close, no file marks - 35 = /dev/rawqft3 Unit 3, rewind-on-close, no file marks - 36 = /dev/nrawqft0 Unit 0, no rewind-on-close, no file marks - 37 = /dev/nrawqft1 Unit 1, no rewind-on-close, no file marks - 38 = /dev/nrawqft2 Unit 2, no rewind-on-close, no file marks - 39 = /dev/nrawqft3 Unit 3, no rewind-on-close, no file marks - - 27 block Third Matsushita (Panasonic/SoundBlaster) CD-ROM - 0 = /dev/sbpcd8 Panasonic CD-ROM controller 2 unit 0 - 1 = /dev/sbpcd9 Panasonic CD-ROM controller 2 unit 1 - 2 = /dev/sbpcd10 Panasonic CD-ROM controller 2 unit 2 - 3 = /dev/sbpcd11 Panasonic CD-ROM controller 2 unit 3 - - 28 char Stallion serial card - card programming - 0 = /dev/staliomem0 First Stallion card I/O memory - 1 = /dev/staliomem1 Second Stallion card I/O memory - 2 = /dev/staliomem2 Third Stallion card I/O memory - 3 = /dev/staliomem3 Fourth Stallion card I/O memory - - 28 char Atari SLM ACSI laser printer (68k/Atari) - 0 = /dev/slm0 First SLM laser printer - 1 = /dev/slm1 Second SLM laser printer - ... - 28 block Fourth Matsushita (Panasonic/SoundBlaster) CD-ROM - 0 = /dev/sbpcd12 Panasonic CD-ROM controller 3 unit 0 - 1 = /dev/sbpcd13 Panasonic CD-ROM controller 3 unit 1 - 2 = /dev/sbpcd14 Panasonic CD-ROM controller 3 unit 2 - 3 = /dev/sbpcd15 Panasonic CD-ROM controller 3 unit 3 - - 28 block ACSI disk (68k/Atari) - 0 = /dev/ada First ACSI disk whole disk - 16 = /dev/adb Second ACSI disk whole disk - 32 = /dev/adc Third ACSI disk whole disk - ... - 240 = /dev/adp 16th ACSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15, like SCSI. - - 29 char Universal frame buffer - 0 = /dev/fb0 First frame buffer - 1 = /dev/fb1 Second frame buffer - ... - 31 = /dev/fb31 32nd frame buffer - - 29 block Aztech/Orchid/Okano/Wearnes CD-ROM - 0 = /dev/aztcd Aztech CD-ROM - - 30 char iBCS-2 compatibility devices - 0 = /dev/socksys Socket access - 1 = /dev/spx SVR3 local X interface - 32 = /dev/inet/ip Network access - 33 = /dev/inet/icmp - 34 = /dev/inet/ggp - 35 = /dev/inet/ipip - 36 = /dev/inet/tcp - 37 = /dev/inet/egp - 38 = /dev/inet/pup - 39 = /dev/inet/udp - 40 = /dev/inet/idp - 41 = /dev/inet/rawip - - Additionally, iBCS-2 requires the following links: - - /dev/ip -> /dev/inet/ip - /dev/icmp -> /dev/inet/icmp - /dev/ggp -> /dev/inet/ggp - /dev/ipip -> /dev/inet/ipip - /dev/tcp -> /dev/inet/tcp - /dev/egp -> /dev/inet/egp - /dev/pup -> /dev/inet/pup - /dev/udp -> /dev/inet/udp - /dev/idp -> /dev/inet/idp - /dev/rawip -> /dev/inet/rawip - /dev/inet/arp -> /dev/inet/udp - /dev/inet/rip -> /dev/inet/udp - /dev/nfsd -> /dev/socksys - /dev/X0R -> /dev/null (? apparently not required ?) - - 30 block Philips LMS CM-205 CD-ROM - 0 = /dev/cm205cd Philips LMS CM-205 CD-ROM - - /dev/lmscd is an older name for this device. This - driver does not work with the CM-205MS CD-ROM. - - 31 char MPU-401 MIDI - 0 = /dev/mpu401data MPU-401 data port - 1 = /dev/mpu401stat MPU-401 status port - - 31 block ROM/flash memory card - 0 = /dev/rom0 First ROM card (rw) - ... - 7 = /dev/rom7 Eighth ROM card (rw) - 8 = /dev/rrom0 First ROM card (ro) - ... - 15 = /dev/rrom7 Eighth ROM card (ro) - 16 = /dev/flash0 First flash memory card (rw) - ... - 23 = /dev/flash7 Eighth flash memory card (rw) - 24 = /dev/rflash0 First flash memory card (ro) - ... - 31 = /dev/rflash7 Eighth flash memory card (ro) - - The read-write (rw) devices support back-caching - written data in RAM, as well as writing to flash RAM - devices. The read-only devices (ro) support reading - only. - - 32 char Specialix serial card - 0 = /dev/ttyX0 First Specialix port - 1 = /dev/ttyX1 Second Specialix port - ... - 32 block Philips LMS CM-206 CD-ROM - 0 = /dev/cm206cd Philips LMS CM-206 CD-ROM - - 33 char Specialix serial card - alternate devices - 0 = /dev/cux0 Callout device for ttyX0 - 1 = /dev/cux1 Callout device for ttyX1 - ... - 33 block Third IDE hard disk/CD-ROM interface - 0 = /dev/hde Master: whole disk (or CD-ROM) - 64 = /dev/hdf Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 34 char Z8530 HDLC driver - 0 = /dev/scc0 First Z8530, first port - 1 = /dev/scc1 First Z8530, second port - 2 = /dev/scc2 Second Z8530, first port - 3 = /dev/scc3 Second Z8530, second port - ... - - In a previous version these devices were named - /dev/sc1 for /dev/scc0, /dev/sc2 for /dev/scc1, and so - on. - - 34 block Fourth IDE hard disk/CD-ROM interface - 0 = /dev/hdg Master: whole disk (or CD-ROM) - 64 = /dev/hdh Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 35 char tclmidi MIDI driver - 0 = /dev/midi0 First MIDI port, kernel timed - 1 = /dev/midi1 Second MIDI port, kernel timed - 2 = /dev/midi2 Third MIDI port, kernel timed - 3 = /dev/midi3 Fourth MIDI port, kernel timed - 64 = /dev/rmidi0 First MIDI port, untimed - 65 = /dev/rmidi1 Second MIDI port, untimed - 66 = /dev/rmidi2 Third MIDI port, untimed - 67 = /dev/rmidi3 Fourth MIDI port, untimed - 128 = /dev/smpte0 First MIDI port, SMPTE timed - 129 = /dev/smpte1 Second MIDI port, SMPTE timed - 130 = /dev/smpte2 Third MIDI port, SMPTE timed - 131 = /dev/smpte3 Fourth MIDI port, SMPTE timed - - 35 block Slow memory ramdisk - 0 = /dev/slram Slow memory ramdisk - - 36 char Netlink support - 0 = /dev/route Routing, device updates, kernel to user - 1 = /dev/skip enSKIP security cache control - 3 = /dev/fwmonitor Firewall packet copies - 16 = /dev/tap0 First Ethertap device - ... - 31 = /dev/tap15 16th Ethertap device - - 36 block OBSOLETE (was MCA ESDI hard disk) - - 37 char IDE tape - 0 = /dev/ht0 First IDE tape - 1 = /dev/ht1 Second IDE tape - ... - 128 = /dev/nht0 First IDE tape, no rewind-on-close - 129 = /dev/nht1 Second IDE tape, no rewind-on-close - ... - - Currently, only one IDE tape drive is supported. - - 37 block Zorro II ramdisk - 0 = /dev/z2ram Zorro II ramdisk - - 38 char Myricom PCI Myrinet board - 0 = /dev/mlanai0 First Myrinet board - 1 = /dev/mlanai1 Second Myrinet board - ... - - This device is used for status query, board control - and "user level packet I/O." This board is also - accessible as a standard networking "eth" device. - - 38 block OBSOLETE (was Linux/AP+) - - 39 char ML-16P experimental I/O board - 0 = /dev/ml16pa-a0 First card, first analog channel - 1 = /dev/ml16pa-a1 First card, second analog channel - ... - 15 = /dev/ml16pa-a15 First card, 16th analog channel - 16 = /dev/ml16pa-d First card, digital lines - 17 = /dev/ml16pa-c0 First card, first counter/timer - 18 = /dev/ml16pa-c1 First card, second counter/timer - 19 = /dev/ml16pa-c2 First card, third counter/timer - 32 = /dev/ml16pb-a0 Second card, first analog channel - 33 = /dev/ml16pb-a1 Second card, second analog channel - ... - 47 = /dev/ml16pb-a15 Second card, 16th analog channel - 48 = /dev/ml16pb-d Second card, digital lines - 49 = /dev/ml16pb-c0 Second card, first counter/timer - 50 = /dev/ml16pb-c1 Second card, second counter/timer - 51 = /dev/ml16pb-c2 Second card, third counter/timer - ... - 39 block - - 40 char - - 40 block - - 41 char Yet Another Micro Monitor - 0 = /dev/yamm Yet Another Micro Monitor - - 41 block - - 42 char Demo/sample use - - 42 block Demo/sample use - - This number is intended for use in sample code, as - well as a general "example" device number. It - should never be used for a device driver that is being - distributed; either obtain an official number or use - the local/experimental range. The sudden addition or - removal of a driver with this number should not cause - ill effects to the system (bugs excepted.) - - IN PARTICULAR, ANY DISTRIBUTION WHICH CONTAINS A - DEVICE DRIVER USING MAJOR NUMBER 42 IS NONCOMPLIANT. - - 43 char isdn4linux virtual modem - 0 = /dev/ttyI0 First virtual modem - ... - 63 = /dev/ttyI63 64th virtual modem - - 43 block Network block devices - 0 = /dev/nb0 First network block device - 1 = /dev/nb1 Second network block device - ... - - Network Block Device is somehow similar to loopback - devices: If you read from it, it sends packet across - network asking server for data. If you write to it, it - sends packet telling server to write. It could be used - to mounting filesystems over the net, swapping over - the net, implementing block device in userland etc. - - 44 char isdn4linux virtual modem - alternate devices - 0 = /dev/cui0 Callout device for ttyI0 - ... - 63 = /dev/cui63 Callout device for ttyI63 - - 44 block Flash Translation Layer (FTL) filesystems - 0 = /dev/ftla FTL on first Memory Technology Device - 16 = /dev/ftlb FTL on second Memory Technology Device - 32 = /dev/ftlc FTL on third Memory Technology Device - ... - 240 = /dev/ftlp FTL on 16th Memory Technology Device - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the partition - limit is 15 rather than 63 per disk (same as SCSI.) - - 45 char isdn4linux ISDN BRI driver - 0 = /dev/isdn0 First virtual B channel raw data - ... - 63 = /dev/isdn63 64th virtual B channel raw data - 64 = /dev/isdnctrl0 First channel control/debug - ... - 127 = /dev/isdnctrl63 64th channel control/debug - - 128 = /dev/ippp0 First SyncPPP device - ... - 191 = /dev/ippp63 64th SyncPPP device - - 255 = /dev/isdninfo ISDN monitor interface - - 45 block Parallel port IDE disk devices - 0 = /dev/pda First parallel port IDE disk - 16 = /dev/pdb Second parallel port IDE disk - 32 = /dev/pdc Third parallel port IDE disk - 48 = /dev/pdd Fourth parallel port IDE disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the partition - limit is 15 rather than 63 per disk. - - 46 char Comtrol Rocketport serial card - 0 = /dev/ttyR0 First Rocketport port - 1 = /dev/ttyR1 Second Rocketport port - ... - 46 block Parallel port ATAPI CD-ROM devices - 0 = /dev/pcd0 First parallel port ATAPI CD-ROM - 1 = /dev/pcd1 Second parallel port ATAPI CD-ROM - 2 = /dev/pcd2 Third parallel port ATAPI CD-ROM - 3 = /dev/pcd3 Fourth parallel port ATAPI CD-ROM - - 47 char Comtrol Rocketport serial card - alternate devices - 0 = /dev/cur0 Callout device for ttyR0 - 1 = /dev/cur1 Callout device for ttyR1 - ... - 47 block Parallel port ATAPI disk devices - 0 = /dev/pf0 First parallel port ATAPI disk - 1 = /dev/pf1 Second parallel port ATAPI disk - 2 = /dev/pf2 Third parallel port ATAPI disk - 3 = /dev/pf3 Fourth parallel port ATAPI disk - - This driver is intended for floppy disks and similar - devices and hence does not support partitioning. - - 48 char SDL RISCom serial card - 0 = /dev/ttyL0 First RISCom port - 1 = /dev/ttyL1 Second RISCom port - ... - 48 block Mylex DAC960 PCI RAID controller; first controller - 0 = /dev/rd/c0d0 First disk, whole disk - 8 = /dev/rd/c0d1 Second disk, whole disk - ... - 248 = /dev/rd/c0d31 32nd disk, whole disk - - For partitions add: - 0 = /dev/rd/c?d? Whole disk - 1 = /dev/rd/c?d?p1 First partition - ... - 7 = /dev/rd/c?d?p7 Seventh partition - - 49 char SDL RISCom serial card - alternate devices - 0 = /dev/cul0 Callout device for ttyL0 - 1 = /dev/cul1 Callout device for ttyL1 - ... - 49 block Mylex DAC960 PCI RAID controller; second controller - 0 = /dev/rd/c1d0 First disk, whole disk - 8 = /dev/rd/c1d1 Second disk, whole disk - ... - 248 = /dev/rd/c1d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 50 char Reserved for GLINT - - 50 block Mylex DAC960 PCI RAID controller; third controller - 0 = /dev/rd/c2d0 First disk, whole disk - 8 = /dev/rd/c2d1 Second disk, whole disk - ... - 248 = /dev/rd/c2d31 32nd disk, whole disk - - 51 char Baycom radio modem OR Radio Tech BIM-XXX-RS232 radio modem - 0 = /dev/bc0 First Baycom radio modem - 1 = /dev/bc1 Second Baycom radio modem - ... - 51 block Mylex DAC960 PCI RAID controller; fourth controller - 0 = /dev/rd/c3d0 First disk, whole disk - 8 = /dev/rd/c3d1 Second disk, whole disk - ... - 248 = /dev/rd/c3d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 52 char Spellcaster DataComm/BRI ISDN card - 0 = /dev/dcbri0 First DataComm card - 1 = /dev/dcbri1 Second DataComm card - 2 = /dev/dcbri2 Third DataComm card - 3 = /dev/dcbri3 Fourth DataComm card - - 52 block Mylex DAC960 PCI RAID controller; fifth controller - 0 = /dev/rd/c4d0 First disk, whole disk - 8 = /dev/rd/c4d1 Second disk, whole disk - ... - 248 = /dev/rd/c4d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 53 char BDM interface for remote debugging MC683xx microcontrollers - 0 = /dev/pd_bdm0 PD BDM interface on lp0 - 1 = /dev/pd_bdm1 PD BDM interface on lp1 - 2 = /dev/pd_bdm2 PD BDM interface on lp2 - 4 = /dev/icd_bdm0 ICD BDM interface on lp0 - 5 = /dev/icd_bdm1 ICD BDM interface on lp1 - 6 = /dev/icd_bdm2 ICD BDM interface on lp2 - - This device is used for the interfacing to the MC683xx - microcontrollers via Background Debug Mode by use of a - Parallel Port interface. PD is the Motorola Public - Domain Interface and ICD is the commercial interface - by P&E. - - 53 block Mylex DAC960 PCI RAID controller; sixth controller - 0 = /dev/rd/c5d0 First disk, whole disk - 8 = /dev/rd/c5d1 Second disk, whole disk - ... - 248 = /dev/rd/c5d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 54 char Electrocardiognosis Holter serial card - 0 = /dev/holter0 First Holter port - 1 = /dev/holter1 Second Holter port - 2 = /dev/holter2 Third Holter port - - A custom serial card used by Electrocardiognosis SRL - to transfer data from Holter - 24-hour heart monitoring equipment. - - 54 block Mylex DAC960 PCI RAID controller; seventh controller - 0 = /dev/rd/c6d0 First disk, whole disk - 8 = /dev/rd/c6d1 Second disk, whole disk - ... - 248 = /dev/rd/c6d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 55 char DSP56001 digital signal processor - 0 = /dev/dsp56k First DSP56001 - - 55 block Mylex DAC960 PCI RAID controller; eighth controller - 0 = /dev/rd/c7d0 First disk, whole disk - 8 = /dev/rd/c7d1 Second disk, whole disk - ... - 248 = /dev/rd/c7d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 56 char Apple Desktop Bus - 0 = /dev/adb ADB bus control - - Additional devices will be added to this number, all - starting with /dev/adb. - - 56 block Fifth IDE hard disk/CD-ROM interface - 0 = /dev/hdi Master: whole disk (or CD-ROM) - 64 = /dev/hdj Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 57 char Hayes ESP serial card - 0 = /dev/ttyP0 First ESP port - 1 = /dev/ttyP1 Second ESP port - ... - - 57 block Sixth IDE hard disk/CD-ROM interface - 0 = /dev/hdk Master: whole disk (or CD-ROM) - 64 = /dev/hdl Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 58 char Hayes ESP serial card - alternate devices - 0 = /dev/cup0 Callout device for ttyP0 - 1 = /dev/cup1 Callout device for ttyP1 - ... - - 58 block Reserved for logical volume manager - - 59 char sf firewall package - 0 = /dev/firewall Communication with sf kernel module - - 59 block Generic PDA filesystem device - 0 = /dev/pda0 First PDA device - 1 = /dev/pda1 Second PDA device - ... - - The pda devices are used to mount filesystems on - remote pda's (basically slow handheld machines with - proprietary OS's and limited memory and storage - running small fs translation drivers) through serial / - IRDA / parallel links. - - NAMING CONFLICT -- PROPOSED REVISED NAME /dev/rpda0 etc - - 60-63 char LOCAL/EXPERIMENTAL USE - - 60-63 block LOCAL/EXPERIMENTAL USE - Allocated for local/experimental use. For devices not - assigned official numbers, these ranges should be - used in order to avoid conflicting with future assignments. - - 64 char ENskip kernel encryption package - 0 = /dev/enskip Communication with ENskip kernel module - - 64 block Scramdisk/DriveCrypt encrypted devices - 0 = /dev/scramdisk/master Master node for ioctls - 1 = /dev/scramdisk/1 First encrypted device - 2 = /dev/scramdisk/2 Second encrypted device - ... - 255 = /dev/scramdisk/255 255th encrypted device - - The filename of the encrypted container and the passwords - are sent via ioctls (using the sdmount tool) to the master - node which then activates them via one of the - /dev/scramdisk/x nodes for loop mounting (all handled - through the sdmount tool). - - Requested by: andy@scramdisklinux.org - - 65 char Sundance "plink" Transputer boards (obsolete, unused) - 0 = /dev/plink0 First plink device - 1 = /dev/plink1 Second plink device - 2 = /dev/plink2 Third plink device - 3 = /dev/plink3 Fourth plink device - 64 = /dev/rplink0 First plink device, raw - 65 = /dev/rplink1 Second plink device, raw - 66 = /dev/rplink2 Third plink device, raw - 67 = /dev/rplink3 Fourth plink device, raw - 128 = /dev/plink0d First plink device, debug - 129 = /dev/plink1d Second plink device, debug - 130 = /dev/plink2d Third plink device, debug - 131 = /dev/plink3d Fourth plink device, debug - 192 = /dev/rplink0d First plink device, raw, debug - 193 = /dev/rplink1d Second plink device, raw, debug - 194 = /dev/rplink2d Third plink device, raw, debug - 195 = /dev/rplink3d Fourth plink device, raw, debug - - This is a commercial driver; contact James Howes - for information. - - 65 block SCSI disk devices (16-31) - 0 = /dev/sdq 17th SCSI disk whole disk - 16 = /dev/sdr 18th SCSI disk whole disk - 32 = /dev/sds 19th SCSI disk whole disk - ... - 240 = /dev/sdaf 32nd SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 66 char YARC PowerPC PCI coprocessor card - 0 = /dev/yppcpci0 First YARC card - 1 = /dev/yppcpci1 Second YARC card - ... - - 66 block SCSI disk devices (32-47) - 0 = /dev/sdag 33th SCSI disk whole disk - 16 = /dev/sdah 34th SCSI disk whole disk - 32 = /dev/sdai 35th SCSI disk whole disk - ... - 240 = /dev/sdav 48nd SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 67 char Coda network file system - 0 = /dev/cfs0 Coda cache manager - - See http://www.coda.cs.cmu.edu for information about Coda. - - 67 block SCSI disk devices (48-63) - 0 = /dev/sdaw 49th SCSI disk whole disk - 16 = /dev/sdax 50th SCSI disk whole disk - 32 = /dev/sday 51st SCSI disk whole disk - ... - 240 = /dev/sdbl 64th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 68 char CAPI 2.0 interface - 0 = /dev/capi20 Control device - 1 = /dev/capi20.00 First CAPI 2.0 application - 2 = /dev/capi20.01 Second CAPI 2.0 application - ... - 20 = /dev/capi20.19 19th CAPI 2.0 application - - ISDN CAPI 2.0 driver for use with CAPI 2.0 - applications; currently supports the AVM B1 card. - - 68 block SCSI disk devices (64-79) - 0 = /dev/sdbm 65th SCSI disk whole disk - 16 = /dev/sdbn 66th SCSI disk whole disk - 32 = /dev/sdbo 67th SCSI disk whole disk - ... - 240 = /dev/sdcb 80th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 69 char MA16 numeric accelerator card - 0 = /dev/ma16 Board memory access - - 69 block SCSI disk devices (80-95) - 0 = /dev/sdcc 81st SCSI disk whole disk - 16 = /dev/sdcd 82nd SCSI disk whole disk - 32 = /dev/sdce 83th SCSI disk whole disk - ... - 240 = /dev/sdcr 96th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 70 char SpellCaster Protocol Services Interface - 0 = /dev/apscfg Configuration interface - 1 = /dev/apsauth Authentication interface - 2 = /dev/apslog Logging interface - 3 = /dev/apsdbg Debugging interface - 64 = /dev/apsisdn ISDN command interface - 65 = /dev/apsasync Async command interface - 128 = /dev/apsmon Monitor interface - - 70 block SCSI disk devices (96-111) - 0 = /dev/sdcs 97th SCSI disk whole disk - 16 = /dev/sdct 98th SCSI disk whole disk - 32 = /dev/sdcu 99th SCSI disk whole disk - ... - 240 = /dev/sddh 112nd SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 71 char Computone IntelliPort II serial card - 0 = /dev/ttyF0 IntelliPort II board 0, port 0 - 1 = /dev/ttyF1 IntelliPort II board 0, port 1 - ... - 63 = /dev/ttyF63 IntelliPort II board 0, port 63 - 64 = /dev/ttyF64 IntelliPort II board 1, port 0 - 65 = /dev/ttyF65 IntelliPort II board 1, port 1 - ... - 127 = /dev/ttyF127 IntelliPort II board 1, port 63 - 128 = /dev/ttyF128 IntelliPort II board 2, port 0 - 129 = /dev/ttyF129 IntelliPort II board 2, port 1 - ... - 191 = /dev/ttyF191 IntelliPort II board 2, port 63 - 192 = /dev/ttyF192 IntelliPort II board 3, port 0 - 193 = /dev/ttyF193 IntelliPort II board 3, port 1 - ... - 255 = /dev/ttyF255 IntelliPort II board 3, port 63 - - 71 block SCSI disk devices (112-127) - 0 = /dev/sddi 113th SCSI disk whole disk - 16 = /dev/sddj 114th SCSI disk whole disk - 32 = /dev/sddk 115th SCSI disk whole disk - ... - 240 = /dev/sddx 128th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 72 char Computone IntelliPort II serial card - alternate devices - 0 = /dev/cuf0 Callout device for ttyF0 - 1 = /dev/cuf1 Callout device for ttyF1 - ... - 63 = /dev/cuf63 Callout device for ttyF63 - 64 = /dev/cuf64 Callout device for ttyF64 - 65 = /dev/cuf65 Callout device for ttyF65 - ... - 127 = /dev/cuf127 Callout device for ttyF127 - 128 = /dev/cuf128 Callout device for ttyF128 - 129 = /dev/cuf129 Callout device for ttyF129 - ... - 191 = /dev/cuf191 Callout device for ttyF191 - 192 = /dev/cuf192 Callout device for ttyF192 - 193 = /dev/cuf193 Callout device for ttyF193 - ... - 255 = /dev/cuf255 Callout device for ttyF255 - - 72 block Compaq Intelligent Drive Array, first controller - 0 = /dev/ida/c0d0 First logical drive whole disk - 16 = /dev/ida/c0d1 Second logical drive whole disk - ... - 240 = /dev/ida/c0d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 73 char Computone IntelliPort II serial card - control devices - 0 = /dev/ip2ipl0 Loadware device for board 0 - 1 = /dev/ip2stat0 Status device for board 0 - 4 = /dev/ip2ipl1 Loadware device for board 1 - 5 = /dev/ip2stat1 Status device for board 1 - 8 = /dev/ip2ipl2 Loadware device for board 2 - 9 = /dev/ip2stat2 Status device for board 2 - 12 = /dev/ip2ipl3 Loadware device for board 3 - 13 = /dev/ip2stat3 Status device for board 3 - - 73 block Compaq Intelligent Drive Array, second controller - 0 = /dev/ida/c1d0 First logical drive whole disk - 16 = /dev/ida/c1d1 Second logical drive whole disk - ... - 240 = /dev/ida/c1d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 74 char SCI bridge - 0 = /dev/SCI/0 SCI device 0 - 1 = /dev/SCI/1 SCI device 1 - ... - - Currently for Dolphin Interconnect Solutions' PCI-SCI - bridge. - - 74 block Compaq Intelligent Drive Array, third controller - 0 = /dev/ida/c2d0 First logical drive whole disk - 16 = /dev/ida/c2d1 Second logical drive whole disk - ... - 240 = /dev/ida/c2d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 75 char Specialix IO8+ serial card - 0 = /dev/ttyW0 First IO8+ port, first card - 1 = /dev/ttyW1 Second IO8+ port, first card - ... - 8 = /dev/ttyW8 First IO8+ port, second card - ... - - 75 block Compaq Intelligent Drive Array, fourth controller - 0 = /dev/ida/c3d0 First logical drive whole disk - 16 = /dev/ida/c3d1 Second logical drive whole disk - ... - 240 = /dev/ida/c3d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 76 char Specialix IO8+ serial card - alternate devices - 0 = /dev/cuw0 Callout device for ttyW0 - 1 = /dev/cuw1 Callout device for ttyW1 - ... - 8 = /dev/cuw8 Callout device for ttyW8 - ... - - 76 block Compaq Intelligent Drive Array, fifth controller - 0 = /dev/ida/c4d0 First logical drive whole disk - 16 = /dev/ida/c4d1 Second logical drive whole disk - ... - 240 = /dev/ida/c4d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - - 77 char ComScire Quantum Noise Generator - 0 = /dev/qng ComScire Quantum Noise Generator - - 77 block Compaq Intelligent Drive Array, sixth controller - 0 = /dev/ida/c5d0 First logical drive whole disk - 16 = /dev/ida/c5d1 Second logical drive whole disk - ... - 240 = /dev/ida/c5d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 78 char PAM Software's multimodem boards - 0 = /dev/ttyM0 First PAM modem - 1 = /dev/ttyM1 Second PAM modem - ... - - 78 block Compaq Intelligent Drive Array, seventh controller - 0 = /dev/ida/c6d0 First logical drive whole disk - 16 = /dev/ida/c6d1 Second logical drive whole disk - ... - 240 = /dev/ida/c6d15 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 79 char PAM Software's multimodem boards - alternate devices - 0 = /dev/cum0 Callout device for ttyM0 - 1 = /dev/cum1 Callout device for ttyM1 - ... - - 79 block Compaq Intelligent Drive Array, eighth controller - 0 = /dev/ida/c7d0 First logical drive whole disk - 16 = /dev/ida/c7d1 Second logical drive whole disk - ... - 240 = /dev/ida/c715 16th logical drive whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 80 char Photometrics AT200 CCD camera - 0 = /dev/at200 Photometrics AT200 CCD camera - - 80 block I2O hard disk - 0 = /dev/i2o/hda First I2O hard disk, whole disk - 16 = /dev/i2o/hdb Second I2O hard disk, whole disk - ... - 240 = /dev/i2o/hdp 16th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 81 char video4linux - 0 = /dev/video0 Video capture/overlay device - ... - 63 = /dev/video63 Video capture/overlay device - 64 = /dev/radio0 Radio device - ... - 127 = /dev/radio63 Radio device - 128 = /dev/swradio0 Software Defined Radio device - ... - 191 = /dev/swradio63 Software Defined Radio device - 224 = /dev/vbi0 Vertical blank interrupt - ... - 255 = /dev/vbi31 Vertical blank interrupt - - Minor numbers are allocated dynamically unless - CONFIG_VIDEO_FIXED_MINOR_RANGES (default n) - configuration option is set. - - 81 block I2O hard disk - 0 = /dev/i2o/hdq 17th I2O hard disk, whole disk - 16 = /dev/i2o/hdr 18th I2O hard disk, whole disk - ... - 240 = /dev/i2o/hdaf 32nd I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 82 char WiNRADiO communications receiver card - 0 = /dev/winradio0 First WiNRADiO card - 1 = /dev/winradio1 Second WiNRADiO card - ... - - The driver and documentation may be obtained from - http://www.winradio.com/ - - 82 block I2O hard disk - 0 = /dev/i2o/hdag 33rd I2O hard disk, whole disk - 16 = /dev/i2o/hdah 34th I2O hard disk, whole disk - ... - 240 = /dev/i2o/hdav 48th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 83 char Matrox mga_vid video driver - 0 = /dev/mga_vid0 1st video card - 1 = /dev/mga_vid1 2nd video card - 2 = /dev/mga_vid2 3rd video card - ... - 15 = /dev/mga_vid15 16th video card - - 83 block I2O hard disk - 0 = /dev/i2o/hdaw 49th I2O hard disk, whole disk - 16 = /dev/i2o/hdax 50th I2O hard disk, whole disk - ... - 240 = /dev/i2o/hdbl 64th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 84 char Ikon 1011[57] Versatec Greensheet Interface - 0 = /dev/ihcp0 First Greensheet port - 1 = /dev/ihcp1 Second Greensheet port - - 84 block I2O hard disk - 0 = /dev/i2o/hdbm 65th I2O hard disk, whole disk - 16 = /dev/i2o/hdbn 66th I2O hard disk, whole disk - ... - 240 = /dev/i2o/hdcb 80th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 85 char Linux/SGI shared memory input queue - 0 = /dev/shmiq Master shared input queue - 1 = /dev/qcntl0 First device pushed - 2 = /dev/qcntl1 Second device pushed - ... - - 85 block I2O hard disk - 0 = /dev/i2o/hdcc 81st I2O hard disk, whole disk - 16 = /dev/i2o/hdcd 82nd I2O hard disk, whole disk - ... - 240 = /dev/i2o/hdcr 96th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 86 char SCSI media changer - 0 = /dev/sch0 First SCSI media changer - 1 = /dev/sch1 Second SCSI media changer - ... - - 86 block I2O hard disk - 0 = /dev/i2o/hdcs 97th I2O hard disk, whole disk - 16 = /dev/i2o/hdct 98th I2O hard disk, whole disk - ... - 240 = /dev/i2o/hddh 112th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 87 char Sony Control-A1 stereo control bus - 0 = /dev/controla0 First device on chain - 1 = /dev/controla1 Second device on chain - ... - - 87 block I2O hard disk - 0 = /dev/i2o/hddi 113rd I2O hard disk, whole disk - 16 = /dev/i2o/hddj 114th I2O hard disk, whole disk - ... - 240 = /dev/i2o/hddx 128th I2O hard disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 88 char COMX synchronous serial card - 0 = /dev/comx0 COMX channel 0 - 1 = /dev/comx1 COMX channel 1 - ... - - 88 block Seventh IDE hard disk/CD-ROM interface - 0 = /dev/hdm Master: whole disk (or CD-ROM) - 64 = /dev/hdn Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 89 char I2C bus interface - 0 = /dev/i2c-0 First I2C adapter - 1 = /dev/i2c-1 Second I2C adapter - ... - - 89 block Eighth IDE hard disk/CD-ROM interface - 0 = /dev/hdo Master: whole disk (or CD-ROM) - 64 = /dev/hdp Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 90 char Memory Technology Device (RAM, ROM, Flash) - 0 = /dev/mtd0 First MTD (rw) - 1 = /dev/mtdr0 First MTD (ro) - ... - 30 = /dev/mtd15 16th MTD (rw) - 31 = /dev/mtdr15 16th MTD (ro) - - 90 block Ninth IDE hard disk/CD-ROM interface - 0 = /dev/hdq Master: whole disk (or CD-ROM) - 64 = /dev/hdr Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 91 char CAN-Bus devices - 0 = /dev/can0 First CAN-Bus controller - 1 = /dev/can1 Second CAN-Bus controller - ... - - 91 block Tenth IDE hard disk/CD-ROM interface - 0 = /dev/hds Master: whole disk (or CD-ROM) - 64 = /dev/hdt Slave: whole disk (or CD-ROM) - - Partitions are handled the same way as for the first - interface (see major number 3). - - 92 char Reserved for ith Kommunikationstechnik MIC ISDN card - - 92 block PPDD encrypted disk driver - 0 = /dev/ppdd0 First encrypted disk - 1 = /dev/ppdd1 Second encrypted disk - ... - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 93 char - - 93 block NAND Flash Translation Layer filesystem - 0 = /dev/nftla First NFTL layer - 16 = /dev/nftlb Second NFTL layer - ... - 240 = /dev/nftlp 16th NTFL layer - - 94 char - - 94 block IBM S/390 DASD block storage - 0 = /dev/dasda First DASD device, major - 1 = /dev/dasda1 First DASD device, block 1 - 2 = /dev/dasda2 First DASD device, block 2 - 3 = /dev/dasda3 First DASD device, block 3 - 4 = /dev/dasdb Second DASD device, major - 5 = /dev/dasdb1 Second DASD device, block 1 - 6 = /dev/dasdb2 Second DASD device, block 2 - 7 = /dev/dasdb3 Second DASD device, block 3 - ... - - 95 char IP filter - 0 = /dev/ipl Filter control device/log file - 1 = /dev/ipnat NAT control device/log file - 2 = /dev/ipstate State information log file - 3 = /dev/ipauth Authentication control device/log file - ... - - 96 char Parallel port ATAPI tape devices - 0 = /dev/pt0 First parallel port ATAPI tape - 1 = /dev/pt1 Second parallel port ATAPI tape - ... - 128 = /dev/npt0 First p.p. ATAPI tape, no rewind - 129 = /dev/npt1 Second p.p. ATAPI tape, no rewind - ... - - 96 block Inverse NAND Flash Translation Layer - 0 = /dev/inftla First INFTL layer - 16 = /dev/inftlb Second INFTL layer - ... - 240 = /dev/inftlp 16th INTFL layer - - 97 char Parallel port generic ATAPI interface - 0 = /dev/pg0 First parallel port ATAPI device - 1 = /dev/pg1 Second parallel port ATAPI device - 2 = /dev/pg2 Third parallel port ATAPI device - 3 = /dev/pg3 Fourth parallel port ATAPI device - - These devices support the same API as the generic SCSI - devices. - - 98 char Control and Measurement Device (comedi) - 0 = /dev/comedi0 First comedi device - 1 = /dev/comedi1 Second comedi device - ... - - See http://stm.lbl.gov/comedi. - - 98 block User-mode virtual block device - 0 = /dev/ubda First user-mode block device - 16 = /dev/udbb Second user-mode block device - ... - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - This device is used by the user-mode virtual kernel port. - - 99 char Raw parallel ports - 0 = /dev/parport0 First parallel port - 1 = /dev/parport1 Second parallel port - ... - - 99 block JavaStation flash disk - 0 = /dev/jsfd JavaStation flash disk - - 100 char Telephony for Linux - 0 = /dev/phone0 First telephony device - 1 = /dev/phone1 Second telephony device - ... - - 101 char Motorola DSP 56xxx board - 0 = /dev/mdspstat Status information - 1 = /dev/mdsp1 First DSP board I/O controls - ... - 16 = /dev/mdsp16 16th DSP board I/O controls - - 101 block AMI HyperDisk RAID controller - 0 = /dev/amiraid/ar0 First array whole disk - 16 = /dev/amiraid/ar1 Second array whole disk - ... - 240 = /dev/amiraid/ar15 16th array whole disk - - For each device, partitions are added as: - 0 = /dev/amiraid/ar? Whole disk - 1 = /dev/amiraid/ar?p1 First partition - 2 = /dev/amiraid/ar?p2 Second partition - ... - 15 = /dev/amiraid/ar?p15 15th partition - - 102 char - - 102 block Compressed block device - 0 = /dev/cbd/a First compressed block device, whole device - 16 = /dev/cbd/b Second compressed block device, whole device - ... - 240 = /dev/cbd/p 16th compressed block device, whole device - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 103 char Arla network file system - 0 = /dev/nnpfs0 First NNPFS device - 1 = /dev/nnpfs1 Second NNPFS device - - Arla is a free clone of the Andrew File System, AFS. - The NNPFS device gives user mode filesystem - implementations a kernel presence for caching and easy - mounting. For more information about the project, - write to or see - http://www.stacken.kth.se/project/arla/ - - 103 block Audit device - 0 = /dev/audit Audit device - - 104 char Flash BIOS support - - 104 block Compaq Next Generation Drive Array, first controller - 0 = /dev/cciss/c0d0 First logical drive, whole disk - 16 = /dev/cciss/c0d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c0d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 105 char Comtrol VS-1000 serial controller - 0 = /dev/ttyV0 First VS-1000 port - 1 = /dev/ttyV1 Second VS-1000 port - ... - - 105 block Compaq Next Generation Drive Array, second controller - 0 = /dev/cciss/c1d0 First logical drive, whole disk - 16 = /dev/cciss/c1d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c1d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 106 char Comtrol VS-1000 serial controller - alternate devices - 0 = /dev/cuv0 First VS-1000 port - 1 = /dev/cuv1 Second VS-1000 port - ... - - 106 block Compaq Next Generation Drive Array, third controller - 0 = /dev/cciss/c2d0 First logical drive, whole disk - 16 = /dev/cciss/c2d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c2d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 107 char 3Dfx Voodoo Graphics device - 0 = /dev/3dfx Primary 3Dfx graphics device - - 107 block Compaq Next Generation Drive Array, fourth controller - 0 = /dev/cciss/c3d0 First logical drive, whole disk - 16 = /dev/cciss/c3d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c3d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 108 char Device independent PPP interface - 0 = /dev/ppp Device independent PPP interface - - 108 block Compaq Next Generation Drive Array, fifth controller - 0 = /dev/cciss/c4d0 First logical drive, whole disk - 16 = /dev/cciss/c4d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c4d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 109 char Reserved for logical volume manager - - 109 block Compaq Next Generation Drive Array, sixth controller - 0 = /dev/cciss/c5d0 First logical drive, whole disk - 16 = /dev/cciss/c5d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c5d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 110 char miroMEDIA Surround board - 0 = /dev/srnd0 First miroMEDIA Surround board - 1 = /dev/srnd1 Second miroMEDIA Surround board - ... - - 110 block Compaq Next Generation Drive Array, seventh controller - 0 = /dev/cciss/c6d0 First logical drive, whole disk - 16 = /dev/cciss/c6d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c6d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 111 char - - 111 block Compaq Next Generation Drive Array, eighth controller - 0 = /dev/cciss/c7d0 First logical drive, whole disk - 16 = /dev/cciss/c7d1 Second logical drive, whole disk - ... - 240 = /dev/cciss/c7d15 16th logical drive, whole disk - - Partitions are handled the same way as for Mylex - DAC960 (see major number 48) except that the limit on - partitions is 15. - - 112 char ISI serial card - 0 = /dev/ttyM0 First ISI port - 1 = /dev/ttyM1 Second ISI port - ... - - There is currently a device-naming conflict between - these and PAM multimodems (major 78). - - 112 block IBM iSeries virtual disk - 0 = /dev/iseries/vda First virtual disk, whole disk - 8 = /dev/iseries/vdb Second virtual disk, whole disk - ... - 200 = /dev/iseries/vdz 26th virtual disk, whole disk - 208 = /dev/iseries/vdaa 27th virtual disk, whole disk - ... - 248 = /dev/iseries/vdaf 32nd virtual disk, whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 7. - - 113 char ISI serial card - alternate devices - 0 = /dev/cum0 Callout device for ttyM0 - 1 = /dev/cum1 Callout device for ttyM1 - ... - - 113 block IBM iSeries virtual CD-ROM - 0 = /dev/iseries/vcda First virtual CD-ROM - 1 = /dev/iseries/vcdb Second virtual CD-ROM - ... - - 114 char Picture Elements ISE board - 0 = /dev/ise0 First ISE board - 1 = /dev/ise1 Second ISE board - ... - 128 = /dev/isex0 Control node for first ISE board - 129 = /dev/isex1 Control node for second ISE board - ... - - The ISE board is an embedded computer, optimized for - image processing. The /dev/iseN nodes are the general - I/O access to the board, the /dev/isex0 nodes command - nodes used to control the board. - - 114 block IDE BIOS powered software RAID interfaces such as the - Promise Fastrak - - 0 = /dev/ataraid/d0 - 1 = /dev/ataraid/d0p1 - 2 = /dev/ataraid/d0p2 - ... - 16 = /dev/ataraid/d1 - 17 = /dev/ataraid/d1p1 - 18 = /dev/ataraid/d1p2 - ... - 255 = /dev/ataraid/d15p15 - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 115 char TI link cable devices (115 was formerly the console driver speaker) - 0 = /dev/tipar0 Parallel cable on first parallel port - ... - 7 = /dev/tipar7 Parallel cable on seventh parallel port - - 8 = /dev/tiser0 Serial cable on first serial port - ... - 15 = /dev/tiser7 Serial cable on seventh serial port - - 16 = /dev/tiusb0 First USB cable - ... - 47 = /dev/tiusb31 32nd USB cable - - 115 block NetWare (NWFS) Devices (0-255) - - The NWFS (NetWare) devices are used to present a - collection of NetWare Mirror Groups or NetWare - Partitions as a logical storage segment for - use in mounting NetWare volumes. A maximum of - 256 NetWare volumes can be supported in a single - machine. - - http://cgfa.telepac.pt/ftp2/kernel.org/linux/kernel/people/jmerkey/nwfs/ - - 0 = /dev/nwfs/v0 First NetWare (NWFS) Logical Volume - 1 = /dev/nwfs/v1 Second NetWare (NWFS) Logical Volume - 2 = /dev/nwfs/v2 Third NetWare (NWFS) Logical Volume - ... - 255 = /dev/nwfs/v255 Last NetWare (NWFS) Logical Volume - - 116 char Advanced Linux Sound Driver (ALSA) - - 116 block MicroMemory battery backed RAM adapter (NVRAM) - Supports 16 boards, 15 partitions each. - Requested by neilb at cse.unsw.edu.au. - - 0 = /dev/umem/d0 Whole of first board - 1 = /dev/umem/d0p1 First partition of first board - 2 = /dev/umem/d0p2 Second partition of first board - 15 = /dev/umem/d0p15 15th partition of first board - - 16 = /dev/umem/d1 Whole of second board - 17 = /dev/umem/d1p1 First partition of second board - ... - 255= /dev/umem/d15p15 15th partition of 16th board. - - 117 char COSA/SRP synchronous serial card - 0 = /dev/cosa0c0 1st board, 1st channel - 1 = /dev/cosa0c1 1st board, 2nd channel - ... - 16 = /dev/cosa1c0 2nd board, 1st channel - 17 = /dev/cosa1c1 2nd board, 2nd channel - ... - - 117 block Enterprise Volume Management System (EVMS) - - The EVMS driver uses a layered, plug-in model to provide - unparalleled flexibility and extensibility in managing - storage. This allows for easy expansion or customization - of various levels of volume management. Requested by - Mark Peloquin (peloquin at us.ibm.com). - - Note: EVMS populates and manages all the devnodes in - /dev/evms. - - http://sf.net/projects/evms - - 0 = /dev/evms/block_device EVMS block device - 1 = /dev/evms/legacyname1 First EVMS legacy device - 2 = /dev/evms/legacyname2 Second EVMS legacy device - ... - Both ranges can grow (down or up) until they meet. - ... - 254 = /dev/evms/EVMSname2 Second EVMS native device - 255 = /dev/evms/EVMSname1 First EVMS native device - - Note: legacyname(s) are derived from the normal legacy - device names. For example, /dev/hda5 would become - /dev/evms/hda5. - - 118 char IBM Cryptographic Accelerator - 0 = /dev/ica Virtual interface to all IBM Crypto Accelerators - 1 = /dev/ica0 IBMCA Device 0 - 2 = /dev/ica1 IBMCA Device 1 - ... - - 119 char VMware virtual network control - 0 = /dev/vnet0 1st virtual network - 1 = /dev/vnet1 2nd virtual network - ... - - 120-127 char LOCAL/EXPERIMENTAL USE - - 120-127 block LOCAL/EXPERIMENTAL USE - Allocated for local/experimental use. For devices not - assigned official numbers, these ranges should be - used in order to avoid conflicting with future assignments. - - 128-135 char Unix98 PTY masters - - These devices should not have corresponding device - nodes; instead they should be accessed through the - /dev/ptmx cloning interface. - - 128 block SCSI disk devices (128-143) - 0 = /dev/sddy 129th SCSI disk whole disk - 16 = /dev/sddz 130th SCSI disk whole disk - 32 = /dev/sdea 131th SCSI disk whole disk - ... - 240 = /dev/sden 144th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 129 block SCSI disk devices (144-159) - 0 = /dev/sdeo 145th SCSI disk whole disk - 16 = /dev/sdep 146th SCSI disk whole disk - 32 = /dev/sdeq 147th SCSI disk whole disk - ... - 240 = /dev/sdfd 160th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 130 char (Misc devices) - - 130 block SCSI disk devices (160-175) - 0 = /dev/sdfe 161st SCSI disk whole disk - 16 = /dev/sdff 162nd SCSI disk whole disk - 32 = /dev/sdfg 163rd SCSI disk whole disk - ... - 240 = /dev/sdft 176th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 131 block SCSI disk devices (176-191) - 0 = /dev/sdfu 177th SCSI disk whole disk - 16 = /dev/sdfv 178th SCSI disk whole disk - 32 = /dev/sdfw 179th SCSI disk whole disk - ... - 240 = /dev/sdgj 192nd SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 132 block SCSI disk devices (192-207) - 0 = /dev/sdgk 193rd SCSI disk whole disk - 16 = /dev/sdgl 194th SCSI disk whole disk - 32 = /dev/sdgm 195th SCSI disk whole disk - ... - 240 = /dev/sdgz 208th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 133 block SCSI disk devices (208-223) - 0 = /dev/sdha 209th SCSI disk whole disk - 16 = /dev/sdhb 210th SCSI disk whole disk - 32 = /dev/sdhc 211th SCSI disk whole disk - ... - 240 = /dev/sdhp 224th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 134 block SCSI disk devices (224-239) - 0 = /dev/sdhq 225th SCSI disk whole disk - 16 = /dev/sdhr 226th SCSI disk whole disk - 32 = /dev/sdhs 227th SCSI disk whole disk - ... - 240 = /dev/sdif 240th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 135 block SCSI disk devices (240-255) - 0 = /dev/sdig 241st SCSI disk whole disk - 16 = /dev/sdih 242nd SCSI disk whole disk - 32 = /dev/sdih 243rd SCSI disk whole disk - ... - 240 = /dev/sdiv 256th SCSI disk whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 136-143 char Unix98 PTY slaves - 0 = /dev/pts/0 First Unix98 pseudo-TTY - 1 = /dev/pts/1 Second Unix98 pseudo-TTY - ... - - These device nodes are automatically generated with - the proper permissions and modes by mounting the - devpts filesystem onto /dev/pts with the appropriate - mount options (distribution dependent, however, on - *most* distributions the appropriate options are - "mode=0620,gid=".) - - 136 block Mylex DAC960 PCI RAID controller; ninth controller - 0 = /dev/rd/c8d0 First disk, whole disk - 8 = /dev/rd/c8d1 Second disk, whole disk - ... - 248 = /dev/rd/c8d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 137 block Mylex DAC960 PCI RAID controller; tenth controller - 0 = /dev/rd/c9d0 First disk, whole disk - 8 = /dev/rd/c9d1 Second disk, whole disk - ... - 248 = /dev/rd/c9d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 138 block Mylex DAC960 PCI RAID controller; eleventh controller - 0 = /dev/rd/c10d0 First disk, whole disk - 8 = /dev/rd/c10d1 Second disk, whole disk - ... - 248 = /dev/rd/c10d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 139 block Mylex DAC960 PCI RAID controller; twelfth controller - 0 = /dev/rd/c11d0 First disk, whole disk - 8 = /dev/rd/c11d1 Second disk, whole disk - ... - 248 = /dev/rd/c11d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 140 block Mylex DAC960 PCI RAID controller; thirteenth controller - 0 = /dev/rd/c12d0 First disk, whole disk - 8 = /dev/rd/c12d1 Second disk, whole disk - ... - 248 = /dev/rd/c12d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 141 block Mylex DAC960 PCI RAID controller; fourteenth controller - 0 = /dev/rd/c13d0 First disk, whole disk - 8 = /dev/rd/c13d1 Second disk, whole disk - ... - 248 = /dev/rd/c13d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 142 block Mylex DAC960 PCI RAID controller; fifteenth controller - 0 = /dev/rd/c14d0 First disk, whole disk - 8 = /dev/rd/c14d1 Second disk, whole disk - ... - 248 = /dev/rd/c14d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 143 block Mylex DAC960 PCI RAID controller; sixteenth controller - 0 = /dev/rd/c15d0 First disk, whole disk - 8 = /dev/rd/c15d1 Second disk, whole disk - ... - 248 = /dev/rd/c15d31 32nd disk, whole disk - - Partitions are handled as for major 48. - - 144 char Encapsulated PPP - 0 = /dev/pppox0 First PPP over Ethernet - ... - 63 = /dev/pppox63 64th PPP over Ethernet - - This is primarily used for ADSL. - - The SST 5136-DN DeviceNet interface driver has been - relocated to major 183 due to an unfortunate conflict. - - 144 block Expansion Area #1 for more non-device (e.g. NFS) mounts - 0 = mounted device 256 - 255 = mounted device 511 - - 145 char SAM9407-based soundcard - 0 = /dev/sam0_mixer - 1 = /dev/sam0_sequencer - 2 = /dev/sam0_midi00 - 3 = /dev/sam0_dsp - 4 = /dev/sam0_audio - 6 = /dev/sam0_sndstat - 18 = /dev/sam0_midi01 - 34 = /dev/sam0_midi02 - 50 = /dev/sam0_midi03 - 64 = /dev/sam1_mixer - ... - 128 = /dev/sam2_mixer - ... - 192 = /dev/sam3_mixer - ... - - Device functions match OSS, but offer a number of - addons, which are sam9407 specific. OSS can be - operated simultaneously, taking care of the codec. - - 145 block Expansion Area #2 for more non-device (e.g. NFS) mounts - 0 = mounted device 512 - 255 = mounted device 767 - - 146 char SYSTRAM SCRAMNet mirrored-memory network - 0 = /dev/scramnet0 First SCRAMNet device - 1 = /dev/scramnet1 Second SCRAMNet device - ... - - 146 block Expansion Area #3 for more non-device (e.g. NFS) mounts - 0 = mounted device 768 - 255 = mounted device 1023 - - 147 char Aureal Semiconductor Vortex Audio device - 0 = /dev/aureal0 First Aureal Vortex - 1 = /dev/aureal1 Second Aureal Vortex - ... - - 147 block Distributed Replicated Block Device (DRBD) - 0 = /dev/drbd0 First DRBD device - 1 = /dev/drbd1 Second DRBD device - ... - - 148 char Technology Concepts serial card - 0 = /dev/ttyT0 First TCL port - 1 = /dev/ttyT1 Second TCL port - ... - - 149 char Technology Concepts serial card - alternate devices - 0 = /dev/cut0 Callout device for ttyT0 - 1 = /dev/cut0 Callout device for ttyT1 - ... - - 150 char Real-Time Linux FIFOs - 0 = /dev/rtf0 First RTLinux FIFO - 1 = /dev/rtf1 Second RTLinux FIFO - ... - - 151 char DPT I2O SmartRaid V controller - 0 = /dev/dpti0 First DPT I2O adapter - 1 = /dev/dpti1 Second DPT I2O adapter - ... - - 152 char EtherDrive Control Device - 0 = /dev/etherd/ctl Connect/Disconnect an EtherDrive - 1 = /dev/etherd/err Monitor errors - 2 = /dev/etherd/raw Raw AoE packet monitor - - 152 block EtherDrive Block Devices - 0 = /dev/etherd/0 EtherDrive 0 - ... - 255 = /dev/etherd/255 EtherDrive 255 - - 153 char SPI Bus Interface (sometimes referred to as MicroWire) - 0 = /dev/spi0 First SPI device on the bus - 1 = /dev/spi1 Second SPI device on the bus - ... - 15 = /dev/spi15 Sixteenth SPI device on the bus - - 153 block Enhanced Metadisk RAID (EMD) storage units - 0 = /dev/emd/0 First unit - 1 = /dev/emd/0p1 Partition 1 on First unit - 2 = /dev/emd/0p2 Partition 2 on First unit - ... - 15 = /dev/emd/0p15 Partition 15 on First unit - - 16 = /dev/emd/1 Second unit - 32 = /dev/emd/2 Third unit - ... - 240 = /dev/emd/15 Sixteenth unit - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 154 char Specialix RIO serial card - 0 = /dev/ttySR0 First RIO port - ... - 255 = /dev/ttySR255 256th RIO port - - 155 char Specialix RIO serial card - alternate devices - 0 = /dev/cusr0 Callout device for ttySR0 - ... - 255 = /dev/cusr255 Callout device for ttySR255 - - 156 char Specialix RIO serial card - 0 = /dev/ttySR256 257th RIO port - ... - 255 = /dev/ttySR511 512th RIO port - - 157 char Specialix RIO serial card - alternate devices - 0 = /dev/cusr256 Callout device for ttySR256 - ... - 255 = /dev/cusr511 Callout device for ttySR511 - - 158 char Dialogic GammaLink fax driver - 0 = /dev/gfax0 GammaLink channel 0 - 1 = /dev/gfax1 GammaLink channel 1 - ... - - 159 char RESERVED - - 159 block RESERVED - - 160 char General Purpose Instrument Bus (GPIB) - 0 = /dev/gpib0 First GPIB bus - 1 = /dev/gpib1 Second GPIB bus - ... - - 160 block Carmel 8-port SATA Disks on First Controller - 0 = /dev/carmel/0 SATA disk 0 whole disk - 1 = /dev/carmel/0p1 SATA disk 0 partition 1 - ... - 31 = /dev/carmel/0p31 SATA disk 0 partition 31 - - 32 = /dev/carmel/1 SATA disk 1 whole disk - 64 = /dev/carmel/2 SATA disk 2 whole disk - ... - 224 = /dev/carmel/7 SATA disk 7 whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 31. - - 161 char IrCOMM devices (IrDA serial/parallel emulation) - 0 = /dev/ircomm0 First IrCOMM device - 1 = /dev/ircomm1 Second IrCOMM device - ... - 16 = /dev/irlpt0 First IrLPT device - 17 = /dev/irlpt1 Second IrLPT device - ... - - 161 block Carmel 8-port SATA Disks on Second Controller - 0 = /dev/carmel/8 SATA disk 8 whole disk - 1 = /dev/carmel/8p1 SATA disk 8 partition 1 - ... - 31 = /dev/carmel/8p31 SATA disk 8 partition 31 - - 32 = /dev/carmel/9 SATA disk 9 whole disk - 64 = /dev/carmel/10 SATA disk 10 whole disk - ... - 224 = /dev/carmel/15 SATA disk 15 whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 31. - - 162 char Raw block device interface - 0 = /dev/rawctl Raw I/O control device - 1 = /dev/raw/raw1 First raw I/O device - 2 = /dev/raw/raw2 Second raw I/O device - ... - max minor number of raw device is set by kernel config - MAX_RAW_DEVS or raw module parameter 'max_raw_devs' - - 163 char - - 164 char Chase Research AT/PCI-Fast serial card - 0 = /dev/ttyCH0 AT/PCI-Fast board 0, port 0 - ... - 15 = /dev/ttyCH15 AT/PCI-Fast board 0, port 15 - 16 = /dev/ttyCH16 AT/PCI-Fast board 1, port 0 - ... - 31 = /dev/ttyCH31 AT/PCI-Fast board 1, port 15 - 32 = /dev/ttyCH32 AT/PCI-Fast board 2, port 0 - ... - 47 = /dev/ttyCH47 AT/PCI-Fast board 2, port 15 - 48 = /dev/ttyCH48 AT/PCI-Fast board 3, port 0 - ... - 63 = /dev/ttyCH63 AT/PCI-Fast board 3, port 15 - - 165 char Chase Research AT/PCI-Fast serial card - alternate devices - 0 = /dev/cuch0 Callout device for ttyCH0 - ... - 63 = /dev/cuch63 Callout device for ttyCH63 - - 166 char ACM USB modems - 0 = /dev/ttyACM0 First ACM modem - 1 = /dev/ttyACM1 Second ACM modem - ... - - 167 char ACM USB modems - alternate devices - 0 = /dev/cuacm0 Callout device for ttyACM0 - 1 = /dev/cuacm1 Callout device for ttyACM1 - ... - - 168 char Eracom CSA7000 PCI encryption adaptor - 0 = /dev/ecsa0 First CSA7000 - 1 = /dev/ecsa1 Second CSA7000 - ... - - 169 char Eracom CSA8000 PCI encryption adaptor - 0 = /dev/ecsa8-0 First CSA8000 - 1 = /dev/ecsa8-1 Second CSA8000 - ... - - 170 char AMI MegaRAC remote access controller - 0 = /dev/megarac0 First MegaRAC card - 1 = /dev/megarac1 Second MegaRAC card - ... - - 171 char Reserved for IEEE 1394 (Firewire) - - 172 char Moxa Intellio serial card - 0 = /dev/ttyMX0 First Moxa port - 1 = /dev/ttyMX1 Second Moxa port - ... - 127 = /dev/ttyMX127 128th Moxa port - 128 = /dev/moxactl Moxa control port - - 173 char Moxa Intellio serial card - alternate devices - 0 = /dev/cumx0 Callout device for ttyMX0 - 1 = /dev/cumx1 Callout device for ttyMX1 - ... - 127 = /dev/cumx127 Callout device for ttyMX127 - - 174 char SmartIO serial card - 0 = /dev/ttySI0 First SmartIO port - 1 = /dev/ttySI1 Second SmartIO port - ... - - 175 char SmartIO serial card - alternate devices - 0 = /dev/cusi0 Callout device for ttySI0 - 1 = /dev/cusi1 Callout device for ttySI1 - ... - - 176 char nCipher nFast PCI crypto accelerator - 0 = /dev/nfastpci0 First nFast PCI device - 1 = /dev/nfastpci1 First nFast PCI device - ... - - 177 char TI PCILynx memory spaces - 0 = /dev/pcilynx/aux0 AUX space of first PCILynx card - ... - 15 = /dev/pcilynx/aux15 AUX space of 16th PCILynx card - 16 = /dev/pcilynx/rom0 ROM space of first PCILynx card - ... - 31 = /dev/pcilynx/rom15 ROM space of 16th PCILynx card - 32 = /dev/pcilynx/ram0 RAM space of first PCILynx card - ... - 47 = /dev/pcilynx/ram15 RAM space of 16th PCILynx card - - 178 char Giganet cLAN1xxx virtual interface adapter - 0 = /dev/clanvi0 First cLAN adapter - 1 = /dev/clanvi1 Second cLAN adapter - ... - - 179 block MMC block devices - 0 = /dev/mmcblk0 First SD/MMC card - 1 = /dev/mmcblk0p1 First partition on first MMC card - 8 = /dev/mmcblk1 Second SD/MMC card - ... - - The start of next SD/MMC card can be configured with - CONFIG_MMC_BLOCK_MINORS, or overridden at boot/modprobe - time using the mmcblk.perdev_minors option. That would - bump the offset between each card to be the configured - value instead of the default 8. - - 179 char CCube DVXChip-based PCI products - 0 = /dev/dvxirq0 First DVX device - 1 = /dev/dvxirq1 Second DVX device - ... - - 180 char USB devices - 0 = /dev/usb/lp0 First USB printer - ... - 15 = /dev/usb/lp15 16th USB printer - 48 = /dev/usb/scanner0 First USB scanner - ... - 63 = /dev/usb/scanner15 16th USB scanner - 64 = /dev/usb/rio500 Diamond Rio 500 - 65 = /dev/usb/usblcd USBLCD Interface (info@usblcd.de) - 66 = /dev/usb/cpad0 Synaptics cPad (mouse/LCD) - 96 = /dev/usb/hiddev0 1st USB HID device - ... - 111 = /dev/usb/hiddev15 16th USB HID device - 112 = /dev/usb/auer0 1st auerswald ISDN device - ... - 127 = /dev/usb/auer15 16th auerswald ISDN device - 128 = /dev/usb/brlvgr0 First Braille Voyager device - ... - 131 = /dev/usb/brlvgr3 Fourth Braille Voyager device - 132 = /dev/usb/idmouse ID Mouse (fingerprint scanner) device - 133 = /dev/usb/sisusbvga1 First SiSUSB VGA device - ... - 140 = /dev/usb/sisusbvga8 Eighth SISUSB VGA device - 144 = /dev/usb/lcd USB LCD device - 160 = /dev/usb/legousbtower0 1st USB Legotower device - ... - 175 = /dev/usb/legousbtower15 16th USB Legotower device - 176 = /dev/usb/usbtmc1 First USB TMC device - ... - 191 = /dev/usb/usbtmc16 16th USB TMC device - 192 = /dev/usb/yurex1 First USB Yurex device - ... - 209 = /dev/usb/yurex16 16th USB Yurex device - - 180 block USB block devices - 0 = /dev/uba First USB block device - 8 = /dev/ubb Second USB block device - 16 = /dev/ubc Third USB block device - ... - - 181 char Conrad Electronic parallel port radio clocks - 0 = /dev/pcfclock0 First Conrad radio clock - 1 = /dev/pcfclock1 Second Conrad radio clock - ... - - 182 char Picture Elements THR2 binarizer - 0 = /dev/pethr0 First THR2 board - 1 = /dev/pethr1 Second THR2 board - ... - - 183 char SST 5136-DN DeviceNet interface - 0 = /dev/ss5136dn0 First DeviceNet interface - 1 = /dev/ss5136dn1 Second DeviceNet interface - ... - - This device used to be assigned to major number 144. - It had to be moved due to an unfortunate conflict. - - 184 char Picture Elements' video simulator/sender - 0 = /dev/pevss0 First sender board - 1 = /dev/pevss1 Second sender board - ... - - 185 char InterMezzo high availability file system - 0 = /dev/intermezzo0 First cache manager - 1 = /dev/intermezzo1 Second cache manager - ... - - See http://web.archive.org/web/20080115195241/ - http://inter-mezzo.org/index.html - - 186 char Object-based storage control device - 0 = /dev/obd0 First obd control device - 1 = /dev/obd1 Second obd control device - ... - - See ftp://ftp.lustre.org/pub/obd for code and information. - - 187 char DESkey hardware encryption device - 0 = /dev/deskey0 First DES key - 1 = /dev/deskey1 Second DES key - ... - - 188 char USB serial converters - 0 = /dev/ttyUSB0 First USB serial converter - 1 = /dev/ttyUSB1 Second USB serial converter - ... - - 189 char USB serial converters - alternate devices - 0 = /dev/cuusb0 Callout device for ttyUSB0 - 1 = /dev/cuusb1 Callout device for ttyUSB1 - ... - - 190 char Kansas City tracker/tuner card - 0 = /dev/kctt0 First KCT/T card - 1 = /dev/kctt1 Second KCT/T card - ... - - 191 char Reserved for PCMCIA - - 192 char Kernel profiling interface - 0 = /dev/profile Profiling control device - 1 = /dev/profile0 Profiling device for CPU 0 - 2 = /dev/profile1 Profiling device for CPU 1 - ... - - 193 char Kernel event-tracing interface - 0 = /dev/trace Tracing control device - 1 = /dev/trace0 Tracing device for CPU 0 - 2 = /dev/trace1 Tracing device for CPU 1 - ... - - 194 char linVideoStreams (LINVS) - 0 = /dev/mvideo/status0 Video compression status - 1 = /dev/mvideo/stream0 Video stream - 2 = /dev/mvideo/frame0 Single compressed frame - 3 = /dev/mvideo/rawframe0 Raw uncompressed frame - 4 = /dev/mvideo/codec0 Direct codec access - 5 = /dev/mvideo/video4linux0 Video4Linux compatibility - - 16 = /dev/mvideo/status1 Second device - ... - 32 = /dev/mvideo/status2 Third device - ... - ... - 240 = /dev/mvideo/status15 16th device - ... - - 195 char Nvidia graphics devices - 0 = /dev/nvidia0 First Nvidia card - 1 = /dev/nvidia1 Second Nvidia card - ... - 255 = /dev/nvidiactl Nvidia card control device - - 196 char Tormenta T1 card - 0 = /dev/tor/0 Master control channel for all cards - 1 = /dev/tor/1 First DS0 - 2 = /dev/tor/2 Second DS0 - ... - 48 = /dev/tor/48 48th DS0 - 49 = /dev/tor/49 First pseudo-channel - 50 = /dev/tor/50 Second pseudo-channel - ... - - 197 char OpenTNF tracing facility - 0 = /dev/tnf/t0 Trace 0 data extraction - 1 = /dev/tnf/t1 Trace 1 data extraction - ... - 128 = /dev/tnf/status Tracing facility status - 130 = /dev/tnf/trace Tracing device - - 198 char Total Impact TPMP2 quad coprocessor PCI card - 0 = /dev/tpmp2/0 First card - 1 = /dev/tpmp2/1 Second card - ... - - 199 char Veritas volume manager (VxVM) volumes - 0 = /dev/vx/rdsk/*/* First volume - 1 = /dev/vx/rdsk/*/* Second volume - ... - - 199 block Veritas volume manager (VxVM) volumes - 0 = /dev/vx/dsk/*/* First volume - 1 = /dev/vx/dsk/*/* Second volume - ... - - The namespace in these directories is maintained by - the user space VxVM software. - - 200 char Veritas VxVM configuration interface - 0 = /dev/vx/config Configuration access node - 1 = /dev/vx/trace Volume i/o trace access node - 2 = /dev/vx/iod Volume i/o daemon access node - 3 = /dev/vx/info Volume information access node - 4 = /dev/vx/task Volume tasks access node - 5 = /dev/vx/taskmon Volume tasks monitor daemon - - 201 char Veritas VxVM dynamic multipathing driver - 0 = /dev/vx/rdmp/* First multipath device - 1 = /dev/vx/rdmp/* Second multipath device - ... - 201 block Veritas VxVM dynamic multipathing driver - 0 = /dev/vx/dmp/* First multipath device - 1 = /dev/vx/dmp/* Second multipath device - ... - - The namespace in these directories is maintained by - the user space VxVM software. - - 202 char CPU model-specific registers - 0 = /dev/cpu/0/msr MSRs on CPU 0 - 1 = /dev/cpu/1/msr MSRs on CPU 1 - ... - - 202 block Xen Virtual Block Device - 0 = /dev/xvda First Xen VBD whole disk - 16 = /dev/xvdb Second Xen VBD whole disk - 32 = /dev/xvdc Third Xen VBD whole disk - ... - 240 = /dev/xvdp Sixteenth Xen VBD whole disk - - Partitions are handled in the same way as for IDE - disks (see major number 3) except that the limit on - partitions is 15. - - 203 char CPU CPUID information - 0 = /dev/cpu/0/cpuid CPUID on CPU 0 - 1 = /dev/cpu/1/cpuid CPUID on CPU 1 - ... - - 204 char Low-density serial ports - 0 = /dev/ttyLU0 LinkUp Systems L72xx UART - port 0 - 1 = /dev/ttyLU1 LinkUp Systems L72xx UART - port 1 - 2 = /dev/ttyLU2 LinkUp Systems L72xx UART - port 2 - 3 = /dev/ttyLU3 LinkUp Systems L72xx UART - port 3 - 4 = /dev/ttyFB0 Intel Footbridge (ARM) - 5 = /dev/ttySA0 StrongARM builtin serial port 0 - 6 = /dev/ttySA1 StrongARM builtin serial port 1 - 7 = /dev/ttySA2 StrongARM builtin serial port 2 - 8 = /dev/ttySC0 SCI serial port (SuperH) - port 0 - 9 = /dev/ttySC1 SCI serial port (SuperH) - port 1 - 10 = /dev/ttySC2 SCI serial port (SuperH) - port 2 - 11 = /dev/ttySC3 SCI serial port (SuperH) - port 3 - 12 = /dev/ttyFW0 Firmware console - port 0 - 13 = /dev/ttyFW1 Firmware console - port 1 - 14 = /dev/ttyFW2 Firmware console - port 2 - 15 = /dev/ttyFW3 Firmware console - port 3 - 16 = /dev/ttyAM0 ARM "AMBA" serial port 0 - ... - 31 = /dev/ttyAM15 ARM "AMBA" serial port 15 - 32 = /dev/ttyDB0 DataBooster serial port 0 - ... - 39 = /dev/ttyDB7 DataBooster serial port 7 - 40 = /dev/ttySG0 SGI Altix console port - 41 = /dev/ttySMX0 Motorola i.MX - port 0 - 42 = /dev/ttySMX1 Motorola i.MX - port 1 - 43 = /dev/ttySMX2 Motorola i.MX - port 2 - 44 = /dev/ttyMM0 Marvell MPSC - port 0 - 45 = /dev/ttyMM1 Marvell MPSC - port 1 - 46 = /dev/ttyCPM0 PPC CPM (SCC or SMC) - port 0 - ... - 47 = /dev/ttyCPM5 PPC CPM (SCC or SMC) - port 5 - 50 = /dev/ttyIOC0 Altix serial card - ... - 81 = /dev/ttyIOC31 Altix serial card - 82 = /dev/ttyVR0 NEC VR4100 series SIU - 83 = /dev/ttyVR1 NEC VR4100 series DSIU - 84 = /dev/ttyIOC84 Altix ioc4 serial card - ... - 115 = /dev/ttyIOC115 Altix ioc4 serial card - 116 = /dev/ttySIOC0 Altix ioc3 serial card - ... - 147 = /dev/ttySIOC31 Altix ioc3 serial card - 148 = /dev/ttyPSC0 PPC PSC - port 0 - ... - 153 = /dev/ttyPSC5 PPC PSC - port 5 - 154 = /dev/ttyAT0 ATMEL serial port 0 - ... - 169 = /dev/ttyAT15 ATMEL serial port 15 - 170 = /dev/ttyNX0 Hilscher netX serial port 0 - ... - 185 = /dev/ttyNX15 Hilscher netX serial port 15 - 186 = /dev/ttyJ0 JTAG1 DCC protocol based serial port emulation - 187 = /dev/ttyUL0 Xilinx uartlite - port 0 - ... - 190 = /dev/ttyUL3 Xilinx uartlite - port 3 - 191 = /dev/xvc0 Xen virtual console - port 0 - 192 = /dev/ttyPZ0 pmac_zilog - port 0 - ... - 195 = /dev/ttyPZ3 pmac_zilog - port 3 - 196 = /dev/ttyTX0 TX39/49 serial port 0 - ... - 204 = /dev/ttyTX7 TX39/49 serial port 7 - 205 = /dev/ttySC0 SC26xx serial port 0 - 206 = /dev/ttySC1 SC26xx serial port 1 - 207 = /dev/ttySC2 SC26xx serial port 2 - 208 = /dev/ttySC3 SC26xx serial port 3 - 209 = /dev/ttyMAX0 MAX3100 serial port 0 - 210 = /dev/ttyMAX1 MAX3100 serial port 1 - 211 = /dev/ttyMAX2 MAX3100 serial port 2 - 212 = /dev/ttyMAX3 MAX3100 serial port 3 - - 205 char Low-density serial ports (alternate device) - 0 = /dev/culu0 Callout device for ttyLU0 - 1 = /dev/culu1 Callout device for ttyLU1 - 2 = /dev/culu2 Callout device for ttyLU2 - 3 = /dev/culu3 Callout device for ttyLU3 - 4 = /dev/cufb0 Callout device for ttyFB0 - 5 = /dev/cusa0 Callout device for ttySA0 - 6 = /dev/cusa1 Callout device for ttySA1 - 7 = /dev/cusa2 Callout device for ttySA2 - 8 = /dev/cusc0 Callout device for ttySC0 - 9 = /dev/cusc1 Callout device for ttySC1 - 10 = /dev/cusc2 Callout device for ttySC2 - 11 = /dev/cusc3 Callout device for ttySC3 - 12 = /dev/cufw0 Callout device for ttyFW0 - 13 = /dev/cufw1 Callout device for ttyFW1 - 14 = /dev/cufw2 Callout device for ttyFW2 - 15 = /dev/cufw3 Callout device for ttyFW3 - 16 = /dev/cuam0 Callout device for ttyAM0 - ... - 31 = /dev/cuam15 Callout device for ttyAM15 - 32 = /dev/cudb0 Callout device for ttyDB0 - ... - 39 = /dev/cudb7 Callout device for ttyDB7 - 40 = /dev/cusg0 Callout device for ttySG0 - 41 = /dev/ttycusmx0 Callout device for ttySMX0 - 42 = /dev/ttycusmx1 Callout device for ttySMX1 - 43 = /dev/ttycusmx2 Callout device for ttySMX2 - 46 = /dev/cucpm0 Callout device for ttyCPM0 - ... - 49 = /dev/cucpm5 Callout device for ttyCPM5 - 50 = /dev/cuioc40 Callout device for ttyIOC40 - ... - 81 = /dev/cuioc431 Callout device for ttyIOC431 - 82 = /dev/cuvr0 Callout device for ttyVR0 - 83 = /dev/cuvr1 Callout device for ttyVR1 - - 206 char OnStream SC-x0 tape devices - 0 = /dev/osst0 First OnStream SCSI tape, mode 0 - 1 = /dev/osst1 Second OnStream SCSI tape, mode 0 - ... - 32 = /dev/osst0l First OnStream SCSI tape, mode 1 - 33 = /dev/osst1l Second OnStream SCSI tape, mode 1 - ... - 64 = /dev/osst0m First OnStream SCSI tape, mode 2 - 65 = /dev/osst1m Second OnStream SCSI tape, mode 2 - ... - 96 = /dev/osst0a First OnStream SCSI tape, mode 3 - 97 = /dev/osst1a Second OnStream SCSI tape, mode 3 - ... - 128 = /dev/nosst0 No rewind version of /dev/osst0 - 129 = /dev/nosst1 No rewind version of /dev/osst1 - ... - 160 = /dev/nosst0l No rewind version of /dev/osst0l - 161 = /dev/nosst1l No rewind version of /dev/osst1l - ... - 192 = /dev/nosst0m No rewind version of /dev/osst0m - 193 = /dev/nosst1m No rewind version of /dev/osst1m - ... - 224 = /dev/nosst0a No rewind version of /dev/osst0a - 225 = /dev/nosst1a No rewind version of /dev/osst1a - ... - - The OnStream SC-x0 SCSI tapes do not support the - standard SCSI SASD command set and therefore need - their own driver "osst". Note that the IDE, USB (and - maybe ParPort) versions may be driven via ide-scsi or - usb-storage SCSI emulation and this osst device and - driver as well. The ADR-x0 drives are QIC-157 - compliant and don't need osst. - - 207 char Compaq ProLiant health feature indicate - 0 = /dev/cpqhealth/cpqw Redirector interface - 1 = /dev/cpqhealth/crom EISA CROM - 2 = /dev/cpqhealth/cdt Data Table - 3 = /dev/cpqhealth/cevt Event Log - 4 = /dev/cpqhealth/casr Automatic Server Recovery - 5 = /dev/cpqhealth/cecc ECC Memory - 6 = /dev/cpqhealth/cmca Machine Check Architecture - 7 = /dev/cpqhealth/ccsm Deprecated CDT - 8 = /dev/cpqhealth/cnmi NMI Handling - 9 = /dev/cpqhealth/css Sideshow Management - 10 = /dev/cpqhealth/cram CMOS interface - 11 = /dev/cpqhealth/cpci PCI IRQ interface - - 208 char User space serial ports - 0 = /dev/ttyU0 First user space serial port - 1 = /dev/ttyU1 Second user space serial port - ... - - 209 char User space serial ports (alternate devices) - 0 = /dev/cuu0 Callout device for ttyU0 - 1 = /dev/cuu1 Callout device for ttyU1 - ... - - 210 char SBE, Inc. sync/async serial card - 0 = /dev/sbei/wxcfg0 Configuration device for board 0 - 1 = /dev/sbei/dld0 Download device for board 0 - 2 = /dev/sbei/wan00 WAN device, port 0, board 0 - 3 = /dev/sbei/wan01 WAN device, port 1, board 0 - 4 = /dev/sbei/wan02 WAN device, port 2, board 0 - 5 = /dev/sbei/wan03 WAN device, port 3, board 0 - 6 = /dev/sbei/wanc00 WAN clone device, port 0, board 0 - 7 = /dev/sbei/wanc01 WAN clone device, port 1, board 0 - 8 = /dev/sbei/wanc02 WAN clone device, port 2, board 0 - 9 = /dev/sbei/wanc03 WAN clone device, port 3, board 0 - 10 = /dev/sbei/wxcfg1 Configuration device for board 1 - 11 = /dev/sbei/dld1 Download device for board 1 - 12 = /dev/sbei/wan10 WAN device, port 0, board 1 - 13 = /dev/sbei/wan11 WAN device, port 1, board 1 - 14 = /dev/sbei/wan12 WAN device, port 2, board 1 - 15 = /dev/sbei/wan13 WAN device, port 3, board 1 - 16 = /dev/sbei/wanc10 WAN clone device, port 0, board 1 - 17 = /dev/sbei/wanc11 WAN clone device, port 1, board 1 - 18 = /dev/sbei/wanc12 WAN clone device, port 2, board 1 - 19 = /dev/sbei/wanc13 WAN clone device, port 3, board 1 - ... - - Yes, each board is really spaced 10 (decimal) apart. - - 211 char Addinum CPCI1500 digital I/O card - 0 = /dev/addinum/cpci1500/0 First CPCI1500 card - 1 = /dev/addinum/cpci1500/1 Second CPCI1500 card - ... - - 212 char LinuxTV.org DVB driver subsystem - 0 = /dev/dvb/adapter0/video0 first video decoder of first card - 1 = /dev/dvb/adapter0/audio0 first audio decoder of first card - 2 = /dev/dvb/adapter0/sec0 (obsolete/unused) - 3 = /dev/dvb/adapter0/frontend0 first frontend device of first card - 4 = /dev/dvb/adapter0/demux0 first demux device of first card - 5 = /dev/dvb/adapter0/dvr0 first digital video recoder device of first card - 6 = /dev/dvb/adapter0/ca0 first common access port of first card - 7 = /dev/dvb/adapter0/net0 first network device of first card - 8 = /dev/dvb/adapter0/osd0 first on-screen-display device of first card - 9 = /dev/dvb/adapter0/video1 second video decoder of first card - ... - 64 = /dev/dvb/adapter1/video0 first video decoder of second card - ... - 128 = /dev/dvb/adapter2/video0 first video decoder of third card - ... - 196 = /dev/dvb/adapter3/video0 first video decoder of fourth card - - 216 char Bluetooth RFCOMM TTY devices - 0 = /dev/rfcomm0 First Bluetooth RFCOMM TTY device - 1 = /dev/rfcomm1 Second Bluetooth RFCOMM TTY device - ... - - 217 char Bluetooth RFCOMM TTY devices (alternate devices) - 0 = /dev/curf0 Callout device for rfcomm0 - 1 = /dev/curf1 Callout device for rfcomm1 - ... - - 218 char The Logical Company bus Unibus/Qbus adapters - 0 = /dev/logicalco/bci/0 First bus adapter - 1 = /dev/logicalco/bci/1 First bus adapter - ... - - 219 char The Logical Company DCI-1300 digital I/O card - 0 = /dev/logicalco/dci1300/0 First DCI-1300 card - 1 = /dev/logicalco/dci1300/1 Second DCI-1300 card - ... - - 220 char Myricom Myrinet "GM" board - 0 = /dev/myricom/gm0 First Myrinet GM board - 1 = /dev/myricom/gmp0 First board "root access" - 2 = /dev/myricom/gm1 Second Myrinet GM board - 3 = /dev/myricom/gmp1 Second board "root access" - ... - - 221 char VME bus - 0 = /dev/bus/vme/m0 First master image - 1 = /dev/bus/vme/m1 Second master image - 2 = /dev/bus/vme/m2 Third master image - 3 = /dev/bus/vme/m3 Fourth master image - 4 = /dev/bus/vme/s0 First slave image - 5 = /dev/bus/vme/s1 Second slave image - 6 = /dev/bus/vme/s2 Third slave image - 7 = /dev/bus/vme/s3 Fourth slave image - 8 = /dev/bus/vme/ctl Control - - It is expected that all VME bus drivers will use the - same interface. For interface documentation see - http://www.vmelinux.org/. - - 224 char A2232 serial card - 0 = /dev/ttyY0 First A2232 port - 1 = /dev/ttyY1 Second A2232 port - ... - - 225 char A2232 serial card (alternate devices) - 0 = /dev/cuy0 Callout device for ttyY0 - 1 = /dev/cuy1 Callout device for ttyY1 - ... - - 226 char Direct Rendering Infrastructure (DRI) - 0 = /dev/dri/card0 First graphics card - 1 = /dev/dri/card1 Second graphics card - ... - - 227 char IBM 3270 terminal Unix tty access - 1 = /dev/3270/tty1 First 3270 terminal - 2 = /dev/3270/tty2 Seconds 3270 terminal - ... - - 228 char IBM 3270 terminal block-mode access - 0 = /dev/3270/tub Controlling interface - 1 = /dev/3270/tub1 First 3270 terminal - 2 = /dev/3270/tub2 Second 3270 terminal - ... - - 229 char IBM iSeries/pSeries virtual console - 0 = /dev/hvc0 First console port - 1 = /dev/hvc1 Second console port - ... - - 230 char IBM iSeries virtual tape - 0 = /dev/iseries/vt0 First virtual tape, mode 0 - 1 = /dev/iseries/vt1 Second virtual tape, mode 0 - ... - 32 = /dev/iseries/vt0l First virtual tape, mode 1 - 33 = /dev/iseries/vt1l Second virtual tape, mode 1 - ... - 64 = /dev/iseries/vt0m First virtual tape, mode 2 - 65 = /dev/iseries/vt1m Second virtual tape, mode 2 - ... - 96 = /dev/iseries/vt0a First virtual tape, mode 3 - 97 = /dev/iseries/vt1a Second virtual tape, mode 3 - ... - 128 = /dev/iseries/nvt0 First virtual tape, mode 0, no rewind - 129 = /dev/iseries/nvt1 Second virtual tape, mode 0, no rewind - ... - 160 = /dev/iseries/nvt0l First virtual tape, mode 1, no rewind - 161 = /dev/iseries/nvt1l Second virtual tape, mode 1, no rewind - ... - 192 = /dev/iseries/nvt0m First virtual tape, mode 2, no rewind - 193 = /dev/iseries/nvt1m Second virtual tape, mode 2, no rewind - ... - 224 = /dev/iseries/nvt0a First virtual tape, mode 3, no rewind - 225 = /dev/iseries/nvt1a Second virtual tape, mode 3, no rewind - ... - - "No rewind" refers to the omission of the default - automatic rewind on device close. The MTREW or MTOFFL - ioctl()'s can be used to rewind the tape regardless of - the device used to access it. - - 231 char InfiniBand - 0 = /dev/infiniband/umad0 - 1 = /dev/infiniband/umad1 - ... - 63 = /dev/infiniband/umad63 63rd InfiniBandMad device - 64 = /dev/infiniband/issm0 First InfiniBand IsSM device - 65 = /dev/infiniband/issm1 Second InfiniBand IsSM device - ... - 127 = /dev/infiniband/issm63 63rd InfiniBand IsSM device - 128 = /dev/infiniband/uverbs0 First InfiniBand verbs device - 129 = /dev/infiniband/uverbs1 Second InfiniBand verbs device - ... - 159 = /dev/infiniband/uverbs31 31st InfiniBand verbs device - - 232 char Biometric Devices - 0 = /dev/biometric/sensor0/fingerprint first fingerprint sensor on first device - 1 = /dev/biometric/sensor0/iris first iris sensor on first device - 2 = /dev/biometric/sensor0/retina first retina sensor on first device - 3 = /dev/biometric/sensor0/voiceprint first voiceprint sensor on first device - 4 = /dev/biometric/sensor0/facial first facial sensor on first device - 5 = /dev/biometric/sensor0/hand first hand sensor on first device - ... - 10 = /dev/biometric/sensor1/fingerprint first fingerprint sensor on second device - ... - 20 = /dev/biometric/sensor2/fingerprint first fingerprint sensor on third device - ... - - 233 char PathScale InfiniPath interconnect - 0 = /dev/ipath Primary device for programs (any unit) - 1 = /dev/ipath0 Access specifically to unit 0 - 2 = /dev/ipath1 Access specifically to unit 1 - ... - 4 = /dev/ipath3 Access specifically to unit 3 - 129 = /dev/ipath_sma Device used by Subnet Management Agent - 130 = /dev/ipath_diag Device used by diagnostics programs - - 234-254 char RESERVED FOR DYNAMIC ASSIGNMENT - Character devices that request a dynamic allocation of major number will - take numbers starting from 254 and downward. - - 240-254 block LOCAL/EXPERIMENTAL USE - Allocated for local/experimental use. For devices not - assigned official numbers, these ranges should be - used in order to avoid conflicting with future assignments. - - 255 char RESERVED - - 255 block RESERVED - - This major is reserved to assist the expansion to a - larger number space. No device nodes with this major - should ever be created on the filesystem. - (This is probably not true anymore, but I'll leave it - for now /Torben) - - ---LARGE MAJORS!!!!!--- - - 256 char Equinox SST multi-port serial boards - 0 = /dev/ttyEQ0 First serial port on first Equinox SST board - 127 = /dev/ttyEQ127 Last serial port on first Equinox SST board - 128 = /dev/ttyEQ128 First serial port on second Equinox SST board - ... - 1027 = /dev/ttyEQ1027 Last serial port on eighth Equinox SST board - - 256 block Resident Flash Disk Flash Translation Layer - 0 = /dev/rfda First RFD FTL layer - 16 = /dev/rfdb Second RFD FTL layer - ... - 240 = /dev/rfdp 16th RFD FTL layer - - 257 char Phoenix Technologies Cryptographic Services Driver - 0 = /dev/ptlsec Crypto Services Driver - - 257 block SSFDC Flash Translation Layer filesystem - 0 = /dev/ssfdca First SSFDC layer - 8 = /dev/ssfdcb Second SSFDC layer - 16 = /dev/ssfdcc Third SSFDC layer - 24 = /dev/ssfdcd 4th SSFDC layer - 32 = /dev/ssfdce 5th SSFDC layer - 40 = /dev/ssfdcf 6th SSFDC layer - 48 = /dev/ssfdcg 7th SSFDC layer - 56 = /dev/ssfdch 8th SSFDC layer - - 258 block ROM/Flash read-only translation layer - 0 = /dev/blockrom0 First ROM card's translation layer interface - 1 = /dev/blockrom1 Second ROM card's translation layer interface - ... - - 259 block Block Extended Major - Used dynamically to hold additional partition minor - numbers and allow large numbers of partitions per device - - 259 char FPGA configuration interfaces - 0 = /dev/icap0 First Xilinx internal configuration - 1 = /dev/icap1 Second Xilinx internal configuration - - 260 char OSD (Object-based-device) SCSI Device - 0 = /dev/osd0 First OSD Device - 1 = /dev/osd1 Second OSD Device - ... - 255 = /dev/osd255 256th OSD Device - +.. include:: devices.txt + :literal: Additional ``/dev/`` directory entries -------------------------------------- diff --git a/Documentation/admin-guide/devices.txt b/Documentation/admin-guide/devices.txt new file mode 100644 index 000000000000..c9cea2e39c21 --- /dev/null +++ b/Documentation/admin-guide/devices.txt @@ -0,0 +1,3081 @@ + 0 Unnamed devices (e.g. non-device mounts) + 0 = reserved as null device number + See block major 144, 145, 146 for expansion areas. + + 1 char Memory devices + 1 = /dev/mem Physical memory access + 2 = /dev/kmem Kernel virtual memory access + 3 = /dev/null Null device + 4 = /dev/port I/O port access + 5 = /dev/zero Null byte source + 6 = /dev/core OBSOLETE - replaced by /proc/kcore + 7 = /dev/full Returns ENOSPC on write + 8 = /dev/random Nondeterministic random number gen. + 9 = /dev/urandom Faster, less secure random number gen. + 10 = /dev/aio Asynchronous I/O notification interface + 11 = /dev/kmsg Writes to this come out as printk's, reads + export the buffered printk records. + 12 = /dev/oldmem OBSOLETE - replaced by /proc/vmcore + + 1 block RAM disk + 0 = /dev/ram0 First RAM disk + 1 = /dev/ram1 Second RAM disk + ... + 250 = /dev/initrd Initial RAM disk + + Older kernels had /dev/ramdisk (1, 1) here. + /dev/initrd refers to a RAM disk which was preloaded + by the boot loader; newer kernels use /dev/ram0 for + the initrd. + + 2 char Pseudo-TTY masters + 0 = /dev/ptyp0 First PTY master + 1 = /dev/ptyp1 Second PTY master + ... + 255 = /dev/ptyef 256th PTY master + + Pseudo-tty's are named as follows: + * Masters are "pty", slaves are "tty"; + * the fourth letter is one of pqrstuvwxyzabcde indicating + the 1st through 16th series of 16 pseudo-ttys each, and + * the fifth letter is one of 0123456789abcdef indicating + the position within the series. + + These are the old-style (BSD) PTY devices; Unix98 + devices are on major 128 and above and use the PTY + master multiplex (/dev/ptmx) to acquire a PTY on + demand. + + 2 block Floppy disks + 0 = /dev/fd0 Controller 0, drive 0, autodetect + 1 = /dev/fd1 Controller 0, drive 1, autodetect + 2 = /dev/fd2 Controller 0, drive 2, autodetect + 3 = /dev/fd3 Controller 0, drive 3, autodetect + 128 = /dev/fd4 Controller 1, drive 0, autodetect + 129 = /dev/fd5 Controller 1, drive 1, autodetect + 130 = /dev/fd6 Controller 1, drive 2, autodetect + 131 = /dev/fd7 Controller 1, drive 3, autodetect + + To specify format, add to the autodetect device number: + 0 = /dev/fd? Autodetect format + 4 = /dev/fd?d360 5.25" 360K in a 360K drive(1) + 20 = /dev/fd?h360 5.25" 360K in a 1200K drive(1) + 48 = /dev/fd?h410 5.25" 410K in a 1200K drive + 64 = /dev/fd?h420 5.25" 420K in a 1200K drive + 24 = /dev/fd?h720 5.25" 720K in a 1200K drive + 80 = /dev/fd?h880 5.25" 880K in a 1200K drive(1) + 8 = /dev/fd?h1200 5.25" 1200K in a 1200K drive(1) + 40 = /dev/fd?h1440 5.25" 1440K in a 1200K drive(1) + 56 = /dev/fd?h1476 5.25" 1476K in a 1200K drive + 72 = /dev/fd?h1494 5.25" 1494K in a 1200K drive + 92 = /dev/fd?h1600 5.25" 1600K in a 1200K drive(1) + + 12 = /dev/fd?u360 3.5" 360K Double Density(2) + 16 = /dev/fd?u720 3.5" 720K Double Density(1) + 120 = /dev/fd?u800 3.5" 800K Double Density(2) + 52 = /dev/fd?u820 3.5" 820K Double Density + 68 = /dev/fd?u830 3.5" 830K Double Density + 84 = /dev/fd?u1040 3.5" 1040K Double Density(1) + 88 = /dev/fd?u1120 3.5" 1120K Double Density(1) + 28 = /dev/fd?u1440 3.5" 1440K High Density(1) + 124 = /dev/fd?u1600 3.5" 1600K High Density(1) + 44 = /dev/fd?u1680 3.5" 1680K High Density(3) + 60 = /dev/fd?u1722 3.5" 1722K High Density + 76 = /dev/fd?u1743 3.5" 1743K High Density + 96 = /dev/fd?u1760 3.5" 1760K High Density + 116 = /dev/fd?u1840 3.5" 1840K High Density(3) + 100 = /dev/fd?u1920 3.5" 1920K High Density(1) + 32 = /dev/fd?u2880 3.5" 2880K Extra Density(1) + 104 = /dev/fd?u3200 3.5" 3200K Extra Density + 108 = /dev/fd?u3520 3.5" 3520K Extra Density + 112 = /dev/fd?u3840 3.5" 3840K Extra Density(1) + + 36 = /dev/fd?CompaQ Compaq 2880K drive; obsolete? + + (1) Autodetectable format + (2) Autodetectable format in a Double Density (720K) drive only + (3) Autodetectable format in a High Density (1440K) drive only + + NOTE: The letter in the device name (d, q, h or u) + signifies the type of drive: 5.25" Double Density (d), + 5.25" Quad Density (q), 5.25" High Density (h) or 3.5" + (any model, u). The use of the capital letters D, H + and E for the 3.5" models have been deprecated, since + the drive type is insignificant for these devices. + + 3 char Pseudo-TTY slaves + 0 = /dev/ttyp0 First PTY slave + 1 = /dev/ttyp1 Second PTY slave + ... + 255 = /dev/ttyef 256th PTY slave + + These are the old-style (BSD) PTY devices; Unix98 + devices are on major 136 and above. + + 3 block First MFM, RLL and IDE hard disk/CD-ROM interface + 0 = /dev/hda Master: whole disk (or CD-ROM) + 64 = /dev/hdb Slave: whole disk (or CD-ROM) + + For partitions, add to the whole disk device number: + 0 = /dev/hd? Whole disk + 1 = /dev/hd?1 First partition + 2 = /dev/hd?2 Second partition + ... + 63 = /dev/hd?63 63rd partition + + For Linux/i386, partitions 1-4 are the primary + partitions, and 5 and above are logical partitions. + Other versions of Linux use partitioning schemes + appropriate to their respective architectures. + + 4 char TTY devices + 0 = /dev/tty0 Current virtual console + + 1 = /dev/tty1 First virtual console + ... + 63 = /dev/tty63 63rd virtual console + 64 = /dev/ttyS0 First UART serial port + ... + 255 = /dev/ttyS191 192nd UART serial port + + UART serial ports refer to 8250/16450/16550 series devices. + + Older versions of the Linux kernel used this major + number for BSD PTY devices. As of Linux 2.1.115, this + is no longer supported. Use major numbers 2 and 3. + + 4 block Aliases for dynamically allocated major devices to be used + when its not possible to create the real device nodes + because the root filesystem is mounted read-only. + + 0 = /dev/root + + 5 char Alternate TTY devices + 0 = /dev/tty Current TTY device + 1 = /dev/console System console + 2 = /dev/ptmx PTY master multiplex + 3 = /dev/ttyprintk User messages via printk TTY device + 64 = /dev/cua0 Callout device for ttyS0 + ... + 255 = /dev/cua191 Callout device for ttyS191 + + (5,1) is /dev/console starting with Linux 2.1.71. See + the section on terminal devices for more information + on /dev/console. + + 6 char Parallel printer devices + 0 = /dev/lp0 Parallel printer on parport0 + 1 = /dev/lp1 Parallel printer on parport1 + ... + + Current Linux kernels no longer have a fixed mapping + between parallel ports and I/O addresses. Instead, + they are redirected through the parport multiplex layer. + + 7 char Virtual console capture devices + 0 = /dev/vcs Current vc text contents + 1 = /dev/vcs1 tty1 text contents + ... + 63 = /dev/vcs63 tty63 text contents + 128 = /dev/vcsa Current vc text/attribute contents + 129 = /dev/vcsa1 tty1 text/attribute contents + ... + 191 = /dev/vcsa63 tty63 text/attribute contents + + NOTE: These devices permit both read and write access. + + 7 block Loopback devices + 0 = /dev/loop0 First loop device + 1 = /dev/loop1 Second loop device + ... + + The loop devices are used to mount filesystems not + associated with block devices. The binding to the + loop devices is handled by mount(8) or losetup(8). + + 8 block SCSI disk devices (0-15) + 0 = /dev/sda First SCSI disk whole disk + 16 = /dev/sdb Second SCSI disk whole disk + 32 = /dev/sdc Third SCSI disk whole disk + ... + 240 = /dev/sdp Sixteenth SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 9 char SCSI tape devices + 0 = /dev/st0 First SCSI tape, mode 0 + 1 = /dev/st1 Second SCSI tape, mode 0 + ... + 32 = /dev/st0l First SCSI tape, mode 1 + 33 = /dev/st1l Second SCSI tape, mode 1 + ... + 64 = /dev/st0m First SCSI tape, mode 2 + 65 = /dev/st1m Second SCSI tape, mode 2 + ... + 96 = /dev/st0a First SCSI tape, mode 3 + 97 = /dev/st1a Second SCSI tape, mode 3 + ... + 128 = /dev/nst0 First SCSI tape, mode 0, no rewind + 129 = /dev/nst1 Second SCSI tape, mode 0, no rewind + ... + 160 = /dev/nst0l First SCSI tape, mode 1, no rewind + 161 = /dev/nst1l Second SCSI tape, mode 1, no rewind + ... + 192 = /dev/nst0m First SCSI tape, mode 2, no rewind + 193 = /dev/nst1m Second SCSI tape, mode 2, no rewind + ... + 224 = /dev/nst0a First SCSI tape, mode 3, no rewind + 225 = /dev/nst1a Second SCSI tape, mode 3, no rewind + ... + + "No rewind" refers to the omission of the default + automatic rewind on device close. The MTREW or MTOFFL + ioctl()'s can be used to rewind the tape regardless of + the device used to access it. + + 9 block Metadisk (RAID) devices + 0 = /dev/md0 First metadisk group + 1 = /dev/md1 Second metadisk group + ... + + The metadisk driver is used to span a + filesystem across multiple physical disks. + + 10 char Non-serial mice, misc features + 0 = /dev/logibm Logitech bus mouse + 1 = /dev/psaux PS/2-style mouse port + 2 = /dev/inportbm Microsoft Inport bus mouse + 3 = /dev/atibm ATI XL bus mouse + 4 = /dev/jbm J-mouse + 4 = /dev/amigamouse Amiga mouse (68k/Amiga) + 5 = /dev/atarimouse Atari mouse + 6 = /dev/sunmouse Sun mouse + 7 = /dev/amigamouse1 Second Amiga mouse + 8 = /dev/smouse Simple serial mouse driver + 9 = /dev/pc110pad IBM PC-110 digitizer pad + 10 = /dev/adbmouse Apple Desktop Bus mouse + 11 = /dev/vrtpanel Vr41xx embedded touch panel + 13 = /dev/vpcmouse Connectix Virtual PC Mouse + 14 = /dev/touchscreen/ucb1x00 UCB 1x00 touchscreen + 15 = /dev/touchscreen/mk712 MK712 touchscreen + 128 = /dev/beep Fancy beep device + 129 = + 130 = /dev/watchdog Watchdog timer port + 131 = /dev/temperature Machine internal temperature + 132 = /dev/hwtrap Hardware fault trap + 133 = /dev/exttrp External device trap + 134 = /dev/apm_bios Advanced Power Management BIOS + 135 = /dev/rtc Real Time Clock + 137 = /dev/vhci Bluetooth virtual HCI driver + 139 = /dev/openprom SPARC OpenBoot PROM + 140 = /dev/relay8 Berkshire Products Octal relay card + 141 = /dev/relay16 Berkshire Products ISO-16 relay card + 142 = + 143 = /dev/pciconf PCI configuration space + 144 = /dev/nvram Non-volatile configuration RAM + 145 = /dev/hfmodem Soundcard shortwave modem control + 146 = /dev/graphics Linux/SGI graphics device + 147 = /dev/opengl Linux/SGI OpenGL pipe + 148 = /dev/gfx Linux/SGI graphics effects device + 149 = /dev/input/mouse Linux/SGI Irix emulation mouse + 150 = /dev/input/keyboard Linux/SGI Irix emulation keyboard + 151 = /dev/led Front panel LEDs + 152 = /dev/kpoll Kernel Poll Driver + 153 = /dev/mergemem Memory merge device + 154 = /dev/pmu Macintosh PowerBook power manager + 155 = /dev/isictl MultiTech ISICom serial control + 156 = /dev/lcd Front panel LCD display + 157 = /dev/ac Applicom Intl Profibus card + 158 = /dev/nwbutton Netwinder external button + 159 = /dev/nwdebug Netwinder debug interface + 160 = /dev/nwflash Netwinder flash memory + 161 = /dev/userdma User-space DMA access + 162 = /dev/smbus System Management Bus + 163 = /dev/lik Logitech Internet Keyboard + 164 = /dev/ipmo Intel Intelligent Platform Management + 165 = /dev/vmmon VMware virtual machine monitor + 166 = /dev/i2o/ctl I2O configuration manager + 167 = /dev/specialix_sxctl Specialix serial control + 168 = /dev/tcldrv Technology Concepts serial control + 169 = /dev/specialix_rioctl Specialix RIO serial control + 170 = /dev/thinkpad/thinkpad IBM Thinkpad devices + 171 = /dev/srripc QNX4 API IPC manager + 172 = /dev/usemaclone Semaphore clone device + 173 = /dev/ipmikcs Intelligent Platform Management + 174 = /dev/uctrl SPARCbook 3 microcontroller + 175 = /dev/agpgart AGP Graphics Address Remapping Table + 176 = /dev/gtrsc Gorgy Timing radio clock + 177 = /dev/cbm Serial CBM bus + 178 = /dev/jsflash JavaStation OS flash SIMM + 179 = /dev/xsvc High-speed shared-mem/semaphore service + 180 = /dev/vrbuttons Vr41xx button input device + 181 = /dev/toshiba Toshiba laptop SMM support + 182 = /dev/perfctr Performance-monitoring counters + 183 = /dev/hwrng Generic random number generator + 184 = /dev/cpu/microcode CPU microcode update interface + 186 = /dev/atomicps Atomic shapshot of process state data + 187 = /dev/irnet IrNET device + 188 = /dev/smbusbios SMBus BIOS + 189 = /dev/ussp_ctl User space serial port control + 190 = /dev/crash Mission Critical Linux crash dump facility + 191 = /dev/pcl181 + 192 = /dev/nas_xbus NAS xbus LCD/buttons access + 193 = /dev/d7s SPARC 7-segment display + 194 = /dev/zkshim Zero-Knowledge network shim control + 195 = /dev/elographics/e2201 Elographics touchscreen E271-2201 + 196 = /dev/vfio/vfio VFIO userspace driver interface + 197 = /dev/pxa3xx-gcu PXA3xx graphics controller unit driver + 198 = /dev/sexec Signed executable interface + 199 = /dev/scanners/cuecat :CueCat barcode scanner + 200 = /dev/net/tun TAP/TUN network device + 201 = /dev/button/gulpb Transmeta GULP-B buttons + 202 = /dev/emd/ctl Enhanced Metadisk RAID (EMD) control + 203 = /dev/cuse Cuse (character device in user-space) + 204 = /dev/video/em8300 EM8300 DVD decoder control + 205 = /dev/video/em8300_mv EM8300 DVD decoder video + 206 = /dev/video/em8300_ma EM8300 DVD decoder audio + 207 = /dev/video/em8300_sp EM8300 DVD decoder subpicture + 208 = /dev/compaq/cpqphpc Compaq PCI Hot Plug Controller + 209 = /dev/compaq/cpqrid Compaq Remote Insight Driver + 210 = /dev/impi/bt IMPI coprocessor block transfer + 211 = /dev/impi/smic IMPI coprocessor stream interface + 212 = /dev/watchdogs/0 First watchdog device + 213 = /dev/watchdogs/1 Second watchdog device + 214 = /dev/watchdogs/2 Third watchdog device + 215 = /dev/watchdogs/3 Fourth watchdog device + 216 = /dev/fujitsu/apanel Fujitsu/Siemens application panel + 217 = /dev/ni/natmotn National Instruments Motion + 218 = /dev/kchuid Inter-process chuid control + 219 = /dev/modems/mwave MWave modem firmware upload + 220 = /dev/mptctl Message passing technology (MPT) control + 221 = /dev/mvista/hssdsi Montavista PICMG hot swap system driver + 222 = /dev/mvista/hasi Montavista PICMG high availability + 223 = /dev/input/uinput User level driver support for input + 224 = /dev/tpm TCPA TPM driver + 225 = /dev/pps Pulse Per Second driver + 226 = /dev/systrace Systrace device + 227 = /dev/mcelog X86_64 Machine Check Exception driver + 228 = /dev/hpet HPET driver + 229 = /dev/fuse Fuse (virtual filesystem in user-space) + 230 = /dev/midishare MidiShare driver + 231 = /dev/snapshot System memory snapshot device + 232 = /dev/kvm Kernel-based virtual machine (hardware virtualization extensions) + 233 = /dev/kmview View-OS A process with a view + 234 = /dev/btrfs-control Btrfs control device + 235 = /dev/autofs Autofs control device + 236 = /dev/mapper/control Device-Mapper control device + 237 = /dev/loop-control Loopback control device + 238 = /dev/vhost-net Host kernel accelerator for virtio net + 239 = /dev/uhid User-space I/O driver support for HID subsystem + + 240-254 Reserved for local use + 255 Reserved for MISC_DYNAMIC_MINOR + + 11 char Raw keyboard device (Linux/SPARC only) + 0 = /dev/kbd Raw keyboard device + + 11 char Serial Mux device (Linux/PA-RISC only) + 0 = /dev/ttyB0 First mux port + 1 = /dev/ttyB1 Second mux port + ... + + 11 block SCSI CD-ROM devices + 0 = /dev/scd0 First SCSI CD-ROM + 1 = /dev/scd1 Second SCSI CD-ROM + ... + + The prefix /dev/sr (instead of /dev/scd) has been deprecated. + + 12 char QIC-02 tape + 2 = /dev/ntpqic11 QIC-11, no rewind-on-close + 3 = /dev/tpqic11 QIC-11, rewind-on-close + 4 = /dev/ntpqic24 QIC-24, no rewind-on-close + 5 = /dev/tpqic24 QIC-24, rewind-on-close + 6 = /dev/ntpqic120 QIC-120, no rewind-on-close + 7 = /dev/tpqic120 QIC-120, rewind-on-close + 8 = /dev/ntpqic150 QIC-150, no rewind-on-close + 9 = /dev/tpqic150 QIC-150, rewind-on-close + + The device names specified are proposed -- if there + are "standard" names for these devices, please let me know. + + 12 block + + 13 char Input core + 0 = /dev/input/js0 First joystick + 1 = /dev/input/js1 Second joystick + ... + 32 = /dev/input/mouse0 First mouse + 33 = /dev/input/mouse1 Second mouse + ... + 63 = /dev/input/mice Unified mouse + 64 = /dev/input/event0 First event queue + 65 = /dev/input/event1 Second event queue + ... + + Each device type has 5 bits (32 minors). + + 13 block Previously used for the XT disk (/dev/xdN) + Deleted in kernel v3.9. + + 14 char Open Sound System (OSS) + 0 = /dev/mixer Mixer control + 1 = /dev/sequencer Audio sequencer + 2 = /dev/midi00 First MIDI port + 3 = /dev/dsp Digital audio + 4 = /dev/audio Sun-compatible digital audio + 6 = + 7 = /dev/audioctl SPARC audio control device + 8 = /dev/sequencer2 Sequencer -- alternate device + 16 = /dev/mixer1 Second soundcard mixer control + 17 = /dev/patmgr0 Sequencer patch manager + 18 = /dev/midi01 Second MIDI port + 19 = /dev/dsp1 Second soundcard digital audio + 20 = /dev/audio1 Second soundcard Sun digital audio + 33 = /dev/patmgr1 Sequencer patch manager + 34 = /dev/midi02 Third MIDI port + 50 = /dev/midi03 Fourth MIDI port + + 14 block + + 15 char Joystick + 0 = /dev/js0 First analog joystick + 1 = /dev/js1 Second analog joystick + ... + 128 = /dev/djs0 First digital joystick + 129 = /dev/djs1 Second digital joystick + ... + 15 block Sony CDU-31A/CDU-33A CD-ROM + 0 = /dev/sonycd Sony CDU-31a CD-ROM + + 16 char Non-SCSI scanners + 0 = /dev/gs4500 Genius 4500 handheld scanner + + 16 block GoldStar CD-ROM + 0 = /dev/gscd GoldStar CD-ROM + + 17 char OBSOLETE (was Chase serial card) + 0 = /dev/ttyH0 First Chase port + 1 = /dev/ttyH1 Second Chase port + ... + 17 block Optics Storage CD-ROM + 0 = /dev/optcd Optics Storage CD-ROM + + 18 char OBSOLETE (was Chase serial card - alternate devices) + 0 = /dev/cuh0 Callout device for ttyH0 + 1 = /dev/cuh1 Callout device for ttyH1 + ... + 18 block Sanyo CD-ROM + 0 = /dev/sjcd Sanyo CD-ROM + + 19 char Cyclades serial card + 0 = /dev/ttyC0 First Cyclades port + ... + 31 = /dev/ttyC31 32nd Cyclades port + + 19 block "Double" compressed disk + 0 = /dev/double0 First compressed disk + ... + 7 = /dev/double7 Eighth compressed disk + 128 = /dev/cdouble0 Mirror of first compressed disk + ... + 135 = /dev/cdouble7 Mirror of eighth compressed disk + + See the Double documentation for the meaning of the + mirror devices. + + 20 char Cyclades serial card - alternate devices + 0 = /dev/cub0 Callout device for ttyC0 + ... + 31 = /dev/cub31 Callout device for ttyC31 + + 20 block Hitachi CD-ROM (under development) + 0 = /dev/hitcd Hitachi CD-ROM + + 21 char Generic SCSI access + 0 = /dev/sg0 First generic SCSI device + 1 = /dev/sg1 Second generic SCSI device + ... + + Most distributions name these /dev/sga, /dev/sgb...; + this sets an unnecessary limit of 26 SCSI devices in + the system and is counter to standard Linux + device-naming practice. + + 21 block Acorn MFM hard drive interface + 0 = /dev/mfma First MFM drive whole disk + 64 = /dev/mfmb Second MFM drive whole disk + + This device is used on the ARM-based Acorn RiscPC. + Partitions are handled the same way as for IDE disks + (see major number 3). + + 22 char Digiboard serial card + 0 = /dev/ttyD0 First Digiboard port + 1 = /dev/ttyD1 Second Digiboard port + ... + 22 block Second IDE hard disk/CD-ROM interface + 0 = /dev/hdc Master: whole disk (or CD-ROM) + 64 = /dev/hdd Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 23 char Digiboard serial card - alternate devices + 0 = /dev/cud0 Callout device for ttyD0 + 1 = /dev/cud1 Callout device for ttyD1 + ... + 23 block Mitsumi proprietary CD-ROM + 0 = /dev/mcd Mitsumi CD-ROM + + 24 char Stallion serial card + 0 = /dev/ttyE0 Stallion port 0 card 0 + 1 = /dev/ttyE1 Stallion port 1 card 0 + ... + 64 = /dev/ttyE64 Stallion port 0 card 1 + 65 = /dev/ttyE65 Stallion port 1 card 1 + ... + 128 = /dev/ttyE128 Stallion port 0 card 2 + 129 = /dev/ttyE129 Stallion port 1 card 2 + ... + 192 = /dev/ttyE192 Stallion port 0 card 3 + 193 = /dev/ttyE193 Stallion port 1 card 3 + ... + 24 block Sony CDU-535 CD-ROM + 0 = /dev/cdu535 Sony CDU-535 CD-ROM + + 25 char Stallion serial card - alternate devices + 0 = /dev/cue0 Callout device for ttyE0 + 1 = /dev/cue1 Callout device for ttyE1 + ... + 64 = /dev/cue64 Callout device for ttyE64 + 65 = /dev/cue65 Callout device for ttyE65 + ... + 128 = /dev/cue128 Callout device for ttyE128 + 129 = /dev/cue129 Callout device for ttyE129 + ... + 192 = /dev/cue192 Callout device for ttyE192 + 193 = /dev/cue193 Callout device for ttyE193 + ... + 25 block First Matsushita (Panasonic/SoundBlaster) CD-ROM + 0 = /dev/sbpcd0 Panasonic CD-ROM controller 0 unit 0 + 1 = /dev/sbpcd1 Panasonic CD-ROM controller 0 unit 1 + 2 = /dev/sbpcd2 Panasonic CD-ROM controller 0 unit 2 + 3 = /dev/sbpcd3 Panasonic CD-ROM controller 0 unit 3 + + 26 char + + 26 block Second Matsushita (Panasonic/SoundBlaster) CD-ROM + 0 = /dev/sbpcd4 Panasonic CD-ROM controller 1 unit 0 + 1 = /dev/sbpcd5 Panasonic CD-ROM controller 1 unit 1 + 2 = /dev/sbpcd6 Panasonic CD-ROM controller 1 unit 2 + 3 = /dev/sbpcd7 Panasonic CD-ROM controller 1 unit 3 + + 27 char QIC-117 tape + 0 = /dev/qft0 Unit 0, rewind-on-close + 1 = /dev/qft1 Unit 1, rewind-on-close + 2 = /dev/qft2 Unit 2, rewind-on-close + 3 = /dev/qft3 Unit 3, rewind-on-close + 4 = /dev/nqft0 Unit 0, no rewind-on-close + 5 = /dev/nqft1 Unit 1, no rewind-on-close + 6 = /dev/nqft2 Unit 2, no rewind-on-close + 7 = /dev/nqft3 Unit 3, no rewind-on-close + 16 = /dev/zqft0 Unit 0, rewind-on-close, compression + 17 = /dev/zqft1 Unit 1, rewind-on-close, compression + 18 = /dev/zqft2 Unit 2, rewind-on-close, compression + 19 = /dev/zqft3 Unit 3, rewind-on-close, compression + 20 = /dev/nzqft0 Unit 0, no rewind-on-close, compression + 21 = /dev/nzqft1 Unit 1, no rewind-on-close, compression + 22 = /dev/nzqft2 Unit 2, no rewind-on-close, compression + 23 = /dev/nzqft3 Unit 3, no rewind-on-close, compression + 32 = /dev/rawqft0 Unit 0, rewind-on-close, no file marks + 33 = /dev/rawqft1 Unit 1, rewind-on-close, no file marks + 34 = /dev/rawqft2 Unit 2, rewind-on-close, no file marks + 35 = /dev/rawqft3 Unit 3, rewind-on-close, no file marks + 36 = /dev/nrawqft0 Unit 0, no rewind-on-close, no file marks + 37 = /dev/nrawqft1 Unit 1, no rewind-on-close, no file marks + 38 = /dev/nrawqft2 Unit 2, no rewind-on-close, no file marks + 39 = /dev/nrawqft3 Unit 3, no rewind-on-close, no file marks + + 27 block Third Matsushita (Panasonic/SoundBlaster) CD-ROM + 0 = /dev/sbpcd8 Panasonic CD-ROM controller 2 unit 0 + 1 = /dev/sbpcd9 Panasonic CD-ROM controller 2 unit 1 + 2 = /dev/sbpcd10 Panasonic CD-ROM controller 2 unit 2 + 3 = /dev/sbpcd11 Panasonic CD-ROM controller 2 unit 3 + + 28 char Stallion serial card - card programming + 0 = /dev/staliomem0 First Stallion card I/O memory + 1 = /dev/staliomem1 Second Stallion card I/O memory + 2 = /dev/staliomem2 Third Stallion card I/O memory + 3 = /dev/staliomem3 Fourth Stallion card I/O memory + + 28 char Atari SLM ACSI laser printer (68k/Atari) + 0 = /dev/slm0 First SLM laser printer + 1 = /dev/slm1 Second SLM laser printer + ... + 28 block Fourth Matsushita (Panasonic/SoundBlaster) CD-ROM + 0 = /dev/sbpcd12 Panasonic CD-ROM controller 3 unit 0 + 1 = /dev/sbpcd13 Panasonic CD-ROM controller 3 unit 1 + 2 = /dev/sbpcd14 Panasonic CD-ROM controller 3 unit 2 + 3 = /dev/sbpcd15 Panasonic CD-ROM controller 3 unit 3 + + 28 block ACSI disk (68k/Atari) + 0 = /dev/ada First ACSI disk whole disk + 16 = /dev/adb Second ACSI disk whole disk + 32 = /dev/adc Third ACSI disk whole disk + ... + 240 = /dev/adp 16th ACSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15, like SCSI. + + 29 char Universal frame buffer + 0 = /dev/fb0 First frame buffer + 1 = /dev/fb1 Second frame buffer + ... + 31 = /dev/fb31 32nd frame buffer + + 29 block Aztech/Orchid/Okano/Wearnes CD-ROM + 0 = /dev/aztcd Aztech CD-ROM + + 30 char iBCS-2 compatibility devices + 0 = /dev/socksys Socket access + 1 = /dev/spx SVR3 local X interface + 32 = /dev/inet/ip Network access + 33 = /dev/inet/icmp + 34 = /dev/inet/ggp + 35 = /dev/inet/ipip + 36 = /dev/inet/tcp + 37 = /dev/inet/egp + 38 = /dev/inet/pup + 39 = /dev/inet/udp + 40 = /dev/inet/idp + 41 = /dev/inet/rawip + + Additionally, iBCS-2 requires the following links: + + /dev/ip -> /dev/inet/ip + /dev/icmp -> /dev/inet/icmp + /dev/ggp -> /dev/inet/ggp + /dev/ipip -> /dev/inet/ipip + /dev/tcp -> /dev/inet/tcp + /dev/egp -> /dev/inet/egp + /dev/pup -> /dev/inet/pup + /dev/udp -> /dev/inet/udp + /dev/idp -> /dev/inet/idp + /dev/rawip -> /dev/inet/rawip + /dev/inet/arp -> /dev/inet/udp + /dev/inet/rip -> /dev/inet/udp + /dev/nfsd -> /dev/socksys + /dev/X0R -> /dev/null (? apparently not required ?) + + 30 block Philips LMS CM-205 CD-ROM + 0 = /dev/cm205cd Philips LMS CM-205 CD-ROM + + /dev/lmscd is an older name for this device. This + driver does not work with the CM-205MS CD-ROM. + + 31 char MPU-401 MIDI + 0 = /dev/mpu401data MPU-401 data port + 1 = /dev/mpu401stat MPU-401 status port + + 31 block ROM/flash memory card + 0 = /dev/rom0 First ROM card (rw) + ... + 7 = /dev/rom7 Eighth ROM card (rw) + 8 = /dev/rrom0 First ROM card (ro) + ... + 15 = /dev/rrom7 Eighth ROM card (ro) + 16 = /dev/flash0 First flash memory card (rw) + ... + 23 = /dev/flash7 Eighth flash memory card (rw) + 24 = /dev/rflash0 First flash memory card (ro) + ... + 31 = /dev/rflash7 Eighth flash memory card (ro) + + The read-write (rw) devices support back-caching + written data in RAM, as well as writing to flash RAM + devices. The read-only devices (ro) support reading + only. + + 32 char Specialix serial card + 0 = /dev/ttyX0 First Specialix port + 1 = /dev/ttyX1 Second Specialix port + ... + 32 block Philips LMS CM-206 CD-ROM + 0 = /dev/cm206cd Philips LMS CM-206 CD-ROM + + 33 char Specialix serial card - alternate devices + 0 = /dev/cux0 Callout device for ttyX0 + 1 = /dev/cux1 Callout device for ttyX1 + ... + 33 block Third IDE hard disk/CD-ROM interface + 0 = /dev/hde Master: whole disk (or CD-ROM) + 64 = /dev/hdf Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 34 char Z8530 HDLC driver + 0 = /dev/scc0 First Z8530, first port + 1 = /dev/scc1 First Z8530, second port + 2 = /dev/scc2 Second Z8530, first port + 3 = /dev/scc3 Second Z8530, second port + ... + + In a previous version these devices were named + /dev/sc1 for /dev/scc0, /dev/sc2 for /dev/scc1, and so + on. + + 34 block Fourth IDE hard disk/CD-ROM interface + 0 = /dev/hdg Master: whole disk (or CD-ROM) + 64 = /dev/hdh Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 35 char tclmidi MIDI driver + 0 = /dev/midi0 First MIDI port, kernel timed + 1 = /dev/midi1 Second MIDI port, kernel timed + 2 = /dev/midi2 Third MIDI port, kernel timed + 3 = /dev/midi3 Fourth MIDI port, kernel timed + 64 = /dev/rmidi0 First MIDI port, untimed + 65 = /dev/rmidi1 Second MIDI port, untimed + 66 = /dev/rmidi2 Third MIDI port, untimed + 67 = /dev/rmidi3 Fourth MIDI port, untimed + 128 = /dev/smpte0 First MIDI port, SMPTE timed + 129 = /dev/smpte1 Second MIDI port, SMPTE timed + 130 = /dev/smpte2 Third MIDI port, SMPTE timed + 131 = /dev/smpte3 Fourth MIDI port, SMPTE timed + + 35 block Slow memory ramdisk + 0 = /dev/slram Slow memory ramdisk + + 36 char Netlink support + 0 = /dev/route Routing, device updates, kernel to user + 1 = /dev/skip enSKIP security cache control + 3 = /dev/fwmonitor Firewall packet copies + 16 = /dev/tap0 First Ethertap device + ... + 31 = /dev/tap15 16th Ethertap device + + 36 block OBSOLETE (was MCA ESDI hard disk) + + 37 char IDE tape + 0 = /dev/ht0 First IDE tape + 1 = /dev/ht1 Second IDE tape + ... + 128 = /dev/nht0 First IDE tape, no rewind-on-close + 129 = /dev/nht1 Second IDE tape, no rewind-on-close + ... + + Currently, only one IDE tape drive is supported. + + 37 block Zorro II ramdisk + 0 = /dev/z2ram Zorro II ramdisk + + 38 char Myricom PCI Myrinet board + 0 = /dev/mlanai0 First Myrinet board + 1 = /dev/mlanai1 Second Myrinet board + ... + + This device is used for status query, board control + and "user level packet I/O." This board is also + accessible as a standard networking "eth" device. + + 38 block OBSOLETE (was Linux/AP+) + + 39 char ML-16P experimental I/O board + 0 = /dev/ml16pa-a0 First card, first analog channel + 1 = /dev/ml16pa-a1 First card, second analog channel + ... + 15 = /dev/ml16pa-a15 First card, 16th analog channel + 16 = /dev/ml16pa-d First card, digital lines + 17 = /dev/ml16pa-c0 First card, first counter/timer + 18 = /dev/ml16pa-c1 First card, second counter/timer + 19 = /dev/ml16pa-c2 First card, third counter/timer + 32 = /dev/ml16pb-a0 Second card, first analog channel + 33 = /dev/ml16pb-a1 Second card, second analog channel + ... + 47 = /dev/ml16pb-a15 Second card, 16th analog channel + 48 = /dev/ml16pb-d Second card, digital lines + 49 = /dev/ml16pb-c0 Second card, first counter/timer + 50 = /dev/ml16pb-c1 Second card, second counter/timer + 51 = /dev/ml16pb-c2 Second card, third counter/timer + ... + 39 block + + 40 char + + 40 block + + 41 char Yet Another Micro Monitor + 0 = /dev/yamm Yet Another Micro Monitor + + 41 block + + 42 char Demo/sample use + + 42 block Demo/sample use + + This number is intended for use in sample code, as + well as a general "example" device number. It + should never be used for a device driver that is being + distributed; either obtain an official number or use + the local/experimental range. The sudden addition or + removal of a driver with this number should not cause + ill effects to the system (bugs excepted.) + + IN PARTICULAR, ANY DISTRIBUTION WHICH CONTAINS A + DEVICE DRIVER USING MAJOR NUMBER 42 IS NONCOMPLIANT. + + 43 char isdn4linux virtual modem + 0 = /dev/ttyI0 First virtual modem + ... + 63 = /dev/ttyI63 64th virtual modem + + 43 block Network block devices + 0 = /dev/nb0 First network block device + 1 = /dev/nb1 Second network block device + ... + + Network Block Device is somehow similar to loopback + devices: If you read from it, it sends packet across + network asking server for data. If you write to it, it + sends packet telling server to write. It could be used + to mounting filesystems over the net, swapping over + the net, implementing block device in userland etc. + + 44 char isdn4linux virtual modem - alternate devices + 0 = /dev/cui0 Callout device for ttyI0 + ... + 63 = /dev/cui63 Callout device for ttyI63 + + 44 block Flash Translation Layer (FTL) filesystems + 0 = /dev/ftla FTL on first Memory Technology Device + 16 = /dev/ftlb FTL on second Memory Technology Device + 32 = /dev/ftlc FTL on third Memory Technology Device + ... + 240 = /dev/ftlp FTL on 16th Memory Technology Device + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the partition + limit is 15 rather than 63 per disk (same as SCSI.) + + 45 char isdn4linux ISDN BRI driver + 0 = /dev/isdn0 First virtual B channel raw data + ... + 63 = /dev/isdn63 64th virtual B channel raw data + 64 = /dev/isdnctrl0 First channel control/debug + ... + 127 = /dev/isdnctrl63 64th channel control/debug + + 128 = /dev/ippp0 First SyncPPP device + ... + 191 = /dev/ippp63 64th SyncPPP device + + 255 = /dev/isdninfo ISDN monitor interface + + 45 block Parallel port IDE disk devices + 0 = /dev/pda First parallel port IDE disk + 16 = /dev/pdb Second parallel port IDE disk + 32 = /dev/pdc Third parallel port IDE disk + 48 = /dev/pdd Fourth parallel port IDE disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the partition + limit is 15 rather than 63 per disk. + + 46 char Comtrol Rocketport serial card + 0 = /dev/ttyR0 First Rocketport port + 1 = /dev/ttyR1 Second Rocketport port + ... + 46 block Parallel port ATAPI CD-ROM devices + 0 = /dev/pcd0 First parallel port ATAPI CD-ROM + 1 = /dev/pcd1 Second parallel port ATAPI CD-ROM + 2 = /dev/pcd2 Third parallel port ATAPI CD-ROM + 3 = /dev/pcd3 Fourth parallel port ATAPI CD-ROM + + 47 char Comtrol Rocketport serial card - alternate devices + 0 = /dev/cur0 Callout device for ttyR0 + 1 = /dev/cur1 Callout device for ttyR1 + ... + 47 block Parallel port ATAPI disk devices + 0 = /dev/pf0 First parallel port ATAPI disk + 1 = /dev/pf1 Second parallel port ATAPI disk + 2 = /dev/pf2 Third parallel port ATAPI disk + 3 = /dev/pf3 Fourth parallel port ATAPI disk + + This driver is intended for floppy disks and similar + devices and hence does not support partitioning. + + 48 char SDL RISCom serial card + 0 = /dev/ttyL0 First RISCom port + 1 = /dev/ttyL1 Second RISCom port + ... + 48 block Mylex DAC960 PCI RAID controller; first controller + 0 = /dev/rd/c0d0 First disk, whole disk + 8 = /dev/rd/c0d1 Second disk, whole disk + ... + 248 = /dev/rd/c0d31 32nd disk, whole disk + + For partitions add: + 0 = /dev/rd/c?d? Whole disk + 1 = /dev/rd/c?d?p1 First partition + ... + 7 = /dev/rd/c?d?p7 Seventh partition + + 49 char SDL RISCom serial card - alternate devices + 0 = /dev/cul0 Callout device for ttyL0 + 1 = /dev/cul1 Callout device for ttyL1 + ... + 49 block Mylex DAC960 PCI RAID controller; second controller + 0 = /dev/rd/c1d0 First disk, whole disk + 8 = /dev/rd/c1d1 Second disk, whole disk + ... + 248 = /dev/rd/c1d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 50 char Reserved for GLINT + + 50 block Mylex DAC960 PCI RAID controller; third controller + 0 = /dev/rd/c2d0 First disk, whole disk + 8 = /dev/rd/c2d1 Second disk, whole disk + ... + 248 = /dev/rd/c2d31 32nd disk, whole disk + + 51 char Baycom radio modem OR Radio Tech BIM-XXX-RS232 radio modem + 0 = /dev/bc0 First Baycom radio modem + 1 = /dev/bc1 Second Baycom radio modem + ... + 51 block Mylex DAC960 PCI RAID controller; fourth controller + 0 = /dev/rd/c3d0 First disk, whole disk + 8 = /dev/rd/c3d1 Second disk, whole disk + ... + 248 = /dev/rd/c3d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 52 char Spellcaster DataComm/BRI ISDN card + 0 = /dev/dcbri0 First DataComm card + 1 = /dev/dcbri1 Second DataComm card + 2 = /dev/dcbri2 Third DataComm card + 3 = /dev/dcbri3 Fourth DataComm card + + 52 block Mylex DAC960 PCI RAID controller; fifth controller + 0 = /dev/rd/c4d0 First disk, whole disk + 8 = /dev/rd/c4d1 Second disk, whole disk + ... + 248 = /dev/rd/c4d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 53 char BDM interface for remote debugging MC683xx microcontrollers + 0 = /dev/pd_bdm0 PD BDM interface on lp0 + 1 = /dev/pd_bdm1 PD BDM interface on lp1 + 2 = /dev/pd_bdm2 PD BDM interface on lp2 + 4 = /dev/icd_bdm0 ICD BDM interface on lp0 + 5 = /dev/icd_bdm1 ICD BDM interface on lp1 + 6 = /dev/icd_bdm2 ICD BDM interface on lp2 + + This device is used for the interfacing to the MC683xx + microcontrollers via Background Debug Mode by use of a + Parallel Port interface. PD is the Motorola Public + Domain Interface and ICD is the commercial interface + by P&E. + + 53 block Mylex DAC960 PCI RAID controller; sixth controller + 0 = /dev/rd/c5d0 First disk, whole disk + 8 = /dev/rd/c5d1 Second disk, whole disk + ... + 248 = /dev/rd/c5d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 54 char Electrocardiognosis Holter serial card + 0 = /dev/holter0 First Holter port + 1 = /dev/holter1 Second Holter port + 2 = /dev/holter2 Third Holter port + + A custom serial card used by Electrocardiognosis SRL + to transfer data from Holter + 24-hour heart monitoring equipment. + + 54 block Mylex DAC960 PCI RAID controller; seventh controller + 0 = /dev/rd/c6d0 First disk, whole disk + 8 = /dev/rd/c6d1 Second disk, whole disk + ... + 248 = /dev/rd/c6d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 55 char DSP56001 digital signal processor + 0 = /dev/dsp56k First DSP56001 + + 55 block Mylex DAC960 PCI RAID controller; eighth controller + 0 = /dev/rd/c7d0 First disk, whole disk + 8 = /dev/rd/c7d1 Second disk, whole disk + ... + 248 = /dev/rd/c7d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 56 char Apple Desktop Bus + 0 = /dev/adb ADB bus control + + Additional devices will be added to this number, all + starting with /dev/adb. + + 56 block Fifth IDE hard disk/CD-ROM interface + 0 = /dev/hdi Master: whole disk (or CD-ROM) + 64 = /dev/hdj Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 57 char Hayes ESP serial card + 0 = /dev/ttyP0 First ESP port + 1 = /dev/ttyP1 Second ESP port + ... + + 57 block Sixth IDE hard disk/CD-ROM interface + 0 = /dev/hdk Master: whole disk (or CD-ROM) + 64 = /dev/hdl Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 58 char Hayes ESP serial card - alternate devices + 0 = /dev/cup0 Callout device for ttyP0 + 1 = /dev/cup1 Callout device for ttyP1 + ... + + 58 block Reserved for logical volume manager + + 59 char sf firewall package + 0 = /dev/firewall Communication with sf kernel module + + 59 block Generic PDA filesystem device + 0 = /dev/pda0 First PDA device + 1 = /dev/pda1 Second PDA device + ... + + The pda devices are used to mount filesystems on + remote pda's (basically slow handheld machines with + proprietary OS's and limited memory and storage + running small fs translation drivers) through serial / + IRDA / parallel links. + + NAMING CONFLICT -- PROPOSED REVISED NAME /dev/rpda0 etc + + 60-63 char LOCAL/EXPERIMENTAL USE + + 60-63 block LOCAL/EXPERIMENTAL USE + Allocated for local/experimental use. For devices not + assigned official numbers, these ranges should be + used in order to avoid conflicting with future assignments. + + 64 char ENskip kernel encryption package + 0 = /dev/enskip Communication with ENskip kernel module + + 64 block Scramdisk/DriveCrypt encrypted devices + 0 = /dev/scramdisk/master Master node for ioctls + 1 = /dev/scramdisk/1 First encrypted device + 2 = /dev/scramdisk/2 Second encrypted device + ... + 255 = /dev/scramdisk/255 255th encrypted device + + The filename of the encrypted container and the passwords + are sent via ioctls (using the sdmount tool) to the master + node which then activates them via one of the + /dev/scramdisk/x nodes for loop mounting (all handled + through the sdmount tool). + + Requested by: andy@scramdisklinux.org + + 65 char Sundance "plink" Transputer boards (obsolete, unused) + 0 = /dev/plink0 First plink device + 1 = /dev/plink1 Second plink device + 2 = /dev/plink2 Third plink device + 3 = /dev/plink3 Fourth plink device + 64 = /dev/rplink0 First plink device, raw + 65 = /dev/rplink1 Second plink device, raw + 66 = /dev/rplink2 Third plink device, raw + 67 = /dev/rplink3 Fourth plink device, raw + 128 = /dev/plink0d First plink device, debug + 129 = /dev/plink1d Second plink device, debug + 130 = /dev/plink2d Third plink device, debug + 131 = /dev/plink3d Fourth plink device, debug + 192 = /dev/rplink0d First plink device, raw, debug + 193 = /dev/rplink1d Second plink device, raw, debug + 194 = /dev/rplink2d Third plink device, raw, debug + 195 = /dev/rplink3d Fourth plink device, raw, debug + + This is a commercial driver; contact James Howes + for information. + + 65 block SCSI disk devices (16-31) + 0 = /dev/sdq 17th SCSI disk whole disk + 16 = /dev/sdr 18th SCSI disk whole disk + 32 = /dev/sds 19th SCSI disk whole disk + ... + 240 = /dev/sdaf 32nd SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 66 char YARC PowerPC PCI coprocessor card + 0 = /dev/yppcpci0 First YARC card + 1 = /dev/yppcpci1 Second YARC card + ... + + 66 block SCSI disk devices (32-47) + 0 = /dev/sdag 33th SCSI disk whole disk + 16 = /dev/sdah 34th SCSI disk whole disk + 32 = /dev/sdai 35th SCSI disk whole disk + ... + 240 = /dev/sdav 48nd SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 67 char Coda network file system + 0 = /dev/cfs0 Coda cache manager + + See http://www.coda.cs.cmu.edu for information about Coda. + + 67 block SCSI disk devices (48-63) + 0 = /dev/sdaw 49th SCSI disk whole disk + 16 = /dev/sdax 50th SCSI disk whole disk + 32 = /dev/sday 51st SCSI disk whole disk + ... + 240 = /dev/sdbl 64th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 68 char CAPI 2.0 interface + 0 = /dev/capi20 Control device + 1 = /dev/capi20.00 First CAPI 2.0 application + 2 = /dev/capi20.01 Second CAPI 2.0 application + ... + 20 = /dev/capi20.19 19th CAPI 2.0 application + + ISDN CAPI 2.0 driver for use with CAPI 2.0 + applications; currently supports the AVM B1 card. + + 68 block SCSI disk devices (64-79) + 0 = /dev/sdbm 65th SCSI disk whole disk + 16 = /dev/sdbn 66th SCSI disk whole disk + 32 = /dev/sdbo 67th SCSI disk whole disk + ... + 240 = /dev/sdcb 80th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 69 char MA16 numeric accelerator card + 0 = /dev/ma16 Board memory access + + 69 block SCSI disk devices (80-95) + 0 = /dev/sdcc 81st SCSI disk whole disk + 16 = /dev/sdcd 82nd SCSI disk whole disk + 32 = /dev/sdce 83th SCSI disk whole disk + ... + 240 = /dev/sdcr 96th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 70 char SpellCaster Protocol Services Interface + 0 = /dev/apscfg Configuration interface + 1 = /dev/apsauth Authentication interface + 2 = /dev/apslog Logging interface + 3 = /dev/apsdbg Debugging interface + 64 = /dev/apsisdn ISDN command interface + 65 = /dev/apsasync Async command interface + 128 = /dev/apsmon Monitor interface + + 70 block SCSI disk devices (96-111) + 0 = /dev/sdcs 97th SCSI disk whole disk + 16 = /dev/sdct 98th SCSI disk whole disk + 32 = /dev/sdcu 99th SCSI disk whole disk + ... + 240 = /dev/sddh 112nd SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 71 char Computone IntelliPort II serial card + 0 = /dev/ttyF0 IntelliPort II board 0, port 0 + 1 = /dev/ttyF1 IntelliPort II board 0, port 1 + ... + 63 = /dev/ttyF63 IntelliPort II board 0, port 63 + 64 = /dev/ttyF64 IntelliPort II board 1, port 0 + 65 = /dev/ttyF65 IntelliPort II board 1, port 1 + ... + 127 = /dev/ttyF127 IntelliPort II board 1, port 63 + 128 = /dev/ttyF128 IntelliPort II board 2, port 0 + 129 = /dev/ttyF129 IntelliPort II board 2, port 1 + ... + 191 = /dev/ttyF191 IntelliPort II board 2, port 63 + 192 = /dev/ttyF192 IntelliPort II board 3, port 0 + 193 = /dev/ttyF193 IntelliPort II board 3, port 1 + ... + 255 = /dev/ttyF255 IntelliPort II board 3, port 63 + + 71 block SCSI disk devices (112-127) + 0 = /dev/sddi 113th SCSI disk whole disk + 16 = /dev/sddj 114th SCSI disk whole disk + 32 = /dev/sddk 115th SCSI disk whole disk + ... + 240 = /dev/sddx 128th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 72 char Computone IntelliPort II serial card - alternate devices + 0 = /dev/cuf0 Callout device for ttyF0 + 1 = /dev/cuf1 Callout device for ttyF1 + ... + 63 = /dev/cuf63 Callout device for ttyF63 + 64 = /dev/cuf64 Callout device for ttyF64 + 65 = /dev/cuf65 Callout device for ttyF65 + ... + 127 = /dev/cuf127 Callout device for ttyF127 + 128 = /dev/cuf128 Callout device for ttyF128 + 129 = /dev/cuf129 Callout device for ttyF129 + ... + 191 = /dev/cuf191 Callout device for ttyF191 + 192 = /dev/cuf192 Callout device for ttyF192 + 193 = /dev/cuf193 Callout device for ttyF193 + ... + 255 = /dev/cuf255 Callout device for ttyF255 + + 72 block Compaq Intelligent Drive Array, first controller + 0 = /dev/ida/c0d0 First logical drive whole disk + 16 = /dev/ida/c0d1 Second logical drive whole disk + ... + 240 = /dev/ida/c0d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 73 char Computone IntelliPort II serial card - control devices + 0 = /dev/ip2ipl0 Loadware device for board 0 + 1 = /dev/ip2stat0 Status device for board 0 + 4 = /dev/ip2ipl1 Loadware device for board 1 + 5 = /dev/ip2stat1 Status device for board 1 + 8 = /dev/ip2ipl2 Loadware device for board 2 + 9 = /dev/ip2stat2 Status device for board 2 + 12 = /dev/ip2ipl3 Loadware device for board 3 + 13 = /dev/ip2stat3 Status device for board 3 + + 73 block Compaq Intelligent Drive Array, second controller + 0 = /dev/ida/c1d0 First logical drive whole disk + 16 = /dev/ida/c1d1 Second logical drive whole disk + ... + 240 = /dev/ida/c1d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 74 char SCI bridge + 0 = /dev/SCI/0 SCI device 0 + 1 = /dev/SCI/1 SCI device 1 + ... + + Currently for Dolphin Interconnect Solutions' PCI-SCI + bridge. + + 74 block Compaq Intelligent Drive Array, third controller + 0 = /dev/ida/c2d0 First logical drive whole disk + 16 = /dev/ida/c2d1 Second logical drive whole disk + ... + 240 = /dev/ida/c2d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 75 char Specialix IO8+ serial card + 0 = /dev/ttyW0 First IO8+ port, first card + 1 = /dev/ttyW1 Second IO8+ port, first card + ... + 8 = /dev/ttyW8 First IO8+ port, second card + ... + + 75 block Compaq Intelligent Drive Array, fourth controller + 0 = /dev/ida/c3d0 First logical drive whole disk + 16 = /dev/ida/c3d1 Second logical drive whole disk + ... + 240 = /dev/ida/c3d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 76 char Specialix IO8+ serial card - alternate devices + 0 = /dev/cuw0 Callout device for ttyW0 + 1 = /dev/cuw1 Callout device for ttyW1 + ... + 8 = /dev/cuw8 Callout device for ttyW8 + ... + + 76 block Compaq Intelligent Drive Array, fifth controller + 0 = /dev/ida/c4d0 First logical drive whole disk + 16 = /dev/ida/c4d1 Second logical drive whole disk + ... + 240 = /dev/ida/c4d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + + 77 char ComScire Quantum Noise Generator + 0 = /dev/qng ComScire Quantum Noise Generator + + 77 block Compaq Intelligent Drive Array, sixth controller + 0 = /dev/ida/c5d0 First logical drive whole disk + 16 = /dev/ida/c5d1 Second logical drive whole disk + ... + 240 = /dev/ida/c5d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 78 char PAM Software's multimodem boards + 0 = /dev/ttyM0 First PAM modem + 1 = /dev/ttyM1 Second PAM modem + ... + + 78 block Compaq Intelligent Drive Array, seventh controller + 0 = /dev/ida/c6d0 First logical drive whole disk + 16 = /dev/ida/c6d1 Second logical drive whole disk + ... + 240 = /dev/ida/c6d15 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 79 char PAM Software's multimodem boards - alternate devices + 0 = /dev/cum0 Callout device for ttyM0 + 1 = /dev/cum1 Callout device for ttyM1 + ... + + 79 block Compaq Intelligent Drive Array, eighth controller + 0 = /dev/ida/c7d0 First logical drive whole disk + 16 = /dev/ida/c7d1 Second logical drive whole disk + ... + 240 = /dev/ida/c715 16th logical drive whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 80 char Photometrics AT200 CCD camera + 0 = /dev/at200 Photometrics AT200 CCD camera + + 80 block I2O hard disk + 0 = /dev/i2o/hda First I2O hard disk, whole disk + 16 = /dev/i2o/hdb Second I2O hard disk, whole disk + ... + 240 = /dev/i2o/hdp 16th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 81 char video4linux + 0 = /dev/video0 Video capture/overlay device + ... + 63 = /dev/video63 Video capture/overlay device + 64 = /dev/radio0 Radio device + ... + 127 = /dev/radio63 Radio device + 128 = /dev/swradio0 Software Defined Radio device + ... + 191 = /dev/swradio63 Software Defined Radio device + 224 = /dev/vbi0 Vertical blank interrupt + ... + 255 = /dev/vbi31 Vertical blank interrupt + + Minor numbers are allocated dynamically unless + CONFIG_VIDEO_FIXED_MINOR_RANGES (default n) + configuration option is set. + + 81 block I2O hard disk + 0 = /dev/i2o/hdq 17th I2O hard disk, whole disk + 16 = /dev/i2o/hdr 18th I2O hard disk, whole disk + ... + 240 = /dev/i2o/hdaf 32nd I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 82 char WiNRADiO communications receiver card + 0 = /dev/winradio0 First WiNRADiO card + 1 = /dev/winradio1 Second WiNRADiO card + ... + + The driver and documentation may be obtained from + http://www.winradio.com/ + + 82 block I2O hard disk + 0 = /dev/i2o/hdag 33rd I2O hard disk, whole disk + 16 = /dev/i2o/hdah 34th I2O hard disk, whole disk + ... + 240 = /dev/i2o/hdav 48th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 83 char Matrox mga_vid video driver + 0 = /dev/mga_vid0 1st video card + 1 = /dev/mga_vid1 2nd video card + 2 = /dev/mga_vid2 3rd video card + ... + 15 = /dev/mga_vid15 16th video card + + 83 block I2O hard disk + 0 = /dev/i2o/hdaw 49th I2O hard disk, whole disk + 16 = /dev/i2o/hdax 50th I2O hard disk, whole disk + ... + 240 = /dev/i2o/hdbl 64th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 84 char Ikon 1011[57] Versatec Greensheet Interface + 0 = /dev/ihcp0 First Greensheet port + 1 = /dev/ihcp1 Second Greensheet port + + 84 block I2O hard disk + 0 = /dev/i2o/hdbm 65th I2O hard disk, whole disk + 16 = /dev/i2o/hdbn 66th I2O hard disk, whole disk + ... + 240 = /dev/i2o/hdcb 80th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 85 char Linux/SGI shared memory input queue + 0 = /dev/shmiq Master shared input queue + 1 = /dev/qcntl0 First device pushed + 2 = /dev/qcntl1 Second device pushed + ... + + 85 block I2O hard disk + 0 = /dev/i2o/hdcc 81st I2O hard disk, whole disk + 16 = /dev/i2o/hdcd 82nd I2O hard disk, whole disk + ... + 240 = /dev/i2o/hdcr 96th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 86 char SCSI media changer + 0 = /dev/sch0 First SCSI media changer + 1 = /dev/sch1 Second SCSI media changer + ... + + 86 block I2O hard disk + 0 = /dev/i2o/hdcs 97th I2O hard disk, whole disk + 16 = /dev/i2o/hdct 98th I2O hard disk, whole disk + ... + 240 = /dev/i2o/hddh 112th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 87 char Sony Control-A1 stereo control bus + 0 = /dev/controla0 First device on chain + 1 = /dev/controla1 Second device on chain + ... + + 87 block I2O hard disk + 0 = /dev/i2o/hddi 113rd I2O hard disk, whole disk + 16 = /dev/i2o/hddj 114th I2O hard disk, whole disk + ... + 240 = /dev/i2o/hddx 128th I2O hard disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 88 char COMX synchronous serial card + 0 = /dev/comx0 COMX channel 0 + 1 = /dev/comx1 COMX channel 1 + ... + + 88 block Seventh IDE hard disk/CD-ROM interface + 0 = /dev/hdm Master: whole disk (or CD-ROM) + 64 = /dev/hdn Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 89 char I2C bus interface + 0 = /dev/i2c-0 First I2C adapter + 1 = /dev/i2c-1 Second I2C adapter + ... + + 89 block Eighth IDE hard disk/CD-ROM interface + 0 = /dev/hdo Master: whole disk (or CD-ROM) + 64 = /dev/hdp Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 90 char Memory Technology Device (RAM, ROM, Flash) + 0 = /dev/mtd0 First MTD (rw) + 1 = /dev/mtdr0 First MTD (ro) + ... + 30 = /dev/mtd15 16th MTD (rw) + 31 = /dev/mtdr15 16th MTD (ro) + + 90 block Ninth IDE hard disk/CD-ROM interface + 0 = /dev/hdq Master: whole disk (or CD-ROM) + 64 = /dev/hdr Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 91 char CAN-Bus devices + 0 = /dev/can0 First CAN-Bus controller + 1 = /dev/can1 Second CAN-Bus controller + ... + + 91 block Tenth IDE hard disk/CD-ROM interface + 0 = /dev/hds Master: whole disk (or CD-ROM) + 64 = /dev/hdt Slave: whole disk (or CD-ROM) + + Partitions are handled the same way as for the first + interface (see major number 3). + + 92 char Reserved for ith Kommunikationstechnik MIC ISDN card + + 92 block PPDD encrypted disk driver + 0 = /dev/ppdd0 First encrypted disk + 1 = /dev/ppdd1 Second encrypted disk + ... + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 93 char + + 93 block NAND Flash Translation Layer filesystem + 0 = /dev/nftla First NFTL layer + 16 = /dev/nftlb Second NFTL layer + ... + 240 = /dev/nftlp 16th NTFL layer + + 94 char + + 94 block IBM S/390 DASD block storage + 0 = /dev/dasda First DASD device, major + 1 = /dev/dasda1 First DASD device, block 1 + 2 = /dev/dasda2 First DASD device, block 2 + 3 = /dev/dasda3 First DASD device, block 3 + 4 = /dev/dasdb Second DASD device, major + 5 = /dev/dasdb1 Second DASD device, block 1 + 6 = /dev/dasdb2 Second DASD device, block 2 + 7 = /dev/dasdb3 Second DASD device, block 3 + ... + + 95 char IP filter + 0 = /dev/ipl Filter control device/log file + 1 = /dev/ipnat NAT control device/log file + 2 = /dev/ipstate State information log file + 3 = /dev/ipauth Authentication control device/log file + ... + + 96 char Parallel port ATAPI tape devices + 0 = /dev/pt0 First parallel port ATAPI tape + 1 = /dev/pt1 Second parallel port ATAPI tape + ... + 128 = /dev/npt0 First p.p. ATAPI tape, no rewind + 129 = /dev/npt1 Second p.p. ATAPI tape, no rewind + ... + + 96 block Inverse NAND Flash Translation Layer + 0 = /dev/inftla First INFTL layer + 16 = /dev/inftlb Second INFTL layer + ... + 240 = /dev/inftlp 16th INTFL layer + + 97 char Parallel port generic ATAPI interface + 0 = /dev/pg0 First parallel port ATAPI device + 1 = /dev/pg1 Second parallel port ATAPI device + 2 = /dev/pg2 Third parallel port ATAPI device + 3 = /dev/pg3 Fourth parallel port ATAPI device + + These devices support the same API as the generic SCSI + devices. + + 98 char Control and Measurement Device (comedi) + 0 = /dev/comedi0 First comedi device + 1 = /dev/comedi1 Second comedi device + ... + + See http://stm.lbl.gov/comedi. + + 98 block User-mode virtual block device + 0 = /dev/ubda First user-mode block device + 16 = /dev/udbb Second user-mode block device + ... + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + This device is used by the user-mode virtual kernel port. + + 99 char Raw parallel ports + 0 = /dev/parport0 First parallel port + 1 = /dev/parport1 Second parallel port + ... + + 99 block JavaStation flash disk + 0 = /dev/jsfd JavaStation flash disk + + 100 char Telephony for Linux + 0 = /dev/phone0 First telephony device + 1 = /dev/phone1 Second telephony device + ... + + 101 char Motorola DSP 56xxx board + 0 = /dev/mdspstat Status information + 1 = /dev/mdsp1 First DSP board I/O controls + ... + 16 = /dev/mdsp16 16th DSP board I/O controls + + 101 block AMI HyperDisk RAID controller + 0 = /dev/amiraid/ar0 First array whole disk + 16 = /dev/amiraid/ar1 Second array whole disk + ... + 240 = /dev/amiraid/ar15 16th array whole disk + + For each device, partitions are added as: + 0 = /dev/amiraid/ar? Whole disk + 1 = /dev/amiraid/ar?p1 First partition + 2 = /dev/amiraid/ar?p2 Second partition + ... + 15 = /dev/amiraid/ar?p15 15th partition + + 102 char + + 102 block Compressed block device + 0 = /dev/cbd/a First compressed block device, whole device + 16 = /dev/cbd/b Second compressed block device, whole device + ... + 240 = /dev/cbd/p 16th compressed block device, whole device + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 103 char Arla network file system + 0 = /dev/nnpfs0 First NNPFS device + 1 = /dev/nnpfs1 Second NNPFS device + + Arla is a free clone of the Andrew File System, AFS. + The NNPFS device gives user mode filesystem + implementations a kernel presence for caching and easy + mounting. For more information about the project, + write to or see + http://www.stacken.kth.se/project/arla/ + + 103 block Audit device + 0 = /dev/audit Audit device + + 104 char Flash BIOS support + + 104 block Compaq Next Generation Drive Array, first controller + 0 = /dev/cciss/c0d0 First logical drive, whole disk + 16 = /dev/cciss/c0d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c0d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 105 char Comtrol VS-1000 serial controller + 0 = /dev/ttyV0 First VS-1000 port + 1 = /dev/ttyV1 Second VS-1000 port + ... + + 105 block Compaq Next Generation Drive Array, second controller + 0 = /dev/cciss/c1d0 First logical drive, whole disk + 16 = /dev/cciss/c1d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c1d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 106 char Comtrol VS-1000 serial controller - alternate devices + 0 = /dev/cuv0 First VS-1000 port + 1 = /dev/cuv1 Second VS-1000 port + ... + + 106 block Compaq Next Generation Drive Array, third controller + 0 = /dev/cciss/c2d0 First logical drive, whole disk + 16 = /dev/cciss/c2d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c2d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 107 char 3Dfx Voodoo Graphics device + 0 = /dev/3dfx Primary 3Dfx graphics device + + 107 block Compaq Next Generation Drive Array, fourth controller + 0 = /dev/cciss/c3d0 First logical drive, whole disk + 16 = /dev/cciss/c3d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c3d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 108 char Device independent PPP interface + 0 = /dev/ppp Device independent PPP interface + + 108 block Compaq Next Generation Drive Array, fifth controller + 0 = /dev/cciss/c4d0 First logical drive, whole disk + 16 = /dev/cciss/c4d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c4d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 109 char Reserved for logical volume manager + + 109 block Compaq Next Generation Drive Array, sixth controller + 0 = /dev/cciss/c5d0 First logical drive, whole disk + 16 = /dev/cciss/c5d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c5d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 110 char miroMEDIA Surround board + 0 = /dev/srnd0 First miroMEDIA Surround board + 1 = /dev/srnd1 Second miroMEDIA Surround board + ... + + 110 block Compaq Next Generation Drive Array, seventh controller + 0 = /dev/cciss/c6d0 First logical drive, whole disk + 16 = /dev/cciss/c6d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c6d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 111 char + + 111 block Compaq Next Generation Drive Array, eighth controller + 0 = /dev/cciss/c7d0 First logical drive, whole disk + 16 = /dev/cciss/c7d1 Second logical drive, whole disk + ... + 240 = /dev/cciss/c7d15 16th logical drive, whole disk + + Partitions are handled the same way as for Mylex + DAC960 (see major number 48) except that the limit on + partitions is 15. + + 112 char ISI serial card + 0 = /dev/ttyM0 First ISI port + 1 = /dev/ttyM1 Second ISI port + ... + + There is currently a device-naming conflict between + these and PAM multimodems (major 78). + + 112 block IBM iSeries virtual disk + 0 = /dev/iseries/vda First virtual disk, whole disk + 8 = /dev/iseries/vdb Second virtual disk, whole disk + ... + 200 = /dev/iseries/vdz 26th virtual disk, whole disk + 208 = /dev/iseries/vdaa 27th virtual disk, whole disk + ... + 248 = /dev/iseries/vdaf 32nd virtual disk, whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 7. + + 113 char ISI serial card - alternate devices + 0 = /dev/cum0 Callout device for ttyM0 + 1 = /dev/cum1 Callout device for ttyM1 + ... + + 113 block IBM iSeries virtual CD-ROM + 0 = /dev/iseries/vcda First virtual CD-ROM + 1 = /dev/iseries/vcdb Second virtual CD-ROM + ... + + 114 char Picture Elements ISE board + 0 = /dev/ise0 First ISE board + 1 = /dev/ise1 Second ISE board + ... + 128 = /dev/isex0 Control node for first ISE board + 129 = /dev/isex1 Control node for second ISE board + ... + + The ISE board is an embedded computer, optimized for + image processing. The /dev/iseN nodes are the general + I/O access to the board, the /dev/isex0 nodes command + nodes used to control the board. + + 114 block IDE BIOS powered software RAID interfaces such as the + Promise Fastrak + + 0 = /dev/ataraid/d0 + 1 = /dev/ataraid/d0p1 + 2 = /dev/ataraid/d0p2 + ... + 16 = /dev/ataraid/d1 + 17 = /dev/ataraid/d1p1 + 18 = /dev/ataraid/d1p2 + ... + 255 = /dev/ataraid/d15p15 + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 115 char TI link cable devices (115 was formerly the console driver speaker) + 0 = /dev/tipar0 Parallel cable on first parallel port + ... + 7 = /dev/tipar7 Parallel cable on seventh parallel port + + 8 = /dev/tiser0 Serial cable on first serial port + ... + 15 = /dev/tiser7 Serial cable on seventh serial port + + 16 = /dev/tiusb0 First USB cable + ... + 47 = /dev/tiusb31 32nd USB cable + + 115 block NetWare (NWFS) Devices (0-255) + + The NWFS (NetWare) devices are used to present a + collection of NetWare Mirror Groups or NetWare + Partitions as a logical storage segment for + use in mounting NetWare volumes. A maximum of + 256 NetWare volumes can be supported in a single + machine. + + http://cgfa.telepac.pt/ftp2/kernel.org/linux/kernel/people/jmerkey/nwfs/ + + 0 = /dev/nwfs/v0 First NetWare (NWFS) Logical Volume + 1 = /dev/nwfs/v1 Second NetWare (NWFS) Logical Volume + 2 = /dev/nwfs/v2 Third NetWare (NWFS) Logical Volume + ... + 255 = /dev/nwfs/v255 Last NetWare (NWFS) Logical Volume + + 116 char Advanced Linux Sound Driver (ALSA) + + 116 block MicroMemory battery backed RAM adapter (NVRAM) + Supports 16 boards, 15 partitions each. + Requested by neilb at cse.unsw.edu.au. + + 0 = /dev/umem/d0 Whole of first board + 1 = /dev/umem/d0p1 First partition of first board + 2 = /dev/umem/d0p2 Second partition of first board + 15 = /dev/umem/d0p15 15th partition of first board + + 16 = /dev/umem/d1 Whole of second board + 17 = /dev/umem/d1p1 First partition of second board + ... + 255= /dev/umem/d15p15 15th partition of 16th board. + + 117 char COSA/SRP synchronous serial card + 0 = /dev/cosa0c0 1st board, 1st channel + 1 = /dev/cosa0c1 1st board, 2nd channel + ... + 16 = /dev/cosa1c0 2nd board, 1st channel + 17 = /dev/cosa1c1 2nd board, 2nd channel + ... + + 117 block Enterprise Volume Management System (EVMS) + + The EVMS driver uses a layered, plug-in model to provide + unparalleled flexibility and extensibility in managing + storage. This allows for easy expansion or customization + of various levels of volume management. Requested by + Mark Peloquin (peloquin at us.ibm.com). + + Note: EVMS populates and manages all the devnodes in + /dev/evms. + + http://sf.net/projects/evms + + 0 = /dev/evms/block_device EVMS block device + 1 = /dev/evms/legacyname1 First EVMS legacy device + 2 = /dev/evms/legacyname2 Second EVMS legacy device + ... + Both ranges can grow (down or up) until they meet. + ... + 254 = /dev/evms/EVMSname2 Second EVMS native device + 255 = /dev/evms/EVMSname1 First EVMS native device + + Note: legacyname(s) are derived from the normal legacy + device names. For example, /dev/hda5 would become + /dev/evms/hda5. + + 118 char IBM Cryptographic Accelerator + 0 = /dev/ica Virtual interface to all IBM Crypto Accelerators + 1 = /dev/ica0 IBMCA Device 0 + 2 = /dev/ica1 IBMCA Device 1 + ... + + 119 char VMware virtual network control + 0 = /dev/vnet0 1st virtual network + 1 = /dev/vnet1 2nd virtual network + ... + + 120-127 char LOCAL/EXPERIMENTAL USE + + 120-127 block LOCAL/EXPERIMENTAL USE + Allocated for local/experimental use. For devices not + assigned official numbers, these ranges should be + used in order to avoid conflicting with future assignments. + + 128-135 char Unix98 PTY masters + + These devices should not have corresponding device + nodes; instead they should be accessed through the + /dev/ptmx cloning interface. + + 128 block SCSI disk devices (128-143) + 0 = /dev/sddy 129th SCSI disk whole disk + 16 = /dev/sddz 130th SCSI disk whole disk + 32 = /dev/sdea 131th SCSI disk whole disk + ... + 240 = /dev/sden 144th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 129 block SCSI disk devices (144-159) + 0 = /dev/sdeo 145th SCSI disk whole disk + 16 = /dev/sdep 146th SCSI disk whole disk + 32 = /dev/sdeq 147th SCSI disk whole disk + ... + 240 = /dev/sdfd 160th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 130 char (Misc devices) + + 130 block SCSI disk devices (160-175) + 0 = /dev/sdfe 161st SCSI disk whole disk + 16 = /dev/sdff 162nd SCSI disk whole disk + 32 = /dev/sdfg 163rd SCSI disk whole disk + ... + 240 = /dev/sdft 176th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 131 block SCSI disk devices (176-191) + 0 = /dev/sdfu 177th SCSI disk whole disk + 16 = /dev/sdfv 178th SCSI disk whole disk + 32 = /dev/sdfw 179th SCSI disk whole disk + ... + 240 = /dev/sdgj 192nd SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 132 block SCSI disk devices (192-207) + 0 = /dev/sdgk 193rd SCSI disk whole disk + 16 = /dev/sdgl 194th SCSI disk whole disk + 32 = /dev/sdgm 195th SCSI disk whole disk + ... + 240 = /dev/sdgz 208th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 133 block SCSI disk devices (208-223) + 0 = /dev/sdha 209th SCSI disk whole disk + 16 = /dev/sdhb 210th SCSI disk whole disk + 32 = /dev/sdhc 211th SCSI disk whole disk + ... + 240 = /dev/sdhp 224th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 134 block SCSI disk devices (224-239) + 0 = /dev/sdhq 225th SCSI disk whole disk + 16 = /dev/sdhr 226th SCSI disk whole disk + 32 = /dev/sdhs 227th SCSI disk whole disk + ... + 240 = /dev/sdif 240th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 135 block SCSI disk devices (240-255) + 0 = /dev/sdig 241st SCSI disk whole disk + 16 = /dev/sdih 242nd SCSI disk whole disk + 32 = /dev/sdih 243rd SCSI disk whole disk + ... + 240 = /dev/sdiv 256th SCSI disk whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 136-143 char Unix98 PTY slaves + 0 = /dev/pts/0 First Unix98 pseudo-TTY + 1 = /dev/pts/1 Second Unix98 pseudo-TTY + ... + + These device nodes are automatically generated with + the proper permissions and modes by mounting the + devpts filesystem onto /dev/pts with the appropriate + mount options (distribution dependent, however, on + *most* distributions the appropriate options are + "mode=0620,gid=".) + + 136 block Mylex DAC960 PCI RAID controller; ninth controller + 0 = /dev/rd/c8d0 First disk, whole disk + 8 = /dev/rd/c8d1 Second disk, whole disk + ... + 248 = /dev/rd/c8d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 137 block Mylex DAC960 PCI RAID controller; tenth controller + 0 = /dev/rd/c9d0 First disk, whole disk + 8 = /dev/rd/c9d1 Second disk, whole disk + ... + 248 = /dev/rd/c9d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 138 block Mylex DAC960 PCI RAID controller; eleventh controller + 0 = /dev/rd/c10d0 First disk, whole disk + 8 = /dev/rd/c10d1 Second disk, whole disk + ... + 248 = /dev/rd/c10d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 139 block Mylex DAC960 PCI RAID controller; twelfth controller + 0 = /dev/rd/c11d0 First disk, whole disk + 8 = /dev/rd/c11d1 Second disk, whole disk + ... + 248 = /dev/rd/c11d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 140 block Mylex DAC960 PCI RAID controller; thirteenth controller + 0 = /dev/rd/c12d0 First disk, whole disk + 8 = /dev/rd/c12d1 Second disk, whole disk + ... + 248 = /dev/rd/c12d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 141 block Mylex DAC960 PCI RAID controller; fourteenth controller + 0 = /dev/rd/c13d0 First disk, whole disk + 8 = /dev/rd/c13d1 Second disk, whole disk + ... + 248 = /dev/rd/c13d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 142 block Mylex DAC960 PCI RAID controller; fifteenth controller + 0 = /dev/rd/c14d0 First disk, whole disk + 8 = /dev/rd/c14d1 Second disk, whole disk + ... + 248 = /dev/rd/c14d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 143 block Mylex DAC960 PCI RAID controller; sixteenth controller + 0 = /dev/rd/c15d0 First disk, whole disk + 8 = /dev/rd/c15d1 Second disk, whole disk + ... + 248 = /dev/rd/c15d31 32nd disk, whole disk + + Partitions are handled as for major 48. + + 144 char Encapsulated PPP + 0 = /dev/pppox0 First PPP over Ethernet + ... + 63 = /dev/pppox63 64th PPP over Ethernet + + This is primarily used for ADSL. + + The SST 5136-DN DeviceNet interface driver has been + relocated to major 183 due to an unfortunate conflict. + + 144 block Expansion Area #1 for more non-device (e.g. NFS) mounts + 0 = mounted device 256 + 255 = mounted device 511 + + 145 char SAM9407-based soundcard + 0 = /dev/sam0_mixer + 1 = /dev/sam0_sequencer + 2 = /dev/sam0_midi00 + 3 = /dev/sam0_dsp + 4 = /dev/sam0_audio + 6 = /dev/sam0_sndstat + 18 = /dev/sam0_midi01 + 34 = /dev/sam0_midi02 + 50 = /dev/sam0_midi03 + 64 = /dev/sam1_mixer + ... + 128 = /dev/sam2_mixer + ... + 192 = /dev/sam3_mixer + ... + + Device functions match OSS, but offer a number of + addons, which are sam9407 specific. OSS can be + operated simultaneously, taking care of the codec. + + 145 block Expansion Area #2 for more non-device (e.g. NFS) mounts + 0 = mounted device 512 + 255 = mounted device 767 + + 146 char SYSTRAM SCRAMNet mirrored-memory network + 0 = /dev/scramnet0 First SCRAMNet device + 1 = /dev/scramnet1 Second SCRAMNet device + ... + + 146 block Expansion Area #3 for more non-device (e.g. NFS) mounts + 0 = mounted device 768 + 255 = mounted device 1023 + + 147 char Aureal Semiconductor Vortex Audio device + 0 = /dev/aureal0 First Aureal Vortex + 1 = /dev/aureal1 Second Aureal Vortex + ... + + 147 block Distributed Replicated Block Device (DRBD) + 0 = /dev/drbd0 First DRBD device + 1 = /dev/drbd1 Second DRBD device + ... + + 148 char Technology Concepts serial card + 0 = /dev/ttyT0 First TCL port + 1 = /dev/ttyT1 Second TCL port + ... + + 149 char Technology Concepts serial card - alternate devices + 0 = /dev/cut0 Callout device for ttyT0 + 1 = /dev/cut0 Callout device for ttyT1 + ... + + 150 char Real-Time Linux FIFOs + 0 = /dev/rtf0 First RTLinux FIFO + 1 = /dev/rtf1 Second RTLinux FIFO + ... + + 151 char DPT I2O SmartRaid V controller + 0 = /dev/dpti0 First DPT I2O adapter + 1 = /dev/dpti1 Second DPT I2O adapter + ... + + 152 char EtherDrive Control Device + 0 = /dev/etherd/ctl Connect/Disconnect an EtherDrive + 1 = /dev/etherd/err Monitor errors + 2 = /dev/etherd/raw Raw AoE packet monitor + + 152 block EtherDrive Block Devices + 0 = /dev/etherd/0 EtherDrive 0 + ... + 255 = /dev/etherd/255 EtherDrive 255 + + 153 char SPI Bus Interface (sometimes referred to as MicroWire) + 0 = /dev/spi0 First SPI device on the bus + 1 = /dev/spi1 Second SPI device on the bus + ... + 15 = /dev/spi15 Sixteenth SPI device on the bus + + 153 block Enhanced Metadisk RAID (EMD) storage units + 0 = /dev/emd/0 First unit + 1 = /dev/emd/0p1 Partition 1 on First unit + 2 = /dev/emd/0p2 Partition 2 on First unit + ... + 15 = /dev/emd/0p15 Partition 15 on First unit + + 16 = /dev/emd/1 Second unit + 32 = /dev/emd/2 Third unit + ... + 240 = /dev/emd/15 Sixteenth unit + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 154 char Specialix RIO serial card + 0 = /dev/ttySR0 First RIO port + ... + 255 = /dev/ttySR255 256th RIO port + + 155 char Specialix RIO serial card - alternate devices + 0 = /dev/cusr0 Callout device for ttySR0 + ... + 255 = /dev/cusr255 Callout device for ttySR255 + + 156 char Specialix RIO serial card + 0 = /dev/ttySR256 257th RIO port + ... + 255 = /dev/ttySR511 512th RIO port + + 157 char Specialix RIO serial card - alternate devices + 0 = /dev/cusr256 Callout device for ttySR256 + ... + 255 = /dev/cusr511 Callout device for ttySR511 + + 158 char Dialogic GammaLink fax driver + 0 = /dev/gfax0 GammaLink channel 0 + 1 = /dev/gfax1 GammaLink channel 1 + ... + + 159 char RESERVED + + 159 block RESERVED + + 160 char General Purpose Instrument Bus (GPIB) + 0 = /dev/gpib0 First GPIB bus + 1 = /dev/gpib1 Second GPIB bus + ... + + 160 block Carmel 8-port SATA Disks on First Controller + 0 = /dev/carmel/0 SATA disk 0 whole disk + 1 = /dev/carmel/0p1 SATA disk 0 partition 1 + ... + 31 = /dev/carmel/0p31 SATA disk 0 partition 31 + + 32 = /dev/carmel/1 SATA disk 1 whole disk + 64 = /dev/carmel/2 SATA disk 2 whole disk + ... + 224 = /dev/carmel/7 SATA disk 7 whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 31. + + 161 char IrCOMM devices (IrDA serial/parallel emulation) + 0 = /dev/ircomm0 First IrCOMM device + 1 = /dev/ircomm1 Second IrCOMM device + ... + 16 = /dev/irlpt0 First IrLPT device + 17 = /dev/irlpt1 Second IrLPT device + ... + + 161 block Carmel 8-port SATA Disks on Second Controller + 0 = /dev/carmel/8 SATA disk 8 whole disk + 1 = /dev/carmel/8p1 SATA disk 8 partition 1 + ... + 31 = /dev/carmel/8p31 SATA disk 8 partition 31 + + 32 = /dev/carmel/9 SATA disk 9 whole disk + 64 = /dev/carmel/10 SATA disk 10 whole disk + ... + 224 = /dev/carmel/15 SATA disk 15 whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 31. + + 162 char Raw block device interface + 0 = /dev/rawctl Raw I/O control device + 1 = /dev/raw/raw1 First raw I/O device + 2 = /dev/raw/raw2 Second raw I/O device + ... + max minor number of raw device is set by kernel config + MAX_RAW_DEVS or raw module parameter 'max_raw_devs' + + 163 char + + 164 char Chase Research AT/PCI-Fast serial card + 0 = /dev/ttyCH0 AT/PCI-Fast board 0, port 0 + ... + 15 = /dev/ttyCH15 AT/PCI-Fast board 0, port 15 + 16 = /dev/ttyCH16 AT/PCI-Fast board 1, port 0 + ... + 31 = /dev/ttyCH31 AT/PCI-Fast board 1, port 15 + 32 = /dev/ttyCH32 AT/PCI-Fast board 2, port 0 + ... + 47 = /dev/ttyCH47 AT/PCI-Fast board 2, port 15 + 48 = /dev/ttyCH48 AT/PCI-Fast board 3, port 0 + ... + 63 = /dev/ttyCH63 AT/PCI-Fast board 3, port 15 + + 165 char Chase Research AT/PCI-Fast serial card - alternate devices + 0 = /dev/cuch0 Callout device for ttyCH0 + ... + 63 = /dev/cuch63 Callout device for ttyCH63 + + 166 char ACM USB modems + 0 = /dev/ttyACM0 First ACM modem + 1 = /dev/ttyACM1 Second ACM modem + ... + + 167 char ACM USB modems - alternate devices + 0 = /dev/cuacm0 Callout device for ttyACM0 + 1 = /dev/cuacm1 Callout device for ttyACM1 + ... + + 168 char Eracom CSA7000 PCI encryption adaptor + 0 = /dev/ecsa0 First CSA7000 + 1 = /dev/ecsa1 Second CSA7000 + ... + + 169 char Eracom CSA8000 PCI encryption adaptor + 0 = /dev/ecsa8-0 First CSA8000 + 1 = /dev/ecsa8-1 Second CSA8000 + ... + + 170 char AMI MegaRAC remote access controller + 0 = /dev/megarac0 First MegaRAC card + 1 = /dev/megarac1 Second MegaRAC card + ... + + 171 char Reserved for IEEE 1394 (Firewire) + + 172 char Moxa Intellio serial card + 0 = /dev/ttyMX0 First Moxa port + 1 = /dev/ttyMX1 Second Moxa port + ... + 127 = /dev/ttyMX127 128th Moxa port + 128 = /dev/moxactl Moxa control port + + 173 char Moxa Intellio serial card - alternate devices + 0 = /dev/cumx0 Callout device for ttyMX0 + 1 = /dev/cumx1 Callout device for ttyMX1 + ... + 127 = /dev/cumx127 Callout device for ttyMX127 + + 174 char SmartIO serial card + 0 = /dev/ttySI0 First SmartIO port + 1 = /dev/ttySI1 Second SmartIO port + ... + + 175 char SmartIO serial card - alternate devices + 0 = /dev/cusi0 Callout device for ttySI0 + 1 = /dev/cusi1 Callout device for ttySI1 + ... + + 176 char nCipher nFast PCI crypto accelerator + 0 = /dev/nfastpci0 First nFast PCI device + 1 = /dev/nfastpci1 First nFast PCI device + ... + + 177 char TI PCILynx memory spaces + 0 = /dev/pcilynx/aux0 AUX space of first PCILynx card + ... + 15 = /dev/pcilynx/aux15 AUX space of 16th PCILynx card + 16 = /dev/pcilynx/rom0 ROM space of first PCILynx card + ... + 31 = /dev/pcilynx/rom15 ROM space of 16th PCILynx card + 32 = /dev/pcilynx/ram0 RAM space of first PCILynx card + ... + 47 = /dev/pcilynx/ram15 RAM space of 16th PCILynx card + + 178 char Giganet cLAN1xxx virtual interface adapter + 0 = /dev/clanvi0 First cLAN adapter + 1 = /dev/clanvi1 Second cLAN adapter + ... + + 179 block MMC block devices + 0 = /dev/mmcblk0 First SD/MMC card + 1 = /dev/mmcblk0p1 First partition on first MMC card + 8 = /dev/mmcblk1 Second SD/MMC card + ... + + The start of next SD/MMC card can be configured with + CONFIG_MMC_BLOCK_MINORS, or overridden at boot/modprobe + time using the mmcblk.perdev_minors option. That would + bump the offset between each card to be the configured + value instead of the default 8. + + 179 char CCube DVXChip-based PCI products + 0 = /dev/dvxirq0 First DVX device + 1 = /dev/dvxirq1 Second DVX device + ... + + 180 char USB devices + 0 = /dev/usb/lp0 First USB printer + ... + 15 = /dev/usb/lp15 16th USB printer + 48 = /dev/usb/scanner0 First USB scanner + ... + 63 = /dev/usb/scanner15 16th USB scanner + 64 = /dev/usb/rio500 Diamond Rio 500 + 65 = /dev/usb/usblcd USBLCD Interface (info@usblcd.de) + 66 = /dev/usb/cpad0 Synaptics cPad (mouse/LCD) + 96 = /dev/usb/hiddev0 1st USB HID device + ... + 111 = /dev/usb/hiddev15 16th USB HID device + 112 = /dev/usb/auer0 1st auerswald ISDN device + ... + 127 = /dev/usb/auer15 16th auerswald ISDN device + 128 = /dev/usb/brlvgr0 First Braille Voyager device + ... + 131 = /dev/usb/brlvgr3 Fourth Braille Voyager device + 132 = /dev/usb/idmouse ID Mouse (fingerprint scanner) device + 133 = /dev/usb/sisusbvga1 First SiSUSB VGA device + ... + 140 = /dev/usb/sisusbvga8 Eighth SISUSB VGA device + 144 = /dev/usb/lcd USB LCD device + 160 = /dev/usb/legousbtower0 1st USB Legotower device + ... + 175 = /dev/usb/legousbtower15 16th USB Legotower device + 176 = /dev/usb/usbtmc1 First USB TMC device + ... + 191 = /dev/usb/usbtmc16 16th USB TMC device + 192 = /dev/usb/yurex1 First USB Yurex device + ... + 209 = /dev/usb/yurex16 16th USB Yurex device + + 180 block USB block devices + 0 = /dev/uba First USB block device + 8 = /dev/ubb Second USB block device + 16 = /dev/ubc Third USB block device + ... + + 181 char Conrad Electronic parallel port radio clocks + 0 = /dev/pcfclock0 First Conrad radio clock + 1 = /dev/pcfclock1 Second Conrad radio clock + ... + + 182 char Picture Elements THR2 binarizer + 0 = /dev/pethr0 First THR2 board + 1 = /dev/pethr1 Second THR2 board + ... + + 183 char SST 5136-DN DeviceNet interface + 0 = /dev/ss5136dn0 First DeviceNet interface + 1 = /dev/ss5136dn1 Second DeviceNet interface + ... + + This device used to be assigned to major number 144. + It had to be moved due to an unfortunate conflict. + + 184 char Picture Elements' video simulator/sender + 0 = /dev/pevss0 First sender board + 1 = /dev/pevss1 Second sender board + ... + + 185 char InterMezzo high availability file system + 0 = /dev/intermezzo0 First cache manager + 1 = /dev/intermezzo1 Second cache manager + ... + + See http://web.archive.org/web/20080115195241/ + http://inter-mezzo.org/index.html + + 186 char Object-based storage control device + 0 = /dev/obd0 First obd control device + 1 = /dev/obd1 Second obd control device + ... + + See ftp://ftp.lustre.org/pub/obd for code and information. + + 187 char DESkey hardware encryption device + 0 = /dev/deskey0 First DES key + 1 = /dev/deskey1 Second DES key + ... + + 188 char USB serial converters + 0 = /dev/ttyUSB0 First USB serial converter + 1 = /dev/ttyUSB1 Second USB serial converter + ... + + 189 char USB serial converters - alternate devices + 0 = /dev/cuusb0 Callout device for ttyUSB0 + 1 = /dev/cuusb1 Callout device for ttyUSB1 + ... + + 190 char Kansas City tracker/tuner card + 0 = /dev/kctt0 First KCT/T card + 1 = /dev/kctt1 Second KCT/T card + ... + + 191 char Reserved for PCMCIA + + 192 char Kernel profiling interface + 0 = /dev/profile Profiling control device + 1 = /dev/profile0 Profiling device for CPU 0 + 2 = /dev/profile1 Profiling device for CPU 1 + ... + + 193 char Kernel event-tracing interface + 0 = /dev/trace Tracing control device + 1 = /dev/trace0 Tracing device for CPU 0 + 2 = /dev/trace1 Tracing device for CPU 1 + ... + + 194 char linVideoStreams (LINVS) + 0 = /dev/mvideo/status0 Video compression status + 1 = /dev/mvideo/stream0 Video stream + 2 = /dev/mvideo/frame0 Single compressed frame + 3 = /dev/mvideo/rawframe0 Raw uncompressed frame + 4 = /dev/mvideo/codec0 Direct codec access + 5 = /dev/mvideo/video4linux0 Video4Linux compatibility + + 16 = /dev/mvideo/status1 Second device + ... + 32 = /dev/mvideo/status2 Third device + ... + ... + 240 = /dev/mvideo/status15 16th device + ... + + 195 char Nvidia graphics devices + 0 = /dev/nvidia0 First Nvidia card + 1 = /dev/nvidia1 Second Nvidia card + ... + 255 = /dev/nvidiactl Nvidia card control device + + 196 char Tormenta T1 card + 0 = /dev/tor/0 Master control channel for all cards + 1 = /dev/tor/1 First DS0 + 2 = /dev/tor/2 Second DS0 + ... + 48 = /dev/tor/48 48th DS0 + 49 = /dev/tor/49 First pseudo-channel + 50 = /dev/tor/50 Second pseudo-channel + ... + + 197 char OpenTNF tracing facility + 0 = /dev/tnf/t0 Trace 0 data extraction + 1 = /dev/tnf/t1 Trace 1 data extraction + ... + 128 = /dev/tnf/status Tracing facility status + 130 = /dev/tnf/trace Tracing device + + 198 char Total Impact TPMP2 quad coprocessor PCI card + 0 = /dev/tpmp2/0 First card + 1 = /dev/tpmp2/1 Second card + ... + + 199 char Veritas volume manager (VxVM) volumes + 0 = /dev/vx/rdsk/*/* First volume + 1 = /dev/vx/rdsk/*/* Second volume + ... + + 199 block Veritas volume manager (VxVM) volumes + 0 = /dev/vx/dsk/*/* First volume + 1 = /dev/vx/dsk/*/* Second volume + ... + + The namespace in these directories is maintained by + the user space VxVM software. + + 200 char Veritas VxVM configuration interface + 0 = /dev/vx/config Configuration access node + 1 = /dev/vx/trace Volume i/o trace access node + 2 = /dev/vx/iod Volume i/o daemon access node + 3 = /dev/vx/info Volume information access node + 4 = /dev/vx/task Volume tasks access node + 5 = /dev/vx/taskmon Volume tasks monitor daemon + + 201 char Veritas VxVM dynamic multipathing driver + 0 = /dev/vx/rdmp/* First multipath device + 1 = /dev/vx/rdmp/* Second multipath device + ... + 201 block Veritas VxVM dynamic multipathing driver + 0 = /dev/vx/dmp/* First multipath device + 1 = /dev/vx/dmp/* Second multipath device + ... + + The namespace in these directories is maintained by + the user space VxVM software. + + 202 char CPU model-specific registers + 0 = /dev/cpu/0/msr MSRs on CPU 0 + 1 = /dev/cpu/1/msr MSRs on CPU 1 + ... + + 202 block Xen Virtual Block Device + 0 = /dev/xvda First Xen VBD whole disk + 16 = /dev/xvdb Second Xen VBD whole disk + 32 = /dev/xvdc Third Xen VBD whole disk + ... + 240 = /dev/xvdp Sixteenth Xen VBD whole disk + + Partitions are handled in the same way as for IDE + disks (see major number 3) except that the limit on + partitions is 15. + + 203 char CPU CPUID information + 0 = /dev/cpu/0/cpuid CPUID on CPU 0 + 1 = /dev/cpu/1/cpuid CPUID on CPU 1 + ... + + 204 char Low-density serial ports + 0 = /dev/ttyLU0 LinkUp Systems L72xx UART - port 0 + 1 = /dev/ttyLU1 LinkUp Systems L72xx UART - port 1 + 2 = /dev/ttyLU2 LinkUp Systems L72xx UART - port 2 + 3 = /dev/ttyLU3 LinkUp Systems L72xx UART - port 3 + 4 = /dev/ttyFB0 Intel Footbridge (ARM) + 5 = /dev/ttySA0 StrongARM builtin serial port 0 + 6 = /dev/ttySA1 StrongARM builtin serial port 1 + 7 = /dev/ttySA2 StrongARM builtin serial port 2 + 8 = /dev/ttySC0 SCI serial port (SuperH) - port 0 + 9 = /dev/ttySC1 SCI serial port (SuperH) - port 1 + 10 = /dev/ttySC2 SCI serial port (SuperH) - port 2 + 11 = /dev/ttySC3 SCI serial port (SuperH) - port 3 + 12 = /dev/ttyFW0 Firmware console - port 0 + 13 = /dev/ttyFW1 Firmware console - port 1 + 14 = /dev/ttyFW2 Firmware console - port 2 + 15 = /dev/ttyFW3 Firmware console - port 3 + 16 = /dev/ttyAM0 ARM "AMBA" serial port 0 + ... + 31 = /dev/ttyAM15 ARM "AMBA" serial port 15 + 32 = /dev/ttyDB0 DataBooster serial port 0 + ... + 39 = /dev/ttyDB7 DataBooster serial port 7 + 40 = /dev/ttySG0 SGI Altix console port + 41 = /dev/ttySMX0 Motorola i.MX - port 0 + 42 = /dev/ttySMX1 Motorola i.MX - port 1 + 43 = /dev/ttySMX2 Motorola i.MX - port 2 + 44 = /dev/ttyMM0 Marvell MPSC - port 0 + 45 = /dev/ttyMM1 Marvell MPSC - port 1 + 46 = /dev/ttyCPM0 PPC CPM (SCC or SMC) - port 0 + ... + 47 = /dev/ttyCPM5 PPC CPM (SCC or SMC) - port 5 + 50 = /dev/ttyIOC0 Altix serial card + ... + 81 = /dev/ttyIOC31 Altix serial card + 82 = /dev/ttyVR0 NEC VR4100 series SIU + 83 = /dev/ttyVR1 NEC VR4100 series DSIU + 84 = /dev/ttyIOC84 Altix ioc4 serial card + ... + 115 = /dev/ttyIOC115 Altix ioc4 serial card + 116 = /dev/ttySIOC0 Altix ioc3 serial card + ... + 147 = /dev/ttySIOC31 Altix ioc3 serial card + 148 = /dev/ttyPSC0 PPC PSC - port 0 + ... + 153 = /dev/ttyPSC5 PPC PSC - port 5 + 154 = /dev/ttyAT0 ATMEL serial port 0 + ... + 169 = /dev/ttyAT15 ATMEL serial port 15 + 170 = /dev/ttyNX0 Hilscher netX serial port 0 + ... + 185 = /dev/ttyNX15 Hilscher netX serial port 15 + 186 = /dev/ttyJ0 JTAG1 DCC protocol based serial port emulation + 187 = /dev/ttyUL0 Xilinx uartlite - port 0 + ... + 190 = /dev/ttyUL3 Xilinx uartlite - port 3 + 191 = /dev/xvc0 Xen virtual console - port 0 + 192 = /dev/ttyPZ0 pmac_zilog - port 0 + ... + 195 = /dev/ttyPZ3 pmac_zilog - port 3 + 196 = /dev/ttyTX0 TX39/49 serial port 0 + ... + 204 = /dev/ttyTX7 TX39/49 serial port 7 + 205 = /dev/ttySC0 SC26xx serial port 0 + 206 = /dev/ttySC1 SC26xx serial port 1 + 207 = /dev/ttySC2 SC26xx serial port 2 + 208 = /dev/ttySC3 SC26xx serial port 3 + 209 = /dev/ttyMAX0 MAX3100 serial port 0 + 210 = /dev/ttyMAX1 MAX3100 serial port 1 + 211 = /dev/ttyMAX2 MAX3100 serial port 2 + 212 = /dev/ttyMAX3 MAX3100 serial port 3 + + 205 char Low-density serial ports (alternate device) + 0 = /dev/culu0 Callout device for ttyLU0 + 1 = /dev/culu1 Callout device for ttyLU1 + 2 = /dev/culu2 Callout device for ttyLU2 + 3 = /dev/culu3 Callout device for ttyLU3 + 4 = /dev/cufb0 Callout device for ttyFB0 + 5 = /dev/cusa0 Callout device for ttySA0 + 6 = /dev/cusa1 Callout device for ttySA1 + 7 = /dev/cusa2 Callout device for ttySA2 + 8 = /dev/cusc0 Callout device for ttySC0 + 9 = /dev/cusc1 Callout device for ttySC1 + 10 = /dev/cusc2 Callout device for ttySC2 + 11 = /dev/cusc3 Callout device for ttySC3 + 12 = /dev/cufw0 Callout device for ttyFW0 + 13 = /dev/cufw1 Callout device for ttyFW1 + 14 = /dev/cufw2 Callout device for ttyFW2 + 15 = /dev/cufw3 Callout device for ttyFW3 + 16 = /dev/cuam0 Callout device for ttyAM0 + ... + 31 = /dev/cuam15 Callout device for ttyAM15 + 32 = /dev/cudb0 Callout device for ttyDB0 + ... + 39 = /dev/cudb7 Callout device for ttyDB7 + 40 = /dev/cusg0 Callout device for ttySG0 + 41 = /dev/ttycusmx0 Callout device for ttySMX0 + 42 = /dev/ttycusmx1 Callout device for ttySMX1 + 43 = /dev/ttycusmx2 Callout device for ttySMX2 + 46 = /dev/cucpm0 Callout device for ttyCPM0 + ... + 49 = /dev/cucpm5 Callout device for ttyCPM5 + 50 = /dev/cuioc40 Callout device for ttyIOC40 + ... + 81 = /dev/cuioc431 Callout device for ttyIOC431 + 82 = /dev/cuvr0 Callout device for ttyVR0 + 83 = /dev/cuvr1 Callout device for ttyVR1 + + 206 char OnStream SC-x0 tape devices + 0 = /dev/osst0 First OnStream SCSI tape, mode 0 + 1 = /dev/osst1 Second OnStream SCSI tape, mode 0 + ... + 32 = /dev/osst0l First OnStream SCSI tape, mode 1 + 33 = /dev/osst1l Second OnStream SCSI tape, mode 1 + ... + 64 = /dev/osst0m First OnStream SCSI tape, mode 2 + 65 = /dev/osst1m Second OnStream SCSI tape, mode 2 + ... + 96 = /dev/osst0a First OnStream SCSI tape, mode 3 + 97 = /dev/osst1a Second OnStream SCSI tape, mode 3 + ... + 128 = /dev/nosst0 No rewind version of /dev/osst0 + 129 = /dev/nosst1 No rewind version of /dev/osst1 + ... + 160 = /dev/nosst0l No rewind version of /dev/osst0l + 161 = /dev/nosst1l No rewind version of /dev/osst1l + ... + 192 = /dev/nosst0m No rewind version of /dev/osst0m + 193 = /dev/nosst1m No rewind version of /dev/osst1m + ... + 224 = /dev/nosst0a No rewind version of /dev/osst0a + 225 = /dev/nosst1a No rewind version of /dev/osst1a + ... + + The OnStream SC-x0 SCSI tapes do not support the + standard SCSI SASD command set and therefore need + their own driver "osst". Note that the IDE, USB (and + maybe ParPort) versions may be driven via ide-scsi or + usb-storage SCSI emulation and this osst device and + driver as well. The ADR-x0 drives are QIC-157 + compliant and don't need osst. + + 207 char Compaq ProLiant health feature indicate + 0 = /dev/cpqhealth/cpqw Redirector interface + 1 = /dev/cpqhealth/crom EISA CROM + 2 = /dev/cpqhealth/cdt Data Table + 3 = /dev/cpqhealth/cevt Event Log + 4 = /dev/cpqhealth/casr Automatic Server Recovery + 5 = /dev/cpqhealth/cecc ECC Memory + 6 = /dev/cpqhealth/cmca Machine Check Architecture + 7 = /dev/cpqhealth/ccsm Deprecated CDT + 8 = /dev/cpqhealth/cnmi NMI Handling + 9 = /dev/cpqhealth/css Sideshow Management + 10 = /dev/cpqhealth/cram CMOS interface + 11 = /dev/cpqhealth/cpci PCI IRQ interface + + 208 char User space serial ports + 0 = /dev/ttyU0 First user space serial port + 1 = /dev/ttyU1 Second user space serial port + ... + + 209 char User space serial ports (alternate devices) + 0 = /dev/cuu0 Callout device for ttyU0 + 1 = /dev/cuu1 Callout device for ttyU1 + ... + + 210 char SBE, Inc. sync/async serial card + 0 = /dev/sbei/wxcfg0 Configuration device for board 0 + 1 = /dev/sbei/dld0 Download device for board 0 + 2 = /dev/sbei/wan00 WAN device, port 0, board 0 + 3 = /dev/sbei/wan01 WAN device, port 1, board 0 + 4 = /dev/sbei/wan02 WAN device, port 2, board 0 + 5 = /dev/sbei/wan03 WAN device, port 3, board 0 + 6 = /dev/sbei/wanc00 WAN clone device, port 0, board 0 + 7 = /dev/sbei/wanc01 WAN clone device, port 1, board 0 + 8 = /dev/sbei/wanc02 WAN clone device, port 2, board 0 + 9 = /dev/sbei/wanc03 WAN clone device, port 3, board 0 + 10 = /dev/sbei/wxcfg1 Configuration device for board 1 + 11 = /dev/sbei/dld1 Download device for board 1 + 12 = /dev/sbei/wan10 WAN device, port 0, board 1 + 13 = /dev/sbei/wan11 WAN device, port 1, board 1 + 14 = /dev/sbei/wan12 WAN device, port 2, board 1 + 15 = /dev/sbei/wan13 WAN device, port 3, board 1 + 16 = /dev/sbei/wanc10 WAN clone device, port 0, board 1 + 17 = /dev/sbei/wanc11 WAN clone device, port 1, board 1 + 18 = /dev/sbei/wanc12 WAN clone device, port 2, board 1 + 19 = /dev/sbei/wanc13 WAN clone device, port 3, board 1 + ... + + Yes, each board is really spaced 10 (decimal) apart. + + 211 char Addinum CPCI1500 digital I/O card + 0 = /dev/addinum/cpci1500/0 First CPCI1500 card + 1 = /dev/addinum/cpci1500/1 Second CPCI1500 card + ... + + 212 char LinuxTV.org DVB driver subsystem + 0 = /dev/dvb/adapter0/video0 first video decoder of first card + 1 = /dev/dvb/adapter0/audio0 first audio decoder of first card + 2 = /dev/dvb/adapter0/sec0 (obsolete/unused) + 3 = /dev/dvb/adapter0/frontend0 first frontend device of first card + 4 = /dev/dvb/adapter0/demux0 first demux device of first card + 5 = /dev/dvb/adapter0/dvr0 first digital video recoder device of first card + 6 = /dev/dvb/adapter0/ca0 first common access port of first card + 7 = /dev/dvb/adapter0/net0 first network device of first card + 8 = /dev/dvb/adapter0/osd0 first on-screen-display device of first card + 9 = /dev/dvb/adapter0/video1 second video decoder of first card + ... + 64 = /dev/dvb/adapter1/video0 first video decoder of second card + ... + 128 = /dev/dvb/adapter2/video0 first video decoder of third card + ... + 196 = /dev/dvb/adapter3/video0 first video decoder of fourth card + + 216 char Bluetooth RFCOMM TTY devices + 0 = /dev/rfcomm0 First Bluetooth RFCOMM TTY device + 1 = /dev/rfcomm1 Second Bluetooth RFCOMM TTY device + ... + + 217 char Bluetooth RFCOMM TTY devices (alternate devices) + 0 = /dev/curf0 Callout device for rfcomm0 + 1 = /dev/curf1 Callout device for rfcomm1 + ... + + 218 char The Logical Company bus Unibus/Qbus adapters + 0 = /dev/logicalco/bci/0 First bus adapter + 1 = /dev/logicalco/bci/1 First bus adapter + ... + + 219 char The Logical Company DCI-1300 digital I/O card + 0 = /dev/logicalco/dci1300/0 First DCI-1300 card + 1 = /dev/logicalco/dci1300/1 Second DCI-1300 card + ... + + 220 char Myricom Myrinet "GM" board + 0 = /dev/myricom/gm0 First Myrinet GM board + 1 = /dev/myricom/gmp0 First board "root access" + 2 = /dev/myricom/gm1 Second Myrinet GM board + 3 = /dev/myricom/gmp1 Second board "root access" + ... + + 221 char VME bus + 0 = /dev/bus/vme/m0 First master image + 1 = /dev/bus/vme/m1 Second master image + 2 = /dev/bus/vme/m2 Third master image + 3 = /dev/bus/vme/m3 Fourth master image + 4 = /dev/bus/vme/s0 First slave image + 5 = /dev/bus/vme/s1 Second slave image + 6 = /dev/bus/vme/s2 Third slave image + 7 = /dev/bus/vme/s3 Fourth slave image + 8 = /dev/bus/vme/ctl Control + + It is expected that all VME bus drivers will use the + same interface. For interface documentation see + http://www.vmelinux.org/. + + 224 char A2232 serial card + 0 = /dev/ttyY0 First A2232 port + 1 = /dev/ttyY1 Second A2232 port + ... + + 225 char A2232 serial card (alternate devices) + 0 = /dev/cuy0 Callout device for ttyY0 + 1 = /dev/cuy1 Callout device for ttyY1 + ... + + 226 char Direct Rendering Infrastructure (DRI) + 0 = /dev/dri/card0 First graphics card + 1 = /dev/dri/card1 Second graphics card + ... + + 227 char IBM 3270 terminal Unix tty access + 1 = /dev/3270/tty1 First 3270 terminal + 2 = /dev/3270/tty2 Seconds 3270 terminal + ... + + 228 char IBM 3270 terminal block-mode access + 0 = /dev/3270/tub Controlling interface + 1 = /dev/3270/tub1 First 3270 terminal + 2 = /dev/3270/tub2 Second 3270 terminal + ... + + 229 char IBM iSeries/pSeries virtual console + 0 = /dev/hvc0 First console port + 1 = /dev/hvc1 Second console port + ... + + 230 char IBM iSeries virtual tape + 0 = /dev/iseries/vt0 First virtual tape, mode 0 + 1 = /dev/iseries/vt1 Second virtual tape, mode 0 + ... + 32 = /dev/iseries/vt0l First virtual tape, mode 1 + 33 = /dev/iseries/vt1l Second virtual tape, mode 1 + ... + 64 = /dev/iseries/vt0m First virtual tape, mode 2 + 65 = /dev/iseries/vt1m Second virtual tape, mode 2 + ... + 96 = /dev/iseries/vt0a First virtual tape, mode 3 + 97 = /dev/iseries/vt1a Second virtual tape, mode 3 + ... + 128 = /dev/iseries/nvt0 First virtual tape, mode 0, no rewind + 129 = /dev/iseries/nvt1 Second virtual tape, mode 0, no rewind + ... + 160 = /dev/iseries/nvt0l First virtual tape, mode 1, no rewind + 161 = /dev/iseries/nvt1l Second virtual tape, mode 1, no rewind + ... + 192 = /dev/iseries/nvt0m First virtual tape, mode 2, no rewind + 193 = /dev/iseries/nvt1m Second virtual tape, mode 2, no rewind + ... + 224 = /dev/iseries/nvt0a First virtual tape, mode 3, no rewind + 225 = /dev/iseries/nvt1a Second virtual tape, mode 3, no rewind + ... + + "No rewind" refers to the omission of the default + automatic rewind on device close. The MTREW or MTOFFL + ioctl()'s can be used to rewind the tape regardless of + the device used to access it. + + 231 char InfiniBand + 0 = /dev/infiniband/umad0 + 1 = /dev/infiniband/umad1 + ... + 63 = /dev/infiniband/umad63 63rd InfiniBandMad device + 64 = /dev/infiniband/issm0 First InfiniBand IsSM device + 65 = /dev/infiniband/issm1 Second InfiniBand IsSM device + ... + 127 = /dev/infiniband/issm63 63rd InfiniBand IsSM device + 128 = /dev/infiniband/uverbs0 First InfiniBand verbs device + 129 = /dev/infiniband/uverbs1 Second InfiniBand verbs device + ... + 159 = /dev/infiniband/uverbs31 31st InfiniBand verbs device + + 232 char Biometric Devices + 0 = /dev/biometric/sensor0/fingerprint first fingerprint sensor on first device + 1 = /dev/biometric/sensor0/iris first iris sensor on first device + 2 = /dev/biometric/sensor0/retina first retina sensor on first device + 3 = /dev/biometric/sensor0/voiceprint first voiceprint sensor on first device + 4 = /dev/biometric/sensor0/facial first facial sensor on first device + 5 = /dev/biometric/sensor0/hand first hand sensor on first device + ... + 10 = /dev/biometric/sensor1/fingerprint first fingerprint sensor on second device + ... + 20 = /dev/biometric/sensor2/fingerprint first fingerprint sensor on third device + ... + + 233 char PathScale InfiniPath interconnect + 0 = /dev/ipath Primary device for programs (any unit) + 1 = /dev/ipath0 Access specifically to unit 0 + 2 = /dev/ipath1 Access specifically to unit 1 + ... + 4 = /dev/ipath3 Access specifically to unit 3 + 129 = /dev/ipath_sma Device used by Subnet Management Agent + 130 = /dev/ipath_diag Device used by diagnostics programs + + 234-254 char RESERVED FOR DYNAMIC ASSIGNMENT + Character devices that request a dynamic allocation of major number will + take numbers starting from 254 and downward. + + 240-254 block LOCAL/EXPERIMENTAL USE + Allocated for local/experimental use. For devices not + assigned official numbers, these ranges should be + used in order to avoid conflicting with future assignments. + + 255 char RESERVED + + 255 block RESERVED + + This major is reserved to assist the expansion to a + larger number space. No device nodes with this major + should ever be created on the filesystem. + (This is probably not true anymore, but I'll leave it + for now /Torben) + + ---LARGE MAJORS!!!!!--- + + 256 char Equinox SST multi-port serial boards + 0 = /dev/ttyEQ0 First serial port on first Equinox SST board + 127 = /dev/ttyEQ127 Last serial port on first Equinox SST board + 128 = /dev/ttyEQ128 First serial port on second Equinox SST board + ... + 1027 = /dev/ttyEQ1027 Last serial port on eighth Equinox SST board + + 256 block Resident Flash Disk Flash Translation Layer + 0 = /dev/rfda First RFD FTL layer + 16 = /dev/rfdb Second RFD FTL layer + ... + 240 = /dev/rfdp 16th RFD FTL layer + + 257 char Phoenix Technologies Cryptographic Services Driver + 0 = /dev/ptlsec Crypto Services Driver + + 257 block SSFDC Flash Translation Layer filesystem + 0 = /dev/ssfdca First SSFDC layer + 8 = /dev/ssfdcb Second SSFDC layer + 16 = /dev/ssfdcc Third SSFDC layer + 24 = /dev/ssfdcd 4th SSFDC layer + 32 = /dev/ssfdce 5th SSFDC layer + 40 = /dev/ssfdcf 6th SSFDC layer + 48 = /dev/ssfdcg 7th SSFDC layer + 56 = /dev/ssfdch 8th SSFDC layer + + 258 block ROM/Flash read-only translation layer + 0 = /dev/blockrom0 First ROM card's translation layer interface + 1 = /dev/blockrom1 Second ROM card's translation layer interface + ... + + 259 block Block Extended Major + Used dynamically to hold additional partition minor + numbers and allow large numbers of partitions per device + + 259 char FPGA configuration interfaces + 0 = /dev/icap0 First Xilinx internal configuration + 1 = /dev/icap1 Second Xilinx internal configuration + + 260 char OSD (Object-based-device) SCSI Device + 0 = /dev/osd0 First OSD Device + 1 = /dev/osd1 Second OSD Device + ... + 255 = /dev/osd255 256th OSD Device -- cgit v1.2.3 From ab0e44c155519d9b16f9eca1644d520788dd4545 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 7 Nov 2016 17:03:16 -0200 Subject: bug-hunting.rst: update info about bug hunting The document shows a really old procedure for bug hunting that nobody uses anymore. Remove such section, and update the remaining documentation to reflect the procedures used currently. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/bug-hunting.rst | 186 ++++++++++++------------------ 1 file changed, 76 insertions(+), 110 deletions(-) diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst index d35dd9fd1af0..818b3e09267f 100644 --- a/Documentation/admin-guide/bug-hunting.rst +++ b/Documentation/admin-guide/bug-hunting.rst @@ -1,7 +1,7 @@ Bug hunting +++++++++++ -Last updated: 20 December 2005 +Last updated: 28 October 2016 Introduction ============ @@ -20,120 +20,62 @@ Before you submit a bug report read Devices not appearing ===================== -Often this is caused by udev. Check that first before blaming it on the -kernel. +Often this is caused by udev/systemd. Check that first before blaming it +on the kernel. Finding patch that caused a bug =============================== - - -Finding using ``git-bisect`` ----------------------------- - Using the provided tools with ``git`` makes finding bugs easy provided the bug is reproducible. Steps to do it: -- start using git for the kernel source -- read the man page for ``git-bisect`` -- have fun - -Finding it the old way ----------------------- - -[Sat Mar 2 10:32:33 PST 1996 KERNEL_BUG-HOWTO lm@sgi.com (Larry McVoy)] - -This is how to track down a bug if you know nothing about kernel hacking. -It's a brute force approach but it works pretty well. - -You need: - - - A reproducible bug - it has to happen predictably (sorry) - - All the kernel tar files from a revision that worked to the - revision that doesn't - -You will then do: - - - Rebuild a revision that you believe works, install, and verify that. - - Do a binary search over the kernels to figure out which one - introduced the bug. I.e., suppose 1.3.28 didn't have the bug, but - you know that 1.3.69 does. Pick a kernel in the middle and build - that, like 1.3.50. Build & test; if it works, pick the mid point - between .50 and .69, else the mid point between .28 and .50. - - You'll narrow it down to the kernel that introduced the bug. You - can probably do better than this but it gets tricky. +- build the Kernel from its git source +- start bisect with [#f1]_:: - - Narrow it down to a subdirectory + $ git bisect start - - Copy kernel that works into "test". Let's say that 3.62 works, - but 3.63 doesn't. So you diff -r those two kernels and come - up with a list of directories that changed. For each of those - directories: +- mark the broken changeset with:: - Copy the non-working directory next to the working directory - as "dir.63". - One directory at time, try moving the working directory to - "dir.62" and mv dir.63 dir"time, try:: + $ git bisect bad [commit] - mv dir dir.62 - mv dir.63 dir - find dir -name '*.[oa]' -print | xargs rm -f +- mark a changeset where the code is known to work with:: - And then rebuild and retest. Assuming that all related - changes were contained in the sub directory, this should - isolate the change to a directory. + $ git bisect good [commit] - Problems: changes in header files may have occurred; I've - found in my case that they were self explanatory - you may - or may not want to give up when that happens. +- rebuild the Kernel and test +- interact with git bisect by using either:: - - Narrow it down to a file + $ git bisect good - - You can apply the same technique to each file in the directory, - hoping that the changes in that file are self contained. + or:: - - Narrow it down to a routine + $ git bisect bad - - You can take the old file and the new file and manually create - a merged file that has:: + depending if the bug happened on the changeset you're testing +- After some interactions, git bisect will give you the changeset that + likely caused the bug. - #ifdef VER62 - routine() - { - ... - } - #else - routine() - { - ... - } - #endif +- For example, if you know that the current version is bad, and version + 4.8 is good, you could do:: - And then walk through that file, one routine at a time and - prefix it with:: + $ git bisect start + $ git bisect bad # Current version is bad + $ git bisect good v4.8 - #define VER62 - /* both routines here */ - #undef VER62 - Then recompile, retest, move the ifdefs until you find the one - that makes the difference. +.. [#f1] You can, optionally, provide both good and bad arguments at git + start:: -Finally, you take all the info that you have, kernel revisions, bug -description, the extent to which you have narrowed it down, and pass -that off to whomever you believe is the maintainer of that section. -A post to linux.dev.kernel isn't such a bad idea if you've done some -work to narrow it down. + git bisect start [BAD] [GOOD] -If you get it down to a routine, you'll probably get a fix in 24 hours. +For further references, please read: -My apologies to Linus and the other kernel hackers for describing this -brute force approach, it's hardly what a kernel hacker would do. However, -it does work and it lets non-hackers help fix bugs. And it is cool -because Linux snapshots will let you do this - something that you can't -do with vendor supplied releases. +- The man page for ``git-bisect`` +- `Fighting regressions with git bisect `_ +- `Fully automated bisecting with "git bisect run" `_ +- `Using Git bisect to figure out when brokenness was introduced `_ Fixing the bug ============== @@ -141,13 +83,16 @@ Fixing the bug Nobody is going to tell you how to fix bugs. Seriously. You need to work it out. But below are some hints on how to use the tools. +objdump +------- + To debug a kernel, use objdump and look for the hex offset from the crash output to find the valid line of code/assembler. Without debug symbols, you will see the assembler code for the routine shown, but if your kernel has debug symbols the C code will also be available. (Debug symbols can be enabled in the kernel hacking menu of the menu configuration.) For example:: - objdump -r -S -l --disassemble net/dccp/ipv4.o + $ objdump -r -S -l --disassemble net/dccp/ipv4.o .. note:: @@ -157,7 +102,7 @@ in the kernel hacking menu of the menu configuration.) For example:: If you don't have access to the code you can also debug on some crash dumps e.g. crash dump output as shown by Dave Miller:: - EIP is at ip_queue_xmit+0x14/0x4c0 + EIP is at +0x14/0x4c0 ... Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00 00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08 @@ -185,16 +130,25 @@ e.g. crash dump output as shown by Dave Miller:: mov 0x8(%ebp), %ebx ! %ebx = skb->sk mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt +gdb +--- + In addition, you can use GDB to figure out the exact file and line -number of the OOPS from the ``vmlinux`` file. If you have -``CONFIG_DEBUG_INFO`` enabled, you can simply copy the EIP value from the -OOPS:: +number of the OOPS from the ``vmlinux`` file. + +The usage of gdb requires a kernel compiled with ``CONFIG_DEBUG_INFO``. +This can be set by running:: + + $ ./scripts/config -d COMPILE_TEST -e DEBUG_KERNEL -e DEBUG_INFO + +On a kernel compiled with ``CONFIG_DEBUG_INFO``, you can simply copy the +EIP value from the OOPS:: EIP: 0060:[] Not tainted VLI And use GDB to translate that to human-readable form:: - gdb vmlinux + $ gdb vmlinux (gdb) l *0xc021e50e If you don't have ``CONFIG_DEBUG_INFO`` enabled, you use the function @@ -204,14 +158,32 @@ offset from the OOPS:: And recompile the kernel with ``CONFIG_DEBUG_INFO`` enabled:: - make vmlinux - gdb vmlinux + $ make vmlinux + $ gdb vmlinux + (gdb) l *vt_ioctl+0xda8 + 0x1888 is in vt_ioctl (drivers/tty/vt/vt_ioctl.c:293). + 288 { + 289 struct vc_data *vc = NULL; + 290 int ret = 0; + 291 + 292 console_lock(); + 293 if (VT_BUSY(vc_num)) + 294 ret = -EBUSY; + 295 else if (vc_num) + 296 vc = vc_deallocate(vc_num); + 297 console_unlock(); + +or, if you want to be more verbose:: + (gdb) p vt_ioctl - (gdb) l *(0x
+ 0xda8) + $1 = {int (struct tty_struct *, unsigned int, unsigned long)} 0xae0 + (gdb) l *0xae0+0xda8 -or, as one command:: +You could, instead, use the object file:: - (gdb) l *(vt_ioctl + 0xda8) + $ make drivers/tty/ + $ gdb drivers/tty/vt/vt_ioctl.o + (gdb) l *vt_ioctl+0xda8 If you have a call trace, such as:: @@ -221,17 +193,11 @@ If you have a call trace, such as:: [] :jbd:journal_stop+0x1be/0x1ee ... -this shows the problem in the :jbd: module. You can load that module in gdb -and list the relevant code:: - - gdb fs/jbd/jbd.ko - (gdb) p log_wait_commit - (gdb) l *(0x
+ 0xa3) - -or:: - - (gdb) l *(log_wait_commit + 0xa3) +this shows the problem likely in the :jbd: module. You can load that module +in gdb and list the relevant code:: + $ gdb fs/jbd/jbd.ko + (gdb) l *log_wait_commit+0xa3 Another very useful option of the Kernel Hacking section in menuconfig is Debug memory allocations. This will help you see whether data has been -- cgit v1.2.3 From c730904b16c7ee6f3bba2d1536621151745fc314 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 7 Nov 2016 17:03:17 -0200 Subject: doc-rst: admin-guide: move bug bisect to a separate file Better organize the admin guide documentation by moving the bug bisect to a separate file. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/bug-bisect.rst | 78 +++++++++++++++++++++++++++++++ Documentation/admin-guide/bug-hunting.rst | 74 ----------------------------- Documentation/admin-guide/index.rst | 1 + 3 files changed, 79 insertions(+), 74 deletions(-) create mode 100644 Documentation/admin-guide/bug-bisect.rst diff --git a/Documentation/admin-guide/bug-bisect.rst b/Documentation/admin-guide/bug-bisect.rst new file mode 100644 index 000000000000..5682d742017c --- /dev/null +++ b/Documentation/admin-guide/bug-bisect.rst @@ -0,0 +1,78 @@ +Bisecting a bug ++++++++++++++++ + +Last updated: 28 October 2016 + +Introduction +============ + +Always try the latest kernel from kernel.org and build from source. If you are +not confident in doing that please report the bug to your distribution vendor +instead of to a kernel developer. + +Finding bugs is not always easy. Have a go though. If you can't find it don't +give up. Report as much as you have found to the relevant maintainer. See +MAINTAINERS for who that is for the subsystem you have worked on. + +Before you submit a bug report read +:ref:`Documentation/admin-guide/reporting-bugs.rst `. + +Devices not appearing +===================== + +Often this is caused by udev/systemd. Check that first before blaming it +on the kernel. + +Finding patch that caused a bug +=============================== + +Using the provided tools with ``git`` makes finding bugs easy provided the bug +is reproducible. + +Steps to do it: + +- build the Kernel from its git source +- start bisect with [#f1]_:: + + $ git bisect start + +- mark the broken changeset with:: + + $ git bisect bad [commit] + +- mark a changeset where the code is known to work with:: + + $ git bisect good [commit] + +- rebuild the Kernel and test +- interact with git bisect by using either:: + + $ git bisect good + + or:: + + $ git bisect bad + + depending if the bug happened on the changeset you're testing +- After some interactions, git bisect will give you the changeset that + likely caused the bug. + +- For example, if you know that the current version is bad, and version + 4.8 is good, you could do:: + + $ git bisect start + $ git bisect bad # Current version is bad + $ git bisect good v4.8 + + +.. [#f1] You can, optionally, provide both good and bad arguments at git + start:: + + git bisect start [BAD] [GOOD] + +For further references, please read: + +- The man page for ``git-bisect`` +- `Fighting regressions with git bisect `_ +- `Fully automated bisecting with "git bisect run" `_ +- `Using Git bisect to figure out when brokenness was introduced `_ diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst index 818b3e09267f..d245d4677ae2 100644 --- a/Documentation/admin-guide/bug-hunting.rst +++ b/Documentation/admin-guide/bug-hunting.rst @@ -3,80 +3,6 @@ Bug hunting Last updated: 28 October 2016 -Introduction -============ - -Always try the latest kernel from kernel.org and build from source. If you are -not confident in doing that please report the bug to your distribution vendor -instead of to a kernel developer. - -Finding bugs is not always easy. Have a go though. If you can't find it don't -give up. Report as much as you have found to the relevant maintainer. See -MAINTAINERS for who that is for the subsystem you have worked on. - -Before you submit a bug report read -:ref:`Documentation/admin-guide/reporting-bugs.rst `. - -Devices not appearing -===================== - -Often this is caused by udev/systemd. Check that first before blaming it -on the kernel. - -Finding patch that caused a bug -=============================== - -Using the provided tools with ``git`` makes finding bugs easy provided the bug -is reproducible. - -Steps to do it: - -- build the Kernel from its git source -- start bisect with [#f1]_:: - - $ git bisect start - -- mark the broken changeset with:: - - $ git bisect bad [commit] - -- mark a changeset where the code is known to work with:: - - $ git bisect good [commit] - -- rebuild the Kernel and test -- interact with git bisect by using either:: - - $ git bisect good - - or:: - - $ git bisect bad - - depending if the bug happened on the changeset you're testing -- After some interactions, git bisect will give you the changeset that - likely caused the bug. - -- For example, if you know that the current version is bad, and version - 4.8 is good, you could do:: - - $ git bisect start - $ git bisect bad # Current version is bad - $ git bisect good v4.8 - - -.. [#f1] You can, optionally, provide both good and bad arguments at git - start:: - - git bisect start [BAD] [GOOD] - -For further references, please read: - -- The man page for ``git-bisect`` -- `Fighting regressions with git bisect `_ -- `Fully automated bisecting with "git bisect run" `_ -- `Using Git bisect to figure out when brokenness was introduced `_ - Fixing the bug ============== diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 368845e9900a..98e60f678352 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -26,6 +26,7 @@ problems and bugs in particular. reporting-bugs security-bugs bug-hunting + bug-bisect oops-tracing ramoops dynamic-debug-howto -- cgit v1.2.3 From 337c188dff4a850643ee299c38b2591bbda937a7 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 7 Nov 2016 17:03:18 -0200 Subject: admin-guide: move tainted kernels info to a separate file The tainted kernels info is not directly related to the oops tracing. So, let's move it to a separate file. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/index.rst | 9 ++-- Documentation/admin-guide/oops-tracing.rst | 59 --------------------------- Documentation/admin-guide/tainted-kernels.rst | 59 +++++++++++++++++++++++++++ 3 files changed, 64 insertions(+), 63 deletions(-) create mode 100644 Documentation/admin-guide/tainted-kernels.rst diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 98e60f678352..86a6ab98d6b6 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -8,7 +8,7 @@ document! With luck things will improve quickly over time. This initial section contains overall information, including the README file describing the kernel as a whole, documentation on kernel parameters, -etc. +etc. .. toctree:: :maxdepth: 1 @@ -22,12 +22,13 @@ problems and bugs in particular. .. toctree:: :maxdepth: 1 - + reporting-bugs security-bugs bug-hunting bug-bisect oops-tracing + tainted-kernels ramoops dynamic-debug-howto init @@ -38,7 +39,7 @@ ABI will be found here. .. toctree:: :maxdepth: 1 - + sysfs-rules The rest of this manual consists of various unordered guides on how to @@ -46,7 +47,7 @@ configure specific aspects of kernel behavior to your liking. .. toctree:: :maxdepth: 1 - + initrd serial-console braille-console diff --git a/Documentation/admin-guide/oops-tracing.rst b/Documentation/admin-guide/oops-tracing.rst index 13be8d7bcfe7..1f5e2b716631 100644 --- a/Documentation/admin-guide/oops-tracing.rst +++ b/Documentation/admin-guide/oops-tracing.rst @@ -239,62 +239,3 @@ processed by ``klogd``:: --------------------------------------------------------------------------- -Tainted kernels ---------------- - -Some oops reports contain the string **'Tainted: '** after the program -counter. This indicates that the kernel has been tainted by some -mechanism. The string is followed by a series of position-sensitive -characters, each representing a particular tainted value. - - 1) 'G' if all modules loaded have a GPL or compatible license, 'P' if - any proprietary module has been loaded. Modules without a - MODULE_LICENSE or with a MODULE_LICENSE that is not recognised by - insmod as GPL compatible are assumed to be proprietary. - - 2) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all - modules were loaded normally. - - 3) ``S`` if the oops occurred on an SMP kernel running on hardware that - hasn't been certified as safe to run multiprocessor. - Currently this occurs only on various Athlons that are not - SMP capable. - - 4) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all - modules were unloaded normally. - - 5) ``M`` if any processor has reported a Machine Check Exception, - ``' '`` if no Machine Check Exceptions have occurred. - - 6) ``B`` if a page-release function has found a bad page reference or - some unexpected page flags. - - 7) ``U`` if a user or user application specifically requested that the - Tainted flag be set, ``' '`` otherwise. - - 8) ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG. - - 9) ``A`` if the ACPI table has been overridden. - - 10) ``W`` if a warning has previously been issued by the kernel. - (Though some warnings may set more specific taint flags.) - - 11) ``C`` if a staging driver has been loaded. - - 12) ``I`` if the kernel is working around a severe bug in the platform - firmware (BIOS or similar). - - 13) ``O`` if an externally-built ("out-of-tree") module has been loaded. - - 14) ``E`` if an unsigned module has been loaded in a kernel supporting - module signature. - - 15) ``L`` if a soft lockup has previously occurred on the system. - - 16) ``K`` if the kernel has been live patched. - -The primary reason for the **'Tainted: '** string is to tell kernel -debuggers if this is a clean kernel or if anything unusual has -occurred. Tainting is permanent: even if an offending module is -unloaded, the tainted value remains to indicate that the kernel is not -trustworthy. diff --git a/Documentation/admin-guide/tainted-kernels.rst b/Documentation/admin-guide/tainted-kernels.rst new file mode 100644 index 000000000000..1df03b5cb02f --- /dev/null +++ b/Documentation/admin-guide/tainted-kernels.rst @@ -0,0 +1,59 @@ +Tainted kernels +--------------- + +Some oops reports contain the string **'Tainted: '** after the program +counter. This indicates that the kernel has been tainted by some +mechanism. The string is followed by a series of position-sensitive +characters, each representing a particular tainted value. + + 1) 'G' if all modules loaded have a GPL or compatible license, 'P' if + any proprietary module has been loaded. Modules without a + MODULE_LICENSE or with a MODULE_LICENSE that is not recognised by + insmod as GPL compatible are assumed to be proprietary. + + 2) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all + modules were loaded normally. + + 3) ``S`` if the oops occurred on an SMP kernel running on hardware that + hasn't been certified as safe to run multiprocessor. + Currently this occurs only on various Athlons that are not + SMP capable. + + 4) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all + modules were unloaded normally. + + 5) ``M`` if any processor has reported a Machine Check Exception, + ``' '`` if no Machine Check Exceptions have occurred. + + 6) ``B`` if a page-release function has found a bad page reference or + some unexpected page flags. + + 7) ``U`` if a user or user application specifically requested that the + Tainted flag be set, ``' '`` otherwise. + + 8) ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG. + + 9) ``A`` if the ACPI table has been overridden. + + 10) ``W`` if a warning has previously been issued by the kernel. + (Though some warnings may set more specific taint flags.) + + 11) ``C`` if a staging driver has been loaded. + + 12) ``I`` if the kernel is working around a severe bug in the platform + firmware (BIOS or similar). + + 13) ``O`` if an externally-built ("out-of-tree") module has been loaded. + + 14) ``E`` if an unsigned module has been loaded in a kernel supporting + module signature. + + 15) ``L`` if a soft lockup has previously occurred on the system. + + 16) ``K`` if the kernel has been live patched. + +The primary reason for the **'Tainted: '** string is to tell kernel +debuggers if this is a clean kernel or if anything unusual has +occurred. Tainting is permanent: even if an offending module is +unloaded, the tainted value remains to indicate that the kernel is not +trustworthy. -- cgit v1.2.3 From f226e460875da8e00febf55e5ec3438e498ca676 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 7 Nov 2016 17:03:19 -0200 Subject: admin-guide: merge oops-tracing with bug-hunting Now that oops-tracing.rst has only information about stack dumps found on OOPS, and bug-hunting.rst has only information about how to identify the source code line associated with a stack dump, let's merge them and improve the information inside it. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/bug-hunting.rst | 358 +++++++++++++++++++++++------ Documentation/admin-guide/index.rst | 1 - Documentation/admin-guide/oops-tracing.rst | 241 ------------------- 3 files changed, 293 insertions(+), 307 deletions(-) delete mode 100644 Documentation/admin-guide/oops-tracing.rst diff --git a/Documentation/admin-guide/bug-hunting.rst b/Documentation/admin-guide/bug-hunting.rst index d245d4677ae2..08c4b1308189 100644 --- a/Documentation/admin-guide/bug-hunting.rst +++ b/Documentation/admin-guide/bug-hunting.rst @@ -1,68 +1,113 @@ Bug hunting -+++++++++++ - -Last updated: 28 October 2016 - -Fixing the bug -============== - -Nobody is going to tell you how to fix bugs. Seriously. You need to work it -out. But below are some hints on how to use the tools. - -objdump -------- - -To debug a kernel, use objdump and look for the hex offset from the crash -output to find the valid line of code/assembler. Without debug symbols, you -will see the assembler code for the routine shown, but if your kernel has -debug symbols the C code will also be available. (Debug symbols can be enabled -in the kernel hacking menu of the menu configuration.) For example:: - - $ objdump -r -S -l --disassemble net/dccp/ipv4.o +=========== + +Kernel bug reports often come with a stack dump like the one below:: + + ------------[ cut here ]------------ + WARNING: CPU: 1 PID: 28102 at kernel/module.c:1108 module_put+0x57/0x70 + Modules linked in: dvb_usb_gp8psk(-) dvb_usb dvb_core nvidia_drm(PO) nvidia_modeset(PO) snd_hda_codec_hdmi snd_hda_intel snd_hda_codec snd_hwdep snd_hda_core snd_pcm snd_timer snd soundcore nvidia(PO) [last unloaded: rc_core] + CPU: 1 PID: 28102 Comm: rmmod Tainted: P WC O 4.8.4-build.1 #1 + Hardware name: MSI MS-7309/MS-7309, BIOS V1.12 02/23/2009 + 00000000 c12ba080 00000000 00000000 c103ed6a c1616014 00000001 00006dc6 + c1615862 00000454 c109e8a7 c109e8a7 00000009 ffffffff 00000000 f13f6a10 + f5f5a600 c103ee33 00000009 00000000 00000000 c109e8a7 f80ca4d0 c109f617 + Call Trace: + [] ? dump_stack+0x44/0x64 + [] ? __warn+0xfa/0x120 + [] ? module_put+0x57/0x70 + [] ? module_put+0x57/0x70 + [] ? warn_slowpath_null+0x23/0x30 + [] ? module_put+0x57/0x70 + [] ? gp8psk_fe_set_frontend+0x460/0x460 [dvb_usb_gp8psk] + [] ? symbol_put_addr+0x27/0x50 + [] ? dvb_usb_adapter_frontend_exit+0x3a/0x70 [dvb_usb] + [] ? dvb_usb_exit+0x2f/0xd0 [dvb_usb] + [] ? usb_disable_endpoint+0x7c/0xb0 + [] ? dvb_usb_device_exit+0x2a/0x50 [dvb_usb] + [] ? usb_unbind_interface+0x62/0x250 + [] ? __pm_runtime_idle+0x44/0x70 + [] ? __device_release_driver+0x78/0x120 + [] ? driver_detach+0x87/0x90 + [] ? bus_remove_driver+0x38/0x90 + [] ? usb_deregister+0x58/0xb0 + [] ? SyS_delete_module+0x130/0x1f0 + [] ? task_work_run+0x64/0x80 + [] ? exit_to_usermode_loop+0x85/0x90 + [] ? do_fast_syscall_32+0x80/0x130 + [] ? sysenter_past_esp+0x40/0x6a + ---[ end trace 6ebc60ef3981792f ]--- + +Such stack traces provide enough information to identify the line inside the +Kernel's source code where the bug happened. Depending on the severity of +the issue, it may also contain the word **Oops**, as on this one:: + + BUG: unable to handle kernel NULL pointer dereference at (null) + IP: [] iret_exc+0x7d0/0xa59 + *pdpt = 000000002258a001 *pde = 0000000000000000 + Oops: 0002 [#1] PREEMPT SMP + ... + +Despite being an **Oops** or some other sort of stack trace, the offended +line is usually required to identify and handle the bug. Along this chapter, +we'll refer to "Oops" for all kinds of stack traces that need to be analized. .. note:: - You need to be at the top level of the kernel tree for this to pick up - your C files. - -If you don't have access to the code you can also debug on some crash dumps -e.g. crash dump output as shown by Dave Miller:: - - EIP is at +0x14/0x4c0 - ... - Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00 - 00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08 - <8b> 83 3c 01 00 00 89 44 24 14 8b 45 28 85 c0 89 44 24 18 0f 85 - - Put the bytes into a "foo.s" file like this: - - .text - .globl foo - foo: - .byte .... /* bytes from Code: part of OOPS dump */ - - Compile it with "gcc -c -o foo.o foo.s" then look at the output of - "objdump --disassemble foo.o". - - Output: - - ip_queue_xmit: - push %ebp - push %edi - push %esi - push %ebx - sub $0xbc, %esp - mov 0xd0(%esp), %ebp ! %ebp = arg0 (skb) - mov 0x8(%ebp), %ebx ! %ebx = skb->sk - mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt + ``ksymoops`` is useless on 2.6 or upper. Please use the Oops in its original + format (from ``dmesg``, etc). Ignore any references in this or other docs to + "decoding the Oops" or "running it through ksymoops". + If you post an Oops from 2.6+ that has been run through ``ksymoops``, + people will just tell you to repost it. + +Where is the Oops message is located? +------------------------------------- + +Normally the Oops text is read from the kernel buffers by klogd and +handed to ``syslogd`` which writes it to a syslog file, typically +``/var/log/messages`` (depends on ``/etc/syslog.conf``). On systems with +systemd, it may also be stored by the ``journald`` daemon, and accessed +by running ``journalctl`` command. + +Sometimes ``klogd`` dies, in which case you can run ``dmesg > file`` to +read the data from the kernel buffers and save it. Or you can +``cat /proc/kmsg > file``, however you have to break in to stop the transfer, +``kmsg`` is a "never ending file". + +If the machine has crashed so badly that you cannot enter commands or +the disk is not available then you have three options: + +(1) Hand copy the text from the screen and type it in after the machine + has restarted. Messy but it is the only option if you have not + planned for a crash. Alternatively, you can take a picture of + the screen with a digital camera - not nice, but better than + nothing. If the messages scroll off the top of the console, you + may find that booting with a higher resolution (eg, ``vga=791``) + will allow you to read more of the text. (Caveat: This needs ``vesafb``, + so won't help for 'early' oopses) + +(2) Boot with a serial console (see + :ref:`Documentation/admin-guide/serial-console.rst `), + run a null modem to a second machine and capture the output there + using your favourite communication program. Minicom works well. + +(3) Use Kdump (see Documentation/kdump/kdump.txt), + extract the kernel ring buffer from old memory with using dmesg + gdbmacro in Documentation/kdump/gdbmacros.txt. + +Finding the bug's location +-------------------------- + +Reporting a bug works best if you point the location of the bug at the +Kernel source file. There are two methods for doing that. Usually, using +``gdb`` is easier, but the Kernel should be pre-compiled with debug info. gdb ---- +^^^ -In addition, you can use GDB to figure out the exact file and line +The GNU debug (``gdb``) is the best way to figure out the exact file and line number of the OOPS from the ``vmlinux`` file. -The usage of gdb requires a kernel compiled with ``CONFIG_DEBUG_INFO``. +The usage of gdb works best on a kernel compiled with ``CONFIG_DEBUG_INFO``. This can be set by running:: $ ./scripts/config -d COMPILE_TEST -e DEBUG_KERNEL -e DEBUG_INFO @@ -84,6 +129,7 @@ offset from the OOPS:: And recompile the kernel with ``CONFIG_DEBUG_INFO`` enabled:: + $ ./scripts/config -d COMPILE_TEST -e DEBUG_KERNEL -e DEBUG_INFO $ make vmlinux $ gdb vmlinux (gdb) l *vt_ioctl+0xda8 @@ -125,17 +171,199 @@ in gdb and list the relevant code:: $ gdb fs/jbd/jbd.ko (gdb) l *log_wait_commit+0xa3 -Another very useful option of the Kernel Hacking section in menuconfig is -Debug memory allocations. This will help you see whether data has been -initialised and not set before use etc. To see the values that get assigned -with this look at ``mm/slab.c`` and search for ``POISON_INUSE``. When using -this an Oops will often show the poisoned data instead of zero which is the -default. +.. note:: + + You can also do the same for any function call at the stack trace, + like this one:: + + [] ? dvb_usb_adapter_frontend_exit+0x3a/0x70 [dvb_usb] + + The position where the above call happened can be seen with:: + + $ gdb drivers/media/usb/dvb-usb/dvb-usb.o + (gdb) l *dvb_usb_adapter_frontend_exit+0x3a + +objdump +^^^^^^^ + +To debug a kernel, use objdump and look for the hex offset from the crash +output to find the valid line of code/assembler. Without debug symbols, you +will see the assembler code for the routine shown, but if your kernel has +debug symbols the C code will also be available. (Debug symbols can be enabled +in the kernel hacking menu of the menu configuration.) For example:: + + $ objdump -r -S -l --disassemble net/dccp/ipv4.o + +.. note:: -Once you have worked out a fix please submit it upstream. After all open -source is about sharing what you do and don't you want to be recognised for -your genius? + You need to be at the top level of the kernel tree for this to pick up + your C files. + +If you don't have access to the code you can also debug on some crash dumps +e.g. crash dump output as shown by Dave Miller:: + + EIP is at +0x14/0x4c0 + ... + Code: 44 24 04 e8 6f 05 00 00 e9 e8 fe ff ff 8d 76 00 8d bc 27 00 00 + 00 00 55 57 56 53 81 ec bc 00 00 00 8b ac 24 d0 00 00 00 8b 5d 08 + <8b> 83 3c 01 00 00 89 44 24 14 8b 45 28 85 c0 89 44 24 18 0f 85 + + Put the bytes into a "foo.s" file like this: + + .text + .globl foo + foo: + .byte .... /* bytes from Code: part of OOPS dump */ + + Compile it with "gcc -c -o foo.o foo.s" then look at the output of + "objdump --disassemble foo.o". + + Output: + + ip_queue_xmit: + push %ebp + push %edi + push %esi + push %ebx + sub $0xbc, %esp + mov 0xd0(%esp), %ebp ! %ebp = arg0 (skb) + mov 0x8(%ebp), %ebx ! %ebx = skb->sk + mov 0x13c(%ebx), %eax ! %eax = inet_sk(sk)->opt + +Reporting the bug +----------------- + +Once you find where the bug happened, by inspecting its location, +you could either try to fix it yourself or report it upstream. + +In order to report it upstream, you should identify the mailing list +used for the development of the affected code. This can be done by using +the ``get_maintainer.pl`` script. + +For example, if you find a bug at the gspca's conex.c file, you can get +their maintainers with:: + + $ ./scripts/get_maintainer.pl -f drivers/media/usb/gspca/sonixj.c + Hans Verkuil (odd fixer:GSPCA USB WEBCAM DRIVER,commit_signer:1/1=100%) + Mauro Carvalho Chehab (maintainer:MEDIA INPUT INFRASTRUCTURE (V4L/DVB),commit_signer:1/1=100%) + Tejun Heo (commit_signer:1/1=100%) + Bhaktipriya Shridhar (commit_signer:1/1=100%,authored:1/1=100%,added_lines:4/4=100%,removed_lines:9/9=100%) + linux-media@vger.kernel.org (open list:GSPCA USB WEBCAM DRIVER) + linux-kernel@vger.kernel.org (open list) + +Please notice that it will point to: + +- The last developers that touched on the source code. On the above example, + Tejun and Bhaktipriya (in this specific case, none really envolved on the + development of this file); +- The driver maintainer (Hans Verkuil); +- The subsystem maintainer (Mauro Carvalho Chehab) +- The driver and/or subsystem mailing list (linux-media@vger.kernel.org); +- the Linux Kernel mailing list (linux-kernel@vger.kernel.org). + +Usually, the fastest way to have your bug fixed is to report it to mailing +list used for the development of the code (linux-media ML) copying the driver maintainer (Hans). + +If you are totally stumped as to whom to send the report, and +``get_maintainer.pl`` didn't provide you anything useful, send it to +linux-kernel@vger.kernel.org. + +Thanks for your help in making Linux as stable as humanly possible. + +Fixing the bug +-------------- + +If you know programming, you could help us by not only reporting the bug, +but also providing us with a solution. After all open source is about +sharing what you do and don't you want to be recognised for your genius? + +If you decide to take this way, once you have worked out a fix please submit +it upstream. Please do read ref:`Documentation/process/submitting-patches.rst ` though to help your code get accepted. + + +--------------------------------------------------------------------------- + +Notes on Oops tracing with ``klogd`` +------------------------------------ + +In order to help Linus and the other kernel developers there has been +substantial support incorporated into ``klogd`` for processing protection +faults. In order to have full support for address resolution at least +version 1.3-pl3 of the ``sysklogd`` package should be used. + +When a protection fault occurs the ``klogd`` daemon automatically +translates important addresses in the kernel log messages to their +symbolic equivalents. This translated kernel message is then +forwarded through whatever reporting mechanism ``klogd`` is using. The +protection fault message can be simply cut out of the message files +and forwarded to the kernel developers. + +Two types of address resolution are performed by ``klogd``. The first is +static translation and the second is dynamic translation. Static +translation uses the System.map file in much the same manner that +ksymoops does. In order to do static translation the ``klogd`` daemon +must be able to find a system map file at daemon initialization time. +See the klogd man page for information on how ``klogd`` searches for map +files. + +Dynamic address translation is important when kernel loadable modules +are being used. Since memory for kernel modules is allocated from the +kernel's dynamic memory pools there are no fixed locations for either +the start of the module or for functions and symbols in the module. + +The kernel supports system calls which allow a program to determine +which modules are loaded and their location in memory. Using these +system calls the klogd daemon builds a symbol table which can be used +to debug a protection fault which occurs in a loadable kernel module. + +At the very minimum klogd will provide the name of the module which +generated the protection fault. There may be additional symbolic +information available if the developer of the loadable module chose to +export symbol information from the module. + +Since the kernel module environment can be dynamic there must be a +mechanism for notifying the ``klogd`` daemon when a change in module +environment occurs. There are command line options available which +allow klogd to signal the currently executing daemon that symbol +information should be refreshed. See the ``klogd`` manual page for more +information. + +A patch is included with the sysklogd distribution which modifies the +``modules-2.0.0`` package to automatically signal klogd whenever a module +is loaded or unloaded. Applying this patch provides essentially +seamless support for debugging protection faults which occur with +kernel loadable modules. + +The following is an example of a protection fault in a loadable module +processed by ``klogd``:: + + Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc + Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 + Aug 29 09:51:01 blizard kernel: *pde = 00000000 + Aug 29 09:51:01 blizard kernel: Oops: 0002 + Aug 29 09:51:01 blizard kernel: CPU: 0 + Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] + Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 + Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c + Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c + Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 + Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) + Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 + Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 + Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 + Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] + Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 + +--------------------------------------------------------------------------- + +:: + + Dr. G.W. Wettstein Oncology Research Div. Computing Facility + Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com + 820 4th St. N. + Fargo, ND 58122 + Phone: 701-234-7556 diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 86a6ab98d6b6..2681cbd24cdd 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -27,7 +27,6 @@ problems and bugs in particular. security-bugs bug-hunting bug-bisect - oops-tracing tainted-kernels ramoops dynamic-debug-howto diff --git a/Documentation/admin-guide/oops-tracing.rst b/Documentation/admin-guide/oops-tracing.rst deleted file mode 100644 index 1f5e2b716631..000000000000 --- a/Documentation/admin-guide/oops-tracing.rst +++ /dev/null @@ -1,241 +0,0 @@ -OOPS tracing -============ - -.. note:: - - ``ksymoops`` is useless on 2.6 or upper. Please use the Oops in its original - format (from ``dmesg``, etc). Ignore any references in this or other docs to - "decoding the Oops" or "running it through ksymoops". - If you post an Oops from 2.6+ that has been run through ``ksymoops``, - people will just tell you to repost it. - -Quick Summary -------------- - -Find the Oops and send it to the maintainer of the kernel area that seems to be -involved with the problem. Don't worry too much about getting the wrong person. -If you are unsure send it to the person responsible for the code relevant to -what you were doing. If it occurs repeatably try and describe how to recreate -it. That's worth even more than the oops. - -If you are totally stumped as to whom to send the report, send it to -linux-kernel@vger.kernel.org. Thanks for your help in making Linux as -stable as humanly possible. - -Where is the Oops? ----------------------- - -Normally the Oops text is read from the kernel buffers by klogd and -handed to ``syslogd`` which writes it to a syslog file, typically -``/var/log/messages`` (depends on ``/etc/syslog.conf``). Sometimes ``klogd`` -dies, in which case you can run ``dmesg > file`` to read the data from the -kernel buffers and save it. Or you can ``cat /proc/kmsg > file``, however you -have to break in to stop the transfer, ``kmsg`` is a "never ending file". -If the machine has crashed so badly that you cannot enter commands or -the disk is not available then you have three options : - -(1) Hand copy the text from the screen and type it in after the machine - has restarted. Messy but it is the only option if you have not - planned for a crash. Alternatively, you can take a picture of - the screen with a digital camera - not nice, but better than - nothing. If the messages scroll off the top of the console, you - may find that booting with a higher resolution (eg, ``vga=791``) - will allow you to read more of the text. (Caveat: This needs ``vesafb``, - so won't help for 'early' oopses) - -(2) Boot with a serial console (see - :ref:`Documentation/admin-guide/serial-console.rst `), - run a null modem to a second machine and capture the output there - using your favourite communication program. Minicom works well. - -(3) Use Kdump (see Documentation/kdump/kdump.txt), - extract the kernel ring buffer from old memory with using dmesg - gdbmacro in Documentation/kdump/gdbmacros.txt. - - -Full Information ----------------- - -.. note:: - - the message from Linus below applies to 2.4 kernel. I have preserved it - for historical reasons, and because some of the information in it still - applies. Especially, please ignore any references to ksymoops. - - :: - - From: Linus Torvalds - - How to track down an Oops.. [originally a mail to linux-kernel] - - The main trick is having 5 years of experience with those pesky oops - messages ;-) - -Actually, there are things you can do that make this easier. I have two -separate approaches:: - - gdb /usr/src/linux/vmlinux - gdb> disassemble - -That's the easy way to find the problem, at least if the bug-report is -well made (like this one was - run through ``ksymoops`` to get the -information of which function and the offset in the function that it -happened in). - -Oh, it helps if the report happens on a kernel that is compiled with the -same compiler and similar setups. - -The other thing to do is disassemble the "Code:" part of the bug report: -ksymoops will do this too with the correct tools, but if you don't have -the tools you can just do a silly program:: - - char str[] = "\xXX\xXX\xXX..."; - main(){} - -and compile it with ``gcc -g`` and then do ``disassemble str`` (where the ``XX`` -stuff are the values reported by the Oops - you can just cut-and-paste -and do a replace of spaces to ``\x`` - that's what I do, as I'm too lazy -to write a program to automate this all). - -Alternatively, you can use the shell script in ``scripts/decodecode``. -Its usage is:: - - decodecode < oops.txt - -The hex bytes that follow "Code:" may (in some architectures) have a series -of bytes that precede the current instruction pointer as well as bytes at and -following the current instruction pointer. In some cases, one instruction -byte or word is surrounded by ``<>`` or ``()``, as in ``<86>`` or ``(f00d)``. -These ``<>`` or ``()`` markings indicate the current instruction pointer. - -Example from i386, split into multiple lines for readability:: - - Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1 - 64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54 - 7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0 - -Finally, if you want to see where the code comes from, you can do:: - - cd /usr/src/linux - make fs/buffer.s # or whatever file the bug happened in - -and then you get a better idea of what happens than with the gdb -disassembly. - -Now, the trick is just then to combine all the data you have: the C -sources (and general knowledge of what it **should** do), the assembly -listing and the code disassembly (and additionally the register dump you -also get from the "oops" message - that can be useful to see **what** the -corrupted pointers were, and when you have the assembler listing you can -also match the other registers to whatever C expressions they were used -for). - -Essentially, you just look at what doesn't match (in this case it was the -"Code" disassembly that didn't match with what the compiler generated). -Then you need to find out **why** they don't match. Often it's simple - you -see that the code uses a NULL pointer and then you look at the code and -wonder how the NULL pointer got there, and if it's a valid thing to do -you just check against it.. - -Now, if somebody gets the idea that this is time-consuming and requires -some small amount of concentration, you're right. Which is why I will -mostly just ignore any panic reports that don't have the symbol table -info etc looked up: it simply gets too hard to look it up (I have some -programs to search for specific patterns in the kernel code segment, and -sometimes I have been able to look up those kinds of panics too, but -that really requires pretty good knowledge of the kernel just to be able -to pick out the right sequences etc..) - -**Sometimes** it happens that I just see the disassembled code sequence -from the panic, and I know immediately where it's coming from. That's when -I get worried that I've been doing this for too long ;-) - - Linus - - ---------------------------------------------------------------------------- - -Notes on Oops tracing with ``klogd`` ------------------------------------- - -In order to help Linus and the other kernel developers there has been -substantial support incorporated into ``klogd`` for processing protection -faults. In order to have full support for address resolution at least -version 1.3-pl3 of the ``sysklogd`` package should be used. - -When a protection fault occurs the ``klogd`` daemon automatically -translates important addresses in the kernel log messages to their -symbolic equivalents. This translated kernel message is then -forwarded through whatever reporting mechanism ``klogd`` is using. The -protection fault message can be simply cut out of the message files -and forwarded to the kernel developers. - -Two types of address resolution are performed by ``klogd``. The first is -static translation and the second is dynamic translation. Static -translation uses the System.map file in much the same manner that -ksymoops does. In order to do static translation the ``klogd`` daemon -must be able to find a system map file at daemon initialization time. -See the klogd man page for information on how ``klogd`` searches for map -files. - -Dynamic address translation is important when kernel loadable modules -are being used. Since memory for kernel modules is allocated from the -kernel's dynamic memory pools there are no fixed locations for either -the start of the module or for functions and symbols in the module. - -The kernel supports system calls which allow a program to determine -which modules are loaded and their location in memory. Using these -system calls the klogd daemon builds a symbol table which can be used -to debug a protection fault which occurs in a loadable kernel module. - -At the very minimum klogd will provide the name of the module which -generated the protection fault. There may be additional symbolic -information available if the developer of the loadable module chose to -export symbol information from the module. - -Since the kernel module environment can be dynamic there must be a -mechanism for notifying the ``klogd`` daemon when a change in module -environment occurs. There are command line options available which -allow klogd to signal the currently executing daemon that symbol -information should be refreshed. See the ``klogd`` manual page for more -information. - -A patch is included with the sysklogd distribution which modifies the -``modules-2.0.0`` package to automatically signal klogd whenever a module -is loaded or unloaded. Applying this patch provides essentially -seamless support for debugging protection faults which occur with -kernel loadable modules. - -The following is an example of a protection fault in a loadable module -processed by ``klogd``:: - - Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc - Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000 - Aug 29 09:51:01 blizard kernel: *pde = 00000000 - Aug 29 09:51:01 blizard kernel: Oops: 0002 - Aug 29 09:51:01 blizard kernel: CPU: 0 - Aug 29 09:51:01 blizard kernel: EIP: 0010:[oops:_oops+16/3868] - Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212 - Aug 29 09:51:01 blizard kernel: eax: 315e97cc ebx: 003a6f80 ecx: 001be77b edx: 00237c0c - Aug 29 09:51:01 blizard kernel: esi: 00000000 edi: bffffdb3 ebp: 00589f90 esp: 00589f8c - Aug 29 09:51:01 blizard kernel: ds: 0018 es: 0018 fs: 002b gs: 002b ss: 0018 - Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000) - Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001 - Aug 29 09:51:01 blizard kernel: 00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00 - Aug 29 09:51:01 blizard kernel: bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036 - Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128] - Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3 - ---------------------------------------------------------------------------- - -:: - - Dr. G.W. Wettstein Oncology Research Div. Computing Facility - Roger Maris Cancer Center INTERNET: greg@wind.rmcc.com - 820 4th St. N. - Fargo, ND 58122 - Phone: 701-234-7556 - - ---------------------------------------------------------------------------- - -- cgit v1.2.3 From d80b9d2aba35d2c9c030c77ad463454c077959ea Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:10 +0900 Subject: Documentation/process/howto: Mark subsection in suggested format `Specific guidelines for the kernel documentation` section of `kernel-documentation.rst` suggests to use ``~`` for subsection but subsections in HOWTO is not marked in the format. This commit marks them in the format. Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet --- Documentation/process/howto.rst | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst index 3f66a1980726..449ca1f199f4 100644 --- a/Documentation/process/howto.rst +++ b/Documentation/process/howto.rst @@ -254,7 +254,8 @@ branches. These different branches are: - the 4.x -next kernel tree for integration tests 4.x kernel tree ------------------ +~~~~~~~~~~~~~~~ + 4.x kernels are maintained by Linus Torvalds, and can be found on https://kernel.org in the pub/linux/kernel/v4.x/ directory. Its development process is as follows: @@ -289,7 +290,8 @@ mailing list about kernel releases: preconceived timeline."* 4.x.y -stable kernel tree -------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~ + Kernels with 3-part versions are -stable kernels. They contain relatively small and critical fixes for security problems or significant regressions discovered in a given 4.x kernel. @@ -312,7 +314,8 @@ documents what kinds of changes are acceptable for the -stable tree, and how the release process works. 4.x -git patches ----------------- +~~~~~~~~~~~~~~~~ + These are daily snapshots of Linus' kernel tree which are managed in a git repository (hence the name.) These patches are usually released daily and represent the current state of Linus' tree. They are more @@ -320,7 +323,8 @@ experimental than -rc kernels since they are generated automatically without even a cursory glance to see if they are sane. Subsystem Specific kernel trees and patches -------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The maintainers of the various kernel subsystems --- and also many kernel subsystem developers --- expose their current state of development in source repositories. That way, others can see what is @@ -344,7 +348,8 @@ accepted, or rejected. Most of these patchwork sites are listed at https://patchwork.kernel.org/. 4.x -next kernel tree for integration tests -------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + Before updates from subsystem trees are merged into the mainline 4.x tree, they need to be integration-tested. For this purpose, a special testing repository exists into which virtually all subsystem trees are -- cgit v1.2.3 From a9c9c70e3422ae673c7f95d0bc25bbdaf4e10576 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:11 +0900 Subject: ko_KR/HOWTO: Fix a typo: s/Linux Torvalds/Linus Torvalds Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet --- Documentation/ko_KR/HOWTO | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index 025252731af5..4f5778dfeed2 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -231,7 +231,7 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H 4.x 커널 트리 --------------- -4.x 커널들은 Linux Torvalds가 관리하며 kernel.org의 pub/linux/kernel/v4.x/ +4.x 커널들은 Linus Torvalds가 관리하며 kernel.org의 pub/linux/kernel/v4.x/ 디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다. - 새로운 커널이 배포되자마자 2주의 시간이 주어진다. 이 기간동은 메인테이너들은 큰 diff들을 Linus에게 제출할 수 있다. 대개 이 패치들은 -- cgit v1.2.3 From a9fb9356af8120db6f10d061ed70382ed8a161f0 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:12 +0900 Subject: ko_KR/HOWTO: Fix subtitles style This commit fixes subtitles style. It aligns them with their header, adjust blank lines between them properly. Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet --- Documentation/ko_KR/HOWTO | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index 4f5778dfeed2..1a5d7a8d66be 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -229,8 +229,7 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H - 4.x - 통합 테스트를 위한 next 커널 트리 4.x 커널 트리 ---------------- - +------------- 4.x 커널들은 Linus Torvalds가 관리하며 kernel.org의 pub/linux/kernel/v4.x/ 디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다. - 새로운 커널이 배포되자마자 2주의 시간이 주어진다. 이 기간동은 @@ -261,8 +260,7 @@ Andrew Morton의 글이 있다. 배포되는 것은 아니기 때문이다." 4.x.y - 안정 커널 트리 ------------------------- - +---------------------- 3 자리 숫자로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 4.x 커널에서 발견된 큰 회귀들이나 보안 문제들 중 비교적 작고 중요한 수정들을 포함한다. @@ -280,9 +278,8 @@ Andrew Morton의 글이 있다. 종류의 변경들이 -stable 트리로 들어왔는지와 배포 프로세스가 어떻게 진행되는지를 설명한다. - 4.x -git 패치들 ------------------- +--------------- git 저장소(그러므로 -git이라는 이름이 붙음)에는 날마다 관리되는 Linus의 커널 트리의 snapshot 들이 있다. 이 패치들은 일반적으로 날마다 배포되며 Linus의 트리의 현재 상태를 나타낸다. 이 패치들은 정상적인지 조금도 @@ -311,7 +308,7 @@ Linus의 트리의 현재 상태를 나타낸다. 이 패치들은 정상적인 http://patchwork.ozlabs.org/ 에 나열되어 있다. 4.x - 통합 테스트를 위한 next 커널 트리 ------------------------------------------ +--------------------------------------- 서브시스템 트리들의 변경사항들은 mainline 4.x 트리로 들어오기 전에 통합 테스트를 거쳐야 한다. 이런 목적으로, 모든 서브시스템 트리의 변경사항을 거의 매일 받아가는 특수한 테스트 저장소가 존재한다: @@ -321,8 +318,10 @@ http://patchwork.ozlabs.org/ 에 나열되어 있다. 가해질 것인지 간략히 알 수 있다. 모험심 강한 테스터라면 -next 커널에서 테스트를 수행하는 것도 좋을 것이다. + 버그 보고 --------- + bugzilla.kernel.org는 리눅스 커널 개발자들이 커널의 버그를 추적하는 곳이다. 사용자들은 발견한 모든 버그들을 보고하기 위하여 이 툴을 사용할 것을 권장한다. kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라. @@ -405,7 +404,7 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메 커뮤니티와 협력하는 법 --------------------- +---------------------- 커널 커뮤니티의 목적은 가능한한 가장 좋은 커널을 제공하는 것이다. 여러분이 받아들여질 패치를 제출하게 되면 그 패치의 기술적인 이점으로 검토될 것이다. @@ -443,7 +442,7 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메 커널 커뮤니티와 기업 조직간의 차이점 ------------------------------------------------------------------ +------------------------------------ 커널 커뮤니티는 가장 전통적인 회사의 개발 환경과는 다르다. 여기에 여러분들의 문제를 피하기 위한 목록이 있다. 여러분들이 제안한 변경들에 관하여 말할 때 좋은 것들 : -- cgit v1.2.3 From d7e81bfd55810bac093b478e9d7bdb2faf4cd997 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:13 +0900 Subject: ko_KR/HOWTO: Update obsolete link to bugzilla faq Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet --- Documentation/ko_KR/HOWTO | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index 1a5d7a8d66be..f3348ef68bbd 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -325,7 +325,7 @@ http://patchwork.ozlabs.org/ 에 나열되어 있다. bugzilla.kernel.org는 리눅스 커널 개발자들이 커널의 버그를 추적하는 곳이다. 사용자들은 발견한 모든 버그들을 보고하기 위하여 이 툴을 사용할 것을 권장한다. kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라. - http://test.kernel.org/bugzilla/faq.html + http://bugzilla.kernel.org/page.cgi?id=faq.html 메인 커널 소스 디렉토리에 있는 admin-guide/reporting-bugs.rst 파일은 커널 버그라고 생각되는 것을 보고하는 방법에 관한 좋은 템플릿이며 문제를 추적하기 위해서 커널 -- cgit v1.2.3 From 1c9feddacdfaf27bcef94ae691420a302b7f0a8e Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:14 +0900 Subject: ko_KR/HOWTO: Convert to ReST notation This commit applies commit 022e04d6f555 ("Documentation/HOWTO: convert to ReST notation") to Korean translation and fix a trivial ReST build failure problem. Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet --- Documentation/ko_KR/HOWTO | 55 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 52 insertions(+), 3 deletions(-) diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index f3348ef68bbd..c2a3f1719753 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -9,17 +9,20 @@ read for non English (read: korean) speakers and is not intended as a fork. So if you have any comments or updates for this file please try to update the original English file first. -================================== +---------------------------------- + 이 문서는 Documentation/process/howto.rst 의 한글 번역입니다. 역자： 김민찬 감수： 이제이미 -================================== + +---------------------------------- + 어떻게 리눅스 커널 개발을 하는가 ---------------------------------- +================================ 이 문서는 커널 개발에 있어 가장 중요한 문서이다. 이 문서는 리눅스 커널 개발자가 되는 법과 리눅스 커널 개발 커뮤니티와 일하는 @@ -46,6 +49,7 @@ Documentation/process/howto.rst 어셈블리(특정 아키텍쳐)는 잘 알아야 할 필요는 없다. 다음의 참고서적들은 기본에 충실한 C 교육이나 수년간의 경험에 견주지는 못하지만 적어도 참고 용도로는 좋을 것이다 + - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall] - "Practical C Programming" by Steve Oualline [O'Reilly] - "C: A Reference Manual" by Harbison and Steele [Prentice Hall] @@ -79,6 +83,7 @@ Documentation/process/howto.rst 그들의 말에 의지해서는 안된다. GPL에 관한 잦은 질문들과 답변들은 다음을 참조하라. + http://www.gnu.org/licenses/gpl-faq.html @@ -93,6 +98,7 @@ GPL에 관한 잦은 질문들과 답변들은 다음을 참조하라. mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. 다음은 커널 소스 트리에 있는 읽어야 할 파일들의 리스트이다. + README 이 파일은 리눅스 커널에 관하여 간단한 배경 설명과 커널을 설정하고 빌드하기 위해 필요한 것을 설명한다. 커널에 입문하는 사람들은 여기서 @@ -112,26 +118,34 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. Documentation/process/submitting-drivers.rst 이 파일들은 성공적으로 패치를 만들고 보내는 법을 다음의 내용들로 굉장히 상세히 설명하고 있다(그러나 다음으로 한정되진 않는다). + - Email 내용들 - Email 양식 - 그것을 누구에게 보낼지 + 이러한 규칙들을 따르는 것이 성공(역자주: 패치가 받아들여 지는 것)을 보장하진 않는다(왜냐하면 모든 패치들은 내용과 스타일에 관하여 면밀히 검토되기 때문이다). 그러나 규칙을 따르지 않는다면 거의 성공하지도 못할 것이다. 올바른 패치들을 만드는 법에 관한 훌륭한 다른 문서들이 있다. + "The Perfect Patch" + http://www.ozlabs.org/~akpm/stuff/tpp.txt + "Linux kernel patch submission format" + http://linux.yyz.us/patch-format.html Documentation/process/stable-api-nonsense.rst 이 문서는 의도적으로 커널이 불변하는 API를 갖지 않도록 결정한 이유를 설명하며 다음과 같은 것들을 포함한다. + - 서브시스템 shim-layer(호환성을 위해?) - 운영체제들간의 드라이버 이식성 - 커널 소스 트리내에 빠른 변화를 늦추는 것(또는 빠른 변화를 막는 것) + 이 문서는 리눅스 개발 철학을 이해하는데 필수적이며 다른 운영체제에서 리눅스로 전향하는 사람들에게는 매우 중요하다. @@ -168,10 +182,14 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. 올바르게 처리하는 법에 관한 규칙을 포함하고 있다. 이 문서는 Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, HTML, 그리고 man 페이지들로 다음과 같이 실행하여 만들어 진다. + +:: + make pdfdocs make psdocs make htmldocs make mandocs + 각각의 명령을 메인 커널 소스 디렉토리로부터 실행한다. @@ -180,7 +198,9 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H 여러분이 리눅스 커널 개발에 관하여 아무것도 모른다면 Linux KernelNewbies 프로젝트를 봐야 한다. + http://kernelnewbies.org + 그곳은 거의 모든 종류의 기본적인 커널 개발 질문들(질문하기 전에 먼저 아카이브를 찾아봐라. 과거에 이미 답변되었을 수도 있다)을 할 수 있는 도움이 될만한 메일링 리스트가 있다. 또한 실시간으로 질문 할 수 있는 IRC 채널도 @@ -192,7 +212,9 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H 여러분이 어디서 시작해야 할진 모르지만 커널 개발 커뮤니티에 참여할 수 있는 일들을 찾길 원한다면 리눅스 커널 Janitor 프로젝트를 살펴봐라. + http://kernelnewbies.org/KernelJanitors + 그곳은 시작하기에 훌륭한 장소이다. 그곳은 리눅스 커널 소스 트리내에 간단히 정리되고 수정될 수 있는 문제들에 관하여 설명한다. 여러분은 이 프로젝트를 대표하는 개발자들과 일하면서 자신의 패치를 리눅스 커널 트리에 @@ -204,6 +226,7 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H 올바른 포맷으로 포장하는데 도움이 필요하다면 그러한 문제를 돕기 위해 만들어진 kernel-mentors 프로젝트가 있다. 그곳은 메일링 리스트이며 다음에서 참조할 수 있다. + http://selenic.com/mailman/listinfo/kernel-mentors 리눅스 커널 코드에 실제 변경을 하기 전에 반드시 그 코드가 어떻게 @@ -213,6 +236,7 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H 것은 Linux Cross-Reference project이며 그것은 자기 참조 방식이며 소스코드를 인덱스된 웹 페이지들의 형태로 보여준다. 최신의 멋진 커널 코드 저장소는 다음을 통하여 참조할 수 있다. + http://lxr.free-electrons.com/ @@ -222,6 +246,7 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H 리눅스 커널 개발 프로세스는 현재 몇몇 다른 메인 커널 "브랜치들"과 서브시스템에 특화된 커널 브랜치들로 구성된다. 몇몇 다른 메인 브랜치들은 다음과 같다. + - main 4.x 커널 트리 - 4.x.y - 안정된 커널 트리 - 4.x -git 커널 패치들 @@ -232,6 +257,7 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H ------------- 4.x 커널들은 Linus Torvalds가 관리하며 kernel.org의 pub/linux/kernel/v4.x/ 디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다. + - 새로운 커널이 배포되자마자 2주의 시간이 주어진다. 이 기간동은 메인테이너들은 큰 diff들을 Linus에게 제출할 수 있다. 대개 이 패치들은 몇 주 동안 -next 커널내에 이미 있었던 것들이다. 큰 변경들을 제출하는 데 @@ -255,6 +281,9 @@ Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, H 커널 배포에 있어서 언급할만한 가치가 있는 리눅스 커널 메일링 리스트의 Andrew Morton의 글이 있다. + +:: + "커널이 언제 배포될지는 아무도 모른다. 왜냐하면 배포는 알려진 버그의 상황에 따라 배포되는 것이지 미리정해 놓은 시간에 따라 배포되는 것은 아니기 때문이다." @@ -312,6 +341,7 @@ http://patchwork.ozlabs.org/ 에 나열되어 있다. 서브시스템 트리들의 변경사항들은 mainline 4.x 트리로 들어오기 전에 통합 테스트를 거쳐야 한다. 이런 목적으로, 모든 서브시스템 트리의 변경사항을 거의 매일 받아가는 특수한 테스트 저장소가 존재한다: + http://git.kernel.org/?p=linux/kernel/git/sfr/linux-next.git 이런 식으로, -next 커널을 통해 다음 머지 기간에 메인라인 커널에 어떤 변경이 @@ -325,6 +355,7 @@ http://patchwork.ozlabs.org/ 에 나열되어 있다. bugzilla.kernel.org는 리눅스 커널 개발자들이 커널의 버그를 추적하는 곳이다. 사용자들은 발견한 모든 버그들을 보고하기 위하여 이 툴을 사용할 것을 권장한다. kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라. + http://bugzilla.kernel.org/page.cgi?id=faq.html 메인 커널 소스 디렉토리에 있는 admin-guide/reporting-bugs.rst 파일은 커널 버그라고 생각되는 @@ -360,10 +391,14 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메 위의 몇몇 문서들이 설명하였지만 핵심 커널 개발자들의 대다수는 리눅스 커널 메일링 리스트에 참여하고 있다. 리스트에 등록하고 해지하는 방법에 관한 자세한 사항은 다음에서 참조할 수 있다. + http://vger.kernel.org/vger-lists.html#linux-kernel + 웹상의 많은 다른 곳에도 메일링 리스트의 아카이브들이 있다. 이러한 아카이브들을 찾으려면 검색 엔진을 사용하라. 예를 들어: + http://dir.gmane.org/gmane.linux.kernel + 여러분이 새로운 문제에 관해 리스트에 올리기 전에 말하고 싶은 주제에 관한 것을 아카이브에서 먼저 찾아보기를 강력히 권장한다. 이미 상세하게 토론된 많은 것들이 메일링 리스트의 아카이브에 기록되어 있다. @@ -373,11 +408,13 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메 있는지는 MAINTAINERS 파일을 참조하라. 많은 리스트들은 kernel.org에서 호스트되고 있다. 그 정보들은 다음에서 참조될 수 있다. + http://vger.kernel.org/vger-lists.html 리스트들을 사용할 때는 올바른 예절을 따를 것을 유념해라. 대단하진 않지만 다음 URL은 리스트(혹은 모든 리스트)와 대화하는 몇몇 간단한 가이드라인을 가지고 있다. + http://www.albion.com/netiquette/ 여러 사람들이 여러분의 메일에 응답한다면 CC: 즉 수신 리스트는 꽤 커지게 @@ -409,6 +446,7 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메 커널 커뮤니티의 목적은 가능한한 가장 좋은 커널을 제공하는 것이다. 여러분이 받아들여질 패치를 제출하게 되면 그 패치의 기술적인 이점으로 검토될 것이다. 그럼 여러분들은 무엇을 기대하고 있어야 하는가? + - 비판 - 의견 - 변경을 위한 요구 @@ -422,6 +460,7 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메 기다려보고 다시 시도해라. 때론 너무 많은 메일들 속에 묻혀버리기도 한다. 여러분은 무엇을 해서는 안되는가? + - 여러분의 패치가 아무 질문 없이 받아들여지기를 기대하는 것 - 방어적이 되는 것 - 의견을 무시하는 것 @@ -445,7 +484,9 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메 ------------------------------------ 커널 커뮤니티는 가장 전통적인 회사의 개발 환경과는 다르다. 여기에 여러분들의 문제를 피하기 위한 목록이 있다. + 여러분들이 제안한 변경들에 관하여 말할 때 좋은 것들 : + - "이것은 여러 문제들을 해결합니다." - "이것은 2000 라인의 코드를 줄입니다." - "이것은 내가 말하려는 것에 관해 설명하는 패치입니다." @@ -454,6 +495,7 @@ bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메 - "이것은 일반적인 머신에서 성능을 향상함으로..." 여러분들이 말할 때 피해야 할 좋지 않은 것들 : + - "우리는 그것을 AIX/ptx/Solaris에서 이러한 방법으로 했다. 그러므로 그것은 좋은 것임에 틀림없다..." - "나는 20년동안 이것을 해왔다. 그러므로..." - "이것은 돈을 벌기위해 나의 회사가 필요로 하는 것이다." @@ -513,6 +555,9 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅 간단하게(혹은 간단한게 재배치하여) 하는 것도 중요하다. 여기에 커널 개발자 Al Viro의 이야기가 있다. + +:: + "학생의 수학 숙제를 채점하는 선생님을 생각해보라. 선생님은 학생들이 답을 얻을때까지 겪은 시행착오를 보길 원하지 않는다. 선생님들은 간결하고 가장 뛰어난 답을 보길 원한다. 훌륭한 학생은 이것을 알고 @@ -548,13 +593,16 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅 생각하여 이메일을 작성해야 한다. 이 정보는 패치를 위한 ChangeLog가 될 것이다. 그리고 항상 그 내용을 보길 원하는 모든 사람들을 위해 보존될 것이다. 패치는 완벽하게 다음과 같은 내용들을 포함하여 설명해야 한다. + - 변경이 왜 필요한지 - 패치에 관한 전체 설계 접근(approach) - 구현 상세들 - 테스트 결과들 이것이 무엇인지 더 자세한 것을 알고 싶다면 다음 문서의 ChageLog 항을 봐라. + "The Perfect Patch" + http://www.ozlabs.org/~akpm/stuff/tpp.txt @@ -569,6 +617,7 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅 ---------- + "개발 프로세스"(http://lwn.net/Articles/94386/) 섹션을 작성하는데 있어 참고할 문서를 사용하도록 허락해준 Paolo Ciarrocchi에게 감사한다. 여러분들이 말해야 할 것과 말해서는 안되는 것의 목록 중 일부를 제공해준 -- cgit v1.2.3 From ae8fc192811f206cc136ffffcf8229ea380edf15 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:15 +0900 Subject: ko_KR/HOWTO: Add cross-references to other documents This commit applies commit 609d99a3b72e ("Documentation/HOWTO: add cross-references to other documents") to Korean translation. Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet --- Documentation/ko_KR/HOWTO | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index c2a3f1719753..7f0b4e66e6c2 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -104,18 +104,17 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. 빌드하기 위해 필요한 것을 설명한다. 커널에 입문하는 사람들은 여기서 시작해야 한다. - Documentation/process/changes.rst + :ref:`Documentation/process/changes.rst ` 이 파일은 커널을 성공적으로 빌드하고 실행시키기 위해 필요한 다양한 소프트웨어 패키지들의 최소 버젼을 나열한다. - Documentation/process/coding-style.rst + :ref:`Documentation/process/coding-style.rst ` 이 문서는 리눅스 커널 코딩 스타일과 그렇게 한 몇몇 이유를 설명한다. 모든 새로운 코드는 이 문서에 가이드라인들을 따라야 한다. 대부분의 메인테이너들은 이 규칙을 따르는 패치들만을 받아들일 것이고 많은 사람들이 그 패치가 올바른 스타일일 경우만 코드를 검토할 것이다. - Documentation/process/submitting-patches.rst - Documentation/process/submitting-drivers.rst + :ref:`Documentation/process/submitting-patches.rst ` 와 :ref:`Documentation/process/submitting-drivers.rst ` 이 파일들은 성공적으로 패치를 만들고 보내는 법을 다음의 내용들로 굉장히 상세히 설명하고 있다(그러나 다음으로 한정되진 않는다). @@ -138,7 +137,7 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. http://linux.yyz.us/patch-format.html - Documentation/process/stable-api-nonsense.rst + :ref:`Documentation/process/stable-api-nonsense.rst ` 이 문서는 의도적으로 커널이 불변하는 API를 갖지 않도록 결정한 이유를 설명하며 다음과 같은 것들을 포함한다. @@ -150,12 +149,12 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. 리눅스로 전향하는 사람들에게는 매우 중요하다. - Documentation/admin-guide/security-bugs.rst + :ref:`Documentation/admin-guide/security-bugs.rst ` 여러분들이 리눅스 커널의 보안 문제를 발견했다고 생각한다면 이 문서에 나온 단계에 따라서 커널 개발자들에게 알리고 그 문제를 해결할 수 있도록 도와 달라. - Documentation/process/management-style.rst + :ref:`Documentation/process/management-style.rst ` 이 문서는 리눅스 커널 메인테이너들이 그들의 방법론에 녹아 있는 정신을 어떻게 공유하고 운영하는지를 설명한다. 이것은 커널 개발에 입문하는 모든 사람들(또는 커널 개발에 작은 호기심이라도 있는 사람들)이 @@ -163,17 +162,17 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. 독특한 행동에 관하여 흔히 있는 오해들과 혼란들을 해소하고 있기 때문이다. - Documentation/process/stable-kernel-rules.rst + :ref:`Documentation/process/stable_kernel_rules.rst ` 이 문서는 안정적인 커널 배포가 이루어지는 규칙을 설명하고 있으며 여러분들이 이러한 배포들 중 하나에 변경을 하길 원한다면 무엇을 해야 하는지를 설명한다. - Documentation/process/kernel-docs.rst + :ref:`Documentation/process/kernel-docs.rst ` 커널 개발에 관계된 외부 문서의 리스트이다. 커널 내의 포함된 문서들 중에 여러분이 찾고 싶은 문서를 발견하지 못할 경우 이 리스트를 살펴보라. - Documentation/process/applying-patches.rst + :ref:`Documentation/process/applying-patches.rst ` 패치가 무엇이며 그것을 커널의 다른 개발 브랜치들에 어떻게 적용하는지에 관하여 자세히 설명하고 있는 좋은 입문서이다. -- cgit v1.2.3 From 48fe44ccf311fb68eba235eed9358559e893d2f5 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:16 +0900 Subject: ko_KR/HOWTO: Update information about generating documentation This commit applies commit 43fb67a5258c ("Documentation/HOWTO: update information about generating documentation") to Korean translation. Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet --- Documentation/ko_KR/HOWTO | 30 ++++++++++++++++++++++-------- 1 file changed, 22 insertions(+), 8 deletions(-) diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index 7f0b4e66e6c2..918be41b75de 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -176,21 +176,35 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. 패치가 무엇이며 그것을 커널의 다른 개발 브랜치들에 어떻게 적용하는지에 관하여 자세히 설명하고 있는 좋은 입문서이다. -커널은 소스 코드 그 자체에서 자동적으로 만들어질 수 있는 많은 문서들을 -가지고 있다. 이것은 커널 내의 API에 대한 모든 설명, 그리고 락킹을 -올바르게 처리하는 법에 관한 규칙을 포함하고 있다. 이 문서는 -Documentation/DocBook/ 디렉토리 내에서 만들어지며 PDF, Postscript, HTML, -그리고 man 페이지들로 다음과 같이 실행하여 만들어 진다. +커널은 소스 코드 그 자체에서 또는 이것과 같은 ReStructuredText 마크업 (ReST) 을 +통해 자동적으로 만들어질 수 있는 많은 문서들을 가지고 있다. 이것은 커널 내의 +API에 대한 모든 설명, 그리고 락킹을 올바르게 처리하는 법에 관한 규칙을 포함하고 +있다. + +모든 그런 문서들은 커널 소스 디렉토리에서 다음 커맨드를 실행하는 것을 통해 PDF +나 HTML 의 형태로 만들어질 수 있다. :: make pdfdocs - make psdocs make htmldocs - make mandocs -각각의 명령을 메인 커널 소스 디렉토리로부터 실행한다. +ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된다. 해당 +문서들은 다음의 커맨드를 사용하면 LaTeX 이나 ePub 로도 만들어질 수 있다: + +:: + + make latexdocs + make epubdocs + +현재, ReST 로의 변환이 진행중인, DocBook 으로 쓰인 문서들이 존재한다. 그런 +문서들은 Documentation/DocBook/ 디렉토리 안에 생성될 것이고 다음 커맨드를 통해 +Postscript 나 man page 로도 만들어질 수 있다: + +:: + make psdocs + make mandocs 커널 개발자가 되는 것 --------------------- -- cgit v1.2.3 From 80f0fceb4fc78c2cc6830dc707af51ac285bd8aa Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:17 +0900 Subject: ko_KR/HOWTO: Improve some markups to make it visually better This commit applies commit 34fed7e7e0e5 ("Documentation/HOWTO: improve some markups to make it visually better") to Korean translation. Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet --- Documentation/ko_KR/HOWTO | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index 918be41b75de..4df8ef3d0ffe 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -295,11 +295,9 @@ Postscript 나 man page 로도 만들어질 수 있다: 커널 배포에 있어서 언급할만한 가치가 있는 리눅스 커널 메일링 리스트의 Andrew Morton의 글이 있다. -:: - - "커널이 언제 배포될지는 아무도 모른다. 왜냐하면 배포는 알려진 + *"커널이 언제 배포될지는 아무도 모른다. 왜냐하면 배포는 알려진 버그의 상황에 따라 배포되는 것이지 미리정해 놓은 시간에 따라 - 배포되는 것은 아니기 때문이다." + 배포되는 것은 아니기 때문이다."* 4.x.y - 안정 커널 트리 ---------------------- @@ -569,16 +567,14 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅 여기에 커널 개발자 Al Viro의 이야기가 있다. -:: - - "학생의 수학 숙제를 채점하는 선생님을 생각해보라. 선생님은 학생들이 + *"학생의 수학 숙제를 채점하는 선생님을 생각해보라. 선생님은 학생들이 답을 얻을때까지 겪은 시행착오를 보길 원하지 않는다. 선생님들은 간결하고 가장 뛰어난 답을 보길 원한다. 훌륭한 학생은 이것을 알고 - 마지막으로 답을 얻기 전 중간 과정들을 제출하진 않는다. + 마지막으로 답을 얻기 전 중간 과정들을 제출하진 않는다.* - 커널 개발도 마찬가지이다. 메인테이너들과 검토하는 사람들은 문제를 + *커널 개발도 마찬가지이다. 메인테이너들과 검토하는 사람들은 문제를 풀어나가는 과정속에 숨겨진 과정을 보길 원하진 않는다. 그들은 - 간결하고 멋진 답을 보길 원한다." + 간결하고 멋진 답을 보길 원한다."* 커뮤니티와 협력하며 뛰어난 답을 찾는 것과 여러분들의 끝마치지 못한 작업들 사이에 균형을 유지해야 하는 것은 어려울지도 모른다. 그러므로 프로세스의 -- cgit v1.2.3 From a1456a7303bbcca1e5e0dbe91927bd6efd5d97fd Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:18 +0900 Subject: ko_KR/HOWTO: Adjust external link references This commit appplies commit f1eebe92c265 ("Documentation/HOWTO: adjust external link references") to Korean translation. Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet --- Documentation/ko_KR/HOWTO | 39 ++++++++++++++++++--------------------- 1 file changed, 18 insertions(+), 21 deletions(-) diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index 4df8ef3d0ffe..8f3a1a68758d 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -84,7 +84,7 @@ Documentation/process/howto.rst GPL에 관한 잦은 질문들과 답변들은 다음을 참조하라. - http://www.gnu.org/licenses/gpl-faq.html + https://www.gnu.org/licenses/gpl-faq.html 문서 @@ -130,11 +130,9 @@ mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다. 올바른 패치들을 만드는 법에 관한 훌륭한 다른 문서들이 있다. "The Perfect Patch" - - http://www.ozlabs.org/~akpm/stuff/tpp.txt + https://www.ozlabs.org/~akpm/stuff/tpp.txt "Linux kernel patch submission format" - http://linux.yyz.us/patch-format.html :ref:`Documentation/process/stable-api-nonsense.rst ` @@ -212,7 +210,7 @@ Postscript 나 man page 로도 만들어질 수 있다: 여러분이 리눅스 커널 개발에 관하여 아무것도 모른다면 Linux KernelNewbies 프로젝트를 봐야 한다. - http://kernelnewbies.org + https://kernelnewbies.org 그곳은 거의 모든 종류의 기본적인 커널 개발 질문들(질문하기 전에 먼저 아카이브를 찾아봐라. 과거에 이미 답변되었을 수도 있다)을 할 수 있는 도움이 @@ -226,7 +224,7 @@ Postscript 나 man page 로도 만들어질 수 있다: 여러분이 어디서 시작해야 할진 모르지만 커널 개발 커뮤니티에 참여할 수 있는 일들을 찾길 원한다면 리눅스 커널 Janitor 프로젝트를 살펴봐라. - http://kernelnewbies.org/KernelJanitors + https://kernelnewbies.org/KernelJanitors 그곳은 시작하기에 훌륭한 장소이다. 그곳은 리눅스 커널 소스 트리내에 간단히 정리되고 수정될 수 있는 문제들에 관하여 설명한다. 여러분은 이 @@ -240,7 +238,7 @@ Postscript 나 man page 로도 만들어질 수 있다: 만들어진 kernel-mentors 프로젝트가 있다. 그곳은 메일링 리스트이며 다음에서 참조할 수 있다. - http://selenic.com/mailman/listinfo/kernel-mentors + https://selenic.com/mailman/listinfo/kernel-mentors 리눅스 커널 코드에 실제 변경을 하기 전에 반드시 그 코드가 어떻게 동작하는지 이해하고 있어야 한다. 코드를 분석하기 위하여 특정한 툴의 @@ -268,14 +266,14 @@ Postscript 나 man page 로도 만들어질 수 있다: 4.x 커널 트리 ------------- -4.x 커널들은 Linus Torvalds가 관리하며 kernel.org의 pub/linux/kernel/v4.x/ -디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다. +4.x 커널들은 Linus Torvalds가 관리하며 https://kernel.org의 +pub/linux/kernel/v4.x/ 디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다. - 새로운 커널이 배포되자마자 2주의 시간이 주어진다. 이 기간동은 메인테이너들은 큰 diff들을 Linus에게 제출할 수 있다. 대개 이 패치들은 몇 주 동안 -next 커널내에 이미 있었던 것들이다. 큰 변경들을 제출하는 데 선호되는 방법은 git(커널의 소스 관리 툴, 더 많은 정보들은 - http://git-scm.com/ 에서 참조할 수 있다)를 사용하는 것이지만 순수한 + https://git-scm.com/ 에서 참조할 수 있다)를 사용하는 것이지만 순수한 패치파일의 형식으로 보내는 것도 무관하다. - 2주 후에 -rc1 커널이 배포되며 지금부터는 전체 커널의 안정성에 영향을 미칠수 있는 새로운 기능들을 포함하지 않는 패치들만이 추가될 수 있다. @@ -337,14 +335,14 @@ Linus의 트리의 현재 상태를 나타낸다. 이 패치들은 정상적인 대부분의 이러한 저장소는 git 트리지만, git이 아닌 SCM으로 관리되거나, quilt 시리즈로 제공되는 패치들도 존재한다. 이러한 서브시스템 저장소들은 MAINTAINERS -파일에 나열되어 있다. 대부분은 http://git.kernel.org 에서 볼 수 있다. +파일에 나열되어 있다. 대부분은 https://git.kernel.org 에서 볼 수 있다. 제안된 패치는 서브시스템 트리에 커밋되기 전에 메일링 리스트를 통해 리뷰된다(아래의 관련 섹션을 참고하기 바란다). 일부 커널 서브시스템의 경우, 이 리뷰 프로세스는 patchwork라는 도구를 통해 추적된다. patchwork은 등록된 패치와 패치에 대한 코멘트, 패치의 버전을 볼 수 있는 웹 인터페이스를 제공하고, 메인테이너는 패치를 리뷰 중, 리뷰 통과, 또는 반려됨으로 표시할 수 있다. -대부분의 이러한 patchwork 사이트는 http://patchwork.kernel.org/ 또는 +대부분의 이러한 patchwork 사이트는 https://patchwork.kernel.org/ 또는 http://patchwork.ozlabs.org/ 에 나열되어 있다. 4.x - 통합 테스트를 위한 next 커널 트리 @@ -353,7 +351,7 @@ http://patchwork.ozlabs.org/ 에 나열되어 있다. 테스트를 거쳐야 한다. 이런 목적으로, 모든 서브시스템 트리의 변경사항을 거의 매일 받아가는 특수한 테스트 저장소가 존재한다: - http://git.kernel.org/?p=linux/kernel/git/sfr/linux-next.git + https://git.kernel.org/?p=linux/kernel/git/sfr/linux-next.git 이런 식으로, -next 커널을 통해 다음 머지 기간에 메인라인 커널에 어떤 변경이 가해질 것인지 간략히 알 수 있다. 모험심 강한 테스터라면 -next 커널에서 테스트를 @@ -363,11 +361,11 @@ http://patchwork.ozlabs.org/ 에 나열되어 있다. 버그 보고 --------- -bugzilla.kernel.org는 리눅스 커널 개발자들이 커널의 버그를 추적하는 곳이다. -사용자들은 발견한 모든 버그들을 보고하기 위하여 이 툴을 사용할 것을 권장한다. -kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라. +https://bugzilla.kernel.org는 리눅스 커널 개발자들이 커널의 버그를 추적하는 +곳이다. 사용자들은 발견한 모든 버그들을 보고하기 위하여 이 툴을 사용할 것을 +권장한다. kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라. - http://bugzilla.kernel.org/page.cgi?id=faq.html + https://bugzilla.kernel.org/page.cgi?id=faq.html 메인 커널 소스 디렉토리에 있는 admin-guide/reporting-bugs.rst 파일은 커널 버그라고 생각되는 것을 보고하는 방법에 관한 좋은 템플릿이며 문제를 추적하기 위해서 커널 @@ -385,13 +383,14 @@ kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라. 점수를 얻을 수 있는 가장 좋은 방법중의 하나이다. 왜냐하면 많은 사람들은 다른 사람들의 버그들을 수정하기 위하여 시간을 낭비하지 않기 때문이다. -이미 보고된 버그 리포트들을 가지고 작업하기 위해서 http://bugzilla.kernel.org를 +이미 보고된 버그 리포트들을 가지고 작업하기 위해서 https://bugzilla.kernel.org를 참조하라. 여러분이 앞으로 생겨날 버그 리포트들의 조언자가 되길 원한다면 bugme-new 메일링 리스트나(새로운 버그 리포트들만이 이곳에서 메일로 전해진다) bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메일로 전해진다) 에 등록하면 된다. https://lists.linux-foundation.org/mailman/listinfo/bugme-new + https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors @@ -615,8 +614,6 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅 http://www.ozlabs.org/~akpm/stuff/tpp.txt - - 이 모든 것을 하는 것은 매우 어려운 일이다. 완벽히 소화하는 데는 적어도 몇년이 걸릴 수도 있다. 많은 인내와 결심이 필요한 계속되는 개선의 과정이다. 그러나 가능한한 포기하지 말라. 많은 사람들은 이전부터 해왔던 것이고 그 사람들도 @@ -627,7 +624,7 @@ Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅 ---------- -"개발 프로세스"(http://lwn.net/Articles/94386/) 섹션을 +"개발 프로세스"(https://lwn.net/Articles/94386/) 섹션을 작성하는데 있어 참고할 문서를 사용하도록 허락해준 Paolo Ciarrocchi에게 감사한다. 여러분들이 말해야 할 것과 말해서는 안되는 것의 목록 중 일부를 제공해준 Randy Dunlap과 Gerrit Huizenga에게 감사한다. 또한 검토와 의견 그리고 -- cgit v1.2.3 From 602facb35b065f59ddfafe194c1ca8c9a013ddde Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:19 +0900 Subject: ko_KR/HOWTO: Clean up bare :: lines This commit applies commit 1b49ecf2f3be ("docs: Clean up bare :: lines") to Korean translation. Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet --- Documentation/ko_KR/HOWTO | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index 8f3a1a68758d..2a91ebd8391f 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -180,26 +180,20 @@ API에 대한 모든 설명, 그리고 락킹을 올바르게 처리하는 법 있다. 모든 그런 문서들은 커널 소스 디렉토리에서 다음 커맨드를 실행하는 것을 통해 PDF -나 HTML 의 형태로 만들어질 수 있다. - -:: +나 HTML 의 형태로 만들어질 수 있다:: make pdfdocs make htmldocs ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된다. 해당 -문서들은 다음의 커맨드를 사용하면 LaTeX 이나 ePub 로도 만들어질 수 있다: - -:: +문서들은 다음의 커맨드를 사용하면 LaTeX 이나 ePub 로도 만들어질 수 있다:: make latexdocs make epubdocs 현재, ReST 로의 변환이 진행중인, DocBook 으로 쓰인 문서들이 존재한다. 그런 문서들은 Documentation/DocBook/ 디렉토리 안에 생성될 것이고 다음 커맨드를 통해 -Postscript 나 man page 로도 만들어질 수 있다: - -:: +Postscript 나 man page 로도 만들어질 수 있다:: make psdocs make mandocs -- cgit v1.2.3 From 15c467f981828cde5be50ca13aeba70bf64bfee4 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:20 +0900 Subject: ko_KR/HOWTO: Add whitespace between URL and text Because few sentences has no whitespace between URL and text, few document viewers fail to properly parse the URL from it. This commit adds whitespace between them to fix the problem. Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet --- Documentation/ko_KR/HOWTO | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index 2a91ebd8391f..9aea302ed8c3 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -260,7 +260,7 @@ Postscript 나 man page 로도 만들어질 수 있다:: 4.x 커널 트리 ------------- -4.x 커널들은 Linus Torvalds가 관리하며 https://kernel.org의 +4.x 커널들은 Linus Torvalds가 관리하며 https://kernel.org 의 pub/linux/kernel/v4.x/ 디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다. - 새로운 커널이 배포되자마자 2주의 시간이 주어진다. 이 기간동은 @@ -377,8 +377,8 @@ https://bugzilla.kernel.org는 리눅스 커널 개발자들이 커널의 버그 점수를 얻을 수 있는 가장 좋은 방법중의 하나이다. 왜냐하면 많은 사람들은 다른 사람들의 버그들을 수정하기 위하여 시간을 낭비하지 않기 때문이다. -이미 보고된 버그 리포트들을 가지고 작업하기 위해서 https://bugzilla.kernel.org를 -참조하라. 여러분이 앞으로 생겨날 버그 리포트들의 조언자가 되길 원한다면 +이미 보고된 버그 리포트들을 가지고 작업하기 위해서 https://bugzilla.kernel.org +를 참조하라. 여러분이 앞으로 생겨날 버그 리포트들의 조언자가 되길 원한다면 bugme-new 메일링 리스트나(새로운 버그 리포트들만이 이곳에서 메일로 전해진다) bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메일로 전해진다) 에 등록하면 된다. -- cgit v1.2.3 From ac72618fc84da69337d692e9af41f9049fc3b6a2 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:21 +0900 Subject: ko_KR/HOWTO: Mark subsection in suggested format `Specific guidelines for the kernel documentation` section of `kernel-documentation.rst` suggests to use ``~`` for subsection but subsections in HOWTO is not marked in the format. This commit marks them in the format. Signed-off-by: SeongJae Park Signed-off-by: Jonathan Corbet --- Documentation/ko_KR/HOWTO | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO index 9aea302ed8c3..3b0c15b277e0 100644 --- a/Documentation/ko_KR/HOWTO +++ b/Documentation/ko_KR/HOWTO @@ -259,7 +259,8 @@ Postscript 나 man page 로도 만들어질 수 있다:: - 4.x - 통합 테스트를 위한 next 커널 트리 4.x 커널 트리 -------------- +~~~~~~~~~~~~~ + 4.x 커널들은 Linus Torvalds가 관리하며 https://kernel.org 의 pub/linux/kernel/v4.x/ 디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다. @@ -292,7 +293,8 @@ Andrew Morton의 글이 있다. 배포되는 것은 아니기 때문이다."* 4.x.y - 안정 커널 트리 ----------------------- +~~~~~~~~~~~~~~~~~~~~~~ + 3 자리 숫자로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 4.x 커널에서 발견된 큰 회귀들이나 보안 문제들 중 비교적 작고 중요한 수정들을 포함한다. @@ -311,14 +313,16 @@ Andrew Morton의 글이 있다. 진행되는지를 설명한다. 4.x -git 패치들 ---------------- +~~~~~~~~~~~~~~~ + git 저장소(그러므로 -git이라는 이름이 붙음)에는 날마다 관리되는 Linus의 커널 트리의 snapshot 들이 있다. 이 패치들은 일반적으로 날마다 배포되며 Linus의 트리의 현재 상태를 나타낸다. 이 패치들은 정상적인지 조금도 살펴보지 않고 자동적으로 생성된 것이므로 -rc 커널들 보다도 더 실험적이다. 서브시스템 커널 트리들과 패치들 -------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + 다양한 커널 서브시스템의 메인테이너들 --- 그리고 많은 커널 서브시스템 개발자들 --- 은 그들의 현재 개발 상태를 소스 저장소로 노출한다. 이를 통해 다른 사람들도 커널의 다른 영역에 어떤 변화가 이루어지고 있는지 알 수 있다. 급속히 개발이 -- cgit v1.2.3 From ca4354543a7d7f5a6ed50b01b42a61f1d42e725d Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 7 Nov 2016 18:03:13 -0700 Subject: docs: Fix a PDF build error in bug-bisect.rst It seems we can't have literal blocks in footnotes, which almost actually makes some sense. So just use basic ``monospace`` instead. Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/bug-bisect.rst | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/Documentation/admin-guide/bug-bisect.rst b/Documentation/admin-guide/bug-bisect.rst index 5682d742017c..59567da344e8 100644 --- a/Documentation/admin-guide/bug-bisect.rst +++ b/Documentation/admin-guide/bug-bisect.rst @@ -66,9 +66,7 @@ Steps to do it: .. [#f1] You can, optionally, provide both good and bad arguments at git - start:: - - git bisect start [BAD] [GOOD] + start with ``git bisect start [BAD] [GOOD]`` For further references, please read: -- cgit v1.2.3 From 78566cf137dab5682d00721d6f7277cedbc2635d Mon Sep 17 00:00:00 2001 From: Shuah Khan Date: Mon, 7 Nov 2016 13:24:14 -0700 Subject: Doc: update kselftest.txt with details on how to run tests after install Update kselftest.txt with details on how to run tests after install. Signed-off-by: Shuah Khan Signed-off-by: Jonathan Corbet --- Documentation/kselftest.txt | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/Documentation/kselftest.txt b/Documentation/kselftest.txt index 54bee77fa728..e5c7254e73d7 100644 --- a/Documentation/kselftest.txt +++ b/Documentation/kselftest.txt @@ -70,6 +70,17 @@ To install selftests in an user specified location: $ cd tools/testing/selftests $ ./kselftest_install.sh install_dir +Running installed selftests +=========================== + +Kselftest install as well as the Kselftest tarball provide a script +named "run_kselftest.sh" to run the tests. + +You can simply do the following to run the installed Kselftests. Please +note some tests will require root privileges. + +cd kselftest +./run_kselftest.sh Contributing new tests ====================== -- cgit v1.2.3 From 9e355ba76455d6d44f5cf888eee820ae9a06b3ec Mon Sep 17 00:00:00 2001 From: Jarkko Sakkinen Date: Thu, 3 Nov 2016 17:57:51 -0600 Subject: tpm: transition tpm_vtpm_proxy documentation to the Sphinx Transitioned the tpm_vtpm_proxy documentation to the Sphinx infrastructure and removed parts from the documentation that are easier to pull from the sources. Restructured vtpm_proxy.h and tpm_vtpm_proxy.c to be compatible with this approach and wrote associated documentation comments. Signed-off-by: Jarkko Sakkinen Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 1 + Documentation/tpm/index.rst | 7 ++++ Documentation/tpm/tpm_vtpm_proxy.rst | 50 +++++++++++++++++++++++++ Documentation/tpm/tpm_vtpm_proxy.txt | 71 ------------------------------------ 4 files changed, 58 insertions(+), 71 deletions(-) create mode 100644 Documentation/tpm/index.rst create mode 100644 Documentation/tpm/tpm_vtpm_proxy.rst delete mode 100644 Documentation/tpm/tpm_vtpm_proxy.txt diff --git a/Documentation/index.rst b/Documentation/index.rst index e0fc72963e87..0058b65d361c 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -19,6 +19,7 @@ Contents: media/dvb-drivers/index media/v4l-drivers/index gpu/index + tpm/index Indices and tables ================== diff --git a/Documentation/tpm/index.rst b/Documentation/tpm/index.rst new file mode 100644 index 000000000000..af77a7bbb070 --- /dev/null +++ b/Documentation/tpm/index.rst @@ -0,0 +1,7 @@ +===================================== +Trusted Platform Module documentation +===================================== + +.. toctree:: + + tpm_vtpm_proxy diff --git a/Documentation/tpm/tpm_vtpm_proxy.rst b/Documentation/tpm/tpm_vtpm_proxy.rst new file mode 100644 index 000000000000..ea08e76b17f5 --- /dev/null +++ b/Documentation/tpm/tpm_vtpm_proxy.rst @@ -0,0 +1,50 @@ +============================================= +Virtual TPM Proxy Driver for Linux Containers +============================================= + +| Authors: +| Stefan Berger + +This document describes the virtual Trusted Platform Module (vTPM) +proxy device driver for Linux containers. + +Introduction +============ + +The goal of this work is to provide TPM functionality to each Linux +container. This allows programs to interact with a TPM in a container +the same way they interact with a TPM on the physical system. Each +container gets its own unique, emulated, software TPM. + +Design +====== + +To make an emulated software TPM available to each container, the container +management stack needs to create a device pair consisting of a client TPM +character device ``/dev/tpmX`` (with X=0,1,2...) and a 'server side' file +descriptor. The former is moved into the container by creating a character +device with the appropriate major and minor numbers while the file descriptor +is passed to the TPM emulator. Software inside the container can then send +TPM commands using the character device and the emulator will receive the +commands via the file descriptor and use it for sending back responses. + +To support this, the virtual TPM proxy driver provides a device ``/dev/vtpmx`` +that is used to create device pairs using an ioctl. The ioctl takes as +an input flags for configuring the device. The flags for example indicate +whether TPM 1.2 or TPM 2 functionality is supported by the TPM emulator. +The result of the ioctl are the file descriptor for the 'server side' +as well as the major and minor numbers of the character device that was created. +Besides that the number of the TPM character device is returned. If for +example ``/dev/tpm10`` was created, the number (``dev_num``) 10 is returned. + +Once the device has been created, the driver will immediately try to talk +to the TPM. All commands from the driver can be read from the file descriptor +returned by the ioctl. The commands should be responded to immediately. + +UAPI +==== + +.. kernel-doc:: include/uapi/linux/vtpm_proxy.h + +.. kernel-doc:: drivers/char/tpm/tpm_vtpm_proxy.c + :functions: vtpmx_ioc_new_dev diff --git a/Documentation/tpm/tpm_vtpm_proxy.txt b/Documentation/tpm/tpm_vtpm_proxy.txt deleted file mode 100644 index 30d19022f869..000000000000 --- a/Documentation/tpm/tpm_vtpm_proxy.txt +++ /dev/null @@ -1,71 +0,0 @@ -Virtual TPM Proxy Driver for Linux Containers - -Authors: Stefan Berger (IBM) - -This document describes the virtual Trusted Platform Module (vTPM) -proxy device driver for Linux containers. - -INTRODUCTION ------------- - -The goal of this work is to provide TPM functionality to each Linux -container. This allows programs to interact with a TPM in a container -the same way they interact with a TPM on the physical system. Each -container gets its own unique, emulated, software TPM. - - -DESIGN ------- - -To make an emulated software TPM available to each container, the container -management stack needs to create a device pair consisting of a client TPM -character device /dev/tpmX (with X=0,1,2...) and a 'server side' file -descriptor. The former is moved into the container by creating a character -device with the appropriate major and minor numbers while the file descriptor -is passed to the TPM emulator. Software inside the container can then send -TPM commands using the character device and the emulator will receive the -commands via the file descriptor and use it for sending back responses. - -To support this, the virtual TPM proxy driver provides a device /dev/vtpmx -that is used to create device pairs using an ioctl. The ioctl takes as -an input flags for configuring the device. The flags for example indicate -whether TPM 1.2 or TPM 2 functionality is supported by the TPM emulator. -The result of the ioctl are the file descriptor for the 'server side' -as well as the major and minor numbers of the character device that was created. -Besides that the number of the TPM character device is return. If for -example /dev/tpm10 was created, the number (dev_num) 10 is returned. - -The following is the data structure of the TPM_PROXY_IOC_NEW_DEV ioctl: - -struct vtpm_proxy_new_dev { - __u32 flags; /* input */ - __u32 tpm_num; /* output */ - __u32 fd; /* output */ - __u32 major; /* output */ - __u32 minor; /* output */ -}; - -Note that if unsupported flags are passed to the device driver, the ioctl will -fail and errno will be set to EOPNOTSUPP. Similarly, if an unsupported ioctl is -called on the device driver, the ioctl will fail and errno will be set to -ENOTTY. - -See /usr/include/linux/vtpm_proxy.h for definitions related to the public interface -of this vTPM device driver. - -Once the device has been created, the driver will immediately try to talk -to the TPM. All commands from the driver can be read from the file descriptor -returned by the ioctl. The commands should be responded to immediately. - -Depending on the version of TPM the following commands will be sent by the -driver: - -- TPM 1.2: - - the driver will send a TPM_Startup command to the TPM emulator - - the driver will send commands to read the command durations and - interface timeouts from the TPM emulator -- TPM 2: - - the driver will send a TPM2_Startup command to the TPM emulator - -The TPM device /dev/tpmX will only appear if all of the relevant commands -were responded to properly. -- cgit v1.2.3 From 799a545bb9383c6185ad27063adca03d28ee1823 Mon Sep 17 00:00:00 2001 From: Jarkko Sakkinen Date: Thu, 3 Nov 2016 17:57:52 -0600 Subject: tpm: move documentation under Documentation/security In order too make Documentation root directory cleaner move the tpm directory under Documentation/security. Signed-off-by: Jarkko Sakkinen Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 2 +- Documentation/security/index.rst | 7 ++ Documentation/security/tpm/index.rst | 7 ++ Documentation/security/tpm/tpm_vtpm_proxy.rst | 50 ++++++++++++ Documentation/security/tpm/xen-tpmfront.txt | 113 ++++++++++++++++++++++++++ Documentation/tpm/index.rst | 7 -- Documentation/tpm/tpm_vtpm_proxy.rst | 50 ------------ Documentation/tpm/xen-tpmfront.txt | 113 -------------------------- 8 files changed, 178 insertions(+), 171 deletions(-) create mode 100644 Documentation/security/index.rst create mode 100644 Documentation/security/tpm/index.rst create mode 100644 Documentation/security/tpm/tpm_vtpm_proxy.rst create mode 100644 Documentation/security/tpm/xen-tpmfront.txt delete mode 100644 Documentation/tpm/index.rst delete mode 100644 Documentation/tpm/tpm_vtpm_proxy.rst delete mode 100644 Documentation/tpm/xen-tpmfront.txt diff --git a/Documentation/index.rst b/Documentation/index.rst index 0058b65d361c..b4c3034ebc09 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -19,7 +19,7 @@ Contents: media/dvb-drivers/index media/v4l-drivers/index gpu/index - tpm/index + security/index Indices and tables ================== diff --git a/Documentation/security/index.rst b/Documentation/security/index.rst new file mode 100644 index 000000000000..9bae6bb20e7f --- /dev/null +++ b/Documentation/security/index.rst @@ -0,0 +1,7 @@ +====================== +Security documentation +====================== + +.. toctree:: + + tpm/index diff --git a/Documentation/security/tpm/index.rst b/Documentation/security/tpm/index.rst new file mode 100644 index 000000000000..af77a7bbb070 --- /dev/null +++ b/Documentation/security/tpm/index.rst @@ -0,0 +1,7 @@ +===================================== +Trusted Platform Module documentation +===================================== + +.. toctree:: + + tpm_vtpm_proxy diff --git a/Documentation/security/tpm/tpm_vtpm_proxy.rst b/Documentation/security/tpm/tpm_vtpm_proxy.rst new file mode 100644 index 000000000000..ea08e76b17f5 --- /dev/null +++ b/Documentation/security/tpm/tpm_vtpm_proxy.rst @@ -0,0 +1,50 @@ +============================================= +Virtual TPM Proxy Driver for Linux Containers +============================================= + +| Authors: +| Stefan Berger + +This document describes the virtual Trusted Platform Module (vTPM) +proxy device driver for Linux containers. + +Introduction +============ + +The goal of this work is to provide TPM functionality to each Linux +container. This allows programs to interact with a TPM in a container +the same way they interact with a TPM on the physical system. Each +container gets its own unique, emulated, software TPM. + +Design +====== + +To make an emulated software TPM available to each container, the container +management stack needs to create a device pair consisting of a client TPM +character device ``/dev/tpmX`` (with X=0,1,2...) and a 'server side' file +descriptor. The former is moved into the container by creating a character +device with the appropriate major and minor numbers while the file descriptor +is passed to the TPM emulator. Software inside the container can then send +TPM commands using the character device and the emulator will receive the +commands via the file descriptor and use it for sending back responses. + +To support this, the virtual TPM proxy driver provides a device ``/dev/vtpmx`` +that is used to create device pairs using an ioctl. The ioctl takes as +an input flags for configuring the device. The flags for example indicate +whether TPM 1.2 or TPM 2 functionality is supported by the TPM emulator. +The result of the ioctl are the file descriptor for the 'server side' +as well as the major and minor numbers of the character device that was created. +Besides that the number of the TPM character device is returned. If for +example ``/dev/tpm10`` was created, the number (``dev_num``) 10 is returned. + +Once the device has been created, the driver will immediately try to talk +to the TPM. All commands from the driver can be read from the file descriptor +returned by the ioctl. The commands should be responded to immediately. + +UAPI +==== + +.. kernel-doc:: include/uapi/linux/vtpm_proxy.h + +.. kernel-doc:: drivers/char/tpm/tpm_vtpm_proxy.c + :functions: vtpmx_ioc_new_dev diff --git a/Documentation/security/tpm/xen-tpmfront.txt b/Documentation/security/tpm/xen-tpmfront.txt new file mode 100644 index 000000000000..69346de87ff3 --- /dev/null +++ b/Documentation/security/tpm/xen-tpmfront.txt @@ -0,0 +1,113 @@ +Virtual TPM interface for Xen + +Authors: Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA) + +This document describes the virtual Trusted Platform Module (vTPM) subsystem for +Xen. The reader is assumed to have familiarity with building and installing Xen, +Linux, and a basic understanding of the TPM and vTPM concepts. + +INTRODUCTION + +The goal of this work is to provide a TPM functionality to a virtual guest +operating system (in Xen terms, a DomU). This allows programs to interact with +a TPM in a virtual system the same way they interact with a TPM on the physical +system. Each guest gets its own unique, emulated, software TPM. However, each +of the vTPM's secrets (Keys, NVRAM, etc) are managed by a vTPM Manager domain, +which seals the secrets to the Physical TPM. If the process of creating each of +these domains (manager, vTPM, and guest) is trusted, the vTPM subsystem extends +the chain of trust rooted in the hardware TPM to virtual machines in Xen. Each +major component of vTPM is implemented as a separate domain, providing secure +separation guaranteed by the hypervisor. The vTPM domains are implemented in +mini-os to reduce memory and processor overhead. + +This mini-os vTPM subsystem was built on top of the previous vTPM work done by +IBM and Intel corporation. + + +DESIGN OVERVIEW +--------------- + +The architecture of vTPM is described below: + ++------------------+ +| Linux DomU | ... +| | ^ | +| v | | +| xen-tpmfront | ++------------------+ + | ^ + v | ++------------------+ +| mini-os/tpmback | +| | ^ | +| v | | +| vtpm-stubdom | ... +| | ^ | +| v | | +| mini-os/tpmfront | ++------------------+ + | ^ + v | ++------------------+ +| mini-os/tpmback | +| | ^ | +| v | | +| vtpmmgr-stubdom | +| | ^ | +| v | | +| mini-os/tpm_tis | ++------------------+ + | ^ + v | ++------------------+ +| Hardware TPM | ++------------------+ + + * Linux DomU: The Linux based guest that wants to use a vTPM. There may be + more than one of these. + + * xen-tpmfront.ko: Linux kernel virtual TPM frontend driver. This driver + provides vTPM access to a Linux-based DomU. + + * mini-os/tpmback: Mini-os TPM backend driver. The Linux frontend driver + connects to this backend driver to facilitate communications + between the Linux DomU and its vTPM. This driver is also + used by vtpmmgr-stubdom to communicate with vtpm-stubdom. + + * vtpm-stubdom: A mini-os stub domain that implements a vTPM. There is a + one to one mapping between running vtpm-stubdom instances and + logical vtpms on the system. The vTPM Platform Configuration + Registers (PCRs) are normally all initialized to zero. + + * mini-os/tpmfront: Mini-os TPM frontend driver. The vTPM mini-os domain + vtpm-stubdom uses this driver to communicate with + vtpmmgr-stubdom. This driver is also used in mini-os + domains such as pv-grub that talk to the vTPM domain. + + * vtpmmgr-stubdom: A mini-os domain that implements the vTPM manager. There is + only one vTPM manager and it should be running during the + entire lifetime of the machine. This domain regulates + access to the physical TPM on the system and secures the + persistent state of each vTPM. + + * mini-os/tpm_tis: Mini-os TPM version 1.2 TPM Interface Specification (TIS) + driver. This driver used by vtpmmgr-stubdom to talk directly to + the hardware TPM. Communication is facilitated by mapping + hardware memory pages into vtpmmgr-stubdom. + + * Hardware TPM: The physical TPM that is soldered onto the motherboard. + + +INTEGRATION WITH XEN +-------------------- + +Support for the vTPM driver was added in Xen using the libxl toolstack in Xen +4.3. See the Xen documentation (docs/misc/vtpm.txt) for details on setting up +the vTPM and vTPM Manager stub domains. Once the stub domains are running, a +vTPM device is set up in the same manner as a disk or network device in the +domain's configuration file. + +In order to use features such as IMA that require a TPM to be loaded prior to +the initrd, the xen-tpmfront driver must be compiled in to the kernel. If not +using such features, the driver can be compiled as a module and will be loaded +as usual. diff --git a/Documentation/tpm/index.rst b/Documentation/tpm/index.rst deleted file mode 100644 index af77a7bbb070..000000000000 --- a/Documentation/tpm/index.rst +++ /dev/null @@ -1,7 +0,0 @@ -===================================== -Trusted Platform Module documentation -===================================== - -.. toctree:: - - tpm_vtpm_proxy diff --git a/Documentation/tpm/tpm_vtpm_proxy.rst b/Documentation/tpm/tpm_vtpm_proxy.rst deleted file mode 100644 index ea08e76b17f5..000000000000 --- a/Documentation/tpm/tpm_vtpm_proxy.rst +++ /dev/null @@ -1,50 +0,0 @@ -============================================= -Virtual TPM Proxy Driver for Linux Containers -============================================= - -| Authors: -| Stefan Berger - -This document describes the virtual Trusted Platform Module (vTPM) -proxy device driver for Linux containers. - -Introduction -============ - -The goal of this work is to provide TPM functionality to each Linux -container. This allows programs to interact with a TPM in a container -the same way they interact with a TPM on the physical system. Each -container gets its own unique, emulated, software TPM. - -Design -====== - -To make an emulated software TPM available to each container, the container -management stack needs to create a device pair consisting of a client TPM -character device ``/dev/tpmX`` (with X=0,1,2...) and a 'server side' file -descriptor. The former is moved into the container by creating a character -device with the appropriate major and minor numbers while the file descriptor -is passed to the TPM emulator. Software inside the container can then send -TPM commands using the character device and the emulator will receive the -commands via the file descriptor and use it for sending back responses. - -To support this, the virtual TPM proxy driver provides a device ``/dev/vtpmx`` -that is used to create device pairs using an ioctl. The ioctl takes as -an input flags for configuring the device. The flags for example indicate -whether TPM 1.2 or TPM 2 functionality is supported by the TPM emulator. -The result of the ioctl are the file descriptor for the 'server side' -as well as the major and minor numbers of the character device that was created. -Besides that the number of the TPM character device is returned. If for -example ``/dev/tpm10`` was created, the number (``dev_num``) 10 is returned. - -Once the device has been created, the driver will immediately try to talk -to the TPM. All commands from the driver can be read from the file descriptor -returned by the ioctl. The commands should be responded to immediately. - -UAPI -==== - -.. kernel-doc:: include/uapi/linux/vtpm_proxy.h - -.. kernel-doc:: drivers/char/tpm/tpm_vtpm_proxy.c - :functions: vtpmx_ioc_new_dev diff --git a/Documentation/tpm/xen-tpmfront.txt b/Documentation/tpm/xen-tpmfront.txt deleted file mode 100644 index 69346de87ff3..000000000000 --- a/Documentation/tpm/xen-tpmfront.txt +++ /dev/null @@ -1,113 +0,0 @@ -Virtual TPM interface for Xen - -Authors: Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA) - -This document describes the virtual Trusted Platform Module (vTPM) subsystem for -Xen. The reader is assumed to have familiarity with building and installing Xen, -Linux, and a basic understanding of the TPM and vTPM concepts. - -INTRODUCTION - -The goal of this work is to provide a TPM functionality to a virtual guest -operating system (in Xen terms, a DomU). This allows programs to interact with -a TPM in a virtual system the same way they interact with a TPM on the physical -system. Each guest gets its own unique, emulated, software TPM. However, each -of the vTPM's secrets (Keys, NVRAM, etc) are managed by a vTPM Manager domain, -which seals the secrets to the Physical TPM. If the process of creating each of -these domains (manager, vTPM, and guest) is trusted, the vTPM subsystem extends -the chain of trust rooted in the hardware TPM to virtual machines in Xen. Each -major component of vTPM is implemented as a separate domain, providing secure -separation guaranteed by the hypervisor. The vTPM domains are implemented in -mini-os to reduce memory and processor overhead. - -This mini-os vTPM subsystem was built on top of the previous vTPM work done by -IBM and Intel corporation. - - -DESIGN OVERVIEW ---------------- - -The architecture of vTPM is described below: - -+------------------+ -| Linux DomU | ... -| | ^ | -| v | | -| xen-tpmfront | -+------------------+ - | ^ - v | -+------------------+ -| mini-os/tpmback | -| | ^ | -| v | | -| vtpm-stubdom | ... -| | ^ | -| v | | -| mini-os/tpmfront | -+------------------+ - | ^ - v | -+------------------+ -| mini-os/tpmback | -| | ^ | -| v | | -| vtpmmgr-stubdom | -| | ^ | -| v | | -| mini-os/tpm_tis | -+------------------+ - | ^ - v | -+------------------+ -| Hardware TPM | -+------------------+ - - * Linux DomU: The Linux based guest that wants to use a vTPM. There may be - more than one of these. - - * xen-tpmfront.ko: Linux kernel virtual TPM frontend driver. This driver - provides vTPM access to a Linux-based DomU. - - * mini-os/tpmback: Mini-os TPM backend driver. The Linux frontend driver - connects to this backend driver to facilitate communications - between the Linux DomU and its vTPM. This driver is also - used by vtpmmgr-stubdom to communicate with vtpm-stubdom. - - * vtpm-stubdom: A mini-os stub domain that implements a vTPM. There is a - one to one mapping between running vtpm-stubdom instances and - logical vtpms on the system. The vTPM Platform Configuration - Registers (PCRs) are normally all initialized to zero. - - * mini-os/tpmfront: Mini-os TPM frontend driver. The vTPM mini-os domain - vtpm-stubdom uses this driver to communicate with - vtpmmgr-stubdom. This driver is also used in mini-os - domains such as pv-grub that talk to the vTPM domain. - - * vtpmmgr-stubdom: A mini-os domain that implements the vTPM manager. There is - only one vTPM manager and it should be running during the - entire lifetime of the machine. This domain regulates - access to the physical TPM on the system and secures the - persistent state of each vTPM. - - * mini-os/tpm_tis: Mini-os TPM version 1.2 TPM Interface Specification (TIS) - driver. This driver used by vtpmmgr-stubdom to talk directly to - the hardware TPM. Communication is facilitated by mapping - hardware memory pages into vtpmmgr-stubdom. - - * Hardware TPM: The physical TPM that is soldered onto the motherboard. - - -INTEGRATION WITH XEN --------------------- - -Support for the vTPM driver was added in Xen using the libxl toolstack in Xen -4.3. See the Xen documentation (docs/misc/vtpm.txt) for details on setting up -the vTPM and vTPM Manager stub domains. Once the stub domains are running, a -vTPM device is set up in the same manner as a disk or network device in the -domain's configuration file. - -In order to use features such as IMA that require a TPM to be loaded prior to -the initrd, the xen-tpmfront driver must be compiled in to the kernel. If not -using such features, the driver can be compiled as a module and will be loaded -as usual. -- cgit v1.2.3 From 05d5f95dc7c6a61fb2b2af0935727a6ea61cb0f1 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Tue, 1 Nov 2016 15:36:02 +0100 Subject: doc-rst: make cleandocs misses a fair number of files Removes intermediate 'Documentation/DocBook/.*.xml.cmd' files Changes since v1: - Reduce the patch to DocBook cleandocs References: http://lkml.kernel.org/r/CA+r1Zhjr5SCVAroREBv84t9bxDVu5jVJ_Fu=BbVDGNNABdQOuQ@mail.gmail.com Reported-by: Jim Davis Signed-off-by: Markus Heiser Signed-off-by: Jonathan Corbet --- Documentation/DocBook/Makefile | 1 + 1 file changed, 1 insertion(+) diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index fdf8232d0eeb..263e6577de66 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -264,6 +264,7 @@ clean-files := $(DOCBOOKS) \ $(patsubst %.xml, %.aux.xml, $(DOCBOOKS)) \ $(patsubst %.xml, %.xml.db, $(DOCBOOKS)) \ $(patsubst %.xml, %.xml, $(DOCBOOKS)) \ + $(patsubst %.xml, .%.xml.cmd, $(DOCBOOKS)) \ $(index) clean-dirs := $(patsubst %.xml,%,$(DOCBOOKS)) man -- cgit v1.2.3 From beab6cb20c1dff4a0fb1ee9d14ff5f826ccd2c84 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Thu, 3 Nov 2016 01:57:34 +0900 Subject: coding-style: fix mismatch of jump label name Commit 865a1caa4b6b ("CodingStyle: Clarify and complete chapter 7") renamed the label "out_buffer" to "out_free_buffer", but missed to change this line. Signed-off-by: Masahiro Yamada Reviewed-by: Jean Delvare Signed-off-by: Jonathan Corbet --- Documentation/process/coding-style.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index 968808bec407..3e7905172000 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -475,7 +475,7 @@ The rationale for using gotos is: ... } result = 1; - goto out_buffer; + goto out_free_buffer; } ... out_free_buffer: -- cgit v1.2.3 From d55003d86e0ce598b599277973035327779b643b Mon Sep 17 00:00:00 2001 From: Luis de Bethencourt Date: Tue, 1 Nov 2016 15:23:37 +0000 Subject: USB: fix typo in documentation A typo sneaked in the latest change on the USB documentation. Fixing it and also a trailing whitespace since it is also in the "USB Host-Side API Model" chapter. Signed-off-by: Luis de Bethencourt --- Documentation/DocBook/usb.tmpl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/DocBook/usb.tmpl b/Documentation/DocBook/usb.tmpl index 8ec4d595b218..e322691be67e 100644 --- a/Documentation/DocBook/usb.tmpl +++ b/Documentation/DocBook/usb.tmpl @@ -160,7 +160,7 @@ In theory, all HCDs provide the same functionality through the same API. In practice, that's becoming mostly true, but there are still differences that crop up especially with - fault handling on the less common controllers. + fault handling on the less common controllers. Different controllers don't necessarily report the same aspects of failures, and recovery from faults (including software-induced ones like unlinking an URB) isn't yet fully @@ -168,7 +168,7 @@ Device driver authors should make a point of doing disconnect testing (while the device is active) with each different host controller driver, to make sure drivers don't have bugs of - thei1r own as well as to make sure they aren't relying on some + their own as well as to make sure they aren't relying on some HCD-specific behavior. -- cgit v1.2.3 From 3a5182c04a020e5ba5339c3b393cae0d17b74ef5 Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Thu, 10 Nov 2016 17:37:15 +0100 Subject: ALSA: doc: Remove alsa-parameters.txt This is a really obsoleted information, effectively just listing the module names. Let's get rid of it for avoiding confusions. Signed-off-by: Takashi Iwai --- Documentation/sound/alsa/alsa-parameters.txt | 135 --------------------------- 1 file changed, 135 deletions(-) delete mode 100644 Documentation/sound/alsa/alsa-parameters.txt diff --git a/Documentation/sound/alsa/alsa-parameters.txt b/Documentation/sound/alsa/alsa-parameters.txt deleted file mode 100644 index 0fa40679b080..000000000000 --- a/Documentation/sound/alsa/alsa-parameters.txt +++ /dev/null @@ -1,135 +0,0 @@ - ALSA Kernel Parameters - ~~~~~~~~~~~~~~~~~~~~~~ - -See Documentation/kernel-parameters.txt for general information on -specifying module parameters. - -This document may not be entirely up to date and comprehensive. The command -"modinfo -p ${modulename}" shows a current list of all parameters of a loadable -module. Loadable modules, after being loaded into the running kernel, also -reveal their parameters in /sys/module/${modulename}/parameters/. Some of these -parameters may be changed at runtime by the command -"echo -n ${value} > /sys/module/${modulename}/parameters/${parm}". - - - snd-ad1816a= [HW,ALSA] - - snd-ad1848= [HW,ALSA] - - snd-ali5451= [HW,ALSA] - - snd-als100= [HW,ALSA] - - snd-als4000= [HW,ALSA] - - snd-azt2320= [HW,ALSA] - - snd-cmi8330= [HW,ALSA] - - snd-cmipci= [HW,ALSA] - - snd-cs4231= [HW,ALSA] - - snd-cs4232= [HW,ALSA] - - snd-cs4236= [HW,ALSA] - - snd-cs4281= [HW,ALSA] - - snd-cs46xx= [HW,ALSA] - - snd-dt019x= [HW,ALSA] - - snd-dummy= [HW,ALSA] - - snd-emu10k1= [HW,ALSA] - - snd-ens1370= [HW,ALSA] - - snd-ens1371= [HW,ALSA] - - snd-es968= [HW,ALSA] - - snd-es1688= [HW,ALSA] - - snd-es18xx= [HW,ALSA] - - snd-es1938= [HW,ALSA] - - snd-es1968= [HW,ALSA] - - snd-fm801= [HW,ALSA] - - snd-gusclassic= [HW,ALSA] - - snd-gusextreme= [HW,ALSA] - - snd-gusmax= [HW,ALSA] - - snd-hdsp= [HW,ALSA] - - snd-ice1712= [HW,ALSA] - - snd-intel8x0= [HW,ALSA] - - snd-interwave= [HW,ALSA] - - snd-interwave-stb= - [HW,ALSA] - - snd-korg1212= [HW,ALSA] - - snd-maestro3= [HW,ALSA] - - snd-mpu401= [HW,ALSA] - - snd-mtpav= [HW,ALSA] - - snd-nm256= [HW,ALSA] - - snd-opl3sa2= [HW,ALSA] - - snd-opti92x-ad1848= - [HW,ALSA] - - snd-opti92x-cs4231= - [HW,ALSA] - - snd-opti93x= [HW,ALSA] - - snd-pmac= [HW,ALSA] - - snd-rme32= [HW,ALSA] - - snd-rme96= [HW,ALSA] - - snd-rme9652= [HW,ALSA] - - snd-sb8= [HW,ALSA] - - snd-sb16= [HW,ALSA] - - snd-sbawe= [HW,ALSA] - - snd-serial= [HW,ALSA] - - snd-sgalaxy= [HW,ALSA] - - snd-sonicvibes= [HW,ALSA] - - snd-sun-amd7930= - [HW,ALSA] - - snd-sun-cs4231= [HW,ALSA] - - snd-trident= [HW,ALSA] - - snd-usb-audio= [HW,ALSA,USB] - - snd-via82xx= [HW,ALSA] - - snd-virmidi= [HW,ALSA] - - snd-wavefront= [HW,ALSA] - - snd-ymfpci= [HW,ALSA] -- cgit v1.2.3 From 8551914a5e19094255a0e2aadb24f70736f7ba7d Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 2 Nov 2016 21:30:39 +0100 Subject: ALSA: doc: ReSTize alsa-driver-api document A simple conversion of alsa-driver-api document from DocBook to ReST. It's moved to the new Documentation/sound/kernel-api subdirectory that will contain other ALSA kernel API documents. The GPL legal note was removed, as it's superfluous (and doesn't fit with ReST kernel docs pretty well). Signed-off-by: Takashi Iwai --- Documentation/DocBook/Makefile | 2 +- Documentation/DocBook/alsa-driver-api.tmpl | 142 --------------------- Documentation/index.rst | 1 + Documentation/sound/index.rst | 15 +++ Documentation/sound/kernel-api/alsa-driver-api.rst | 134 +++++++++++++++++++ Documentation/sound/kernel-api/index.rst | 7 + 6 files changed, 158 insertions(+), 143 deletions(-) delete mode 100644 Documentation/DocBook/alsa-driver-api.tmpl create mode 100644 Documentation/sound/index.rst create mode 100644 Documentation/sound/kernel-api/alsa-driver-api.rst create mode 100644 Documentation/sound/kernel-api/index.rst diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index fdf8232d0eeb..e173497959fa 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -13,7 +13,7 @@ DOCBOOKS := z8530book.xml \ gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ debugobjects.xml sh.xml regulator.xml \ - alsa-driver-api.xml writing-an-alsa-driver.xml \ + writing-an-alsa-driver.xml \ tracepoint.xml w1.xml \ writing_musb_glue_layer.xml crypto-API.xml iio.xml diff --git a/Documentation/DocBook/alsa-driver-api.tmpl b/Documentation/DocBook/alsa-driver-api.tmpl deleted file mode 100644 index 53f439dcc94b..000000000000 --- a/Documentation/DocBook/alsa-driver-api.tmpl +++ /dev/null @@ -1,142 +0,0 @@ - - - - - - - - - The ALSA Driver API - - - - This document is free; you can redistribute it and/or modify it - under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - - - This document is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the - implied warranty of MERCHANTABILITY or FITNESS FOR A - PARTICULAR PURPOSE. See the GNU General Public License - for more details. - - - - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - - - - - - - - Management of Cards and Devices - Card Management -!Esound/core/init.c - - Device Components -!Esound/core/device.c - - Module requests and Device File Entries -!Esound/core/sound.c - - Memory Management Helpers -!Esound/core/memory.c -!Esound/core/memalloc.c - - - PCM API - PCM Core -!Esound/core/pcm.c -!Esound/core/pcm_lib.c -!Esound/core/pcm_native.c -!Iinclude/sound/pcm.h - - PCM Format Helpers -!Esound/core/pcm_misc.c - - PCM Memory Management -!Esound/core/pcm_memory.c - - PCM DMA Engine API -!Esound/core/pcm_dmaengine.c -!Iinclude/sound/dmaengine_pcm.h - - - Control/Mixer API - General Control Interface -!Esound/core/control.c - - AC97 Codec API -!Esound/pci/ac97/ac97_codec.c -!Esound/pci/ac97/ac97_pcm.c - - Virtual Master Control API -!Esound/core/vmaster.c -!Iinclude/sound/control.h - - - MIDI API - Raw MIDI API -!Esound/core/rawmidi.c - - MPU401-UART API -!Esound/drivers/mpu401/mpu401_uart.c - - - Proc Info API - Proc Info Interface -!Esound/core/info.c - - - Compress Offload - Compress Offload API -!Esound/core/compress_offload.c -!Iinclude/uapi/sound/compress_offload.h -!Iinclude/uapi/sound/compress_params.h -!Iinclude/sound/compress_driver.h - - - ASoC - ASoC Core API -!Iinclude/sound/soc.h -!Esound/soc/soc-core.c - -!Esound/soc/soc-devres.c -!Esound/soc/soc-io.c -!Esound/soc/soc-pcm.c -!Esound/soc/soc-ops.c -!Esound/soc/soc-compress.c - - ASoC DAPM API -!Esound/soc/soc-dapm.c - - ASoC DMA Engine API -!Esound/soc/soc-generic-dmaengine-pcm.c - - - Miscellaneous Functions - Hardware-Dependent Devices API -!Esound/core/hwdep.c - - Jack Abstraction Layer API -!Iinclude/sound/jack.h -!Esound/core/jack.c -!Esound/soc/soc-jack.c - - ISA DMA Helpers -!Esound/core/isadma.c - - Other Helper Macros -!Iinclude/sound/core.h - - - - diff --git a/Documentation/index.rst b/Documentation/index.rst index c53d089455a4..115c551da5f5 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -18,6 +18,7 @@ Contents: media/index gpu/index 80211/index + sound/index Indices and tables ================== diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst new file mode 100644 index 000000000000..280a57115f00 --- /dev/null +++ b/Documentation/sound/index.rst @@ -0,0 +1,15 @@ +=================================== +Linux Sound Subsystem Documentation +=================================== + +.. toctree:: + :maxdepth: 2 + + kernel-api/index + +.. only:: subproject + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/sound/kernel-api/alsa-driver-api.rst b/Documentation/sound/kernel-api/alsa-driver-api.rst new file mode 100644 index 000000000000..14cd138989e3 --- /dev/null +++ b/Documentation/sound/kernel-api/alsa-driver-api.rst @@ -0,0 +1,134 @@ +=================== +The ALSA Driver API +=================== + +Management of Cards and Devices +=============================== + +Card Management +--------------- +.. kernel-doc:: sound/core/init.c + +Device Components +----------------- +.. kernel-doc:: sound/core/device.c + +Module requests and Device File Entries +--------------------------------------- +.. kernel-doc:: sound/core/sound.c + +Memory Management Helpers +------------------------- +.. kernel-doc:: sound/core/memory.c +.. kernel-doc:: sound/core/memalloc.c + + +PCM API +======= + +PCM Core +-------- +.. kernel-doc:: sound/core/pcm.c +.. kernel-doc:: sound/core/pcm_lib.c +.. kernel-doc:: sound/core/pcm_native.c +.. kernel-doc:: include/sound/pcm.h + +PCM Format Helpers +------------------ +.. kernel-doc:: sound/core/pcm_misc.c + +PCM Memory Management +--------------------- +.. kernel-doc:: sound/core/pcm_memory.c + +PCM DMA Engine API +------------------ +.. kernel-doc:: sound/core/pcm_dmaengine.c +.. kernel-doc:: include/sound/dmaengine_pcm.h + +Control/Mixer API +================= + +General Control Interface +------------------------- +.. kernel-doc:: sound/core/control.c + +AC97 Codec API +-------------- +.. kernel-doc:: sound/pci/ac97/ac97_codec.c +.. kernel-doc:: sound/pci/ac97/ac97_pcm.c + +Virtual Master Control API +-------------------------- +.. kernel-doc:: sound/core/vmaster.c +.. kernel-doc:: include/sound/control.h + +MIDI API +======== + +Raw MIDI API +------------ +.. kernel-doc:: sound/core/rawmidi.c + +MPU401-UART API +--------------- +.. kernel-doc:: sound/drivers/mpu401/mpu401_uart.c + +Proc Info API +============= + +Proc Info Interface +------------------- +.. kernel-doc:: sound/core/info.c + +Compress Offload +================ + +Compress Offload API +-------------------- +.. kernel-doc:: sound/core/compress_offload.c +.. kernel-doc:: include/uapi/sound/compress_offload.h +.. kernel-doc:: include/uapi/sound/compress_params.h +.. kernel-doc:: include/sound/compress_driver.h + +ASoC +==== + +ASoC Core API +------------- +.. kernel-doc:: include/sound/soc.h +.. kernel-doc:: sound/soc/soc-core.c +.. kernel-doc:: sound/soc/soc-devres.c +.. kernel-doc:: sound/soc/soc-io.c +.. kernel-doc:: sound/soc/soc-pcm.c +.. kernel-doc:: sound/soc/soc-ops.c +.. kernel-doc:: sound/soc/soc-compress.c + +ASoC DAPM API +------------- +.. kernel-doc:: sound/soc/soc-dapm.c + +ASoC DMA Engine API +------------------- +.. kernel-doc:: sound/soc/soc-generic-dmaengine-pcm.c + +Miscellaneous Functions +======================= + +Hardware-Dependent Devices API +------------------------------ +.. kernel-doc:: sound/core/hwdep.c + +Jack Abstraction Layer API +-------------------------- +.. kernel-doc:: include/sound/jack.h +.. kernel-doc:: sound/core/jack.c +.. kernel-doc:: sound/soc/soc-jack.c + +ISA DMA Helpers +--------------- +.. kernel-doc:: sound/core/isadma.c + +Other Helper Macros +------------------- +.. kernel-doc:: include/sound/core.h diff --git a/Documentation/sound/kernel-api/index.rst b/Documentation/sound/kernel-api/index.rst new file mode 100644 index 000000000000..73c13497dec7 --- /dev/null +++ b/Documentation/sound/kernel-api/index.rst @@ -0,0 +1,7 @@ +ALSA Kernel API Documentation +============================= + +.. toctree:: + :maxdepth: 2 + + alsa-driver-api -- cgit v1.2.3 From 7ddedebb03b7ec030c528ebacdd43e45373476e3 Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Thu, 29 Sep 2016 18:21:46 +0200 Subject: ALSA: doc: ReSTize writing-an-alsa-driver document Another simple conversion from DocBook to ReST. This required a few manual fixups and reformats, but the most of contents are kept as is. Signed-off-by: Takashi Iwai --- Documentation/DocBook/Makefile | 3 +- Documentation/DocBook/writing-an-alsa-driver.tmpl | 6206 -------------------- Documentation/sound/kernel-api/index.rst | 1 + .../sound/kernel-api/writing-an-alsa-driver.rst | 4219 +++++++++++++ 4 files changed, 4221 insertions(+), 6208 deletions(-) delete mode 100644 Documentation/DocBook/writing-an-alsa-driver.tmpl create mode 100644 Documentation/sound/kernel-api/writing-an-alsa-driver.rst diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index e173497959fa..72f78ae46c10 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -12,8 +12,7 @@ DOCBOOKS := z8530book.xml \ kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \ gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \ - debugobjects.xml sh.xml regulator.xml \ - writing-an-alsa-driver.xml \ + 80211.xml debugobjects.xml sh.xml regulator.xml \ tracepoint.xml w1.xml \ writing_musb_glue_layer.xml crypto-API.xml iio.xml diff --git a/Documentation/DocBook/writing-an-alsa-driver.tmpl b/Documentation/DocBook/writing-an-alsa-driver.tmpl deleted file mode 100644 index a27ab9f53fb6..000000000000 --- a/Documentation/DocBook/writing-an-alsa-driver.tmpl +++ /dev/null @@ -1,6206 +0,0 @@ - - - - - - - - - Writing an ALSA Driver - - Takashi - Iwai - -
- tiwai@suse.de -
- - - - Oct 15, 2007 - 0.3.7 - - - - This document describes how to write an ALSA (Advanced Linux - Sound Architecture) driver. - - - - - - Copyright (c) 2002-2005 Takashi Iwai tiwai@suse.de - - - - This document is free; you can redistribute it and/or modify it - under the terms of the GNU General Public License as published by - the Free Software Foundation; either version 2 of the License, or - (at your option) any later version. - - - - This document is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the - implied warranty of MERCHANTABILITY or FITNESS FOR A - PARTICULAR PURPOSE. See the GNU General Public License - for more details. - - - - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - - - - - - - - - - Preface - - This document describes how to write an - - ALSA (Advanced Linux Sound Architecture) - driver. The document focuses mainly on PCI soundcards. - In the case of other device types, the API might - be different, too. However, at least the ALSA kernel API is - consistent, and therefore it would be still a bit help for - writing them. - - - - This document targets people who already have enough - C language skills and have basic linux kernel programming - knowledge. This document doesn't explain the general - topic of linux kernel coding and doesn't cover low-level - driver implementation details. It only describes - the standard way to write a PCI sound driver on ALSA. - - - - If you are already familiar with the older ALSA ver.0.5.x API, you - can check the drivers such as sound/pci/es1938.c or - sound/pci/maestro3.c which have also almost the same - code-base in the ALSA 0.5.x tree, so you can compare the differences. - - - - This document is still a draft version. Any feedback and - corrections, please!! - - - - - - - - - File Tree Structure - -
- General - - The ALSA drivers are provided in two ways. - - - - One is the trees provided as a tarball or via cvs from the - ALSA's ftp site, and another is the 2.6 (or later) Linux kernel - tree. To synchronize both, the ALSA driver tree is split into - two different trees: alsa-kernel and alsa-driver. The former - contains purely the source code for the Linux 2.6 (or later) - tree. This tree is designed only for compilation on 2.6 or - later environment. The latter, alsa-driver, contains many subtle - files for compiling ALSA drivers outside of the Linux kernel tree, - wrapper functions for older 2.2 and 2.4 kernels, to adapt the latest kernel API, - and additional drivers which are still in development or in - tests. The drivers in alsa-driver tree will be moved to - alsa-kernel (and eventually to the 2.6 kernel tree) when they are - finished and confirmed to work fine. - - - - The file tree structure of ALSA driver is depicted below. Both - alsa-kernel and alsa-driver have almost the same file - structure, except for core directory. It's - named as acore in alsa-driver tree. - - - ALSA File Tree Structure - - sound - /core - /oss - /seq - /oss - /instr - /ioctl32 - /include - /drivers - /mpu401 - /opl3 - /i2c - /l3 - /synth - /emux - /pci - /(cards) - /isa - /(cards) - /arm - /ppc - /sparc - /usb - /pcmcia /(cards) - /oss - - - -
- -
- core directory - - This directory contains the middle layer which is the heart - of ALSA drivers. In this directory, the native ALSA modules are - stored. The sub-directories contain different modules and are - dependent upon the kernel config. - - -
- core/oss - - - The codes for PCM and mixer OSS emulation modules are stored - in this directory. The rawmidi OSS emulation is included in - the ALSA rawmidi code since it's quite small. The sequencer - code is stored in core/seq/oss directory (see - - below). - -
- -
- core/ioctl32 - - - This directory contains the 32bit-ioctl wrappers for 64bit - architectures such like x86-64, ppc64 and sparc64. For 32bit - and alpha architectures, these are not compiled. - -
- -
- core/seq - - This directory and its sub-directories are for the ALSA - sequencer. This directory contains the sequencer core and - primary sequencer modules such like snd-seq-midi, - snd-seq-virmidi, etc. They are compiled only when - CONFIG_SND_SEQUENCER is set in the kernel - config. - -
- -
- core/seq/oss - - This contains the OSS sequencer emulation codes. - -
- -
- core/seq/instr - - This directory contains the modules for the sequencer - instrument layer. - -
-
- -
- include directory - - This is the place for the public header files of ALSA drivers, - which are to be exported to user-space, or included by - several files at different directories. Basically, the private - header files should not be placed in this directory, but you may - still find files there, due to historical reasons :) - -
- -
- drivers directory - - This directory contains code shared among different drivers - on different architectures. They are hence supposed not to be - architecture-specific. - For example, the dummy pcm driver and the serial MIDI - driver are found in this directory. In the sub-directories, - there is code for components which are independent from - bus and cpu architectures. - - -
- drivers/mpu401 - - The MPU401 and MPU401-UART modules are stored here. - -
- -
- drivers/opl3 and opl4 - - The OPL3 and OPL4 FM-synth stuff is found here. - -
-
- -
- i2c directory - - This contains the ALSA i2c components. - - - - Although there is a standard i2c layer on Linux, ALSA has its - own i2c code for some cards, because the soundcard needs only a - simple operation and the standard i2c API is too complicated for - such a purpose. - - -
- i2c/l3 - - This is a sub-directory for ARM L3 i2c. - -
-
- -
- synth directory - - This contains the synth middle-level modules. - - - - So far, there is only Emu8000/Emu10k1 synth driver under - the synth/emux sub-directory. - -
- -
- pci directory - - This directory and its sub-directories hold the top-level card modules - for PCI soundcards and the code specific to the PCI BUS. - - - - The drivers compiled from a single file are stored directly - in the pci directory, while the drivers with several source files are - stored on their own sub-directory (e.g. emu10k1, ice1712). - -
- -
- isa directory - - This directory and its sub-directories hold the top-level card modules - for ISA soundcards. - -
- -
- arm, ppc, and sparc directories - - They are used for top-level card modules which are - specific to one of these architectures. - -
- -
- usb directory - - This directory contains the USB-audio driver. In the latest version, the - USB MIDI driver is integrated in the usb-audio driver. - -
- -
- pcmcia directory - - The PCMCIA, especially PCCard drivers will go here. CardBus - drivers will be in the pci directory, because their API is identical - to that of standard PCI cards. - -
- -
- oss directory - - The OSS/Lite source files are stored here in Linux 2.6 (or - later) tree. In the ALSA driver tarball, this directory is empty, - of course :) - -
- - - - - - - - Basic Flow for PCI Drivers - -
- Outline - - The minimum flow for PCI soundcards is as follows: - - - define the PCI ID table (see the section - PCI Entries - ). - create probe() callback. - create remove() callback. - create a pci_driver structure - containing the three pointers above. - create an init() function just calling - the pci_register_driver() to register the pci_driver table - defined above. - create an exit() function to call - the pci_unregister_driver() function. - - -
- -
- Full Code Example - - The code example is shown below. Some parts are kept - unimplemented at this moment but will be filled in the - next sections. The numbers in the comment lines of the - snd_mychip_probe() function - refer to details explained in the following section. - - - Basic Flow for PCI Drivers - Example - - - #include - #include - #include - #include - - /* module parameters (see "Module Parameters") */ - /* SNDRV_CARDS: maximum number of cards supported by this module */ - static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX; - static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR; - static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP; - - /* definition of the chip-specific record */ - struct mychip { - struct snd_card *card; - /* the rest of the implementation will be in section - * "PCI Resource Management" - */ - }; - - /* chip-specific destructor - * (see "PCI Resource Management") - */ - static int snd_mychip_free(struct mychip *chip) - { - .... /* will be implemented later... */ - } - - /* component-destructor - * (see "Management of Cards and Components") - */ - static int snd_mychip_dev_free(struct snd_device *device) - { - return snd_mychip_free(device->device_data); - } - - /* chip-specific constructor - * (see "Management of Cards and Components") - */ - static int snd_mychip_create(struct snd_card *card, - struct pci_dev *pci, - struct mychip **rchip) - { - struct mychip *chip; - int err; - static struct snd_device_ops ops = { - .dev_free = snd_mychip_dev_free, - }; - - *rchip = NULL; - - /* check PCI availability here - * (see "PCI Resource Management") - */ - .... - - /* allocate a chip-specific data with zero filled */ - chip = kzalloc(sizeof(*chip), GFP_KERNEL); - if (chip == NULL) - return -ENOMEM; - - chip->card = card; - - /* rest of initialization here; will be implemented - * later, see "PCI Resource Management" - */ - .... - - err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops); - if (err < 0) { - snd_mychip_free(chip); - return err; - } - - *rchip = chip; - return 0; - } - - /* constructor -- see "Constructor" sub-section */ - static int snd_mychip_probe(struct pci_dev *pci, - const struct pci_device_id *pci_id) - { - static int dev; - struct snd_card *card; - struct mychip *chip; - int err; - - /* (1) */ - if (dev >= SNDRV_CARDS) - return -ENODEV; - if (!enable[dev]) { - dev++; - return -ENOENT; - } - - /* (2) */ - err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, - 0, &card); - if (err < 0) - return err; - - /* (3) */ - err = snd_mychip_create(card, pci, &chip); - if (err < 0) { - snd_card_free(card); - return err; - } - - /* (4) */ - strcpy(card->driver, "My Chip"); - strcpy(card->shortname, "My Own Chip 123"); - sprintf(card->longname, "%s at 0x%lx irq %i", - card->shortname, chip->ioport, chip->irq); - - /* (5) */ - .... /* implemented later */ - - /* (6) */ - err = snd_card_register(card); - if (err < 0) { - snd_card_free(card); - return err; - } - - /* (7) */ - pci_set_drvdata(pci, card); - dev++; - return 0; - } - - /* destructor -- see the "Destructor" sub-section */ - static void snd_mychip_remove(struct pci_dev *pci) - { - snd_card_free(pci_get_drvdata(pci)); - pci_set_drvdata(pci, NULL); - } -]]> - - - -
- -
- Constructor - - The real constructor of PCI drivers is the probe callback. - The probe callback and other component-constructors which are called - from the probe callback cannot be used with - the __init prefix - because any PCI device could be a hotplug device. - - - - In the probe callback, the following scheme is often used. - - -
- 1) Check and increment the device index. - - - -= SNDRV_CARDS) - return -ENODEV; - if (!enable[dev]) { - dev++; - return -ENOENT; - } -]]> - - - - where enable[dev] is the module option. - - - - Each time the probe callback is called, check the - availability of the device. If not available, simply increment - the device index and returns. dev will be incremented also - later (step - 7). - -
- -
- 2) Create a card instance - - - -dev, index[dev], id[dev], THIS_MODULE, - 0, &card); -]]> - - - - - - The details will be explained in the section - - Management of Cards and Components. - -
- -
- 3) Create a main component - - In this part, the PCI resources are allocated. - - - - - - - - The details will be explained in the section PCI Resource - Management. - -
- -
- 4) Set the driver ID and name strings. - - - -driver, "My Chip"); - strcpy(card->shortname, "My Own Chip 123"); - sprintf(card->longname, "%s at 0x%lx irq %i", - card->shortname, chip->ioport, chip->irq); -]]> - - - - The driver field holds the minimal ID string of the - chip. This is used by alsa-lib's configurator, so keep it - simple but unique. - Even the same driver can have different driver IDs to - distinguish the functionality of each chip type. - - - - The shortname field is a string shown as more verbose - name. The longname field contains the information - shown in /proc/asound/cards. - -
- -
- 5) Create other components, such as mixer, MIDI, etc. - - Here you define the basic components such as - PCM, - mixer (e.g. AC97), - MIDI (e.g. MPU-401), - and other interfaces. - Also, if you want a proc - file, define it here, too. - -
- -
- 6) Register the card instance. - - - - - - - - - - Will be explained in the section Management - of Cards and Components, too. - -
- -
- 7) Set the PCI driver data and return zero. - - - - - - - - In the above, the card record is stored. This pointer is - used in the remove callback and power-management - callbacks, too. - -
-
- -
- Destructor - - The destructor, remove callback, simply releases the card - instance. Then the ALSA middle layer will release all the - attached components automatically. - - - - It would be typically like the following: - - - - - - - - The above code assumes that the card pointer is set to the PCI - driver data. - -
- -
- Header Files - - For the above example, at least the following include files - are necessary. - - - - - #include - #include - #include - #include -]]> - - - - where the last one is necessary only when module options are - defined in the source file. If the code is split into several - files, the files without module options don't need them. - - - - In addition to these headers, you'll need - <linux/interrupt.h> for interrupt - handling, and <asm/io.h> for I/O - access. If you use the mdelay() or - udelay() functions, you'll need to include - <linux/delay.h> too. - - - - The ALSA interfaces like the PCM and control APIs are defined in other - <sound/xxx.h> header files. - They have to be included after - <sound/core.h>. - - -
- - - - - - - - Management of Cards and Components - -
- Card Instance - - For each soundcard, a card record must be allocated. - - - - A card record is the headquarters of the soundcard. It manages - the whole list of devices (components) on the soundcard, such as - PCM, mixers, MIDI, synthesizer, and so on. Also, the card - record holds the ID and the name strings of the card, manages - the root of proc files, and controls the power-management states - and hotplug disconnections. The component list on the card - record is used to manage the correct release of resources at - destruction. - - - - As mentioned above, to create a card instance, call - snd_card_new(). - - - -dev, index, id, module, extra_size, &card); -]]> - - - - - - The function takes six arguments: the parent device pointer, - the card-index number, the id string, the module pointer (usually - THIS_MODULE), - the size of extra-data space, and the pointer to return the - card instance. The extra_size argument is used to - allocate card->private_data for the - chip-specific data. Note that these data - are allocated by snd_card_new(). - - - - The first argument, the pointer of struct - device, specifies the parent device. - For PCI devices, typically &pci-> is passed there. - -
- -
- Components - - After the card is created, you can attach the components - (devices) to the card instance. In an ALSA driver, a component is - represented as a struct snd_device object. - A component can be a PCM instance, a control interface, a raw - MIDI interface, etc. Each such instance has one component - entry. - - - - A component can be created via - snd_device_new() function. - - - - - - - - - - This takes the card pointer, the device-level - (SNDRV_DEV_XXX), the data pointer, and the - callback pointers (&ops). The - device-level defines the type of components and the order of - registration and de-registration. For most components, the - device-level is already defined. For a user-defined component, - you can use SNDRV_DEV_LOWLEVEL. - - - - This function itself doesn't allocate the data space. The data - must be allocated manually beforehand, and its pointer is passed - as the argument. This pointer (chip in the - above example) is used as the identifier for the instance. - - - - Each pre-defined ALSA component such as ac97 and pcm calls - snd_device_new() inside its - constructor. The destructor for each component is defined in the - callback pointers. Hence, you don't need to take care of - calling a destructor for such a component. - - - - If you wish to create your own component, you need to - set the destructor function to the dev_free callback in - the ops, so that it can be released - automatically via snd_card_free(). - The next example will show an implementation of chip-specific - data. - -
- -
- Chip-Specific Data - - Chip-specific information, e.g. the I/O port address, its - resource pointer, or the irq number, is stored in the - chip-specific record. - - - - - - - - - - In general, there are two ways of allocating the chip record. - - -
- 1. Allocating via <function>snd_card_new()</function>. - - As mentioned above, you can pass the extra-data-length - to the 5th argument of snd_card_new(), i.e. - - - -dev, index[dev], id[dev], THIS_MODULE, - sizeof(struct mychip), &card); -]]> - - - - struct mychip is the type of the chip record. - - - - In return, the allocated record can be accessed as - - - -private_data; -]]> - - - - With this method, you don't have to allocate twice. - The record is released together with the card instance. - -
- -
- 2. Allocating an extra device. - - - After allocating a card instance via - snd_card_new() (with - 0 on the 4th arg), call - kzalloc(). - - - -dev, index[dev], id[dev], THIS_MODULE, - 0, &card); - ..... - chip = kzalloc(sizeof(*chip), GFP_KERNEL); -]]> - - - - - - The chip record should have the field to hold the card - pointer at least, - - - - - - - - - - Then, set the card pointer in the returned chip instance. - - - -card = card; -]]> - - - - - - Next, initialize the fields, and register this chip - record as a low-level device with a specified - ops, - - - - - - - - snd_mychip_dev_free() is the - device-destructor function, which will call the real - destructor. - - - - - -device_data); - } -]]> - - - - where snd_mychip_free() is the real destructor. - -
-
- -
- Registration and Release - - After all components are assigned, register the card instance - by calling snd_card_register(). Access - to the device files is enabled at this point. That is, before - snd_card_register() is called, the - components are safely inaccessible from external side. If this - call fails, exit the probe function after releasing the card via - snd_card_free(). - - - - For releasing the card instance, you can call simply - snd_card_free(). As mentioned earlier, all - components are released automatically by this call. - - - - For a device which allows hotplugging, you can use - snd_card_free_when_closed. This one will - postpone the destruction until all devices are closed. - - -
- - - - - - - - - PCI Resource Management - -
- Full Code Example - - In this section, we'll complete the chip-specific constructor, - destructor and PCI entries. Example code is shown first, - below. - - - PCI Resource Management Example - -irq >= 0) - free_irq(chip->irq, chip); - /* release the I/O ports & memory */ - pci_release_regions(chip->pci); - /* disable the PCI entry */ - pci_disable_device(chip->pci); - /* release the data */ - kfree(chip); - return 0; - } - - /* chip-specific constructor */ - static int snd_mychip_create(struct snd_card *card, - struct pci_dev *pci, - struct mychip **rchip) - { - struct mychip *chip; - int err; - static struct snd_device_ops ops = { - .dev_free = snd_mychip_dev_free, - }; - - *rchip = NULL; - - /* initialize the PCI entry */ - err = pci_enable_device(pci); - if (err < 0) - return err; - /* check PCI availability (28bit DMA) */ - if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 || - pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) { - printk(KERN_ERR "error to set 28bit mask DMA\n"); - pci_disable_device(pci); - return -ENXIO; - } - - chip = kzalloc(sizeof(*chip), GFP_KERNEL); - if (chip == NULL) { - pci_disable_device(pci); - return -ENOMEM; - } - - /* initialize the stuff */ - chip->card = card; - chip->pci = pci; - chip->irq = -1; - - /* (1) PCI resource allocation */ - err = pci_request_regions(pci, "My Chip"); - if (err < 0) { - kfree(chip); - pci_disable_device(pci); - return err; - } - chip->port = pci_resource_start(pci, 0); - if (request_irq(pci->irq, snd_mychip_interrupt, - IRQF_SHARED, KBUILD_MODNAME, chip)) { - printk(KERN_ERR "cannot grab irq %d\n", pci->irq); - snd_mychip_free(chip); - return -EBUSY; - } - chip->irq = pci->irq; - - /* (2) initialization of the chip hardware */ - .... /* (not implemented in this document) */ - - err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops); - if (err < 0) { - snd_mychip_free(chip); - return err; - } - - *rchip = chip; - return 0; - } - - /* PCI IDs */ - static struct pci_device_id snd_mychip_ids[] = { - { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR, - PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, }, - .... - { 0, } - }; - MODULE_DEVICE_TABLE(pci, snd_mychip_ids); - - /* pci_driver definition */ - static struct pci_driver driver = { - .name = KBUILD_MODNAME, - .id_table = snd_mychip_ids, - .probe = snd_mychip_probe, - .remove = snd_mychip_remove, - }; - - /* module initialization */ - static int __init alsa_card_mychip_init(void) - { - return pci_register_driver(&driver); - } - - /* module clean up */ - static void __exit alsa_card_mychip_exit(void) - { - pci_unregister_driver(&driver); - } - - module_init(alsa_card_mychip_init) - module_exit(alsa_card_mychip_exit) - - EXPORT_NO_SYMBOLS; /* for old kernels only */ -]]> - - - -
- -
- Some Hafta's - - The allocation of PCI resources is done in the - probe() function, and usually an extra - xxx_create() function is written for this - purpose. - - - - In the case of PCI devices, you first have to call - the pci_enable_device() function before - allocating resources. Also, you need to set the proper PCI DMA - mask to limit the accessed I/O range. In some cases, you might - need to call pci_set_master() function, - too. - - - - Suppose the 28bit mask, and the code to be added would be like: - - - - - - - -
- -
- Resource Allocation - - The allocation of I/O ports and irqs is done via standard kernel - functions. Unlike ALSA ver.0.5.x., there are no helpers for - that. And these resources must be released in the destructor - function (see below). Also, on ALSA 0.9.x, you don't need to - allocate (pseudo-)DMA for PCI like in ALSA 0.5.x. - - - - Now assume that the PCI device has an I/O port with 8 bytes - and an interrupt. Then struct mychip will have the - following fields: - - - - - - - - - - For an I/O port (and also a memory region), you need to have - the resource pointer for the standard resource management. For - an irq, you have to keep only the irq number (integer). But you - need to initialize this number as -1 before actual allocation, - since irq 0 is valid. The port address and its resource pointer - can be initialized as null by - kzalloc() automatically, so you - don't have to take care of resetting them. - - - - The allocation of an I/O port is done like this: - - - -port = pci_resource_start(pci, 0); -]]> - - - - - - - It will reserve the I/O port region of 8 bytes of the given - PCI device. The returned value, chip->res_port, is allocated - via kmalloc() by - request_region(). The pointer must be - released via kfree(), but there is a - problem with this. This issue will be explained later. - - - - The allocation of an interrupt source is done like this: - - - -irq, snd_mychip_interrupt, - IRQF_SHARED, KBUILD_MODNAME, chip)) { - printk(KERN_ERR "cannot grab irq %d\n", pci->irq); - snd_mychip_free(chip); - return -EBUSY; - } - chip->irq = pci->irq; -]]> - - - - where snd_mychip_interrupt() is the - interrupt handler defined later. - Note that chip->irq should be defined - only when request_irq() succeeded. - - - - On the PCI bus, interrupts can be shared. Thus, - IRQF_SHARED is used as the interrupt flag of - request_irq(). - - - - The last argument of request_irq() is the - data pointer passed to the interrupt handler. Usually, the - chip-specific record is used for that, but you can use what you - like, too. - - - - I won't give details about the interrupt handler at this - point, but at least its appearance can be explained now. The - interrupt handler looks usually like the following: - - - - - - - - - - Now let's write the corresponding destructor for the resources - above. The role of destructor is simple: disable the hardware - (if already activated) and release the resources. So far, we - have no hardware part, so the disabling code is not written here. - - - - To release the resources, the check-and-release - method is a safer way. For the interrupt, do like this: - - - -irq >= 0) - free_irq(chip->irq, chip); -]]> - - - - Since the irq number can start from 0, you should initialize - chip->irq with a negative value (e.g. -1), so that you can - check the validity of the irq number as above. - - - - When you requested I/O ports or memory regions via - pci_request_region() or - pci_request_regions() like in this example, - release the resource(s) using the corresponding function, - pci_release_region() or - pci_release_regions(). - - - -pci); -]]> - - - - - - When you requested manually via request_region() - or request_mem_region, you can release it via - release_resource(). Suppose that you keep - the resource pointer returned from request_region() - in chip->res_port, the release procedure looks like: - - - -res_port); -]]> - - - - - - Don't forget to call pci_disable_device() - before the end. - - - - And finally, release the chip-specific record. - - - - - - - - - - We didn't implement the hardware disabling part in the above. - If you need to do this, please note that the destructor may be - called even before the initialization of the chip is completed. - It would be better to have a flag to skip hardware disabling - if the hardware was not initialized yet. - - - - When the chip-data is assigned to the card using - snd_device_new() with - SNDRV_DEV_LOWLELVEL , its destructor is - called at the last. That is, it is assured that all other - components like PCMs and controls have already been released. - You don't have to stop PCMs, etc. explicitly, but just - call low-level hardware stopping. - - - - The management of a memory-mapped region is almost as same as - the management of an I/O port. You'll need three fields like - the following: - - - - - - - - and the allocation would be like below: - - - -iobase_phys = pci_resource_start(pci, 0); - chip->iobase_virt = ioremap_nocache(chip->iobase_phys, - pci_resource_len(pci, 0)); -]]> - - - - and the corresponding destructor would be: - - - -iobase_virt) - iounmap(chip->iobase_virt); - .... - pci_release_regions(chip->pci); - .... - } -]]> - - - - -
- -
- PCI Entries - - So far, so good. Let's finish the missing PCI - stuff. At first, we need a - pci_device_id table for this - chipset. It's a table of PCI vendor/device ID number, and some - masks. - - - - For example, - - - - - - - - - - The first and second fields of - the pci_device_id structure are the vendor and - device IDs. If you have no reason to filter the matching - devices, you can leave the remaining fields as above. The last - field of the pci_device_id struct contains - private data for this entry. You can specify any value here, for - example, to define specific operations for supported device IDs. - Such an example is found in the intel8x0 driver. - - - - The last entry of this list is the terminator. You must - specify this all-zero entry. - - - - Then, prepare the pci_driver record: - - - - - - - - - - The probe and - remove functions have already - been defined in the previous sections. - The name - field is the name string of this device. Note that you must not - use a slash / in this string. - - - - And at last, the module entries: - - - - - - - - - - Note that these module entries are tagged with - __init and - __exit prefixes. - - - - Oh, one thing was forgotten. If you have no exported symbols, - you need to declare it in 2.2 or 2.4 kernels (it's not necessary in 2.6 kernels). - - - - - - - - That's all! - -
- - - - - - - - PCM Interface - -
- General - - The PCM middle layer of ALSA is quite powerful and it is only - necessary for each driver to implement the low-level functions - to access its hardware. - - - - For accessing to the PCM layer, you need to include - <sound/pcm.h> first. In addition, - <sound/pcm_params.h> might be needed - if you access to some functions related with hw_param. - - - - Each card device can have up to four pcm instances. A pcm - instance corresponds to a pcm device file. The limitation of - number of instances comes only from the available bit size of - the Linux's device numbers. Once when 64bit device number is - used, we'll have more pcm instances available. - - - - A pcm instance consists of pcm playback and capture streams, - and each pcm stream consists of one or more pcm substreams. Some - soundcards support multiple playback functions. For example, - emu10k1 has a PCM playback of 32 stereo substreams. In this case, at - each open, a free substream is (usually) automatically chosen - and opened. Meanwhile, when only one substream exists and it was - already opened, the successful open will either block - or error with EAGAIN according to the - file open mode. But you don't have to care about such details in your - driver. The PCM middle layer will take care of such work. - -
- -
- Full Code Example - - The example code below does not include any hardware access - routines but shows only the skeleton, how to build up the PCM - interfaces. - - - PCM Example Code - - - .... - - /* hardware definition */ - static struct snd_pcm_hardware snd_mychip_playback_hw = { - .info = (SNDRV_PCM_INFO_MMAP | - SNDRV_PCM_INFO_INTERLEAVED | - SNDRV_PCM_INFO_BLOCK_TRANSFER | - SNDRV_PCM_INFO_MMAP_VALID), - .formats = SNDRV_PCM_FMTBIT_S16_LE, - .rates = SNDRV_PCM_RATE_8000_48000, - .rate_min = 8000, - .rate_max = 48000, - .channels_min = 2, - .channels_max = 2, - .buffer_bytes_max = 32768, - .period_bytes_min = 4096, - .period_bytes_max = 32768, - .periods_min = 1, - .periods_max = 1024, - }; - - /* hardware definition */ - static struct snd_pcm_hardware snd_mychip_capture_hw = { - .info = (SNDRV_PCM_INFO_MMAP | - SNDRV_PCM_INFO_INTERLEAVED | - SNDRV_PCM_INFO_BLOCK_TRANSFER | - SNDRV_PCM_INFO_MMAP_VALID), - .formats = SNDRV_PCM_FMTBIT_S16_LE, - .rates = SNDRV_PCM_RATE_8000_48000, - .rate_min = 8000, - .rate_max = 48000, - .channels_min = 2, - .channels_max = 2, - .buffer_bytes_max = 32768, - .period_bytes_min = 4096, - .period_bytes_max = 32768, - .periods_min = 1, - .periods_max = 1024, - }; - - /* open callback */ - static int snd_mychip_playback_open(struct snd_pcm_substream *substream) - { - struct mychip *chip = snd_pcm_substream_chip(substream); - struct snd_pcm_runtime *runtime = substream->runtime; - - runtime->hw = snd_mychip_playback_hw; - /* more hardware-initialization will be done here */ - .... - return 0; - } - - /* close callback */ - static int snd_mychip_playback_close(struct snd_pcm_substream *substream) - { - struct mychip *chip = snd_pcm_substream_chip(substream); - /* the hardware-specific codes will be here */ - .... - return 0; - - } - - /* open callback */ - static int snd_mychip_capture_open(struct snd_pcm_substream *substream) - { - struct mychip *chip = snd_pcm_substream_chip(substream); - struct snd_pcm_runtime *runtime = substream->runtime; - - runtime->hw = snd_mychip_capture_hw; - /* more hardware-initialization will be done here */ - .... - return 0; - } - - /* close callback */ - static int snd_mychip_capture_close(struct snd_pcm_substream *substream) - { - struct mychip *chip = snd_pcm_substream_chip(substream); - /* the hardware-specific codes will be here */ - .... - return 0; - - } - - /* hw_params callback */ - static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream, - struct snd_pcm_hw_params *hw_params) - { - return snd_pcm_lib_malloc_pages(substream, - params_buffer_bytes(hw_params)); - } - - /* hw_free callback */ - static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream) - { - return snd_pcm_lib_free_pages(substream); - } - - /* prepare callback */ - static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream) - { - struct mychip *chip = snd_pcm_substream_chip(substream); - struct snd_pcm_runtime *runtime = substream->runtime; - - /* set up the hardware with the current configuration - * for example... - */ - mychip_set_sample_format(chip, runtime->format); - mychip_set_sample_rate(chip, runtime->rate); - mychip_set_channels(chip, runtime->channels); - mychip_set_dma_setup(chip, runtime->dma_addr, - chip->buffer_size, - chip->period_size); - return 0; - } - - /* trigger callback */ - static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream, - int cmd) - { - switch (cmd) { - case SNDRV_PCM_TRIGGER_START: - /* do something to start the PCM engine */ - .... - break; - case SNDRV_PCM_TRIGGER_STOP: - /* do something to stop the PCM engine */ - .... - break; - default: - return -EINVAL; - } - } - - /* pointer callback */ - static snd_pcm_uframes_t - snd_mychip_pcm_pointer(struct snd_pcm_substream *substream) - { - struct mychip *chip = snd_pcm_substream_chip(substream); - unsigned int current_ptr; - - /* get the current hardware pointer */ - current_ptr = mychip_get_hw_pointer(chip); - return current_ptr; - } - - /* operators */ - static struct snd_pcm_ops snd_mychip_playback_ops = { - .open = snd_mychip_playback_open, - .close = snd_mychip_playback_close, - .ioctl = snd_pcm_lib_ioctl, - .hw_params = snd_mychip_pcm_hw_params, - .hw_free = snd_mychip_pcm_hw_free, - .prepare = snd_mychip_pcm_prepare, - .trigger = snd_mychip_pcm_trigger, - .pointer = snd_mychip_pcm_pointer, - }; - - /* operators */ - static struct snd_pcm_ops snd_mychip_capture_ops = { - .open = snd_mychip_capture_open, - .close = snd_mychip_capture_close, - .ioctl = snd_pcm_lib_ioctl, - .hw_params = snd_mychip_pcm_hw_params, - .hw_free = snd_mychip_pcm_hw_free, - .prepare = snd_mychip_pcm_prepare, - .trigger = snd_mychip_pcm_trigger, - .pointer = snd_mychip_pcm_pointer, - }; - - /* - * definitions of capture are omitted here... - */ - - /* create a pcm device */ - static int snd_mychip_new_pcm(struct mychip *chip) - { - struct snd_pcm *pcm; - int err; - - err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm); - if (err < 0) - return err; - pcm->private_data = chip; - strcpy(pcm->name, "My Chip"); - chip->pcm = pcm; - /* set operators */ - snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK, - &snd_mychip_playback_ops); - snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE, - &snd_mychip_capture_ops); - /* pre-allocation of buffers */ - /* NOTE: this may fail */ - snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV, - snd_dma_pci_data(chip->pci), - 64*1024, 64*1024); - return 0; - } -]]> - - - -
- -
- Constructor - - A pcm instance is allocated by the snd_pcm_new() - function. It would be better to create a constructor for pcm, - namely, - - - -card, "My Chip", 0, 1, 1, &pcm); - if (err < 0) - return err; - pcm->private_data = chip; - strcpy(pcm->name, "My Chip"); - chip->pcm = pcm; - .... - return 0; - } -]]> - - - - - - The snd_pcm_new() function takes four - arguments. The first argument is the card pointer to which this - pcm is assigned, and the second is the ID string. - - - - The third argument (index, 0 in the - above) is the index of this new pcm. It begins from zero. If - you create more than one pcm instances, specify the - different numbers in this argument. For example, - index = 1 for the second PCM device. - - - - The fourth and fifth arguments are the number of substreams - for playback and capture, respectively. Here 1 is used for - both arguments. When no playback or capture substreams are available, - pass 0 to the corresponding argument. - - - - If a chip supports multiple playbacks or captures, you can - specify more numbers, but they must be handled properly in - open/close, etc. callbacks. When you need to know which - substream you are referring to, then it can be obtained from - struct snd_pcm_substream data passed to each callback - as follows: - - - -number; -]]> - - - - - - After the pcm is created, you need to set operators for each - pcm stream. - - - - - - - - - - The operators are defined typically like this: - - - - - - - - All the callbacks are described in the - - Operators subsection. - - - - After setting the operators, you probably will want to - pre-allocate the buffer. For the pre-allocation, simply call - the following: - - - -pci), - 64*1024, 64*1024); -]]> - - - - It will allocate a buffer up to 64kB as default. - Buffer management details will be described in the later section Buffer and Memory - Management. - - - - Additionally, you can set some extra information for this pcm - in pcm->info_flags. - The available values are defined as - SNDRV_PCM_INFO_XXX in - <sound/asound.h>, which is used for - the hardware definition (described later). When your soundchip - supports only half-duplex, specify like this: - - - -info_flags = SNDRV_PCM_INFO_HALF_DUPLEX; -]]> - - - -
- -
- ... And the Destructor? - - The destructor for a pcm instance is not always - necessary. Since the pcm device will be released by the middle - layer code automatically, you don't have to call the destructor - explicitly. - - - - The destructor would be necessary if you created - special records internally and needed to release them. In such a - case, set the destructor function to - pcm->private_free: - - - PCM Instance with a Destructor - -my_private_pcm_data); - /* do what you like else */ - .... - } - - static int snd_mychip_new_pcm(struct mychip *chip) - { - struct snd_pcm *pcm; - .... - /* allocate your own data */ - chip->my_private_pcm_data = kmalloc(...); - /* set the destructor */ - pcm->private_data = chip; - pcm->private_free = mychip_pcm_free; - .... - } -]]> - - - -
- -
- Runtime Pointer - The Chest of PCM Information - - When the PCM substream is opened, a PCM runtime instance is - allocated and assigned to the substream. This pointer is - accessible via substream->runtime. - This runtime pointer holds most information you need - to control the PCM: the copy of hw_params and sw_params configurations, the buffer - pointers, mmap records, spinlocks, etc. - - - - The definition of runtime instance is found in - <sound/pcm.h>. Here are - the contents of this file: - - - - - - - - - For the operators (callbacks) of each sound driver, most of - these records are supposed to be read-only. Only the PCM - middle-layer changes / updates them. The exceptions are - the hardware description (hw) DMA buffer information and the - private data. Besides, if you use the standard buffer allocation - method via snd_pcm_lib_malloc_pages(), - you don't need to set the DMA buffer information by yourself. - - - - In the sections below, important records are explained. - - -
- Hardware Description - - The hardware descriptor (struct snd_pcm_hardware) - contains the definitions of the fundamental hardware - configuration. Above all, you'll need to define this in - - the open callback. - Note that the runtime instance holds the copy of the - descriptor, not the pointer to the existing descriptor. That - is, in the open callback, you can modify the copied descriptor - (runtime->hw) as you need. For example, if the maximum - number of channels is 1 only on some chip models, you can - still use the same hardware descriptor and change the - channels_max later: - - -runtime; - ... - runtime->hw = snd_mychip_playback_hw; /* common definition */ - if (chip->model == VERY_OLD_ONE) - runtime->hw.channels_max = 1; -]]> - - - - - - Typically, you'll have a hardware descriptor as below: - - - - - - - - - - - The info field contains the type and - capabilities of this pcm. The bit flags are defined in - <sound/asound.h> as - SNDRV_PCM_INFO_XXX. Here, at least, you - have to specify whether the mmap is supported and which - interleaved format is supported. - When the hardware supports mmap, add the - SNDRV_PCM_INFO_MMAP flag here. When the - hardware supports the interleaved or the non-interleaved - formats, SNDRV_PCM_INFO_INTERLEAVED or - SNDRV_PCM_INFO_NONINTERLEAVED flag must - be set, respectively. If both are supported, you can set both, - too. - - - - In the above example, MMAP_VALID and - BLOCK_TRANSFER are specified for the OSS mmap - mode. Usually both are set. Of course, - MMAP_VALID is set only if the mmap is - really supported. - - - - The other possible flags are - SNDRV_PCM_INFO_PAUSE and - SNDRV_PCM_INFO_RESUME. The - PAUSE bit means that the pcm supports the - pause operation, while the - RESUME bit means that the pcm supports - the full suspend/resume operation. - If the PAUSE flag is set, - the trigger callback below - must handle the corresponding (pause push/release) commands. - The suspend/resume trigger commands can be defined even without - the RESUME flag. See - Power Management section for details. - - - - When the PCM substreams can be synchronized (typically, - synchronized start/stop of a playback and a capture streams), - you can give SNDRV_PCM_INFO_SYNC_START, - too. In this case, you'll need to check the linked-list of - PCM substreams in the trigger callback. This will be - described in the later section. - - - - - - formats field contains the bit-flags - of supported formats (SNDRV_PCM_FMTBIT_XXX). - If the hardware supports more than one format, give all or'ed - bits. In the example above, the signed 16bit little-endian - format is specified. - - - - - - rates field contains the bit-flags of - supported rates (SNDRV_PCM_RATE_XXX). - When the chip supports continuous rates, pass - CONTINUOUS bit additionally. - The pre-defined rate bits are provided only for typical - rates. If your chip supports unconventional rates, you need to add - the KNOT bit and set up the hardware - constraint manually (explained later). - - - - - - rate_min and - rate_max define the minimum and - maximum sample rate. This should correspond somehow to - rates bits. - - - - - - channel_min and - channel_max - define, as you might already expected, the minimum and maximum - number of channels. - - - - - - buffer_bytes_max defines the - maximum buffer size in bytes. There is no - buffer_bytes_min field, since - it can be calculated from the minimum period size and the - minimum number of periods. - Meanwhile, period_bytes_min and - define the minimum and maximum size of the period in bytes. - periods_max and - periods_min define the maximum and - minimum number of periods in the buffer. - - - - The period is a term that corresponds to - a fragment in the OSS world. The period defines the size at - which a PCM interrupt is generated. This size strongly - depends on the hardware. - Generally, the smaller period size will give you more - interrupts, that is, more controls. - In the case of capture, this size defines the input latency. - On the other hand, the whole buffer size defines the - output latency for the playback direction. - - - - - - There is also a field fifo_size. - This specifies the size of the hardware FIFO, but currently it - is neither used in the driver nor in the alsa-lib. So, you - can ignore this field. - - - - -
- -
- PCM Configurations - - Ok, let's go back again to the PCM runtime records. - The most frequently referred records in the runtime instance are - the PCM configurations. - The PCM configurations are stored in the runtime instance - after the application sends hw_params data via - alsa-lib. There are many fields copied from hw_params and - sw_params structs. For example, - format holds the format type - chosen by the application. This field contains the enum value - SNDRV_PCM_FORMAT_XXX. - - - - One thing to be noted is that the configured buffer and period - sizes are stored in frames in the runtime. - In the ALSA world, 1 frame = channels * samples-size. - For conversion between frames and bytes, you can use the - frames_to_bytes() and - bytes_to_frames() helper functions. - - -period_size); -]]> - - - - - - Also, many software parameters (sw_params) are - stored in frames, too. Please check the type of the field. - snd_pcm_uframes_t is for the frames as unsigned - integer while snd_pcm_sframes_t is for the frames - as signed integer. - -
- -
- DMA Buffer Information - - The DMA buffer is defined by the following four fields, - dma_area, - dma_addr, - dma_bytes and - dma_private. - The dma_area holds the buffer - pointer (the logical address). You can call - memcpy from/to - this pointer. Meanwhile, dma_addr - holds the physical address of the buffer. This field is - specified only when the buffer is a linear buffer. - dma_bytes holds the size of buffer - in bytes. dma_private is used for - the ALSA DMA allocator. - - - - If you use a standard ALSA function, - snd_pcm_lib_malloc_pages(), for - allocating the buffer, these fields are set by the ALSA middle - layer, and you should not change them by - yourself. You can read them but not write them. - On the other hand, if you want to allocate the buffer by - yourself, you'll need to manage it in hw_params callback. - At least, dma_bytes is mandatory. - dma_area is necessary when the - buffer is mmapped. If your driver doesn't support mmap, this - field is not necessary. dma_addr - is also optional. You can use - dma_private as you like, too. - -
- -
- Running Status - - The running status can be referred via runtime->status. - This is the pointer to the struct snd_pcm_mmap_status - record. For example, you can get the current DMA hardware - pointer via runtime->status->hw_ptr. - - - - The DMA application pointer can be referred via - runtime->control, which points to the - struct snd_pcm_mmap_control record. - However, accessing directly to this value is not recommended. - -
- -
- Private Data - - You can allocate a record for the substream and store it in - runtime->private_data. Usually, this - is done in - - the open callback. - Don't mix this with pcm->private_data. - The pcm->private_data usually points to the - chip instance assigned statically at the creation of PCM, while the - runtime->private_data points to a dynamic - data structure created at the PCM open callback. - - - -runtime->private_data = data; - .... - } -]]> - - - - - - The allocated object must be released in - - the close callback. - -
- -
- -
- Operators - - OK, now let me give details about each pcm callback - (ops). In general, every callback must - return 0 if successful, or a negative error number - such as -EINVAL. To choose an appropriate - error number, it is advised to check what value other parts of - the kernel return when the same kind of request fails. - - - - The callback function takes at least the argument with - snd_pcm_substream pointer. To retrieve - the chip record from the given substream instance, you can use the - following macro. - - - - - - - - The macro reads substream->private_data, - which is a copy of pcm->private_data. - You can override the former if you need to assign different data - records per PCM substream. For example, the cmi8330 driver assigns - different private_data for playback and capture directions, - because it uses two different codecs (SB- and AD-compatible) for - different directions. - - -
- open callback - - - - - - - - This is called when a pcm substream is opened. - - - - At least, here you have to initialize the runtime->hw - record. Typically, this is done by like this: - - - -runtime; - - runtime->hw = snd_mychip_playback_hw; - return 0; - } -]]> - - - - where snd_mychip_playback_hw is the - pre-defined hardware description. - - - - You can allocate a private data in this callback, as described - in - Private Data section. - - - - If the hardware configuration needs more constraints, set the - hardware constraints here, too. - See - Constraints for more details. - -
- -
- close callback - - - - - - - - Obviously, this is called when a pcm substream is closed. - - - - Any private instance for a pcm substream allocated in the - open callback will be released here. - - - -runtime->private_data); - .... - } -]]> - - - -
- -
- ioctl callback - - This is used for any special call to pcm ioctls. But - usually you can pass a generic ioctl callback, - snd_pcm_lib_ioctl. - -
- -
- hw_params callback - - - - - - - - - - This is called when the hardware parameter - (hw_params) is set - up by the application, - that is, once when the buffer size, the period size, the - format, etc. are defined for the pcm substream. - - - - Many hardware setups should be done in this callback, - including the allocation of buffers. - - - - Parameters to be initialized are retrieved by - params_xxx() macros. To allocate - buffer, you can call a helper function, - - - - - - - - snd_pcm_lib_malloc_pages() is available - only when the DMA buffers have been pre-allocated. - See the section - Buffer Types for more details. - - - - Note that this and prepare callbacks - may be called multiple times per initialization. - For example, the OSS emulation may - call these callbacks at each change via its ioctl. - - - - Thus, you need to be careful not to allocate the same buffers - many times, which will lead to memory leaks! Calling the - helper function above many times is OK. It will release the - previous buffer automatically when it was already allocated. - - - - Another note is that this callback is non-atomic - (schedulable) as default, i.e. when no - nonatomic flag set. - This is important, because the - trigger callback - is atomic (non-schedulable). That is, mutexes or any - schedule-related functions are not available in - trigger callback. - Please see the subsection - - Atomicity for details. - -
- -
- hw_free callback - - - - - - - - - - This is called to release the resources allocated via - hw_params. For example, releasing the - buffer via - snd_pcm_lib_malloc_pages() is done by - calling the following: - - - - - - - - - - This function is always called before the close callback is called. - Also, the callback may be called multiple times, too. - Keep track whether the resource was already released. - -
- -
- prepare callback - - - - - - - - - - This callback is called when the pcm is - prepared. You can set the format type, sample - rate, etc. here. The difference from - hw_params is that the - prepare callback will be called each - time - snd_pcm_prepare() is called, i.e. when - recovering after underruns, etc. - - - - Note that this callback is now non-atomic. - You can use schedule-related functions safely in this callback. - - - - In this and the following callbacks, you can refer to the - values via the runtime record, - substream->runtime. - For example, to get the current - rate, format or channels, access to - runtime->rate, - runtime->format or - runtime->channels, respectively. - The physical address of the allocated buffer is set to - runtime->dma_area. The buffer and period sizes are - in runtime->buffer_size and runtime->period_size, - respectively. - - - - Be careful that this callback will be called many times at - each setup, too. - -
- -
- trigger callback - - - - - - - - This is called when the pcm is started, stopped or paused. - - - - Which action is specified in the second argument, - SNDRV_PCM_TRIGGER_XXX in - <sound/pcm.h>. At least, - the START and STOP - commands must be defined in this callback. - - - - - - - - - - When the pcm supports the pause operation (given in the info - field of the hardware table), the PAUSE_PUSH - and PAUSE_RELEASE commands must be - handled here, too. The former is the command to pause the pcm, - and the latter to restart the pcm again. - - - - When the pcm supports the suspend/resume operation, - regardless of full or partial suspend/resume support, - the SUSPEND and RESUME - commands must be handled, too. - These commands are issued when the power-management status is - changed. Obviously, the SUSPEND and - RESUME commands - suspend and resume the pcm substream, and usually, they - are identical to the STOP and - START commands, respectively. - See the - Power Management section for details. - - - - As mentioned, this callback is atomic as default unless - nonatomic flag set, and - you cannot call functions which may sleep. - The trigger callback should be as minimal as possible, - just really triggering the DMA. The other stuff should be - initialized hw_params and prepare callbacks properly - beforehand. - -
- -
- pointer callback - - - - - - - - This callback is called when the PCM middle layer inquires - the current hardware position on the buffer. The position must - be returned in frames, - ranging from 0 to buffer_size - 1. - - - - This is called usually from the buffer-update routine in the - pcm middle layer, which is invoked when - snd_pcm_period_elapsed() is called in the - interrupt routine. Then the pcm middle layer updates the - position and calculates the available space, and wakes up the - sleeping poll threads, etc. - - - - This callback is also atomic as default. - -
- -
- copy and silence callbacks - - These callbacks are not mandatory, and can be omitted in - most cases. These callbacks are used when the hardware buffer - cannot be in the normal memory space. Some chips have their - own buffer on the hardware which is not mappable. In such a - case, you have to transfer the data manually from the memory - buffer to the hardware buffer. Or, if the buffer is - non-contiguous on both physical and virtual memory spaces, - these callbacks must be defined, too. - - - - If these two callbacks are defined, copy and set-silence - operations are done by them. The detailed will be described in - the later section Buffer and Memory - Management. - -
- -
- ack callback - - This callback is also not mandatory. This callback is called - when the appl_ptr is updated in read or write operations. - Some drivers like emu10k1-fx and cs46xx need to track the - current appl_ptr for the internal buffer, and this callback - is useful only for such a purpose. - - - This callback is atomic as default. - -
- -
- page callback - - - This callback is optional too. This callback is used - mainly for non-contiguous buffers. The mmap calls this - callback to get the page address. Some examples will be - explained in the later section Buffer and Memory - Management, too. - -
-
- -
- Interrupt Handler - - The rest of pcm stuff is the PCM interrupt handler. The - role of PCM interrupt handler in the sound driver is to update - the buffer position and to tell the PCM middle layer when the - buffer position goes across the prescribed period size. To - inform this, call the snd_pcm_period_elapsed() - function. - - - - There are several types of sound chips to generate the interrupts. - - -
- Interrupts at the period (fragment) boundary - - This is the most frequently found type: the hardware - generates an interrupt at each period boundary. - In this case, you can call - snd_pcm_period_elapsed() at each - interrupt. - - - - snd_pcm_period_elapsed() takes the - substream pointer as its argument. Thus, you need to keep the - substream pointer accessible from the chip instance. For - example, define substream field in the chip record to hold the - current running substream pointer, and set the pointer value - at open callback (and reset at close callback). - - - - If you acquire a spinlock in the interrupt handler, and the - lock is used in other pcm callbacks, too, then you have to - release the lock before calling - snd_pcm_period_elapsed(), because - snd_pcm_period_elapsed() calls other pcm - callbacks inside. - - - - Typical code would be like: - - - Interrupt Handler Case #1 - -lock); - .... - if (pcm_irq_invoked(chip)) { - /* call updater, unlock before it */ - spin_unlock(&chip->lock); - snd_pcm_period_elapsed(chip->substream); - spin_lock(&chip->lock); - /* acknowledge the interrupt if necessary */ - } - .... - spin_unlock(&chip->lock); - return IRQ_HANDLED; - } -]]> - - - -
- -
- High frequency timer interrupts - - This happens when the hardware doesn't generate interrupts - at the period boundary but issues timer interrupts at a fixed - timer rate (e.g. es1968 or ymfpci drivers). - In this case, you need to check the current hardware - position and accumulate the processed sample length at each - interrupt. When the accumulated size exceeds the period - size, call - snd_pcm_period_elapsed() and reset the - accumulator. - - - - Typical code would be like the following. - - - Interrupt Handler Case #2 - -lock); - .... - if (pcm_irq_invoked(chip)) { - unsigned int last_ptr, size; - /* get the current hardware pointer (in frames) */ - last_ptr = get_hw_ptr(chip); - /* calculate the processed frames since the - * last update - */ - if (last_ptr < chip->last_ptr) - size = runtime->buffer_size + last_ptr - - chip->last_ptr; - else - size = last_ptr - chip->last_ptr; - /* remember the last updated point */ - chip->last_ptr = last_ptr; - /* accumulate the size */ - chip->size += size; - /* over the period boundary? */ - if (chip->size >= runtime->period_size) { - /* reset the accumulator */ - chip->size %= runtime->period_size; - /* call updater */ - spin_unlock(&chip->lock); - snd_pcm_period_elapsed(substream); - spin_lock(&chip->lock); - } - /* acknowledge the interrupt if necessary */ - } - .... - spin_unlock(&chip->lock); - return IRQ_HANDLED; - } -]]> - - - -
- -
- On calling <function>snd_pcm_period_elapsed()</function> - - In both cases, even if more than one period are elapsed, you - don't have to call - snd_pcm_period_elapsed() many times. Call - only once. And the pcm layer will check the current hardware - pointer and update to the latest status. - -
-
- -
- Atomicity - - One of the most important (and thus difficult to debug) problems - in kernel programming are race conditions. - In the Linux kernel, they are usually avoided via spin-locks, mutexes - or semaphores. In general, if a race condition can happen - in an interrupt handler, it has to be managed atomically, and you - have to use a spinlock to protect the critical session. If the - critical section is not in interrupt handler code and - if taking a relatively long time to execute is acceptable, you - should use mutexes or semaphores instead. - - - - As already seen, some pcm callbacks are atomic and some are - not. For example, the hw_params callback is - non-atomic, while trigger callback is - atomic. This means, the latter is called already in a spinlock - held by the PCM middle layer. Please take this atomicity into - account when you choose a locking scheme in the callbacks. - - - - In the atomic callbacks, you cannot use functions which may call - schedule or go to - sleep. Semaphores and mutexes can sleep, - and hence they cannot be used inside the atomic callbacks - (e.g. trigger callback). - To implement some delay in such a callback, please use - udelay() or mdelay(). - - - - All three atomic callbacks (trigger, pointer, and ack) are - called with local interrupts disabled. - - - - The recent changes in PCM core code, however, allow all PCM - operations to be non-atomic. This assumes that the all caller - sides are in non-atomic contexts. For example, the function - snd_pcm_period_elapsed() is called - typically from the interrupt handler. But, if you set up the - driver to use a threaded interrupt handler, this call can be in - non-atomic context, too. In such a case, you can set - nonatomic filed of - snd_pcm object after creating it. - When this flag is set, mutex and rwsem are used internally in - the PCM core instead of spin and rwlocks, so that you can call - all PCM functions safely in a non-atomic context. - - -
-
- Constraints - - If your chip supports unconventional sample rates, or only the - limited samples, you need to set a constraint for the - condition. - - - - For example, in order to restrict the sample rates in the some - supported values, use - snd_pcm_hw_constraint_list(). - You need to call this function in the open callback. - - - Example of Hardware Constraints - -runtime, 0, - SNDRV_PCM_HW_PARAM_RATE, - &constraints_rates); - if (err < 0) - return err; - .... - } -]]> - - - - - - There are many different constraints. - Look at sound/pcm.h for a complete list. - You can even define your own constraint rules. - For example, let's suppose my_chip can manage a substream of 1 channel - if and only if the format is S16_LE, otherwise it supports any format - specified in the snd_pcm_hardware structure (or in any - other constraint_list). You can build a rule like this: - - - Example of Hardware Constraints for Channels - -bits[0] == SNDRV_PCM_FMTBIT_S16_LE) { - ch.min = ch.max = 1; - ch.integer = 1; - return snd_interval_refine(c, &ch); - } - return 0; - } -]]> - - - - - - Then you need to call this function to add your rule: - - - -runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS, - hw_rule_channels_by_format, NULL, - SNDRV_PCM_HW_PARAM_FORMAT, -1); -]]> - - - - - - The rule function is called when an application sets the PCM - format, and it refines the number of channels accordingly. - But an application may set the number of channels before - setting the format. Thus you also need to define the inverse rule: - - - Example of Hardware Constraints for Formats - -min < 2) { - fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE; - return snd_mask_refine(f, &fmt); - } - return 0; - } -]]> - - - - - - ...and in the open callback: - - -runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT, - hw_rule_format_by_channels, NULL, - SNDRV_PCM_HW_PARAM_CHANNELS, -1); -]]> - - - - - - I won't give more details here, rather I - would like to say, Luke, use the source. - -
- - - - - - - - - Control Interface - -
- General - - The control interface is used widely for many switches, - sliders, etc. which are accessed from user-space. Its most - important use is the mixer interface. In other words, since ALSA - 0.9.x, all the mixer stuff is implemented on the control kernel API. - - - - ALSA has a well-defined AC97 control module. If your chip - supports only the AC97 and nothing else, you can skip this - section. - - - - The control API is defined in - <sound/control.h>. - Include this file if you want to add your own controls. - -
- -
- Definition of Controls - - To create a new control, you need to define the - following three - callbacks: info, - get and - put. Then, define a - struct snd_kcontrol_new record, such as: - - - Definition of a Control - - - - - - - - The iface field specifies the control - type, SNDRV_CTL_ELEM_IFACE_XXX, which - is usually MIXER. - Use CARD for global controls that are not - logically part of the mixer. - If the control is closely associated with some specific device on - the sound card, use HWDEP, - PCM, RAWMIDI, - TIMER, or SEQUENCER, and - specify the device number with the - device and - subdevice fields. - - - - The name is the name identifier - string. Since ALSA 0.9.x, the control name is very important, - because its role is classified from its name. There are - pre-defined standard control names. The details are described in - the - Control Names subsection. - - - - The index field holds the index number - of this control. If there are several different controls with - the same name, they can be distinguished by the index - number. This is the case when - several codecs exist on the card. If the index is zero, you can - omit the definition above. - - - - The access field contains the access - type of this control. Give the combination of bit masks, - SNDRV_CTL_ELEM_ACCESS_XXX, there. - The details will be explained in - the - Access Flags subsection. - - - - The private_value field contains - an arbitrary long integer value for this record. When using - the generic info, - get and - put callbacks, you can pass a value - through this field. If several small numbers are necessary, you can - combine them in bitwise. Or, it's possible to give a pointer - (casted to unsigned long) of some record to this field, too. - - - - The tlv field can be used to provide - metadata about the control; see the - - Metadata subsection. - - - - The other three are - - callback functions. - -
- -
- Control Names - - There are some standards to define the control names. A - control is usually defined from the three parts as - SOURCE DIRECTION FUNCTION. - - - - The first, SOURCE, specifies the source - of the control, and is a string such as Master, - PCM, CD and - Line. There are many pre-defined sources. - - - - The second, DIRECTION, is one of the - following strings according to the direction of the control: - Playback, Capture, Bypass - Playback and Bypass Capture. Or, it can - be omitted, meaning both playback and capture directions. - - - - The third, FUNCTION, is one of the - following strings according to the function of the control: - Switch, Volume and - Route. - - - - The example of control names are, thus, Master Capture - Switch or PCM Playback Volume. - - - - There are some exceptions: - - -
- Global capture and playback - - Capture Source, Capture Switch - and Capture Volume are used for the global - capture (input) source, switch and volume. Similarly, - Playback Switch and Playback - Volume are used for the global output gain switch and - volume. - -
- -
- Tone-controls - - tone-control switch and volumes are specified like - Tone Control - XXX, e.g. Tone Control - - Switch, Tone Control - Bass, - Tone Control - Center. - -
- -
- 3D controls - - 3D-control switches and volumes are specified like 3D - Control - XXX, e.g. 3D Control - - Switch, 3D Control - Center, 3D - Control - Space. - -
- -
- Mic boost - - Mic-boost switch is set as Mic Boost or - Mic Boost (6dB). - - - - More precise information can be found in - Documentation/sound/alsa/ControlNames.txt. - -
-
- -
- Access Flags - - - The access flag is the bitmask which specifies the access type - of the given control. The default access type is - SNDRV_CTL_ELEM_ACCESS_READWRITE, - which means both read and write are allowed to this control. - When the access flag is omitted (i.e. = 0), it is - considered as READWRITE access as default. - - - - When the control is read-only, pass - SNDRV_CTL_ELEM_ACCESS_READ instead. - In this case, you don't have to define - the put callback. - Similarly, when the control is write-only (although it's a rare - case), you can use the WRITE flag instead, and - you don't need the get callback. - - - - If the control value changes frequently (e.g. the VU meter), - VOLATILE flag should be given. This means - that the control may be changed without - - notification. Applications should poll such - a control constantly. - - - - When the control is inactive, set - the INACTIVE flag, too. - There are LOCK and - OWNER flags to change the write - permissions. - - -
- -
- Callbacks - -
- info callback - - The info callback is used to get - detailed information on this control. This must store the - values of the given struct snd_ctl_elem_info - object. For example, for a boolean control with a single - element: - - - Example of info callback - -type = SNDRV_CTL_ELEM_TYPE_BOOLEAN; - uinfo->count = 1; - uinfo->value.integer.min = 0; - uinfo->value.integer.max = 1; - return 0; - } -]]> - - - - - - The type field specifies the type - of the control. There are BOOLEAN, - INTEGER, ENUMERATED, - BYTES, IEC958 and - INTEGER64. The - count field specifies the - number of elements in this control. For example, a stereo - volume would have count = 2. The - value field is a union, and - the values stored are depending on the type. The boolean and - integer types are identical. - - - - The enumerated type is a bit different from others. You'll - need to set the string for the currently given item index. - - - -type = SNDRV_CTL_ELEM_TYPE_ENUMERATED; - uinfo->count = 1; - uinfo->value.enumerated.items = 4; - if (uinfo->value.enumerated.item > 3) - uinfo->value.enumerated.item = 3; - strcpy(uinfo->value.enumerated.name, - texts[uinfo->value.enumerated.item]); - return 0; - } -]]> - - - - - - The above callback can be simplified with a helper function, - snd_ctl_enum_info. The final code - looks like below. - (You can pass ARRAY_SIZE(texts) instead of 4 in the third - argument; it's a matter of taste.) - - - - - - - - - - Some common info callbacks are available for your convenience: - snd_ctl_boolean_mono_info() and - snd_ctl_boolean_stereo_info(). - Obviously, the former is an info callback for a mono channel - boolean item, just like snd_myctl_mono_info - above, and the latter is for a stereo channel boolean item. - - -
- -
- get callback - - - This callback is used to read the current value of the - control and to return to user-space. - - - - For example, - - - Example of get callback - -value.integer.value[0] = get_some_value(chip); - return 0; - } -]]> - - - - - - The value field depends on - the type of control as well as on the info callback. For example, - the sb driver uses this field to store the register offset, - the bit-shift and the bit-mask. The - private_value field is set as follows: - - - - - - and is retrieved in callbacks like - - -private_value & 0xff; - int shift = (kcontrol->private_value >> 16) & 0xff; - int mask = (kcontrol->private_value >> 24) & 0xff; - .... - } -]]> - - - - - - In the get callback, - you have to fill all the elements if the - control has more than one elements, - i.e. count > 1. - In the example above, we filled only one element - (value.integer.value[0]) since it's - assumed as count = 1. - -
- -
- put callback - - - This callback is used to write a value from user-space. - - - - For example, - - - Example of put callback - -current_value != - ucontrol->value.integer.value[0]) { - change_current_value(chip, - ucontrol->value.integer.value[0]); - changed = 1; - } - return changed; - } -]]> - - - - As seen above, you have to return 1 if the value is - changed. If the value is not changed, return 0 instead. - If any fatal error happens, return a negative error code as - usual. - - - - As in the get callback, - when the control has more than one elements, - all elements must be evaluated in this callback, too. - -
- -
- Callbacks are not atomic - - All these three callbacks are basically not atomic. - -
-
- -
- Constructor - - When everything is ready, finally we can create a new - control. To create a control, there are two functions to be - called, snd_ctl_new1() and - snd_ctl_add(). - - - - In the simplest way, you can do like this: - - - - - - - - where my_control is the - struct snd_kcontrol_new object defined above, and chip - is the object pointer to be passed to - kcontrol->private_data - which can be referred to in callbacks. - - - - snd_ctl_new1() allocates a new - snd_kcontrol instance, - and snd_ctl_add assigns the given - control component to the card. - -
- -
- Change Notification - - If you need to change and update a control in the interrupt - routine, you can call snd_ctl_notify(). For - example, - - - - - - - - This function takes the card pointer, the event-mask, and the - control id pointer for the notification. The event-mask - specifies the types of notification, for example, in the above - example, the change of control values is notified. - The id pointer is the pointer of struct snd_ctl_elem_id - to be notified. - You can find some examples in es1938.c or - es1968.c for hardware volume interrupts. - -
- -
- Metadata - - To provide information about the dB values of a mixer control, use - on of the DECLARE_TLV_xxx macros from - <sound/tlv.h> to define a variable - containing this information, set thetlv.p - field to point to this variable, and include the - SNDRV_CTL_ELEM_ACCESS_TLV_READ flag in the - access field; like this: - - - - - - - - - The DECLARE_TLV_DB_SCALE macro defines - information about a mixer control where each step in the control's - value changes the dB value by a constant dB amount. - The first parameter is the name of the variable to be defined. - The second parameter is the minimum value, in units of 0.01 dB. - The third parameter is the step size, in units of 0.01 dB. - Set the fourth parameter to 1 if the minimum value actually mutes - the control. - - - - The DECLARE_TLV_DB_LINEAR macro defines - information about a mixer control where the control's value affects - the output linearly. - The first parameter is the name of the variable to be defined. - The second parameter is the minimum value, in units of 0.01 dB. - The third parameter is the maximum value, in units of 0.01 dB. - If the minimum value mutes the control, set the second parameter to - TLV_DB_GAIN_MUTE. - -
- - - - - - - - - API for AC97 Codec - -
- General - - The ALSA AC97 codec layer is a well-defined one, and you don't - have to write much code to control it. Only low-level control - routines are necessary. The AC97 codec API is defined in - <sound/ac97_codec.h>. - -
- -
- Full Code Example - - - Example of AC97 Interface - -private_data; - .... - /* read a register value here from the codec */ - return the_register_value; - } - - static void snd_mychip_ac97_write(struct snd_ac97 *ac97, - unsigned short reg, unsigned short val) - { - struct mychip *chip = ac97->private_data; - .... - /* write the given register value to the codec */ - } - - static int snd_mychip_ac97(struct mychip *chip) - { - struct snd_ac97_bus *bus; - struct snd_ac97_template ac97; - int err; - static struct snd_ac97_bus_ops ops = { - .write = snd_mychip_ac97_write, - .read = snd_mychip_ac97_read, - }; - - err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus); - if (err < 0) - return err; - memset(&ac97, 0, sizeof(ac97)); - ac97.private_data = chip; - return snd_ac97_mixer(bus, &ac97, &chip->ac97); - } - -]]> - - - -
- -
- Constructor - - To create an ac97 instance, first call snd_ac97_bus - with an ac97_bus_ops_t record with callback functions. - - - - - - - - The bus record is shared among all belonging ac97 instances. - - - - And then call snd_ac97_mixer() with an - struct snd_ac97_template - record together with the bus pointer created above. - - - -ac97); -]]> - - - - where chip->ac97 is a pointer to a newly created - ac97_t instance. - In this case, the chip pointer is set as the private data, so that - the read/write callback functions can refer to this chip instance. - This instance is not necessarily stored in the chip - record. If you need to change the register values from the - driver, or need the suspend/resume of ac97 codecs, keep this - pointer to pass to the corresponding functions. - -
- -
- Callbacks - - The standard callbacks are read and - write. Obviously they - correspond to the functions for read and write accesses to the - hardware low-level codes. - - - - The read callback returns the - register value specified in the argument. - - - -private_data; - .... - return the_register_value; - } -]]> - - - - Here, the chip can be cast from ac97->private_data. - - - - Meanwhile, the write callback is - used to set the register value. - - - - - - - - - - These callbacks are non-atomic like the control API callbacks. - - - - There are also other callbacks: - reset, - wait and - init. - - - - The reset callback is used to reset - the codec. If the chip requires a special kind of reset, you can - define this callback. - - - - The wait callback is used to - add some waiting time in the standard initialization of the codec. If the - chip requires the extra waiting time, define this callback. - - - - The init callback is used for - additional initialization of the codec. - -
- -
- Updating Registers in The Driver - - If you need to access to the codec from the driver, you can - call the following functions: - snd_ac97_write(), - snd_ac97_read(), - snd_ac97_update() and - snd_ac97_update_bits(). - - - - Both snd_ac97_write() and - snd_ac97_update() functions are used to - set a value to the given register - (AC97_XXX). The difference between them is - that snd_ac97_update() doesn't write a - value if the given value has been already set, while - snd_ac97_write() always rewrites the - value. - - - - - - - - - - snd_ac97_read() is used to read the value - of the given register. For example, - - - - - - - - - - snd_ac97_update_bits() is used to update - some bits in the given register. - - - - - - - - - - Also, there is a function to change the sample rate (of a - given register such as - AC97_PCM_FRONT_DAC_RATE) when VRA or - DRA is supported by the codec: - snd_ac97_set_rate(). - - - - - - - - - - The following registers are available to set the rate: - AC97_PCM_MIC_ADC_RATE, - AC97_PCM_FRONT_DAC_RATE, - AC97_PCM_LR_ADC_RATE, - AC97_SPDIF. When - AC97_SPDIF is specified, the register is - not really changed but the corresponding IEC958 status bits will - be updated. - -
- -
- Clock Adjustment - - In some chips, the clock of the codec isn't 48000 but using a - PCI clock (to save a quartz!). In this case, change the field - bus->clock to the corresponding - value. For example, intel8x0 - and es1968 drivers have their own function to read from the clock. - -
- -
- Proc Files - - The ALSA AC97 interface will create a proc file such as - /proc/asound/card0/codec97#0/ac97#0-0 and - ac97#0-0+regs. You can refer to these files to - see the current status and registers of the codec. - -
- -
- Multiple Codecs - - When there are several codecs on the same card, you need to - call snd_ac97_mixer() multiple times with - ac97.num=1 or greater. The num field - specifies the codec number. - - - - If you set up multiple codecs, you either need to write - different callbacks for each codec or check - ac97->num in the callback routines. - -
- - - - - - - - - MIDI (MPU401-UART) Interface - -
- General - - Many soundcards have built-in MIDI (MPU401-UART) - interfaces. When the soundcard supports the standard MPU401-UART - interface, most likely you can use the ALSA MPU401-UART API. The - MPU401-UART API is defined in - <sound/mpu401.h>. - - - - Some soundchips have a similar but slightly different - implementation of mpu401 stuff. For example, emu10k1 has its own - mpu401 routines. - -
- -
- Constructor - - To create a rawmidi object, call - snd_mpu401_uart_new(). - - - - - - - - - - The first argument is the card pointer, and the second is the - index of this component. You can create up to 8 rawmidi - devices. - - - - The third argument is the type of the hardware, - MPU401_HW_XXX. If it's not a special one, - you can use MPU401_HW_MPU401. - - - - The 4th argument is the I/O port address. Many - backward-compatible MPU401 have an I/O port such as 0x330. Or, it - might be a part of its own PCI I/O region. It depends on the - chip design. - - - - The 5th argument is a bitflag for additional information. - When the I/O port address above is part of the PCI I/O - region, the MPU401 I/O port might have been already allocated - (reserved) by the driver itself. In such a case, pass a bit flag - MPU401_INFO_INTEGRATED, - and the mpu401-uart layer will allocate the I/O ports by itself. - - - - When the controller supports only the input or output MIDI stream, - pass the MPU401_INFO_INPUT or - MPU401_INFO_OUTPUT bitflag, respectively. - Then the rawmidi instance is created as a single stream. - - - - MPU401_INFO_MMIO bitflag is used to change - the access method to MMIO (via readb and writeb) instead of - iob and outb. In this case, you have to pass the iomapped address - to snd_mpu401_uart_new(). - - - - When MPU401_INFO_TX_IRQ is set, the output - stream isn't checked in the default interrupt handler. The driver - needs to call snd_mpu401_uart_interrupt_tx() - by itself to start processing the output stream in the irq handler. - - - - If the MPU-401 interface shares its interrupt with the other logical - devices on the card, set MPU401_INFO_IRQ_HOOK - (see - below). - - - - Usually, the port address corresponds to the command port and - port + 1 corresponds to the data port. If not, you may change - the cport field of - struct snd_mpu401 manually - afterward. However, snd_mpu401 pointer is not - returned explicitly by - snd_mpu401_uart_new(). You need to cast - rmidi->private_data to - snd_mpu401 explicitly, - - - -private_data; -]]> - - - - and reset the cport as you like: - - - -cport = my_own_control_port; -]]> - - - - - - The 6th argument specifies the ISA irq number that will be - allocated. If no interrupt is to be allocated (because your - code is already allocating a shared interrupt, or because the - device does not use interrupts), pass -1 instead. - For a MPU-401 device without an interrupt, a polling timer - will be used instead. - -
- -
- Interrupt Handler - - When the interrupt is allocated in - snd_mpu401_uart_new(), an exclusive ISA - interrupt handler is automatically used, hence you don't have - anything else to do than creating the mpu401 stuff. Otherwise, you - have to set MPU401_INFO_IRQ_HOOK, and call - snd_mpu401_uart_interrupt() explicitly from your - own interrupt handler when it has determined that a UART interrupt - has occurred. - - - - In this case, you need to pass the private_data of the - returned rawmidi object from - snd_mpu401_uart_new() as the second - argument of snd_mpu401_uart_interrupt(). - - - -private_data, regs); -]]> - - - -
- - - - - - - - - RawMIDI Interface - -
- Overview - - - The raw MIDI interface is used for hardware MIDI ports that can - be accessed as a byte stream. It is not used for synthesizer - chips that do not directly understand MIDI. - - - - ALSA handles file and buffer management. All you have to do is - to write some code to move data between the buffer and the - hardware. - - - - The rawmidi API is defined in - <sound/rawmidi.h>. - -
- -
- Constructor - - - To create a rawmidi device, call the - snd_rawmidi_new function: - - -card, "MyMIDI", 0, outs, ins, &rmidi); - if (err < 0) - return err; - rmidi->private_data = chip; - strcpy(rmidi->name, "My MIDI"); - rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT | - SNDRV_RAWMIDI_INFO_INPUT | - SNDRV_RAWMIDI_INFO_DUPLEX; -]]> - - - - - - The first argument is the card pointer, the second argument is - the ID string. - - - - The third argument is the index of this component. You can - create up to 8 rawmidi devices. - - - - The fourth and fifth arguments are the number of output and - input substreams, respectively, of this device (a substream is - the equivalent of a MIDI port). - - - - Set the info_flags field to specify - the capabilities of the device. - Set SNDRV_RAWMIDI_INFO_OUTPUT if there is - at least one output port, - SNDRV_RAWMIDI_INFO_INPUT if there is at - least one input port, - and SNDRV_RAWMIDI_INFO_DUPLEX if the device - can handle output and input at the same time. - - - - After the rawmidi device is created, you need to set the - operators (callbacks) for each substream. There are helper - functions to set the operators for all the substreams of a device: - - - - - - - - - The operators are usually defined like this: - - - - - - These callbacks are explained in the Callbacks - section. - - - - If there are more than one substream, you should give a - unique name to each of them: - - -streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams, - list { - sprintf(substream->name, "My MIDI Port %d", substream->number + 1); - } - /* same for SNDRV_RAWMIDI_STREAM_INPUT */ -]]> - - - -
- -
- Callbacks - - - In all the callbacks, the private data that you've set for the - rawmidi device can be accessed as - substream->rmidi->private_data. - - - - - If there is more than one port, your callbacks can determine the - port index from the struct snd_rawmidi_substream data passed to each - callback: - - -number; -]]> - - - - -
- <function>open</function> callback - - - - - - - - - This is called when a substream is opened. - You can initialize the hardware here, but you shouldn't - start transmitting/receiving data yet. - -
- -
- <function>close</function> callback - - - - - - - - - Guess what. - - - - The open and close - callbacks of a rawmidi device are serialized with a mutex, - and can sleep. - -
- -
- <function>trigger</function> callback for output - substreams - - - - - - - - - This is called with a nonzero up - parameter when there is some data in the substream buffer that - must be transmitted. - - - - To read data from the buffer, call - snd_rawmidi_transmit_peek. It will - return the number of bytes that have been read; this will be - less than the number of bytes requested when there are no more - data in the buffer. - After the data have been transmitted successfully, call - snd_rawmidi_transmit_ack to remove the - data from the substream buffer: - - - - - - - - - If you know beforehand that the hardware will accept data, you - can use the snd_rawmidi_transmit function - which reads some data and removes them from the buffer at once: - - - - - - - - - If you know beforehand how many bytes you can accept, you can - use a buffer size greater than one with the - snd_rawmidi_transmit* functions. - - - - The trigger callback must not sleep. If - the hardware FIFO is full before the substream buffer has been - emptied, you have to continue transmitting data later, either - in an interrupt handler, or with a timer if the hardware - doesn't have a MIDI transmit interrupt. - - - - The trigger callback is called with a - zero up parameter when the transmission - of data should be aborted. - -
- -
- <function>trigger</function> callback for input - substreams - - - - - - - - - This is called with a nonzero up - parameter to enable receiving data, or with a zero - up parameter do disable receiving data. - - - - The trigger callback must not sleep; the - actual reading of data from the device is usually done in an - interrupt handler. - - - - When data reception is enabled, your interrupt handler should - call snd_rawmidi_receive for all received - data: - - - - - - -
- -
- <function>drain</function> callback - - - - - - - - - This is only used with output substreams. This function should wait - until all data read from the substream buffer have been transmitted. - This ensures that the device can be closed and the driver unloaded - without losing data. - - - - This callback is optional. If you do not set - drain in the struct snd_rawmidi_ops - structure, ALSA will simply wait for 50 milliseconds - instead. - -
-
- - - - - - - - - Miscellaneous Devices - -
- FM OPL3 - - The FM OPL3 is still used in many chips (mainly for backward - compatibility). ALSA has a nice OPL3 FM control layer, too. The - OPL3 API is defined in - <sound/opl3.h>. - - - - FM registers can be directly accessed through the direct-FM API, - defined in <sound/asound_fm.h>. In - ALSA native mode, FM registers are accessed through - the Hardware-Dependent Device direct-FM extension API, whereas in - OSS compatible mode, FM registers can be accessed with the OSS - direct-FM compatible API in /dev/dmfmX device. - - - - To create the OPL3 component, you have two functions to - call. The first one is a constructor for the opl3_t - instance. - - - - - - - - - - The first argument is the card pointer, the second one is the - left port address, and the third is the right port address. In - most cases, the right port is placed at the left port + 2. - - - - The fourth argument is the hardware type. - - - - When the left and right ports have been already allocated by - the card driver, pass non-zero to the fifth argument - (integrated). Otherwise, the opl3 module will - allocate the specified ports by itself. - - - - When the accessing the hardware requires special method - instead of the standard I/O access, you can create opl3 instance - separately with snd_opl3_new(). - - - - - - - - - - Then set command, - private_data and - private_free for the private - access function, the private data and the destructor. - The l_port and r_port are not necessarily set. Only the - command must be set properly. You can retrieve the data - from the opl3->private_data field. - - - - After creating the opl3 instance via snd_opl3_new(), - call snd_opl3_init() to initialize the chip to the - proper state. Note that snd_opl3_create() always - calls it internally. - - - - If the opl3 instance is created successfully, then create a - hwdep device for this opl3. - - - - - - - - - - The first argument is the opl3_t instance you - created, and the second is the index number, usually 0. - - - - The third argument is the index-offset for the sequencer - client assigned to the OPL3 port. When there is an MPU401-UART, - give 1 for here (UART always takes 0). - -
- -
- Hardware-Dependent Devices - - Some chips need user-space access for special - controls or for loading the micro code. In such a case, you can - create a hwdep (hardware-dependent) device. The hwdep API is - defined in <sound/hwdep.h>. You can - find examples in opl3 driver or - isa/sb/sb16_csp.c. - - - - The creation of the hwdep instance is done via - snd_hwdep_new(). - - - - - - - - where the third argument is the index number. - - - - You can then pass any pointer value to the - private_data. - If you assign a private data, you should define the - destructor, too. The destructor function is set in - the private_free field. - - - -private_data = p; - hw->private_free = mydata_free; -]]> - - - - and the implementation of the destructor would be: - - - -private_data; - kfree(p); - } -]]> - - - - - - The arbitrary file operations can be defined for this - instance. The file operators are defined in - the ops table. For example, assume that - this chip needs an ioctl. - - - -ops.open = mydata_open; - hw->ops.ioctl = mydata_ioctl; - hw->ops.release = mydata_release; -]]> - - - - And implement the callback functions as you like. - -
- -
- IEC958 (S/PDIF) - - Usually the controls for IEC958 devices are implemented via - the control interface. There is a macro to compose a name string for - IEC958 controls, SNDRV_CTL_NAME_IEC958() - defined in <include/asound.h>. - - - - There are some standard controls for IEC958 status bits. These - controls use the type SNDRV_CTL_ELEM_TYPE_IEC958, - and the size of element is fixed as 4 bytes array - (value.iec958.status[x]). For the info - callback, you don't specify - the value field for this type (the count field must be set, - though). - - - - IEC958 Playback Con Mask is used to return the - bit-mask for the IEC958 status bits of consumer mode. Similarly, - IEC958 Playback Pro Mask returns the bitmask for - professional mode. They are read-only controls, and are defined - as MIXER controls (iface = - SNDRV_CTL_ELEM_IFACE_MIXER). - - - - Meanwhile, IEC958 Playback Default control is - defined for getting and setting the current default IEC958 - bits. Note that this one is usually defined as a PCM control - (iface = SNDRV_CTL_ELEM_IFACE_PCM), - although in some places it's defined as a MIXER control. - - - - In addition, you can define the control switches to - enable/disable or to set the raw bit mode. The implementation - will depend on the chip, but the control should be named as - IEC958 xxx, preferably using - the SNDRV_CTL_NAME_IEC958() macro. - - - - You can find several cases, for example, - pci/emu10k1, - pci/ice1712, or - pci/cmipci.c. - -
- - - - - - - - - Buffer and Memory Management - -
- Buffer Types - - ALSA provides several different buffer allocation functions - depending on the bus and the architecture. All these have a - consistent API. The allocation of physically-contiguous pages is - done via - snd_malloc_xxx_pages() function, where xxx - is the bus type. - - - - The allocation of pages with fallback is - snd_malloc_xxx_pages_fallback(). This - function tries to allocate the specified pages but if the pages - are not available, it tries to reduce the page sizes until - enough space is found. - - - - The release the pages, call - snd_free_xxx_pages() function. - - - - Usually, ALSA drivers try to allocate and reserve - a large contiguous physical space - at the time the module is loaded for the later use. - This is called pre-allocation. - As already written, you can call the following function at - pcm instance construction time (in the case of PCI bus). - - - - - - - - where size is the byte size to be - pre-allocated and the max is the maximum - size to be changed via the prealloc proc file. - The allocator will try to get an area as large as possible - within the given size. - - - - The second argument (type) and the third argument (device pointer) - are dependent on the bus. - In the case of the ISA bus, pass snd_dma_isa_data() - as the third argument with SNDRV_DMA_TYPE_DEV type. - For the continuous buffer unrelated to the bus can be pre-allocated - with SNDRV_DMA_TYPE_CONTINUOUS type and the - snd_dma_continuous_data(GFP_KERNEL) device pointer, - where GFP_KERNEL is the kernel allocation flag to - use. - For the PCI scatter-gather buffers, use - SNDRV_DMA_TYPE_DEV_SG with - snd_dma_pci_data(pci) - (see the - Non-Contiguous Buffers - section). - - - - Once the buffer is pre-allocated, you can use the - allocator in the hw_params callback: - - - - - - - - Note that you have to pre-allocate to use this function. - -
- -
- External Hardware Buffers - - Some chips have their own hardware buffers and the DMA - transfer from the host memory is not available. In such a case, - you need to either 1) copy/set the audio data directly to the - external hardware buffer, or 2) make an intermediate buffer and - copy/set the data from it to the external hardware buffer in - interrupts (or in tasklets, preferably). - - - - The first case works fine if the external hardware buffer is large - enough. This method doesn't need any extra buffers and thus is - more effective. You need to define the - copy and - silence callbacks for - the data transfer. However, there is a drawback: it cannot - be mmapped. The examples are GUS's GF1 PCM or emu8000's - wavetable PCM. - - - - The second case allows for mmap on the buffer, although you have - to handle an interrupt or a tasklet to transfer the data - from the intermediate buffer to the hardware buffer. You can find an - example in the vxpocket driver. - - - - Another case is when the chip uses a PCI memory-map - region for the buffer instead of the host memory. In this case, - mmap is available only on certain architectures like the Intel one. - In non-mmap mode, the data cannot be transferred as in the normal - way. Thus you need to define the copy and - silence callbacks as well, - as in the cases above. The examples are found in - rme32.c and rme96.c. - - - - The implementation of the copy and - silence callbacks depends upon - whether the hardware supports interleaved or non-interleaved - samples. The copy callback is - defined like below, a bit - differently depending whether the direction is playback or - capture: - - - - - - - - - - In the case of interleaved samples, the second argument - (channel) is not used. The third argument - (pos) points the - current position offset in frames. - - - - The meaning of the fourth argument is different between - playback and capture. For playback, it holds the source data - pointer, and for capture, it's the destination data pointer. - - - - The last argument is the number of frames to be copied. - - - - What you have to do in this callback is again different - between playback and capture directions. In the - playback case, you copy the given amount of data - (count) at the specified pointer - (src) to the specified offset - (pos) on the hardware buffer. When - coded like memcpy-like way, the copy would be like: - - - - - - - - - - For the capture direction, you copy the given amount of - data (count) at the specified offset - (pos) on the hardware buffer to the - specified pointer (dst). - - - - - - - - Note that both the position and the amount of data are given - in frames. - - - - In the case of non-interleaved samples, the implementation - will be a bit more complicated. - - - - You need to check the channel argument, and if it's -1, copy - the whole channels. Otherwise, you have to copy only the - specified channel. Please check - isa/gus/gus_pcm.c as an example. - - - - The silence callback is also - implemented in a similar way. - - - - - - - - - - The meanings of arguments are the same as in the - copy - callback, although there is no src/dst - argument. In the case of interleaved samples, the channel - argument has no meaning, as well as on - copy callback. - - - - The role of silence callback is to - set the given amount - (count) of silence data at the - specified offset (pos) on the hardware - buffer. Suppose that the data format is signed (that is, the - silent-data is 0), and the implementation using a memset-like - function would be like: - - - - - - - - - - In the case of non-interleaved samples, again, the - implementation becomes a bit more complicated. See, for example, - isa/gus/gus_pcm.c. - -
- -
- Non-Contiguous Buffers - - If your hardware supports the page table as in emu10k1 or the - buffer descriptors as in via82xx, you can use the scatter-gather - (SG) DMA. ALSA provides an interface for handling SG-buffers. - The API is provided in <sound/pcm.h>. - - - - For creating the SG-buffer handler, call - snd_pcm_lib_preallocate_pages() or - snd_pcm_lib_preallocate_pages_for_all() - with SNDRV_DMA_TYPE_DEV_SG - in the PCM constructor like other PCI pre-allocator. - You need to pass snd_dma_pci_data(pci), - where pci is the struct pci_dev pointer - of the chip as well. - The struct snd_sg_buf instance is created as - substream->dma_private. You can cast - the pointer like: - - - -dma_private; -]]> - - - - - - Then call snd_pcm_lib_malloc_pages() - in the hw_params callback - as well as in the case of normal PCI buffer. - The SG-buffer handler will allocate the non-contiguous kernel - pages of the given size and map them onto the virtually contiguous - memory. The virtual pointer is addressed in runtime->dma_area. - The physical address (runtime->dma_addr) is set to zero, - because the buffer is physically non-contiguous. - The physical address table is set up in sgbuf->table. - You can get the physical address at a certain offset via - snd_pcm_sgbuf_get_addr(). - - - - When a SG-handler is used, you need to set - snd_pcm_sgbuf_ops_page as - the page callback. - (See - page callback section.) - - - - To release the data, call - snd_pcm_lib_free_pages() in the - hw_free callback as usual. - -
- -
- Vmalloc'ed Buffers - - It's possible to use a buffer allocated via - vmalloc, for example, for an intermediate - buffer. Since the allocated pages are not contiguous, you need - to set the page callback to obtain - the physical address at every offset. - - - - The implementation of page callback - would be like this: - - - - - - /* get the physical page pointer on the given offset */ - static struct page *mychip_page(struct snd_pcm_substream *substream, - unsigned long offset) - { - void *pageptr = substream->runtime->dma_area + offset; - return vmalloc_to_page(pageptr); - } -]]> - - - -
- - - - - - - - - Proc Interface - - ALSA provides an easy interface for procfs. The proc files are - very useful for debugging. I recommend you set up proc files if - you write a driver and want to get a running status or register - dumps. The API is found in - <sound/info.h>. - - - - To create a proc file, call - snd_card_proc_new(). - - - - - - - - where the second argument specifies the name of the proc file to be - created. The above example will create a file - my-file under the card directory, - e.g. /proc/asound/card0/my-file. - - - - Like other components, the proc entry created via - snd_card_proc_new() will be registered and - released automatically in the card registration and release - functions. - - - - When the creation is successful, the function stores a new - instance in the pointer given in the third argument. - It is initialized as a text proc file for read only. To use - this proc file as a read-only text file as it is, set the read - callback with a private data via - snd_info_set_text_ops(). - - - - - - - - where the second argument (chip) is the - private data to be used in the callbacks. The third parameter - specifies the read buffer size and the fourth - (my_proc_read) is the callback function, which - is defined like - - - - - - - - - - - In the read callback, use snd_iprintf() for - output strings, which works just like normal - printf(). For example, - - - -private_data; - - snd_iprintf(buffer, "This is my chip!\n"); - snd_iprintf(buffer, "Port = %ld\n", chip->port); - } -]]> - - - - - - The file permissions can be changed afterwards. As default, it's - set as read only for all users. If you want to add write - permission for the user (root as default), do as follows: - - - -mode = S_IFREG | S_IRUGO | S_IWUSR; -]]> - - - - and set the write buffer size and the callback - - - -c.text.write = my_proc_write; -]]> - - - - - - For the write callback, you can use - snd_info_get_line() to get a text line, and - snd_info_get_str() to retrieve a string from - the line. Some examples are found in - core/oss/mixer_oss.c, core/oss/and - pcm_oss.c. - - - - For a raw-data proc-file, set the attributes as follows: - - - -content = SNDRV_INFO_CONTENT_DATA; - entry->private_data = chip; - entry->c.ops = &my_file_io_ops; - entry->size = 4096; - entry->mode = S_IFREG | S_IRUGO; -]]> - - - - For the raw data, size field must be - set properly. This specifies the maximum size of the proc file access. - - - - The read/write callbacks of raw mode are more direct than the text mode. - You need to use a low-level I/O functions such as - copy_from/to_user() to transfer the - data. - - - - - - - - If the size of the info entry has been set up properly, - count and pos are - guaranteed to fit within 0 and the given size. - You don't have to check the range in the callbacks unless any - other condition is required. - - - - - - - - - - - Power Management - - If the chip is supposed to work with suspend/resume - functions, you need to add power-management code to the - driver. The additional code for power-management should be - ifdef'ed with - CONFIG_PM. - - - - If the driver fully supports suspend/resume - that is, the device can be - properly resumed to its state when suspend was called, - you can set the SNDRV_PCM_INFO_RESUME flag - in the pcm info field. Usually, this is possible when the - registers of the chip can be safely saved and restored to - RAM. If this is set, the trigger callback is called with - SNDRV_PCM_TRIGGER_RESUME after the resume - callback completes. - - - - Even if the driver doesn't support PM fully but - partial suspend/resume is still possible, it's still worthy to - implement suspend/resume callbacks. In such a case, applications - would reset the status by calling - snd_pcm_prepare() and restart the stream - appropriately. Hence, you can define suspend/resume callbacks - below but don't set SNDRV_PCM_INFO_RESUME - info flag to the PCM. - - - - Note that the trigger with SUSPEND can always be called when - snd_pcm_suspend_all is called, - regardless of the SNDRV_PCM_INFO_RESUME flag. - The RESUME flag affects only the behavior - of snd_pcm_resume(). - (Thus, in theory, - SNDRV_PCM_TRIGGER_RESUME isn't needed - to be handled in the trigger callback when no - SNDRV_PCM_INFO_RESUME flag is set. But, - it's better to keep it for compatibility reasons.) - - - In the earlier version of ALSA drivers, a common - power-management layer was provided, but it has been removed. - The driver needs to define the suspend/resume hooks according to - the bus the device is connected to. In the case of PCI drivers, the - callbacks look like below: - - - - - - - - - - The scheme of the real suspend job is as follows. - - - Retrieve the card and the chip data. - Call snd_power_change_state() with - SNDRV_CTL_POWER_D3hot to change the - power status. - Call snd_pcm_suspend_all() to suspend the running PCM streams. - If AC97 codecs are used, call - snd_ac97_suspend() for each codec. - Save the register values if necessary. - Stop the hardware if necessary. - Disable the PCI device by calling - pci_disable_device(). Then, call - pci_save_state() at last. - - - - - A typical code would be like: - - - -private_data; - /* (2) */ - snd_power_change_state(card, SNDRV_CTL_POWER_D3hot); - /* (3) */ - snd_pcm_suspend_all(chip->pcm); - /* (4) */ - snd_ac97_suspend(chip->ac97); - /* (5) */ - snd_mychip_save_registers(chip); - /* (6) */ - snd_mychip_stop_hardware(chip); - /* (7) */ - pci_disable_device(pci); - pci_save_state(pci); - return 0; - } -]]> - - - - - - The scheme of the real resume job is as follows. - - - Retrieve the card and the chip data. - Set up PCI. First, call pci_restore_state(). - Then enable the pci device again by calling pci_enable_device(). - Call pci_set_master() if necessary, too. - Re-initialize the chip. - Restore the saved registers if necessary. - Resume the mixer, e.g. calling - snd_ac97_resume(). - Restart the hardware (if any). - Call snd_power_change_state() with - SNDRV_CTL_POWER_D0 to notify the processes. - - - - - A typical code would be like: - - - -private_data; - /* (2) */ - pci_restore_state(pci); - pci_enable_device(pci); - pci_set_master(pci); - /* (3) */ - snd_mychip_reinit_chip(chip); - /* (4) */ - snd_mychip_restore_registers(chip); - /* (5) */ - snd_ac97_resume(chip->ac97); - /* (6) */ - snd_mychip_restart_chip(chip); - /* (7) */ - snd_power_change_state(card, SNDRV_CTL_POWER_D0); - return 0; - } -]]> - - - - - - As shown in the above, it's better to save registers after - suspending the PCM operations via - snd_pcm_suspend_all() or - snd_pcm_suspend(). It means that the PCM - streams are already stopped when the register snapshot is - taken. But, remember that you don't have to restart the PCM - stream in the resume callback. It'll be restarted via - trigger call with SNDRV_PCM_TRIGGER_RESUME - when necessary. - - - - OK, we have all callbacks now. Let's set them up. In the - initialization of the card, make sure that you can get the chip - data from the card instance, typically via - private_data field, in case you - created the chip data individually. - - - -dev, index[dev], id[dev], THIS_MODULE, - 0, &card); - .... - chip = kzalloc(sizeof(*chip), GFP_KERNEL); - .... - card->private_data = chip; - .... - } -]]> - - - - When you created the chip data with - snd_card_new(), it's anyway accessible - via private_data field. - - - -dev, index[dev], id[dev], THIS_MODULE, - sizeof(struct mychip), &card); - .... - chip = card->private_data; - .... - } -]]> - - - - - - - If you need a space to save the registers, allocate the - buffer for it here, too, since it would be fatal - if you cannot allocate a memory in the suspend phase. - The allocated buffer should be released in the corresponding - destructor. - - - - And next, set suspend/resume callbacks to the pci_driver. - - - - - - - - - - - - - - - - Module Parameters - - There are standard module options for ALSA. At least, each - module should have the index, - id and enable - options. - - - - If the module supports multiple cards (usually up to - 8 = SNDRV_CARDS cards), they should be - arrays. The default initial values are defined already as - constants for easier programming: - - - - - - - - - - If the module supports only a single card, they could be single - variables, instead. enable option is not - always necessary in this case, but it would be better to have a - dummy option for compatibility. - - - - The module parameters must be declared with the standard - module_param()(), - module_param_array()() and - MODULE_PARM_DESC() macros. - - - - The typical coding would be like below: - - - - - - - - - - Also, don't forget to define the module description, classes, - license and devices. Especially, the recent modprobe requires to - define the module license as GPL, etc., otherwise the system is - shown as tainted. - - - - - - - - - - - - - - - - How To Put Your Driver Into ALSA Tree -
- General - - So far, you've learned how to write the driver codes. - And you might have a question now: how to put my own - driver into the ALSA driver tree? - Here (finally :) the standard procedure is described briefly. - - - - Suppose that you create a new PCI driver for the card - xyz. The card module name would be - snd-xyz. The new driver is usually put into the alsa-driver - tree, alsa-driver/pci directory in - the case of PCI cards. - Then the driver is evaluated, audited and tested - by developers and users. After a certain time, the driver - will go to the alsa-kernel tree (to the corresponding directory, - such as alsa-kernel/pci) and eventually - will be integrated into the Linux 2.6 tree (the directory would be - linux/sound/pci). - - - - In the following sections, the driver code is supposed - to be put into alsa-driver tree. The two cases are covered: - a driver consisting of a single source file and one consisting - of several source files. - -
- -
- Driver with A Single Source File - - - - - Modify alsa-driver/pci/Makefile - - - - Suppose you have a file xyz.c. Add the following - two lines - - - - - - - - - - - Create the Kconfig entry - - - - Add the new entry of Kconfig for your xyz driver. - - - - - - - the line, select SND_PCM, specifies that the driver xyz supports - PCM. In addition to SND_PCM, the following components are - supported for select command: - SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART, - SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC. - Add the select command for each supported component. - - - - Note that some selections imply the lowlevel selections. - For example, PCM includes TIMER, MPU401_UART includes RAWMIDI, - AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP. - You don't need to give the lowlevel selections again. - - - - For the details of Kconfig script, refer to the kbuild - documentation. - - - - - - - Run cvscompile script to re-generate the configure script and - build the whole stuff again. - - - - -
- -
- Drivers with Several Source Files - - Suppose that the driver snd-xyz have several source files. - They are located in the new subdirectory, - pci/xyz. - - - - - Add a new directory (xyz) in - alsa-driver/pci/Makefile as below - - - - - - - - - - - - Under the directory xyz, create a Makefile - - - Sample Makefile for a driver xyz - - - - - - - - - - Create the Kconfig entry - - - - This procedure is as same as in the last section. - - - - - - Run cvscompile script to re-generate the configure script and - build the whole stuff again. - - - - -
- - - - - - - - Useful Functions - -
- <function>snd_printk()</function> and friends - - ALSA provides a verbose version of the - printk() function. If a kernel config - CONFIG_SND_VERBOSE_PRINTK is set, this - function prints the given message together with the file name - and the line of the caller. The KERN_XXX - prefix is processed as - well as the original printk() does, so it's - recommended to add this prefix, e.g. - - - - - - - - - - There are also printk()'s for - debugging. snd_printd() can be used for - general debugging purposes. If - CONFIG_SND_DEBUG is set, this function is - compiled, and works just like - snd_printk(). If the ALSA is compiled - without the debugging flag, it's ignored. - - - - snd_printdd() is compiled in only when - CONFIG_SND_DEBUG_VERBOSE is set. Please note - that CONFIG_SND_DEBUG_VERBOSE is not set as default - even if you configure the alsa-driver with - option. You need to give - explicitly option instead. - -
- -
- <function>snd_BUG()</function> - - It shows the BUG? message and - stack trace as well as snd_BUG_ON at the point. - It's useful to show that a fatal error happens there. - - - When no debug flag is set, this macro is ignored. - -
- -
- <function>snd_BUG_ON()</function> - - snd_BUG_ON() macro is similar with - WARN_ON() macro. For example, - - - - - - - - or it can be used as the condition, - - - - - - - - - - The macro takes an conditional expression to evaluate. - When CONFIG_SND_DEBUG, is set, if the - expression is non-zero, it shows the warning message such as - BUG? (xxx) - normally followed by stack trace. - - In both cases it returns the evaluated value. - - -
- - - - - - - - - Acknowledgments - - I would like to thank Phil Kerr for his help for improvement and - corrections of this document. - - - Kevin Conder reformatted the original plain-text to the - DocBook format. - - - Giuliano Pochini corrected typos and contributed the example codes - in the hardware constraints section. - - - diff --git a/Documentation/sound/kernel-api/index.rst b/Documentation/sound/kernel-api/index.rst index 73c13497dec7..d0e6df35b4b4 100644 --- a/Documentation/sound/kernel-api/index.rst +++ b/Documentation/sound/kernel-api/index.rst @@ -5,3 +5,4 @@ ALSA Kernel API Documentation :maxdepth: 2 alsa-driver-api + writing-an-alsa-driver diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst new file mode 100644 index 000000000000..95c5443eff38 --- /dev/null +++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst @@ -0,0 +1,4219 @@ +====================== +Writing an ALSA Driver +====================== + +:Author: Takashi Iwai +:Date: Oct 15, 2007 +:Edition: 0.3.7 + +Preface +======= + +This document describes how to write an `ALSA (Advanced Linux Sound +Architecture) `__ driver. The document +focuses mainly on PCI soundcards. In the case of other device types, the +API might be different, too. However, at least the ALSA kernel API is +consistent, and therefore it would be still a bit help for writing them. + +This document targets people who already have enough C language skills +and have basic linux kernel programming knowledge. This document doesn't +explain the general topic of linux kernel coding and doesn't cover +low-level driver implementation details. It only describes the standard +way to write a PCI sound driver on ALSA. + +If you are already familiar with the older ALSA ver.0.5.x API, you can +check the drivers such as ``sound/pci/es1938.c`` or +``sound/pci/maestro3.c`` which have also almost the same code-base in +the ALSA 0.5.x tree, so you can compare the differences. + +This document is still a draft version. Any feedback and corrections, +please!! + +File Tree Structure +=================== + +General +------- + +The ALSA drivers are provided in two ways. + +One is the trees provided as a tarball or via cvs from the ALSA's ftp +site, and another is the 2.6 (or later) Linux kernel tree. To +synchronize both, the ALSA driver tree is split into two different +trees: alsa-kernel and alsa-driver. The former contains purely the +source code for the Linux 2.6 (or later) tree. This tree is designed +only for compilation on 2.6 or later environment. The latter, +alsa-driver, contains many subtle files for compiling ALSA drivers +outside of the Linux kernel tree, wrapper functions for older 2.2 and +2.4 kernels, to adapt the latest kernel API, and additional drivers +which are still in development or in tests. The drivers in alsa-driver +tree will be moved to alsa-kernel (and eventually to the 2.6 kernel +tree) when they are finished and confirmed to work fine. + +The file tree structure of ALSA driver is depicted below. Both +alsa-kernel and alsa-driver have almost the same file structure, except +for “core” directory. It's named as “acore” in alsa-driver tree. + +:: + + sound + /core + /oss + /seq + /oss + /instr + /ioctl32 + /include + /drivers + /mpu401 + /opl3 + /i2c + /l3 + /synth + /emux + /pci + /(cards) + /isa + /(cards) + /arm + /ppc + /sparc + /usb + /pcmcia /(cards) + /oss + + +core directory +-------------- + +This directory contains the middle layer which is the heart of ALSA +drivers. In this directory, the native ALSA modules are stored. The +sub-directories contain different modules and are dependent upon the +kernel config. + +core/oss +~~~~~~~~ + +The codes for PCM and mixer OSS emulation modules are stored in this +directory. The rawmidi OSS emulation is included in the ALSA rawmidi +code since it's quite small. The sequencer code is stored in +``core/seq/oss`` directory (see `below <#core-seq-oss>`__). + +core/ioctl32 +~~~~~~~~~~~~ + +This directory contains the 32bit-ioctl wrappers for 64bit architectures +such like x86-64, ppc64 and sparc64. For 32bit and alpha architectures, +these are not compiled. + +core/seq +~~~~~~~~ + +This directory and its sub-directories are for the ALSA sequencer. This +directory contains the sequencer core and primary sequencer modules such +like snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when +``CONFIG_SND_SEQUENCER`` is set in the kernel config. + +core/seq/oss +~~~~~~~~~~~~ + +This contains the OSS sequencer emulation codes. + +core/seq/instr +~~~~~~~~~~~~~~ + +This directory contains the modules for the sequencer instrument layer. + +include directory +----------------- + +This is the place for the public header files of ALSA drivers, which are +to be exported to user-space, or included by several files at different +directories. Basically, the private header files should not be placed in +this directory, but you may still find files there, due to historical +reasons :) + +drivers directory +----------------- + +This directory contains code shared among different drivers on different +architectures. They are hence supposed not to be architecture-specific. +For example, the dummy pcm driver and the serial MIDI driver are found +in this directory. In the sub-directories, there is code for components +which are independent from bus and cpu architectures. + +drivers/mpu401 +~~~~~~~~~~~~~~ + +The MPU401 and MPU401-UART modules are stored here. + +drivers/opl3 and opl4 +~~~~~~~~~~~~~~~~~~~~~ + +The OPL3 and OPL4 FM-synth stuff is found here. + +i2c directory +------------- + +This contains the ALSA i2c components. + +Although there is a standard i2c layer on Linux, ALSA has its own i2c +code for some cards, because the soundcard needs only a simple operation +and the standard i2c API is too complicated for such a purpose. + +i2c/l3 +~~~~~~ + +This is a sub-directory for ARM L3 i2c. + +synth directory +--------------- + +This contains the synth middle-level modules. + +So far, there is only Emu8000/Emu10k1 synth driver under the +``synth/emux`` sub-directory. + +pci directory +------------- + +This directory and its sub-directories hold the top-level card modules +for PCI soundcards and the code specific to the PCI BUS. + +The drivers compiled from a single file are stored directly in the pci +directory, while the drivers with several source files are stored on +their own sub-directory (e.g. emu10k1, ice1712). + +isa directory +------------- + +This directory and its sub-directories hold the top-level card modules +for ISA soundcards. + +arm, ppc, and sparc directories +------------------------------- + +They are used for top-level card modules which are specific to one of +these architectures. + +usb directory +------------- + +This directory contains the USB-audio driver. In the latest version, the +USB MIDI driver is integrated in the usb-audio driver. + +pcmcia directory +---------------- + +The PCMCIA, especially PCCard drivers will go here. CardBus drivers will +be in the pci directory, because their API is identical to that of +standard PCI cards. + +oss directory +------------- + +The OSS/Lite source files are stored here in Linux 2.6 (or later) tree. +In the ALSA driver tarball, this directory is empty, of course :) + +Basic Flow for PCI Drivers +========================== + +Outline +------- + +The minimum flow for PCI soundcards is as follows: + +- define the PCI ID table (see the section `PCI Entries`_). + +- create ``probe`` callback. + +- create ``remove`` callback. + +- create a :c:type:`struct pci_driver ` structure + containing the three pointers above. + +- create an ``init`` function just calling the + :c:func:`pci_register_driver()` to register the pci_driver + table defined above. + +- create an ``exit`` function to call the + :c:func:`pci_unregister_driver()` function. + +Full Code Example +----------------- + +The code example is shown below. Some parts are kept unimplemented at +this moment but will be filled in the next sections. The numbers in the +comment lines of the :c:func:`snd_mychip_probe()` function refer +to details explained in the following section. + +:: + + #include + #include + #include + #include + #include + + /* module parameters (see "Module Parameters") */ + /* SNDRV_CARDS: maximum number of cards supported by this module */ + static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX; + static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR; + static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP; + + /* definition of the chip-specific record */ + struct mychip { + struct snd_card *card; + /* the rest of the implementation will be in section + * "PCI Resource Management" + */ + }; + + /* chip-specific destructor + * (see "PCI Resource Management") + */ + static int snd_mychip_free(struct mychip *chip) + { + .... /* will be implemented later... */ + } + + /* component-destructor + * (see "Management of Cards and Components") + */ + static int snd_mychip_dev_free(struct snd_device *device) + { + return snd_mychip_free(device->device_data); + } + + /* chip-specific constructor + * (see "Management of Cards and Components") + */ + static int snd_mychip_create(struct snd_card *card, + struct pci_dev *pci, + struct mychip **rchip) + { + struct mychip *chip; + int err; + static struct snd_device_ops ops = { + .dev_free = snd_mychip_dev_free, + }; + + *rchip = NULL; + + /* check PCI availability here + * (see "PCI Resource Management") + */ + .... + + /* allocate a chip-specific data with zero filled */ + chip = kzalloc(sizeof(*chip), GFP_KERNEL); + if (chip == NULL) + return -ENOMEM; + + chip->card = card; + + /* rest of initialization here; will be implemented + * later, see "PCI Resource Management" + */ + .... + + err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops); + if (err < 0) { + snd_mychip_free(chip); + return err; + } + + *rchip = chip; + return 0; + } + + /* constructor -- see "Driver Constructor" sub-section */ + static int snd_mychip_probe(struct pci_dev *pci, + const struct pci_device_id *pci_id) + { + static int dev; + struct snd_card *card; + struct mychip *chip; + int err; + + /* (1) */ + if (dev >= SNDRV_CARDS) + return -ENODEV; + if (!enable[dev]) { + dev++; + return -ENOENT; + } + + /* (2) */ + err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, + 0, &card); + if (err < 0) + return err; + + /* (3) */ + err = snd_mychip_create(card, pci, &chip); + if (err < 0) { + snd_card_free(card); + return err; + } + + /* (4) */ + strcpy(card->driver, "My Chip"); + strcpy(card->shortname, "My Own Chip 123"); + sprintf(card->longname, "%s at 0x%lx irq %i", + card->shortname, chip->ioport, chip->irq); + + /* (5) */ + .... /* implemented later */ + + /* (6) */ + err = snd_card_register(card); + if (err < 0) { + snd_card_free(card); + return err; + } + + /* (7) */ + pci_set_drvdata(pci, card); + dev++; + return 0; + } + + /* destructor -- see the "Destructor" sub-section */ + static void snd_mychip_remove(struct pci_dev *pci) + { + snd_card_free(pci_get_drvdata(pci)); + pci_set_drvdata(pci, NULL); + } + + + +Driver Constructor +------------------ + +The real constructor of PCI drivers is the ``probe`` callback. The +``probe`` callback and other component-constructors which are called +from the ``probe`` callback cannot be used with the ``__init`` prefix +because any PCI device could be a hotplug device. + +In the ``probe`` callback, the following scheme is often used. + +1) Check and increment the device index. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + static int dev; + .... + if (dev >= SNDRV_CARDS) + return -ENODEV; + if (!enable[dev]) { + dev++; + return -ENOENT; + } + + +where ``enable[dev]`` is the module option. + +Each time the ``probe`` callback is called, check the availability of +the device. If not available, simply increment the device index and +returns. dev will be incremented also later (`step 7 +<#set-the-pci-driver-data-and-return-zero>`__). + +2) Create a card instance +~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + struct snd_card *card; + int err; + .... + err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, + 0, &card); + + +The details will be explained in the section `Management of Cards and +Components`_. + +3) Create a main component +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In this part, the PCI resources are allocated. + +:: + + struct mychip *chip; + .... + err = snd_mychip_create(card, pci, &chip); + if (err < 0) { + snd_card_free(card); + return err; + } + +The details will be explained in the section `PCI Resource +Management`_. + +4) Set the driver ID and name strings. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + strcpy(card->driver, "My Chip"); + strcpy(card->shortname, "My Own Chip 123"); + sprintf(card->longname, "%s at 0x%lx irq %i", + card->shortname, chip->ioport, chip->irq); + +The driver field holds the minimal ID string of the chip. This is used +by alsa-lib's configurator, so keep it simple but unique. Even the +same driver can have different driver IDs to distinguish the +functionality of each chip type. + +The shortname field is a string shown as more verbose name. The longname +field contains the information shown in ``/proc/asound/cards``. + +5) Create other components, such as mixer, MIDI, etc. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Here you define the basic components such as `PCM <#PCM-Interface>`__, +mixer (e.g. `AC97 <#API-for-AC97-Codec>`__), MIDI (e.g. +`MPU-401 <#MIDI-MPU401-UART-Interface>`__), and other interfaces. +Also, if you want a `proc file <#Proc-Interface>`__, define it here, +too. + +6) Register the card instance. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + err = snd_card_register(card); + if (err < 0) { + snd_card_free(card); + return err; + } + +Will be explained in the section `Management of Cards and +Components`_, too. + +7) Set the PCI driver data and return zero. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + pci_set_drvdata(pci, card); + dev++; + return 0; + +In the above, the card record is stored. This pointer is used in the +remove callback and power-management callbacks, too. + +Destructor +---------- + +The destructor, remove callback, simply releases the card instance. Then +the ALSA middle layer will release all the attached components +automatically. + +It would be typically like the following: + +:: + + static void snd_mychip_remove(struct pci_dev *pci) + { + snd_card_free(pci_get_drvdata(pci)); + pci_set_drvdata(pci, NULL); + } + + +The above code assumes that the card pointer is set to the PCI driver +data. + +Header Files +------------ + +For the above example, at least the following include files are +necessary. + +:: + + #include + #include + #include + #include + #include + +where the last one is necessary only when module options are defined +in the source file. If the code is split into several files, the files +without module options don't need them. + +In addition to these headers, you'll need ```` for +interrupt handling, and ```` for I/O access. If you use the +:c:func:`mdelay()` or :c:func:`udelay()` functions, you'll need +to include ```` too. + +The ALSA interfaces like the PCM and control APIs are defined in other +```` header files. They have to be included after +````. + +Management of Cards and Components +================================== + +Card Instance +------------- + +For each soundcard, a “card” record must be allocated. + +A card record is the headquarters of the soundcard. It manages the whole +list of devices (components) on the soundcard, such as PCM, mixers, +MIDI, synthesizer, and so on. Also, the card record holds the ID and the +name strings of the card, manages the root of proc files, and controls +the power-management states and hotplug disconnections. The component +list on the card record is used to manage the correct release of +resources at destruction. + +As mentioned above, to create a card instance, call +:c:func:`snd_card_new()`. + +:: + + struct snd_card *card; + int err; + err = snd_card_new(&pci->dev, index, id, module, extra_size, &card); + + +The function takes six arguments: the parent device pointer, the +card-index number, the id string, the module pointer (usually +``THIS_MODULE``), the size of extra-data space, and the pointer to +return the card instance. The extra_size argument is used to allocate +card->private_data for the chip-specific data. Note that these data are +allocated by :c:func:`snd_card_new()`. + +The first argument, the pointer of struct :c:type:`struct device +`, specifies the parent device. For PCI devices, typically +``&pci->`` is passed there. + +Components +---------- + +After the card is created, you can attach the components (devices) to +the card instance. In an ALSA driver, a component is represented as a +:c:type:`struct snd_device ` object. A component +can be a PCM instance, a control interface, a raw MIDI interface, etc. +Each such instance has one component entry. + +A component can be created via :c:func:`snd_device_new()` +function. + +:: + + snd_device_new(card, SNDRV_DEV_XXX, chip, &ops); + +This takes the card pointer, the device-level (``SNDRV_DEV_XXX``), the +data pointer, and the callback pointers (``&ops``). The device-level +defines the type of components and the order of registration and +de-registration. For most components, the device-level is already +defined. For a user-defined component, you can use +``SNDRV_DEV_LOWLEVEL``. + +This function itself doesn't allocate the data space. The data must be +allocated manually beforehand, and its pointer is passed as the +argument. This pointer (``chip`` in the above example) is used as the +identifier for the instance. + +Each pre-defined ALSA component such as ac97 and pcm calls +:c:func:`snd_device_new()` inside its constructor. The destructor +for each component is defined in the callback pointers. Hence, you don't +need to take care of calling a destructor for such a component. + +If you wish to create your own component, you need to set the destructor +function to the dev_free callback in the ``ops``, so that it can be +released automatically via :c:func:`snd_card_free()`. The next +example will show an implementation of chip-specific data. + +Chip-Specific Data +------------------ + +Chip-specific information, e.g. the I/O port address, its resource +pointer, or the irq number, is stored in the chip-specific record. + +:: + + struct mychip { + .... + }; + + +In general, there are two ways of allocating the chip record. + +1. Allocating via :c:func:`snd_card_new()`. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As mentioned above, you can pass the extra-data-length to the 5th +argument of :c:func:`snd_card_new()`, i.e. + +:: + + err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, + sizeof(struct mychip), &card); + +:c:type:`struct mychip ` is the type of the chip record. + +In return, the allocated record can be accessed as + +:: + + struct mychip *chip = card->private_data; + +With this method, you don't have to allocate twice. The record is +released together with the card instance. + +2. Allocating an extra device. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +After allocating a card instance via :c:func:`snd_card_new()` +(with ``0`` on the 4th arg), call :c:func:`kzalloc()`. + +:: + + struct snd_card *card; + struct mychip *chip; + err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, + 0, &card); + ..... + chip = kzalloc(sizeof(*chip), GFP_KERNEL); + +The chip record should have the field to hold the card pointer at least, + +:: + + struct mychip { + struct snd_card *card; + .... + }; + + +Then, set the card pointer in the returned chip instance. + +:: + + chip->card = card; + +Next, initialize the fields, and register this chip record as a +low-level device with a specified ``ops``, + +:: + + static struct snd_device_ops ops = { + .dev_free = snd_mychip_dev_free, + }; + .... + snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops); + +:c:func:`snd_mychip_dev_free()` is the device-destructor +function, which will call the real destructor. + +:: + + static int snd_mychip_dev_free(struct snd_device *device) + { + return snd_mychip_free(device->device_data); + } + +where :c:func:`snd_mychip_free()` is the real destructor. + +Registration and Release +------------------------ + +After all components are assigned, register the card instance by calling +:c:func:`snd_card_register()`. Access to the device files is +enabled at this point. That is, before +:c:func:`snd_card_register()` is called, the components are safely +inaccessible from external side. If this call fails, exit the probe +function after releasing the card via :c:func:`snd_card_free()`. + +For releasing the card instance, you can call simply +:c:func:`snd_card_free()`. As mentioned earlier, all components +are released automatically by this call. + +For a device which allows hotplugging, you can use +:c:func:`snd_card_free_when_closed()`. This one will postpone +the destruction until all devices are closed. + +PCI Resource Management +======================= + +Full Code Example +----------------- + +In this section, we'll complete the chip-specific constructor, +destructor and PCI entries. Example code is shown first, below. + +:: + + struct mychip { + struct snd_card *card; + struct pci_dev *pci; + + unsigned long port; + int irq; + }; + + static int snd_mychip_free(struct mychip *chip) + { + /* disable hardware here if any */ + .... /* (not implemented in this document) */ + + /* release the irq */ + if (chip->irq >= 0) + free_irq(chip->irq, chip); + /* release the I/O ports & memory */ + pci_release_regions(chip->pci); + /* disable the PCI entry */ + pci_disable_device(chip->pci); + /* release the data */ + kfree(chip); + return 0; + } + + /* chip-specific constructor */ + static int snd_mychip_create(struct snd_card *card, + struct pci_dev *pci, + struct mychip **rchip) + { + struct mychip *chip; + int err; + static struct snd_device_ops ops = { + .dev_free = snd_mychip_dev_free, + }; + + *rchip = NULL; + + /* initialize the PCI entry */ + err = pci_enable_device(pci); + if (err < 0) + return err; + /* check PCI availability (28bit DMA) */ + if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 || + pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) { + printk(KERN_ERR "error to set 28bit mask DMA\n"); + pci_disable_device(pci); + return -ENXIO; + } + + chip = kzalloc(sizeof(*chip), GFP_KERNEL); + if (chip == NULL) { + pci_disable_device(pci); + return -ENOMEM; + } + + /* initialize the stuff */ + chip->card = card; + chip->pci = pci; + chip->irq = -1; + + /* (1) PCI resource allocation */ + err = pci_request_regions(pci, "My Chip"); + if (err < 0) { + kfree(chip); + pci_disable_device(pci); + return err; + } + chip->port = pci_resource_start(pci, 0); + if (request_irq(pci->irq, snd_mychip_interrupt, + IRQF_SHARED, KBUILD_MODNAME, chip)) { + printk(KERN_ERR "cannot grab irq %d\n", pci->irq); + snd_mychip_free(chip); + return -EBUSY; + } + chip->irq = pci->irq; + + /* (2) initialization of the chip hardware */ + .... /* (not implemented in this document) */ + + err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops); + if (err < 0) { + snd_mychip_free(chip); + return err; + } + + *rchip = chip; + return 0; + } + + /* PCI IDs */ + static struct pci_device_id snd_mychip_ids[] = { + { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR, + PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, }, + .... + { 0, } + }; + MODULE_DEVICE_TABLE(pci, snd_mychip_ids); + + /* pci_driver definition */ + static struct pci_driver driver = { + .name = KBUILD_MODNAME, + .id_table = snd_mychip_ids, + .probe = snd_mychip_probe, + .remove = snd_mychip_remove, + }; + + /* module initialization */ + static int __init alsa_card_mychip_init(void) + { + return pci_register_driver(&driver); + } + + /* module clean up */ + static void __exit alsa_card_mychip_exit(void) + { + pci_unregister_driver(&driver); + } + + module_init(alsa_card_mychip_init) + module_exit(alsa_card_mychip_exit) + + EXPORT_NO_SYMBOLS; /* for old kernels only */ + +Some Hafta's +------------ + +The allocation of PCI resources is done in the ``probe`` function, and +usually an extra :c:func:`xxx_create()` function is written for this +purpose. + +In the case of PCI devices, you first have to call the +:c:func:`pci_enable_device()` function before allocating +resources. Also, you need to set the proper PCI DMA mask to limit the +accessed I/O range. In some cases, you might need to call +:c:func:`pci_set_master()` function, too. + +Suppose the 28bit mask, and the code to be added would be like: + +:: + + err = pci_enable_device(pci); + if (err < 0) + return err; + if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 || + pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) { + printk(KERN_ERR "error to set 28bit mask DMA\n"); + pci_disable_device(pci); + return -ENXIO; + } + + +Resource Allocation +------------------- + +The allocation of I/O ports and irqs is done via standard kernel +functions. Unlike ALSA ver.0.5.x., there are no helpers for that. And +these resources must be released in the destructor function (see below). +Also, on ALSA 0.9.x, you don't need to allocate (pseudo-)DMA for PCI +like in ALSA 0.5.x. + +Now assume that the PCI device has an I/O port with 8 bytes and an +interrupt. Then :c:type:`struct mychip ` will have the +following fields: + +:: + + struct mychip { + struct snd_card *card; + + unsigned long port; + int irq; + }; + + +For an I/O port (and also a memory region), you need to have the +resource pointer for the standard resource management. For an irq, you +have to keep only the irq number (integer). But you need to initialize +this number as -1 before actual allocation, since irq 0 is valid. The +port address and its resource pointer can be initialized as null by +:c:func:`kzalloc()` automatically, so you don't have to take care of +resetting them. + +The allocation of an I/O port is done like this: + +:: + + err = pci_request_regions(pci, "My Chip"); + if (err < 0) { + kfree(chip); + pci_disable_device(pci); + return err; + } + chip->port = pci_resource_start(pci, 0); + +It will reserve the I/O port region of 8 bytes of the given PCI device. +The returned value, ``chip->res_port``, is allocated via +:c:func:`kmalloc()` by :c:func:`request_region()`. The pointer +must be released via :c:func:`kfree()`, but there is a problem with +this. This issue will be explained later. + +The allocation of an interrupt source is done like this: + +:: + + if (request_irq(pci->irq, snd_mychip_interrupt, + IRQF_SHARED, KBUILD_MODNAME, chip)) { + printk(KERN_ERR "cannot grab irq %d\n", pci->irq); + snd_mychip_free(chip); + return -EBUSY; + } + chip->irq = pci->irq; + +where :c:func:`snd_mychip_interrupt()` is the interrupt handler +defined `later <#pcm-interface-interrupt-handler>`__. Note that +``chip->irq`` should be defined only when :c:func:`request_irq()` +succeeded. + +On the PCI bus, interrupts can be shared. Thus, ``IRQF_SHARED`` is used +as the interrupt flag of :c:func:`request_irq()`. + +The last argument of :c:func:`request_irq()` is the data pointer +passed to the interrupt handler. Usually, the chip-specific record is +used for that, but you can use what you like, too. + +I won't give details about the interrupt handler at this point, but at +least its appearance can be explained now. The interrupt handler looks +usually like the following: + +:: + + static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) + { + struct mychip *chip = dev_id; + .... + return IRQ_HANDLED; + } + + +Now let's write the corresponding destructor for the resources above. +The role of destructor is simple: disable the hardware (if already +activated) and release the resources. So far, we have no hardware part, +so the disabling code is not written here. + +To release the resources, the “check-and-release” method is a safer way. +For the interrupt, do like this: + +:: + + if (chip->irq >= 0) + free_irq(chip->irq, chip); + +Since the irq number can start from 0, you should initialize +``chip->irq`` with a negative value (e.g. -1), so that you can check +the validity of the irq number as above. + +When you requested I/O ports or memory regions via +:c:func:`pci_request_region()` or +:c:func:`pci_request_regions()` like in this example, release the +resource(s) using the corresponding function, +:c:func:`pci_release_region()` or +:c:func:`pci_release_regions()`. + +:: + + pci_release_regions(chip->pci); + +When you requested manually via :c:func:`request_region()` or +:c:func:`request_mem_region()`, you can release it via +:c:func:`release_resource()`. Suppose that you keep the resource +pointer returned from :c:func:`request_region()` in +chip->res_port, the release procedure looks like: + +:: + + release_and_free_resource(chip->res_port); + +Don't forget to call :c:func:`pci_disable_device()` before the +end. + +And finally, release the chip-specific record. + +:: + + kfree(chip); + +We didn't implement the hardware disabling part in the above. If you +need to do this, please note that the destructor may be called even +before the initialization of the chip is completed. It would be better +to have a flag to skip hardware disabling if the hardware was not +initialized yet. + +When the chip-data is assigned to the card using +:c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL`` , its +destructor is called at the last. That is, it is assured that all other +components like PCMs and controls have already been released. You don't +have to stop PCMs, etc. explicitly, but just call low-level hardware +stopping. + +The management of a memory-mapped region is almost as same as the +management of an I/O port. You'll need three fields like the +following: + +:: + + struct mychip { + .... + unsigned long iobase_phys; + void __iomem *iobase_virt; + }; + +and the allocation would be like below: + +:: + + if ((err = pci_request_regions(pci, "My Chip")) < 0) { + kfree(chip); + return err; + } + chip->iobase_phys = pci_resource_start(pci, 0); + chip->iobase_virt = ioremap_nocache(chip->iobase_phys, + pci_resource_len(pci, 0)); + +and the corresponding destructor would be: + +:: + + static int snd_mychip_free(struct mychip *chip) + { + .... + if (chip->iobase_virt) + iounmap(chip->iobase_virt); + .... + pci_release_regions(chip->pci); + .... + } + +PCI Entries +----------- + +So far, so good. Let's finish the missing PCI stuff. At first, we need a +:c:type:`struct pci_device_id ` table for +this chipset. It's a table of PCI vendor/device ID number, and some +masks. + +For example, + +:: + + static struct pci_device_id snd_mychip_ids[] = { + { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR, + PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, }, + .... + { 0, } + }; + MODULE_DEVICE_TABLE(pci, snd_mychip_ids); + +The first and second fields of the :c:type:`struct pci_device_id +` structure are the vendor and device IDs. If you +have no reason to filter the matching devices, you can leave the +remaining fields as above. The last field of the :c:type:`struct +pci_device_id ` struct contains private data +for this entry. You can specify any value here, for example, to define +specific operations for supported device IDs. Such an example is found +in the intel8x0 driver. + +The last entry of this list is the terminator. You must specify this +all-zero entry. + +Then, prepare the :c:type:`struct pci_driver ` +record: + +:: + + static struct pci_driver driver = { + .name = KBUILD_MODNAME, + .id_table = snd_mychip_ids, + .probe = snd_mychip_probe, + .remove = snd_mychip_remove, + }; + +The ``probe`` and ``remove`` functions have already been defined in +the previous sections. The ``name`` field is the name string of this +device. Note that you must not use a slash “/” in this string. + +And at last, the module entries: + +:: + + static int __init alsa_card_mychip_init(void) + { + return pci_register_driver(&driver); + } + + static void __exit alsa_card_mychip_exit(void) + { + pci_unregister_driver(&driver); + } + + module_init(alsa_card_mychip_init) + module_exit(alsa_card_mychip_exit) + +Note that these module entries are tagged with ``__init`` and ``__exit`` +prefixes. + +Oh, one thing was forgotten. If you have no exported symbols, you need +to declare it in 2.2 or 2.4 kernels (it's not necessary in 2.6 kernels). + +:: + + EXPORT_NO_SYMBOLS; + +That's all! + +PCM Interface +============= + +General +------- + +The PCM middle layer of ALSA is quite powerful and it is only necessary +for each driver to implement the low-level functions to access its +hardware. + +For accessing to the PCM layer, you need to include ```` +first. In addition, ```` might be needed if you +access to some functions related with hw_param. + +Each card device can have up to four pcm instances. A pcm instance +corresponds to a pcm device file. The limitation of number of instances +comes only from the available bit size of the Linux's device numbers. +Once when 64bit device number is used, we'll have more pcm instances +available. + +A pcm instance consists of pcm playback and capture streams, and each +pcm stream consists of one or more pcm substreams. Some soundcards +support multiple playback functions. For example, emu10k1 has a PCM +playback of 32 stereo substreams. In this case, at each open, a free +substream is (usually) automatically chosen and opened. Meanwhile, when +only one substream exists and it was already opened, the successful open +will either block or error with ``EAGAIN`` according to the file open +mode. But you don't have to care about such details in your driver. The +PCM middle layer will take care of such work. + +Full Code Example +----------------- + +The example code below does not include any hardware access routines but +shows only the skeleton, how to build up the PCM interfaces. + +:: + + #include + .... + + /* hardware definition */ + static struct snd_pcm_hardware snd_mychip_playback_hw = { + .info = (SNDRV_PCM_INFO_MMAP | + SNDRV_PCM_INFO_INTERLEAVED | + SNDRV_PCM_INFO_BLOCK_TRANSFER | + SNDRV_PCM_INFO_MMAP_VALID), + .formats = SNDRV_PCM_FMTBIT_S16_LE, + .rates = SNDRV_PCM_RATE_8000_48000, + .rate_min = 8000, + .rate_max = 48000, + .channels_min = 2, + .channels_max = 2, + .buffer_bytes_max = 32768, + .period_bytes_min = 4096, + .period_bytes_max = 32768, + .periods_min = 1, + .periods_max = 1024, + }; + + /* hardware definition */ + static struct snd_pcm_hardware snd_mychip_capture_hw = { + .info = (SNDRV_PCM_INFO_MMAP | + SNDRV_PCM_INFO_INTERLEAVED | + SNDRV_PCM_INFO_BLOCK_TRANSFER | + SNDRV_PCM_INFO_MMAP_VALID), + .formats = SNDRV_PCM_FMTBIT_S16_LE, + .rates = SNDRV_PCM_RATE_8000_48000, + .rate_min = 8000, + .rate_max = 48000, + .channels_min = 2, + .channels_max = 2, + .buffer_bytes_max = 32768, + .period_bytes_min = 4096, + .period_bytes_max = 32768, + .periods_min = 1, + .periods_max = 1024, + }; + + /* open callback */ + static int snd_mychip_playback_open(struct snd_pcm_substream *substream) + { + struct mychip *chip = snd_pcm_substream_chip(substream); + struct snd_pcm_runtime *runtime = substream->runtime; + + runtime->hw = snd_mychip_playback_hw; + /* more hardware-initialization will be done here */ + .... + return 0; + } + + /* close callback */ + static int snd_mychip_playback_close(struct snd_pcm_substream *substream) + { + struct mychip *chip = snd_pcm_substream_chip(substream); + /* the hardware-specific codes will be here */ + .... + return 0; + + } + + /* open callback */ + static int snd_mychip_capture_open(struct snd_pcm_substream *substream) + { + struct mychip *chip = snd_pcm_substream_chip(substream); + struct snd_pcm_runtime *runtime = substream->runtime; + + runtime->hw = snd_mychip_capture_hw; + /* more hardware-initialization will be done here */ + .... + return 0; + } + + /* close callback */ + static int snd_mychip_capture_close(struct snd_pcm_substream *substream) + { + struct mychip *chip = snd_pcm_substream_chip(substream); + /* the hardware-specific codes will be here */ + .... + return 0; + + } + + /* hw_params callback */ + static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream, + struct snd_pcm_hw_params *hw_params) + { + return snd_pcm_lib_malloc_pages(substream, + params_buffer_bytes(hw_params)); + } + + /* hw_free callback */ + static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream) + { + return snd_pcm_lib_free_pages(substream); + } + + /* prepare callback */ + static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream) + { + struct mychip *chip = snd_pcm_substream_chip(substream); + struct snd_pcm_runtime *runtime = substream->runtime; + + /* set up the hardware with the current configuration + * for example... + */ + mychip_set_sample_format(chip, runtime->format); + mychip_set_sample_rate(chip, runtime->rate); + mychip_set_channels(chip, runtime->channels); + mychip_set_dma_setup(chip, runtime->dma_addr, + chip->buffer_size, + chip->period_size); + return 0; + } + + /* trigger callback */ + static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream, + int cmd) + { + switch (cmd) { + case SNDRV_PCM_TRIGGER_START: + /* do something to start the PCM engine */ + .... + break; + case SNDRV_PCM_TRIGGER_STOP: + /* do something to stop the PCM engine */ + .... + break; + default: + return -EINVAL; + } + } + + /* pointer callback */ + static snd_pcm_uframes_t + snd_mychip_pcm_pointer(struct snd_pcm_substream *substream) + { + struct mychip *chip = snd_pcm_substream_chip(substream); + unsigned int current_ptr; + + /* get the current hardware pointer */ + current_ptr = mychip_get_hw_pointer(chip); + return current_ptr; + } + + /* operators */ + static struct snd_pcm_ops snd_mychip_playback_ops = { + .open = snd_mychip_playback_open, + .close = snd_mychip_playback_close, + .ioctl = snd_pcm_lib_ioctl, + .hw_params = snd_mychip_pcm_hw_params, + .hw_free = snd_mychip_pcm_hw_free, + .prepare = snd_mychip_pcm_prepare, + .trigger = snd_mychip_pcm_trigger, + .pointer = snd_mychip_pcm_pointer, + }; + + /* operators */ + static struct snd_pcm_ops snd_mychip_capture_ops = { + .open = snd_mychip_capture_open, + .close = snd_mychip_capture_close, + .ioctl = snd_pcm_lib_ioctl, + .hw_params = snd_mychip_pcm_hw_params, + .hw_free = snd_mychip_pcm_hw_free, + .prepare = snd_mychip_pcm_prepare, + .trigger = snd_mychip_pcm_trigger, + .pointer = snd_mychip_pcm_pointer, + }; + + /* + * definitions of capture are omitted here... + */ + + /* create a pcm device */ + static int snd_mychip_new_pcm(struct mychip *chip) + { + struct snd_pcm *pcm; + int err; + + err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm); + if (err < 0) + return err; + pcm->private_data = chip; + strcpy(pcm->name, "My Chip"); + chip->pcm = pcm; + /* set operators */ + snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK, + &snd_mychip_playback_ops); + snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE, + &snd_mychip_capture_ops); + /* pre-allocation of buffers */ + /* NOTE: this may fail */ + snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV, + snd_dma_pci_data(chip->pci), + 64*1024, 64*1024); + return 0; + } + + +PCM Constructor +--------------- + +A pcm instance is allocated by the :c:func:`snd_pcm_new()` +function. It would be better to create a constructor for pcm, namely, + +:: + + static int snd_mychip_new_pcm(struct mychip *chip) + { + struct snd_pcm *pcm; + int err; + + err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm); + if (err < 0) + return err; + pcm->private_data = chip; + strcpy(pcm->name, "My Chip"); + chip->pcm = pcm; + .... + return 0; + } + +The :c:func:`snd_pcm_new()` function takes four arguments. The +first argument is the card pointer to which this pcm is assigned, and +the second is the ID string. + +The third argument (``index``, 0 in the above) is the index of this new +pcm. It begins from zero. If you create more than one pcm instances, +specify the different numbers in this argument. For example, ``index = +1`` for the second PCM device. + +The fourth and fifth arguments are the number of substreams for playback +and capture, respectively. Here 1 is used for both arguments. When no +playback or capture substreams are available, pass 0 to the +corresponding argument. + +If a chip supports multiple playbacks or captures, you can specify more +numbers, but they must be handled properly in open/close, etc. +callbacks. When you need to know which substream you are referring to, +then it can be obtained from :c:type:`struct snd_pcm_substream +` data passed to each callback as follows: + +:: + + struct snd_pcm_substream *substream; + int index = substream->number; + + +After the pcm is created, you need to set operators for each pcm stream. + +:: + + snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK, + &snd_mychip_playback_ops); + snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE, + &snd_mychip_capture_ops); + +The operators are defined typically like this: + +:: + + static struct snd_pcm_ops snd_mychip_playback_ops = { + .open = snd_mychip_pcm_open, + .close = snd_mychip_pcm_close, + .ioctl = snd_pcm_lib_ioctl, + .hw_params = snd_mychip_pcm_hw_params, + .hw_free = snd_mychip_pcm_hw_free, + .prepare = snd_mychip_pcm_prepare, + .trigger = snd_mychip_pcm_trigger, + .pointer = snd_mychip_pcm_pointer, + }; + +All the callbacks are described in the Operators_ subsection. + +After setting the operators, you probably will want to pre-allocate the +buffer. For the pre-allocation, simply call the following: + +:: + + snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV, + snd_dma_pci_data(chip->pci), + 64*1024, 64*1024); + +It will allocate a buffer up to 64kB as default. Buffer management +details will be described in the later section `Buffer and Memory +Management`_. + +Additionally, you can set some extra information for this pcm in +``pcm->info_flags``. The available values are defined as +``SNDRV_PCM_INFO_XXX`` in ````, which is used for the +hardware definition (described later). When your soundchip supports only +half-duplex, specify like this: + +:: + + pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX; + + +... And the Destructor? +----------------------- + +The destructor for a pcm instance is not always necessary. Since the pcm +device will be released by the middle layer code automatically, you +don't have to call the destructor explicitly. + +The destructor would be necessary if you created special records +internally and needed to release them. In such a case, set the +destructor function to ``pcm->private_free``: + +:: + + static void mychip_pcm_free(struct snd_pcm *pcm) + { + struct mychip *chip = snd_pcm_chip(pcm); + /* free your own data */ + kfree(chip->my_private_pcm_data); + /* do what you like else */ + .... + } + + static int snd_mychip_new_pcm(struct mychip *chip) + { + struct snd_pcm *pcm; + .... + /* allocate your own data */ + chip->my_private_pcm_data = kmalloc(...); + /* set the destructor */ + pcm->private_data = chip; + pcm->private_free = mychip_pcm_free; + .... + } + + + +Runtime Pointer - The Chest of PCM Information +---------------------------------------------- + +When the PCM substream is opened, a PCM runtime instance is allocated +and assigned to the substream. This pointer is accessible via +``substream->runtime``. This runtime pointer holds most information you +need to control the PCM: the copy of hw_params and sw_params +configurations, the buffer pointers, mmap records, spinlocks, etc. + +The definition of runtime instance is found in ````. Here +are the contents of this file: + +:: + + struct _snd_pcm_runtime { + /* -- Status -- */ + struct snd_pcm_substream *trigger_master; + snd_timestamp_t trigger_tstamp; /* trigger timestamp */ + int overrange; + snd_pcm_uframes_t avail_max; + snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */ + snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/ + + /* -- HW params -- */ + snd_pcm_access_t access; /* access mode */ + snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */ + snd_pcm_subformat_t subformat; /* subformat */ + unsigned int rate; /* rate in Hz */ + unsigned int channels; /* channels */ + snd_pcm_uframes_t period_size; /* period size */ + unsigned int periods; /* periods */ + snd_pcm_uframes_t buffer_size; /* buffer size */ + unsigned int tick_time; /* tick time */ + snd_pcm_uframes_t min_align; /* Min alignment for the format */ + size_t byte_align; + unsigned int frame_bits; + unsigned int sample_bits; + unsigned int info; + unsigned int rate_num; + unsigned int rate_den; + + /* -- SW params -- */ + struct timespec tstamp_mode; /* mmap timestamp is updated */ + unsigned int period_step; + unsigned int sleep_min; /* min ticks to sleep */ + snd_pcm_uframes_t start_threshold; + snd_pcm_uframes_t stop_threshold; + snd_pcm_uframes_t silence_threshold; /* Silence filling happens when + noise is nearest than this */ + snd_pcm_uframes_t silence_size; /* Silence filling size */ + snd_pcm_uframes_t boundary; /* pointers wrap point */ + + snd_pcm_uframes_t silenced_start; + snd_pcm_uframes_t silenced_size; + + snd_pcm_sync_id_t sync; /* hardware synchronization ID */ + + /* -- mmap -- */ + volatile struct snd_pcm_mmap_status *status; + volatile struct snd_pcm_mmap_control *control; + atomic_t mmap_count; + + /* -- locking / scheduling -- */ + spinlock_t lock; + wait_queue_head_t sleep; + struct timer_list tick_timer; + struct fasync_struct *fasync; + + /* -- private section -- */ + void *private_data; + void (*private_free)(struct snd_pcm_runtime *runtime); + + /* -- hardware description -- */ + struct snd_pcm_hardware hw; + struct snd_pcm_hw_constraints hw_constraints; + + /* -- timer -- */ + unsigned int timer_resolution; /* timer resolution */ + + /* -- DMA -- */ + unsigned char *dma_area; /* DMA area */ + dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */ + size_t dma_bytes; /* size of DMA area */ + + struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */ + + #if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE) + /* -- OSS things -- */ + struct snd_pcm_oss_runtime oss; + #endif + }; + + +For the operators (callbacks) of each sound driver, most of these +records are supposed to be read-only. Only the PCM middle-layer changes +/ updates them. The exceptions are the hardware description (hw) DMA +buffer information and the private data. Besides, if you use the +standard buffer allocation method via +:c:func:`snd_pcm_lib_malloc_pages()`, you don't need to set the +DMA buffer information by yourself. + +In the sections below, important records are explained. + +Hardware Description +~~~~~~~~~~~~~~~~~~~~ + +The hardware descriptor (:c:type:`struct snd_pcm_hardware +`) contains the definitions of the fundamental +hardware configuration. Above all, you'll need to define this in the +`PCM open callback`_. Note that the runtime instance holds the copy of +the descriptor, not the pointer to the existing descriptor. That is, +in the open callback, you can modify the copied descriptor +(``runtime->hw``) as you need. For example, if the maximum number of +channels is 1 only on some chip models, you can still use the same +hardware descriptor and change the channels_max later: + +:: + + struct snd_pcm_runtime *runtime = substream->runtime; + ... + runtime->hw = snd_mychip_playback_hw; /* common definition */ + if (chip->model == VERY_OLD_ONE) + runtime->hw.channels_max = 1; + +Typically, you'll have a hardware descriptor as below: + +:: + + static struct snd_pcm_hardware snd_mychip_playback_hw = { + .info = (SNDRV_PCM_INFO_MMAP | + SNDRV_PCM_INFO_INTERLEAVED | + SNDRV_PCM_INFO_BLOCK_TRANSFER | + SNDRV_PCM_INFO_MMAP_VALID), + .formats = SNDRV_PCM_FMTBIT_S16_LE, + .rates = SNDRV_PCM_RATE_8000_48000, + .rate_min = 8000, + .rate_max = 48000, + .channels_min = 2, + .channels_max = 2, + .buffer_bytes_max = 32768, + .period_bytes_min = 4096, + .period_bytes_max = 32768, + .periods_min = 1, + .periods_max = 1024, + }; + +- The ``info`` field contains the type and capabilities of this + pcm. The bit flags are defined in ```` as + ``SNDRV_PCM_INFO_XXX``. Here, at least, you have to specify whether + the mmap is supported and which interleaved format is + supported. When the hardware supports mmap, add the + ``SNDRV_PCM_INFO_MMAP`` flag here. When the hardware supports the + interleaved or the non-interleaved formats, + ``SNDRV_PCM_INFO_INTERLEAVED`` or ``SNDRV_PCM_INFO_NONINTERLEAVED`` + flag must be set, respectively. If both are supported, you can set + both, too. + + In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are + specified for the OSS mmap mode. Usually both are set. Of course, + ``MMAP_VALID`` is set only if the mmap is really supported. + + The other possible flags are ``SNDRV_PCM_INFO_PAUSE`` and + ``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the pcm + supports the “pause” operation, while the ``RESUME`` bit means that + the pcm supports the full “suspend/resume” operation. If the + ``PAUSE`` flag is set, the ``trigger`` callback below must handle + the corresponding (pause push/release) commands. The suspend/resume + trigger commands can be defined even without the ``RESUME`` + flag. See `Power Management`_ section for details. + + When the PCM substreams can be synchronized (typically, + synchronized start/stop of a playback and a capture streams), you + can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll + need to check the linked-list of PCM substreams in the trigger + callback. This will be described in the later section. + +- ``formats`` field contains the bit-flags of supported formats + (``SNDRV_PCM_FMTBIT_XXX``). If the hardware supports more than one + format, give all or'ed bits. In the example above, the signed 16bit + little-endian format is specified. + +- ``rates`` field contains the bit-flags of supported rates + (``SNDRV_PCM_RATE_XXX``). When the chip supports continuous rates, + pass ``CONTINUOUS`` bit additionally. The pre-defined rate bits are + provided only for typical rates. If your chip supports + unconventional rates, you need to add the ``KNOT`` bit and set up + the hardware constraint manually (explained later). + +- ``rate_min`` and ``rate_max`` define the minimum and maximum sample + rate. This should correspond somehow to ``rates`` bits. + +- ``channel_min`` and ``channel_max`` define, as you might already + expected, the minimum and maximum number of channels. + +- ``buffer_bytes_max`` defines the maximum buffer size in + bytes. There is no ``buffer_bytes_min`` field, since it can be + calculated from the minimum period size and the minimum number of + periods. Meanwhile, ``period_bytes_min`` and define the minimum and + maximum size of the period in bytes. ``periods_max`` and + ``periods_min`` define the maximum and minimum number of periods in + the buffer. + + The “period” is a term that corresponds to a fragment in the OSS + world. The period defines the size at which a PCM interrupt is + generated. This size strongly depends on the hardware. Generally, + the smaller period size will give you more interrupts, that is, + more controls. In the case of capture, this size defines the input + latency. On the other hand, the whole buffer size defines the + output latency for the playback direction. + +- There is also a field ``fifo_size``. This specifies the size of the + hardware FIFO, but currently it is neither used in the driver nor + in the alsa-lib. So, you can ignore this field. + +PCM Configurations +~~~~~~~~~~~~~~~~~~ + +Ok, let's go back again to the PCM runtime records. The most +frequently referred records in the runtime instance are the PCM +configurations. The PCM configurations are stored in the runtime +instance after the application sends ``hw_params`` data via +alsa-lib. There are many fields copied from hw_params and sw_params +structs. For example, ``format`` holds the format type chosen by the +application. This field contains the enum value +``SNDRV_PCM_FORMAT_XXX``. + +One thing to be noted is that the configured buffer and period sizes +are stored in “frames” in the runtime. In the ALSA world, ``1 frame = +channels \* samples-size``. For conversion between frames and bytes, +you can use the :c:func:`frames_to_bytes()` and +:c:func:`bytes_to_frames()` helper functions. + +:: + + period_bytes = frames_to_bytes(runtime, runtime->period_size); + +Also, many software parameters (sw_params) are stored in frames, too. +Please check the type of the field. ``snd_pcm_uframes_t`` is for the +frames as unsigned integer while ``snd_pcm_sframes_t`` is for the +frames as signed integer. + +DMA Buffer Information +~~~~~~~~~~~~~~~~~~~~~~ + +The DMA buffer is defined by the following four fields, ``dma_area``, +``dma_addr``, ``dma_bytes`` and ``dma_private``. The ``dma_area`` +holds the buffer pointer (the logical address). You can call +:c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds +the physical address of the buffer. This field is specified only when +the buffer is a linear buffer. ``dma_bytes`` holds the size of buffer +in bytes. ``dma_private`` is used for the ALSA DMA allocator. + +If you use a standard ALSA function, +:c:func:`snd_pcm_lib_malloc_pages()`, for allocating the buffer, +these fields are set by the ALSA middle layer, and you should *not* +change them by yourself. You can read them but not write them. On the +other hand, if you want to allocate the buffer by yourself, you'll +need to manage it in hw_params callback. At least, ``dma_bytes`` is +mandatory. ``dma_area`` is necessary when the buffer is mmapped. If +your driver doesn't support mmap, this field is not +necessary. ``dma_addr`` is also optional. You can use dma_private as +you like, too. + +Running Status +~~~~~~~~~~~~~~ + +The running status can be referred via ``runtime->status``. This is +the pointer to the :c:type:`struct snd_pcm_mmap_status +` record. For example, you can get the current +DMA hardware pointer via ``runtime->status->hw_ptr``. + +The DMA application pointer can be referred via ``runtime->control``, +which points to the :c:type:`struct snd_pcm_mmap_control +` record. However, accessing directly to +this value is not recommended. + +Private Data +~~~~~~~~~~~~ + +You can allocate a record for the substream and store it in +``runtime->private_data``. Usually, this is done in the `PCM open +callback`_. Don't mix this with ``pcm->private_data``. The +``pcm->private_data`` usually points to the chip instance assigned +statically at the creation of PCM, while the ``runtime->private_data`` +points to a dynamic data structure created at the PCM open +callback. + +:: + + static int snd_xxx_open(struct snd_pcm_substream *substream) + { + struct my_pcm_data *data; + .... + data = kmalloc(sizeof(*data), GFP_KERNEL); + substream->runtime->private_data = data; + .... + } + + +The allocated object must be released in the `close callback`_. + +Operators +--------- + +OK, now let me give details about each pcm callback (``ops``). In +general, every callback must return 0 if successful, or a negative +error number such as ``-EINVAL``. To choose an appropriate error +number, it is advised to check what value other parts of the kernel +return when the same kind of request fails. + +The callback function takes at least the argument with :c:type:`struct +snd_pcm_substream ` pointer. To retrieve the chip +record from the given substream instance, you can use the following +macro. + +:: + + int xxx() { + struct mychip *chip = snd_pcm_substream_chip(substream); + .... + } + +The macro reads ``substream->private_data``, which is a copy of +``pcm->private_data``. You can override the former if you need to +assign different data records per PCM substream. For example, the +cmi8330 driver assigns different ``private_data`` for playback and +capture directions, because it uses two different codecs (SB- and +AD-compatible) for different directions. + +PCM open callback +~~~~~~~~~~~~~~~~~ + +:: + + static int snd_xxx_open(struct snd_pcm_substream *substream); + +This is called when a pcm substream is opened. + +At least, here you have to initialize the ``runtime->hw`` +record. Typically, this is done by like this: + +:: + + static int snd_xxx_open(struct snd_pcm_substream *substream) + { + struct mychip *chip = snd_pcm_substream_chip(substream); + struct snd_pcm_runtime *runtime = substream->runtime; + + runtime->hw = snd_mychip_playback_hw; + return 0; + } + +where ``snd_mychip_playback_hw`` is the pre-defined hardware +description. + +You can allocate a private data in this callback, as described in +`Private Data`_ section. + +If the hardware configuration needs more constraints, set the hardware +constraints here, too. See Constraints_ for more details. + +close callback +~~~~~~~~~~~~~~ + +:: + + static int snd_xxx_close(struct snd_pcm_substream *substream); + + +Obviously, this is called when a pcm substream is closed. + +Any private instance for a pcm substream allocated in the ``open`` +callback will be released here. + +:: + + static int snd_xxx_close(struct snd_pcm_substream *substream) + { + .... + kfree(substream->runtime->private_data); + .... + } + +ioctl callback +~~~~~~~~~~~~~~ + +This is used for any special call to pcm ioctls. But usually you can +pass a generic ioctl callback, :c:func:`snd_pcm_lib_ioctl()`. + +hw_params callback +~~~~~~~~~~~~~~~~~~~ + +:: + + static int snd_xxx_hw_params(struct snd_pcm_substream *substream, + struct snd_pcm_hw_params *hw_params); + +This is called when the hardware parameter (``hw_params``) is set up +by the application, that is, once when the buffer size, the period +size, the format, etc. are defined for the pcm substream. + +Many hardware setups should be done in this callback, including the +allocation of buffers. + +Parameters to be initialized are retrieved by +:c:func:`params_xxx()` macros. To allocate buffer, you can call a +helper function, + +:: + + snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params)); + +:c:func:`snd_pcm_lib_malloc_pages()` is available only when the +DMA buffers have been pre-allocated. See the section `Buffer Types`_ +for more details. + +Note that this and ``prepare`` callbacks may be called multiple times +per initialization. For example, the OSS emulation may call these +callbacks at each change via its ioctl. + +Thus, you need to be careful not to allocate the same buffers many +times, which will lead to memory leaks! Calling the helper function +above many times is OK. It will release the previous buffer +automatically when it was already allocated. + +Another note is that this callback is non-atomic (schedulable) as +default, i.e. when no ``nonatomic`` flag set. This is important, +because the ``trigger`` callback is atomic (non-schedulable). That is, +mutexes or any schedule-related functions are not available in +``trigger`` callback. Please see the subsection Atomicity_ for +details. + +hw_free callback +~~~~~~~~~~~~~~~~~ + +:: + + static int snd_xxx_hw_free(struct snd_pcm_substream *substream); + +This is called to release the resources allocated via +``hw_params``. For example, releasing the buffer via +:c:func:`snd_pcm_lib_malloc_pages()` is done by calling the +following: + +:: + + snd_pcm_lib_free_pages(substream); + +This function is always called before the close callback is called. +Also, the callback may be called multiple times, too. Keep track +whether the resource was already released. + +prepare callback +~~~~~~~~~~~~~~~~ + +:: + + static int snd_xxx_prepare(struct snd_pcm_substream *substream); + +This callback is called when the pcm is “prepared”. You can set the +format type, sample rate, etc. here. The difference from ``hw_params`` +is that the ``prepare`` callback will be called each time +:c:func:`snd_pcm_prepare()` is called, i.e. when recovering after +underruns, etc. + +Note that this callback is now non-atomic. You can use +schedule-related functions safely in this callback. + +In this and the following callbacks, you can refer to the values via +the runtime record, ``substream->runtime``. For example, to get the +current rate, format or channels, access to ``runtime->rate``, +``runtime->format`` or ``runtime->channels``, respectively. The +physical address of the allocated buffer is set to +``runtime->dma_area``. The buffer and period sizes are in +``runtime->buffer_size`` and ``runtime->period_size``, respectively. + +Be careful that this callback will be called many times at each setup, +too. + +trigger callback +~~~~~~~~~~~~~~~~ + +:: + + static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd); + +This is called when the pcm is started, stopped or paused. + +Which action is specified in the second argument, +``SNDRV_PCM_TRIGGER_XXX`` in ````. At least, the ``START`` +and ``STOP`` commands must be defined in this callback. + +:: + + switch (cmd) { + case SNDRV_PCM_TRIGGER_START: + /* do something to start the PCM engine */ + break; + case SNDRV_PCM_TRIGGER_STOP: + /* do something to stop the PCM engine */ + break; + default: + return -EINVAL; + } + +When the pcm supports the pause operation (given in the info field of +the hardware table), the ``PAUSE_PUSH`` and ``PAUSE_RELEASE`` commands +must be handled here, too. The former is the command to pause the pcm, +and the latter to restart the pcm again. + +When the pcm supports the suspend/resume operation, regardless of full +or partial suspend/resume support, the ``SUSPEND`` and ``RESUME`` +commands must be handled, too. These commands are issued when the +power-management status is changed. Obviously, the ``SUSPEND`` and +``RESUME`` commands suspend and resume the pcm substream, and usually, +they are identical to the ``STOP`` and ``START`` commands, respectively. +See the `Power Management`_ section for details. + +As mentioned, this callback is atomic as default unless ``nonatomic`` +flag set, and you cannot call functions which may sleep. The +``trigger`` callback should be as minimal as possible, just really +triggering the DMA. The other stuff should be initialized +``hw_params`` and ``prepare`` callbacks properly beforehand. + +pointer callback +~~~~~~~~~~~~~~~~ + +:: + + static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream) + +This callback is called when the PCM middle layer inquires the current +hardware position on the buffer. The position must be returned in +frames, ranging from 0 to ``buffer_size - 1``. + +This is called usually from the buffer-update routine in the pcm +middle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()` +is called in the interrupt routine. Then the pcm middle layer updates +the position and calculates the available space, and wakes up the +sleeping poll threads, etc. + +This callback is also atomic as default. + +copy and silence callbacks +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These callbacks are not mandatory, and can be omitted in most cases. +These callbacks are used when the hardware buffer cannot be in the +normal memory space. Some chips have their own buffer on the hardware +which is not mappable. In such a case, you have to transfer the data +manually from the memory buffer to the hardware buffer. Or, if the +buffer is non-contiguous on both physical and virtual memory spaces, +these callbacks must be defined, too. + +If these two callbacks are defined, copy and set-silence operations +are done by them. The detailed will be described in the later section +`Buffer and Memory Management`_. + +ack callback +~~~~~~~~~~~~ + +This callback is also not mandatory. This callback is called when the +``appl_ptr`` is updated in read or write operations. Some drivers like +emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the +internal buffer, and this callback is useful only for such a purpose. + +This callback is atomic as default. + +page callback +~~~~~~~~~~~~~ + +This callback is optional too. This callback is used mainly for +non-contiguous buffers. The mmap calls this callback to get the page +address. Some examples will be explained in the later section `Buffer +and Memory Management`_, too. + +PCM Interrupt Handler +--------------------- + +The rest of pcm stuff is the PCM interrupt handler. The role of PCM +interrupt handler in the sound driver is to update the buffer position +and to tell the PCM middle layer when the buffer position goes across +the prescribed period size. To inform this, call the +:c:func:`snd_pcm_period_elapsed()` function. + +There are several types of sound chips to generate the interrupts. + +Interrupts at the period (fragment) boundary +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is the most frequently found type: the hardware generates an +interrupt at each period boundary. In this case, you can call +:c:func:`snd_pcm_period_elapsed()` at each interrupt. + +:c:func:`snd_pcm_period_elapsed()` takes the substream pointer as +its argument. Thus, you need to keep the substream pointer accessible +from the chip instance. For example, define ``substream`` field in the +chip record to hold the current running substream pointer, and set the +pointer value at ``open`` callback (and reset at ``close`` callback). + +If you acquire a spinlock in the interrupt handler, and the lock is used +in other pcm callbacks, too, then you have to release the lock before +calling :c:func:`snd_pcm_period_elapsed()`, because +:c:func:`snd_pcm_period_elapsed()` calls other pcm callbacks +inside. + +Typical code would be like: + +:: + + + static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) + { + struct mychip *chip = dev_id; + spin_lock(&chip->lock); + .... + if (pcm_irq_invoked(chip)) { + /* call updater, unlock before it */ + spin_unlock(&chip->lock); + snd_pcm_period_elapsed(chip->substream); + spin_lock(&chip->lock); + /* acknowledge the interrupt if necessary */ + } + .... + spin_unlock(&chip->lock); + return IRQ_HANDLED; + } + + + +High frequency timer interrupts +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This happens when the hardware doesn't generate interrupts at the period +boundary but issues timer interrupts at a fixed timer rate (e.g. es1968 +or ymfpci drivers). In this case, you need to check the current hardware +position and accumulate the processed sample length at each interrupt. +When the accumulated size exceeds the period size, call +:c:func:`snd_pcm_period_elapsed()` and reset the accumulator. + +Typical code would be like the following. + +:: + + + static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) + { + struct mychip *chip = dev_id; + spin_lock(&chip->lock); + .... + if (pcm_irq_invoked(chip)) { + unsigned int last_ptr, size; + /* get the current hardware pointer (in frames) */ + last_ptr = get_hw_ptr(chip); + /* calculate the processed frames since the + * last update + */ + if (last_ptr < chip->last_ptr) + size = runtime->buffer_size + last_ptr + - chip->last_ptr; + else + size = last_ptr - chip->last_ptr; + /* remember the last updated point */ + chip->last_ptr = last_ptr; + /* accumulate the size */ + chip->size += size; + /* over the period boundary? */ + if (chip->size >= runtime->period_size) { + /* reset the accumulator */ + chip->size %= runtime->period_size; + /* call updater */ + spin_unlock(&chip->lock); + snd_pcm_period_elapsed(substream); + spin_lock(&chip->lock); + } + /* acknowledge the interrupt if necessary */ + } + .... + spin_unlock(&chip->lock); + return IRQ_HANDLED; + } + + + +On calling :c:func:`snd_pcm_period_elapsed()` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In both cases, even if more than one period are elapsed, you don't have +to call :c:func:`snd_pcm_period_elapsed()` many times. Call only +once. And the pcm layer will check the current hardware pointer and +update to the latest status. + +Atomicity +--------- + +One of the most important (and thus difficult to debug) problems in +kernel programming are race conditions. In the Linux kernel, they are +usually avoided via spin-locks, mutexes or semaphores. In general, if a +race condition can happen in an interrupt handler, it has to be managed +atomically, and you have to use a spinlock to protect the critical +session. If the critical section is not in interrupt handler code and if +taking a relatively long time to execute is acceptable, you should use +mutexes or semaphores instead. + +As already seen, some pcm callbacks are atomic and some are not. For +example, the ``hw_params`` callback is non-atomic, while ``trigger`` +callback is atomic. This means, the latter is called already in a +spinlock held by the PCM middle layer. Please take this atomicity into +account when you choose a locking scheme in the callbacks. + +In the atomic callbacks, you cannot use functions which may call +:c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and +mutexes can sleep, and hence they cannot be used inside the atomic +callbacks (e.g. ``trigger`` callback). To implement some delay in such a +callback, please use :c:func:`udelay()` or :c:func:`mdelay()`. + +All three atomic callbacks (trigger, pointer, and ack) are called with +local interrupts disabled. + +The recent changes in PCM core code, however, allow all PCM operations +to be non-atomic. This assumes that the all caller sides are in +non-atomic contexts. For example, the function +:c:func:`snd_pcm_period_elapsed()` is called typically from the +interrupt handler. But, if you set up the driver to use a threaded +interrupt handler, this call can be in non-atomic context, too. In such +a case, you can set ``nonatomic`` filed of :c:type:`struct snd_pcm +` object after creating it. When this flag is set, mutex +and rwsem are used internally in the PCM core instead of spin and +rwlocks, so that you can call all PCM functions safely in a non-atomic +context. + +Constraints +----------- + +If your chip supports unconventional sample rates, or only the limited +samples, you need to set a constraint for the condition. + +For example, in order to restrict the sample rates in the some supported +values, use :c:func:`snd_pcm_hw_constraint_list()`. You need to +call this function in the open callback. + +:: + + static unsigned int rates[] = + {4000, 10000, 22050, 44100}; + static struct snd_pcm_hw_constraint_list constraints_rates = { + .count = ARRAY_SIZE(rates), + .list = rates, + .mask = 0, + }; + + static int snd_mychip_pcm_open(struct snd_pcm_substream *substream) + { + int err; + .... + err = snd_pcm_hw_constraint_list(substream->runtime, 0, + SNDRV_PCM_HW_PARAM_RATE, + &constraints_rates); + if (err < 0) + return err; + .... + } + + + +There are many different constraints. Look at ``sound/pcm.h`` for a +complete list. You can even define your own constraint rules. For +example, let's suppose my_chip can manage a substream of 1 channel if +and only if the format is ``S16_LE``, otherwise it supports any format +specified in the :c:type:`struct snd_pcm_hardware +` structure (or in any other +constraint_list). You can build a rule like this: + +:: + + static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params, + struct snd_pcm_hw_rule *rule) + { + struct snd_interval *c = hw_param_interval(params, + SNDRV_PCM_HW_PARAM_CHANNELS); + struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT); + struct snd_interval ch; + + snd_interval_any(&ch); + if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) { + ch.min = ch.max = 1; + ch.integer = 1; + return snd_interval_refine(c, &ch); + } + return 0; + } + + +Then you need to call this function to add your rule: + +:: + + snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS, + hw_rule_channels_by_format, NULL, + SNDRV_PCM_HW_PARAM_FORMAT, -1); + +The rule function is called when an application sets the PCM format, and +it refines the number of channels accordingly. But an application may +set the number of channels before setting the format. Thus you also need +to define the inverse rule: + +:: + + static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params, + struct snd_pcm_hw_rule *rule) + { + struct snd_interval *c = hw_param_interval(params, + SNDRV_PCM_HW_PARAM_CHANNELS); + struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT); + struct snd_mask fmt; + + snd_mask_any(&fmt); /* Init the struct */ + if (c->min < 2) { + fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE; + return snd_mask_refine(f, &fmt); + } + return 0; + } + + +... and in the open callback: + +:: + + snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT, + hw_rule_format_by_channels, NULL, + SNDRV_PCM_HW_PARAM_CHANNELS, -1); + +I won't give more details here, rather I would like to say, “Luke, use +the source.” + +Control Interface +================= + +General +------- + +The control interface is used widely for many switches, sliders, etc. +which are accessed from user-space. Its most important use is the mixer +interface. In other words, since ALSA 0.9.x, all the mixer stuff is +implemented on the control kernel API. + +ALSA has a well-defined AC97 control module. If your chip supports only +the AC97 and nothing else, you can skip this section. + +The control API is defined in ````. Include this file +if you want to add your own controls. + +Definition of Controls +---------------------- + +To create a new control, you need to define the following three +callbacks: ``info``, ``get`` and ``put``. Then, define a +:c:type:`struct snd_kcontrol_new ` record, such as: + +:: + + + static struct snd_kcontrol_new my_control = { + .iface = SNDRV_CTL_ELEM_IFACE_MIXER, + .name = "PCM Playback Switch", + .index = 0, + .access = SNDRV_CTL_ELEM_ACCESS_READWRITE, + .private_value = 0xffff, + .info = my_control_info, + .get = my_control_get, + .put = my_control_put + }; + + +The ``iface`` field specifies the control type, +``SNDRV_CTL_ELEM_IFACE_XXX``, which is usually ``MIXER``. Use ``CARD`` +for global controls that are not logically part of the mixer. If the +control is closely associated with some specific device on the sound +card, use ``HWDEP``, ``PCM``, ``RAWMIDI``, ``TIMER``, or ``SEQUENCER``, +and specify the device number with the ``device`` and ``subdevice`` +fields. + +The ``name`` is the name identifier string. Since ALSA 0.9.x, the +control name is very important, because its role is classified from +its name. There are pre-defined standard control names. The details +are described in the `Control Names`_ subsection. + +The ``index`` field holds the index number of this control. If there +are several different controls with the same name, they can be +distinguished by the index number. This is the case when several +codecs exist on the card. If the index is zero, you can omit the +definition above. + +The ``access`` field contains the access type of this control. Give +the combination of bit masks, ``SNDRV_CTL_ELEM_ACCESS_XXX``, +there. The details will be explained in the `Access Flags`_ +subsection. + +The ``private_value`` field contains an arbitrary long integer value +for this record. When using the generic ``info``, ``get`` and ``put`` +callbacks, you can pass a value through this field. If several small +numbers are necessary, you can combine them in bitwise. Or, it's +possible to give a pointer (casted to unsigned long) of some record to +this field, too. + +The ``tlv`` field can be used to provide metadata about the control; +see the `Metadata`_ subsection. + +The other three are `Control Callbacks`_. + +Control Names +------------- + +There are some standards to define the control names. A control is +usually defined from the three parts as “SOURCE DIRECTION FUNCTION”. + +The first, ``SOURCE``, specifies the source of the control, and is a +string such as “Master”, “PCM”, “CD” and “Line”. There are many +pre-defined sources. + +The second, ``DIRECTION``, is one of the following strings according to +the direction of the control: “Playback”, “Capture”, “Bypass Playback” +and “Bypass Capture”. Or, it can be omitted, meaning both playback and +capture directions. + +The third, ``FUNCTION``, is one of the following strings according to +the function of the control: “Switch”, “Volume” and “Route”. + +The example of control names are, thus, “Master Capture Switch” or “PCM +Playback Volume”. + +There are some exceptions: + +Global capture and playback +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +“Capture Source”, “Capture Switch” and “Capture Volume” are used for the +global capture (input) source, switch and volume. Similarly, “Playback +Switch” and “Playback Volume” are used for the global output gain switch +and volume. + +Tone-controls +~~~~~~~~~~~~~ + +tone-control switch and volumes are specified like “Tone Control - XXX”, +e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control - +Center”. + +3D controls +~~~~~~~~~~~ + +3D-control switches and volumes are specified like “3D Control - XXX”, +e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”. + +Mic boost +~~~~~~~~~ + +Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”. + +More precise information can be found in +``Documentation/sound/alsa/ControlNames.txt``. + +Access Flags +------------ + +The access flag is the bitmask which specifies the access type of the +given control. The default access type is +``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which means both read and write are +allowed to this control. When the access flag is omitted (i.e. = 0), it +is considered as ``READWRITE`` access as default. + +When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ`` +instead. In this case, you don't have to define the ``put`` callback. +Similarly, when the control is write-only (although it's a rare case), +you can use the ``WRITE`` flag instead, and you don't need the ``get`` +callback. + +If the control value changes frequently (e.g. the VU meter), +``VOLATILE`` flag should be given. This means that the control may be +changed without `Change notification`_. Applications should poll such +a control constantly. + +When the control is inactive, set the ``INACTIVE`` flag, too. There are +``LOCK`` and ``OWNER`` flags to change the write permissions. + +Control Callbacks +----------------- + +info callback +~~~~~~~~~~~~~ + +The ``info`` callback is used to get detailed information on this +control. This must store the values of the given :c:type:`struct +snd_ctl_elem_info ` object. For example, +for a boolean control with a single element: + +:: + + + static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_info *uinfo) + { + uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN; + uinfo->count = 1; + uinfo->value.integer.min = 0; + uinfo->value.integer.max = 1; + return 0; + } + + + +The ``type`` field specifies the type of the control. There are +``BOOLEAN``, ``INTEGER``, ``ENUMERATED``, ``BYTES``, ``IEC958`` and +``INTEGER64``. The ``count`` field specifies the number of elements in +this control. For example, a stereo volume would have count = 2. The +``value`` field is a union, and the values stored are depending on the +type. The boolean and integer types are identical. + +The enumerated type is a bit different from others. You'll need to set +the string for the currently given item index. + +:: + + static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_info *uinfo) + { + static char *texts[4] = { + "First", "Second", "Third", "Fourth" + }; + uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED; + uinfo->count = 1; + uinfo->value.enumerated.items = 4; + if (uinfo->value.enumerated.item > 3) + uinfo->value.enumerated.item = 3; + strcpy(uinfo->value.enumerated.name, + texts[uinfo->value.enumerated.item]); + return 0; + } + +The above callback can be simplified with a helper function, +:c:func:`snd_ctl_enum_info()`. The final code looks like below. +(You can pass ``ARRAY_SIZE(texts)`` instead of 4 in the third argument; +it's a matter of taste.) + +:: + + static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_info *uinfo) + { + static char *texts[4] = { + "First", "Second", "Third", "Fourth" + }; + return snd_ctl_enum_info(uinfo, 1, 4, texts); + } + + +Some common info callbacks are available for your convenience: +:c:func:`snd_ctl_boolean_mono_info()` and +:c:func:`snd_ctl_boolean_stereo_info()`. Obviously, the former +is an info callback for a mono channel boolean item, just like +:c:func:`snd_myctl_mono_info()` above, and the latter is for a +stereo channel boolean item. + +get callback +~~~~~~~~~~~~ + +This callback is used to read the current value of the control and to +return to user-space. + +For example, + +:: + + + static int snd_myctl_get(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_value *ucontrol) + { + struct mychip *chip = snd_kcontrol_chip(kcontrol); + ucontrol->value.integer.value[0] = get_some_value(chip); + return 0; + } + + + +The ``value`` field depends on the type of control as well as on the +info callback. For example, the sb driver uses this field to store the +register offset, the bit-shift and the bit-mask. The ``private_value`` +field is set as follows: + +:: + + .private_value = reg | (shift << 16) | (mask << 24) + +and is retrieved in callbacks like + +:: + + static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_value *ucontrol) + { + int reg = kcontrol->private_value & 0xff; + int shift = (kcontrol->private_value >> 16) & 0xff; + int mask = (kcontrol->private_value >> 24) & 0xff; + .... + } + +In the ``get`` callback, you have to fill all the elements if the +control has more than one elements, i.e. ``count > 1``. In the example +above, we filled only one element (``value.integer.value[0]``) since +it's assumed as ``count = 1``. + +put callback +~~~~~~~~~~~~ + +This callback is used to write a value from user-space. + +For example, + +:: + + + static int snd_myctl_put(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_value *ucontrol) + { + struct mychip *chip = snd_kcontrol_chip(kcontrol); + int changed = 0; + if (chip->current_value != + ucontrol->value.integer.value[0]) { + change_current_value(chip, + ucontrol->value.integer.value[0]); + changed = 1; + } + return changed; + } + + + +As seen above, you have to return 1 if the value is changed. If the +value is not changed, return 0 instead. If any fatal error happens, +return a negative error code as usual. + +As in the ``get`` callback, when the control has more than one +elements, all elements must be evaluated in this callback, too. + +Callbacks are not atomic +~~~~~~~~~~~~~~~~~~~~~~~~ + +All these three callbacks are basically not atomic. + +Control Constructor +------------------- + +When everything is ready, finally we can create a new control. To create +a control, there are two functions to be called, +:c:func:`snd_ctl_new1()` and :c:func:`snd_ctl_add()`. + +In the simplest way, you can do like this: + +:: + + err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip)); + if (err < 0) + return err; + +where ``my_control`` is the :c:type:`struct snd_kcontrol_new +` object defined above, and chip is the object +pointer to be passed to kcontrol->private_data which can be referred +to in callbacks. + +:c:func:`snd_ctl_new1()` allocates a new :c:type:`struct +snd_kcontrol ` instance, and +:c:func:`snd_ctl_add()` assigns the given control component to the +card. + +Change Notification +------------------- + +If you need to change and update a control in the interrupt routine, you +can call :c:func:`snd_ctl_notify()`. For example, + +:: + + snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer); + +This function takes the card pointer, the event-mask, and the control id +pointer for the notification. The event-mask specifies the types of +notification, for example, in the above example, the change of control +values is notified. The id pointer is the pointer of :c:type:`struct +snd_ctl_elem_id ` to be notified. You can +find some examples in ``es1938.c`` or ``es1968.c`` for hardware volume +interrupts. + +Metadata +-------- + +To provide information about the dB values of a mixer control, use on of +the ``DECLARE_TLV_xxx`` macros from ```` to define a +variable containing this information, set the ``tlv.p`` field to point to +this variable, and include the ``SNDRV_CTL_ELEM_ACCESS_TLV_READ`` flag +in the ``access`` field; like this: + +:: + + static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0); + + static struct snd_kcontrol_new my_control = { + ... + .access = SNDRV_CTL_ELEM_ACCESS_READWRITE | + SNDRV_CTL_ELEM_ACCESS_TLV_READ, + ... + .tlv.p = db_scale_my_control, + }; + + +The :c:func:`DECLARE_TLV_DB_SCALE()` macro defines information +about a mixer control where each step in the control's value changes the +dB value by a constant dB amount. The first parameter is the name of the +variable to be defined. The second parameter is the minimum value, in +units of 0.01 dB. The third parameter is the step size, in units of 0.01 +dB. Set the fourth parameter to 1 if the minimum value actually mutes +the control. + +The :c:func:`DECLARE_TLV_DB_LINEAR()` macro defines information +about a mixer control where the control's value affects the output +linearly. The first parameter is the name of the variable to be defined. +The second parameter is the minimum value, in units of 0.01 dB. The +third parameter is the maximum value, in units of 0.01 dB. If the +minimum value mutes the control, set the second parameter to +``TLV_DB_GAIN_MUTE``. + +API for AC97 Codec +================== + +General +------- + +The ALSA AC97 codec layer is a well-defined one, and you don't have to +write much code to control it. Only low-level control routines are +necessary. The AC97 codec API is defined in ````. + +Full Code Example +----------------- + +:: + + struct mychip { + .... + struct snd_ac97 *ac97; + .... + }; + + static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97, + unsigned short reg) + { + struct mychip *chip = ac97->private_data; + .... + /* read a register value here from the codec */ + return the_register_value; + } + + static void snd_mychip_ac97_write(struct snd_ac97 *ac97, + unsigned short reg, unsigned short val) + { + struct mychip *chip = ac97->private_data; + .... + /* write the given register value to the codec */ + } + + static int snd_mychip_ac97(struct mychip *chip) + { + struct snd_ac97_bus *bus; + struct snd_ac97_template ac97; + int err; + static struct snd_ac97_bus_ops ops = { + .write = snd_mychip_ac97_write, + .read = snd_mychip_ac97_read, + }; + + err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus); + if (err < 0) + return err; + memset(&ac97, 0, sizeof(ac97)); + ac97.private_data = chip; + return snd_ac97_mixer(bus, &ac97, &chip->ac97); + } + + +AC97 Constructor +---------------- + +To create an ac97 instance, first call :c:func:`snd_ac97_bus()` +with an ``ac97_bus_ops_t`` record with callback functions. + +:: + + struct snd_ac97_bus *bus; + static struct snd_ac97_bus_ops ops = { + .write = snd_mychip_ac97_write, + .read = snd_mychip_ac97_read, + }; + + snd_ac97_bus(card, 0, &ops, NULL, &pbus); + +The bus record is shared among all belonging ac97 instances. + +And then call :c:func:`snd_ac97_mixer()` with an :c:type:`struct +snd_ac97_template ` record together with +the bus pointer created above. + +:: + + struct snd_ac97_template ac97; + int err; + + memset(&ac97, 0, sizeof(ac97)); + ac97.private_data = chip; + snd_ac97_mixer(bus, &ac97, &chip->ac97); + +where chip->ac97 is a pointer to a newly created ``ac97_t`` +instance. In this case, the chip pointer is set as the private data, +so that the read/write callback functions can refer to this chip +instance. This instance is not necessarily stored in the chip +record. If you need to change the register values from the driver, or +need the suspend/resume of ac97 codecs, keep this pointer to pass to +the corresponding functions. + +AC97 Callbacks +-------------- + +The standard callbacks are ``read`` and ``write``. Obviously they +correspond to the functions for read and write accesses to the +hardware low-level codes. + +The ``read`` callback returns the register value specified in the +argument. + +:: + + static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97, + unsigned short reg) + { + struct mychip *chip = ac97->private_data; + .... + return the_register_value; + } + +Here, the chip can be cast from ``ac97->private_data``. + +Meanwhile, the ``write`` callback is used to set the register +value + +:: + + static void snd_mychip_ac97_write(struct snd_ac97 *ac97, + unsigned short reg, unsigned short val) + + +These callbacks are non-atomic like the control API callbacks. + +There are also other callbacks: ``reset``, ``wait`` and ``init``. + +The ``reset`` callback is used to reset the codec. If the chip +requires a special kind of reset, you can define this callback. + +The ``wait`` callback is used to add some waiting time in the standard +initialization of the codec. If the chip requires the extra waiting +time, define this callback. + +The ``init`` callback is used for additional initialization of the +codec. + +Updating Registers in The Driver +-------------------------------- + +If you need to access to the codec from the driver, you can call the +following functions: :c:func:`snd_ac97_write()`, +:c:func:`snd_ac97_read()`, :c:func:`snd_ac97_update()` and +:c:func:`snd_ac97_update_bits()`. + +Both :c:func:`snd_ac97_write()` and +:c:func:`snd_ac97_update()` functions are used to set a value to +the given register (``AC97_XXX``). The difference between them is that +:c:func:`snd_ac97_update()` doesn't write a value if the given +value has been already set, while :c:func:`snd_ac97_write()` +always rewrites the value. + +:: + + snd_ac97_write(ac97, AC97_MASTER, 0x8080); + snd_ac97_update(ac97, AC97_MASTER, 0x8080); + +:c:func:`snd_ac97_read()` is used to read the value of the given +register. For example, + +:: + + value = snd_ac97_read(ac97, AC97_MASTER); + +:c:func:`snd_ac97_update_bits()` is used to update some bits in +the given register. + +:: + + snd_ac97_update_bits(ac97, reg, mask, value); + +Also, there is a function to change the sample rate (of a given register +such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the +codec: :c:func:`snd_ac97_set_rate()`. + +:: + + snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100); + + +The following registers are available to set the rate: +``AC97_PCM_MIC_ADC_RATE``, ``AC97_PCM_FRONT_DAC_RATE``, +``AC97_PCM_LR_ADC_RATE``, ``AC97_SPDIF``. When ``AC97_SPDIF`` is +specified, the register is not really changed but the corresponding +IEC958 status bits will be updated. + +Clock Adjustment +---------------- + +In some chips, the clock of the codec isn't 48000 but using a PCI clock +(to save a quartz!). In this case, change the field ``bus->clock`` to +the corresponding value. For example, intel8x0 and es1968 drivers have +their own function to read from the clock. + +Proc Files +---------- + +The ALSA AC97 interface will create a proc file such as +``/proc/asound/card0/codec97#0/ac97#0-0`` and ``ac97#0-0+regs``. You +can refer to these files to see the current status and registers of +the codec. + +Multiple Codecs +--------------- + +When there are several codecs on the same card, you need to call +:c:func:`snd_ac97_mixer()` multiple times with ``ac97.num=1`` or +greater. The ``num`` field specifies the codec number. + +If you set up multiple codecs, you either need to write different +callbacks for each codec or check ``ac97->num`` in the callback +routines. + +MIDI (MPU401-UART) Interface +============================ + +General +------- + +Many soundcards have built-in MIDI (MPU401-UART) interfaces. When the +soundcard supports the standard MPU401-UART interface, most likely you +can use the ALSA MPU401-UART API. The MPU401-UART API is defined in +````. + +Some soundchips have a similar but slightly different implementation of +mpu401 stuff. For example, emu10k1 has its own mpu401 routines. + +MIDI Constructor +---------------- + +To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`. + +:: + + struct snd_rawmidi *rmidi; + snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags, + irq, &rmidi); + + +The first argument is the card pointer, and the second is the index of +this component. You can create up to 8 rawmidi devices. + +The third argument is the type of the hardware, ``MPU401_HW_XXX``. If +it's not a special one, you can use ``MPU401_HW_MPU401``. + +The 4th argument is the I/O port address. Many backward-compatible +MPU401 have an I/O port such as 0x330. Or, it might be a part of its own +PCI I/O region. It depends on the chip design. + +The 5th argument is a bitflag for additional information. When the I/O +port address above is part of the PCI I/O region, the MPU401 I/O port +might have been already allocated (reserved) by the driver itself. In +such a case, pass a bit flag ``MPU401_INFO_INTEGRATED``, and the +mpu401-uart layer will allocate the I/O ports by itself. + +When the controller supports only the input or output MIDI stream, pass +the ``MPU401_INFO_INPUT`` or ``MPU401_INFO_OUTPUT`` bitflag, +respectively. Then the rawmidi instance is created as a single stream. + +``MPU401_INFO_MMIO`` bitflag is used to change the access method to MMIO +(via readb and writeb) instead of iob and outb. In this case, you have +to pass the iomapped address to :c:func:`snd_mpu401_uart_new()`. + +When ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in +the default interrupt handler. The driver needs to call +:c:func:`snd_mpu401_uart_interrupt_tx()` by itself to start +processing the output stream in the irq handler. + +If the MPU-401 interface shares its interrupt with the other logical +devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see +`below <#MIDI-Interrupt-Handler>`__). + +Usually, the port address corresponds to the command port and port + 1 +corresponds to the data port. If not, you may change the ``cport`` +field of :c:type:`struct snd_mpu401 ` manually afterward. +However, :c:type:`struct snd_mpu401 ` pointer is +not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You +need to cast ``rmidi->private_data`` to :c:type:`struct snd_mpu401 +` explicitly, + +:: + + struct snd_mpu401 *mpu; + mpu = rmidi->private_data; + +and reset the ``cport`` as you like: + +:: + + mpu->cport = my_own_control_port; + +The 6th argument specifies the ISA irq number that will be allocated. If +no interrupt is to be allocated (because your code is already allocating +a shared interrupt, or because the device does not use interrupts), pass +-1 instead. For a MPU-401 device without an interrupt, a polling timer +will be used instead. + +MIDI Interrupt Handler +---------------------- + +When the interrupt is allocated in +:c:func:`snd_mpu401_uart_new()`, an exclusive ISA interrupt +handler is automatically used, hence you don't have anything else to do +than creating the mpu401 stuff. Otherwise, you have to set +``MPU401_INFO_IRQ_HOOK``, and call +:c:func:`snd_mpu401_uart_interrupt()` explicitly from your own +interrupt handler when it has determined that a UART interrupt has +occurred. + +In this case, you need to pass the private_data of the returned rawmidi +object from :c:func:`snd_mpu401_uart_new()` as the second +argument of :c:func:`snd_mpu401_uart_interrupt()`. + +:: + + snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs); + + +RawMIDI Interface +================= + +Overview +-------- + +The raw MIDI interface is used for hardware MIDI ports that can be +accessed as a byte stream. It is not used for synthesizer chips that do +not directly understand MIDI. + +ALSA handles file and buffer management. All you have to do is to write +some code to move data between the buffer and the hardware. + +The rawmidi API is defined in ````. + +RawMIDI Constructor +------------------- + +To create a rawmidi device, call the :c:func:`snd_rawmidi_new()` +function: + +:: + + struct snd_rawmidi *rmidi; + err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi); + if (err < 0) + return err; + rmidi->private_data = chip; + strcpy(rmidi->name, "My MIDI"); + rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT | + SNDRV_RAWMIDI_INFO_INPUT | + SNDRV_RAWMIDI_INFO_DUPLEX; + +The first argument is the card pointer, the second argument is the ID +string. + +The third argument is the index of this component. You can create up to +8 rawmidi devices. + +The fourth and fifth arguments are the number of output and input +substreams, respectively, of this device (a substream is the equivalent +of a MIDI port). + +Set the ``info_flags`` field to specify the capabilities of the +device. Set ``SNDRV_RAWMIDI_INFO_OUTPUT`` if there is at least one +output port, ``SNDRV_RAWMIDI_INFO_INPUT`` if there is at least one +input port, and ``SNDRV_RAWMIDI_INFO_DUPLEX`` if the device can handle +output and input at the same time. + +After the rawmidi device is created, you need to set the operators +(callbacks) for each substream. There are helper functions to set the +operators for all the substreams of a device: + +:: + + snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops); + snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops); + +The operators are usually defined like this: + +:: + + static struct snd_rawmidi_ops snd_mymidi_output_ops = { + .open = snd_mymidi_output_open, + .close = snd_mymidi_output_close, + .trigger = snd_mymidi_output_trigger, + }; + +These callbacks are explained in the `RawMIDI Callbacks`_ section. + +If there are more than one substream, you should give a unique name to +each of them: + +:: + + struct snd_rawmidi_substream *substream; + list_for_each_entry(substream, + &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams, + list { + sprintf(substream->name, "My MIDI Port %d", substream->number + 1); + } + /* same for SNDRV_RAWMIDI_STREAM_INPUT */ + +RawMIDI Callbacks +----------------- + +In all the callbacks, the private data that you've set for the rawmidi +device can be accessed as ``substream->rmidi->private_data``. + +If there is more than one port, your callbacks can determine the port +index from the struct snd_rawmidi_substream data passed to each +callback: + +:: + + struct snd_rawmidi_substream *substream; + int index = substream->number; + +RawMIDI open callback +~~~~~~~~~~~~~~~~~~~~~ + +:: + + static int snd_xxx_open(struct snd_rawmidi_substream *substream); + + +This is called when a substream is opened. You can initialize the +hardware here, but you shouldn't start transmitting/receiving data yet. + +RawMIDI close callback +~~~~~~~~~~~~~~~~~~~~~~ + +:: + + static int snd_xxx_close(struct snd_rawmidi_substream *substream); + +Guess what. + +The ``open`` and ``close`` callbacks of a rawmidi device are +serialized with a mutex, and can sleep. + +Rawmidi trigger callback for output substreams +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up); + + +This is called with a nonzero ``up`` parameter when there is some data +in the substream buffer that must be transmitted. + +To read data from the buffer, call +:c:func:`snd_rawmidi_transmit_peek()`. It will return the number +of bytes that have been read; this will be less than the number of bytes +requested when there are no more data in the buffer. After the data have +been transmitted successfully, call +:c:func:`snd_rawmidi_transmit_ack()` to remove the data from the +substream buffer: + +:: + + unsigned char data; + while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) { + if (snd_mychip_try_to_transmit(data)) + snd_rawmidi_transmit_ack(substream, 1); + else + break; /* hardware FIFO full */ + } + +If you know beforehand that the hardware will accept data, you can use +the :c:func:`snd_rawmidi_transmit()` function which reads some +data and removes them from the buffer at once: + +:: + + while (snd_mychip_transmit_possible()) { + unsigned char data; + if (snd_rawmidi_transmit(substream, &data, 1) != 1) + break; /* no more data */ + snd_mychip_transmit(data); + } + +If you know beforehand how many bytes you can accept, you can use a +buffer size greater than one with the +:c:func:`snd_rawmidi_transmit\*()` functions. + +The ``trigger`` callback must not sleep. If the hardware FIFO is full +before the substream buffer has been emptied, you have to continue +transmitting data later, either in an interrupt handler, or with a +timer if the hardware doesn't have a MIDI transmit interrupt. + +The ``trigger`` callback is called with a zero ``up`` parameter when +the transmission of data should be aborted. + +RawMIDI trigger callback for input substreams +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +:: + + static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up); + + +This is called with a nonzero ``up`` parameter to enable receiving data, +or with a zero ``up`` parameter do disable receiving data. + +The ``trigger`` callback must not sleep; the actual reading of data +from the device is usually done in an interrupt handler. + +When data reception is enabled, your interrupt handler should call +:c:func:`snd_rawmidi_receive()` for all received data: + +:: + + void snd_mychip_midi_interrupt(...) + { + while (mychip_midi_available()) { + unsigned char data; + data = mychip_midi_read(); + snd_rawmidi_receive(substream, &data, 1); + } + } + + +drain callback +~~~~~~~~~~~~~~ + +:: + + static void snd_xxx_drain(struct snd_rawmidi_substream *substream); + + +This is only used with output substreams. This function should wait +until all data read from the substream buffer have been transmitted. +This ensures that the device can be closed and the driver unloaded +without losing data. + +This callback is optional. If you do not set ``drain`` in the struct +snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds +instead. + +Miscellaneous Devices +===================== + +FM OPL3 +------- + +The FM OPL3 is still used in many chips (mainly for backward +compatibility). ALSA has a nice OPL3 FM control layer, too. The OPL3 API +is defined in ````. + +FM registers can be directly accessed through the direct-FM API, defined +in ````. In ALSA native mode, FM registers are +accessed through the Hardware-Dependent Device direct-FM extension API, +whereas in OSS compatible mode, FM registers can be accessed with the +OSS direct-FM compatible API in ``/dev/dmfmX`` device. + +To create the OPL3 component, you have two functions to call. The first +one is a constructor for the ``opl3_t`` instance. + +:: + + struct snd_opl3 *opl3; + snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX, + integrated, &opl3); + +The first argument is the card pointer, the second one is the left port +address, and the third is the right port address. In most cases, the +right port is placed at the left port + 2. + +The fourth argument is the hardware type. + +When the left and right ports have been already allocated by the card +driver, pass non-zero to the fifth argument (``integrated``). Otherwise, +the opl3 module will allocate the specified ports by itself. + +When the accessing the hardware requires special method instead of the +standard I/O access, you can create opl3 instance separately with +:c:func:`snd_opl3_new()`. + +:: + + struct snd_opl3 *opl3; + snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3); + +Then set ``command``, ``private_data`` and ``private_free`` for the +private access function, the private data and the destructor. The +``l_port`` and ``r_port`` are not necessarily set. Only the command +must be set properly. You can retrieve the data from the +``opl3->private_data`` field. + +After creating the opl3 instance via :c:func:`snd_opl3_new()`, +call :c:func:`snd_opl3_init()` to initialize the chip to the +proper state. Note that :c:func:`snd_opl3_create()` always calls +it internally. + +If the opl3 instance is created successfully, then create a hwdep device +for this opl3. + +:: + + struct snd_hwdep *opl3hwdep; + snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep); + +The first argument is the ``opl3_t`` instance you created, and the +second is the index number, usually 0. + +The third argument is the index-offset for the sequencer client assigned +to the OPL3 port. When there is an MPU401-UART, give 1 for here (UART +always takes 0). + +Hardware-Dependent Devices +-------------------------- + +Some chips need user-space access for special controls or for loading +the micro code. In such a case, you can create a hwdep +(hardware-dependent) device. The hwdep API is defined in +````. You can find examples in opl3 driver or +``isa/sb/sb16_csp.c``. + +The creation of the ``hwdep`` instance is done via +:c:func:`snd_hwdep_new()`. + +:: + + struct snd_hwdep *hw; + snd_hwdep_new(card, "My HWDEP", 0, &hw); + +where the third argument is the index number. + +You can then pass any pointer value to the ``private_data``. If you +assign a private data, you should define the destructor, too. The +destructor function is set in the ``private_free`` field. + +:: + + struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL); + hw->private_data = p; + hw->private_free = mydata_free; + +and the implementation of the destructor would be: + +:: + + static void mydata_free(struct snd_hwdep *hw) + { + struct mydata *p = hw->private_data; + kfree(p); + } + +The arbitrary file operations can be defined for this instance. The file +operators are defined in the ``ops`` table. For example, assume that +this chip needs an ioctl. + +:: + + hw->ops.open = mydata_open; + hw->ops.ioctl = mydata_ioctl; + hw->ops.release = mydata_release; + +And implement the callback functions as you like. + +IEC958 (S/PDIF) +--------------- + +Usually the controls for IEC958 devices are implemented via the control +interface. There is a macro to compose a name string for IEC958 +controls, :c:func:`SNDRV_CTL_NAME_IEC958()` defined in +````. + +There are some standard controls for IEC958 status bits. These controls +use the type ``SNDRV_CTL_ELEM_TYPE_IEC958``, and the size of element is +fixed as 4 bytes array (value.iec958.status[x]). For the ``info`` +callback, you don't specify the value field for this type (the count +field must be set, though). + +“IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958 +status bits of consumer mode. Similarly, “IEC958 Playback Pro Mask” +returns the bitmask for professional mode. They are read-only controls, +and are defined as MIXER controls (iface = +``SNDRV_CTL_ELEM_IFACE_MIXER``). + +Meanwhile, “IEC958 Playback Default” control is defined for getting and +setting the current default IEC958 bits. Note that this one is usually +defined as a PCM control (iface = ``SNDRV_CTL_ELEM_IFACE_PCM``), +although in some places it's defined as a MIXER control. + +In addition, you can define the control switches to enable/disable or to +set the raw bit mode. The implementation will depend on the chip, but +the control should be named as “IEC958 xxx”, preferably using the +:c:func:`SNDRV_CTL_NAME_IEC958()` macro. + +You can find several cases, for example, ``pci/emu10k1``, +``pci/ice1712``, or ``pci/cmipci.c``. + +Buffer and Memory Management +============================ + +Buffer Types +------------ + +ALSA provides several different buffer allocation functions depending on +the bus and the architecture. All these have a consistent API. The +allocation of physically-contiguous pages is done via +:c:func:`snd_malloc_xxx_pages()` function, where xxx is the bus +type. + +The allocation of pages with fallback is +:c:func:`snd_malloc_xxx_pages_fallback()`. This function tries +to allocate the specified pages but if the pages are not available, it +tries to reduce the page sizes until enough space is found. + +The release the pages, call :c:func:`snd_free_xxx_pages()` +function. + +Usually, ALSA drivers try to allocate and reserve a large contiguous +physical space at the time the module is loaded for the later use. This +is called “pre-allocation”. As already written, you can call the +following function at pcm instance construction time (in the case of PCI +bus). + +:: + + snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV, + snd_dma_pci_data(pci), size, max); + +where ``size`` is the byte size to be pre-allocated and the ``max`` is +the maximum size to be changed via the ``prealloc`` proc file. The +allocator will try to get an area as large as possible within the +given size. + +The second argument (type) and the third argument (device pointer) are +dependent on the bus. In the case of the ISA bus, pass +:c:func:`snd_dma_isa_data()` as the third argument with +``SNDRV_DMA_TYPE_DEV`` type. For the continuous buffer unrelated to the +bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type and the +``snd_dma_continuous_data(GFP_KERNEL)`` device pointer, where +``GFP_KERNEL`` is the kernel allocation flag to use. For the PCI +scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with +``snd_dma_pci_data(pci)`` (see the `Non-Contiguous Buffers`_ +section). + +Once the buffer is pre-allocated, you can use the allocator in the +``hw_params`` callback: + +:: + + snd_pcm_lib_malloc_pages(substream, size); + +Note that you have to pre-allocate to use this function. + +External Hardware Buffers +------------------------- + +Some chips have their own hardware buffers and the DMA transfer from the +host memory is not available. In such a case, you need to either 1) +copy/set the audio data directly to the external hardware buffer, or 2) +make an intermediate buffer and copy/set the data from it to the +external hardware buffer in interrupts (or in tasklets, preferably). + +The first case works fine if the external hardware buffer is large +enough. This method doesn't need any extra buffers and thus is more +effective. You need to define the ``copy`` and ``silence`` callbacks +for the data transfer. However, there is a drawback: it cannot be +mmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM. + +The second case allows for mmap on the buffer, although you have to +handle an interrupt or a tasklet to transfer the data from the +intermediate buffer to the hardware buffer. You can find an example in +the vxpocket driver. + +Another case is when the chip uses a PCI memory-map region for the +buffer instead of the host memory. In this case, mmap is available only +on certain architectures like the Intel one. In non-mmap mode, the data +cannot be transferred as in the normal way. Thus you need to define the +``copy`` and ``silence`` callbacks as well, as in the cases above. The +examples are found in ``rme32.c`` and ``rme96.c``. + +The implementation of the ``copy`` and ``silence`` callbacks depends +upon whether the hardware supports interleaved or non-interleaved +samples. The ``copy`` callback is defined like below, a bit +differently depending whether the direction is playback or capture: + +:: + + static int playback_copy(struct snd_pcm_substream *substream, int channel, + snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count); + static int capture_copy(struct snd_pcm_substream *substream, int channel, + snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count); + +In the case of interleaved samples, the second argument (``channel``) is +not used. The third argument (``pos``) points the current position +offset in frames. + +The meaning of the fourth argument is different between playback and +capture. For playback, it holds the source data pointer, and for +capture, it's the destination data pointer. + +The last argument is the number of frames to be copied. + +What you have to do in this callback is again different between playback +and capture directions. In the playback case, you copy the given amount +of data (``count``) at the specified pointer (``src``) to the specified +offset (``pos``) on the hardware buffer. When coded like memcpy-like +way, the copy would be like: + +:: + + my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src, + frames_to_bytes(runtime, count)); + +For the capture direction, you copy the given amount of data (``count``) +at the specified offset (``pos``) on the hardware buffer to the +specified pointer (``dst``). + +:: + + my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos), + frames_to_bytes(runtime, count)); + +Note that both the position and the amount of data are given in frames. + +In the case of non-interleaved samples, the implementation will be a bit +more complicated. + +You need to check the channel argument, and if it's -1, copy the whole +channels. Otherwise, you have to copy only the specified channel. Please +check ``isa/gus/gus_pcm.c`` as an example. + +The ``silence`` callback is also implemented in a similar way + +:: + + static int silence(struct snd_pcm_substream *substream, int channel, + snd_pcm_uframes_t pos, snd_pcm_uframes_t count); + +The meanings of arguments are the same as in the ``copy`` callback, +although there is no ``src/dst`` argument. In the case of interleaved +samples, the channel argument has no meaning, as well as on ``copy`` +callback. + +The role of ``silence`` callback is to set the given amount +(``count``) of silence data at the specified offset (``pos``) on the +hardware buffer. Suppose that the data format is signed (that is, the +silent-data is 0), and the implementation using a memset-like function +would be like: + +:: + + my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0, + frames_to_bytes(runtime, count)); + +In the case of non-interleaved samples, again, the implementation +becomes a bit more complicated. See, for example, ``isa/gus/gus_pcm.c``. + +Non-Contiguous Buffers +---------------------- + +If your hardware supports the page table as in emu10k1 or the buffer +descriptors as in via82xx, you can use the scatter-gather (SG) DMA. ALSA +provides an interface for handling SG-buffers. The API is provided in +````. + +For creating the SG-buffer handler, call +:c:func:`snd_pcm_lib_preallocate_pages()` or +:c:func:`snd_pcm_lib_preallocate_pages_for_all()` with +``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like other PCI +pre-allocator. You need to pass ``snd_dma_pci_data(pci)``, where pci is +the :c:type:`struct pci_dev ` pointer of the chip as +well. The ``struct snd_sg_buf`` instance is created as +``substream->dma_private``. You can cast the pointer like: + +:: + + struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private; + +Then call :c:func:`snd_pcm_lib_malloc_pages()` in the ``hw_params`` +callback as well as in the case of normal PCI buffer. The SG-buffer +handler will allocate the non-contiguous kernel pages of the given size +and map them onto the virtually contiguous memory. The virtual pointer +is addressed in runtime->dma_area. The physical address +(``runtime->dma_addr``) is set to zero, because the buffer is +physically non-contiguous. The physical address table is set up in +``sgbuf->table``. You can get the physical address at a certain offset +via :c:func:`snd_pcm_sgbuf_get_addr()`. + +When a SG-handler is used, you need to set +:c:func:`snd_pcm_sgbuf_ops_page()` as the ``page`` callback. (See +`page callback`_ section.) + +To release the data, call :c:func:`snd_pcm_lib_free_pages()` in +the ``hw_free`` callback as usual. + +Vmalloc'ed Buffers +------------------ + +It's possible to use a buffer allocated via :c:func:`vmalloc()`, for +example, for an intermediate buffer. Since the allocated pages are not +contiguous, you need to set the ``page`` callback to obtain the physical +address at every offset. + +The implementation of ``page`` callback would be like this: + +:: + + #include + + /* get the physical page pointer on the given offset */ + static struct page *mychip_page(struct snd_pcm_substream *substream, + unsigned long offset) + { + void *pageptr = substream->runtime->dma_area + offset; + return vmalloc_to_page(pageptr); + } + +Proc Interface +============== + +ALSA provides an easy interface for procfs. The proc files are very +useful for debugging. I recommend you set up proc files if you write a +driver and want to get a running status or register dumps. The API is +found in ````. + +To create a proc file, call :c:func:`snd_card_proc_new()`. + +:: + + struct snd_info_entry *entry; + int err = snd_card_proc_new(card, "my-file", &entry); + +where the second argument specifies the name of the proc file to be +created. The above example will create a file ``my-file`` under the +card directory, e.g. ``/proc/asound/card0/my-file``. + +Like other components, the proc entry created via +:c:func:`snd_card_proc_new()` will be registered and released +automatically in the card registration and release functions. + +When the creation is successful, the function stores a new instance in +the pointer given in the third argument. It is initialized as a text +proc file for read only. To use this proc file as a read-only text file +as it is, set the read callback with a private data via +:c:func:`snd_info_set_text_ops()`. + +:: + + snd_info_set_text_ops(entry, chip, my_proc_read); + +where the second argument (``chip``) is the private data to be used in +the callbacks. The third parameter specifies the read buffer size and +the fourth (``my_proc_read``) is the callback function, which is +defined like + +:: + + static void my_proc_read(struct snd_info_entry *entry, + struct snd_info_buffer *buffer); + +In the read callback, use :c:func:`snd_iprintf()` for output +strings, which works just like normal :c:func:`printf()`. For +example, + +:: + + static void my_proc_read(struct snd_info_entry *entry, + struct snd_info_buffer *buffer) + { + struct my_chip *chip = entry->private_data; + + snd_iprintf(buffer, "This is my chip!\n"); + snd_iprintf(buffer, "Port = %ld\n", chip->port); + } + +The file permissions can be changed afterwards. As default, it's set as +read only for all users. If you want to add write permission for the +user (root as default), do as follows: + +:: + + entry->mode = S_IFREG | S_IRUGO | S_IWUSR; + +and set the write buffer size and the callback + +:: + + entry->c.text.write = my_proc_write; + +For the write callback, you can use :c:func:`snd_info_get_line()` +to get a text line, and :c:func:`snd_info_get_str()` to retrieve +a string from the line. Some examples are found in +``core/oss/mixer_oss.c``, core/oss/and ``pcm_oss.c``. + +For a raw-data proc-file, set the attributes as follows: + +:: + + static struct snd_info_entry_ops my_file_io_ops = { + .read = my_file_io_read, + }; + + entry->content = SNDRV_INFO_CONTENT_DATA; + entry->private_data = chip; + entry->c.ops = &my_file_io_ops; + entry->size = 4096; + entry->mode = S_IFREG | S_IRUGO; + +For the raw data, ``size`` field must be set properly. This specifies +the maximum size of the proc file access. + +The read/write callbacks of raw mode are more direct than the text mode. +You need to use a low-level I/O functions such as +:c:func:`copy_from/to_user()` to transfer the data. + +:: + + static ssize_t my_file_io_read(struct snd_info_entry *entry, + void *file_private_data, + struct file *file, + char *buf, + size_t count, + loff_t pos) + { + if (copy_to_user(buf, local_data + pos, count)) + return -EFAULT; + return count; + } + +If the size of the info entry has been set up properly, ``count`` and +``pos`` are guaranteed to fit within 0 and the given size. You don't +have to check the range in the callbacks unless any other condition is +required. + +Power Management +================ + +If the chip is supposed to work with suspend/resume functions, you need +to add power-management code to the driver. The additional code for +power-management should be ifdef-ed with ``CONFIG_PM``. + +If the driver *fully* supports suspend/resume that is, the device can be +properly resumed to its state when suspend was called, you can set the +``SNDRV_PCM_INFO_RESUME`` flag in the pcm info field. Usually, this is +possible when the registers of the chip can be safely saved and restored +to RAM. If this is set, the trigger callback is called with +``SNDRV_PCM_TRIGGER_RESUME`` after the resume callback completes. + +Even if the driver doesn't support PM fully but partial suspend/resume +is still possible, it's still worthy to implement suspend/resume +callbacks. In such a case, applications would reset the status by +calling :c:func:`snd_pcm_prepare()` and restart the stream +appropriately. Hence, you can define suspend/resume callbacks below but +don't set ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM. + +Note that the trigger with SUSPEND can always be called when +:c:func:`snd_pcm_suspend_all()` is called, regardless of the +``SNDRV_PCM_INFO_RESUME`` flag. The ``RESUME`` flag affects only the +behavior of :c:func:`snd_pcm_resume()`. (Thus, in theory, +``SNDRV_PCM_TRIGGER_RESUME`` isn't needed to be handled in the trigger +callback when no ``SNDRV_PCM_INFO_RESUME`` flag is set. But, it's better +to keep it for compatibility reasons.) + +In the earlier version of ALSA drivers, a common power-management layer +was provided, but it has been removed. The driver needs to define the +suspend/resume hooks according to the bus the device is connected to. In +the case of PCI drivers, the callbacks look like below: + +:: + + #ifdef CONFIG_PM + static int snd_my_suspend(struct pci_dev *pci, pm_message_t state) + { + .... /* do things for suspend */ + return 0; + } + static int snd_my_resume(struct pci_dev *pci) + { + .... /* do things for suspend */ + return 0; + } + #endif + +The scheme of the real suspend job is as follows. + +1. Retrieve the card and the chip data. + +2. Call :c:func:`snd_power_change_state()` with + ``SNDRV_CTL_POWER_D3hot`` to change the power status. + +3. Call :c:func:`snd_pcm_suspend_all()` to suspend the running + PCM streams. + +4. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for + each codec. + +5. Save the register values if necessary. + +6. Stop the hardware if necessary. + +7. Disable the PCI device by calling + :c:func:`pci_disable_device()`. Then, call + :c:func:`pci_save_state()` at last. + +A typical code would be like: + +:: + + static int mychip_suspend(struct pci_dev *pci, pm_message_t state) + { + /* (1) */ + struct snd_card *card = pci_get_drvdata(pci); + struct mychip *chip = card->private_data; + /* (2) */ + snd_power_change_state(card, SNDRV_CTL_POWER_D3hot); + /* (3) */ + snd_pcm_suspend_all(chip->pcm); + /* (4) */ + snd_ac97_suspend(chip->ac97); + /* (5) */ + snd_mychip_save_registers(chip); + /* (6) */ + snd_mychip_stop_hardware(chip); + /* (7) */ + pci_disable_device(pci); + pci_save_state(pci); + return 0; + } + + +The scheme of the real resume job is as follows. + +1. Retrieve the card and the chip data. + +2. Set up PCI. First, call :c:func:`pci_restore_state()`. Then + enable the pci device again by calling + :c:func:`pci_enable_device()`. Call + :c:func:`pci_set_master()` if necessary, too. + +3. Re-initialize the chip. + +4. Restore the saved registers if necessary. + +5. Resume the mixer, e.g. calling :c:func:`snd_ac97_resume()`. + +6. Restart the hardware (if any). + +7. Call :c:func:`snd_power_change_state()` with + ``SNDRV_CTL_POWER_D0`` to notify the processes. + +A typical code would be like: + +:: + + static int mychip_resume(struct pci_dev *pci) + { + /* (1) */ + struct snd_card *card = pci_get_drvdata(pci); + struct mychip *chip = card->private_data; + /* (2) */ + pci_restore_state(pci); + pci_enable_device(pci); + pci_set_master(pci); + /* (3) */ + snd_mychip_reinit_chip(chip); + /* (4) */ + snd_mychip_restore_registers(chip); + /* (5) */ + snd_ac97_resume(chip->ac97); + /* (6) */ + snd_mychip_restart_chip(chip); + /* (7) */ + snd_power_change_state(card, SNDRV_CTL_POWER_D0); + return 0; + } + +As shown in the above, it's better to save registers after suspending +the PCM operations via :c:func:`snd_pcm_suspend_all()` or +:c:func:`snd_pcm_suspend()`. It means that the PCM streams are +already stopped when the register snapshot is taken. But, remember that +you don't have to restart the PCM stream in the resume callback. It'll +be restarted via trigger call with ``SNDRV_PCM_TRIGGER_RESUME`` when +necessary. + +OK, we have all callbacks now. Let's set them up. In the initialization +of the card, make sure that you can get the chip data from the card +instance, typically via ``private_data`` field, in case you created the +chip data individually. + +:: + + static int snd_mychip_probe(struct pci_dev *pci, + const struct pci_device_id *pci_id) + { + .... + struct snd_card *card; + struct mychip *chip; + int err; + .... + err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, + 0, &card); + .... + chip = kzalloc(sizeof(*chip), GFP_KERNEL); + .... + card->private_data = chip; + .... + } + +When you created the chip data with :c:func:`snd_card_new()`, it's +anyway accessible via ``private_data`` field. + +:: + + static int snd_mychip_probe(struct pci_dev *pci, + const struct pci_device_id *pci_id) + { + .... + struct snd_card *card; + struct mychip *chip; + int err; + .... + err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, + sizeof(struct mychip), &card); + .... + chip = card->private_data; + .... + } + +If you need a space to save the registers, allocate the buffer for it +here, too, since it would be fatal if you cannot allocate a memory in +the suspend phase. The allocated buffer should be released in the +corresponding destructor. + +And next, set suspend/resume callbacks to the pci_driver. + +:: + + static struct pci_driver driver = { + .name = KBUILD_MODNAME, + .id_table = snd_my_ids, + .probe = snd_my_probe, + .remove = snd_my_remove, + #ifdef CONFIG_PM + .suspend = snd_my_suspend, + .resume = snd_my_resume, + #endif + }; + +Module Parameters +================= + +There are standard module options for ALSA. At least, each module should +have the ``index``, ``id`` and ``enable`` options. + +If the module supports multiple cards (usually up to 8 = ``SNDRV_CARDS`` +cards), they should be arrays. The default initial values are defined +already as constants for easier programming: + +:: + + static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX; + static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR; + static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP; + +If the module supports only a single card, they could be single +variables, instead. ``enable`` option is not always necessary in this +case, but it would be better to have a dummy option for compatibility. + +The module parameters must be declared with the standard +``module_param()()``, ``module_param_array()()`` and +:c:func:`MODULE_PARM_DESC()` macros. + +The typical coding would be like below: + +:: + + #define CARD_NAME "My Chip" + + module_param_array(index, int, NULL, 0444); + MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard."); + module_param_array(id, charp, NULL, 0444); + MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard."); + module_param_array(enable, bool, NULL, 0444); + MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard."); + +Also, don't forget to define the module description, classes, license +and devices. Especially, the recent modprobe requires to define the +module license as GPL, etc., otherwise the system is shown as “tainted”. + +:: + + MODULE_DESCRIPTION("My Chip"); + MODULE_LICENSE("GPL"); + MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}"); + + +How To Put Your Driver Into ALSA Tree +===================================== + +General +------- + +So far, you've learned how to write the driver codes. And you might have +a question now: how to put my own driver into the ALSA driver tree? Here +(finally :) the standard procedure is described briefly. + +Suppose that you create a new PCI driver for the card “xyz”. The card +module name would be snd-xyz. The new driver is usually put into the +alsa-driver tree, ``alsa-driver/pci`` directory in the case of PCI +cards. Then the driver is evaluated, audited and tested by developers +and users. After a certain time, the driver will go to the alsa-kernel +tree (to the corresponding directory, such as ``alsa-kernel/pci``) and +eventually will be integrated into the Linux 2.6 tree (the directory +would be ``linux/sound/pci``). + +In the following sections, the driver code is supposed to be put into +alsa-driver tree. The two cases are covered: a driver consisting of a +single source file and one consisting of several source files. + +Driver with A Single Source File +-------------------------------- + +1. Modify alsa-driver/pci/Makefile + + Suppose you have a file xyz.c. Add the following two lines + +:: + + snd-xyz-objs := xyz.o + obj-$(CONFIG_SND_XYZ) += snd-xyz.o + +2. Create the Kconfig entry + + Add the new entry of Kconfig for your xyz driver. config SND_XYZ + tristate "Foobar XYZ" depends on SND select SND_PCM help Say Y here + to include support for Foobar XYZ soundcard. To compile this driver + as a module, choose M here: the module will be called snd-xyz. the + line, select SND_PCM, specifies that the driver xyz supports PCM. In + addition to SND_PCM, the following components are supported for + select command: SND_RAWMIDI, SND_TIMER, SND_HWDEP, + SND_MPU401_UART, SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, + SND_AC97_CODEC. Add the select command for each supported + component. + + Note that some selections imply the lowlevel selections. For example, + PCM includes TIMER, MPU401_UART includes RAWMIDI, AC97_CODEC + includes PCM, and OPL3_LIB includes HWDEP. You don't need to give + the lowlevel selections again. + + For the details of Kconfig script, refer to the kbuild documentation. + +3. Run cvscompile script to re-generate the configure script and build + the whole stuff again. + +Drivers with Several Source Files +--------------------------------- + +Suppose that the driver snd-xyz have several source files. They are +located in the new subdirectory, pci/xyz. + +1. Add a new directory (``xyz``) in ``alsa-driver/pci/Makefile`` as + below + +:: + + obj-$(CONFIG_SND) += xyz/ + + +2. Under the directory ``xyz``, create a Makefile + +:: + + ifndef SND_TOPDIR + SND_TOPDIR=../.. + endif + + include $(SND_TOPDIR)/toplevel.config + include $(SND_TOPDIR)/Makefile.conf + + snd-xyz-objs := xyz.o abc.o def.o + + obj-$(CONFIG_SND_XYZ) += snd-xyz.o + + include $(SND_TOPDIR)/Rules.make + +3. Create the Kconfig entry + + This procedure is as same as in the last section. + +4. Run cvscompile script to re-generate the configure script and build + the whole stuff again. + +Useful Functions +================ + +:c:func:`snd_printk()` and friends +--------------------------------------- + +ALSA provides a verbose version of the :c:func:`printk()` function. +If a kernel config ``CONFIG_SND_VERBOSE_PRINTK`` is set, this function +prints the given message together with the file name and the line of the +caller. The ``KERN_XXX`` prefix is processed as well as the original +:c:func:`printk()` does, so it's recommended to add this prefix, +e.g. snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\\n"); + +There are also :c:func:`printk()`'s for debugging. +:c:func:`snd_printd()` can be used for general debugging purposes. +If ``CONFIG_SND_DEBUG`` is set, this function is compiled, and works +just like :c:func:`snd_printk()`. If the ALSA is compiled without +the debugging flag, it's ignored. + +:c:func:`snd_printdd()` is compiled in only when +``CONFIG_SND_DEBUG_VERBOSE`` is set. Please note that +``CONFIG_SND_DEBUG_VERBOSE`` is not set as default even if you configure +the alsa-driver with ``--with-debug=full`` option. You need to give +explicitly ``--with-debug=detect`` option instead. + +:c:func:`snd_BUG()` +------------------------ + +It shows the ``BUG?`` message and stack trace as well as +:c:func:`snd_BUG_ON()` at the point. It's useful to show that a +fatal error happens there. + +When no debug flag is set, this macro is ignored. + +:c:func:`snd_BUG_ON()` +---------------------------- + +:c:func:`snd_BUG_ON()` macro is similar with +:c:func:`WARN_ON()` macro. For example, snd_BUG_ON(!pointer); or +it can be used as the condition, if (snd_BUG_ON(non_zero_is_bug)) +return -EINVAL; + +The macro takes an conditional expression to evaluate. When +``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows +the warning message such as ``BUG? (xxx)`` normally followed by stack +trace. In both cases it returns the evaluated value. + +Acknowledgments +=============== + +I would like to thank Phil Kerr for his help for improvement and +corrections of this document. + +Kevin Conder reformatted the original plain-text to the DocBook format. + +Giuliano Pochini corrected typos and contributed the example codes in +the hardware constraints section. -- cgit v1.2.3 From 9000d69925ac45dcb346b5ea68e71b83cd897d3d Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 13:01:05 +0100 Subject: ALSA: doc: ReSTize HD-Audio document The original HD-Audio.txt was already in asciidoc format, so it's a simple conversion in the end. A new subdirectory, Documentation/sound/hd-audio, is created and the document is moved there with another file name to match better with the recent Documentation tree structure. Signed-off-by: Takashi Iwai --- Documentation/sound/alsa/HD-Audio.txt | 853 -------------------------------- Documentation/sound/hd-audio/index.rst | 7 + Documentation/sound/hd-audio/notes.rst | 880 +++++++++++++++++++++++++++++++++ Documentation/sound/index.rst | 1 + 4 files changed, 888 insertions(+), 853 deletions(-) delete mode 100644 Documentation/sound/alsa/HD-Audio.txt create mode 100644 Documentation/sound/hd-audio/index.rst create mode 100644 Documentation/sound/hd-audio/notes.rst diff --git a/Documentation/sound/alsa/HD-Audio.txt b/Documentation/sound/alsa/HD-Audio.txt deleted file mode 100644 index d4510ebf2e8c..000000000000 --- a/Documentation/sound/alsa/HD-Audio.txt +++ /dev/null @@ -1,853 +0,0 @@ -MORE NOTES ON HD-AUDIO DRIVER -============================= - Takashi Iwai - - -GENERAL -------- - -HD-audio is the new standard on-board audio component on modern PCs -after AC97. Although Linux has been supporting HD-audio since long -time ago, there are often problems with new machines. A part of the -problem is broken BIOS, and the rest is the driver implementation. -This document explains the brief trouble-shooting and debugging -methods for the HD-audio hardware. - -The HD-audio component consists of two parts: the controller chip and -the codec chips on the HD-audio bus. Linux provides a single driver -for all controllers, snd-hda-intel. Although the driver name contains -a word of a well-known hardware vendor, it's not specific to it but for -all controller chips by other companies. Since the HD-audio -controllers are supposed to be compatible, the single snd-hda-driver -should work in most cases. But, not surprisingly, there are known -bugs and issues specific to each controller type. The snd-hda-intel -driver has a bunch of workarounds for these as described below. - -A controller may have multiple codecs. Usually you have one audio -codec and optionally one modem codec. In theory, there might be -multiple audio codecs, e.g. for analog and digital outputs, and the -driver might not work properly because of conflict of mixer elements. -This should be fixed in future if such hardware really exists. - -The snd-hda-intel driver has several different codec parsers depending -on the codec. It has a generic parser as a fallback, but this -functionality is fairly limited until now. Instead of the generic -parser, usually the codec-specific parser (coded in patch_*.c) is used -for the codec-specific implementations. The details about the -codec-specific problems are explained in the later sections. - -If you are interested in the deep debugging of HD-audio, read the -HD-audio specification at first. The specification is found on -Intel's web page, for example: - -- http://www.intel.com/standards/hdaudio/ - - -HD-AUDIO CONTROLLER -------------------- - -DMA-Position Problem -~~~~~~~~~~~~~~~~~~~~ -The most common problem of the controller is the inaccurate DMA -pointer reporting. The DMA pointer for playback and capture can be -read in two ways, either via a LPIB register or via a position-buffer -map. As default the driver tries to read from the io-mapped -position-buffer, and falls back to LPIB if the position-buffer appears -dead. However, this detection isn't perfect on some devices. In such -a case, you can change the default method via `position_fix` option. - -`position_fix=1` means to use LPIB method explicitly. -`position_fix=2` means to use the position-buffer. -`position_fix=3` means to use a combination of both methods, needed -for some VIA controllers. The capture stream position is corrected -by comparing both LPIB and position-buffer values. -`position_fix=4` is another combination available for all controllers, -and uses LPIB for the playback and the position-buffer for the capture -streams. -0 is the default value for all other -controllers, the automatic check and fallback to LPIB as described in -the above. If you get a problem of repeated sounds, this option might -help. - -In addition to that, every controller is known to be broken regarding -the wake-up timing. It wakes up a few samples before actually -processing the data on the buffer. This caused a lot of problems, for -example, with ALSA dmix or JACK. Since 2.6.27 kernel, the driver puts -an artificial delay to the wake up timing. This delay is controlled -via `bdl_pos_adj` option. - -When `bdl_pos_adj` is a negative value (as default), it's assigned to -an appropriate value depending on the controller chip. For Intel -chips, it'd be 1 while it'd be 32 for others. Usually this works. -Only in case it doesn't work and you get warning messages, you should -change this parameter to other values. - - -Codec-Probing Problem -~~~~~~~~~~~~~~~~~~~~~ -A less often but a more severe problem is the codec probing. When -BIOS reports the available codec slots wrongly, the driver gets -confused and tries to access the non-existing codec slot. This often -results in the total screw-up, and destructs the further communication -with the codec chips. The symptom appears usually as error messages -like: ------------------------------------------------------------------------- - hda_intel: azx_get_response timeout, switching to polling mode: - last cmd=0x12345678 - hda_intel: azx_get_response timeout, switching to single_cmd mode: - last cmd=0x12345678 ------------------------------------------------------------------------- - -The first line is a warning, and this is usually relatively harmless. -It means that the codec response isn't notified via an IRQ. The -driver uses explicit polling method to read the response. It gives -very slight CPU overhead, but you'd unlikely notice it. - -The second line is, however, a fatal error. If this happens, usually -it means that something is really wrong. Most likely you are -accessing a non-existing codec slot. - -Thus, if the second error message appears, try to narrow the probed -codec slots via `probe_mask` option. It's a bitmask, and each bit -corresponds to the codec slot. For example, to probe only the first -slot, pass `probe_mask=1`. For the first and the third slots, pass -`probe_mask=5` (where 5 = 1 | 4), and so on. - -Since 2.6.29 kernel, the driver has a more robust probing method, so -this error might happen rarely, though. - -On a machine with a broken BIOS, sometimes you need to force the -driver to probe the codec slots the hardware doesn't report for use. -In such a case, turn the bit 8 (0x100) of `probe_mask` option on. -Then the rest 8 bits are passed as the codec slots to probe -unconditionally. For example, `probe_mask=0x103` will force to probe -the codec slots 0 and 1 no matter what the hardware reports. - - -Interrupt Handling -~~~~~~~~~~~~~~~~~~ -HD-audio driver uses MSI as default (if available) since 2.6.33 -kernel as MSI works better on some machines, and in general, it's -better for performance. However, Nvidia controllers showed bad -regressions with MSI (especially in a combination with AMD chipset), -thus we disabled MSI for them. - -There seem also still other devices that don't work with MSI. If you -see a regression wrt the sound quality (stuttering, etc) or a lock-up -in the recent kernel, try to pass `enable_msi=0` option to disable -MSI. If it works, you can add the known bad device to the blacklist -defined in hda_intel.c. In such a case, please report and give the -patch back to the upstream developer. - - -HD-AUDIO CODEC --------------- - -Model Option -~~~~~~~~~~~~ -The most common problem regarding the HD-audio driver is the -unsupported codec features or the mismatched device configuration. -Most of codec-specific code has several preset models, either to -override the BIOS setup or to provide more comprehensive features. - -The driver checks PCI SSID and looks through the static configuration -table until any matching entry is found. If you have a new machine, -you may see a message like below: ------------------------------------------------------------------------- - hda_codec: ALC880: BIOS auto-probing. ------------------------------------------------------------------------- -Meanwhile, in the earlier versions, you would see a message like: ------------------------------------------------------------------------- - hda_codec: Unknown model for ALC880, trying auto-probe from BIOS... ------------------------------------------------------------------------- -Even if you see such a message, DON'T PANIC. Take a deep breath and -keep your towel. First of all, it's an informational message, no -warning, no error. This means that the PCI SSID of your device isn't -listed in the known preset model (white-)list. But, this doesn't mean -that the driver is broken. Many codec-drivers provide the automatic -configuration mechanism based on the BIOS setup. - -The HD-audio codec has usually "pin" widgets, and BIOS sets the default -configuration of each pin, which indicates the location, the -connection type, the jack color, etc. The HD-audio driver can guess -the right connection judging from these default configuration values. -However -- some codec-support codes, such as patch_analog.c, don't -support the automatic probing (yet as of 2.6.28). And, BIOS is often, -yes, pretty often broken. It sets up wrong values and screws up the -driver. - -The preset model (or recently called as "fix-up") is provided -basically to overcome such a situation. When the matching preset -model is found in the white-list, the driver assumes the static -configuration of that preset with the correct pin setup, etc. -Thus, if you have a newer machine with a slightly different PCI SSID -(or codec SSID) from the existing one, you may have a good chance to -re-use the same model. You can pass the `model` option to specify the -preset model instead of PCI (and codec-) SSID look-up. - -What `model` option values are available depends on the codec chip. -Check your codec chip from the codec proc file (see "Codec Proc-File" -section below). It will show the vendor/product name of your codec -chip. Then, see Documentation/sound/alsa/HD-Audio-Models.txt file, -the section of HD-audio driver. You can find a list of codecs -and `model` options belonging to each codec. For example, for Realtek -ALC262 codec chip, pass `model=ultra` for devices that are compatible -with Samsung Q1 Ultra. - -Thus, the first thing you can do for any brand-new, unsupported and -non-working HD-audio hardware is to check HD-audio codec and several -different `model` option values. If you have any luck, some of them -might suit with your device well. - -There are a few special model option values: -- when 'nofixup' is passed, the device-specific fixups in the codec - parser are skipped. -- when `generic` is passed, the codec-specific parser is skipped and - only the generic parser is used. - - -Speaker and Headphone Output -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -One of the most frequent (and obvious) bugs with HD-audio is the -silent output from either or both of a built-in speaker and a -headphone jack. In general, you should try a headphone output at -first. A speaker output often requires more additional controls like -the external amplifier bits. Thus a headphone output has a slightly -better chance. - -Before making a bug report, double-check whether the mixer is set up -correctly. The recent version of snd-hda-intel driver provides mostly -"Master" volume control as well as "Front" volume (where Front -indicates the front-channels). In addition, there can be individual -"Headphone" and "Speaker" controls. - -Ditto for the speaker output. There can be "External Amplifier" -switch on some codecs. Turn on this if present. - -Another related problem is the automatic mute of speaker output by -headphone plugging. This feature is implemented in most cases, but -not on every preset model or codec-support code. - -In anyway, try a different model option if you have such a problem. -Some other models may match better and give you more matching -functionality. If none of the available models works, send a bug -report. See the bug report section for details. - -If you are masochistic enough to debug the driver problem, note the -following: - -- The speaker (and the headphone, too) output often requires the - external amplifier. This can be set usually via EAPD verb or a - certain GPIO. If the codec pin supports EAPD, you have a better - chance via SET_EAPD_BTL verb (0x70c). On others, GPIO pin (mostly - it's either GPIO0 or GPIO1) may turn on/off EAPD. -- Some Realtek codecs require special vendor-specific coefficients to - turn on the amplifier. See patch_realtek.c. -- IDT codecs may have extra power-enable/disable controls on each - analog pin. See patch_sigmatel.c. -- Very rare but some devices don't accept the pin-detection verb until - triggered. Issuing GET_PIN_SENSE verb (0xf09) may result in the - codec-communication stall. Some examples are found in - patch_realtek.c. - - -Capture Problems -~~~~~~~~~~~~~~~~ -The capture problems are often because of missing setups of mixers. -Thus, before submitting a bug report, make sure that you set up the -mixer correctly. For example, both "Capture Volume" and "Capture -Switch" have to be set properly in addition to the right "Capture -Source" or "Input Source" selection. Some devices have "Mic Boost" -volume or switch. - -When the PCM device is opened via "default" PCM (without pulse-audio -plugin), you'll likely have "Digital Capture Volume" control as well. -This is provided for the extra gain/attenuation of the signal in -software, especially for the inputs without the hardware volume -control such as digital microphones. Unless really needed, this -should be set to exactly 50%, corresponding to 0dB -- neither extra -gain nor attenuation. When you use "hw" PCM, i.e., a raw access PCM, -this control will have no influence, though. - -It's known that some codecs / devices have fairly bad analog circuits, -and the recorded sound contains a certain DC-offset. This is no bug -of the driver. - -Most of modern laptops have no analog CD-input connection. Thus, the -recording from CD input won't work in many cases although the driver -provides it as the capture source. Use CDDA instead. - -The automatic switching of the built-in and external mic per plugging -is implemented on some codec models but not on every model. Partly -because of my laziness but mostly lack of testers. Feel free to -submit the improvement patch to the author. - - -Direct Debugging -~~~~~~~~~~~~~~~~ -If no model option gives you a better result, and you are a tough guy -to fight against evil, try debugging via hitting the raw HD-audio -codec verbs to the device. Some tools are available: hda-emu and -hda-analyzer. The detailed description is found in the sections -below. You'd need to enable hwdep for using these tools. See "Kernel -Configuration" section. - - -OTHER ISSUES ------------- - -Kernel Configuration -~~~~~~~~~~~~~~~~~~~~ -In general, I recommend you to enable the sound debug option, -`CONFIG_SND_DEBUG=y`, no matter whether you are debugging or not. -This enables snd_printd() macro and others, and you'll get additional -kernel messages at probing. - -In addition, you can enable `CONFIG_SND_DEBUG_VERBOSE=y`. But this -will give you far more messages. Thus turn this on only when you are -sure to want it. - -Don't forget to turn on the appropriate `CONFIG_SND_HDA_CODEC_*` -options. Note that each of them corresponds to the codec chip, not -the controller chip. Thus, even if lspci shows the Nvidia controller, -you may need to choose the option for other vendors. If you are -unsure, just select all yes. - -`CONFIG_SND_HDA_HWDEP` is a useful option for debugging the driver. -When this is enabled, the driver creates hardware-dependent devices -(one per each codec), and you have a raw access to the device via -these device files. For example, `hwC0D2` will be created for the -codec slot #2 of the first card (#0). For debug-tools such as -hda-verb and hda-analyzer, the hwdep device has to be enabled. -Thus, it'd be better to turn this on always. - -`CONFIG_SND_HDA_RECONFIG` is a new option, and this depends on the -hwdep option above. When enabled, you'll have some sysfs files under -the corresponding hwdep directory. See "HD-audio reconfiguration" -section below. - -`CONFIG_SND_HDA_POWER_SAVE` option enables the power-saving feature. -See "Power-saving" section below. - - -Codec Proc-File -~~~~~~~~~~~~~~~ -The codec proc-file is a treasure-chest for debugging HD-audio. -It shows most of useful information of each codec widget. - -The proc file is located in /proc/asound/card*/codec#*, one file per -each codec slot. You can know the codec vendor, product id and -names, the type of each widget, capabilities and so on. -This file, however, doesn't show the jack sensing state, so far. This -is because the jack-sensing might be depending on the trigger state. - -This file will be picked up by the debug tools, and also it can be fed -to the emulator as the primary codec information. See the debug tools -section below. - -This proc file can be also used to check whether the generic parser is -used. When the generic parser is used, the vendor/product ID name -will appear as "Realtek ID 0262", instead of "Realtek ALC262". - - -HD-Audio Reconfiguration -~~~~~~~~~~~~~~~~~~~~~~~~ -This is an experimental feature to allow you re-configure the HD-audio -codec dynamically without reloading the driver. The following sysfs -files are available under each codec-hwdep device directory (e.g. -/sys/class/sound/hwC0D0): - -vendor_id:: - Shows the 32bit codec vendor-id hex number. You can change the - vendor-id value by writing to this file. -subsystem_id:: - Shows the 32bit codec subsystem-id hex number. You can change the - subsystem-id value by writing to this file. -revision_id:: - Shows the 32bit codec revision-id hex number. You can change the - revision-id value by writing to this file. -afg:: - Shows the AFG ID. This is read-only. -mfg:: - Shows the MFG ID. This is read-only. -name:: - Shows the codec name string. Can be changed by writing to this - file. -modelname:: - Shows the currently set `model` option. Can be changed by writing - to this file. -init_verbs:: - The extra verbs to execute at initialization. You can add a verb by - writing to this file. Pass three numbers: nid, verb and parameter - (separated with a space). -hints:: - Shows / stores hint strings for codec parsers for any use. - Its format is `key = value`. For example, passing `jack_detect = no` - will disable the jack detection of the machine completely. -init_pin_configs:: - Shows the initial pin default config values set by BIOS. -driver_pin_configs:: - Shows the pin default values set by the codec parser explicitly. - This doesn't show all pin values but only the changed values by - the parser. That is, if the parser doesn't change the pin default - config values by itself, this will contain nothing. -user_pin_configs:: - Shows the pin default config values to override the BIOS setup. - Writing this (with two numbers, NID and value) appends the new - value. The given will be used instead of the initial BIOS value at - the next reconfiguration time. Note that this config will override - even the driver pin configs, too. -reconfig:: - Triggers the codec re-configuration. When any value is written to - this file, the driver re-initialize and parses the codec tree - again. All the changes done by the sysfs entries above are taken - into account. -clear:: - Resets the codec, removes the mixer elements and PCM stuff of the - specified codec, and clear all init verbs and hints. - -For example, when you want to change the pin default configuration -value of the pin widget 0x14 to 0x9993013f, and let the driver -re-configure based on that state, run like below: ------------------------------------------------------------------------- - # echo 0x14 0x9993013f > /sys/class/sound/hwC0D0/user_pin_configs - # echo 1 > /sys/class/sound/hwC0D0/reconfig ------------------------------------------------------------------------- - - -Hint Strings -~~~~~~~~~~~~ -The codec parser have several switches and adjustment knobs for -matching better with the actual codec or device behavior. Many of -them can be adjusted dynamically via "hints" strings as mentioned in -the section above. For example, by passing `jack_detect = no` string -via sysfs or a patch file, you can disable the jack detection, thus -the codec parser will skip the features like auto-mute or mic -auto-switch. As a boolean value, either `yes`, `no`, `true`, `false`, -`1` or `0` can be passed. - -The generic parser supports the following hints: - -- jack_detect (bool): specify whether the jack detection is available - at all on this machine; default true -- inv_jack_detect (bool): indicates that the jack detection logic is - inverted -- trigger_sense (bool): indicates that the jack detection needs the - explicit call of AC_VERB_SET_PIN_SENSE verb -- inv_eapd (bool): indicates that the EAPD is implemented in the - inverted logic -- pcm_format_first (bool): sets the PCM format before the stream tag - and channel ID -- sticky_stream (bool): keep the PCM format, stream tag and ID as long - as possible; default true -- spdif_status_reset (bool): reset the SPDIF status bits at each time - the SPDIF stream is set up -- pin_amp_workaround (bool): the output pin may have multiple amp - values -- single_adc_amp (bool): ADCs can have only single input amps -- auto_mute (bool): enable/disable the headphone auto-mute feature; - default true -- auto_mic (bool): enable/disable the mic auto-switch feature; default - true -- line_in_auto_switch (bool): enable/disable the line-in auto-switch - feature; default false -- need_dac_fix (bool): limits the DACs depending on the channel count -- primary_hp (bool): probe headphone jacks as the primary outputs; - default true -- multi_io (bool): try probing multi-I/O config (e.g. shared - line-in/surround, mic/clfe jacks) -- multi_cap_vol (bool): provide multiple capture volumes -- inv_dmic_split (bool): provide split internal mic volume/switch for - phase-inverted digital mics -- indep_hp (bool): provide the independent headphone PCM stream and - the corresponding mixer control, if available -- add_stereo_mix_input (bool): add the stereo mix (analog-loopback - mix) to the input mux if available -- add_jack_modes (bool): add "xxx Jack Mode" enum controls to each - I/O jack for allowing to change the headphone amp and mic bias VREF - capabilities -- power_save_node (bool): advanced power management for each widget, - controlling the power sate (D0/D3) of each widget node depending on - the actual pin and stream states -- power_down_unused (bool): power down the unused widgets, a subset of - power_save_node, and will be dropped in future -- add_hp_mic (bool): add the headphone to capture source if possible -- hp_mic_detect (bool): enable/disable the hp/mic shared input for a - single built-in mic case; default true -- mixer_nid (int): specifies the widget NID of the analog-loopback - mixer - - -Early Patching -~~~~~~~~~~~~~~ -When CONFIG_SND_HDA_PATCH_LOADER=y is set, you can pass a "patch" as a -firmware file for modifying the HD-audio setup before initializing the -codec. This can work basically like the reconfiguration via sysfs in -the above, but it does it before the first codec configuration. - -A patch file is a plain text file which looks like below: - ------------------------------------------------------------------------- - [codec] - 0x12345678 0xabcd1234 2 - - [model] - auto - - [pincfg] - 0x12 0x411111f0 - - [verb] - 0x20 0x500 0x03 - 0x20 0x400 0xff - - [hint] - jack_detect = no ------------------------------------------------------------------------- - -The file needs to have a line `[codec]`. The next line should contain -three numbers indicating the codec vendor-id (0x12345678 in the -example), the codec subsystem-id (0xabcd1234) and the address (2) of -the codec. The rest patch entries are applied to this specified codec -until another codec entry is given. Passing 0 or a negative number to -the first or the second value will make the check of the corresponding -field be skipped. It'll be useful for really broken devices that don't -initialize SSID properly. - -The `[model]` line allows to change the model name of the each codec. -In the example above, it will be changed to model=auto. -Note that this overrides the module option. - -After the `[pincfg]` line, the contents are parsed as the initial -default pin-configurations just like `user_pin_configs` sysfs above. -The values can be shown in user_pin_configs sysfs file, too. - -Similarly, the lines after `[verb]` are parsed as `init_verbs` -sysfs entries, and the lines after `[hint]` are parsed as `hints` -sysfs entries, respectively. - -Another example to override the codec vendor id from 0x12345678 to -0xdeadbeef is like below: ------------------------------------------------------------------------- - [codec] - 0x12345678 0xabcd1234 2 - - [vendor_id] - 0xdeadbeef ------------------------------------------------------------------------- - -In the similar way, you can override the codec subsystem_id via -`[subsystem_id]`, the revision id via `[revision_id]` line. -Also, the codec chip name can be rewritten via `[chip_name]` line. ------------------------------------------------------------------------- - [codec] - 0x12345678 0xabcd1234 2 - - [subsystem_id] - 0xffff1111 - - [revision_id] - 0x10 - - [chip_name] - My-own NEWS-0002 ------------------------------------------------------------------------- - -The hd-audio driver reads the file via request_firmware(). Thus, -a patch file has to be located on the appropriate firmware path, -typically, /lib/firmware. For example, when you pass the option -`patch=hda-init.fw`, the file /lib/firmware/hda-init.fw must be -present. - -The patch module option is specific to each card instance, and you -need to give one file name for each instance, separated by commas. -For example, if you have two cards, one for an on-board analog and one -for an HDMI video board, you may pass patch option like below: ------------------------------------------------------------------------- - options snd-hda-intel patch=on-board-patch,hdmi-patch ------------------------------------------------------------------------- - - -Power-Saving -~~~~~~~~~~~~ -The power-saving is a kind of auto-suspend of the device. When the -device is inactive for a certain time, the device is automatically -turned off to save the power. The time to go down is specified via -`power_save` module option, and this option can be changed dynamically -via sysfs. - -The power-saving won't work when the analog loopback is enabled on -some codecs. Make sure that you mute all unneeded signal routes when -you want the power-saving. - -The power-saving feature might cause audible click noises at each -power-down/up depending on the device. Some of them might be -solvable, but some are hard, I'm afraid. Some distros such as -openSUSE enables the power-saving feature automatically when the power -cable is unplugged. Thus, if you hear noises, suspect first the -power-saving. See /sys/module/snd_hda_intel/parameters/power_save to -check the current value. If it's non-zero, the feature is turned on. - -The recent kernel supports the runtime PM for the HD-audio controller -chip, too. It means that the HD-audio controller is also powered up / -down dynamically. The feature is enabled only for certain controller -chips like Intel LynxPoint. You can enable/disable this feature -forcibly by setting `power_save_controller` option, which is also -available at /sys/module/snd_hda_intel/parameters directory. - - -Tracepoints -~~~~~~~~~~~ -The hd-audio driver gives a few basic tracepoints. -`hda:hda_send_cmd` traces each CORB write while `hda:hda_get_response` -traces the response from RIRB (only when read from the codec driver). -`hda:hda_bus_reset` traces the bus-reset due to fatal error, etc, -`hda:hda_unsol_event` traces the unsolicited events, and -`hda:hda_power_down` and `hda:hda_power_up` trace the power down/up -via power-saving behavior. - -Enabling all tracepoints can be done like ------------------------------------------------------------------------- - # echo 1 > /sys/kernel/debug/tracing/events/hda/enable ------------------------------------------------------------------------- -then after some commands, you can traces from -/sys/kernel/debug/tracing/trace file. For example, when you want to -trace what codec command is sent, enable the tracepoint like: ------------------------------------------------------------------------- - # cat /sys/kernel/debug/tracing/trace - # tracer: nop - # - # TASK-PID CPU# TIMESTAMP FUNCTION - # | | | | | - <...>-7807 [002] 105147.774889: hda_send_cmd: [0:0] val=e3a019 - <...>-7807 [002] 105147.774893: hda_send_cmd: [0:0] val=e39019 - <...>-7807 [002] 105147.999542: hda_send_cmd: [0:0] val=e3a01a - <...>-7807 [002] 105147.999543: hda_send_cmd: [0:0] val=e3901a - <...>-26764 [001] 349222.837143: hda_send_cmd: [0:0] val=e3a019 - <...>-26764 [001] 349222.837148: hda_send_cmd: [0:0] val=e39019 - <...>-26764 [001] 349223.058539: hda_send_cmd: [0:0] val=e3a01a - <...>-26764 [001] 349223.058541: hda_send_cmd: [0:0] val=e3901a ------------------------------------------------------------------------- -Here `[0:0]` indicates the card number and the codec address, and -`val` shows the value sent to the codec, respectively. The value is -a packed value, and you can decode it via hda-decode-verb program -included in hda-emu package below. For example, the value e3a019 is -to set the left output-amp value to 25. ------------------------------------------------------------------------- - % hda-decode-verb 0xe3a019 - raw value = 0x00e3a019 - cid = 0, nid = 0x0e, verb = 0x3a0, parm = 0x19 - raw value: verb = 0x3a0, parm = 0x19 - verbname = set_amp_gain_mute - amp raw val = 0xa019 - output, left, idx=0, mute=0, val=25 ------------------------------------------------------------------------- - - -Development Tree -~~~~~~~~~~~~~~~~ -The latest development codes for HD-audio are found on sound git tree: - -- git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound.git - -The master branch or for-next branches can be used as the main -development branches in general while the development for the current -and next kernels are found in for-linus and for-next branches, -respectively. - - -Sending a Bug Report -~~~~~~~~~~~~~~~~~~~~ -If any model or module options don't work for your device, it's time -to send a bug report to the developers. Give the following in your -bug report: - -- Hardware vendor, product and model names -- Kernel version (and ALSA-driver version if you built externally) -- `alsa-info.sh` output; run with `--no-upload` option. See the - section below about alsa-info - -If it's a regression, at best, send alsa-info outputs of both working -and non-working kernels. This is really helpful because we can -compare the codec registers directly. - -Send a bug report either the followings: - -kernel-bugzilla:: - https://bugzilla.kernel.org/ -alsa-devel ML:: - alsa-devel@alsa-project.org - - -DEBUG TOOLS ------------ - -This section describes some tools available for debugging HD-audio -problems. - -alsa-info -~~~~~~~~~ -The script `alsa-info.sh` is a very useful tool to gather the audio -device information. It's included in alsa-utils package. The latest -version can be found on git repository: - -- git://git.alsa-project.org/alsa-utils.git - -The script can be fetched directly from the following URL, too: - -- http://www.alsa-project.org/alsa-info.sh - -Run this script as root, and it will gather the important information -such as the module lists, module parameters, proc file contents -including the codec proc files, mixer outputs and the control -elements. As default, it will store the information onto a web server -on alsa-project.org. But, if you send a bug report, it'd be better to -run with `--no-upload` option, and attach the generated file. - -There are some other useful options. See `--help` option output for -details. - -When a probe error occurs or when the driver obviously assigns a -mismatched model, it'd be helpful to load the driver with -`probe_only=1` option (at best after the cold reboot) and run -alsa-info at this state. With this option, the driver won't configure -the mixer and PCM but just tries to probe the codec slot. After -probing, the proc file is available, so you can get the raw codec -information before modified by the driver. Of course, the driver -isn't usable with `probe_only=1`. But you can continue the -configuration via hwdep sysfs file if hda-reconfig option is enabled. -Using `probe_only` mask 2 skips the reset of HDA codecs (use -`probe_only=3` as module option). The hwdep interface can be used -to determine the BIOS codec initialization. - - -hda-verb -~~~~~~~~ -hda-verb is a tiny program that allows you to access the HD-audio -codec directly. You can execute a raw HD-audio codec verb with this. -This program accesses the hwdep device, thus you need to enable the -kernel config `CONFIG_SND_HDA_HWDEP=y` beforehand. - -The hda-verb program takes four arguments: the hwdep device file, the -widget NID, the verb and the parameter. When you access to the codec -on the slot 2 of the card 0, pass /dev/snd/hwC0D2 to the first -argument, typically. (However, the real path name depends on the -system.) - -The second parameter is the widget number-id to access. The third -parameter can be either a hex/digit number or a string corresponding -to a verb. Similarly, the last parameter is the value to write, or -can be a string for the parameter type. - ------------------------------------------------------------------------- - % hda-verb /dev/snd/hwC0D0 0x12 0x701 2 - nid = 0x12, verb = 0x701, param = 0x2 - value = 0x0 - - % hda-verb /dev/snd/hwC0D0 0x0 PARAMETERS VENDOR_ID - nid = 0x0, verb = 0xf00, param = 0x0 - value = 0x10ec0262 - - % hda-verb /dev/snd/hwC0D0 2 set_a 0xb080 - nid = 0x2, verb = 0x300, param = 0xb080 - value = 0x0 ------------------------------------------------------------------------- - -Although you can issue any verbs with this program, the driver state -won't be always updated. For example, the volume values are usually -cached in the driver, and thus changing the widget amp value directly -via hda-verb won't change the mixer value. - -The hda-verb program is included now in alsa-tools: - -- git://git.alsa-project.org/alsa-tools.git - -Also, the old stand-alone package is found in the ftp directory: - -- ftp://ftp.suse.com/pub/people/tiwai/misc/ - -Also a git repository is available: - -- git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/hda-verb.git - -See README file in the tarball for more details about hda-verb -program. - - -hda-analyzer -~~~~~~~~~~~~ -hda-analyzer provides a graphical interface to access the raw HD-audio -control, based on pyGTK2 binding. It's a more powerful version of -hda-verb. The program gives you an easy-to-use GUI stuff for showing -the widget information and adjusting the amp values, as well as the -proc-compatible output. - -The hda-analyzer: - -- http://git.alsa-project.org/?p=alsa.git;a=tree;f=hda-analyzer - -is a part of alsa.git repository in alsa-project.org: - -- git://git.alsa-project.org/alsa.git - -Codecgraph -~~~~~~~~~~ -Codecgraph is a utility program to generate a graph and visualizes the -codec-node connection of a codec chip. It's especially useful when -you analyze or debug a codec without a proper datasheet. The program -parses the given codec proc file and converts to SVG via graphiz -program. - -The tarball and GIT trees are found in the web page at: - -- http://helllabs.org/codecgraph/ - - -hda-emu -~~~~~~~ -hda-emu is an HD-audio emulator. The main purpose of this program is -to debug an HD-audio codec without the real hardware. Thus, it -doesn't emulate the behavior with the real audio I/O, but it just -dumps the codec register changes and the ALSA-driver internal changes -at probing and operating the HD-audio driver. - -The program requires a codec proc-file to simulate. Get a proc file -for the target codec beforehand, or pick up an example codec from the -codec proc collections in the tarball. Then, run the program with the -proc file, and the hda-emu program will start parsing the codec file -and simulates the HD-audio driver: - ------------------------------------------------------------------------- - % hda-emu codecs/stac9200-dell-d820-laptop - # Parsing.. - hda_codec: Unknown model for STAC9200, using BIOS defaults - hda_codec: pin nid 08 bios pin config 40c003fa - .... ------------------------------------------------------------------------- - -The program gives you only a very dumb command-line interface. You -can get a proc-file dump at the current state, get a list of control -(mixer) elements, set/get the control element value, simulate the PCM -operation, the jack plugging simulation, etc. - -The program is found in the git repository below: - -- git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/hda-emu.git - -See README file in the repository for more details about hda-emu -program. - - -hda-jack-retask -~~~~~~~~~~~~~~~ -hda-jack-retask is a user-friendly GUI program to manipulate the -HD-audio pin control for jack retasking. If you have a problem about -the jack assignment, try this program and check whether you can get -useful results. Once when you figure out the proper pin assignment, -it can be fixed either in the driver code statically or via passing a -firmware patch file (see "Early Patching" section). - -The program is included in alsa-tools now: - -- git://git.alsa-project.org/alsa-tools.git - diff --git a/Documentation/sound/hd-audio/index.rst b/Documentation/sound/hd-audio/index.rst new file mode 100644 index 000000000000..f2dc29019f12 --- /dev/null +++ b/Documentation/sound/hd-audio/index.rst @@ -0,0 +1,7 @@ +HD-Audio +======== + +.. toctree:: + :maxdepth: 2 + + notes diff --git a/Documentation/sound/hd-audio/notes.rst b/Documentation/sound/hd-audio/notes.rst new file mode 100644 index 000000000000..168d0cfab1ce --- /dev/null +++ b/Documentation/sound/hd-audio/notes.rst @@ -0,0 +1,880 @@ +============================= +More Notes on HD-Audio Driver +============================= + +Takashi Iwai + + +General +======= + +HD-audio is the new standard on-board audio component on modern PCs +after AC97. Although Linux has been supporting HD-audio since long +time ago, there are often problems with new machines. A part of the +problem is broken BIOS, and the rest is the driver implementation. +This document explains the brief trouble-shooting and debugging +methods for the HD-audio hardware. + +The HD-audio component consists of two parts: the controller chip and +the codec chips on the HD-audio bus. Linux provides a single driver +for all controllers, snd-hda-intel. Although the driver name contains +a word of a well-known hardware vendor, it's not specific to it but for +all controller chips by other companies. Since the HD-audio +controllers are supposed to be compatible, the single snd-hda-driver +should work in most cases. But, not surprisingly, there are known +bugs and issues specific to each controller type. The snd-hda-intel +driver has a bunch of workarounds for these as described below. + +A controller may have multiple codecs. Usually you have one audio +codec and optionally one modem codec. In theory, there might be +multiple audio codecs, e.g. for analog and digital outputs, and the +driver might not work properly because of conflict of mixer elements. +This should be fixed in future if such hardware really exists. + +The snd-hda-intel driver has several different codec parsers depending +on the codec. It has a generic parser as a fallback, but this +functionality is fairly limited until now. Instead of the generic +parser, usually the codec-specific parser (coded in patch_*.c) is used +for the codec-specific implementations. The details about the +codec-specific problems are explained in the later sections. + +If you are interested in the deep debugging of HD-audio, read the +HD-audio specification at first. The specification is found on +Intel's web page, for example: + +* http://www.intel.com/standards/hdaudio/ + + +HD-Audio Controller +=================== + +DMA-Position Problem +-------------------- +The most common problem of the controller is the inaccurate DMA +pointer reporting. The DMA pointer for playback and capture can be +read in two ways, either via a LPIB register or via a position-buffer +map. As default the driver tries to read from the io-mapped +position-buffer, and falls back to LPIB if the position-buffer appears +dead. However, this detection isn't perfect on some devices. In such +a case, you can change the default method via ``position_fix`` option. + +``position_fix=1`` means to use LPIB method explicitly. +``position_fix=2`` means to use the position-buffer. +``position_fix=3`` means to use a combination of both methods, needed +for some VIA controllers. The capture stream position is corrected +by comparing both LPIB and position-buffer values. +``position_fix=4`` is another combination available for all controllers, +and uses LPIB for the playback and the position-buffer for the capture +streams. +0 is the default value for all other +controllers, the automatic check and fallback to LPIB as described in +the above. If you get a problem of repeated sounds, this option might +help. + +In addition to that, every controller is known to be broken regarding +the wake-up timing. It wakes up a few samples before actually +processing the data on the buffer. This caused a lot of problems, for +example, with ALSA dmix or JACK. Since 2.6.27 kernel, the driver puts +an artificial delay to the wake up timing. This delay is controlled +via ``bdl_pos_adj`` option. + +When ``bdl_pos_adj`` is a negative value (as default), it's assigned to +an appropriate value depending on the controller chip. For Intel +chips, it'd be 1 while it'd be 32 for others. Usually this works. +Only in case it doesn't work and you get warning messages, you should +change this parameter to other values. + + +Codec-Probing Problem +--------------------- +A less often but a more severe problem is the codec probing. When +BIOS reports the available codec slots wrongly, the driver gets +confused and tries to access the non-existing codec slot. This often +results in the total screw-up, and destructs the further communication +with the codec chips. The symptom appears usually as error messages +like: +:: + + hda_intel: azx_get_response timeout, switching to polling mode: + last cmd=0x12345678 + hda_intel: azx_get_response timeout, switching to single_cmd mode: + last cmd=0x12345678 + +The first line is a warning, and this is usually relatively harmless. +It means that the codec response isn't notified via an IRQ. The +driver uses explicit polling method to read the response. It gives +very slight CPU overhead, but you'd unlikely notice it. + +The second line is, however, a fatal error. If this happens, usually +it means that something is really wrong. Most likely you are +accessing a non-existing codec slot. + +Thus, if the second error message appears, try to narrow the probed +codec slots via ``probe_mask`` option. It's a bitmask, and each bit +corresponds to the codec slot. For example, to probe only the first +slot, pass ``probe_mask=1``. For the first and the third slots, pass +``probe_mask=5`` (where 5 = 1 | 4), and so on. + +Since 2.6.29 kernel, the driver has a more robust probing method, so +this error might happen rarely, though. + +On a machine with a broken BIOS, sometimes you need to force the +driver to probe the codec slots the hardware doesn't report for use. +In such a case, turn the bit 8 (0x100) of ``probe_mask`` option on. +Then the rest 8 bits are passed as the codec slots to probe +unconditionally. For example, ``probe_mask=0x103`` will force to probe +the codec slots 0 and 1 no matter what the hardware reports. + + +Interrupt Handling +------------------ +HD-audio driver uses MSI as default (if available) since 2.6.33 +kernel as MSI works better on some machines, and in general, it's +better for performance. However, Nvidia controllers showed bad +regressions with MSI (especially in a combination with AMD chipset), +thus we disabled MSI for them. + +There seem also still other devices that don't work with MSI. If you +see a regression wrt the sound quality (stuttering, etc) or a lock-up +in the recent kernel, try to pass ``enable_msi=0`` option to disable +MSI. If it works, you can add the known bad device to the blacklist +defined in hda_intel.c. In such a case, please report and give the +patch back to the upstream developer. + + +HD-Audio Codec +============== + +Model Option +------------ +The most common problem regarding the HD-audio driver is the +unsupported codec features or the mismatched device configuration. +Most of codec-specific code has several preset models, either to +override the BIOS setup or to provide more comprehensive features. + +The driver checks PCI SSID and looks through the static configuration +table until any matching entry is found. If you have a new machine, +you may see a message like below: +:: + + hda_codec: ALC880: BIOS auto-probing. + +Meanwhile, in the earlier versions, you would see a message like: +:: + + hda_codec: Unknown model for ALC880, trying auto-probe from BIOS... + +Even if you see such a message, DON'T PANIC. Take a deep breath and +keep your towel. First of all, it's an informational message, no +warning, no error. This means that the PCI SSID of your device isn't +listed in the known preset model (white-)list. But, this doesn't mean +that the driver is broken. Many codec-drivers provide the automatic +configuration mechanism based on the BIOS setup. + +The HD-audio codec has usually "pin" widgets, and BIOS sets the default +configuration of each pin, which indicates the location, the +connection type, the jack color, etc. The HD-audio driver can guess +the right connection judging from these default configuration values. +However -- some codec-support codes, such as patch_analog.c, don't +support the automatic probing (yet as of 2.6.28). And, BIOS is often, +yes, pretty often broken. It sets up wrong values and screws up the +driver. + +The preset model (or recently called as "fix-up") is provided +basically to overcome such a situation. When the matching preset +model is found in the white-list, the driver assumes the static +configuration of that preset with the correct pin setup, etc. +Thus, if you have a newer machine with a slightly different PCI SSID +(or codec SSID) from the existing one, you may have a good chance to +re-use the same model. You can pass the ``model`` option to specify the +preset model instead of PCI (and codec-) SSID look-up. + +What ``model`` option values are available depends on the codec chip. +Check your codec chip from the codec proc file (see "Codec Proc-File" +section below). It will show the vendor/product name of your codec +chip. Then, see Documentation/sound/HD-Audio-Models.rst file, +the section of HD-audio driver. You can find a list of codecs +and ``model`` options belonging to each codec. For example, for Realtek +ALC262 codec chip, pass ``model=ultra`` for devices that are compatible +with Samsung Q1 Ultra. + +Thus, the first thing you can do for any brand-new, unsupported and +non-working HD-audio hardware is to check HD-audio codec and several +different ``model`` option values. If you have any luck, some of them +might suit with your device well. + +There are a few special model option values: + +* when 'nofixup' is passed, the device-specific fixups in the codec + parser are skipped. +* when ``generic`` is passed, the codec-specific parser is skipped and + only the generic parser is used. + + +Speaker and Headphone Output +---------------------------- +One of the most frequent (and obvious) bugs with HD-audio is the +silent output from either or both of a built-in speaker and a +headphone jack. In general, you should try a headphone output at +first. A speaker output often requires more additional controls like +the external amplifier bits. Thus a headphone output has a slightly +better chance. + +Before making a bug report, double-check whether the mixer is set up +correctly. The recent version of snd-hda-intel driver provides mostly +"Master" volume control as well as "Front" volume (where Front +indicates the front-channels). In addition, there can be individual +"Headphone" and "Speaker" controls. + +Ditto for the speaker output. There can be "External Amplifier" +switch on some codecs. Turn on this if present. + +Another related problem is the automatic mute of speaker output by +headphone plugging. This feature is implemented in most cases, but +not on every preset model or codec-support code. + +In anyway, try a different model option if you have such a problem. +Some other models may match better and give you more matching +functionality. If none of the available models works, send a bug +report. See the bug report section for details. + +If you are masochistic enough to debug the driver problem, note the +following: + +* The speaker (and the headphone, too) output often requires the + external amplifier. This can be set usually via EAPD verb or a + certain GPIO. If the codec pin supports EAPD, you have a better + chance via SET_EAPD_BTL verb (0x70c). On others, GPIO pin (mostly + it's either GPIO0 or GPIO1) may turn on/off EAPD. +* Some Realtek codecs require special vendor-specific coefficients to + turn on the amplifier. See patch_realtek.c. +* IDT codecs may have extra power-enable/disable controls on each + analog pin. See patch_sigmatel.c. +* Very rare but some devices don't accept the pin-detection verb until + triggered. Issuing GET_PIN_SENSE verb (0xf09) may result in the + codec-communication stall. Some examples are found in + patch_realtek.c. + + +Capture Problems +---------------- +The capture problems are often because of missing setups of mixers. +Thus, before submitting a bug report, make sure that you set up the +mixer correctly. For example, both "Capture Volume" and "Capture +Switch" have to be set properly in addition to the right "Capture +Source" or "Input Source" selection. Some devices have "Mic Boost" +volume or switch. + +When the PCM device is opened via "default" PCM (without pulse-audio +plugin), you'll likely have "Digital Capture Volume" control as well. +This is provided for the extra gain/attenuation of the signal in +software, especially for the inputs without the hardware volume +control such as digital microphones. Unless really needed, this +should be set to exactly 50%, corresponding to 0dB -- neither extra +gain nor attenuation. When you use "hw" PCM, i.e., a raw access PCM, +this control will have no influence, though. + +It's known that some codecs / devices have fairly bad analog circuits, +and the recorded sound contains a certain DC-offset. This is no bug +of the driver. + +Most of modern laptops have no analog CD-input connection. Thus, the +recording from CD input won't work in many cases although the driver +provides it as the capture source. Use CDDA instead. + +The automatic switching of the built-in and external mic per plugging +is implemented on some codec models but not on every model. Partly +because of my laziness but mostly lack of testers. Feel free to +submit the improvement patch to the author. + + +Direct Debugging +---------------- +If no model option gives you a better result, and you are a tough guy +to fight against evil, try debugging via hitting the raw HD-audio +codec verbs to the device. Some tools are available: hda-emu and +hda-analyzer. The detailed description is found in the sections +below. You'd need to enable hwdep for using these tools. See "Kernel +Configuration" section. + + +Other Issues +============ + +Kernel Configuration +-------------------- +In general, I recommend you to enable the sound debug option, +``CONFIG_SND_DEBUG=y``, no matter whether you are debugging or not. +This enables snd_printd() macro and others, and you'll get additional +kernel messages at probing. + +In addition, you can enable ``CONFIG_SND_DEBUG_VERBOSE=y``. But this +will give you far more messages. Thus turn this on only when you are +sure to want it. + +Don't forget to turn on the appropriate ``CONFIG_SND_HDA_CODEC_*`` +options. Note that each of them corresponds to the codec chip, not +the controller chip. Thus, even if lspci shows the Nvidia controller, +you may need to choose the option for other vendors. If you are +unsure, just select all yes. + +``CONFIG_SND_HDA_HWDEP`` is a useful option for debugging the driver. +When this is enabled, the driver creates hardware-dependent devices +(one per each codec), and you have a raw access to the device via +these device files. For example, ``hwC0D2`` will be created for the +codec slot #2 of the first card (#0). For debug-tools such as +hda-verb and hda-analyzer, the hwdep device has to be enabled. +Thus, it'd be better to turn this on always. + +``CONFIG_SND_HDA_RECONFIG`` is a new option, and this depends on the +hwdep option above. When enabled, you'll have some sysfs files under +the corresponding hwdep directory. See "HD-audio reconfiguration" +section below. + +``CONFIG_SND_HDA_POWER_SAVE`` option enables the power-saving feature. +See "Power-saving" section below. + + +Codec Proc-File +--------------- +The codec proc-file is a treasure-chest for debugging HD-audio. +It shows most of useful information of each codec widget. + +The proc file is located in /proc/asound/card*/codec#*, one file per +each codec slot. You can know the codec vendor, product id and +names, the type of each widget, capabilities and so on. +This file, however, doesn't show the jack sensing state, so far. This +is because the jack-sensing might be depending on the trigger state. + +This file will be picked up by the debug tools, and also it can be fed +to the emulator as the primary codec information. See the debug tools +section below. + +This proc file can be also used to check whether the generic parser is +used. When the generic parser is used, the vendor/product ID name +will appear as "Realtek ID 0262", instead of "Realtek ALC262". + + +HD-Audio Reconfiguration +------------------------ +This is an experimental feature to allow you re-configure the HD-audio +codec dynamically without reloading the driver. The following sysfs +files are available under each codec-hwdep device directory (e.g. +/sys/class/sound/hwC0D0): + +vendor_id + Shows the 32bit codec vendor-id hex number. You can change the + vendor-id value by writing to this file. +subsystem_id + Shows the 32bit codec subsystem-id hex number. You can change the + subsystem-id value by writing to this file. +revision_id + Shows the 32bit codec revision-id hex number. You can change the + revision-id value by writing to this file. +afg + Shows the AFG ID. This is read-only. +mfg + Shows the MFG ID. This is read-only. +name + Shows the codec name string. Can be changed by writing to this + file. +modelname + Shows the currently set ``model`` option. Can be changed by writing + to this file. +init_verbs + The extra verbs to execute at initialization. You can add a verb by + writing to this file. Pass three numbers: nid, verb and parameter + (separated with a space). +hints + Shows / stores hint strings for codec parsers for any use. + Its format is ``key = value``. For example, passing ``jack_detect = no`` + will disable the jack detection of the machine completely. +init_pin_configs + Shows the initial pin default config values set by BIOS. +driver_pin_configs + Shows the pin default values set by the codec parser explicitly. + This doesn't show all pin values but only the changed values by + the parser. That is, if the parser doesn't change the pin default + config values by itself, this will contain nothing. +user_pin_configs + Shows the pin default config values to override the BIOS setup. + Writing this (with two numbers, NID and value) appends the new + value. The given will be used instead of the initial BIOS value at + the next reconfiguration time. Note that this config will override + even the driver pin configs, too. +reconfig + Triggers the codec re-configuration. When any value is written to + this file, the driver re-initialize and parses the codec tree + again. All the changes done by the sysfs entries above are taken + into account. +clear + Resets the codec, removes the mixer elements and PCM stuff of the + specified codec, and clear all init verbs and hints. + +For example, when you want to change the pin default configuration +value of the pin widget 0x14 to 0x9993013f, and let the driver +re-configure based on that state, run like below: +:: + + # echo 0x14 0x9993013f > /sys/class/sound/hwC0D0/user_pin_configs + # echo 1 > /sys/class/sound/hwC0D0/reconfig + + +Hint Strings +------------ +The codec parser have several switches and adjustment knobs for +matching better with the actual codec or device behavior. Many of +them can be adjusted dynamically via "hints" strings as mentioned in +the section above. For example, by passing ``jack_detect = no`` string +via sysfs or a patch file, you can disable the jack detection, thus +the codec parser will skip the features like auto-mute or mic +auto-switch. As a boolean value, either ``yes``, ``no``, ``true``, ``false``, +``1`` or ``0`` can be passed. + +The generic parser supports the following hints: + +jack_detect (bool) + specify whether the jack detection is available at all on this + machine; default true +inv_jack_detect (bool) + indicates that the jack detection logic is inverted +trigger_sense (bool) + indicates that the jack detection needs the explicit call of + AC_VERB_SET_PIN_SENSE verb +inv_eapd (bool) + indicates that the EAPD is implemented in the inverted logic +pcm_format_first (bool) + sets the PCM format before the stream tag and channel ID +sticky_stream (bool) + keep the PCM format, stream tag and ID as long as possible; + default true +spdif_status_reset (bool) + reset the SPDIF status bits at each time the SPDIF stream is set + up +pin_amp_workaround (bool) + the output pin may have multiple amp values +single_adc_amp (bool) + ADCs can have only single input amps +auto_mute (bool) + enable/disable the headphone auto-mute feature; default true +auto_mic (bool) + enable/disable the mic auto-switch feature; default true +line_in_auto_switch (bool) + enable/disable the line-in auto-switch feature; default false +need_dac_fix (bool) + limits the DACs depending on the channel count +primary_hp (bool) + probe headphone jacks as the primary outputs; default true +multi_io (bool) + try probing multi-I/O config (e.g. shared line-in/surround, + mic/clfe jacks) +multi_cap_vol (bool) + provide multiple capture volumes +inv_dmic_split (bool) + provide split internal mic volume/switch for phase-inverted + digital mics +indep_hp (bool) + provide the independent headphone PCM stream and the corresponding + mixer control, if available +add_stereo_mix_input (bool) + add the stereo mix (analog-loopback mix) to the input mux if + available +add_jack_modes (bool) + add "xxx Jack Mode" enum controls to each I/O jack for allowing to + change the headphone amp and mic bias VREF capabilities +power_save_node (bool) + advanced power management for each widget, controlling the power + sate (D0/D3) of each widget node depending on the actual pin and + stream states +power_down_unused (bool) + power down the unused widgets, a subset of power_save_node, and + will be dropped in future +add_hp_mic (bool) + add the headphone to capture source if possible +hp_mic_detect (bool) + enable/disable the hp/mic shared input for a single built-in mic + case; default true +mixer_nid (int) + specifies the widget NID of the analog-loopback mixer + + +Early Patching +-------------- +When ``CONFIG_SND_HDA_PATCH_LOADER=y`` is set, you can pass a "patch" +as a firmware file for modifying the HD-audio setup before +initializing the codec. This can work basically like the +reconfiguration via sysfs in the above, but it does it before the +first codec configuration. + +A patch file is a plain text file which looks like below: + +:: + + [codec] + 0x12345678 0xabcd1234 2 + + [model] + auto + + [pincfg] + 0x12 0x411111f0 + + [verb] + 0x20 0x500 0x03 + 0x20 0x400 0xff + + [hint] + jack_detect = no + + +The file needs to have a line ``[codec]``. The next line should contain +three numbers indicating the codec vendor-id (0x12345678 in the +example), the codec subsystem-id (0xabcd1234) and the address (2) of +the codec. The rest patch entries are applied to this specified codec +until another codec entry is given. Passing 0 or a negative number to +the first or the second value will make the check of the corresponding +field be skipped. It'll be useful for really broken devices that don't +initialize SSID properly. + +The ``[model]`` line allows to change the model name of the each codec. +In the example above, it will be changed to model=auto. +Note that this overrides the module option. + +After the ``[pincfg]`` line, the contents are parsed as the initial +default pin-configurations just like ``user_pin_configs`` sysfs above. +The values can be shown in user_pin_configs sysfs file, too. + +Similarly, the lines after ``[verb]`` are parsed as ``init_verbs`` +sysfs entries, and the lines after ``[hint]`` are parsed as ``hints`` +sysfs entries, respectively. + +Another example to override the codec vendor id from 0x12345678 to +0xdeadbeef is like below: +:: + + [codec] + 0x12345678 0xabcd1234 2 + + [vendor_id] + 0xdeadbeef + + +In the similar way, you can override the codec subsystem_id via +``[subsystem_id]``, the revision id via ``[revision_id]`` line. +Also, the codec chip name can be rewritten via ``[chip_name]`` line. +:: + + [codec] + 0x12345678 0xabcd1234 2 + + [subsystem_id] + 0xffff1111 + + [revision_id] + 0x10 + + [chip_name] + My-own NEWS-0002 + + +The hd-audio driver reads the file via request_firmware(). Thus, +a patch file has to be located on the appropriate firmware path, +typically, /lib/firmware. For example, when you pass the option +``patch=hda-init.fw``, the file /lib/firmware/hda-init.fw must be +present. + +The patch module option is specific to each card instance, and you +need to give one file name for each instance, separated by commas. +For example, if you have two cards, one for an on-board analog and one +for an HDMI video board, you may pass patch option like below: +:: + + options snd-hda-intel patch=on-board-patch,hdmi-patch + + +Power-Saving +------------ +The power-saving is a kind of auto-suspend of the device. When the +device is inactive for a certain time, the device is automatically +turned off to save the power. The time to go down is specified via +``power_save`` module option, and this option can be changed dynamically +via sysfs. + +The power-saving won't work when the analog loopback is enabled on +some codecs. Make sure that you mute all unneeded signal routes when +you want the power-saving. + +The power-saving feature might cause audible click noises at each +power-down/up depending on the device. Some of them might be +solvable, but some are hard, I'm afraid. Some distros such as +openSUSE enables the power-saving feature automatically when the power +cable is unplugged. Thus, if you hear noises, suspect first the +power-saving. See /sys/module/snd_hda_intel/parameters/power_save to +check the current value. If it's non-zero, the feature is turned on. + +The recent kernel supports the runtime PM for the HD-audio controller +chip, too. It means that the HD-audio controller is also powered up / +down dynamically. The feature is enabled only for certain controller +chips like Intel LynxPoint. You can enable/disable this feature +forcibly by setting ``power_save_controller`` option, which is also +available at /sys/module/snd_hda_intel/parameters directory. + + +Tracepoints +----------- +The hd-audio driver gives a few basic tracepoints. +``hda:hda_send_cmd`` traces each CORB write while ``hda:hda_get_response`` +traces the response from RIRB (only when read from the codec driver). +``hda:hda_bus_reset`` traces the bus-reset due to fatal error, etc, +``hda:hda_unsol_event`` traces the unsolicited events, and +``hda:hda_power_down`` and ``hda:hda_power_up`` trace the power down/up +via power-saving behavior. + +Enabling all tracepoints can be done like +:: + + # echo 1 > /sys/kernel/debug/tracing/events/hda/enable + +then after some commands, you can traces from +/sys/kernel/debug/tracing/trace file. For example, when you want to +trace what codec command is sent, enable the tracepoint like: +:: + + # cat /sys/kernel/debug/tracing/trace + # tracer: nop + # + # TASK-PID CPU# TIMESTAMP FUNCTION + # | | | | | + <...>-7807 [002] 105147.774889: hda_send_cmd: [0:0] val=e3a019 + <...>-7807 [002] 105147.774893: hda_send_cmd: [0:0] val=e39019 + <...>-7807 [002] 105147.999542: hda_send_cmd: [0:0] val=e3a01a + <...>-7807 [002] 105147.999543: hda_send_cmd: [0:0] val=e3901a + <...>-26764 [001] 349222.837143: hda_send_cmd: [0:0] val=e3a019 + <...>-26764 [001] 349222.837148: hda_send_cmd: [0:0] val=e39019 + <...>-26764 [001] 349223.058539: hda_send_cmd: [0:0] val=e3a01a + <...>-26764 [001] 349223.058541: hda_send_cmd: [0:0] val=e3901a + +Here ``[0:0]`` indicates the card number and the codec address, and +``val`` shows the value sent to the codec, respectively. The value is +a packed value, and you can decode it via hda-decode-verb program +included in hda-emu package below. For example, the value e3a019 is +to set the left output-amp value to 25. +:: + + % hda-decode-verb 0xe3a019 + raw value = 0x00e3a019 + cid = 0, nid = 0x0e, verb = 0x3a0, parm = 0x19 + raw value: verb = 0x3a0, parm = 0x19 + verbname = set_amp_gain_mute + amp raw val = 0xa019 + output, left, idx=0, mute=0, val=25 + + +Development Tree +---------------- +The latest development codes for HD-audio are found on sound git tree: + +* git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/sound.git + +The master branch or for-next branches can be used as the main +development branches in general while the development for the current +and next kernels are found in for-linus and for-next branches, +respectively. + + +Sending a Bug Report +-------------------- +If any model or module options don't work for your device, it's time +to send a bug report to the developers. Give the following in your +bug report: + +* Hardware vendor, product and model names +* Kernel version (and ALSA-driver version if you built externally) +* ``alsa-info.sh`` output; run with ``--no-upload`` option. See the + section below about alsa-info + +If it's a regression, at best, send alsa-info outputs of both working +and non-working kernels. This is really helpful because we can +compare the codec registers directly. + +Send a bug report either the followings: + +kernel-bugzilla + https://bugzilla.kernel.org/ +alsa-devel ML + alsa-devel@alsa-project.org + + +Debug Tools +=========== + +This section describes some tools available for debugging HD-audio +problems. + +alsa-info +--------- +The script ``alsa-info.sh`` is a very useful tool to gather the audio +device information. It's included in alsa-utils package. The latest +version can be found on git repository: + +* git://git.alsa-project.org/alsa-utils.git + +The script can be fetched directly from the following URL, too: + +* http://www.alsa-project.org/alsa-info.sh + +Run this script as root, and it will gather the important information +such as the module lists, module parameters, proc file contents +including the codec proc files, mixer outputs and the control +elements. As default, it will store the information onto a web server +on alsa-project.org. But, if you send a bug report, it'd be better to +run with ``--no-upload`` option, and attach the generated file. + +There are some other useful options. See ``--help`` option output for +details. + +When a probe error occurs or when the driver obviously assigns a +mismatched model, it'd be helpful to load the driver with +``probe_only=1`` option (at best after the cold reboot) and run +alsa-info at this state. With this option, the driver won't configure +the mixer and PCM but just tries to probe the codec slot. After +probing, the proc file is available, so you can get the raw codec +information before modified by the driver. Of course, the driver +isn't usable with ``probe_only=1``. But you can continue the +configuration via hwdep sysfs file if hda-reconfig option is enabled. +Using ``probe_only`` mask 2 skips the reset of HDA codecs (use +``probe_only=3`` as module option). The hwdep interface can be used +to determine the BIOS codec initialization. + + +hda-verb +-------- +hda-verb is a tiny program that allows you to access the HD-audio +codec directly. You can execute a raw HD-audio codec verb with this. +This program accesses the hwdep device, thus you need to enable the +kernel config ``CONFIG_SND_HDA_HWDEP=y`` beforehand. + +The hda-verb program takes four arguments: the hwdep device file, the +widget NID, the verb and the parameter. When you access to the codec +on the slot 2 of the card 0, pass /dev/snd/hwC0D2 to the first +argument, typically. (However, the real path name depends on the +system.) + +The second parameter is the widget number-id to access. The third +parameter can be either a hex/digit number or a string corresponding +to a verb. Similarly, the last parameter is the value to write, or +can be a string for the parameter type. + +:: + + % hda-verb /dev/snd/hwC0D0 0x12 0x701 2 + nid = 0x12, verb = 0x701, param = 0x2 + value = 0x0 + + % hda-verb /dev/snd/hwC0D0 0x0 PARAMETERS VENDOR_ID + nid = 0x0, verb = 0xf00, param = 0x0 + value = 0x10ec0262 + + % hda-verb /dev/snd/hwC0D0 2 set_a 0xb080 + nid = 0x2, verb = 0x300, param = 0xb080 + value = 0x0 + + +Although you can issue any verbs with this program, the driver state +won't be always updated. For example, the volume values are usually +cached in the driver, and thus changing the widget amp value directly +via hda-verb won't change the mixer value. + +The hda-verb program is included now in alsa-tools: + +* git://git.alsa-project.org/alsa-tools.git + +Also, the old stand-alone package is found in the ftp directory: + +* ftp://ftp.suse.com/pub/people/tiwai/misc/ + +Also a git repository is available: + +* git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/hda-verb.git + +See README file in the tarball for more details about hda-verb +program. + + +hda-analyzer +------------ +hda-analyzer provides a graphical interface to access the raw HD-audio +control, based on pyGTK2 binding. It's a more powerful version of +hda-verb. The program gives you an easy-to-use GUI stuff for showing +the widget information and adjusting the amp values, as well as the +proc-compatible output. + +The hda-analyzer: + +* http://git.alsa-project.org/?p=alsa.git;a=tree;f=hda-analyzer + +is a part of alsa.git repository in alsa-project.org: + +* git://git.alsa-project.org/alsa.git + +Codecgraph +---------- +Codecgraph is a utility program to generate a graph and visualizes the +codec-node connection of a codec chip. It's especially useful when +you analyze or debug a codec without a proper datasheet. The program +parses the given codec proc file and converts to SVG via graphiz +program. + +The tarball and GIT trees are found in the web page at: + +* http://helllabs.org/codecgraph/ + + +hda-emu +------- +hda-emu is an HD-audio emulator. The main purpose of this program is +to debug an HD-audio codec without the real hardware. Thus, it +doesn't emulate the behavior with the real audio I/O, but it just +dumps the codec register changes and the ALSA-driver internal changes +at probing and operating the HD-audio driver. + +The program requires a codec proc-file to simulate. Get a proc file +for the target codec beforehand, or pick up an example codec from the +codec proc collections in the tarball. Then, run the program with the +proc file, and the hda-emu program will start parsing the codec file +and simulates the HD-audio driver: + +:: + + % hda-emu codecs/stac9200-dell-d820-laptop + # Parsing.. + hda_codec: Unknown model for STAC9200, using BIOS defaults + hda_codec: pin nid 08 bios pin config 40c003fa + .... + + +The program gives you only a very dumb command-line interface. You +can get a proc-file dump at the current state, get a list of control +(mixer) elements, set/get the control element value, simulate the PCM +operation, the jack plugging simulation, etc. + +The program is found in the git repository below: + +* git://git.kernel.org/pub/scm/linux/kernel/git/tiwai/hda-emu.git + +See README file in the repository for more details about hda-emu +program. + + +hda-jack-retask +--------------- +hda-jack-retask is a user-friendly GUI program to manipulate the +HD-audio pin control for jack retasking. If you have a problem about +the jack assignment, try this program and check whether you can get +useful results. Once when you figure out the proper pin assignment, +it can be fixed either in the driver code statically or via passing a +firmware patch file (see "Early Patching" section). + +The program is included in alsa-tools now: + +* git://git.alsa-project.org/alsa-tools.git diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst index 280a57115f00..e9bac7c8b893 100644 --- a/Documentation/sound/index.rst +++ b/Documentation/sound/index.rst @@ -6,6 +6,7 @@ Linux Sound Subsystem Documentation :maxdepth: 2 kernel-api/index + hd-audio/index .. only:: subproject -- cgit v1.2.3 From a4caad753f0ccc201482bee4bdaa1875524bf2ab Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 14:43:16 +0100 Subject: ALSA: doc: ReSTize HD-Audio-Models document A simple reformat with the description list of ReST, and the content was kept as is, but renamed as Documentation/sound/hd-audio/models.rst. Signed-off-by: Takashi Iwai --- Documentation/sound/alsa/HD-Audio-Models.txt | 324 ----------------- Documentation/sound/hd-audio/index.rst | 1 + Documentation/sound/hd-audio/models.rst | 518 +++++++++++++++++++++++++++ 3 files changed, 519 insertions(+), 324 deletions(-) delete mode 100644 Documentation/sound/alsa/HD-Audio-Models.txt create mode 100644 Documentation/sound/hd-audio/models.rst diff --git a/Documentation/sound/alsa/HD-Audio-Models.txt b/Documentation/sound/alsa/HD-Audio-Models.txt deleted file mode 100644 index ec099d4343f2..000000000000 --- a/Documentation/sound/alsa/HD-Audio-Models.txt +++ /dev/null @@ -1,324 +0,0 @@ - Model name Description - ---------- ----------- -ALC880 -====== - 3stack 3-jack in back and a headphone out - 3stack-digout 3-jack in back, a HP out and a SPDIF out - 5stack 5-jack in back, 2-jack in front - 5stack-digout 5-jack in back, 2-jack in front, a SPDIF out - 6stack 6-jack in back, 2-jack in front - 6stack-digout 6-jack with a SPDIF out - -ALC260 -====== - gpio1 Enable GPIO1 - coef Enable EAPD via COEF table - fujitsu Quirk for FSC S7020 - fujitsu-jwse Quirk for FSC S7020 with jack modes and HP mic support - -ALC262 -====== - inv-dmic Inverted internal mic workaround - -ALC267/268 -========== - inv-dmic Inverted internal mic workaround - hp-eapd Disable HP EAPD on NID 0x15 - -ALC22x/23x/25x/269/27x/28x/29x (and vendor-specific ALC3xxx models) -====== - laptop-amic Laptops with analog-mic input - laptop-dmic Laptops with digital-mic input - alc269-dmic Enable ALC269(VA) digital mic workaround - alc271-dmic Enable ALC271X digital mic workaround - inv-dmic Inverted internal mic workaround - headset-mic Indicates a combined headset (headphone+mic) jack - headset-mode More comprehensive headset support for ALC269 & co - headset-mode-no-hp-mic Headset mode support without headphone mic - lenovo-dock Enables docking station I/O for some Lenovos - hp-gpio-led GPIO LED support on HP laptops - dell-headset-multi Headset jack, which can also be used as mic-in - dell-headset-dock Headset jack (without mic-in), and also dock I/O - alc283-dac-wcaps Fixups for Chromebook with ALC283 - alc283-sense-combo Combo jack sensing on ALC283 - tpt440-dock Pin configs for Lenovo Thinkpad Dock support - -ALC66x/67x/892 -============== - mario Chromebook mario model fixup - asus-mode1 ASUS - asus-mode2 ASUS - asus-mode3 ASUS - asus-mode4 ASUS - asus-mode5 ASUS - asus-mode6 ASUS - asus-mode7 ASUS - asus-mode8 ASUS - inv-dmic Inverted internal mic workaround - dell-headset-multi Headset jack, which can also be used as mic-in - -ALC680 -====== - N/A - -ALC88x/898/1150 -====================== - acer-aspire-4930g Acer Aspire 4930G/5930G/6530G/6930G/7730G - acer-aspire-8930g Acer Aspire 8330G/6935G - acer-aspire Acer Aspire others - inv-dmic Inverted internal mic workaround - no-primary-hp VAIO Z/VGC-LN51JGB workaround (for fixed speaker DAC) - -ALC861/660 -========== - N/A - -ALC861VD/660VD -============== - N/A - -CMI9880 -======= - minimal 3-jack in back - min_fp 3-jack in back, 2-jack in front - full 6-jack in back, 2-jack in front - full_dig 6-jack in back, 2-jack in front, SPDIF I/O - allout 5-jack in back, 2-jack in front, SPDIF out - auto auto-config reading BIOS (default) - -AD1882 / AD1882A -================ - 3stack 3-stack mode - 3stack-automute 3-stack with automute front HP (default) - 6stack 6-stack mode - -AD1884A / AD1883 / AD1984A / AD1984B -==================================== - desktop 3-stack desktop (default) - laptop laptop with HP jack sensing - mobile mobile devices with HP jack sensing - thinkpad Lenovo Thinkpad X300 - touchsmart HP Touchsmart - -AD1884 -====== - N/A - -AD1981 -====== - basic 3-jack (default) - hp HP nx6320 - thinkpad Lenovo Thinkpad T60/X60/Z60 - toshiba Toshiba U205 - -AD1983 -====== - N/A - -AD1984 -====== - basic default configuration - thinkpad Lenovo Thinkpad T61/X61 - dell_desktop Dell T3400 - -AD1986A -======= - 3stack 3-stack, shared surrounds - laptop 2-channel only (FSC V2060, Samsung M50) - laptop-imic 2-channel with built-in mic - eapd Turn on EAPD constantly - -AD1988/AD1988B/AD1989A/AD1989B -============================== - 6stack 6-jack - 6stack-dig ditto with SPDIF - 3stack 3-jack - 3stack-dig ditto with SPDIF - laptop 3-jack with hp-jack automute - laptop-dig ditto with SPDIF - auto auto-config reading BIOS (default) - -Conexant 5045 -============= - laptop-hpsense Laptop with HP sense (old model laptop) - laptop-micsense Laptop with Mic sense (old model fujitsu) - laptop-hpmicsense Laptop with HP and Mic senses - benq Benq R55E - laptop-hp530 HP 530 laptop - test for testing/debugging purpose, almost all controls - can be adjusted. Appearing only when compiled with - $CONFIG_SND_DEBUG=y - -Conexant 5047 -============= - laptop Basic Laptop config - laptop-hp Laptop config for some HP models (subdevice 30A5) - laptop-eapd Laptop config with EAPD support - test for testing/debugging purpose, almost all controls - can be adjusted. Appearing only when compiled with - $CONFIG_SND_DEBUG=y - -Conexant 5051 -============= - laptop Basic Laptop config (default) - hp HP Spartan laptop - hp-dv6736 HP dv6736 - hp-f700 HP Compaq Presario F700 - ideapad Lenovo IdeaPad laptop - toshiba Toshiba Satellite M300 - -Conexant 5066 -============= - laptop Basic Laptop config (default) - hp-laptop HP laptops, e g G60 - asus Asus K52JU, Lenovo G560 - dell-laptop Dell laptops - dell-vostro Dell Vostro - olpc-xo-1_5 OLPC XO 1.5 - ideapad Lenovo IdeaPad U150 - thinkpad Lenovo Thinkpad - -STAC9200 -======== - ref Reference board - oqo OQO Model 2 - dell-d21 Dell (unknown) - dell-d22 Dell (unknown) - dell-d23 Dell (unknown) - dell-m21 Dell Inspiron 630m, Dell Inspiron 640m - dell-m22 Dell Latitude D620, Dell Latitude D820 - dell-m23 Dell XPS M1710, Dell Precision M90 - dell-m24 Dell Latitude 120L - dell-m25 Dell Inspiron E1505n - dell-m26 Dell Inspiron 1501 - dell-m27 Dell Inspiron E1705/9400 - gateway-m4 Gateway laptops with EAPD control - gateway-m4-2 Gateway laptops with EAPD control - panasonic Panasonic CF-74 - auto BIOS setup (default) - -STAC9205/9254 -============= - ref Reference board - dell-m42 Dell (unknown) - dell-m43 Dell Precision - dell-m44 Dell Inspiron - eapd Keep EAPD on (e.g. Gateway T1616) - auto BIOS setup (default) - -STAC9220/9221 -============= - ref Reference board - 3stack D945 3stack - 5stack D945 5stack + SPDIF - intel-mac-v1 Intel Mac Type 1 - intel-mac-v2 Intel Mac Type 2 - intel-mac-v3 Intel Mac Type 3 - intel-mac-v4 Intel Mac Type 4 - intel-mac-v5 Intel Mac Type 5 - intel-mac-auto Intel Mac (detect type according to subsystem id) - macmini Intel Mac Mini (equivalent with type 3) - macbook Intel Mac Book (eq. type 5) - macbook-pro-v1 Intel Mac Book Pro 1st generation (eq. type 3) - macbook-pro Intel Mac Book Pro 2nd generation (eq. type 3) - imac-intel Intel iMac (eq. type 2) - imac-intel-20 Intel iMac (newer version) (eq. type 3) - ecs202 ECS/PC chips - dell-d81 Dell (unknown) - dell-d82 Dell (unknown) - dell-m81 Dell (unknown) - dell-m82 Dell XPS M1210 - auto BIOS setup (default) - -STAC9202/9250/9251 -================== - ref Reference board, base config - m1 Some Gateway MX series laptops (NX560XL) - m1-2 Some Gateway MX series laptops (MX6453) - m2 Some Gateway MX series laptops (M255) - m2-2 Some Gateway MX series laptops - m3 Some Gateway MX series laptops - m5 Some Gateway MX series laptops (MP6954) - m6 Some Gateway NX series laptops - auto BIOS setup (default) - -STAC9227/9228/9229/927x -======================= - ref Reference board - ref-no-jd Reference board without HP/Mic jack detection - 3stack D965 3stack - 5stack D965 5stack + SPDIF - 5stack-no-fp D965 5stack without front panel - dell-3stack Dell Dimension E520 - dell-bios Fixes with Dell BIOS setup - dell-bios-amic Fixes with Dell BIOS setup including analog mic - volknob Fixes with volume-knob widget 0x24 - auto BIOS setup (default) - -STAC92HD71B* -============ - ref Reference board - dell-m4-1 Dell desktops - dell-m4-2 Dell desktops - dell-m4-3 Dell desktops - hp-m4 HP mini 1000 - hp-dv5 HP dv series - hp-hdx HP HDX series - hp-dv4-1222nr HP dv4-1222nr (with LED support) - auto BIOS setup (default) - -STAC92HD73* -=========== - ref Reference board - no-jd BIOS setup but without jack-detection - intel Intel DG45* mobos - dell-m6-amic Dell desktops/laptops with analog mics - dell-m6-dmic Dell desktops/laptops with digital mics - dell-m6 Dell desktops/laptops with both type of mics - dell-eq Dell desktops/laptops - alienware Alienware M17x - auto BIOS setup (default) - -STAC92HD83* -=========== - ref Reference board - mic-ref Reference board with power management for ports - dell-s14 Dell laptop - dell-vostro-3500 Dell Vostro 3500 laptop - hp-dv7-4000 HP dv-7 4000 - hp_cNB11_intquad HP CNB models with 4 speakers - hp-zephyr HP Zephyr - hp-led HP with broken BIOS for mute LED - hp-inv-led HP with broken BIOS for inverted mute LED - hp-mic-led HP with mic-mute LED - headset-jack Dell Latitude with a 4-pin headset jack - hp-envy-bass Pin fixup for HP Envy bass speaker (NID 0x0f) - hp-envy-ts-bass Pin fixup for HP Envy TS bass speaker (NID 0x10) - hp-bnb13-eq Hardware equalizer setup for HP laptops - auto BIOS setup (default) - -STAC92HD95 -========== - hp-led LED support for HP laptops - hp-bass Bass HPF setup for HP Spectre 13 - -STAC9872 -======== - vaio VAIO laptop without SPDIF - auto BIOS setup (default) - -Cirrus Logic CS4206/4207 -======================== - mbp55 MacBook Pro 5,5 - imac27 IMac 27 Inch - auto BIOS setup (default) - -Cirrus Logic CS4208 -=================== - mba6 MacBook Air 6,1 and 6,2 - gpio0 Enable GPIO 0 amp - auto BIOS setup (default) - -VIA VT17xx/VT18xx/VT20xx -======================== - auto BIOS setup (default) diff --git a/Documentation/sound/hd-audio/index.rst b/Documentation/sound/hd-audio/index.rst index f2dc29019f12..1e8376b0066c 100644 --- a/Documentation/sound/hd-audio/index.rst +++ b/Documentation/sound/hd-audio/index.rst @@ -5,3 +5,4 @@ HD-Audio :maxdepth: 2 notes + models diff --git a/Documentation/sound/hd-audio/models.rst b/Documentation/sound/hd-audio/models.rst new file mode 100644 index 000000000000..5338673c88d9 --- /dev/null +++ b/Documentation/sound/hd-audio/models.rst @@ -0,0 +1,518 @@ +============================== +HD-Audio Codec-Specific Models +============================== + +ALC880 +====== +3stack + 3-jack in back and a headphone out +3stack-digout + 3-jack in back, a HP out and a SPDIF out +5stack + 5-jack in back, 2-jack in front +5stack-digout + 5-jack in back, 2-jack in front, a SPDIF out +6stack + 6-jack in back, 2-jack in front +6stack-digout + 6-jack with a SPDIF out + +ALC260 +====== +gpio1 + Enable GPIO1 +coef + Enable EAPD via COEF table +fujitsu + Quirk for FSC S7020 +fujitsu-jwse + Quirk for FSC S7020 with jack modes and HP mic support + +ALC262 +====== +inv-dmic + Inverted internal mic workaround + +ALC267/268 +========== +inv-dmic + Inverted internal mic workaround +hp-eapd + Disable HP EAPD on NID 0x15 + +ALC22x/23x/25x/269/27x/28x/29x (and vendor-specific ALC3xxx models) +=================================================================== +laptop-amic + Laptops with analog-mic input +laptop-dmic + Laptops with digital-mic input +alc269-dmic + Enable ALC269(VA) digital mic workaround +alc271-dmic + Enable ALC271X digital mic workaround +inv-dmic + Inverted internal mic workaround +headset-mic + Indicates a combined headset (headphone+mic) jack +headset-mode + More comprehensive headset support for ALC269 & co +headset-mode-no-hp-mic + Headset mode support without headphone mic +lenovo-dock + Enables docking station I/O for some Lenovos +hp-gpio-led + GPIO LED support on HP laptops +dell-headset-multi + Headset jack, which can also be used as mic-in +dell-headset-dock + Headset jack (without mic-in), and also dock I/O +alc283-dac-wcaps + Fixups for Chromebook with ALC283 +alc283-sense-combo + Combo jack sensing on ALC283 +tpt440-dock + Pin configs for Lenovo Thinkpad Dock support + +ALC66x/67x/892 +============== +mario + Chromebook mario model fixup +asus-mode1 + ASUS +asus-mode2 + ASUS +asus-mode3 + ASUS +asus-mode4 + ASUS +asus-mode5 + ASUS +asus-mode6 + ASUS +asus-mode7 + ASUS +asus-mode8 + ASUS +inv-dmic + Inverted internal mic workaround +dell-headset-multi + Headset jack, which can also be used as mic-in + +ALC680 +====== +N/A + +ALC88x/898/1150 +====================== +acer-aspire-4930g + Acer Aspire 4930G/5930G/6530G/6930G/7730G +acer-aspire-8930g + Acer Aspire 8330G/6935G +acer-aspire + Acer Aspire others +inv-dmic + Inverted internal mic workaround +no-primary-hp + VAIO Z/VGC-LN51JGB workaround (for fixed speaker DAC) + +ALC861/660 +========== +N/A + +ALC861VD/660VD +============== +N/A + +CMI9880 +======= +minimal + 3-jack in back +min_fp + 3-jack in back, 2-jack in front +full + 6-jack in back, 2-jack in front +full_dig + 6-jack in back, 2-jack in front, SPDIF I/O +allout + 5-jack in back, 2-jack in front, SPDIF out +auto + auto-config reading BIOS (default) + +AD1882 / AD1882A +================ +3stack + 3-stack mode +3stack-automute + 3-stack with automute front HP (default) +6stack + 6-stack mode + +AD1884A / AD1883 / AD1984A / AD1984B +==================================== +desktop 3-stack desktop (default) +laptop laptop with HP jack sensing +mobile mobile devices with HP jack sensing +thinkpad Lenovo Thinkpad X300 +touchsmart HP Touchsmart + +AD1884 +====== +N/A + +AD1981 +====== +basic 3-jack (default) +hp HP nx6320 +thinkpad Lenovo Thinkpad T60/X60/Z60 +toshiba Toshiba U205 + +AD1983 +====== +N/A + +AD1984 +====== +basic default configuration +thinkpad Lenovo Thinkpad T61/X61 +dell_desktop Dell T3400 + +AD1986A +======= +3stack + 3-stack, shared surrounds +laptop + 2-channel only (FSC V2060, Samsung M50) +laptop-imic + 2-channel with built-in mic +eapd + Turn on EAPD constantly + +AD1988/AD1988B/AD1989A/AD1989B +============================== +6stack + 6-jack +6stack-dig + ditto with SPDIF +3stack + 3-jack +3stack-dig + ditto with SPDIF +laptop + 3-jack with hp-jack automute +laptop-dig + ditto with SPDIF +auto + auto-config reading BIOS (default) + +Conexant 5045 +============= +laptop-hpsense + Laptop with HP sense (old model laptop) +laptop-micsense + Laptop with Mic sense (old model fujitsu) +laptop-hpmicsense + Laptop with HP and Mic senses +benq + Benq R55E +laptop-hp530 + HP 530 laptop +test + for testing/debugging purpose, almost all controls can be + adjusted. Appearing only when compiled with $CONFIG_SND_DEBUG=y + +Conexant 5047 +============= +laptop + Basic Laptop config +laptop-hp + Laptop config for some HP models (subdevice 30A5) +laptop-eapd + Laptop config with EAPD support +test + for testing/debugging purpose, almost all controls can be + adjusted. Appearing only when compiled with $CONFIG_SND_DEBUG=y + +Conexant 5051 +============= +laptop + Basic Laptop config (default) +hp + HP Spartan laptop +hp-dv6736 + HP dv6736 +hp-f700 + HP Compaq Presario F700 +ideapad + Lenovo IdeaPad laptop +toshiba + Toshiba Satellite M300 + +Conexant 5066 +============= +laptop + Basic Laptop config (default) +hp-laptop + HP laptops, e g G60 +asus + Asus K52JU, Lenovo G560 +dell-laptop + Dell laptops +dell-vostro + Dell Vostro +olpc-xo-1_5 + OLPC XO 1.5 +ideapad + Lenovo IdeaPad U150 +thinkpad + Lenovo Thinkpad + +STAC9200 +======== +ref + Reference board +oqo + OQO Model 2 +dell-d21 + Dell (unknown) +dell-d22 + Dell (unknown) +dell-d23 + Dell (unknown) +dell-m21 + Dell Inspiron 630m, Dell Inspiron 640m +dell-m22 + Dell Latitude D620, Dell Latitude D820 +dell-m23 + Dell XPS M1710, Dell Precision M90 +dell-m24 + Dell Latitude 120L +dell-m25 + Dell Inspiron E1505n +dell-m26 + Dell Inspiron 1501 +dell-m27 + Dell Inspiron E1705/9400 +gateway-m4 + Gateway laptops with EAPD control +gateway-m4-2 + Gateway laptops with EAPD control +panasonic + Panasonic CF-74 +auto + BIOS setup (default) + +STAC9205/9254 +============= +ref + Reference board +dell-m42 + Dell (unknown) +dell-m43 + Dell Precision +dell-m44 + Dell Inspiron +eapd + Keep EAPD on (e.g. Gateway T1616) +auto + BIOS setup (default) + +STAC9220/9221 +============= +ref + Reference board +3stack + D945 3stack +5stack + D945 5stack + SPDIF +intel-mac-v1 + Intel Mac Type 1 +intel-mac-v2 + Intel Mac Type 2 +intel-mac-v3 + Intel Mac Type 3 +intel-mac-v4 + Intel Mac Type 4 +intel-mac-v5 + Intel Mac Type 5 +intel-mac-auto + Intel Mac (detect type according to subsystem id) +macmini + Intel Mac Mini (equivalent with type 3) +macbook + Intel Mac Book (eq. type 5) +macbook-pro-v1 + Intel Mac Book Pro 1st generation (eq. type 3) +macbook-pro + Intel Mac Book Pro 2nd generation (eq. type 3) +imac-intel + Intel iMac (eq. type 2) +imac-intel-20 + Intel iMac (newer version) (eq. type 3) +ecs202 + ECS/PC chips +dell-d81 + Dell (unknown) +dell-d82 + Dell (unknown) +dell-m81 + Dell (unknown) +dell-m82 + Dell XPS M1210 +auto + BIOS setup (default) + +STAC9202/9250/9251 +================== +ref + Reference board, base config +m1 + Some Gateway MX series laptops (NX560XL) +m1-2 + Some Gateway MX series laptops (MX6453) +m2 + Some Gateway MX series laptops (M255) +m2-2 + Some Gateway MX series laptops +m3 + Some Gateway MX series laptops +m5 + Some Gateway MX series laptops (MP6954) +m6 + Some Gateway NX series laptops +auto + BIOS setup (default) + +STAC9227/9228/9229/927x +======================= +ref + Reference board +ref-no-jd + Reference board without HP/Mic jack detection +3stack + D965 3stack +5stack + D965 5stack + SPDIF +5stack-no-fp + D965 5stack without front panel +dell-3stack + Dell Dimension E520 +dell-bios + Fixes with Dell BIOS setup +dell-bios-amic + Fixes with Dell BIOS setup including analog mic +volknob + Fixes with volume-knob widget 0x24 +auto + BIOS setup (default) + +STAC92HD71B* +============ +ref + Reference board +dell-m4-1 + Dell desktops +dell-m4-2 + Dell desktops +dell-m4-3 + Dell desktops +hp-m4 + HP mini 1000 +hp-dv5 + HP dv series +hp-hdx + HP HDX series +hp-dv4-1222nr + HP dv4-1222nr (with LED support) +auto + BIOS setup (default) + +STAC92HD73* +=========== +ref + Reference board +no-jd + BIOS setup but without jack-detection +intel + Intel DG45* mobos +dell-m6-amic + Dell desktops/laptops with analog mics +dell-m6-dmic + Dell desktops/laptops with digital mics +dell-m6 + Dell desktops/laptops with both type of mics +dell-eq + Dell desktops/laptops +alienware + Alienware M17x +auto + BIOS setup (default) + +STAC92HD83* +=========== +ref + Reference board +mic-ref + Reference board with power management for ports +dell-s14 + Dell laptop +dell-vostro-3500 + Dell Vostro 3500 laptop +hp-dv7-4000 + HP dv-7 4000 +hp_cNB11_intquad + HP CNB models with 4 speakers +hp-zephyr + HP Zephyr +hp-led + HP with broken BIOS for mute LED +hp-inv-led + HP with broken BIOS for inverted mute LED +hp-mic-led + HP with mic-mute LED +headset-jack + Dell Latitude with a 4-pin headset jack +hp-envy-bass + Pin fixup for HP Envy bass speaker (NID 0x0f) +hp-envy-ts-bass + Pin fixup for HP Envy TS bass speaker (NID 0x10) +hp-bnb13-eq + Hardware equalizer setup for HP laptops +auto + BIOS setup (default) + +STAC92HD95 +========== +hp-led + LED support for HP laptops +hp-bass + Bass HPF setup for HP Spectre 13 + +STAC9872 +======== +vaio + VAIO laptop without SPDIF +auto + BIOS setup (default) + +Cirrus Logic CS4206/4207 +======================== +mbp55 + MacBook Pro 5,5 +imac27 + IMac 27 Inch +auto + BIOS setup (default) + +Cirrus Logic CS4208 +=================== +mba6 + MacBook Air 6,1 and 6,2 +gpio0 + Enable GPIO 0 amp +auto + BIOS setup (default) + +VIA VT17xx/VT18xx/VT20xx +======================== +auto + BIOS setup (default) -- cgit v1.2.3 From fe0abd18e1ef3cb258b0a5e41ba26ed0c4b88dab Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 16:56:01 +0100 Subject: ALSA: doc: ReSTize HD-Audio-Controls document A conversion from a simple text file. Put to hd-audio subdirectory with a rename. Signed-off-by: Takashi Iwai --- Documentation/sound/alsa/HD-Audio-Controls.txt | 116 ------------------------ Documentation/sound/hd-audio/controls.rst | 121 +++++++++++++++++++++++++ Documentation/sound/hd-audio/index.rst | 1 + 3 files changed, 122 insertions(+), 116 deletions(-) delete mode 100644 Documentation/sound/alsa/HD-Audio-Controls.txt create mode 100644 Documentation/sound/hd-audio/controls.rst diff --git a/Documentation/sound/alsa/HD-Audio-Controls.txt b/Documentation/sound/alsa/HD-Audio-Controls.txt deleted file mode 100644 index e9621e349e17..000000000000 --- a/Documentation/sound/alsa/HD-Audio-Controls.txt +++ /dev/null @@ -1,116 +0,0 @@ -This file explains the codec-specific mixer controls. - -Realtek codecs --------------- - -* Channel Mode - This is an enum control to change the surround-channel setup, - appears only when the surround channels are available. - It gives the number of channels to be used, "2ch", "4ch", "6ch", - and "8ch". According to the configuration, this also controls the - jack-retasking of multi-I/O jacks. - -* Auto-Mute Mode - This is an enum control to change the auto-mute behavior of the - headphone and line-out jacks. If built-in speakers and headphone - and/or line-out jacks are available on a machine, this controls - appears. - When there are only either headphones or line-out jacks, it gives - "Disabled" and "Enabled" state. When enabled, the speaker is muted - automatically when a jack is plugged. - - When both headphone and line-out jacks are present, it gives - "Disabled", "Speaker Only" and "Line-Out+Speaker". When - speaker-only is chosen, plugging into a headphone or a line-out jack - mutes the speakers, but not line-outs. When line-out+speaker is - selected, plugging to a headphone jack mutes both speakers and - line-outs. - - -IDT/Sigmatel codecs -------------------- - -* Analog Loopback - This control enables/disables the analog-loopback circuit. This - appears only when "loopback" is set to true in a codec hint - (see HD-Audio.txt). Note that on some codecs the analog-loopback - and the normal PCM playback are exclusive, i.e. when this is on, you - won't hear any PCM stream. - -* Swap Center/LFE - Swaps the center and LFE channel order. Normally, the left - corresponds to the center and the right to the LFE. When this is - ON, the left to the LFE and the right to the center. - -* Headphone as Line Out - When this control is ON, treat the headphone jacks as line-out - jacks. That is, the headphone won't auto-mute the other line-outs, - and no HP-amp is set to the pins. - -* Mic Jack Mode, Line Jack Mode, etc - These enum controls the direction and the bias of the input jack - pins. Depending on the jack type, it can set as "Mic In" and "Line - In", for determining the input bias, or it can be set to "Line Out" - when the pin is a multi-I/O jack for surround channels. - - -VIA codecs ----------- - -* Smart 5.1 - An enum control to re-task the multi-I/O jacks for surround outputs. - When it's ON, the corresponding input jacks (usually a line-in and a - mic-in) are switched as the surround and the CLFE output jacks. - -* Independent HP - When this enum control is enabled, the headphone output is routed - from an individual stream (the third PCM such as hw:0,2) instead of - the primary stream. In the case the headphone DAC is shared with a - side or a CLFE-channel DAC, the DAC is switched to the headphone - automatically. - -* Loopback Mixing - An enum control to determine whether the analog-loopback route is - enabled or not. When it's enabled, the analog-loopback is mixed to - the front-channel. Also, the same route is used for the headphone - and speaker outputs. As a side-effect, when this mode is set, the - individual volume controls will be no longer available for - headphones and speakers because there is only one DAC connected to a - mixer widget. - -* Dynamic Power-Control - This control determines whether the dynamic power-control per jack - detection is enabled or not. When enabled, the widgets power state - (D0/D3) are changed dynamically depending on the jack plugging - state for saving power consumptions. However, if your system - doesn't provide a proper jack-detection, this won't work; in such a - case, turn this control OFF. - -* Jack Detect - This control is provided only for VT1708 codec which gives no proper - unsolicited event per jack plug. When this is on, the driver polls - the jack detection so that the headphone auto-mute can work, while - turning this off would reduce the power consumption. - - -Conexant codecs ---------------- - -* Auto-Mute Mode - See Reatek codecs. - - -Analog codecs --------------- - -* Channel Mode - This is an enum control to change the surround-channel setup, - appears only when the surround channels are available. - It gives the number of channels to be used, "2ch", "4ch" and "6ch". - According to the configuration, this also controls the - jack-retasking of multi-I/O jacks. - -* Independent HP - When this enum control is enabled, the headphone output is routed - from an individual stream (the third PCM such as hw:0,2) instead of - the primary stream. diff --git a/Documentation/sound/hd-audio/controls.rst b/Documentation/sound/hd-audio/controls.rst new file mode 100644 index 000000000000..f2ebc4f79b44 --- /dev/null +++ b/Documentation/sound/hd-audio/controls.rst @@ -0,0 +1,121 @@ +====================================== +HD-Audio Codec-Specific Mixer Controls +====================================== + + +This file explains the codec-specific mixer controls. + +Realtek codecs +-------------- + +Channel Mode + This is an enum control to change the surround-channel setup, + appears only when the surround channels are available. + It gives the number of channels to be used, "2ch", "4ch", "6ch", + and "8ch". According to the configuration, this also controls the + jack-retasking of multi-I/O jacks. + +Auto-Mute Mode + This is an enum control to change the auto-mute behavior of the + headphone and line-out jacks. If built-in speakers and headphone + and/or line-out jacks are available on a machine, this controls + appears. + When there are only either headphones or line-out jacks, it gives + "Disabled" and "Enabled" state. When enabled, the speaker is muted + automatically when a jack is plugged. + + When both headphone and line-out jacks are present, it gives + "Disabled", "Speaker Only" and "Line-Out+Speaker". When + speaker-only is chosen, plugging into a headphone or a line-out jack + mutes the speakers, but not line-outs. When line-out+speaker is + selected, plugging to a headphone jack mutes both speakers and + line-outs. + + +IDT/Sigmatel codecs +------------------- + +Analog Loopback + This control enables/disables the analog-loopback circuit. This + appears only when "loopback" is set to true in a codec hint + (see HD-Audio.txt). Note that on some codecs the analog-loopback + and the normal PCM playback are exclusive, i.e. when this is on, you + won't hear any PCM stream. + +Swap Center/LFE + Swaps the center and LFE channel order. Normally, the left + corresponds to the center and the right to the LFE. When this is + ON, the left to the LFE and the right to the center. + +Headphone as Line Out + When this control is ON, treat the headphone jacks as line-out + jacks. That is, the headphone won't auto-mute the other line-outs, + and no HP-amp is set to the pins. + +Mic Jack Mode, Line Jack Mode, etc + These enum controls the direction and the bias of the input jack + pins. Depending on the jack type, it can set as "Mic In" and "Line + In", for determining the input bias, or it can be set to "Line Out" + when the pin is a multi-I/O jack for surround channels. + + +VIA codecs +---------- + +Smart 5.1 + An enum control to re-task the multi-I/O jacks for surround outputs. + When it's ON, the corresponding input jacks (usually a line-in and a + mic-in) are switched as the surround and the CLFE output jacks. + +Independent HP + When this enum control is enabled, the headphone output is routed + from an individual stream (the third PCM such as hw:0,2) instead of + the primary stream. In the case the headphone DAC is shared with a + side or a CLFE-channel DAC, the DAC is switched to the headphone + automatically. + +Loopback Mixing + An enum control to determine whether the analog-loopback route is + enabled or not. When it's enabled, the analog-loopback is mixed to + the front-channel. Also, the same route is used for the headphone + and speaker outputs. As a side-effect, when this mode is set, the + individual volume controls will be no longer available for + headphones and speakers because there is only one DAC connected to a + mixer widget. + +Dynamic Power-Control + This control determines whether the dynamic power-control per jack + detection is enabled or not. When enabled, the widgets power state + (D0/D3) are changed dynamically depending on the jack plugging + state for saving power consumptions. However, if your system + doesn't provide a proper jack-detection, this won't work; in such a + case, turn this control OFF. + +Jack Detect + This control is provided only for VT1708 codec which gives no proper + unsolicited event per jack plug. When this is on, the driver polls + the jack detection so that the headphone auto-mute can work, while + turning this off would reduce the power consumption. + + +Conexant codecs +--------------- + +Auto-Mute Mode + See Reatek codecs. + + +Analog codecs +-------------- + +Channel Mode + This is an enum control to change the surround-channel setup, + appears only when the surround channels are available. + It gives the number of channels to be used, "2ch", "4ch" and "6ch". + According to the configuration, this also controls the + jack-retasking of multi-I/O jacks. + +Independent HP + When this enum control is enabled, the headphone output is routed + from an individual stream (the third PCM such as hw:0,2) instead of + the primary stream. diff --git a/Documentation/sound/hd-audio/index.rst b/Documentation/sound/hd-audio/index.rst index 1e8376b0066c..c6efd55a219f 100644 --- a/Documentation/sound/hd-audio/index.rst +++ b/Documentation/sound/hd-audio/index.rst @@ -6,3 +6,4 @@ HD-Audio notes models + controls -- cgit v1.2.3 From 76ab4e15158c677141e8b8ff5f0295166f474553 Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Thu, 10 Nov 2016 17:41:45 +0100 Subject: ALSA: doc: ReSTize HD-Audio-DP-MST-audio.txt A simple conversion from a plain text file. Put to hd-audio subdirectory. Signed-off-by: Takashi Iwai --- Documentation/sound/alsa/HD-Audio-DP-MST-audio.txt | 74 ------------------- Documentation/sound/hd-audio/dp-mst.rst | 84 ++++++++++++++++++++++ Documentation/sound/hd-audio/index.rst | 1 + 3 files changed, 85 insertions(+), 74 deletions(-) delete mode 100644 Documentation/sound/alsa/HD-Audio-DP-MST-audio.txt create mode 100644 Documentation/sound/hd-audio/dp-mst.rst diff --git a/Documentation/sound/alsa/HD-Audio-DP-MST-audio.txt b/Documentation/sound/alsa/HD-Audio-DP-MST-audio.txt deleted file mode 100644 index 82744ac3513d..000000000000 --- a/Documentation/sound/alsa/HD-Audio-DP-MST-audio.txt +++ /dev/null @@ -1,74 +0,0 @@ -To support DP MST audio, HD Audio hdmi codec driver introduces virtual pin -and dynamic pcm assignment. - -Virtual pin is an extension of per_pin. The most difference of DP MST -from legacy is that DP MST introduces device entry. Each pin can contain -several device entries. Each device entry behaves as a pin. - -As each pin may contain several device entries and each codec may contain -several pins, if we use one pcm per per_pin, there will be many PCMs. -The new solution is to create a few PCMs and to dynamically bind pcm to -per_pin. Driver uses spec->dyn_pcm_assign flag to indicate whether to use -the new solution. - -PCM -=== -To be added - - -Jack -==== - -Presume: - - MST must be dyn_pcm_assign, and it is acomp (for Intel scenario); - - NON-MST may or may not be dyn_pcm_assign, it can be acomp or !acomp; - -So there are the following scenarios: - a. MST (&& dyn_pcm_assign && acomp) - b. NON-MST && dyn_pcm_assign && acomp - c. NON-MST && !dyn_pcm_assign && !acomp - -Below discussion will ignore MST and NON-MST difference as it doesn't -impact on jack handling too much. - -Driver uses struct hdmi_pcm pcm[] array in hdmi_spec and snd_jack is -a member of hdmi_pcm. Each pin has one struct hdmi_pcm * pcm pointer. - -For !dyn_pcm_assign, per_pin->pcm will assigned to spec->pcm[n] statically. - -For dyn_pcm_assign, per_pin->pcm will assigned to spec->pcm[n] -when monitor is hotplugged. - - -Build Jack ----------- - -- dyn_pcm_assign -Will not use hda_jack but use snd_jack in spec->pcm_rec[pcm_idx].jack directly. - -- !dyn_pcm_assign -Use hda_jack and assign spec->pcm_rec[pcm_idx].jack = jack->jack statically. - - -Unsolicited Event Enabling --------------------------- -Enable unsolicited event if !acomp. - - -Monitor Hotplug Event Handling ------------------------------- -- acomp -pin_eld_notify() -> check_presence_and_report() -> hdmi_present_sense() -> -sync_eld_via_acomp(). -Use directly snd_jack_report() on spec->pcm_rec[pcm_idx].jack for -both dyn_pcm_assign and !dyn_pcm_assign - -- !acomp -Hdmi_unsol_event() -> hdmi_intrinsic_event() -> check_presence_and_report() -> -hdmi_present_sense() -> hdmi_prepsent_sense_via_verbs() -Use directly snd_jack_report() on spec->pcm_rec[pcm_idx].jack for dyn_pcm_assign. -Use hda_jack mechanism to handle jack events. - - -Others to be added later -======================== diff --git a/Documentation/sound/hd-audio/dp-mst.rst b/Documentation/sound/hd-audio/dp-mst.rst new file mode 100644 index 000000000000..58b72437e6c3 --- /dev/null +++ b/Documentation/sound/hd-audio/dp-mst.rst @@ -0,0 +1,84 @@ +======================= +HD-Audio DP-MST Support +======================= + +To support DP MST audio, HD Audio hdmi codec driver introduces virtual pin +and dynamic pcm assignment. + +Virtual pin is an extension of per_pin. The most difference of DP MST +from legacy is that DP MST introduces device entry. Each pin can contain +several device entries. Each device entry behaves as a pin. + +As each pin may contain several device entries and each codec may contain +several pins, if we use one pcm per per_pin, there will be many PCMs. +The new solution is to create a few PCMs and to dynamically bind pcm to +per_pin. Driver uses spec->dyn_pcm_assign flag to indicate whether to use +the new solution. + +PCM +=== +To be added + + +Jack +==== + +Presume: + - MST must be dyn_pcm_assign, and it is acomp (for Intel scenario); + - NON-MST may or may not be dyn_pcm_assign, it can be acomp or !acomp; + +So there are the following scenarios: + a. MST (&& dyn_pcm_assign && acomp) + b. NON-MST && dyn_pcm_assign && acomp + c. NON-MST && !dyn_pcm_assign && !acomp + +Below discussion will ignore MST and NON-MST difference as it doesn't +impact on jack handling too much. + +Driver uses struct hdmi_pcm pcm[] array in hdmi_spec and snd_jack is +a member of hdmi_pcm. Each pin has one struct hdmi_pcm * pcm pointer. + +For !dyn_pcm_assign, per_pin->pcm will assigned to spec->pcm[n] statically. + +For dyn_pcm_assign, per_pin->pcm will assigned to spec->pcm[n] +when monitor is hotplugged. + + +Build Jack +---------- + +- dyn_pcm_assign + + Will not use hda_jack but use snd_jack in spec->pcm_rec[pcm_idx].jack directly. + +- !dyn_pcm_assign + + Use hda_jack and assign spec->pcm_rec[pcm_idx].jack = jack->jack statically. + + +Unsolicited Event Enabling +-------------------------- +Enable unsolicited event if !acomp. + + +Monitor Hotplug Event Handling +------------------------------ +- acomp + + pin_eld_notify() -> check_presence_and_report() -> hdmi_present_sense() -> + sync_eld_via_acomp(). + + Use directly snd_jack_report() on spec->pcm_rec[pcm_idx].jack for + both dyn_pcm_assign and !dyn_pcm_assign + +- !acomp + + hdmi_unsol_event() -> hdmi_intrinsic_event() -> check_presence_and_report() -> + hdmi_present_sense() -> hdmi_prepsent_sense_via_verbs() + + Use directly snd_jack_report() on spec->pcm_rec[pcm_idx].jack for dyn_pcm_assign. + Use hda_jack mechanism to handle jack events. + + +Others to be added later +======================== diff --git a/Documentation/sound/hd-audio/index.rst b/Documentation/sound/hd-audio/index.rst index c6efd55a219f..f8a72ffffe66 100644 --- a/Documentation/sound/hd-audio/index.rst +++ b/Documentation/sound/hd-audio/index.rst @@ -7,3 +7,4 @@ HD-Audio notes models controls + dp-mst -- cgit v1.2.3 From f6d23df5cac135e7375f14557b2da959405480b6 Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 15:40:00 +0100 Subject: ALSA: doc: ReSTize ALSA-Configuration document A simple conversion from the text file. Since this is the only document specific to the configurations, it's put to the root sound subdirectory. A section describing the obsoleted configure stuff of old alsa-driver tarball got removed. Signed-off-by: Takashi Iwai --- Documentation/sound/alsa-configuration.rst | 2683 +++++++++++++++++++++++ Documentation/sound/alsa/ALSA-Configuration.txt | 2330 -------------------- Documentation/sound/index.rst | 1 + 3 files changed, 2684 insertions(+), 2330 deletions(-) create mode 100644 Documentation/sound/alsa-configuration.rst delete mode 100644 Documentation/sound/alsa/ALSA-Configuration.txt diff --git a/Documentation/sound/alsa-configuration.rst b/Documentation/sound/alsa-configuration.rst new file mode 100644 index 000000000000..aed6b4fb8e46 --- /dev/null +++ b/Documentation/sound/alsa-configuration.rst @@ -0,0 +1,2683 @@ +============================================================== +Advanced Linux Sound Architecture - Driver Configuration guide +============================================================== + + +Kernel Configuration +==================== + +To enable ALSA support you need at least to build the kernel with +primary sound card support (``CONFIG_SOUND``). Since ALSA can emulate +OSS, you don't have to choose any of the OSS modules. + +Enable "OSS API emulation" (``CONFIG_SND_OSSEMUL``) and both OSS mixer +and PCM supports if you want to run OSS applications with ALSA. + +If you want to support the WaveTable functionality on cards such as +SB Live! then you need to enable "Sequencer support" +(``CONFIG_SND_SEQUENCER``). + +To make ALSA debug messages more verbose, enable the "Verbose printk" +and "Debug" options. To check for memory leaks, turn on "Debug memory" +too. "Debug detection" will add checks for the detection of cards. + +Please note that all the ALSA ISA drivers support the Linux isapnp API +(if the card supports ISA PnP). You don't need to configure the cards +using isapnptools. + + +Module parameters +================= + +The user can load modules with options. If the module supports more than +one card and you have more than one card of the same type then you can +specify multiple values for the option separated by commas. + + +Module snd +---------- + +The core ALSA module. It is used by all ALSA card drivers. +It takes the following options which have global effects. + +major + major number for sound driver; + Default: 116 +cards_limit + limiting card index for auto-loading (1-8); + Default: 1; + For auto-loading more than one card, specify this option + together with snd-card-X aliases. +slots + Reserve the slot index for the given driver; + This option takes multiple strings. + See `Module Autoloading Support`_ section for details. +debug + Specifies the debug message level; + (0 = disable debug prints, 1 = normal debug messages, + 2 = verbose debug messages); + This option appears only when ``CONFIG_SND_DEBUG=y``. + This option can be dynamically changed via sysfs + /sys/modules/snd/parameters/debug file. + +Module snd-pcm-oss +------------------ + +The PCM OSS emulation module. +This module takes options which change the mapping of devices. + +dsp_map + PCM device number maps assigned to the 1st OSS device; + Default: 0 +adsp_map + PCM device number maps assigned to the 2st OSS device; + Default: 1 +nonblock_open + Don't block opening busy PCM devices; + Default: 1 + +For example, when ``dsp_map=2``, /dev/dsp will be mapped to PCM #2 of +the card #0. Similarly, when ``adsp_map=0``, /dev/adsp will be mapped +to PCM #0 of the card #0. +For changing the second or later card, specify the option with +commas, such like ``dsp_map=0,1``. + +``nonblock_open`` option is used to change the behavior of the PCM +regarding opening the device. When this option is non-zero, +opening a busy OSS PCM device won't be blocked but return +immediately with EAGAIN (just like O_NONBLOCK flag). + +Module snd-rawmidi +------------------ + +This module takes options which change the mapping of devices. +similar to those of the snd-pcm-oss module. + +midi_map + MIDI device number maps assigned to the 1st OSS device; + Default: 0 +amidi_map + MIDI device number maps assigned to the 2st OSS device; + Default: 1 + +Common parameters for top sound card modules +-------------------------------------------- + +Each of top level sound card module takes the following options. + +index + index (slot #) of sound card; + Values: 0 through 31 or negative; + If nonnegative, assign that index number; + if negative, interpret as a bitmask of permissible indices; + the first free permitted index is assigned; + Default: -1 +id + card ID (identifier or name); + Can be up to 15 characters long; + Default: the card type; + A directory by this name is created under /proc/asound/ + containing information about the card; + This ID can be used instead of the index number in + identifying the card +enable + enable card; + Default: enabled, for PCI and ISA PnP cards + +Module snd-adlib +---------------- + +Module for AdLib FM cards. + +port + port # for OPL chip + +This module supports multiple cards. It does not support autoprobe, so +the port must be specified. For actual AdLib FM cards it will be 0x388. +Note that this card does not have PCM support and no mixer; only FM +synthesis. + +Make sure you have ``sbiload`` from the alsa-tools package available and, +after loading the module, find out the assigned ALSA sequencer port +number through ``sbiload -l``. + +Example output: +:: + + Port Client name Port name + 64:0 OPL2 FM synth OPL2 FM Port + +Load the ``std.sb`` and ``drums.sb`` patches also supplied by ``sbiload``: +:: + + sbiload -p 64:0 std.sb drums.sb + +If you use this driver to drive an OPL3, you can use ``std.o3`` and ``drums.o3`` +instead. To have the card produce sound, use ``aplaymidi`` from alsa-utils: +:: + + aplaymidi -p 64:0 foo.mid + +Module snd-ad1816a +------------------ + +Module for sound cards based on Analog Devices AD1816A/AD1815 ISA chips. + +clockfreq + Clock frequency for AD1816A chip (default = 0, 33000Hz) + +This module supports multiple cards, autoprobe and PnP. + +Module snd-ad1848 +----------------- + +Module for sound cards based on AD1848/AD1847/CS4248 ISA chips. + +port + port # for AD1848 chip +irq + IRQ # for AD1848 chip +dma1 + DMA # for AD1848 chip (0,1,3) + +This module supports multiple cards. It does not support autoprobe +thus main port must be specified!!! Other ports are optional. + +The power-management is supported. + +Module snd-ad1889 +----------------- + +Module for Analog Devices AD1889 chips. + +ac97_quirk + AC'97 workaround for strange hardware; + See the description of intel8x0 module for details. + +This module supports multiple cards. + +Module snd-ali5451 +------------------ + +Module for ALi M5451 PCI chip. + +pcm_channels + Number of hardware channels assigned for PCM +spdif + Support SPDIF I/O; + Default: disabled + +This module supports one chip and autoprobe. + +The power-management is supported. + +Module snd-als100 +----------------- + +Module for sound cards based on Avance Logic ALS100/ALS120 ISA chips. + +This module supports multiple cards, autoprobe and PnP. + +The power-management is supported. + +Module snd-als300 +----------------- + +Module for Avance Logic ALS300 and ALS300+ + +This module supports multiple cards. + +The power-management is supported. + +Module snd-als4000 +------------------ + +Module for sound cards based on Avance Logic ALS4000 PCI chip. + +joystick_port + port # for legacy joystick support; + 0 = disabled (default), 1 = auto-detect + +This module supports multiple cards, autoprobe and PnP. + +The power-management is supported. + +Module snd-asihpi +----------------- + +Module for AudioScience ASI soundcards + +enable_hpi_hwdep + enable HPI hwdep for AudioScience soundcard + +This module supports multiple cards. +The driver requires the firmware loader support on kernel. + +Module snd-atiixp +----------------- + +Module for ATI IXP 150/200/250/400 AC97 controllers. + +ac97_clock + AC'97 clock (default = 48000) +ac97_quirk + AC'97 workaround for strange hardware; + See `AC97 Quirk Option`_ section below. +ac97_codec + Workaround to specify which AC'97 codec instead of probing. + If this works for you file a bug with your `lspci -vn` output. + (-2 = Force probing, -1 = Default behavior, 0-2 = Use the + specified codec.) +spdif_aclink + S/PDIF transfer over AC-link (default = 1) + +This module supports one card and autoprobe. + +ATI IXP has two different methods to control SPDIF output. One is +over AC-link and another is over the "direct" SPDIF output. The +implementation depends on the motherboard, and you'll need to +choose the correct one via spdif_aclink module option. + +The power-management is supported. + +Module snd-atiixp-modem +----------------------- + +Module for ATI IXP 150/200/250 AC97 modem controllers. + +This module supports one card and autoprobe. + +Note: The default index value of this module is -2, i.e. the first +slot is excluded. + +The power-management is supported. + +Module snd-au8810, snd-au8820, snd-au8830 +----------------------------------------- + +Module for Aureal Vortex, Vortex2 and Advantage device. + +pcifix + Control PCI workarounds; + 0 = Disable all workarounds, + 1 = Force the PCI latency of the Aureal card to 0xff, + 2 = Force the Extend PCI#2 Internal Master for Efficient + Handling of Dummy Requests on the VIA KT133 AGP Bridge, + 3 = Force both settings, + 255 = Autodetect what is required (default) + +This module supports all ADB PCM channels, ac97 mixer, SPDIF, hardware +EQ, mpu401, gameport. A3D and wavetable support are still in development. +Development and reverse engineering work is being coordinated at +http://savannah.nongnu.org/projects/openvortex/ +SPDIF output has a copy of the AC97 codec output, unless you use the +``spdif`` pcm device, which allows raw data passthru. +The hardware EQ hardware and SPDIF is only present in the Vortex2 and +Advantage. + +Note: Some ALSA mixer applications don't handle the SPDIF sample rate +control correctly. If you have problems regarding this, try +another ALSA compliant mixer (alsamixer works). + +Module snd-azt1605 +------------------ + +Module for Aztech Sound Galaxy soundcards based on the Aztech AZT1605 +chipset. + +port + port # for BASE (0x220,0x240,0x260,0x280) +wss_port + port # for WSS (0x530,0x604,0xe80,0xf40) +irq + IRQ # for WSS (7,9,10,11) +dma1 + DMA # for WSS playback (0,1,3) +dma2 + DMA # for WSS capture (0,1), -1 = disabled (default) +mpu_port + port # for MPU-401 UART (0x300,0x330), -1 = disabled (default) +mpu_irq + IRQ # for MPU-401 UART (3,5,7,9), -1 = disabled (default) +fm_port + port # for OPL3 (0x388), -1 = disabled (default) + +This module supports multiple cards. It does not support autoprobe: +``port``, ``wss_port``, ``irq`` and ``dma1`` have to be specified. +The other values are optional. + +``port`` needs to match the BASE ADDRESS jumper on the card (0x220 or 0x240) +or the value stored in the card's EEPROM for cards that have an EEPROM and +their "CONFIG MODE" jumper set to "EEPROM SETTING". The other values can +be chosen freely from the options enumerated above. + +If ``dma2`` is specified and different from ``dma1``, the card will operate in +full-duplex mode. When ``dma1=3``, only ``dma2=0`` is valid and the only way to +enable capture since only channels 0 and 1 are available for capture. + +Generic settings are ``port=0x220 wss_port=0x530 irq=10 dma1=1 dma2=0 +mpu_port=0x330 mpu_irq=9 fm_port=0x388``. + +Whatever IRQ and DMA channels you pick, be sure to reserve them for +legacy ISA in your BIOS. + +Module snd-azt2316 +------------------ + +Module for Aztech Sound Galaxy soundcards based on the Aztech AZT2316 +chipset. + +port + port # for BASE (0x220,0x240,0x260,0x280) +wss_port + port # for WSS (0x530,0x604,0xe80,0xf40) +irq + IRQ # for WSS (7,9,10,11) +dma1 + DMA # for WSS playback (0,1,3) +dma2 + DMA # for WSS capture (0,1), -1 = disabled (default) +mpu_port + port # for MPU-401 UART (0x300,0x330), -1 = disabled (default) +mpu_irq + IRQ # for MPU-401 UART (5,7,9,10), -1 = disabled (default) +fm_port + port # for OPL3 (0x388), -1 = disabled (default) + +This module supports multiple cards. It does not support autoprobe: +``port``, ``wss_port``, ``irq`` and ``dma1`` have to be specified. +The other values are optional. + +``port`` needs to match the BASE ADDRESS jumper on the card (0x220 or 0x240) +or the value stored in the card's EEPROM for cards that have an EEPROM and +their "CONFIG MODE" jumper set to "EEPROM SETTING". The other values can +be chosen freely from the options enumerated above. + +If ``dma2`` is specified and different from ``dma1``, the card will operate in +full-duplex mode. When ``dma1=3``, only ``dma2=0`` is valid and the only way to +enable capture since only channels 0 and 1 are available for capture. + +Generic settings are ``port=0x220 wss_port=0x530 irq=10 dma1=1 dma2=0 +mpu_port=0x330 mpu_irq=9 fm_port=0x388``. + +Whatever IRQ and DMA channels you pick, be sure to reserve them for +legacy ISA in your BIOS. + +Module snd-aw2 +-------------- + +Module for Audiowerk2 sound card + +This module supports multiple cards. + +Module snd-azt2320 +------------------ + +Module for sound cards based on Aztech System AZT2320 ISA chip (PnP only). + +This module supports multiple cards, PnP and autoprobe. + +The power-management is supported. + +Module snd-azt3328 +------------------ + +Module for sound cards based on Aztech AZF3328 PCI chip. + +joystick + Enable joystick (default off) + +This module supports multiple cards. + +Module snd-bt87x +---------------- + +Module for video cards based on Bt87x chips. + +digital_rate + Override the default digital rate (Hz) +load_all + Load the driver even if the card model isn't known + +This module supports multiple cards. + +Note: The default index value of this module is -2, i.e. the first +slot is excluded. + +Module snd-ca0106 +----------------- + +Module for Creative Audigy LS and SB Live 24bit + +This module supports multiple cards. + + +Module snd-cmi8330 +------------------ + +Module for sound cards based on C-Media CMI8330 ISA chips. + +isapnp + ISA PnP detection - 0 = disable, 1 = enable (default) + +with ``isapnp=0``, the following options are available: + +wssport + port # for CMI8330 chip (WSS) +wssirq + IRQ # for CMI8330 chip (WSS) +wssdma + first DMA # for CMI8330 chip (WSS) +sbport + port # for CMI8330 chip (SB16) +sbirq + IRQ # for CMI8330 chip (SB16) +sbdma8 + 8bit DMA # for CMI8330 chip (SB16) +sbdma16 + 16bit DMA # for CMI8330 chip (SB16) +fmport + (optional) OPL3 I/O port +mpuport + (optional) MPU401 I/O port +mpuirq + (optional) MPU401 irq # + +This module supports multiple cards and autoprobe. + +The power-management is supported. + +Module snd-cmipci +----------------- + +Module for C-Media CMI8338/8738/8768/8770 PCI sound cards. + +mpu_port + port address of MIDI interface (8338 only): + 0x300,0x310,0x320,0x330 = legacy port, + 0 = disable (default) +fm_port + port address of OPL-3 FM synthesizer (8x38 only): + 0x388 = legacy port, + 1 = integrated PCI port (default on 8738), + 0 = disable +soft_ac3 + Software-conversion of raw SPDIF packets (model 033 only) (default = 1) +joystick_port + Joystick port address (0 = disable, 1 = auto-detect) + +This module supports autoprobe and multiple cards. + +The power-management is supported. + +Module snd-cs4231 +----------------- + +Module for sound cards based on CS4231 ISA chips. + +port + port # for CS4231 chip +mpu_port + port # for MPU-401 UART (optional), -1 = disable +irq + IRQ # for CS4231 chip +mpu_irq + IRQ # for MPU-401 UART +dma1 + first DMA # for CS4231 chip +dma2 + second DMA # for CS4231 chip + +This module supports multiple cards. This module does not support autoprobe +thus main port must be specified!!! Other ports are optional. + +The power-management is supported. + +Module snd-cs4236 +----------------- + +Module for sound cards based on CS4232/CS4232A, +CS4235/CS4236/CS4236B/CS4237B/CS4238B/CS4239 ISA chips. + +isapnp + ISA PnP detection - 0 = disable, 1 = enable (default) + +with ``isapnp=0``, the following options are available: + +port + port # for CS4236 chip (PnP setup - 0x534) +cport + control port # for CS4236 chip (PnP setup - 0x120,0x210,0xf00) +mpu_port + port # for MPU-401 UART (PnP setup - 0x300), -1 = disable +fm_port + FM port # for CS4236 chip (PnP setup - 0x388), -1 = disable +irq + IRQ # for CS4236 chip (5,7,9,11,12,15) +mpu_irq + IRQ # for MPU-401 UART (9,11,12,15) +dma1 + first DMA # for CS4236 chip (0,1,3) +dma2 + second DMA # for CS4236 chip (0,1,3), -1 = disable + +This module supports multiple cards. This module does not support autoprobe +(if ISA PnP is not used) thus main port and control port must be +specified!!! Other ports are optional. + +The power-management is supported. + +This module is aliased as snd-cs4232 since it provides the old +snd-cs4232 functionality, too. + +Module snd-cs4281 +----------------- + +Module for Cirrus Logic CS4281 soundchip. + +dual_codec + Secondary codec ID (0 = disable, default) + +This module supports multiple cards. + +The power-management is supported. + +Module snd-cs46xx +----------------- + +Module for PCI sound cards based on CS4610/CS4612/CS4614/CS4615/CS4622/ +CS4624/CS4630/CS4280 PCI chips. + +external_amp + Force to enable external amplifier. +thinkpad + Force to enable Thinkpad's CLKRUN control. +mmap_valid + Support OSS mmap mode (default = 0). + +This module supports multiple cards and autoprobe. +Usually external amp and CLKRUN controls are detected automatically +from PCI sub vendor/device ids. If they don't work, give the options +above explicitly. + +The power-management is supported. + +Module snd-cs5530 +----------------- + +Module for Cyrix/NatSemi Geode 5530 chip. + +Module snd-cs5535audio +---------------------- + +Module for multifunction CS5535 companion PCI device + +The power-management is supported. + +Module snd-ctxfi +---------------- + +Module for Creative Sound Blaster X-Fi boards (20k1 / 20k2 chips) + +* Creative Sound Blaster X-Fi Titanium Fatal1ty Champion Series +* Creative Sound Blaster X-Fi Titanium Fatal1ty Professional Series +* Creative Sound Blaster X-Fi Titanium Professional Audio +* Creative Sound Blaster X-Fi Titanium +* Creative Sound Blaster X-Fi Elite Pro +* Creative Sound Blaster X-Fi Platinum +* Creative Sound Blaster X-Fi Fatal1ty +* Creative Sound Blaster X-Fi XtremeGamer +* Creative Sound Blaster X-Fi XtremeMusic + +reference_rate + reference sample rate, 44100 or 48000 (default) +multiple + multiple to ref. sample rate, 1 or 2 (default) +subsystem + override the PCI SSID for probing; + the value consists of SSVID << 16 | SSDID. + The default is zero, which means no override. + +This module supports multiple cards. + +Module snd-darla20 +------------------ + +Module for Echoaudio Darla20 + +This module supports multiple cards. +The driver requires the firmware loader support on kernel. + +Module snd-darla24 +------------------ + +Module for Echoaudio Darla24 + +This module supports multiple cards. +The driver requires the firmware loader support on kernel. + +Module snd-dt019x +----------------- + +Module for Diamond Technologies DT-019X / Avance Logic ALS-007 (PnP +only) + +This module supports multiple cards. This module is enabled only with +ISA PnP support. + +The power-management is supported. + +Module snd-dummy +---------------- + +Module for the dummy sound card. This "card" doesn't do any output +or input, but you may use this module for any application which +requires a sound card (like RealPlayer). + +pcm_devs + Number of PCM devices assigned to each card (default = 1, up to 4) +pcm_substreams + Number of PCM substreams assigned to each PCM (default = 8, up to 128) +hrtimer + Use hrtimer (=1, default) or system timer (=0) +fake_buffer + Fake buffer allocations (default = 1) + +When multiple PCM devices are created, snd-dummy gives different +behavior to each PCM device: +* 0 = interleaved with mmap support +* 1 = non-interleaved with mmap support +* 2 = interleaved without mmap +* 3 = non-interleaved without mmap + +As default, snd-dummy drivers doesn't allocate the real buffers +but either ignores read/write or mmap a single dummy page to all +buffer pages, in order to save the resources. If your apps need +the read/ written buffer data to be consistent, pass fake_buffer=0 +option. + +The power-management is supported. + +Module snd-echo3g +----------------- + +Module for Echoaudio 3G cards (Gina3G/Layla3G) + +This module supports multiple cards. +The driver requires the firmware loader support on kernel. + +Module snd-emu10k1 +------------------ + +Module for EMU10K1/EMU10k2 based PCI sound cards. + +* Sound Blaster Live! +* Sound Blaster PCI 512 +* Emu APS (partially supported) +* Sound Blaster Audigy + +extin + bitmap of available external inputs for FX8010 (see bellow) +extout + bitmap of available external outputs for FX8010 (see bellow) +seq_ports + allocated sequencer ports (4 by default) +max_synth_voices + limit of voices used for wavetable (64 by default) +max_buffer_size + specifies the maximum size of wavetable/pcm buffers given in MB + unit. Default value is 128. +enable_ir + enable IR + +This module supports multiple cards and autoprobe. + +Input & Output configurations [extin/extout] +* Creative Card wo/Digital out [0x0003/0x1f03] +* Creative Card w/Digital out [0x0003/0x1f0f] +* Creative Card w/Digital CD in [0x000f/0x1f0f] +* Creative Card wo/Digital out + LiveDrive [0x3fc3/0x1fc3] +* Creative Card w/Digital out + LiveDrive [0x3fc3/0x1fcf] +* Creative Card w/Digital CD in + LiveDrive [0x3fcf/0x1fcf] +* Creative Card wo/Digital out + Digital I/O 2 [0x0fc3/0x1f0f] +* Creative Card w/Digital out + Digital I/O 2 [0x0fc3/0x1f0f] +* Creative Card w/Digital CD in + Digital I/O 2 [0x0fcf/0x1f0f] +* Creative Card 5.1/w Digital out + LiveDrive [0x3fc3/0x1fff] +* Creative Card 5.1 (c) 2003 [0x3fc3/0x7cff] +* Creative Card all ins and outs [0x3fff/0x7fff] + +The power-management is supported. + +Module snd-emu10k1x +------------------- + +Module for Creative Emu10k1X (SB Live Dell OEM version) + +This module supports multiple cards. + +Module snd-ens1370 +------------------ + +Module for Ensoniq AudioPCI ES1370 PCI sound cards. + +* SoundBlaster PCI 64 +* SoundBlaster PCI 128 + +joystick + Enable joystick (default off) + +This module supports multiple cards and autoprobe. + +The power-management is supported. + +Module snd-ens1371 +------------------ + +Module for Ensoniq AudioPCI ES1371 PCI sound cards. + +* SoundBlaster PCI 64 +* SoundBlaster PCI 128 +* SoundBlaster Vibra PCI + +joystick_port + port # for joystick (0x200,0x208,0x210,0x218), 0 = disable + (default), 1 = auto-detect + +This module supports multiple cards and autoprobe. + +The power-management is supported. + +Module snd-es1688 +----------------- + +Module for ESS AudioDrive ES-1688 and ES-688 sound cards. + +isapnp + ISA PnP detection - 0 = disable, 1 = enable (default) +mpu_port + port # for MPU-401 port (0x300,0x310,0x320,0x330), -1 = disable (default) +mpu_irq + IRQ # for MPU-401 port (5,7,9,10) +fm_port + port # for OPL3 (option; share the same port as default) + +with ``isapnp=0``, the following additional options are available: + +port + port # for ES-1688 chip (0x220,0x240,0x260) +irq + IRQ # for ES-1688 chip (5,7,9,10) +dma8 + DMA # for ES-1688 chip (0,1,3) + +This module supports multiple cards and autoprobe (without MPU-401 port) +and PnP with the ES968 chip. + +Module snd-es18xx +----------------- + +Module for ESS AudioDrive ES-18xx sound cards. + +isapnp + ISA PnP detection - 0 = disable, 1 = enable (default) + +with ``isapnp=0``, the following options are available: + +port + port # for ES-18xx chip (0x220,0x240,0x260) +mpu_port + port # for MPU-401 port (0x300,0x310,0x320,0x330), -1 = disable (default) +fm_port + port # for FM (optional, not used) +irq + IRQ # for ES-18xx chip (5,7,9,10) +dma1 + first DMA # for ES-18xx chip (0,1,3) +dma2 + first DMA # for ES-18xx chip (0,1,3) + +This module supports multiple cards, ISA PnP and autoprobe (without MPU-401 +port if native ISA PnP routines are not used). +When ``dma2`` is equal with ``dma1``, the driver works as half-duplex. + +The power-management is supported. + +Module snd-es1938 +----------------- + +Module for sound cards based on ESS Solo-1 (ES1938,ES1946) chips. + +This module supports multiple cards and autoprobe. + +The power-management is supported. + +Module snd-es1968 +----------------- + +Module for sound cards based on ESS Maestro-1/2/2E (ES1968/ES1978) chips. + +total_bufsize + total buffer size in kB (1-4096kB) +pcm_substreams_p + playback channels (1-8, default=2) +pcm_substreams_c + capture channels (1-8, default=0) +clock + clock (0 = auto-detection) +use_pm + support the power-management (0 = off, 1 = on, 2 = auto (default)) +enable_mpu + enable MPU401 (0 = off, 1 = on, 2 = auto (default)) +joystick + enable joystick (default off) + +This module supports multiple cards and autoprobe. + +The power-management is supported. + +Module snd-fm801 +---------------- + +Module for ForteMedia FM801 based PCI sound cards. + +tea575x_tuner + Enable TEA575x tuner; + 1 = MediaForte 256-PCS, + 2 = MediaForte 256-PCPR, + 3 = MediaForte 64-PCR + High 16-bits are video (radio) device number + 1; + example: 0x10002 (MediaForte 256-PCPR, device 1) + +This module supports multiple cards and autoprobe. + +The power-management is supported. + +Module snd-gina20 +----------------- + +Module for Echoaudio Gina20 + +This module supports multiple cards. +The driver requires the firmware loader support on kernel. + +Module snd-gina24 +----------------- + +Module for Echoaudio Gina24 + +This module supports multiple cards. +The driver requires the firmware loader support on kernel. + +Module snd-gusclassic +--------------------- + +Module for Gravis UltraSound Classic sound card. + +port + port # for GF1 chip (0x220,0x230,0x240,0x250,0x260) +irq + IRQ # for GF1 chip (3,5,9,11,12,15) +dma1 + DMA # for GF1 chip (1,3,5,6,7) +dma2 + DMA # for GF1 chip (1,3,5,6,7,-1=disable) +joystick_dac + 0 to 31, (0.59V-4.52V or 0.389V-2.98V) +voices + GF1 voices limit (14-32) +pcm_voices + reserved PCM voices + +This module supports multiple cards and autoprobe. + +Module snd-gusextreme +--------------------- + +Module for Gravis UltraSound Extreme (Synergy ViperMax) sound card. + +port + port # for ES-1688 chip (0x220,0x230,0x240,0x250,0x260) +gf1_port + port # for GF1 chip (0x210,0x220,0x230,0x240,0x250,0x260,0x270) +mpu_port + port # for MPU-401 port (0x300,0x310,0x320,0x330), -1 = disable +irq + IRQ # for ES-1688 chip (5,7,9,10) +gf1_irq + IRQ # for GF1 chip (3,5,9,11,12,15) +mpu_irq + IRQ # for MPU-401 port (5,7,9,10) +dma8 + DMA # for ES-1688 chip (0,1,3) +dma1 + DMA # for GF1 chip (1,3,5,6,7) +joystick_dac + 0 to 31, (0.59V-4.52V or 0.389V-2.98V) +voices + GF1 voices limit (14-32) +pcm_voices + reserved PCM voices + +This module supports multiple cards and autoprobe (without MPU-401 port). + +Module snd-gusmax +----------------- + +Module for Gravis UltraSound MAX sound card. + +port + port # for GF1 chip (0x220,0x230,0x240,0x250,0x260) +irq + IRQ # for GF1 chip (3,5,9,11,12,15) +dma1 + DMA # for GF1 chip (1,3,5,6,7) +dma2 + DMA # for GF1 chip (1,3,5,6,7,-1=disable) +joystick_dac + 0 to 31, (0.59V-4.52V or 0.389V-2.98V) +voices + GF1 voices limit (14-32) +pcm_voices + reserved PCM voices + +This module supports multiple cards and autoprobe. + +Module snd-hda-intel +-------------------- + +Module for Intel HD Audio (ICH6, ICH6M, ESB2, ICH7, ICH8, ICH9, ICH10, +PCH, SCH), ATI SB450, SB600, R600, RS600, RS690, RS780, RV610, RV620, +RV630, RV635, RV670, RV770, VIA VT8251/VT8237A, SIS966, ULI M5461 + +[Multiple options for each card instance] + +model + force the model name +position_fix + Fix DMA pointer; + -1 = system default: choose appropriate one per controller hardware, + 0 = auto: falls back to LPIB when POSBUF doesn't work, + 1 = use LPIB, + 2 = POSBUF: use position buffer, + 3 = VIACOMBO: VIA-specific workaround for capture, + 4 = COMBO: use LPIB for playback, auto for capture stream +probe_mask + Bitmask to probe codecs (default = -1, meaning all slots); + When the bit 8 (0x100) is set, the lower 8 bits are used + as the "fixed" codec slots; i.e. the driver probes the + slots regardless what hardware reports back +probe_only + Only probing and no codec initialization (default=off); + Useful to check the initial codec status for debugging +bdl_pos_adj + Specifies the DMA IRQ timing delay in samples. + Passing -1 will make the driver to choose the appropriate + value based on the controller chip. +patch + Specifies the early "patch" files to modify the HD-audio setup + before initializing the codecs. + This option is available only when ``CONFIG_SND_HDA_PATCH_LOADER=y`` + is set. See hd-audio/notes.rst for details. +beep_mode + Selects the beep registration mode (0=off, 1=on); + default value is set via ``CONFIG_SND_HDA_INPUT_BEEP_MODE`` kconfig. + +[Single (global) options] + +single_cmd + Use single immediate commands to communicate with codecs + (for debugging only) +enable_msi + Enable Message Signaled Interrupt (MSI) (default = off) +power_save + Automatic power-saving timeout (in second, 0 = disable) +power_save_controller + Reset HD-audio controller in power-saving mode (default = on) +align_buffer_size + Force rounding of buffer/period sizes to multiples of 128 bytes. + This is more efficient in terms of memory access but isn't + required by the HDA spec and prevents users from specifying + exact period/buffer sizes. (default = on) +snoop + Enable/disable snooping (default = on) + +This module supports multiple cards and autoprobe. + +See hd-audio/notes.rst for more details about HD-audio driver. + +Each codec may have a model table for different configurations. +If your machine isn't listed there, the default (usually minimal) +configuration is set up. You can pass ``model=`` option to +specify a certain model in such a case. There are different +models depending on the codec chip. The list of available models +is found in hd-audio/models.rst. + +The model name ``generic`` is treated as a special case. When this +model is given, the driver uses the generic codec parser without +"codec-patch". It's sometimes good for testing and debugging. + +If the default configuration doesn't work and one of the above +matches with your device, report it together with alsa-info.sh +output (with ``--no-upload`` option) to kernel bugzilla or alsa-devel +ML (see the section `Links and Addresses`_). + +``power_save`` and ``power_save_controller`` options are for power-saving +mode. See powersave.txt for details. + +Note 2: If you get click noises on output, try the module option +``position_fix=1`` or ``2``. ``position_fix=1`` will use the SD_LPIB +register value without FIFO size correction as the current +DMA pointer. ``position_fix=2`` will make the driver to use +the position buffer instead of reading SD_LPIB register. +(Usually SD_LPIB register is more accurate than the +position buffer.) + +``position_fix=3`` is specific to VIA devices. The position +of the capture stream is checked from both LPIB and POSBUF +values. ``position_fix=4`` is a combination mode, using LPIB +for playback and POSBUF for capture. + +NB: If you get many ``azx_get_response timeout`` messages at +loading, it's likely a problem of interrupts (e.g. ACPI irq +routing). Try to boot with options like ``pci=noacpi``. Also, you +can try ``single_cmd=1`` module option. This will switch the +communication method between HDA controller and codecs to the +single immediate commands instead of CORB/RIRB. Basically, the +single command mode is provided only for BIOS, and you won't get +unsolicited events, too. But, at least, this works independently +from the irq. Remember this is a last resort, and should be +avoided as much as possible... + +MORE NOTES ON ``azx_get_response timeout`` PROBLEMS: +On some hardware, you may need to add a proper probe_mask option +to avoid the ``azx_get_response timeout`` problem above, instead. +This occurs when the access to non-existing or non-working codec slot +(likely a modem one) causes a stall of the communication via HD-audio +bus. You can see which codec slots are probed by enabling +``CONFIG_SND_DEBUG_VERBOSE``, or simply from the file name of the codec +proc files. Then limit the slots to probe by probe_mask option. +For example, ``probe_mask=1`` means to probe only the first slot, and +``probe_mask=4`` means only the third slot. + +The power-management is supported. + +Module snd-hdsp +--------------- + +Module for RME Hammerfall DSP audio interface(s) + +This module supports multiple cards. + +Note: The firmware data can be automatically loaded via hotplug +when ``CONFIG_FW_LOADER`` is set. Otherwise, you need to load +the firmware via hdsploader utility included in alsa-tools +package. +The firmware data is found in alsa-firmware package. + +Note: snd-page-alloc module does the job which snd-hammerfall-mem +module did formerly. It will allocate the buffers in advance +when any HDSP cards are found. To make the buffer +allocation sure, load snd-page-alloc module in the early +stage of boot sequence. See `Early Buffer Allocation`_ +section. + +Module snd-hdspm +---------------- + +Module for RME HDSP MADI board. + +precise_ptr + Enable precise pointer, or disable. +line_outs_monitor + Send playback streams to analog outs by default. +enable_monitor + Enable Analog Out on Channel 63/64 by default. + +See hdspm.txt for details. + +Module snd-ice1712 +------------------ + +Module for Envy24 (ICE1712) based PCI sound cards. + +* MidiMan M Audio Delta 1010 +* MidiMan M Audio Delta 1010LT +* MidiMan M Audio Delta DiO 2496 +* MidiMan M Audio Delta 66 +* MidiMan M Audio Delta 44 +* MidiMan M Audio Delta 410 +* MidiMan M Audio Audiophile 2496 +* TerraTec EWS 88MT +* TerraTec EWS 88D +* TerraTec EWX 24/96 +* TerraTec DMX 6Fire +* TerraTec Phase 88 +* Hoontech SoundTrack DSP 24 +* Hoontech SoundTrack DSP 24 Value +* Hoontech SoundTrack DSP 24 Media 7.1 +* Event Electronics, EZ8 +* Digigram VX442 +* Lionstracs, Mediastaton +* Terrasoniq TS 88 + +model + Use the given board model, one of the following: + delta1010, dio2496, delta66, delta44, audiophile, delta410, + delta1010lt, vx442, ewx2496, ews88mt, ews88mt_new, ews88d, + dmx6fire, dsp24, dsp24_value, dsp24_71, ez8, + phase88, mediastation +omni + Omni I/O support for MidiMan M-Audio Delta44/66 +cs8427_timeout + reset timeout for the CS8427 chip (S/PDIF transceiver) in msec + resolution, default value is 500 (0.5 sec) + +This module supports multiple cards and autoprobe. +Note: The consumer part is not used with all Envy24 based cards (for +example in the MidiMan Delta siree). + +Note: The supported board is detected by reading EEPROM or PCI +SSID (if EEPROM isn't available). You can override the +model by passing ``model`` module option in case that the +driver isn't configured properly or you want to try another +type for testing. + +Module snd-ice1724 +------------------ + +Module for Envy24HT (VT/ICE1724), Envy24PT (VT1720) based PCI sound cards. + +* MidiMan M Audio Revolution 5.1 +* MidiMan M Audio Revolution 7.1 +* MidiMan M Audio Audiophile 192 +* AMP Ltd AUDIO2000 +* TerraTec Aureon 5.1 Sky +* TerraTec Aureon 7.1 Space +* TerraTec Aureon 7.1 Universe +* TerraTec Phase 22 +* TerraTec Phase 28 +* AudioTrak Prodigy 7.1 +* AudioTrak Prodigy 7.1 LT +* AudioTrak Prodigy 7.1 XT +* AudioTrak Prodigy 7.1 HIFI +* AudioTrak Prodigy 7.1 HD2 +* AudioTrak Prodigy 192 +* Pontis MS300 +* Albatron K8X800 Pro II +* Chaintech ZNF3-150 +* Chaintech ZNF3-250 +* Chaintech 9CJS +* Chaintech AV-710 +* Shuttle SN25P +* Onkyo SE-90PCI +* Onkyo SE-200PCI +* ESI Juli@ +* ESI Maya44 +* Hercules Fortissimo IV +* EGO-SYS WaveTerminal 192M + +model + Use the given board model, one of the following: + revo51, revo71, amp2000, prodigy71, prodigy71lt, + prodigy71xt, prodigy71hifi, prodigyhd2, prodigy192, + juli, aureon51, aureon71, universe, ap192, k8x800, + phase22, phase28, ms300, av710, se200pci, se90pci, + fortissimo4, sn25p, WT192M, maya44 + +This module supports multiple cards and autoprobe. + +Note: The supported board is detected by reading EEPROM or PCI +SSID (if EEPROM isn't available). You can override the +model by passing ``model`` module option in case that the +driver isn't configured properly or you want to try another +type for testing. + +Module snd-indigo +----------------- + +Module for Echoaudio Indigo + +This module supports multiple cards. +The driver requires the firmware loader support on kernel. + +Module snd-indigodj +------------------- + +Module for Echoaudio Indigo DJ + +This module supports multiple cards. +The driver requires the firmware loader support on kernel. + +Module snd-indigoio +------------------- + +Module for Echoaudio Indigo IO + +This module supports multiple cards. +The driver requires the firmware loader support on kernel. + +Module snd-intel8x0 +------------------- + +Module for AC'97 motherboards from Intel and compatibles. + +* Intel i810/810E, i815, i820, i830, i84x, MX440 ICH5, ICH6, ICH7, + 6300ESB, ESB2 +* SiS 7012 (SiS 735) +* NVidia NForce, NForce2, NForce3, MCP04, CK804 CK8, CK8S, MCP501 +* AMD AMD768, AMD8111 +* ALi m5455 + +ac97_clock + AC'97 codec clock base (0 = auto-detect) +ac97_quirk + AC'97 workaround for strange hardware; + See `AC97 Quirk Option`_ section below. +buggy_irq + Enable workaround for buggy interrupts on some motherboards + (default yes on nForce chips, otherwise off) +buggy_semaphore + Enable workaround for hardware with buggy semaphores (e.g. on some + ASUS laptops) (default off) +spdif_aclink + Use S/PDIF over AC-link instead of direct connection from the + controller chip (0 = off, 1 = on, -1 = default) + +This module supports one chip and autoprobe. + +Note: the latest driver supports auto-detection of chip clock. +if you still encounter too fast playback, specify the clock +explicitly via the module option ``ac97_clock=41194``. + +Joystick/MIDI ports are not supported by this driver. If your +motherboard has these devices, use the ns558 or snd-mpu401 +modules, respectively. + +The power-management is supported. + +Module snd-intel8x0m +-------------------- + +Module for Intel ICH (i8x0) chipset MC97 modems. + +* Intel i810/810E, i815, i820, i830, i84x, MX440 ICH5, ICH6, ICH7 +* SiS 7013 (SiS 735) +* NVidia NForce, NForce2, NForce2s, NForce3 +* AMD AMD8111 +* ALi m5455 + +ac97_clock + AC'97 codec clock base (0 = auto-detect) + +This module supports one card and autoprobe. + +Note: The default index value of this module is -2, i.e. the first +slot is excluded. + +The power-management is supported. + +Module snd-interwave +-------------------- + +Module for Gravis UltraSound PnP, Dynasonic 3-D/Pro, STB Sound Rage 32 +and other sound cards based on AMD InterWave (tm) chip. + +joystick_dac + 0 to 31, (0.59V-4.52V or 0.389V-2.98V) +midi + 1 = MIDI UART enable, 0 = MIDI UART disable (default) +pcm_voices + reserved PCM voices for the synthesizer (default 2) +effect + 1 = InterWave effects enable (default 0); requires 8 voices +isapnp + ISA PnP detection - 0 = disable, 1 = enable (default) + +with ``isapnp=0``, the following options are available: + +port + port # for InterWave chip (0x210,0x220,0x230,0x240,0x250,0x260) +irq + IRQ # for InterWave chip (3,5,9,11,12,15) +dma1 + DMA # for InterWave chip (0,1,3,5,6,7) +dma2 + DMA # for InterWave chip (0,1,3,5,6,7,-1=disable) + +This module supports multiple cards, autoprobe and ISA PnP. + +Module snd-interwave-stb +------------------------ + +Module for UltraSound 32-Pro (sound card from STB used by Compaq) +and other sound cards based on AMD InterWave (tm) chip with TEA6330T +circuit for extended control of bass, treble and master volume. + +joystick_dac + 0 to 31, (0.59V-4.52V or 0.389V-2.98V) +midi + 1 = MIDI UART enable, 0 = MIDI UART disable (default) +pcm_voices + reserved PCM voices for the synthesizer (default 2) +effect + 1 = InterWave effects enable (default 0); requires 8 voices +isapnp + ISA PnP detection - 0 = disable, 1 = enable (default) + +with ``isapnp=0``, the following options are available: + +port + port # for InterWave chip (0x210,0x220,0x230,0x240,0x250,0x260) +port_tc + tone control (i2c bus) port # for TEA6330T chip (0x350,0x360,0x370,0x380) +irq + IRQ # for InterWave chip (3,5,9,11,12,15) +dma1 + DMA # for InterWave chip (0,1,3,5,6,7) +dma2 + DMA # for InterWave chip (0,1,3,5,6,7,-1=disable) + +This module supports multiple cards, autoprobe and ISA PnP. + +Module snd-jazz16 +------------------- + +Module for Media Vision Jazz16 chipset. The chipset consists of 3 chips: +MVD1216 + MVA416 + MVA514. + +port + port # for SB DSP chip (0x210,0x220,0x230,0x240,0x250,0x260) +irq + IRQ # for SB DSP chip (3,5,7,9,10,15) +dma8 + DMA # for SB DSP chip (1,3) +dma16 + DMA # for SB DSP chip (5,7) +mpu_port + MPU-401 port # (0x300,0x310,0x320,0x330) +mpu_irq + MPU-401 irq # (2,3,5,7) + +This module supports multiple cards. + +Module snd-korg1212 +------------------- + +Module for Korg 1212 IO PCI card + +This module supports multiple cards. + +Module snd-layla20 +------------------ + +Module for Echoaudio Layla20 + +This module supports multiple cards. +The driver requires the firmware loader support on kernel. + +Module snd-layla24 +------------------ + +Module for Echoaudio Layla24 + +This module supports multiple cards. +The driver requires the firmware loader support on kernel. + +Module snd-lola +--------------- + +Module for Digigram Lola PCI-e boards + +This module supports multiple cards. + +Module snd-lx6464es +------------------- + +Module for Digigram LX6464ES boards + +This module supports multiple cards. + +Module snd-maestro3 +------------------- + +Module for Allegro/Maestro3 chips + +external_amp + enable external amp (enabled by default) +amp_gpio + GPIO pin number for external amp (0-15) or -1 for default pin (8 + for allegro, 1 for others) + +This module supports autoprobe and multiple chips. + +Note: the binding of amplifier is dependent on hardware. +If there is no sound even though all channels are unmuted, try to +specify other gpio connection via amp_gpio option. +For example, a Panasonic notebook might need ``amp_gpio=0x0d`` +option. + +The power-management is supported. + +Module snd-mia +--------------- + +Module for Echoaudio Mia + +This module supports multiple cards. +The driver requires the firmware loader support on kernel. + +Module snd-miro +--------------- + +Module for Miro soundcards: miroSOUND PCM 1 pro, miroSOUND PCM 12, +miroSOUND PCM 20 Radio. + +port + Port # (0x530,0x604,0xe80,0xf40) +irq + IRQ # (5,7,9,10,11) +dma1 + 1st dma # (0,1,3) +dma2 + 2nd dma # (0,1) +mpu_port + MPU-401 port # (0x300,0x310,0x320,0x330) +mpu_irq + MPU-401 irq # (5,7,9,10) +fm_port + FM Port # (0x388) +wss + enable WSS mode +ide + enable onboard ide support + +Module snd-mixart +----------------- + +Module for Digigram miXart8 sound cards. + +This module supports multiple cards. +Note: One miXart8 board will be represented as 4 alsa cards. +See MIXART.txt for details. + +When the driver is compiled as a module and the hotplug firmware +is supported, the firmware data is loaded via hotplug automatically. +Install the necessary firmware files in alsa-firmware package. +When no hotplug fw loader is available, you need to load the +firmware via mixartloader utility in alsa-tools package. + +Module snd-mona +--------------- + +Module for Echoaudio Mona + +This module supports multiple cards. +The driver requires the firmware loader support on kernel. + +Module snd-mpu401 +----------------- + +Module for MPU-401 UART devices. + +port + port number or -1 (disable) +irq + IRQ number or -1 (disable) +pnp + PnP detection - 0 = disable, 1 = enable (default) + +This module supports multiple devices and PnP. + +Module snd-msnd-classic +----------------------- + +Module for Turtle Beach MultiSound Classic, Tahiti or Monterey +soundcards. + +io + Port # for msnd-classic card +irq + IRQ # for msnd-classic card +mem + Memory address (0xb0000, 0xc8000, 0xd0000, 0xd8000, 0xe0000 or 0xe8000) +write_ndelay + enable write ndelay (default = 1) +calibrate_signal + calibrate signal (default = 0) +isapnp + ISA PnP detection - 0 = disable, 1 = enable (default) +digital + Digital daughterboard present (default = 0) +cfg + Config port (0x250, 0x260 or 0x270) default = PnP +reset + Reset all devices +mpu_io + MPU401 I/O port +mpu_irq + MPU401 irq# +ide_io0 + IDE port #0 +ide_io1 + IDE port #1 +ide_irq + IDE irq# +joystick_io + Joystick I/O port + +The driver requires firmware files ``turtlebeach/msndinit.bin`` and +``turtlebeach/msndperm.bin`` in the proper firmware directory. + +See Documentation/sound/oss/MultiSound for important information +about this driver. Note that it has been discontinued, but the +Voyetra Turtle Beach knowledge base entry for it is still available +at +http://www.turtlebeach.com + +Module snd-msnd-pinnacle +------------------------ + +Module for Turtle Beach MultiSound Pinnacle/Fiji soundcards. + +io + Port # for pinnacle/fiji card +irq + IRQ # for pinnalce/fiji card +mem + Memory address (0xb0000, 0xc8000, 0xd0000, 0xd8000, 0xe0000 or 0xe8000) +write_ndelay + enable write ndelay (default = 1) +calibrate_signal + calibrate signal (default = 0) +isapnp + ISA PnP detection - 0 = disable, 1 = enable (default) + +The driver requires firmware files ``turtlebeach/pndspini.bin`` and +``turtlebeach/pndsperm.bin`` in the proper firmware directory. + +Module snd-mtpav +---------------- + +Module for MOTU MidiTimePiece AV multiport MIDI (on the parallel +port). + +port + I/O port # for MTPAV (0x378,0x278, default=0x378) +irq + IRQ # for MTPAV (7,5, default=7) +hwports + number of supported hardware ports, default=8. + +Module supports only 1 card. This module has no enable option. + +Module snd-mts64 +---------------- + +Module for Ego Systems (ESI) Miditerminal 4140 + +This module supports multiple devices. +Requires parport (``CONFIG_PARPORT``). + +Module snd-nm256 +---------------- + +Module for NeoMagic NM256AV/ZX chips + +playback_bufsize + max playback frame size in kB (4-128kB) +capture_bufsize + max capture frame size in kB (4-128kB) +force_ac97 + 0 or 1 (disabled by default) +buffer_top + specify buffer top address +use_cache + 0 or 1 (disabled by default) +vaio_hack + alias buffer_top=0x25a800 +reset_workaround + enable AC97 RESET workaround for some laptops +reset_workaround2 + enable extended AC97 RESET workaround for some other laptops + +This module supports one chip and autoprobe. + +The power-management is supported. + +Note: on some notebooks the buffer address cannot be detected +automatically, or causes hang-up during initialization. +In such a case, specify the buffer top address explicitly via +the buffer_top option. +For example, +Sony F250: buffer_top=0x25a800 +Sony F270: buffer_top=0x272800 +The driver supports only ac97 codec. It's possible to force +to initialize/use ac97 although it's not detected. In such a +case, use ``force_ac97=1`` option - but *NO* guarantee whether it +works! + +Note: The NM256 chip can be linked internally with non-AC97 +codecs. This driver supports only the AC97 codec, and won't work +with machines with other (most likely CS423x or OPL3SAx) chips, +even though the device is detected in lspci. In such a case, try +other drivers, e.g. snd-cs4232 or snd-opl3sa2. Some has ISA-PnP +but some doesn't have ISA PnP. You'll need to specify ``isapnp=0`` +and proper hardware parameters in the case without ISA PnP. + +Note: some laptops need a workaround for AC97 RESET. For the +known hardware like Dell Latitude LS and Sony PCG-F305, this +workaround is enabled automatically. For other laptops with a +hard freeze, you can try ``reset_workaround=1`` option. + +Note: Dell Latitude CSx laptops have another problem regarding +AC97 RESET. On these laptops, reset_workaround2 option is +turned on as default. This option is worth to try if the +previous reset_workaround option doesn't help. + +Note: This driver is really crappy. It's a porting from the +OSS driver, which is a result of black-magic reverse engineering. +The detection of codec will fail if the driver is loaded *after* +X-server as described above. You might be able to force to load +the module, but it may result in hang-up. Hence, make sure that +you load this module *before* X if you encounter this kind of +problem. + +Module snd-opl3sa2 +------------------ + +Module for Yamaha OPL3-SA2/SA3 sound cards. + +isapnp + ISA PnP detection - 0 = disable, 1 = enable (default) + +with ``isapnp=0``, the following options are available: + +port + control port # for OPL3-SA chip (0x370) +sb_port + SB port # for OPL3-SA chip (0x220,0x240) +wss_port + WSS port # for OPL3-SA chip (0x530,0xe80,0xf40,0x604) +midi_port + port # for MPU-401 UART (0x300,0x330), -1 = disable +fm_port + FM port # for OPL3-SA chip (0x388), -1 = disable +irq + IRQ # for OPL3-SA chip (5,7,9,10) +dma1 + first DMA # for Yamaha OPL3-SA chip (0,1,3) +dma2 + second DMA # for Yamaha OPL3-SA chip (0,1,3), -1 = disable + +This module supports multiple cards and ISA PnP. It does not support +autoprobe (if ISA PnP is not used) thus all ports must be specified!!! + +The power-management is supported. + +Module snd-opti92x-ad1848 +------------------------- + +Module for sound cards based on OPTi 82c92x and Analog Devices AD1848 chips. +Module works with OAK Mozart cards as well. + +isapnp + ISA PnP detection - 0 = disable, 1 = enable (default) + +with ``isapnp=0``, the following options are available: + +port + port # for WSS chip (0x530,0xe80,0xf40,0x604) +mpu_port + port # for MPU-401 UART (0x300,0x310,0x320,0x330) +fm_port + port # for OPL3 device (0x388) +irq + IRQ # for WSS chip (5,7,9,10,11) +mpu_irq + IRQ # for MPU-401 UART (5,7,9,10) +dma1 + first DMA # for WSS chip (0,1,3) + +This module supports only one card, autoprobe and PnP. + +Module snd-opti92x-cs4231 +------------------------- + +Module for sound cards based on OPTi 82c92x and Crystal CS4231 chips. + +isapnp + ISA PnP detection - 0 = disable, 1 = enable (default) + +with ``isapnp=0``, the following options are available: + +port + port # for WSS chip (0x530,0xe80,0xf40,0x604) +mpu_port + port # for MPU-401 UART (0x300,0x310,0x320,0x330) +fm_port + port # for OPL3 device (0x388) +irq + IRQ # for WSS chip (5,7,9,10,11) +mpu_irq + IRQ # for MPU-401 UART (5,7,9,10) +dma1 + first DMA # for WSS chip (0,1,3) +dma2 + second DMA # for WSS chip (0,1,3) + +This module supports only one card, autoprobe and PnP. + +Module snd-opti93x +------------------ + +Module for sound cards based on OPTi 82c93x chips. + +isapnp + ISA PnP detection - 0 = disable, 1 = enable (default) + +with ``isapnp=0``, the following options are available: + +port + port # for WSS chip (0x530,0xe80,0xf40,0x604) +mpu_port + port # for MPU-401 UART (0x300,0x310,0x320,0x330) +fm_port + port # for OPL3 device (0x388) +irq + IRQ # for WSS chip (5,7,9,10,11) +mpu_irq + IRQ # for MPU-401 UART (5,7,9,10) +dma1 + first DMA # for WSS chip (0,1,3) +dma2 + second DMA # for WSS chip (0,1,3) + +This module supports only one card, autoprobe and PnP. + +Module snd-oxygen +----------------- + +Module for sound cards based on the C-Media CMI8786/8787/8788 chip: + +* Asound A-8788 +* Asus Xonar DG/DGX +* AuzenTech X-Meridian +* AuzenTech X-Meridian 2G +* Bgears b-Enspirer +* Club3D Theatron DTS +* HT-Omega Claro (plus) +* HT-Omega Claro halo (XT) +* Kuroutoshikou CMI8787-HG2PCI +* Razer Barracuda AC-1 +* Sondigo Inferno +* TempoTec HiFier Fantasia +* TempoTec HiFier Serenade + +This module supports autoprobe and multiple cards. + +Module snd-pcsp +--------------- + +Module for internal PC-Speaker. + +nopcm + Disable PC-Speaker PCM sound. Only beeps remain. +nforce_wa + enable NForce chipset workaround. Expect bad sound. + +This module supports system beeps, some kind of PCM playback and +even a few mixer controls. + +Module snd-pcxhr +---------------- + +Module for Digigram PCXHR boards + +This module supports multiple cards. + +Module snd-portman2x4 +--------------------- + +Module for Midiman Portman 2x4 parallel port MIDI interface + +This module supports multiple cards. + +Module snd-powermac (on ppc only) +--------------------------------- + +Module for PowerMac, iMac and iBook on-board soundchips + +enable_beep + enable beep using PCM (enabled as default) + +Module supports autoprobe a chip. + +Note: the driver may have problems regarding endianness. + +The power-management is supported. + +Module snd-pxa2xx-ac97 (on arm only) +------------------------------------ + +Module for AC97 driver for the Intel PXA2xx chip + +For ARM architecture only. + +The power-management is supported. + +Module snd-riptide +------------------ + +Module for Conexant Riptide chip + +joystick_port + Joystick port # (default: 0x200) +mpu_port + MPU401 port # (default: 0x330) +opl3_port + OPL3 port # (default: 0x388) + +This module supports multiple cards. +The driver requires the firmware loader support on kernel. +You need to install the firmware file ``riptide.hex`` to the standard +firmware path (e.g. /lib/firmware). + +Module snd-rme32 +---------------- + +Module for RME Digi32, Digi32 Pro and Digi32/8 (Sek'd Prodif32, +Prodif96 and Prodif Gold) sound cards. + +This module supports multiple cards. + +Module snd-rme96 +---------------- + +Module for RME Digi96, Digi96/8 and Digi96/8 PRO/PAD/PST sound cards. + +This module supports multiple cards. + +Module snd-rme9652 +------------------ + +Module for RME Digi9652 (Hammerfall, Hammerfall-Light) sound cards. + +precise_ptr + Enable precise pointer (doesn't work reliably). (default = 0) + +This module supports multiple cards. + +Note: snd-page-alloc module does the job which snd-hammerfall-mem +module did formerly. It will allocate the buffers in advance +when any RME9652 cards are found. To make the buffer +allocation sure, load snd-page-alloc module in the early +stage of boot sequence. See `Early Buffer Allocation`_ +section. + +Module snd-sa11xx-uda1341 (on arm only) +--------------------------------------- + +Module for Philips UDA1341TS on Compaq iPAQ H3600 sound card. + +Module supports only one card. +Module has no enable and index options. + +The power-management is supported. + +Module snd-sb8 +-------------- + +Module for 8-bit SoundBlaster cards: SoundBlaster 1.0, SoundBlaster 2.0, +SoundBlaster Pro + +port + port # for SB DSP chip (0x220,0x240,0x260) +irq + IRQ # for SB DSP chip (5,7,9,10) +dma8 + DMA # for SB DSP chip (1,3) + +This module supports multiple cards and autoprobe. + +The power-management is supported. + +Module snd-sb16 and snd-sbawe +----------------------------- + +Module for 16-bit SoundBlaster cards: SoundBlaster 16 (PnP), +SoundBlaster AWE 32 (PnP), SoundBlaster AWE 64 PnP + +mic_agc + Mic Auto-Gain-Control - 0 = disable, 1 = enable (default) +csp + ASP/CSP chip support - 0 = disable (default), 1 = enable +isapnp + ISA PnP detection - 0 = disable, 1 = enable (default) + +with isapnp=0, the following options are available: + +port + port # for SB DSP 4.x chip (0x220,0x240,0x260) +mpu_port + port # for MPU-401 UART (0x300,0x330), -1 = disable +awe_port + base port # for EMU8000 synthesizer (0x620,0x640,0x660) (snd-sbawe + module only) +irq + IRQ # for SB DSP 4.x chip (5,7,9,10) +dma8 + 8-bit DMA # for SB DSP 4.x chip (0,1,3) +dma16 + 16-bit DMA # for SB DSP 4.x chip (5,6,7) + +This module supports multiple cards, autoprobe and ISA PnP. + +Note: To use Vibra16X cards in 16-bit half duplex mode, you must +disable 16bit DMA with dma16 = -1 module parameter. +Also, all Sound Blaster 16 type cards can operate in 16-bit +half duplex mode through 8-bit DMA channel by disabling their +16-bit DMA channel. + +The power-management is supported. + +Module snd-sc6000 +----------------- + +Module for Gallant SC-6000 soundcard and later models: SC-6600 and +SC-7000. + +port + Port # (0x220 or 0x240) +mss_port + MSS Port # (0x530 or 0xe80) +irq + IRQ # (5,7,9,10,11) +mpu_irq + MPU-401 IRQ # (5,7,9,10) ,0 - no MPU-401 irq +dma + DMA # (1,3,0) +joystick + Enable gameport - 0 = disable (default), 1 = enable + +This module supports multiple cards. + +This card is also known as Audio Excel DSP 16 or Zoltrix AV302. + +Module snd-sscape +----------------- + +Module for ENSONIQ SoundScape cards. + +port + Port # (PnP setup) +wss_port + WSS Port # (PnP setup) +irq + IRQ # (PnP setup) +mpu_irq + MPU-401 IRQ # (PnP setup) +dma + DMA # (PnP setup) +dma2 + 2nd DMA # (PnP setup, -1 to disable) +joystick + Enable gameport - 0 = disable (default), 1 = enable + +This module supports multiple cards. + +The driver requires the firmware loader support on kernel. + +Module snd-sun-amd7930 (on sparc only) +-------------------------------------- + +Module for AMD7930 sound chips found on Sparcs. + +This module supports multiple cards. + +Module snd-sun-cs4231 (on sparc only) +------------------------------------- + +Module for CS4231 sound chips found on Sparcs. + +This module supports multiple cards. + +Module snd-sun-dbri (on sparc only) +----------------------------------- + +Module for DBRI sound chips found on Sparcs. + +This module supports multiple cards. + +Module snd-wavefront +-------------------- + +Module for Turtle Beach Maui, Tropez and Tropez+ sound cards. + +use_cs4232_midi + Use CS4232 MPU-401 interface + (inaccessibly located inside your computer) +isapnp + ISA PnP detection - 0 = disable, 1 = enable (default) + +with isapnp=0, the following options are available: + +cs4232_pcm_port + Port # for CS4232 PCM interface. +cs4232_pcm_irq + IRQ # for CS4232 PCM interface (5,7,9,11,12,15). +cs4232_mpu_port + Port # for CS4232 MPU-401 interface. +cs4232_mpu_irq + IRQ # for CS4232 MPU-401 interface (9,11,12,15). +ics2115_port + Port # for ICS2115 +ics2115_irq + IRQ # for ICS2115 +fm_port + FM OPL-3 Port # +dma1 + DMA1 # for CS4232 PCM interface. +dma2 + DMA2 # for CS4232 PCM interface. + +The below are options for wavefront_synth features: + +wf_raw + Assume that we need to boot the OS (default:no); + If yes, then during driver loading, the state of the board is + ignored, and we reset the board and load the firmware anyway. +fx_raw + Assume that the FX process needs help (default:yes); + If false, we'll leave the FX processor in whatever state it is + when the driver is loaded. The default is to download the + microprogram and associated coefficients to set it up for + "default" operation, whatever that means. +debug_default + Debug parameters for card initialization +wait_usecs + How long to wait without sleeping, usecs (default:150); + This magic number seems to give pretty optimal throughput + based on my limited experimentation. + If you want to play around with it and find a better value, be + my guest. Remember, the idea is to get a number that causes us + to just busy wait for as many WaveFront commands as possible, + without coming up with a number so large that we hog the whole + CPU. + Specifically, with this number, out of about 134,000 status + waits, only about 250 result in a sleep. +sleep_interval + How long to sleep when waiting for reply (default: 100) +sleep_tries + How many times to try sleeping during a wait (default: 50) +ospath + Pathname to processed ICS2115 OS firmware (default:wavefront.os); + The path name of the ISC2115 OS firmware. In the recent + version, it's handled via firmware loader framework, so it + must be installed in the proper path, typically, + /lib/firmware. +reset_time + How long to wait for a reset to take effect (default:2) +ramcheck_time + How many seconds to wait for the RAM test (default:20) +osrun_time + How many seconds to wait for the ICS2115 OS (default:10) + +This module supports multiple cards and ISA PnP. + +Note: the firmware file ``wavefront.os`` was located in the earlier +version in /etc. Now it's loaded via firmware loader, and +must be in the proper firmware path, such as /lib/firmware. +Copy (or symlink) the file appropriately if you get an error +regarding firmware downloading after upgrading the kernel. + +Module snd-sonicvibes +--------------------- + +Module for S3 SonicVibes PCI sound cards. +* PINE Schubert 32 PCI + +reverb + Reverb Enable - 1 = enable, 0 = disable (default); + SoundCard must have onboard SRAM for this. +mge + Mic Gain Enable - 1 = enable, 0 = disable (default) + +This module supports multiple cards and autoprobe. + +Module snd-serial-u16550 +------------------------ + +Module for UART16550A serial MIDI ports. + +port + port # for UART16550A chip +irq + IRQ # for UART16550A chip, -1 = poll mode +speed + speed in bauds (9600,19200,38400,57600,115200) + 38400 = default +base + base for divisor in bauds (57600,115200,230400,460800) + 115200 = default +outs + number of MIDI ports in a serial port (1-4) + 1 = default +adaptor + Type of adaptor. + 0 = Soundcanvas, 1 = MS-124T, 2 = MS-124W S/A, + 3 = MS-124W M/B, 4 = Generic + +This module supports multiple cards. This module does not support autoprobe +thus the main port must be specified!!! Other options are optional. + +Module snd-trident +------------------ + +Module for Trident 4DWave DX/NX sound cards. +* Best Union Miss Melody 4DWave PCI +* HIS 4DWave PCI +* Warpspeed ONSpeed 4DWave PCI +* AzTech PCI 64-Q3D +* Addonics SV 750 +* CHIC True Sound 4Dwave +* Shark Predator4D-PCI +* Jaton SonicWave 4D +* SiS SI7018 PCI Audio +* Hoontech SoundTrack Digital 4DWave NX + +pcm_channels + max channels (voices) reserved for PCM +wavetable_size + max wavetable size in kB (4-?kb) + +This module supports multiple cards and autoprobe. + +The power-management is supported. + +Module snd-ua101 +---------------- + +Module for the Edirol UA-101/UA-1000 audio/MIDI interfaces. + +This module supports multiple devices, autoprobe and hotplugging. + +Module snd-usb-audio +-------------------- + +Module for USB audio and USB MIDI devices. + +vid + Vendor ID for the device (optional) +pid + Product ID for the device (optional) +nrpacks + Max. number of packets per URB (default: 8) +device_setup + Device specific magic number (optional); + Influence depends on the device + Default: 0x0000 +ignore_ctl_error + Ignore any USB-controller regarding mixer interface (default: no) +autoclock + Enable auto-clock selection for UAC2 devices (default: yes) +quirk_alias + Quirk alias list, pass strings like ``0123abcd:5678beef``, which + applies the existing quirk for the device 5678:beef to a new + device 0123:abcd. + +This module supports multiple devices, autoprobe and hotplugging. + +NB: ``nrpacks`` parameter can be modified dynamically via sysfs. +Don't put the value over 20. Changing via sysfs has no sanity +check. + +NB: ``ignore_ctl_error=1`` may help when you get an error at accessing +the mixer element such as URB error -22. This happens on some +buggy USB device or the controller. + +NB: quirk_alias option is provided only for testing / development. +If you want to have a proper support, contact to upstream for +adding the matching quirk in the driver code statically. + +Module snd-usb-caiaq +-------------------- + +Module for caiaq UB audio interfaces, + +* Native Instruments RigKontrol2 +* Native Instruments Kore Controller +* Native Instruments Audio Kontrol 1 +* Native Instruments Audio 8 DJ + +This module supports multiple devices, autoprobe and hotplugging. + +Module snd-usb-usx2y +-------------------- + +Module for Tascam USB US-122, US-224 and US-428 devices. + +This module supports multiple devices, autoprobe and hotplugging. + +Note: you need to load the firmware via ``usx2yloader`` utility included +in alsa-tools and alsa-firmware packages. + +Module snd-via82xx +------------------ + +Module for AC'97 motherboards based on VIA 82C686A/686B, 8233, 8233A, +8233C, 8235, 8237 (south) bridge. + +mpu_port + 0x300,0x310,0x320,0x330, otherwise obtain BIOS setup + [VIA686A/686B only] +joystick + Enable joystick (default off) [VIA686A/686B only] +ac97_clock + AC'97 codec clock base (default 48000Hz) +dxs_support + support DXS channels, 0 = auto (default), 1 = enable, 2 = disable, + 3 = 48k only, 4 = no VRA, 5 = enable any sample rate and different + sample rates on different channels [VIA8233/C, 8235, 8237 only] +ac97_quirk + AC'97 workaround for strange hardware; + See `AC97 Quirk Option`_ section below. + +This module supports one chip and autoprobe. + +Note: on some SMP motherboards like MSI 694D the interrupts might +not be generated properly. In such a case, please try to +set the SMP (or MPS) version on BIOS to 1.1 instead of +default value 1.4. Then the interrupt number will be +assigned under 15. You might also upgrade your BIOS. + +Note: VIA8233/5/7 (not VIA8233A) can support DXS (direct sound) +channels as the first PCM. On these channels, up to 4 +streams can be played at the same time, and the controller +can perform sample rate conversion with separate rates for +each channel. +As default (``dxs_support = 0``), 48k fixed rate is chosen +except for the known devices since the output is often +noisy except for 48k on some mother boards due to the +bug of BIOS. +Please try once ``dxs_support=5`` and if it works on other +sample rates (e.g. 44.1kHz of mp3 playback), please let us +know the PCI subsystem vendor/device id's (output of +``lspci -nv``). +If ``dxs_support=5`` does not work, try ``dxs_support=4``; if it +doesn't work too, try dxs_support=1. (dxs_support=1 is +usually for old motherboards. The correct implemented +board should work with 4 or 5.) If it still doesn't +work and the default setting is ok, ``dxs_support=3`` is the +right choice. If the default setting doesn't work at all, +try ``dxs_support=2`` to disable the DXS channels. +In any cases, please let us know the result and the +subsystem vendor/device ids. See `Links and Addresses`_ +below. + +Note: for the MPU401 on VIA823x, use snd-mpu401 driver +additionally. The mpu_port option is for VIA686 chips only. + +The power-management is supported. + +Module snd-via82xx-modem +------------------------ + +Module for VIA82xx AC97 modem + +ac97_clock + AC'97 codec clock base (default 48000Hz) + +This module supports one card and autoprobe. + +Note: The default index value of this module is -2, i.e. the first +slot is excluded. + +The power-management is supported. + +Module snd-virmidi +------------------ + +Module for virtual rawmidi devices. +This module creates virtual rawmidi devices which communicate +to the corresponding ALSA sequencer ports. + +midi_devs + MIDI devices # (1-4, default=4) + +This module supports multiple cards. + +Module snd-virtuoso +------------------- + +Module for sound cards based on the Asus AV66/AV100/AV200 chips, +i.e., Xonar D1, DX, D2, D2X, DS, DSX, Essence ST (Deluxe), +Essence STX (II), HDAV1.3 (Deluxe), and HDAV1.3 Slim. + +This module supports autoprobe and multiple cards. + +Module snd-vx222 +---------------- + +Module for Digigram VX-Pocket VX222, V222 v2 and Mic cards. + +mic + Enable Microphone on V222 Mic (NYI) +ibl + Capture IBL size. (default = 0, minimum size) + +This module supports multiple cards. + +When the driver is compiled as a module and the hotplug firmware +is supported, the firmware data is loaded via hotplug automatically. +Install the necessary firmware files in alsa-firmware package. +When no hotplug fw loader is available, you need to load the +firmware via vxloader utility in alsa-tools package. To invoke +vxloader automatically, add the following to /etc/modprobe.d/alsa.conf + +:: + + install snd-vx222 /sbin/modprobe --first-time -i snd-vx222\ + && /usr/bin/vxloader + +(for 2.2/2.4 kernels, add ``post-install /usr/bin/vxloader`` to +/etc/modules.conf, instead.) +IBL size defines the interrupts period for PCM. The smaller size +gives smaller latency but leads to more CPU consumption, too. +The size is usually aligned to 126. As default (=0), the smallest +size is chosen. The possible IBL values can be found in +/proc/asound/cardX/vx-status proc file. + +The power-management is supported. + +Module snd-vxpocket +------------------- + +Module for Digigram VX-Pocket VX2 and 440 PCMCIA cards. + +ibl + Capture IBL size. (default = 0, minimum size) + +This module supports multiple cards. The module is compiled only when +PCMCIA is supported on kernel. + +With the older 2.6.x kernel, to activate the driver via the card +manager, you'll need to set up /etc/pcmcia/vxpocket.conf. See the +sound/pcmcia/vx/vxpocket.c. 2.6.13 or later kernel requires no +longer require a config file. + +When the driver is compiled as a module and the hotplug firmware +is supported, the firmware data is loaded via hotplug automatically. +Install the necessary firmware files in alsa-firmware package. +When no hotplug fw loader is available, you need to load the +firmware via vxloader utility in alsa-tools package. + +About capture IBL, see the description of snd-vx222 module. + +Note: snd-vxp440 driver is merged to snd-vxpocket driver since +ALSA 1.0.10. + +The power-management is supported. + +Module snd-ymfpci +----------------- + +Module for Yamaha PCI chips (YMF72x, YMF74x & YMF75x). + +mpu_port + 0x300,0x330,0x332,0x334, 0 (disable) by default, + 1 (auto-detect for YMF744/754 only) +fm_port + 0x388,0x398,0x3a0,0x3a8, 0 (disable) by default + 1 (auto-detect for YMF744/754 only) +joystick_port + 0x201,0x202,0x204,0x205, 0 (disable) by default, + 1 (auto-detect) +rear_switch + enable shared rear/line-in switch (bool) + +This module supports autoprobe and multiple chips. + +The power-management is supported. + +Module snd-pdaudiocf +-------------------- + +Module for Sound Core PDAudioCF sound card. + +The power-management is supported. + + +AC97 Quirk Option +================= + +The ac97_quirk option is used to enable/override the workaround for +specific devices on drivers for on-board AC'97 controllers like +snd-intel8x0. Some hardware have swapped output pins between Master +and Headphone, or Surround (thanks to confusion of AC'97 +specifications from version to version :-) + +The driver provides the auto-detection of known problematic devices, +but some might be unknown or wrongly detected. In such a case, pass +the proper value with this option. + +The following strings are accepted: + +default + Don't override the default setting +none + Disable the quirk +hp_only + Bind Master and Headphone controls as a single control +swap_hp + Swap headphone and master controls +swap_surround + Swap master and surround controls +ad_sharing + For AD1985, turn on OMS bit and use headphone +alc_jack + For ALC65x, turn on the jack sense mode +inv_eapd + Inverted EAPD implementation +mute_led + Bind EAPD bit for turning on/off mute LED + +For backward compatibility, the corresponding integer value -1, 0, ... +are accepted, too. + +For example, if ``Master`` volume control has no effect on your device +but only ``Headphone`` does, pass ac97_quirk=hp_only module option. + + +Configuring Non-ISAPNP Cards +============================ + +When the kernel is configured with ISA-PnP support, the modules +supporting the isapnp cards will have module options ``isapnp``. +If this option is set, *only* the ISA-PnP devices will be probed. +For probing the non ISA-PnP cards, you have to pass ``isapnp=0`` option +together with the proper i/o and irq configuration. + +When the kernel is configured without ISA-PnP support, isapnp option +will be not built in. + + +Module Autoloading Support +========================== + +The ALSA drivers can be loaded automatically on demand by defining +module aliases. The string ``snd-card-%1`` is requested for ALSA native +devices where ``%i`` is sound card number from zero to seven. + +To auto-load an ALSA driver for OSS services, define the string +``sound-slot-%i`` where ``%i`` means the slot number for OSS, which +corresponds to the card index of ALSA. Usually, define this +as the same card module. + +An example configuration for a single emu10k1 card is like below: +:: + + ----- /etc/modprobe.d/alsa.conf + alias snd-card-0 snd-emu10k1 + alias sound-slot-0 snd-emu10k1 + ----- /etc/modprobe.d/alsa.conf + +The available number of auto-loaded sound cards depends on the module +option ``cards_limit`` of snd module. As default it's set to 1. +To enable the auto-loading of multiple cards, specify the number of +sound cards in that option. + +When multiple cards are available, it'd better to specify the index +number for each card via module option, too, so that the order of +cards is kept consistent. + +An example configuration for two sound cards is like below: +:: + + ----- /etc/modprobe.d/alsa.conf + # ALSA portion + options snd cards_limit=2 + alias snd-card-0 snd-interwave + alias snd-card-1 snd-ens1371 + options snd-interwave index=0 + options snd-ens1371 index=1 + # OSS/Free portion + alias sound-slot-0 snd-interwave + alias sound-slot-1 snd-ens1371 + ----- /etc/modprobe.d/alsa.conf + +In this example, the interwave card is always loaded as the first card +(index 0) and ens1371 as the second (index 1). + +Alternative (and new) way to fixate the slot assignment is to use +``slots`` option of snd module. In the case above, specify like the +following: +:: + + options snd slots=snd-interwave,snd-ens1371 + +Then, the first slot (#0) is reserved for snd-interwave driver, and +the second (#1) for snd-ens1371. You can omit index option in each +driver if slots option is used (although you can still have them at +the same time as long as they don't conflict). + +The slots option is especially useful for avoiding the possible +hot-plugging and the resultant slot conflict. For example, in the +case above again, the first two slots are already reserved. If any +other driver (e.g. snd-usb-audio) is loaded before snd-interwave or +snd-ens1371, it will be assigned to the third or later slot. + +When a module name is given with '!', the slot will be given for any +modules but that name. For example, ``slots=!snd-pcsp`` will reserve +the first slot for any modules but snd-pcsp. + + +ALSA PCM devices to OSS devices mapping +======================================= +:: + + /dev/snd/pcmC0D0[c|p] -> /dev/audio0 (/dev/audio) -> minor 4 + /dev/snd/pcmC0D0[c|p] -> /dev/dsp0 (/dev/dsp) -> minor 3 + /dev/snd/pcmC0D1[c|p] -> /dev/adsp0 (/dev/adsp) -> minor 12 + /dev/snd/pcmC1D0[c|p] -> /dev/audio1 -> minor 4+16 = 20 + /dev/snd/pcmC1D0[c|p] -> /dev/dsp1 -> minor 3+16 = 19 + /dev/snd/pcmC1D1[c|p] -> /dev/adsp1 -> minor 12+16 = 28 + /dev/snd/pcmC2D0[c|p] -> /dev/audio2 -> minor 4+32 = 36 + /dev/snd/pcmC2D0[c|p] -> /dev/dsp2 -> minor 3+32 = 39 + /dev/snd/pcmC2D1[c|p] -> /dev/adsp2 -> minor 12+32 = 44 + +The first number from ``/dev/snd/pcmC{X}D{Y}[c|p]`` expression means +sound card number and second means device number. The ALSA devices +have either ``c`` or ``p`` suffix indicating the direction, capture and +playback, respectively. + +Please note that the device mapping above may be varied via the module +options of snd-pcm-oss module. + + +Proc interfaces (/proc/asound) +============================== + +/proc/asound/card#/pcm#[cp]/oss +------------------------------- +erase + erase all additional information about OSS applications + + [] + + name of application with (higher priority) or without path + + number of fragments or zero if auto + + size of fragment in bytes or zero if auto + + optional parameters + + disable + the application tries to open a pcm device for + this channel but does not want to use it. + (Cause a bug or mmap needs) + It's good for Quake etc... + direct + don't use plugins + block + force block mode (rvplayer) + non-block + force non-block mode + whole-frag + write only whole fragments (optimization affecting + playback only) + no-silence + do not fill silence ahead to avoid clicks + buggy-ptr + Returns the whitespace blocks in GETOPTR ioctl + instead of filled blocks + +Example: +:: + + echo "x11amp 128 16384" > /proc/asound/card0/pcm0p/oss + echo "squake 0 0 disable" > /proc/asound/card0/pcm0c/oss + echo "rvplayer 0 0 block" > /proc/asound/card0/pcm0p/oss + + +Early Buffer Allocation +======================= + +Some drivers (e.g. hdsp) require the large contiguous buffers, and +sometimes it's too late to find such spaces when the driver module is +actually loaded due to memory fragmentation. You can pre-allocate the +PCM buffers by loading snd-page-alloc module and write commands to its +proc file in prior, for example, in the early boot stage like +``/etc/init.d/*.local`` scripts. + +Reading the proc file /proc/drivers/snd-page-alloc shows the current +usage of page allocation. In writing, you can send the following +commands to the snd-page-alloc driver: + +* add VENDOR DEVICE MASK SIZE BUFFERS + +VENDOR and DEVICE are PCI vendor and device IDs. They take +integer numbers (0x prefix is needed for the hex). +MASK is the PCI DMA mask. Pass 0 if not restricted. +SIZE is the size of each buffer to allocate. You can pass +k and m suffix for KB and MB. The max number is 16MB. +BUFFERS is the number of buffers to allocate. It must be greater +than 0. The max number is 4. + +* erase + +This will erase the all pre-allocated buffers which are not in +use. + + +Links and Addresses +=================== + +ALSA project homepage + http://www.alsa-project.org +Kernel Bugzilla + http://bugzilla.kernel.org/ +ALSA Developers ML + mailto:alsa-devel@alsa-project.org +alsa-info.sh script + http://www.alsa-project.org/alsa-info.sh diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt deleted file mode 100644 index fc53ccd9a629..000000000000 --- a/Documentation/sound/alsa/ALSA-Configuration.txt +++ /dev/null @@ -1,2330 +0,0 @@ - - Advanced Linux Sound Architecture - Driver - ========================================== - Configuration guide - - -Kernel Configuration -==================== - -To enable ALSA support you need at least to build the kernel with -primary sound card support (CONFIG_SOUND). Since ALSA can emulate OSS, -you don't have to choose any of the OSS modules. - -Enable "OSS API emulation" (CONFIG_SND_OSSEMUL) and both OSS mixer and -PCM supports if you want to run OSS applications with ALSA. - -If you want to support the WaveTable functionality on cards such as -SB Live! then you need to enable "Sequencer support" -(CONFIG_SND_SEQUENCER). - -To make ALSA debug messages more verbose, enable the "Verbose printk" -and "Debug" options. To check for memory leaks, turn on "Debug memory" -too. "Debug detection" will add checks for the detection of cards. - -Please note that all the ALSA ISA drivers support the Linux isapnp API -(if the card supports ISA PnP). You don't need to configure the cards -using isapnptools. - - -Creating ALSA devices -===================== - -This depends on your distribution, but normally you use the /dev/MAKEDEV -script to create the necessary device nodes. On some systems you use a -script named 'snddevices'. - - -Module parameters -================= - -The user can load modules with options. If the module supports more than -one card and you have more than one card of the same type then you can -specify multiple values for the option separated by commas. - -Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. - - Module snd - ---------- - - The core ALSA module. It is used by all ALSA card drivers. - It takes the following options which have global effects. - - major - major number for sound driver - - Default: 116 - cards_limit - - limiting card index for auto-loading (1-8) - - Default: 1 - - For auto-loading more than one card, specify this - option together with snd-card-X aliases. - slots - Reserve the slot index for the given driver. - This option takes multiple strings. - See "Module Autoloading Support" section for details. - debug - Specifies the debug message level - (0 = disable debug prints, 1 = normal debug messages, - 2 = verbose debug messages) - This option appears only when CONFIG_SND_DEBUG=y. - This option can be dynamically changed via sysfs - /sys/modules/snd/parameters/debug file. - - Module snd-pcm-oss - ------------------ - - The PCM OSS emulation module. - This module takes options which change the mapping of devices. - - dsp_map - PCM device number maps assigned to the 1st OSS device. - - Default: 0 - adsp_map - PCM device number maps assigned to the 2st OSS device. - - Default: 1 - nonblock_open - - Don't block opening busy PCM devices. Default: 1 - - For example, when dsp_map=2, /dev/dsp will be mapped to PCM #2 of - the card #0. Similarly, when adsp_map=0, /dev/adsp will be mapped - to PCM #0 of the card #0. - For changing the second or later card, specify the option with - commas, such like "dsp_map=0,1". - - nonblock_open option is used to change the behavior of the PCM - regarding opening the device. When this option is non-zero, - opening a busy OSS PCM device won't be blocked but return - immediately with EAGAIN (just like O_NONBLOCK flag). - - Module snd-rawmidi - ------------------ - - This module takes options which change the mapping of devices. - similar to those of the snd-pcm-oss module. - - midi_map - MIDI device number maps assigned to the 1st OSS device. - - Default: 0 - amidi_map - MIDI device number maps assigned to the 2st OSS device. - - Default: 1 - - Common parameters for top sound card modules - -------------------------------------------- - - Each of top level sound card module takes the following options. - - index - index (slot #) of sound card - - Values: 0 through 31 or negative - - If nonnegative, assign that index number - - if negative, interpret as a bitmask of permissible - indices; the first free permitted index is assigned - - Default: -1 - id - card ID (identifier or name) - - Can be up to 15 characters long - - Default: the card type - - A directory by this name is created under /proc/asound/ - containing information about the card - - This ID can be used instead of the index number in - identifying the card - enable - enable card - - Default: enabled, for PCI and ISA PnP cards - - Module snd-adlib - ---------------- - - Module for AdLib FM cards. - - port - port # for OPL chip - - This module supports multiple cards. It does not support autoprobe, so - the port must be specified. For actual AdLib FM cards it will be 0x388. - Note that this card does not have PCM support and no mixer; only FM - synthesis. - - Make sure you have "sbiload" from the alsa-tools package available and, - after loading the module, find out the assigned ALSA sequencer port - number through "sbiload -l". Example output: - - Port Client name Port name - 64:0 OPL2 FM synth OPL2 FM Port - - Load the std.sb and drums.sb patches also supplied by sbiload: - - sbiload -p 64:0 std.sb drums.sb - - If you use this driver to drive an OPL3, you can use std.o3 and drums.o3 - instead. To have the card produce sound, use aplaymidi from alsa-utils: - - aplaymidi -p 64:0 foo.mid - - Module snd-ad1816a - ------------------ - - Module for sound cards based on Analog Devices AD1816A/AD1815 ISA chips. - - clockfreq - Clock frequency for AD1816A chip (default = 0, 33000Hz) - - This module supports multiple cards, autoprobe and PnP. - - Module snd-ad1848 - ----------------- - - Module for sound cards based on AD1848/AD1847/CS4248 ISA chips. - - port - port # for AD1848 chip - irq - IRQ # for AD1848 chip - dma1 - DMA # for AD1848 chip (0,1,3) - - This module supports multiple cards. It does not support autoprobe - thus main port must be specified!!! Other ports are optional. - - The power-management is supported. - - Module snd-ad1889 - ----------------- - - Module for Analog Devices AD1889 chips. - - ac97_quirk - AC'97 workaround for strange hardware - See the description of intel8x0 module for details. - - This module supports multiple cards. - - Module snd-ali5451 - ------------------ - - Module for ALi M5451 PCI chip. - - pcm_channels - Number of hardware channels assigned for PCM - spdif - Support SPDIF I/O - - Default: disabled - - This module supports one chip and autoprobe. - - The power-management is supported. - - Module snd-als100 - ----------------- - - Module for sound cards based on Avance Logic ALS100/ALS120 ISA chips. - - This module supports multiple cards, autoprobe and PnP. - - The power-management is supported. - - Module snd-als300 - ----------------- - - Module for Avance Logic ALS300 and ALS300+ - - This module supports multiple cards. - - The power-management is supported. - - Module snd-als4000 - ------------------ - - Module for sound cards based on Avance Logic ALS4000 PCI chip. - - joystick_port - port # for legacy joystick support. - 0 = disabled (default), 1 = auto-detect - - This module supports multiple cards, autoprobe and PnP. - - The power-management is supported. - - Module snd-asihpi - ----------------- - - Module for AudioScience ASI soundcards - - enable_hpi_hwdep - enable HPI hwdep for AudioScience soundcard - - This module supports multiple cards. - The driver requires the firmware loader support on kernel. - - Module snd-atiixp - ----------------- - - Module for ATI IXP 150/200/250/400 AC97 controllers. - - ac97_clock - AC'97 clock (default = 48000) - ac97_quirk - AC'97 workaround for strange hardware - See "AC97 Quirk Option" section below. - ac97_codec - Workaround to specify which AC'97 codec - instead of probing. If this works for you - file a bug with your `lspci -vn` output. - -2 -- Force probing. - -1 -- Default behavior. - 0-2 -- Use the specified codec. - spdif_aclink - S/PDIF transfer over AC-link (default = 1) - - This module supports one card and autoprobe. - - ATI IXP has two different methods to control SPDIF output. One is - over AC-link and another is over the "direct" SPDIF output. The - implementation depends on the motherboard, and you'll need to - choose the correct one via spdif_aclink module option. - - The power-management is supported. - - Module snd-atiixp-modem - ----------------------- - - Module for ATI IXP 150/200/250 AC97 modem controllers. - - This module supports one card and autoprobe. - - Note: The default index value of this module is -2, i.e. the first - slot is excluded. - - The power-management is supported. - - Module snd-au8810, snd-au8820, snd-au8830 - ----------------------------------------- - - Module for Aureal Vortex, Vortex2 and Advantage device. - - pcifix - Control PCI workarounds - 0 = Disable all workarounds - 1 = Force the PCI latency of the Aureal card to 0xff - 2 = Force the Extend PCI#2 Internal Master for Efficient - Handling of Dummy Requests on the VIA KT133 AGP Bridge - 3 = Force both settings - 255 = Autodetect what is required (default) - - This module supports all ADB PCM channels, ac97 mixer, SPDIF, hardware - EQ, mpu401, gameport. A3D and wavetable support are still in development. - Development and reverse engineering work is being coordinated at - http://savannah.nongnu.org/projects/openvortex/ - SPDIF output has a copy of the AC97 codec output, unless you use the - "spdif" pcm device, which allows raw data passthru. - The hardware EQ hardware and SPDIF is only present in the Vortex2 and - Advantage. - - Note: Some ALSA mixer applications don't handle the SPDIF sample rate - control correctly. If you have problems regarding this, try - another ALSA compliant mixer (alsamixer works). - - Module snd-azt1605 - ------------------ - - Module for Aztech Sound Galaxy soundcards based on the Aztech AZT1605 - chipset. - - port - port # for BASE (0x220,0x240,0x260,0x280) - wss_port - port # for WSS (0x530,0x604,0xe80,0xf40) - irq - IRQ # for WSS (7,9,10,11) - dma1 - DMA # for WSS playback (0,1,3) - dma2 - DMA # for WSS capture (0,1), -1 = disabled (default) - mpu_port - port # for MPU-401 UART (0x300,0x330), -1 = disabled (default) - mpu_irq - IRQ # for MPU-401 UART (3,5,7,9), -1 = disabled (default) - fm_port - port # for OPL3 (0x388), -1 = disabled (default) - - This module supports multiple cards. It does not support autoprobe: port, - wss_port, irq and dma1 have to be specified. The other values are - optional. - - "port" needs to match the BASE ADDRESS jumper on the card (0x220 or 0x240) - or the value stored in the card's EEPROM for cards that have an EEPROM and - their "CONFIG MODE" jumper set to "EEPROM SETTING". The other values can - be chosen freely from the options enumerated above. - - If dma2 is specified and different from dma1, the card will operate in - full-duplex mode. When dma1=3, only dma2=0 is valid and the only way to - enable capture since only channels 0 and 1 are available for capture. - - Generic settings are "port=0x220 wss_port=0x530 irq=10 dma1=1 dma2=0 - mpu_port=0x330 mpu_irq=9 fm_port=0x388". - - Whatever IRQ and DMA channels you pick, be sure to reserve them for - legacy ISA in your BIOS. - - Module snd-azt2316 - ------------------ - - Module for Aztech Sound Galaxy soundcards based on the Aztech AZT2316 - chipset. - - port - port # for BASE (0x220,0x240,0x260,0x280) - wss_port - port # for WSS (0x530,0x604,0xe80,0xf40) - irq - IRQ # for WSS (7,9,10,11) - dma1 - DMA # for WSS playback (0,1,3) - dma2 - DMA # for WSS capture (0,1), -1 = disabled (default) - mpu_port - port # for MPU-401 UART (0x300,0x330), -1 = disabled (default) - mpu_irq - IRQ # for MPU-401 UART (5,7,9,10), -1 = disabled (default) - fm_port - port # for OPL3 (0x388), -1 = disabled (default) - - This module supports multiple cards. It does not support autoprobe: port, - wss_port, irq and dma1 have to be specified. The other values are - optional. - - "port" needs to match the BASE ADDRESS jumper on the card (0x220 or 0x240) - or the value stored in the card's EEPROM for cards that have an EEPROM and - their "CONFIG MODE" jumper set to "EEPROM SETTING". The other values can - be chosen freely from the options enumerated above. - - If dma2 is specified and different from dma1, the card will operate in - full-duplex mode. When dma1=3, only dma2=0 is valid and the only way to - enable capture since only channels 0 and 1 are available for capture. - - Generic settings are "port=0x220 wss_port=0x530 irq=10 dma1=1 dma2=0 - mpu_port=0x330 mpu_irq=9 fm_port=0x388". - - Whatever IRQ and DMA channels you pick, be sure to reserve them for - legacy ISA in your BIOS. - - Module snd-aw2 - -------------- - - Module for Audiowerk2 sound card - - This module supports multiple cards. - - Module snd-azt2320 - ------------------ - - Module for sound cards based on Aztech System AZT2320 ISA chip (PnP only). - - This module supports multiple cards, PnP and autoprobe. - - The power-management is supported. - - Module snd-azt3328 - ------------------ - - Module for sound cards based on Aztech AZF3328 PCI chip. - - joystick - Enable joystick (default off) - - This module supports multiple cards. - - Module snd-bt87x - ---------------- - - Module for video cards based on Bt87x chips. - - digital_rate - Override the default digital rate (Hz) - load_all - Load the driver even if the card model isn't known - - This module supports multiple cards. - - Note: The default index value of this module is -2, i.e. the first - slot is excluded. - - Module snd-ca0106 - ----------------- - - Module for Creative Audigy LS and SB Live 24bit - - This module supports multiple cards. - - - Module snd-cmi8330 - ------------------ - - Module for sound cards based on C-Media CMI8330 ISA chips. - - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - - with isapnp=0, the following options are available: - - wssport - port # for CMI8330 chip (WSS) - wssirq - IRQ # for CMI8330 chip (WSS) - wssdma - first DMA # for CMI8330 chip (WSS) - sbport - port # for CMI8330 chip (SB16) - sbirq - IRQ # for CMI8330 chip (SB16) - sbdma8 - 8bit DMA # for CMI8330 chip (SB16) - sbdma16 - 16bit DMA # for CMI8330 chip (SB16) - fmport - (optional) OPL3 I/O port - mpuport - (optional) MPU401 I/O port - mpuirq - (optional) MPU401 irq # - - This module supports multiple cards and autoprobe. - - The power-management is supported. - - Module snd-cmipci - ----------------- - - Module for C-Media CMI8338/8738/8768/8770 PCI sound cards. - - mpu_port - port address of MIDI interface (8338 only): - 0x300,0x310,0x320,0x330 = legacy port, - 0 = disable (default) - fm_port - port address of OPL-3 FM synthesizer (8x38 only): - 0x388 = legacy port, - 1 = integrated PCI port (default on 8738), - 0 = disable - soft_ac3 - Software-conversion of raw SPDIF packets (model 033 only) - (default = 1) - joystick_port - Joystick port address (0 = disable, 1 = auto-detect) - - This module supports autoprobe and multiple cards. - - The power-management is supported. - - Module snd-cs4231 - ----------------- - - Module for sound cards based on CS4231 ISA chips. - - port - port # for CS4231 chip - mpu_port - port # for MPU-401 UART (optional), -1 = disable - irq - IRQ # for CS4231 chip - mpu_irq - IRQ # for MPU-401 UART - dma1 - first DMA # for CS4231 chip - dma2 - second DMA # for CS4231 chip - - This module supports multiple cards. This module does not support autoprobe - thus main port must be specified!!! Other ports are optional. - - The power-management is supported. - - Module snd-cs4236 - ----------------- - - Module for sound cards based on CS4232/CS4232A, - CS4235/CS4236/CS4236B/CS4237B/ - CS4238B/CS4239 ISA chips. - - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - - with isapnp=0, the following options are available: - - port - port # for CS4236 chip (PnP setup - 0x534) - cport - control port # for CS4236 chip (PnP setup - 0x120,0x210,0xf00) - mpu_port - port # for MPU-401 UART (PnP setup - 0x300), -1 = disable - fm_port - FM port # for CS4236 chip (PnP setup - 0x388), -1 = disable - irq - IRQ # for CS4236 chip (5,7,9,11,12,15) - mpu_irq - IRQ # for MPU-401 UART (9,11,12,15) - dma1 - first DMA # for CS4236 chip (0,1,3) - dma2 - second DMA # for CS4236 chip (0,1,3), -1 = disable - - This module supports multiple cards. This module does not support autoprobe - (if ISA PnP is not used) thus main port and control port must be - specified!!! Other ports are optional. - - The power-management is supported. - - This module is aliased as snd-cs4232 since it provides the old - snd-cs4232 functionality, too. - - Module snd-cs4281 - ----------------- - - Module for Cirrus Logic CS4281 soundchip. - - dual_codec - Secondary codec ID (0 = disable, default) - - This module supports multiple cards. - - The power-management is supported. - - Module snd-cs46xx - ----------------- - - Module for PCI sound cards based on CS4610/CS4612/CS4614/CS4615/CS4622/ - CS4624/CS4630/CS4280 PCI chips. - - external_amp - Force to enable external amplifier. - thinkpad - Force to enable Thinkpad's CLKRUN control. - mmap_valid - Support OSS mmap mode (default = 0). - - This module supports multiple cards and autoprobe. - Usually external amp and CLKRUN controls are detected automatically - from PCI sub vendor/device ids. If they don't work, give the options - above explicitly. - - The power-management is supported. - - Module snd-cs5530 - _________________ - - Module for Cyrix/NatSemi Geode 5530 chip. - - Module snd-cs5535audio - ---------------------- - - Module for multifunction CS5535 companion PCI device - - The power-management is supported. - - Module snd-ctxfi - ---------------- - - Module for Creative Sound Blaster X-Fi boards (20k1 / 20k2 chips) - * Creative Sound Blaster X-Fi Titanium Fatal1ty Champion Series - * Creative Sound Blaster X-Fi Titanium Fatal1ty Professional Series - * Creative Sound Blaster X-Fi Titanium Professional Audio - * Creative Sound Blaster X-Fi Titanium - * Creative Sound Blaster X-Fi Elite Pro - * Creative Sound Blaster X-Fi Platinum - * Creative Sound Blaster X-Fi Fatal1ty - * Creative Sound Blaster X-Fi XtremeGamer - * Creative Sound Blaster X-Fi XtremeMusic - - reference_rate - reference sample rate, 44100 or 48000 (default) - multiple - multiple to ref. sample rate, 1 or 2 (default) - subsystem - override the PCI SSID for probing; the value - consists of SSVID << 16 | SSDID. The default is - zero, which means no override. - - This module supports multiple cards. - - Module snd-darla20 - ------------------ - - Module for Echoaudio Darla20 - - This module supports multiple cards. - The driver requires the firmware loader support on kernel. - - Module snd-darla24 - ------------------ - - Module for Echoaudio Darla24 - - This module supports multiple cards. - The driver requires the firmware loader support on kernel. - - Module snd-dt019x - ----------------- - - Module for Diamond Technologies DT-019X / Avance Logic ALS-007 (PnP - only) - - This module supports multiple cards. This module is enabled only with - ISA PnP support. - - The power-management is supported. - - Module snd-dummy - ---------------- - - Module for the dummy sound card. This "card" doesn't do any output - or input, but you may use this module for any application which - requires a sound card (like RealPlayer). - - pcm_devs - Number of PCM devices assigned to each card - (default = 1, up to 4) - pcm_substreams - Number of PCM substreams assigned to each PCM - (default = 8, up to 128) - hrtimer - Use hrtimer (=1, default) or system timer (=0) - fake_buffer - Fake buffer allocations (default = 1) - - When multiple PCM devices are created, snd-dummy gives different - behavior to each PCM device: - 0 = interleaved with mmap support - 1 = non-interleaved with mmap support - 2 = interleaved without mmap - 3 = non-interleaved without mmap - - As default, snd-dummy drivers doesn't allocate the real buffers - but either ignores read/write or mmap a single dummy page to all - buffer pages, in order to save the resources. If your apps need - the read/ written buffer data to be consistent, pass fake_buffer=0 - option. - - The power-management is supported. - - Module snd-echo3g - ----------------- - - Module for Echoaudio 3G cards (Gina3G/Layla3G) - - This module supports multiple cards. - The driver requires the firmware loader support on kernel. - - Module snd-emu10k1 - ------------------ - - Module for EMU10K1/EMU10k2 based PCI sound cards. - * Sound Blaster Live! - * Sound Blaster PCI 512 - * Emu APS (partially supported) - * Sound Blaster Audigy - - extin - bitmap of available external inputs for FX8010 (see bellow) - extout - bitmap of available external outputs for FX8010 (see bellow) - seq_ports - allocated sequencer ports (4 by default) - max_synth_voices - limit of voices used for wavetable (64 by default) - max_buffer_size - specifies the maximum size of wavetable/pcm buffers - given in MB unit. Default value is 128. - enable_ir - enable IR - - This module supports multiple cards and autoprobe. - - Input & Output configurations [extin/extout] - * Creative Card wo/Digital out [0x0003/0x1f03] - * Creative Card w/Digital out [0x0003/0x1f0f] - * Creative Card w/Digital CD in [0x000f/0x1f0f] - * Creative Card wo/Digital out + LiveDrive [0x3fc3/0x1fc3] - * Creative Card w/Digital out + LiveDrive [0x3fc3/0x1fcf] - * Creative Card w/Digital CD in + LiveDrive [0x3fcf/0x1fcf] - * Creative Card wo/Digital out + Digital I/O 2 [0x0fc3/0x1f0f] - * Creative Card w/Digital out + Digital I/O 2 [0x0fc3/0x1f0f] - * Creative Card w/Digital CD in + Digital I/O 2 [0x0fcf/0x1f0f] - * Creative Card 5.1/w Digital out + LiveDrive [0x3fc3/0x1fff] - * Creative Card 5.1 (c) 2003 [0x3fc3/0x7cff] - * Creative Card all ins and outs [0x3fff/0x7fff] - - The power-management is supported. - - Module snd-emu10k1x - ------------------- - - Module for Creative Emu10k1X (SB Live Dell OEM version) - - This module supports multiple cards. - - Module snd-ens1370 - ------------------ - - Module for Ensoniq AudioPCI ES1370 PCI sound cards. - * SoundBlaster PCI 64 - * SoundBlaster PCI 128 - - joystick - Enable joystick (default off) - - This module supports multiple cards and autoprobe. - - The power-management is supported. - - Module snd-ens1371 - ------------------ - - Module for Ensoniq AudioPCI ES1371 PCI sound cards. - * SoundBlaster PCI 64 - * SoundBlaster PCI 128 - * SoundBlaster Vibra PCI - - joystick_port - port # for joystick (0x200,0x208,0x210,0x218), - 0 = disable (default), 1 = auto-detect - - This module supports multiple cards and autoprobe. - - The power-management is supported. - - Module snd-es1688 - ----------------- - - Module for ESS AudioDrive ES-1688 and ES-688 sound cards. - - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - mpu_port - port # for MPU-401 port (0x300,0x310,0x320,0x330), -1 = disable (default) - mpu_irq - IRQ # for MPU-401 port (5,7,9,10) - fm_port - port # for OPL3 (option; share the same port as default) - - with isapnp=0, the following additional options are available: - port - port # for ES-1688 chip (0x220,0x240,0x260) - irq - IRQ # for ES-1688 chip (5,7,9,10) - dma8 - DMA # for ES-1688 chip (0,1,3) - - This module supports multiple cards and autoprobe (without MPU-401 port) - and PnP with the ES968 chip. - - Module snd-es18xx - ----------------- - - Module for ESS AudioDrive ES-18xx sound cards. - - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - - with isapnp=0, the following options are available: - - port - port # for ES-18xx chip (0x220,0x240,0x260) - mpu_port - port # for MPU-401 port (0x300,0x310,0x320,0x330), -1 = disable (default) - fm_port - port # for FM (optional, not used) - irq - IRQ # for ES-18xx chip (5,7,9,10) - dma1 - first DMA # for ES-18xx chip (0,1,3) - dma2 - first DMA # for ES-18xx chip (0,1,3) - - This module supports multiple cards, ISA PnP and autoprobe (without MPU-401 - port if native ISA PnP routines are not used). - When dma2 is equal with dma1, the driver works as half-duplex. - - The power-management is supported. - - Module snd-es1938 - ----------------- - - Module for sound cards based on ESS Solo-1 (ES1938,ES1946) chips. - - This module supports multiple cards and autoprobe. - - The power-management is supported. - - Module snd-es1968 - ----------------- - - Module for sound cards based on ESS Maestro-1/2/2E (ES1968/ES1978) chips. - - total_bufsize - total buffer size in kB (1-4096kB) - pcm_substreams_p - playback channels (1-8, default=2) - pcm_substreams_c - capture channels (1-8, default=0) - clock - clock (0 = auto-detection) - use_pm - support the power-management (0 = off, 1 = on, - 2 = auto (default)) - enable_mpu - enable MPU401 (0 = off, 1 = on, 2 = auto (default)) - joystick - enable joystick (default off) - - This module supports multiple cards and autoprobe. - - The power-management is supported. - - Module snd-fm801 - ---------------- - - Module for ForteMedia FM801 based PCI sound cards. - - tea575x_tuner - Enable TEA575x tuner - - 1 = MediaForte 256-PCS - - 2 = MediaForte 256-PCPR - - 3 = MediaForte 64-PCR - - High 16-bits are video (radio) device number + 1 - - example: 0x10002 (MediaForte 256-PCPR, device 1) - - This module supports multiple cards and autoprobe. - - The power-management is supported. - - Module snd-gina20 - ----------------- - - Module for Echoaudio Gina20 - - This module supports multiple cards. - The driver requires the firmware loader support on kernel. - - Module snd-gina24 - ----------------- - - Module for Echoaudio Gina24 - - This module supports multiple cards. - The driver requires the firmware loader support on kernel. - - Module snd-gusclassic - --------------------- - - Module for Gravis UltraSound Classic sound card. - - port - port # for GF1 chip (0x220,0x230,0x240,0x250,0x260) - irq - IRQ # for GF1 chip (3,5,9,11,12,15) - dma1 - DMA # for GF1 chip (1,3,5,6,7) - dma2 - DMA # for GF1 chip (1,3,5,6,7,-1=disable) - joystick_dac - 0 to 31, (0.59V-4.52V or 0.389V-2.98V) - voices - GF1 voices limit (14-32) - pcm_voices - reserved PCM voices - - This module supports multiple cards and autoprobe. - - Module snd-gusextreme - --------------------- - - Module for Gravis UltraSound Extreme (Synergy ViperMax) sound card. - - port - port # for ES-1688 chip (0x220,0x230,0x240,0x250,0x260) - gf1_port - port # for GF1 chip (0x210,0x220,0x230,0x240,0x250,0x260,0x270) - mpu_port - port # for MPU-401 port (0x300,0x310,0x320,0x330), -1 = disable - irq - IRQ # for ES-1688 chip (5,7,9,10) - gf1_irq - IRQ # for GF1 chip (3,5,9,11,12,15) - mpu_irq - IRQ # for MPU-401 port (5,7,9,10) - dma8 - DMA # for ES-1688 chip (0,1,3) - dma1 - DMA # for GF1 chip (1,3,5,6,7) - joystick_dac - 0 to 31, (0.59V-4.52V or 0.389V-2.98V) - voices - GF1 voices limit (14-32) - pcm_voices - reserved PCM voices - - This module supports multiple cards and autoprobe (without MPU-401 port). - - Module snd-gusmax - ----------------- - - Module for Gravis UltraSound MAX sound card. - - port - port # for GF1 chip (0x220,0x230,0x240,0x250,0x260) - irq - IRQ # for GF1 chip (3,5,9,11,12,15) - dma1 - DMA # for GF1 chip (1,3,5,6,7) - dma2 - DMA # for GF1 chip (1,3,5,6,7,-1=disable) - joystick_dac - 0 to 31, (0.59V-4.52V or 0.389V-2.98V) - voices - GF1 voices limit (14-32) - pcm_voices - reserved PCM voices - - This module supports multiple cards and autoprobe. - - Module snd-hda-intel - -------------------- - - Module for Intel HD Audio (ICH6, ICH6M, ESB2, ICH7, ICH8, ICH9, ICH10, - PCH, SCH), - ATI SB450, SB600, R600, RS600, RS690, RS780, RV610, RV620, - RV630, RV635, RV670, RV770, - VIA VT8251/VT8237A, - SIS966, ULI M5461 - - [Multiple options for each card instance] - model - force the model name - position_fix - Fix DMA pointer - -1 = system default: choose appropriate one per controller - hardware - 0 = auto: falls back to LPIB when POSBUF doesn't work - 1 = use LPIB - 2 = POSBUF: use position buffer - 3 = VIACOMBO: VIA-specific workaround for capture - 4 = COMBO: use LPIB for playback, auto for capture stream - probe_mask - Bitmask to probe codecs (default = -1, meaning all slots) - When the bit 8 (0x100) is set, the lower 8 bits are used - as the "fixed" codec slots; i.e. the driver probes the - slots regardless what hardware reports back - probe_only - Only probing and no codec initialization (default=off); - Useful to check the initial codec status for debugging - bdl_pos_adj - Specifies the DMA IRQ timing delay in samples. - Passing -1 will make the driver to choose the appropriate - value based on the controller chip. - patch - Specifies the early "patch" files to modify the HD-audio - setup before initializing the codecs. This option is - available only when CONFIG_SND_HDA_PATCH_LOADER=y is set. - See HD-Audio.txt for details. - beep_mode - Selects the beep registration mode (0=off, 1=on); default - value is set via CONFIG_SND_HDA_INPUT_BEEP_MODE kconfig. - - [Single (global) options] - single_cmd - Use single immediate commands to communicate with - codecs (for debugging only) - enable_msi - Enable Message Signaled Interrupt (MSI) (default = off) - power_save - Automatic power-saving timeout (in second, 0 = - disable) - power_save_controller - Reset HD-audio controller in power-saving mode - (default = on) - align_buffer_size - Force rounding of buffer/period sizes to multiples - of 128 bytes. This is more efficient in terms of memory - access but isn't required by the HDA spec and prevents - users from specifying exact period/buffer sizes. - (default = on) - snoop - Enable/disable snooping (default = on) - - This module supports multiple cards and autoprobe. - - See Documentation/sound/alsa/HD-Audio.txt for more details about - HD-audio driver. - - Each codec may have a model table for different configurations. - If your machine isn't listed there, the default (usually minimal) - configuration is set up. You can pass "model=" option to - specify a certain model in such a case. There are different - models depending on the codec chip. The list of available models - is found in HD-Audio-Models.txt - - The model name "generic" is treated as a special case. When this - model is given, the driver uses the generic codec parser without - "codec-patch". It's sometimes good for testing and debugging. - - If the default configuration doesn't work and one of the above - matches with your device, report it together with alsa-info.sh - output (with --no-upload option) to kernel bugzilla or alsa-devel - ML (see the section "Links and Addresses"). - - power_save and power_save_controller options are for power-saving - mode. See powersave.txt for details. - - Note 2: If you get click noises on output, try the module option - position_fix=1 or 2. position_fix=1 will use the SD_LPIB - register value without FIFO size correction as the current - DMA pointer. position_fix=2 will make the driver to use - the position buffer instead of reading SD_LPIB register. - (Usually SD_LPIB register is more accurate than the - position buffer.) - - position_fix=3 is specific to VIA devices. The position - of the capture stream is checked from both LPIB and POSBUF - values. position_fix=4 is a combination mode, using LPIB - for playback and POSBUF for capture. - - NB: If you get many "azx_get_response timeout" messages at - loading, it's likely a problem of interrupts (e.g. ACPI irq - routing). Try to boot with options like "pci=noacpi". Also, you - can try "single_cmd=1" module option. This will switch the - communication method between HDA controller and codecs to the - single immediate commands instead of CORB/RIRB. Basically, the - single command mode is provided only for BIOS, and you won't get - unsolicited events, too. But, at least, this works independently - from the irq. Remember this is a last resort, and should be - avoided as much as possible... - - MORE NOTES ON "azx_get_response timeout" PROBLEMS: - On some hardware, you may need to add a proper probe_mask option - to avoid the "azx_get_response timeout" problem above, instead. - This occurs when the access to non-existing or non-working codec slot - (likely a modem one) causes a stall of the communication via HD-audio - bus. You can see which codec slots are probed by enabling - CONFIG_SND_DEBUG_VERBOSE, or simply from the file name of the codec - proc files. Then limit the slots to probe by probe_mask option. - For example, probe_mask=1 means to probe only the first slot, and - probe_mask=4 means only the third slot. - - The power-management is supported. - - Module snd-hdsp - --------------- - - Module for RME Hammerfall DSP audio interface(s) - - This module supports multiple cards. - - Note: The firmware data can be automatically loaded via hotplug - when CONFIG_FW_LOADER is set. Otherwise, you need to load - the firmware via hdsploader utility included in alsa-tools - package. - The firmware data is found in alsa-firmware package. - - Note: snd-page-alloc module does the job which snd-hammerfall-mem - module did formerly. It will allocate the buffers in advance - when any HDSP cards are found. To make the buffer - allocation sure, load snd-page-alloc module in the early - stage of boot sequence. See "Early Buffer Allocation" - section. - - Module snd-hdspm - ---------------- - - Module for RME HDSP MADI board. - - precise_ptr - Enable precise pointer, or disable. - line_outs_monitor - Send playback streams to analog outs by default. - enable_monitor - Enable Analog Out on Channel 63/64 by default. - - See hdspm.txt for details. - - Module snd-ice1712 - ------------------ - - Module for Envy24 (ICE1712) based PCI sound cards. - * MidiMan M Audio Delta 1010 - * MidiMan M Audio Delta 1010LT - * MidiMan M Audio Delta DiO 2496 - * MidiMan M Audio Delta 66 - * MidiMan M Audio Delta 44 - * MidiMan M Audio Delta 410 - * MidiMan M Audio Audiophile 2496 - * TerraTec EWS 88MT - * TerraTec EWS 88D - * TerraTec EWX 24/96 - * TerraTec DMX 6Fire - * TerraTec Phase 88 - * Hoontech SoundTrack DSP 24 - * Hoontech SoundTrack DSP 24 Value - * Hoontech SoundTrack DSP 24 Media 7.1 - * Event Electronics, EZ8 - * Digigram VX442 - * Lionstracs, Mediastaton - * Terrasoniq TS 88 - - model - Use the given board model, one of the following: - delta1010, dio2496, delta66, delta44, audiophile, delta410, - delta1010lt, vx442, ewx2496, ews88mt, ews88mt_new, ews88d, - dmx6fire, dsp24, dsp24_value, dsp24_71, ez8, - phase88, mediastation - omni - Omni I/O support for MidiMan M-Audio Delta44/66 - cs8427_timeout - reset timeout for the CS8427 chip (S/PDIF transceiver) - in msec resolution, default value is 500 (0.5 sec) - - This module supports multiple cards and autoprobe. Note: The consumer part - is not used with all Envy24 based cards (for example in the MidiMan Delta - serie). - - Note: The supported board is detected by reading EEPROM or PCI - SSID (if EEPROM isn't available). You can override the - model by passing "model" module option in case that the - driver isn't configured properly or you want to try another - type for testing. - - Module snd-ice1724 - ------------------ - - Module for Envy24HT (VT/ICE1724), Envy24PT (VT1720) based PCI sound cards. - * MidiMan M Audio Revolution 5.1 - * MidiMan M Audio Revolution 7.1 - * MidiMan M Audio Audiophile 192 - * AMP Ltd AUDIO2000 - * TerraTec Aureon 5.1 Sky - * TerraTec Aureon 7.1 Space - * TerraTec Aureon 7.1 Universe - * TerraTec Phase 22 - * TerraTec Phase 28 - * AudioTrak Prodigy 7.1 - * AudioTrak Prodigy 7.1 LT - * AudioTrak Prodigy 7.1 XT - * AudioTrak Prodigy 7.1 HIFI - * AudioTrak Prodigy 7.1 HD2 - * AudioTrak Prodigy 192 - * Pontis MS300 - * Albatron K8X800 Pro II - * Chaintech ZNF3-150 - * Chaintech ZNF3-250 - * Chaintech 9CJS - * Chaintech AV-710 - * Shuttle SN25P - * Onkyo SE-90PCI - * Onkyo SE-200PCI - * ESI Juli@ - * ESI Maya44 - * Hercules Fortissimo IV - * EGO-SYS WaveTerminal 192M - - model - Use the given board model, one of the following: - revo51, revo71, amp2000, prodigy71, prodigy71lt, - prodigy71xt, prodigy71hifi, prodigyhd2, prodigy192, - juli, aureon51, aureon71, universe, ap192, k8x800, - phase22, phase28, ms300, av710, se200pci, se90pci, - fortissimo4, sn25p, WT192M, maya44 - - This module supports multiple cards and autoprobe. - - Note: The supported board is detected by reading EEPROM or PCI - SSID (if EEPROM isn't available). You can override the - model by passing "model" module option in case that the - driver isn't configured properly or you want to try another - type for testing. - - Module snd-indigo - ----------------- - - Module for Echoaudio Indigo - - This module supports multiple cards. - The driver requires the firmware loader support on kernel. - - Module snd-indigodj - ------------------- - - Module for Echoaudio Indigo DJ - - This module supports multiple cards. - The driver requires the firmware loader support on kernel. - - Module snd-indigoio - ------------------- - - Module for Echoaudio Indigo IO - - This module supports multiple cards. - The driver requires the firmware loader support on kernel. - - Module snd-intel8x0 - ------------------- - - Module for AC'97 motherboards from Intel and compatibles. - * Intel i810/810E, i815, i820, i830, i84x, MX440 - ICH5, ICH6, ICH7, 6300ESB, ESB2 - * SiS 7012 (SiS 735) - * NVidia NForce, NForce2, NForce3, MCP04, CK804 - CK8, CK8S, MCP501 - * AMD AMD768, AMD8111 - * ALi m5455 - - ac97_clock - AC'97 codec clock base (0 = auto-detect) - ac97_quirk - AC'97 workaround for strange hardware - See "AC97 Quirk Option" section below. - buggy_irq - Enable workaround for buggy interrupts on some - motherboards (default yes on nForce chips, - otherwise off) - buggy_semaphore - Enable workaround for hardware with buggy - semaphores (e.g. on some ASUS laptops) - (default off) - spdif_aclink - Use S/PDIF over AC-link instead of direct connection - from the controller chip - (0 = off, 1 = on, -1 = default) - - This module supports one chip and autoprobe. - - Note: the latest driver supports auto-detection of chip clock. - if you still encounter too fast playback, specify the clock - explicitly via the module option "ac97_clock=41194". - - Joystick/MIDI ports are not supported by this driver. If your - motherboard has these devices, use the ns558 or snd-mpu401 - modules, respectively. - - The power-management is supported. - - Module snd-intel8x0m - -------------------- - - Module for Intel ICH (i8x0) chipset MC97 modems. - * Intel i810/810E, i815, i820, i830, i84x, MX440 - ICH5, ICH6, ICH7 - * SiS 7013 (SiS 735) - * NVidia NForce, NForce2, NForce2s, NForce3 - * AMD AMD8111 - * ALi m5455 - - ac97_clock - AC'97 codec clock base (0 = auto-detect) - - This module supports one card and autoprobe. - - Note: The default index value of this module is -2, i.e. the first - slot is excluded. - - The power-management is supported. - - Module snd-interwave - -------------------- - - Module for Gravis UltraSound PnP, Dynasonic 3-D/Pro, STB Sound Rage 32 - and other sound cards based on AMD InterWave (tm) chip. - - joystick_dac - 0 to 31, (0.59V-4.52V or 0.389V-2.98V) - midi - 1 = MIDI UART enable, 0 = MIDI UART disable (default) - pcm_voices - reserved PCM voices for the synthesizer (default 2) - effect - 1 = InterWave effects enable (default 0); - requires 8 voices - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - - with isapnp=0, the following options are available: - - port - port # for InterWave chip (0x210,0x220,0x230,0x240,0x250,0x260) - irq - IRQ # for InterWave chip (3,5,9,11,12,15) - dma1 - DMA # for InterWave chip (0,1,3,5,6,7) - dma2 - DMA # for InterWave chip (0,1,3,5,6,7,-1=disable) - - This module supports multiple cards, autoprobe and ISA PnP. - - Module snd-interwave-stb - ------------------------ - - Module for UltraSound 32-Pro (sound card from STB used by Compaq) - and other sound cards based on AMD InterWave (tm) chip with TEA6330T - circuit for extended control of bass, treble and master volume. - - joystick_dac - 0 to 31, (0.59V-4.52V or 0.389V-2.98V) - midi - 1 = MIDI UART enable, 0 = MIDI UART disable (default) - pcm_voices - reserved PCM voices for the synthesizer (default 2) - effect - 1 = InterWave effects enable (default 0); - requires 8 voices - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - - with isapnp=0, the following options are available: - - port - port # for InterWave chip (0x210,0x220,0x230,0x240,0x250,0x260) - port_tc - tone control (i2c bus) port # for TEA6330T chip (0x350,0x360,0x370,0x380) - irq - IRQ # for InterWave chip (3,5,9,11,12,15) - dma1 - DMA # for InterWave chip (0,1,3,5,6,7) - dma2 - DMA # for InterWave chip (0,1,3,5,6,7,-1=disable) - - This module supports multiple cards, autoprobe and ISA PnP. - - Module snd-jazz16 - ------------------- - - Module for Media Vision Jazz16 chipset. The chipset consists of 3 chips: - MVD1216 + MVA416 + MVA514. - - port - port # for SB DSP chip (0x210,0x220,0x230,0x240,0x250,0x260) - irq - IRQ # for SB DSP chip (3,5,7,9,10,15) - dma8 - DMA # for SB DSP chip (1,3) - dma16 - DMA # for SB DSP chip (5,7) - mpu_port - MPU-401 port # (0x300,0x310,0x320,0x330) - mpu_irq - MPU-401 irq # (2,3,5,7) - - This module supports multiple cards. - - Module snd-korg1212 - ------------------- - - Module for Korg 1212 IO PCI card - - This module supports multiple cards. - - Module snd-layla20 - ------------------ - - Module for Echoaudio Layla20 - - This module supports multiple cards. - The driver requires the firmware loader support on kernel. - - Module snd-layla24 - ------------------ - - Module for Echoaudio Layla24 - - This module supports multiple cards. - The driver requires the firmware loader support on kernel. - - Module snd-lola - --------------- - - Module for Digigram Lola PCI-e boards - - This module supports multiple cards. - - Module snd-lx6464es - ------------------- - - Module for Digigram LX6464ES boards - - This module supports multiple cards. - - Module snd-maestro3 - ------------------- - - Module for Allegro/Maestro3 chips - - external_amp - enable external amp (enabled by default) - amp_gpio - GPIO pin number for external amp (0-15) or - -1 for default pin (8 for allegro, 1 for - others) - - This module supports autoprobe and multiple chips. - - Note: the binding of amplifier is dependent on hardware. - If there is no sound even though all channels are unmuted, try to - specify other gpio connection via amp_gpio option. - For example, a Panasonic notebook might need "amp_gpio=0x0d" - option. - - The power-management is supported. - - Module snd-mia - --------------- - - Module for Echoaudio Mia - - This module supports multiple cards. - The driver requires the firmware loader support on kernel. - - Module snd-miro - --------------- - - Module for Miro soundcards: miroSOUND PCM 1 pro, - miroSOUND PCM 12, - miroSOUND PCM 20 Radio. - - port - Port # (0x530,0x604,0xe80,0xf40) - irq - IRQ # (5,7,9,10,11) - dma1 - 1st dma # (0,1,3) - dma2 - 2nd dma # (0,1) - mpu_port - MPU-401 port # (0x300,0x310,0x320,0x330) - mpu_irq - MPU-401 irq # (5,7,9,10) - fm_port - FM Port # (0x388) - wss - enable WSS mode - ide - enable onboard ide support - - Module snd-mixart - ----------------- - - Module for Digigram miXart8 sound cards. - - This module supports multiple cards. - Note: One miXart8 board will be represented as 4 alsa cards. - See MIXART.txt for details. - - When the driver is compiled as a module and the hotplug firmware - is supported, the firmware data is loaded via hotplug automatically. - Install the necessary firmware files in alsa-firmware package. - When no hotplug fw loader is available, you need to load the - firmware via mixartloader utility in alsa-tools package. - - Module snd-mona - --------------- - - Module for Echoaudio Mona - - This module supports multiple cards. - The driver requires the firmware loader support on kernel. - - Module snd-mpu401 - ----------------- - - Module for MPU-401 UART devices. - - port - port number or -1 (disable) - irq - IRQ number or -1 (disable) - pnp - PnP detection - 0 = disable, 1 = enable (default) - - This module supports multiple devices and PnP. - - Module snd-msnd-classic - ----------------------- - - Module for Turtle Beach MultiSound Classic, Tahiti or Monterey - soundcards. - - io - Port # for msnd-classic card - irq - IRQ # for msnd-classic card - mem - Memory address (0xb0000, 0xc8000, 0xd0000, 0xd8000, - 0xe0000 or 0xe8000) - write_ndelay - enable write ndelay (default = 1) - calibrate_signal - calibrate signal (default = 0) - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - digital - Digital daughterboard present (default = 0) - cfg - Config port (0x250, 0x260 or 0x270) default = PnP - reset - Reset all devices - mpu_io - MPU401 I/O port - mpu_irq - MPU401 irq# - ide_io0 - IDE port #0 - ide_io1 - IDE port #1 - ide_irq - IDE irq# - joystick_io - Joystick I/O port - - The driver requires firmware files "turtlebeach/msndinit.bin" and - "turtlebeach/msndperm.bin" in the proper firmware directory. - - See Documentation/sound/oss/MultiSound for important information - about this driver. Note that it has been discontinued, but the - Voyetra Turtle Beach knowledge base entry for it is still available - at - http://www.turtlebeach.com - - Module snd-msnd-pinnacle - ------------------------ - - Module for Turtle Beach MultiSound Pinnacle/Fiji soundcards. - - io - Port # for pinnacle/fiji card - irq - IRQ # for pinnalce/fiji card - mem - Memory address (0xb0000, 0xc8000, 0xd0000, 0xd8000, - 0xe0000 or 0xe8000) - write_ndelay - enable write ndelay (default = 1) - calibrate_signal - calibrate signal (default = 0) - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - - The driver requires firmware files "turtlebeach/pndspini.bin" and - "turtlebeach/pndsperm.bin" in the proper firmware directory. - - Module snd-mtpav - ---------------- - - Module for MOTU MidiTimePiece AV multiport MIDI (on the parallel - port). - - port - I/O port # for MTPAV (0x378,0x278, default=0x378) - irq - IRQ # for MTPAV (7,5, default=7) - hwports - number of supported hardware ports, default=8. - - Module supports only 1 card. This module has no enable option. - - Module snd-mts64 - ---------------- - - Module for Ego Systems (ESI) Miditerminal 4140 - - This module supports multiple devices. - Requires parport (CONFIG_PARPORT). - - Module snd-nm256 - ---------------- - - Module for NeoMagic NM256AV/ZX chips - - playback_bufsize - max playback frame size in kB (4-128kB) - capture_bufsize - max capture frame size in kB (4-128kB) - force_ac97 - 0 or 1 (disabled by default) - buffer_top - specify buffer top address - use_cache - 0 or 1 (disabled by default) - vaio_hack - alias buffer_top=0x25a800 - reset_workaround - enable AC97 RESET workaround for some laptops - reset_workaround2 - enable extended AC97 RESET workaround for some - other laptops - - This module supports one chip and autoprobe. - - The power-management is supported. - - Note: on some notebooks the buffer address cannot be detected - automatically, or causes hang-up during initialization. - In such a case, specify the buffer top address explicitly via - the buffer_top option. - For example, - Sony F250: buffer_top=0x25a800 - Sony F270: buffer_top=0x272800 - The driver supports only ac97 codec. It's possible to force - to initialize/use ac97 although it's not detected. In such a - case, use force_ac97=1 option - but *NO* guarantee whether it - works! - - Note: The NM256 chip can be linked internally with non-AC97 - codecs. This driver supports only the AC97 codec, and won't work - with machines with other (most likely CS423x or OPL3SAx) chips, - even though the device is detected in lspci. In such a case, try - other drivers, e.g. snd-cs4232 or snd-opl3sa2. Some has ISA-PnP - but some doesn't have ISA PnP. You'll need to specify isapnp=0 - and proper hardware parameters in the case without ISA PnP. - - Note: some laptops need a workaround for AC97 RESET. For the - known hardware like Dell Latitude LS and Sony PCG-F305, this - workaround is enabled automatically. For other laptops with a - hard freeze, you can try reset_workaround=1 option. - - Note: Dell Latitude CSx laptops have another problem regarding - AC97 RESET. On these laptops, reset_workaround2 option is - turned on as default. This option is worth to try if the - previous reset_workaround option doesn't help. - - Note: This driver is really crappy. It's a porting from the - OSS driver, which is a result of black-magic reverse engineering. - The detection of codec will fail if the driver is loaded *after* - X-server as described above. You might be able to force to load - the module, but it may result in hang-up. Hence, make sure that - you load this module *before* X if you encounter this kind of - problem. - - Module snd-opl3sa2 - ------------------ - - Module for Yamaha OPL3-SA2/SA3 sound cards. - - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - - with isapnp=0, the following options are available: - - port - control port # for OPL3-SA chip (0x370) - sb_port - SB port # for OPL3-SA chip (0x220,0x240) - wss_port - WSS port # for OPL3-SA chip (0x530,0xe80,0xf40,0x604) - midi_port - port # for MPU-401 UART (0x300,0x330), -1 = disable - fm_port - FM port # for OPL3-SA chip (0x388), -1 = disable - irq - IRQ # for OPL3-SA chip (5,7,9,10) - dma1 - first DMA # for Yamaha OPL3-SA chip (0,1,3) - dma2 - second DMA # for Yamaha OPL3-SA chip (0,1,3), -1 = disable - - This module supports multiple cards and ISA PnP. It does not support - autoprobe (if ISA PnP is not used) thus all ports must be specified!!! - - The power-management is supported. - - Module snd-opti92x-ad1848 - ------------------------- - - Module for sound cards based on OPTi 82c92x and Analog Devices AD1848 chips. - Module works with OAK Mozart cards as well. - - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - - with isapnp=0, the following options are available: - - port - port # for WSS chip (0x530,0xe80,0xf40,0x604) - mpu_port - port # for MPU-401 UART (0x300,0x310,0x320,0x330) - fm_port - port # for OPL3 device (0x388) - irq - IRQ # for WSS chip (5,7,9,10,11) - mpu_irq - IRQ # for MPU-401 UART (5,7,9,10) - dma1 - first DMA # for WSS chip (0,1,3) - - This module supports only one card, autoprobe and PnP. - - Module snd-opti92x-cs4231 - ------------------------- - - Module for sound cards based on OPTi 82c92x and Crystal CS4231 chips. - - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - - with isapnp=0, the following options are available: - - port - port # for WSS chip (0x530,0xe80,0xf40,0x604) - mpu_port - port # for MPU-401 UART (0x300,0x310,0x320,0x330) - fm_port - port # for OPL3 device (0x388) - irq - IRQ # for WSS chip (5,7,9,10,11) - mpu_irq - IRQ # for MPU-401 UART (5,7,9,10) - dma1 - first DMA # for WSS chip (0,1,3) - dma2 - second DMA # for WSS chip (0,1,3) - - This module supports only one card, autoprobe and PnP. - - Module snd-opti93x - ------------------ - - Module for sound cards based on OPTi 82c93x chips. - - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - - with isapnp=0, the following options are available: - - port - port # for WSS chip (0x530,0xe80,0xf40,0x604) - mpu_port - port # for MPU-401 UART (0x300,0x310,0x320,0x330) - fm_port - port # for OPL3 device (0x388) - irq - IRQ # for WSS chip (5,7,9,10,11) - mpu_irq - IRQ # for MPU-401 UART (5,7,9,10) - dma1 - first DMA # for WSS chip (0,1,3) - dma2 - second DMA # for WSS chip (0,1,3) - - This module supports only one card, autoprobe and PnP. - - Module snd-oxygen - ----------------- - - Module for sound cards based on the C-Media CMI8786/8787/8788 chip: - * Asound A-8788 - * Asus Xonar DG/DGX - * AuzenTech X-Meridian - * AuzenTech X-Meridian 2G - * Bgears b-Enspirer - * Club3D Theatron DTS - * HT-Omega Claro (plus) - * HT-Omega Claro halo (XT) - * Kuroutoshikou CMI8787-HG2PCI - * Razer Barracuda AC-1 - * Sondigo Inferno - * TempoTec HiFier Fantasia - * TempoTec HiFier Serenade - - This module supports autoprobe and multiple cards. - - Module snd-pcsp - ----------------- - - Module for internal PC-Speaker. - - nopcm - Disable PC-Speaker PCM sound. Only beeps remain. - nforce_wa - enable NForce chipset workaround. Expect bad sound. - - This module supports system beeps, some kind of PCM playback and - even a few mixer controls. - - Module snd-pcxhr - ---------------- - - Module for Digigram PCXHR boards - - This module supports multiple cards. - - Module snd-portman2x4 - --------------------- - - Module for Midiman Portman 2x4 parallel port MIDI interface - - This module supports multiple cards. - - Module snd-powermac (on ppc only) - --------------------------------- - - Module for PowerMac, iMac and iBook on-board soundchips - - enable_beep - enable beep using PCM (enabled as default) - - Module supports autoprobe a chip. - - Note: the driver may have problems regarding endianness. - - The power-management is supported. - - Module snd-pxa2xx-ac97 (on arm only) - ------------------------------------ - - Module for AC97 driver for the Intel PXA2xx chip - - For ARM architecture only. - - The power-management is supported. - - Module snd-riptide - ------------------ - - Module for Conexant Riptide chip - - joystick_port - Joystick port # (default: 0x200) - mpu_port - MPU401 port # (default: 0x330) - opl3_port - OPL3 port # (default: 0x388) - - This module supports multiple cards. - The driver requires the firmware loader support on kernel. - You need to install the firmware file "riptide.hex" to the standard - firmware path (e.g. /lib/firmware). - - Module snd-rme32 - ---------------- - - Module for RME Digi32, Digi32 Pro and Digi32/8 (Sek'd Prodif32, - Prodif96 and Prodif Gold) sound cards. - - This module supports multiple cards. - - Module snd-rme96 - ---------------- - - Module for RME Digi96, Digi96/8 and Digi96/8 PRO/PAD/PST sound cards. - - This module supports multiple cards. - - Module snd-rme9652 - ------------------ - - Module for RME Digi9652 (Hammerfall, Hammerfall-Light) sound cards. - - precise_ptr - Enable precise pointer (doesn't work reliably). - (default = 0) - - This module supports multiple cards. - - Note: snd-page-alloc module does the job which snd-hammerfall-mem - module did formerly. It will allocate the buffers in advance - when any RME9652 cards are found. To make the buffer - allocation sure, load snd-page-alloc module in the early - stage of boot sequence. See "Early Buffer Allocation" - section. - - Module snd-sa11xx-uda1341 (on arm only) - --------------------------------------- - - Module for Philips UDA1341TS on Compaq iPAQ H3600 sound card. - - Module supports only one card. - Module has no enable and index options. - - The power-management is supported. - - Module snd-sb8 - -------------- - - Module for 8-bit SoundBlaster cards: SoundBlaster 1.0, - SoundBlaster 2.0, - SoundBlaster Pro - - port - port # for SB DSP chip (0x220,0x240,0x260) - irq - IRQ # for SB DSP chip (5,7,9,10) - dma8 - DMA # for SB DSP chip (1,3) - - This module supports multiple cards and autoprobe. - - The power-management is supported. - - Module snd-sb16 and snd-sbawe - ----------------------------- - - Module for 16-bit SoundBlaster cards: SoundBlaster 16 (PnP), - SoundBlaster AWE 32 (PnP), - SoundBlaster AWE 64 PnP - - mic_agc - Mic Auto-Gain-Control - 0 = disable, 1 = enable (default) - csp - ASP/CSP chip support - 0 = disable (default), 1 = enable - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - - with isapnp=0, the following options are available: - - port - port # for SB DSP 4.x chip (0x220,0x240,0x260) - mpu_port - port # for MPU-401 UART (0x300,0x330), -1 = disable - awe_port - base port # for EMU8000 synthesizer (0x620,0x640,0x660) - (snd-sbawe module only) - irq - IRQ # for SB DSP 4.x chip (5,7,9,10) - dma8 - 8-bit DMA # for SB DSP 4.x chip (0,1,3) - dma16 - 16-bit DMA # for SB DSP 4.x chip (5,6,7) - - This module supports multiple cards, autoprobe and ISA PnP. - - Note: To use Vibra16X cards in 16-bit half duplex mode, you must - disable 16bit DMA with dma16 = -1 module parameter. - Also, all Sound Blaster 16 type cards can operate in 16-bit - half duplex mode through 8-bit DMA channel by disabling their - 16-bit DMA channel. - - The power-management is supported. - - Module snd-sc6000 - ----------------- - - Module for Gallant SC-6000 soundcard and later models: SC-6600 - and SC-7000. - - port - Port # (0x220 or 0x240) - mss_port - MSS Port # (0x530 or 0xe80) - irq - IRQ # (5,7,9,10,11) - mpu_irq - MPU-401 IRQ # (5,7,9,10) ,0 - no MPU-401 irq - dma - DMA # (1,3,0) - joystick - Enable gameport - 0 = disable (default), 1 = enable - - This module supports multiple cards. - - This card is also known as Audio Excel DSP 16 or Zoltrix AV302. - - Module snd-sscape - ----------------- - - Module for ENSONIQ SoundScape cards. - - port - Port # (PnP setup) - wss_port - WSS Port # (PnP setup) - irq - IRQ # (PnP setup) - mpu_irq - MPU-401 IRQ # (PnP setup) - dma - DMA # (PnP setup) - dma2 - 2nd DMA # (PnP setup, -1 to disable) - joystick - Enable gameport - 0 = disable (default), 1 = enable - - This module supports multiple cards. - - The driver requires the firmware loader support on kernel. - - Module snd-sun-amd7930 (on sparc only) - -------------------------------------- - - Module for AMD7930 sound chips found on Sparcs. - - This module supports multiple cards. - - Module snd-sun-cs4231 (on sparc only) - ------------------------------------- - - Module for CS4231 sound chips found on Sparcs. - - This module supports multiple cards. - - Module snd-sun-dbri (on sparc only) - ----------------------------------- - - Module for DBRI sound chips found on Sparcs. - - This module supports multiple cards. - - Module snd-wavefront - -------------------- - - Module for Turtle Beach Maui, Tropez and Tropez+ sound cards. - - use_cs4232_midi - Use CS4232 MPU-401 interface - (inaccessibly located inside your computer) - isapnp - ISA PnP detection - 0 = disable, 1 = enable (default) - - with isapnp=0, the following options are available: - - cs4232_pcm_port - Port # for CS4232 PCM interface. - cs4232_pcm_irq - IRQ # for CS4232 PCM interface (5,7,9,11,12,15). - cs4232_mpu_port - Port # for CS4232 MPU-401 interface. - cs4232_mpu_irq - IRQ # for CS4232 MPU-401 interface (9,11,12,15). - ics2115_port - Port # for ICS2115 - ics2115_irq - IRQ # for ICS2115 - fm_port - FM OPL-3 Port # - dma1 - DMA1 # for CS4232 PCM interface. - dma2 - DMA2 # for CS4232 PCM interface. - - The below are options for wavefront_synth features: - wf_raw - Assume that we need to boot the OS (default:no) - If yes, then during driver loading, the state of the board is - ignored, and we reset the board and load the firmware anyway. - fx_raw - Assume that the FX process needs help (default:yes) - If false, we'll leave the FX processor in whatever state it is - when the driver is loaded. The default is to download the - microprogram and associated coefficients to set it up for - "default" operation, whatever that means. - debug_default - Debug parameters for card initialization - wait_usecs - How long to wait without sleeping, usecs - (default:150) - This magic number seems to give pretty optimal throughput - based on my limited experimentation. - If you want to play around with it and find a better value, be - my guest. Remember, the idea is to get a number that causes us - to just busy wait for as many WaveFront commands as possible, - without coming up with a number so large that we hog the whole - CPU. - Specifically, with this number, out of about 134,000 status - waits, only about 250 result in a sleep. - sleep_interval - How long to sleep when waiting for reply - (default: 100) - sleep_tries - How many times to try sleeping during a wait - (default: 50) - ospath - Pathname to processed ICS2115 OS firmware - (default:wavefront.os) - The path name of the ISC2115 OS firmware. In the recent - version, it's handled via firmware loader framework, so it - must be installed in the proper path, typically, - /lib/firmware. - reset_time - How long to wait for a reset to take effect - (default:2) - ramcheck_time - How many seconds to wait for the RAM test - (default:20) - osrun_time - How many seconds to wait for the ICS2115 OS - (default:10) - - This module supports multiple cards and ISA PnP. - - Note: the firmware file "wavefront.os" was located in the earlier - version in /etc. Now it's loaded via firmware loader, and - must be in the proper firmware path, such as /lib/firmware. - Copy (or symlink) the file appropriately if you get an error - regarding firmware downloading after upgrading the kernel. - - Module snd-sonicvibes - --------------------- - - Module for S3 SonicVibes PCI sound cards. - * PINE Schubert 32 PCI - - reverb - Reverb Enable - 1 = enable, 0 = disable (default) - - SoundCard must have onboard SRAM for this. - mge - Mic Gain Enable - 1 = enable, 0 = disable (default) - - This module supports multiple cards and autoprobe. - - Module snd-serial-u16550 - ------------------------ - - Module for UART16550A serial MIDI ports. - - port - port # for UART16550A chip - irq - IRQ # for UART16550A chip, -1 = poll mode - speed - speed in bauds (9600,19200,38400,57600,115200) - 38400 = default - base - base for divisor in bauds (57600,115200,230400,460800) - 115200 = default - outs - number of MIDI ports in a serial port (1-4) - 1 = default - adaptor - Type of adaptor. - 0 = Soundcanvas, 1 = MS-124T, 2 = MS-124W S/A, - 3 = MS-124W M/B, 4 = Generic - - This module supports multiple cards. This module does not support autoprobe - thus the main port must be specified!!! Other options are optional. - - Module snd-trident - ------------------ - - Module for Trident 4DWave DX/NX sound cards. - * Best Union Miss Melody 4DWave PCI - * HIS 4DWave PCI - * Warpspeed ONSpeed 4DWave PCI - * AzTech PCI 64-Q3D - * Addonics SV 750 - * CHIC True Sound 4Dwave - * Shark Predator4D-PCI - * Jaton SonicWave 4D - * SiS SI7018 PCI Audio - * Hoontech SoundTrack Digital 4DWave NX - - pcm_channels - max channels (voices) reserved for PCM - wavetable_size - max wavetable size in kB (4-?kb) - - This module supports multiple cards and autoprobe. - - The power-management is supported. - - Module snd-ua101 - ---------------- - - Module for the Edirol UA-101/UA-1000 audio/MIDI interfaces. - - This module supports multiple devices, autoprobe and hotplugging. - - Module snd-usb-audio - -------------------- - - Module for USB audio and USB MIDI devices. - - vid - Vendor ID for the device (optional) - pid - Product ID for the device (optional) - nrpacks - Max. number of packets per URB (default: 8) - device_setup - Device specific magic number (optional) - - Influence depends on the device - - Default: 0x0000 - ignore_ctl_error - Ignore any USB-controller regarding mixer - interface (default: no) - autoclock - Enable auto-clock selection for UAC2 devices - (default: yes) - quirk_alias - Quirk alias list, pass strings like - "0123abcd:5678beef", which applies the existing - quirk for the device 5678:beef to a new device - 0123:abcd. - - This module supports multiple devices, autoprobe and hotplugging. - - NB: nrpacks parameter can be modified dynamically via sysfs. - Don't put the value over 20. Changing via sysfs has no sanity - check. - NB: ignore_ctl_error=1 may help when you get an error at accessing - the mixer element such as URB error -22. This happens on some - buggy USB device or the controller. - NB: quirk_alias option is provided only for testing / development. - If you want to have a proper support, contact to upstream for - adding the matching quirk in the driver code statically. - - Module snd-usb-caiaq - -------------------- - - Module for caiaq UB audio interfaces, - * Native Instruments RigKontrol2 - * Native Instruments Kore Controller - * Native Instruments Audio Kontrol 1 - * Native Instruments Audio 8 DJ - - This module supports multiple devices, autoprobe and hotplugging. - - Module snd-usb-usx2y - -------------------- - - Module for Tascam USB US-122, US-224 and US-428 devices. - - This module supports multiple devices, autoprobe and hotplugging. - - Note: you need to load the firmware via usx2yloader utility included - in alsa-tools and alsa-firmware packages. - - Module snd-via82xx - ------------------ - - Module for AC'97 motherboards based on VIA 82C686A/686B, 8233, - 8233A, 8233C, 8235, 8237 (south) bridge. - - mpu_port - 0x300,0x310,0x320,0x330, otherwise obtain BIOS setup - [VIA686A/686B only] - joystick - Enable joystick (default off) [VIA686A/686B only] - ac97_clock - AC'97 codec clock base (default 48000Hz) - dxs_support - support DXS channels, - 0 = auto (default), 1 = enable, 2 = disable, - 3 = 48k only, 4 = no VRA, 5 = enable any sample - rate and different sample rates on different - channels - [VIA8233/C, 8235, 8237 only] - ac97_quirk - AC'97 workaround for strange hardware - See "AC97 Quirk Option" section below. - - This module supports one chip and autoprobe. - - Note: on some SMP motherboards like MSI 694D the interrupts might - not be generated properly. In such a case, please try to - set the SMP (or MPS) version on BIOS to 1.1 instead of - default value 1.4. Then the interrupt number will be - assigned under 15. You might also upgrade your BIOS. - - Note: VIA8233/5/7 (not VIA8233A) can support DXS (direct sound) - channels as the first PCM. On these channels, up to 4 - streams can be played at the same time, and the controller - can perform sample rate conversion with separate rates for - each channel. - As default (dxs_support = 0), 48k fixed rate is chosen - except for the known devices since the output is often - noisy except for 48k on some mother boards due to the - bug of BIOS. - Please try once dxs_support=5 and if it works on other - sample rates (e.g. 44.1kHz of mp3 playback), please let us - know the PCI subsystem vendor/device id's (output of - "lspci -nv"). - If dxs_support=5 does not work, try dxs_support=4; if it - doesn't work too, try dxs_support=1. (dxs_support=1 is - usually for old motherboards. The correct implemented - board should work with 4 or 5.) If it still doesn't - work and the default setting is ok, dxs_support=3 is the - right choice. If the default setting doesn't work at all, - try dxs_support=2 to disable the DXS channels. - In any cases, please let us know the result and the - subsystem vendor/device ids. See "Links and Addresses" - below. - - Note: for the MPU401 on VIA823x, use snd-mpu401 driver - additionally. The mpu_port option is for VIA686 chips only. - - The power-management is supported. - - Module snd-via82xx-modem - ------------------------ - - Module for VIA82xx AC97 modem - - ac97_clock - AC'97 codec clock base (default 48000Hz) - - This module supports one card and autoprobe. - - Note: The default index value of this module is -2, i.e. the first - slot is excluded. - - The power-management is supported. - - Module snd-virmidi - ------------------ - - Module for virtual rawmidi devices. - This module creates virtual rawmidi devices which communicate - to the corresponding ALSA sequencer ports. - - midi_devs - MIDI devices # (1-4, default=4) - - This module supports multiple cards. - - Module snd-virtuoso - ------------------- - - Module for sound cards based on the Asus AV66/AV100/AV200 chips, - i.e., Xonar D1, DX, D2, D2X, DS, DSX, Essence ST (Deluxe), - Essence STX (II), HDAV1.3 (Deluxe), and HDAV1.3 Slim. - - This module supports autoprobe and multiple cards. - - Module snd-vx222 - ---------------- - - Module for Digigram VX-Pocket VX222, V222 v2 and Mic cards. - - mic - Enable Microphone on V222 Mic (NYI) - ibl - Capture IBL size. (default = 0, minimum size) - - This module supports multiple cards. - - When the driver is compiled as a module and the hotplug firmware - is supported, the firmware data is loaded via hotplug automatically. - Install the necessary firmware files in alsa-firmware package. - When no hotplug fw loader is available, you need to load the - firmware via vxloader utility in alsa-tools package. To invoke - vxloader automatically, add the following to /etc/modprobe.d/alsa.conf - - install snd-vx222 /sbin/modprobe --first-time -i snd-vx222 && /usr/bin/vxloader - - (for 2.2/2.4 kernels, add "post-install /usr/bin/vxloader" to - /etc/modules.conf, instead.) - IBL size defines the interrupts period for PCM. The smaller size - gives smaller latency but leads to more CPU consumption, too. - The size is usually aligned to 126. As default (=0), the smallest - size is chosen. The possible IBL values can be found in - /proc/asound/cardX/vx-status proc file. - - The power-management is supported. - - Module snd-vxpocket - ------------------- - - Module for Digigram VX-Pocket VX2 and 440 PCMCIA cards. - - ibl - Capture IBL size. (default = 0, minimum size) - - This module supports multiple cards. The module is compiled only when - PCMCIA is supported on kernel. - - With the older 2.6.x kernel, to activate the driver via the card - manager, you'll need to set up /etc/pcmcia/vxpocket.conf. See the - sound/pcmcia/vx/vxpocket.c. 2.6.13 or later kernel requires no - longer require a config file. - - When the driver is compiled as a module and the hotplug firmware - is supported, the firmware data is loaded via hotplug automatically. - Install the necessary firmware files in alsa-firmware package. - When no hotplug fw loader is available, you need to load the - firmware via vxloader utility in alsa-tools package. - - About capture IBL, see the description of snd-vx222 module. - - Note: snd-vxp440 driver is merged to snd-vxpocket driver since - ALSA 1.0.10. - - The power-management is supported. - - Module snd-ymfpci - ----------------- - - Module for Yamaha PCI chips (YMF72x, YMF74x & YMF75x). - - mpu_port - 0x300,0x330,0x332,0x334, 0 (disable) by default, - 1 (auto-detect for YMF744/754 only) - fm_port - 0x388,0x398,0x3a0,0x3a8, 0 (disable) by default - 1 (auto-detect for YMF744/754 only) - joystick_port - 0x201,0x202,0x204,0x205, 0 (disable) by default, - 1 (auto-detect) - rear_switch - enable shared rear/line-in switch (bool) - - This module supports autoprobe and multiple chips. - - The power-management is supported. - - Module snd-pdaudiocf - -------------------- - - Module for Sound Core PDAudioCF sound card. - - The power-management is supported. - - -AC97 Quirk Option -================= - -The ac97_quirk option is used to enable/override the workaround for -specific devices on drivers for on-board AC'97 controllers like -snd-intel8x0. Some hardware have swapped output pins between Master -and Headphone, or Surround (thanks to confusion of AC'97 -specifications from version to version :-) - -The driver provides the auto-detection of known problematic devices, -but some might be unknown or wrongly detected. In such a case, pass -the proper value with this option. - -The following strings are accepted: - - default Don't override the default setting - - none Disable the quirk - - hp_only Bind Master and Headphone controls as a single control - - swap_hp Swap headphone and master controls - - swap_surround Swap master and surround controls - - ad_sharing For AD1985, turn on OMS bit and use headphone - - alc_jack For ALC65x, turn on the jack sense mode - - inv_eapd Inverted EAPD implementation - - mute_led Bind EAPD bit for turning on/off mute LED - -For backward compatibility, the corresponding integer value -1, 0, -... are accepted, too. - -For example, if "Master" volume control has no effect on your device -but only "Headphone" does, pass ac97_quirk=hp_only module option. - - -Configuring Non-ISAPNP Cards -============================ - -When the kernel is configured with ISA-PnP support, the modules -supporting the isapnp cards will have module options "isapnp". -If this option is set, *only* the ISA-PnP devices will be probed. -For probing the non ISA-PnP cards, you have to pass "isapnp=0" option -together with the proper i/o and irq configuration. - -When the kernel is configured without ISA-PnP support, isapnp option -will be not built in. - - -Module Autoloading Support -========================== - -The ALSA drivers can be loaded automatically on demand by defining -module aliases. The string 'snd-card-%1' is requested for ALSA native -devices where %i is sound card number from zero to seven. - -To auto-load an ALSA driver for OSS services, define the string -'sound-slot-%i' where %i means the slot number for OSS, which -corresponds to the card index of ALSA. Usually, define this -as the same card module. - -An example configuration for a single emu10k1 card is like below: ------ /etc/modprobe.d/alsa.conf -alias snd-card-0 snd-emu10k1 -alias sound-slot-0 snd-emu10k1 ------ /etc/modprobe.d/alsa.conf - -The available number of auto-loaded sound cards depends on the module -option "cards_limit" of snd module. As default it's set to 1. -To enable the auto-loading of multiple cards, specify the number of -sound cards in that option. - -When multiple cards are available, it'd better to specify the index -number for each card via module option, too, so that the order of -cards is kept consistent. - -An example configuration for two sound cards is like below: - ------ /etc/modprobe.d/alsa.conf -# ALSA portion -options snd cards_limit=2 -alias snd-card-0 snd-interwave -alias snd-card-1 snd-ens1371 -options snd-interwave index=0 -options snd-ens1371 index=1 -# OSS/Free portion -alias sound-slot-0 snd-interwave -alias sound-slot-1 snd-ens1371 ------ /etc/modprobe.d/alsa.conf - -In this example, the interwave card is always loaded as the first card -(index 0) and ens1371 as the second (index 1). - -Alternative (and new) way to fixate the slot assignment is to use -"slots" option of snd module. In the case above, specify like the -following: - -options snd slots=snd-interwave,snd-ens1371 - -Then, the first slot (#0) is reserved for snd-interwave driver, and -the second (#1) for snd-ens1371. You can omit index option in each -driver if slots option is used (although you can still have them at -the same time as long as they don't conflict). - -The slots option is especially useful for avoiding the possible -hot-plugging and the resultant slot conflict. For example, in the -case above again, the first two slots are already reserved. If any -other driver (e.g. snd-usb-audio) is loaded before snd-interwave or -snd-ens1371, it will be assigned to the third or later slot. - -When a module name is given with '!', the slot will be given for any -modules but that name. For example, "slots=!snd-pcsp" will reserve -the first slot for any modules but snd-pcsp. - - -ALSA PCM devices to OSS devices mapping -======================================= - -/dev/snd/pcmC0D0[c|p] -> /dev/audio0 (/dev/audio) -> minor 4 -/dev/snd/pcmC0D0[c|p] -> /dev/dsp0 (/dev/dsp) -> minor 3 -/dev/snd/pcmC0D1[c|p] -> /dev/adsp0 (/dev/adsp) -> minor 12 -/dev/snd/pcmC1D0[c|p] -> /dev/audio1 -> minor 4+16 = 20 -/dev/snd/pcmC1D0[c|p] -> /dev/dsp1 -> minor 3+16 = 19 -/dev/snd/pcmC1D1[c|p] -> /dev/adsp1 -> minor 12+16 = 28 -/dev/snd/pcmC2D0[c|p] -> /dev/audio2 -> minor 4+32 = 36 -/dev/snd/pcmC2D0[c|p] -> /dev/dsp2 -> minor 3+32 = 39 -/dev/snd/pcmC2D1[c|p] -> /dev/adsp2 -> minor 12+32 = 44 - -The first number from /dev/snd/pcmC{X}D{Y}[c|p] expression means -sound card number and second means device number. The ALSA devices -have either 'c' or 'p' suffix indicating the direction, capture and -playback, respectively. - -Please note that the device mapping above may be varied via the module -options of snd-pcm-oss module. - - -Proc interfaces (/proc/asound) -============================== - -/proc/asound/card#/pcm#[cp]/oss -------------------------------- - String "erase" - erase all additional information about OSS applications - String " []" - - - name of application with (higher priority) or without path - - number of fragments or zero if auto - - size of fragment in bytes or zero if auto - - optional parameters - - disable the application tries to open a pcm device for - this channel but does not want to use it. - (Cause a bug or mmap needs) - It's good for Quake etc... - - direct don't use plugins - - block force block mode (rvplayer) - - non-block force non-block mode - - whole-frag write only whole fragments (optimization affecting - playback only) - - no-silence do not fill silence ahead to avoid clicks - - buggy-ptr Returns the whitespace blocks in GETOPTR ioctl - instead of filled blocks - - Example: echo "x11amp 128 16384" > /proc/asound/card0/pcm0p/oss - echo "squake 0 0 disable" > /proc/asound/card0/pcm0c/oss - echo "rvplayer 0 0 block" > /proc/asound/card0/pcm0p/oss - - -Early Buffer Allocation -======================= - -Some drivers (e.g. hdsp) require the large contiguous buffers, and -sometimes it's too late to find such spaces when the driver module is -actually loaded due to memory fragmentation. You can pre-allocate the -PCM buffers by loading snd-page-alloc module and write commands to its -proc file in prior, for example, in the early boot stage like -/etc/init.d/*.local scripts. - -Reading the proc file /proc/drivers/snd-page-alloc shows the current -usage of page allocation. In writing, you can send the following -commands to the snd-page-alloc driver: - - - add VENDOR DEVICE MASK SIZE BUFFERS - - VENDOR and DEVICE are PCI vendor and device IDs. They take - integer numbers (0x prefix is needed for the hex). - MASK is the PCI DMA mask. Pass 0 if not restricted. - SIZE is the size of each buffer to allocate. You can pass - k and m suffix for KB and MB. The max number is 16MB. - BUFFERS is the number of buffers to allocate. It must be greater - than 0. The max number is 4. - - - erase - - This will erase the all pre-allocated buffers which are not in - use. - - -Links and Addresses -=================== - - ALSA project homepage - http://www.alsa-project.org - - Kernel Bugzilla - http://bugzilla.kernel.org/ - - ALSA Developers ML - mailto:alsa-devel@alsa-project.org - - alsa-info.sh script - http://www.alsa-project.org/alsa-info.sh diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst index e9bac7c8b893..64fe47af05b6 100644 --- a/Documentation/sound/index.rst +++ b/Documentation/sound/index.rst @@ -6,6 +6,7 @@ Linux Sound Subsystem Documentation :maxdepth: 2 kernel-api/index + alsa-configuration hd-audio/index .. only:: subproject -- cgit v1.2.3 From afb8fd3c72a9f00018f7335590c173ce4cc2a43d Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 15:52:06 +0100 Subject: ALSA: doc: ReSTize Procfile document A simple conversion from a text file. A new subidrectory, Documentation/sound/designs, was created to put this document. The other API design and implementation docuemnts will be put to that directory in later commits. Signed-off-by: Takashi Iwai --- Documentation/sound/alsa/Procfile.txt | 234 ------------------------------ Documentation/sound/designs/index.rst | 7 + Documentation/sound/designs/procfile.rst | 238 +++++++++++++++++++++++++++++++ Documentation/sound/index.rst | 1 + 4 files changed, 246 insertions(+), 234 deletions(-) delete mode 100644 Documentation/sound/alsa/Procfile.txt create mode 100644 Documentation/sound/designs/index.rst create mode 100644 Documentation/sound/designs/procfile.rst diff --git a/Documentation/sound/alsa/Procfile.txt b/Documentation/sound/alsa/Procfile.txt deleted file mode 100644 index 7f8a0d325905..000000000000 --- a/Documentation/sound/alsa/Procfile.txt +++ /dev/null @@ -1,234 +0,0 @@ - Proc Files of ALSA Drivers - ========================== - Takashi Iwai - -General -------- - -ALSA has its own proc tree, /proc/asound. Many useful information are -found in this tree. When you encounter a problem and need debugging, -check the files listed in the following sections. - -Each card has its subtree cardX, where X is from 0 to 7. The -card-specific files are stored in the card* subdirectories. - - -Global Information ------------------- - -cards - Shows the list of currently configured ALSA drivers, - index, the id string, short and long descriptions. - -version - Shows the version string and compile date. - -modules - Lists the module of each card - -devices - Lists the ALSA native device mappings. - -meminfo - Shows the status of allocated pages via ALSA drivers. - Appears only when CONFIG_SND_DEBUG=y. - -hwdep - Lists the currently available hwdep devices in format of - -: - -pcm - Lists the currently available PCM devices in format of - -: : : - -timer - Lists the currently available timer devices - - -oss/devices - Lists the OSS device mappings. - -oss/sndstat - Provides the output compatible with /dev/sndstat. - You can symlink this to /dev/sndstat. - - -Card Specific Files -------------------- - -The card-specific files are found in /proc/asound/card* directories. -Some drivers (e.g. cmipci) have their own proc entries for the -register dump, etc (e.g. /proc/asound/card*/cmipci shows the register -dump). These files would be really helpful for debugging. - -When PCM devices are available on this card, you can see directories -like pcm0p or pcm1c. They hold the PCM information for each PCM -stream. The number after 'pcm' is the PCM device number from 0, and -the last 'p' or 'c' means playback or capture direction. The files in -this subtree is described later. - -The status of MIDI I/O is found in midi* files. It shows the device -name and the received/transmitted bytes through the MIDI device. - -When the card is equipped with AC97 codecs, there are codec97#* -subdirectories (described later). - -When the OSS mixer emulation is enabled (and the module is loaded), -oss_mixer file appears here, too. This shows the current mapping of -OSS mixer elements to the ALSA control elements. You can change the -mapping by writing to this device. Read OSS-Emulation.txt for -details. - - -PCM Proc Files --------------- - -card*/pcm*/info - The general information of this PCM device: card #, device #, - substreams, etc. - -card*/pcm*/xrun_debug - This file appears when CONFIG_SND_DEBUG=y and - CONFIG_PCM_XRUN_DEBUG=y. - This shows the status of xrun (= buffer overrun/xrun) and - invalid PCM position debug/check of ALSA PCM middle layer. - It takes an integer value, can be changed by writing to this - file, such as - - # echo 5 > /proc/asound/card0/pcm0p/xrun_debug - - The value consists of the following bit flags: - bit 0 = Enable XRUN/jiffies debug messages - bit 1 = Show stack trace at XRUN / jiffies check - bit 2 = Enable additional jiffies check - - When the bit 0 is set, the driver will show the messages to - kernel log when an xrun is detected. The debug message is - shown also when the invalid H/W pointer is detected at the - update of periods (usually called from the interrupt - handler). - - When the bit 1 is set, the driver will show the stack trace - additionally. This may help the debugging. - - Since 2.6.30, this option can enable the hwptr check using - jiffies. This detects spontaneous invalid pointer callback - values, but can be lead to too much corrections for a (mostly - buggy) hardware that doesn't give smooth pointer updates. - This feature is enabled via the bit 2. - -card*/pcm*/sub*/info - The general information of this PCM sub-stream. - -card*/pcm*/sub*/status - The current status of this PCM sub-stream, elapsed time, - H/W position, etc. - -card*/pcm*/sub*/hw_params - The hardware parameters set for this sub-stream. - -card*/pcm*/sub*/sw_params - The soft parameters set for this sub-stream. - -card*/pcm*/sub*/prealloc - The buffer pre-allocation information. - -card*/pcm*/sub*/xrun_injection - Triggers an XRUN to the running stream when any value is - written to this proc file. Used for fault injection. - This entry is write-only. - -AC97 Codec Information ----------------------- - -card*/codec97#*/ac97#?-? - Shows the general information of this AC97 codec chip, such as - name, capabilities, set up. - -card*/codec97#0/ac97#?-?+regs - Shows the AC97 register dump. Useful for debugging. - - When CONFIG_SND_DEBUG is enabled, you can write to this file for - changing an AC97 register directly. Pass two hex numbers. - For example, - - # echo 02 9f1f > /proc/asound/card0/codec97#0/ac97#0-0+regs - - -USB Audio Streams ------------------ - -card*/stream* - Shows the assignment and the current status of each audio stream - of the given card. This information is very useful for debugging. - - -HD-Audio Codecs ---------------- - -card*/codec#* - Shows the general codec information and the attribute of each - widget node. - -card*/eld#* - Available for HDMI or DisplayPort interfaces. - Shows ELD(EDID Like Data) info retrieved from the attached HDMI sink, - and describes its audio capabilities and configurations. - - Some ELD fields may be modified by doing `echo name hex_value > eld#*`. - Only do this if you are sure the HDMI sink provided value is wrong. - And if that makes your HDMI audio work, please report to us so that we - can fix it in future kernel releases. - - -Sequencer Information ---------------------- - -seq/drivers - Lists the currently available ALSA sequencer drivers. - -seq/clients - Shows the list of currently available sequencer clients and - ports. The connection status and the running status are shown - in this file, too. - -seq/queues - Lists the currently allocated/running sequencer queues. - -seq/timer - Lists the currently allocated/running sequencer timers. - -seq/oss - Lists the OSS-compatible sequencer stuffs. - - -Help For Debugging? -------------------- - -When the problem is related with PCM, first try to turn on xrun_debug -mode. This will give you the kernel messages when and where xrun -happened. - -If it's really a bug, report it with the following information: - - - the name of the driver/card, show in /proc/asound/cards - - the register dump, if available (e.g. card*/cmipci) - -when it's a PCM problem, - - - set-up of PCM, shown in hw_parms, sw_params, and status in the PCM - sub-stream directory - -when it's a mixer problem, - - - AC97 proc files, codec97#*/* files - -for USB audio/midi, - - - output of lsusb -v - - stream* files in card directory - - -The ALSA bug-tracking system is found at: - - https://bugtrack.alsa-project.org/alsa-bug/ diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst new file mode 100644 index 000000000000..82d19fe3c380 --- /dev/null +++ b/Documentation/sound/designs/index.rst @@ -0,0 +1,7 @@ +Designs and Implementations +=========================== + +.. toctree:: + :maxdepth: 2 + + procfile diff --git a/Documentation/sound/designs/procfile.rst b/Documentation/sound/designs/procfile.rst new file mode 100644 index 000000000000..29a466851fd2 --- /dev/null +++ b/Documentation/sound/designs/procfile.rst @@ -0,0 +1,238 @@ +========================== +Proc Files of ALSA Drivers +========================== + +Takashi Iwai + +General +======= + +ALSA has its own proc tree, /proc/asound. Many useful information are +found in this tree. When you encounter a problem and need debugging, +check the files listed in the following sections. + +Each card has its subtree cardX, where X is from 0 to 7. The +card-specific files are stored in the ``card*`` subdirectories. + + +Global Information +================== + +cards + Shows the list of currently configured ALSA drivers, + index, the id string, short and long descriptions. + +version + Shows the version string and compile date. + +modules + Lists the module of each card + +devices + Lists the ALSA native device mappings. + +meminfo + Shows the status of allocated pages via ALSA drivers. + Appears only when ``CONFIG_SND_DEBUG=y``. + +hwdep + Lists the currently available hwdep devices in format of + ``-: `` + +pcm + Lists the currently available PCM devices in format of + ``-: : : `` + +timer + Lists the currently available timer devices + + +oss/devices + Lists the OSS device mappings. + +oss/sndstat + Provides the output compatible with /dev/sndstat. + You can symlink this to /dev/sndstat. + + +Card Specific Files +=================== + +The card-specific files are found in ``/proc/asound/card*`` directories. +Some drivers (e.g. cmipci) have their own proc entries for the +register dump, etc (e.g. ``/proc/asound/card*/cmipci`` shows the register +dump). These files would be really helpful for debugging. + +When PCM devices are available on this card, you can see directories +like pcm0p or pcm1c. They hold the PCM information for each PCM +stream. The number after ``pcm`` is the PCM device number from 0, and +the last ``p`` or ``c`` means playback or capture direction. The files in +this subtree is described later. + +The status of MIDI I/O is found in ``midi*`` files. It shows the device +name and the received/transmitted bytes through the MIDI device. + +When the card is equipped with AC97 codecs, there are ``codec97#*`` +subdirectories (described later). + +When the OSS mixer emulation is enabled (and the module is loaded), +oss_mixer file appears here, too. This shows the current mapping of +OSS mixer elements to the ALSA control elements. You can change the +mapping by writing to this device. Read OSS-Emulation.txt for +details. + + +PCM Proc Files +============== + +``card*/pcm*/info`` + The general information of this PCM device: card #, device #, + substreams, etc. + +``card*/pcm*/xrun_debug`` + This file appears when ``CONFIG_SND_DEBUG=y`` and + ``CONFIG_PCM_XRUN_DEBUG=y``. + This shows the status of xrun (= buffer overrun/xrun) and + invalid PCM position debug/check of ALSA PCM middle layer. + It takes an integer value, can be changed by writing to this + file, such as:: + + # echo 5 > /proc/asound/card0/pcm0p/xrun_debug + + The value consists of the following bit flags: + + * bit 0 = Enable XRUN/jiffies debug messages + * bit 1 = Show stack trace at XRUN / jiffies check + * bit 2 = Enable additional jiffies check + + When the bit 0 is set, the driver will show the messages to + kernel log when an xrun is detected. The debug message is + shown also when the invalid H/W pointer is detected at the + update of periods (usually called from the interrupt + handler). + + When the bit 1 is set, the driver will show the stack trace + additionally. This may help the debugging. + + Since 2.6.30, this option can enable the hwptr check using + jiffies. This detects spontaneous invalid pointer callback + values, but can be lead to too much corrections for a (mostly + buggy) hardware that doesn't give smooth pointer updates. + This feature is enabled via the bit 2. + +``card*/pcm*/sub*/info`` + The general information of this PCM sub-stream. + +``card*/pcm*/sub*/status`` + The current status of this PCM sub-stream, elapsed time, + H/W position, etc. + +``card*/pcm*/sub*/hw_params`` + The hardware parameters set for this sub-stream. + +``card*/pcm*/sub*/sw_params`` + The soft parameters set for this sub-stream. + +``card*/pcm*/sub*/prealloc`` + The buffer pre-allocation information. + +``card*/pcm*/sub*/xrun_injection`` + Triggers an XRUN to the running stream when any value is + written to this proc file. Used for fault injection. + This entry is write-only. + +AC97 Codec Information +====================== + +``card*/codec97#*/ac97#?-?`` + Shows the general information of this AC97 codec chip, such as + name, capabilities, set up. + +``card*/codec97#0/ac97#?-?+regs`` + Shows the AC97 register dump. Useful for debugging. + + When CONFIG_SND_DEBUG is enabled, you can write to this file for + changing an AC97 register directly. Pass two hex numbers. + For example, + +:: + + # echo 02 9f1f > /proc/asound/card0/codec97#0/ac97#0-0+regs + + +USB Audio Streams +================= + +``card*/stream*`` + Shows the assignment and the current status of each audio stream + of the given card. This information is very useful for debugging. + + +HD-Audio Codecs +=============== + +``card*/codec#*`` + Shows the general codec information and the attribute of each + widget node. + +``card*/eld#*`` + Available for HDMI or DisplayPort interfaces. + Shows ELD(EDID Like Data) info retrieved from the attached HDMI sink, + and describes its audio capabilities and configurations. + + Some ELD fields may be modified by doing ``echo name hex_value > eld#*``. + Only do this if you are sure the HDMI sink provided value is wrong. + And if that makes your HDMI audio work, please report to us so that we + can fix it in future kernel releases. + + +Sequencer Information +===================== + +seq/drivers + Lists the currently available ALSA sequencer drivers. + +seq/clients + Shows the list of currently available sequencer clients and + ports. The connection status and the running status are shown + in this file, too. + +seq/queues + Lists the currently allocated/running sequencer queues. + +seq/timer + Lists the currently allocated/running sequencer timers. + +seq/oss + Lists the OSS-compatible sequencer stuffs. + + +Help For Debugging? +=================== + +When the problem is related with PCM, first try to turn on xrun_debug +mode. This will give you the kernel messages when and where xrun +happened. + +If it's really a bug, report it with the following information: + +- the name of the driver/card, show in ``/proc/asound/cards`` +- the register dump, if available (e.g. ``card*/cmipci``) + +when it's a PCM problem, + +- set-up of PCM, shown in hw_parms, sw_params, and status in the PCM + sub-stream directory + +when it's a mixer problem, + +- AC97 proc files, ``codec97#*/*`` files + +for USB audio/midi, + +- output of ``lsusb -v`` +- ``stream*`` files in card directory + + +The ALSA bug-tracking system is found at: +https://bugtrack.alsa-project.org/alsa-bug/ diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst index 64fe47af05b6..e9fbbfff9d0d 100644 --- a/Documentation/sound/index.rst +++ b/Documentation/sound/index.rst @@ -6,6 +6,7 @@ Linux Sound Subsystem Documentation :maxdepth: 2 kernel-api/index + designs/index alsa-configuration hd-audio/index -- cgit v1.2.3 From 48e92b488d3c419e11bbf03c56ceb43399ac1901 Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 15:54:47 +0100 Subject: ALSA: doc: ReSTize powersave document A simple conversion from a text file. Put into designs subdirectory, although it's mostly relevant with HD-audio. Signed-off-by: Takashi Iwai --- Documentation/sound/alsa/powersave.txt | 41 ----------------------------- Documentation/sound/designs/index.rst | 1 + Documentation/sound/designs/powersave.rst | 43 +++++++++++++++++++++++++++++++ 3 files changed, 44 insertions(+), 41 deletions(-) delete mode 100644 Documentation/sound/alsa/powersave.txt create mode 100644 Documentation/sound/designs/powersave.rst diff --git a/Documentation/sound/alsa/powersave.txt b/Documentation/sound/alsa/powersave.txt deleted file mode 100644 index 9657e8099228..000000000000 --- a/Documentation/sound/alsa/powersave.txt +++ /dev/null @@ -1,41 +0,0 @@ -Notes on Power-Saving Mode -========================== - -AC97 and HD-audio drivers have the automatic power-saving mode. -This feature is enabled via Kconfig CONFIG_SND_AC97_POWER_SAVE -and CONFIG_SND_HDA_POWER_SAVE options, respectively. - -With the automatic power-saving, the driver turns off the codec power -appropriately when no operation is required. When no applications use -the device and/or no analog loopback is set, the power disablement is -done fully or partially. It'll save a certain power consumption, thus -good for laptops (even for desktops). - -The time-out for automatic power-off can be specified via power_save -module option of snd-ac97-codec and snd-hda-intel modules. Specify -the time-out value in seconds. 0 means to disable the automatic -power-saving. The default value of timeout is given via -CONFIG_SND_AC97_POWER_SAVE_DEFAULT and -CONFIG_SND_HDA_POWER_SAVE_DEFAULT Kconfig options. Setting this to 1 -(the minimum value) isn't recommended because many applications try to -reopen the device frequently. 10 would be a good choice for normal -operations. - -The power_save option is exported as writable. This means you can -adjust the value via sysfs on the fly. For example, to turn on the -automatic power-save mode with 10 seconds, write to -/sys/modules/snd_ac97_codec/parameters/power_save (usually as root): - - # echo 10 > /sys/modules/snd_ac97_codec/parameters/power_save - - -Note that you might hear click noise/pop when changing the power -state. Also, it often takes certain time to wake up from the -power-down to the active state. These are often hardly to fix, so -don't report extra bug reports unless you have a fix patch ;-) - -For HD-audio interface, there is another module option, -power_save_controller. This enables/disables the power-save mode of -the controller side. Setting this on may reduce a bit more power -consumption, but might result in longer wake-up time and click noise. -Try to turn it off when you experience such a thing too often. diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst index 82d19fe3c380..362e1c23d51f 100644 --- a/Documentation/sound/designs/index.rst +++ b/Documentation/sound/designs/index.rst @@ -5,3 +5,4 @@ Designs and Implementations :maxdepth: 2 procfile + powersave diff --git a/Documentation/sound/designs/powersave.rst b/Documentation/sound/designs/powersave.rst new file mode 100644 index 000000000000..138157452eb9 --- /dev/null +++ b/Documentation/sound/designs/powersave.rst @@ -0,0 +1,43 @@ +========================== +Notes on Power-Saving Mode +========================== + +AC97 and HD-audio drivers have the automatic power-saving mode. +This feature is enabled via Kconfig ``CONFIG_SND_AC97_POWER_SAVE`` +and ``CONFIG_SND_HDA_POWER_SAVE`` options, respectively. + +With the automatic power-saving, the driver turns off the codec power +appropriately when no operation is required. When no applications use +the device and/or no analog loopback is set, the power disablement is +done fully or partially. It'll save a certain power consumption, thus +good for laptops (even for desktops). + +The time-out for automatic power-off can be specified via ``power_save`` +module option of snd-ac97-codec and snd-hda-intel modules. Specify +the time-out value in seconds. 0 means to disable the automatic +power-saving. The default value of timeout is given via +``CONFIG_SND_AC97_POWER_SAVE_DEFAULT`` and +``CONFIG_SND_HDA_POWER_SAVE_DEFAULT`` Kconfig options. Setting this to 1 +(the minimum value) isn't recommended because many applications try to +reopen the device frequently. 10 would be a good choice for normal +operations. + +The ``power_save`` option is exported as writable. This means you can +adjust the value via sysfs on the fly. For example, to turn on the +automatic power-save mode with 10 seconds, write to +``/sys/modules/snd_ac97_codec/parameters/power_save`` (usually as root): +:: + + # echo 10 > /sys/modules/snd_ac97_codec/parameters/power_save + + +Note that you might hear click noise/pop when changing the power +state. Also, it often takes certain time to wake up from the +power-down to the active state. These are often hardly to fix, so +don't report extra bug reports unless you have a fix patch ;-) + +For HD-audio interface, there is another module option, +power_save_controller. This enables/disables the power-save mode of +the controller side. Setting this on may reduce a bit more power +consumption, but might result in longer wake-up time and click noise. +Try to turn it off when you experience such a thing too often. -- cgit v1.2.3 From efe541c230e41106ce912e096e19518630e810db Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 16:05:18 +0100 Subject: ALSA: doc: ReSTize Channel-Mapping-API document A simple conversion from a text file. Put to designs subdirectory. Signed-off-by: Takashi Iwai --- Documentation/sound/alsa/Channel-Mapping-API.txt | 153 ------------------- .../sound/designs/channel-mapping-api.rst | 164 +++++++++++++++++++++ Documentation/sound/designs/index.rst | 1 + 3 files changed, 165 insertions(+), 153 deletions(-) delete mode 100644 Documentation/sound/alsa/Channel-Mapping-API.txt create mode 100644 Documentation/sound/designs/channel-mapping-api.rst diff --git a/Documentation/sound/alsa/Channel-Mapping-API.txt b/Documentation/sound/alsa/Channel-Mapping-API.txt deleted file mode 100644 index 3c43d1a4ca0e..000000000000 --- a/Documentation/sound/alsa/Channel-Mapping-API.txt +++ /dev/null @@ -1,153 +0,0 @@ -ALSA PCM channel-mapping API -============================ - Takashi Iwai - -GENERAL -------- - -The channel mapping API allows user to query the possible channel maps -and the current channel map, also optionally to modify the channel map -of the current stream. - -A channel map is an array of position for each PCM channel. -Typically, a stereo PCM stream has a channel map of - { front_left, front_right } -while a 4.0 surround PCM stream has a channel map of - { front left, front right, rear left, rear right }. - -The problem, so far, was that we had no standard channel map -explicitly, and applications had no way to know which channel -corresponds to which (speaker) position. Thus, applications applied -wrong channels for 5.1 outputs, and you hear suddenly strange sound -from rear. Or, some devices secretly assume that center/LFE is the -third/fourth channels while others that C/LFE as 5th/6th channels. - -Also, some devices such as HDMI are configurable for different speaker -positions even with the same number of total channels. However, there -was no way to specify this because of lack of channel map -specification. These are the main motivations for the new channel -mapping API. - - -DESIGN ------- - -Actually, "the channel mapping API" doesn't introduce anything new in -the kernel/user-space ABI perspective. It uses only the existing -control element features. - -As a ground design, each PCM substream may contain a control element -providing the channel mapping information and configuration. This -element is specified by: - iface = SNDRV_CTL_ELEM_IFACE_PCM - name = "Playback Channel Map" or "Capture Channel Map" - device = the same device number for the assigned PCM substream - index = the same index number for the assigned PCM substream - -Note the name is different depending on the PCM substream direction. - -Each control element provides at least the TLV read operation and the -read operation. Optionally, the write operation can be provided to -allow user to change the channel map dynamically. - -* TLV - -The TLV operation gives the list of available channel -maps. A list item of a channel map is usually a TLV of - type data-bytes ch0 ch1 ch2... -where type is the TLV type value, the second argument is the total -bytes (not the numbers) of channel values, and the rest are the -position value for each channel. - -As a TLV type, either SNDRV_CTL_TLVT_CHMAP_FIXED, -SNDRV_CTL_TLV_CHMAP_VAR or SNDRV_CTL_TLVT_CHMAP_PAIRED can be used. -The _FIXED type is for a channel map with the fixed channel position -while the latter two are for flexible channel positions. _VAR type is -for a channel map where all channels are freely swappable and _PAIRED -type is where pair-wise channels are swappable. For example, when you -have {FL/FR/RL/RR} channel map, _PAIRED type would allow you to swap -only {RL/RR/FL/FR} while _VAR type would allow even swapping FL and -RR. - -These new TLV types are defined in sound/tlv.h. - -The available channel position values are defined in sound/asound.h, -here is a cut: - -/* channel positions */ -enum { - SNDRV_CHMAP_UNKNOWN = 0, - SNDRV_CHMAP_NA, /* N/A, silent */ - SNDRV_CHMAP_MONO, /* mono stream */ - /* this follows the alsa-lib mixer channel value + 3 */ - SNDRV_CHMAP_FL, /* front left */ - SNDRV_CHMAP_FR, /* front right */ - SNDRV_CHMAP_RL, /* rear left */ - SNDRV_CHMAP_RR, /* rear right */ - SNDRV_CHMAP_FC, /* front center */ - SNDRV_CHMAP_LFE, /* LFE */ - SNDRV_CHMAP_SL, /* side left */ - SNDRV_CHMAP_SR, /* side right */ - SNDRV_CHMAP_RC, /* rear center */ - /* new definitions */ - SNDRV_CHMAP_FLC, /* front left center */ - SNDRV_CHMAP_FRC, /* front right center */ - SNDRV_CHMAP_RLC, /* rear left center */ - SNDRV_CHMAP_RRC, /* rear right center */ - SNDRV_CHMAP_FLW, /* front left wide */ - SNDRV_CHMAP_FRW, /* front right wide */ - SNDRV_CHMAP_FLH, /* front left high */ - SNDRV_CHMAP_FCH, /* front center high */ - SNDRV_CHMAP_FRH, /* front right high */ - SNDRV_CHMAP_TC, /* top center */ - SNDRV_CHMAP_TFL, /* top front left */ - SNDRV_CHMAP_TFR, /* top front right */ - SNDRV_CHMAP_TFC, /* top front center */ - SNDRV_CHMAP_TRL, /* top rear left */ - SNDRV_CHMAP_TRR, /* top rear right */ - SNDRV_CHMAP_TRC, /* top rear center */ - SNDRV_CHMAP_LAST = SNDRV_CHMAP_TRC, -}; - -When a PCM stream can provide more than one channel map, you can -provide multiple channel maps in a TLV container type. The TLV data -to be returned will contain such as: - SNDRV_CTL_TLVT_CONTAINER 96 - SNDRV_CTL_TLVT_CHMAP_FIXED 4 SNDRV_CHMAP_FC - SNDRV_CTL_TLVT_CHMAP_FIXED 8 SNDRV_CHMAP_FL SNDRV_CHMAP_FR - SNDRV_CTL_TLVT_CHMAP_FIXED 16 NDRV_CHMAP_FL SNDRV_CHMAP_FR \ - SNDRV_CHMAP_RL SNDRV_CHMAP_RR - -The channel position is provided in LSB 16bits. The upper bits are -used for bit flags. - -#define SNDRV_CHMAP_POSITION_MASK 0xffff -#define SNDRV_CHMAP_PHASE_INVERSE (0x01 << 16) -#define SNDRV_CHMAP_DRIVER_SPEC (0x02 << 16) - -SNDRV_CHMAP_PHASE_INVERSE indicates the channel is phase inverted, -(thus summing left and right channels would result in almost silence). -Some digital mic devices have this. - -When SNDRV_CHMAP_DRIVER_SPEC is set, all the channel position values -don't follow the standard definition above but driver-specific. - -* READ OPERATION - -The control read operation is for providing the current channel map of -the given stream. The control element returns an integer array -containing the position of each channel. - -When this is performed before the number of the channel is specified -(i.e. hw_params is set), it should return all channels set to -UNKNOWN. - -* WRITE OPERATION - -The control write operation is optional, and only for devices that can -change the channel configuration on the fly, such as HDMI. User needs -to pass an integer value containing the valid channel positions for -all channels of the assigned PCM substream. - -This operation is allowed only at PCM PREPARED state. When called in -other states, it shall return an error. diff --git a/Documentation/sound/designs/channel-mapping-api.rst b/Documentation/sound/designs/channel-mapping-api.rst new file mode 100644 index 000000000000..58e6312a43c0 --- /dev/null +++ b/Documentation/sound/designs/channel-mapping-api.rst @@ -0,0 +1,164 @@ +============================ +ALSA PCM channel-mapping API +============================ + +Takashi Iwai + +General +======= + +The channel mapping API allows user to query the possible channel maps +and the current channel map, also optionally to modify the channel map +of the current stream. + +A channel map is an array of position for each PCM channel. +Typically, a stereo PCM stream has a channel map of +``{ front_left, front_right }`` +while a 4.0 surround PCM stream has a channel map of +``{ front left, front right, rear left, rear right }.`` + +The problem, so far, was that we had no standard channel map +explicitly, and applications had no way to know which channel +corresponds to which (speaker) position. Thus, applications applied +wrong channels for 5.1 outputs, and you hear suddenly strange sound +from rear. Or, some devices secretly assume that center/LFE is the +third/fourth channels while others that C/LFE as 5th/6th channels. + +Also, some devices such as HDMI are configurable for different speaker +positions even with the same number of total channels. However, there +was no way to specify this because of lack of channel map +specification. These are the main motivations for the new channel +mapping API. + + +Design +====== + +Actually, "the channel mapping API" doesn't introduce anything new in +the kernel/user-space ABI perspective. It uses only the existing +control element features. + +As a ground design, each PCM substream may contain a control element +providing the channel mapping information and configuration. This +element is specified by: + +* iface = SNDRV_CTL_ELEM_IFACE_PCM +* name = "Playback Channel Map" or "Capture Channel Map" +* device = the same device number for the assigned PCM substream +* index = the same index number for the assigned PCM substream + +Note the name is different depending on the PCM substream direction. + +Each control element provides at least the TLV read operation and the +read operation. Optionally, the write operation can be provided to +allow user to change the channel map dynamically. + +TLV +--- + +The TLV operation gives the list of available channel +maps. A list item of a channel map is usually a TLV of +``type data-bytes ch0 ch1 ch2...`` +where type is the TLV type value, the second argument is the total +bytes (not the numbers) of channel values, and the rest are the +position value for each channel. + +As a TLV type, either ``SNDRV_CTL_TLVT_CHMAP_FIXED``, +``SNDRV_CTL_TLV_CHMAP_VAR`` or ``SNDRV_CTL_TLVT_CHMAP_PAIRED`` can be used. +The ``_FIXED`` type is for a channel map with the fixed channel position +while the latter two are for flexible channel positions. ``_VAR`` type is +for a channel map where all channels are freely swappable and ``_PAIRED`` +type is where pair-wise channels are swappable. For example, when you +have {FL/FR/RL/RR} channel map, ``_PAIRED`` type would allow you to swap +only {RL/RR/FL/FR} while ``_VAR`` type would allow even swapping FL and +RR. + +These new TLV types are defined in ``sound/tlv.h``. + +The available channel position values are defined in ``sound/asound.h``, +here is a cut: + +:: + + /* channel positions */ + enum { + SNDRV_CHMAP_UNKNOWN = 0, + SNDRV_CHMAP_NA, /* N/A, silent */ + SNDRV_CHMAP_MONO, /* mono stream */ + /* this follows the alsa-lib mixer channel value + 3 */ + SNDRV_CHMAP_FL, /* front left */ + SNDRV_CHMAP_FR, /* front right */ + SNDRV_CHMAP_RL, /* rear left */ + SNDRV_CHMAP_RR, /* rear right */ + SNDRV_CHMAP_FC, /* front center */ + SNDRV_CHMAP_LFE, /* LFE */ + SNDRV_CHMAP_SL, /* side left */ + SNDRV_CHMAP_SR, /* side right */ + SNDRV_CHMAP_RC, /* rear center */ + /* new definitions */ + SNDRV_CHMAP_FLC, /* front left center */ + SNDRV_CHMAP_FRC, /* front right center */ + SNDRV_CHMAP_RLC, /* rear left center */ + SNDRV_CHMAP_RRC, /* rear right center */ + SNDRV_CHMAP_FLW, /* front left wide */ + SNDRV_CHMAP_FRW, /* front right wide */ + SNDRV_CHMAP_FLH, /* front left high */ + SNDRV_CHMAP_FCH, /* front center high */ + SNDRV_CHMAP_FRH, /* front right high */ + SNDRV_CHMAP_TC, /* top center */ + SNDRV_CHMAP_TFL, /* top front left */ + SNDRV_CHMAP_TFR, /* top front right */ + SNDRV_CHMAP_TFC, /* top front center */ + SNDRV_CHMAP_TRL, /* top rear left */ + SNDRV_CHMAP_TRR, /* top rear right */ + SNDRV_CHMAP_TRC, /* top rear center */ + SNDRV_CHMAP_LAST = SNDRV_CHMAP_TRC, + }; + +When a PCM stream can provide more than one channel map, you can +provide multiple channel maps in a TLV container type. The TLV data +to be returned will contain such as: +:: + + SNDRV_CTL_TLVT_CONTAINER 96 + SNDRV_CTL_TLVT_CHMAP_FIXED 4 SNDRV_CHMAP_FC + SNDRV_CTL_TLVT_CHMAP_FIXED 8 SNDRV_CHMAP_FL SNDRV_CHMAP_FR + SNDRV_CTL_TLVT_CHMAP_FIXED 16 NDRV_CHMAP_FL SNDRV_CHMAP_FR \ + SNDRV_CHMAP_RL SNDRV_CHMAP_RR + +The channel position is provided in LSB 16bits. The upper bits are +used for bit flags. +:: + + #define SNDRV_CHMAP_POSITION_MASK 0xffff + #define SNDRV_CHMAP_PHASE_INVERSE (0x01 << 16) + #define SNDRV_CHMAP_DRIVER_SPEC (0x02 << 16) + +``SNDRV_CHMAP_PHASE_INVERSE`` indicates the channel is phase inverted, +(thus summing left and right channels would result in almost silence). +Some digital mic devices have this. + +When ``SNDRV_CHMAP_DRIVER_SPEC`` is set, all the channel position values +don't follow the standard definition above but driver-specific. + +Read Operation +-------------- + +The control read operation is for providing the current channel map of +the given stream. The control element returns an integer array +containing the position of each channel. + +When this is performed before the number of the channel is specified +(i.e. hw_params is set), it should return all channels set to +``UNKNOWN``. + +Write Operation +--------------- + +The control write operation is optional, and only for devices that can +change the channel configuration on the fly, such as HDMI. User needs +to pass an integer value containing the valid channel positions for +all channels of the assigned PCM substream. + +This operation is allowed only at PCM PREPARED state. When called in +other states, it shall return an error. diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst index 362e1c23d51f..dd4fcbcb2b92 100644 --- a/Documentation/sound/designs/index.rst +++ b/Documentation/sound/designs/index.rst @@ -4,5 +4,6 @@ Designs and Implementations .. toctree:: :maxdepth: 2 + channel-mapping-api procfile powersave -- cgit v1.2.3 From 0c266c4b707e263ac74e0bd4330b4193fa46c434 Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 16:18:14 +0100 Subject: ALSA: doc: ReSTize OSS-Emulation document A simple conversion from a text file. Put to designs subdirectory. Signed-off-by: Takashi Iwai --- Documentation/sound/alsa/OSS-Emulation.txt | 305 ----------------------- Documentation/sound/designs/index.rst | 1 + Documentation/sound/designs/oss-emulation.rst | 336 ++++++++++++++++++++++++++ 3 files changed, 337 insertions(+), 305 deletions(-) delete mode 100644 Documentation/sound/alsa/OSS-Emulation.txt create mode 100644 Documentation/sound/designs/oss-emulation.rst diff --git a/Documentation/sound/alsa/OSS-Emulation.txt b/Documentation/sound/alsa/OSS-Emulation.txt deleted file mode 100644 index 152ca2a3f1bd..000000000000 --- a/Documentation/sound/alsa/OSS-Emulation.txt +++ /dev/null @@ -1,305 +0,0 @@ - NOTES ON KERNEL OSS-EMULATION - ============================= - - Jan. 22, 2004 Takashi Iwai - - -Modules -======= - -ALSA provides a powerful OSS emulation on the kernel. -The OSS emulation for PCM, mixer and sequencer devices is implemented -as add-on kernel modules, snd-pcm-oss, snd-mixer-oss and snd-seq-oss. -When you need to access the OSS PCM, mixer or sequencer devices, the -corresponding module has to be loaded. - -These modules are loaded automatically when the corresponding service -is called. The alias is defined sound-service-x-y, where x and y are -the card number and the minor unit number. Usually you don't have to -define these aliases by yourself. - -Only necessary step for auto-loading of OSS modules is to define the -card alias in /etc/modprobe.d/alsa.conf, such as - - alias sound-slot-0 snd-emu10k1 - -As the second card, define sound-slot-1 as well. -Note that you can't use the aliased name as the target name (i.e. -"alias sound-slot-0 snd-card-0" doesn't work any more like the old -modutils). - -The currently available OSS configuration is shown in -/proc/asound/oss/sndstat. This shows in the same syntax of -/dev/sndstat, which is available on the commercial OSS driver. -On ALSA, you can symlink /dev/sndstat to this proc file. - -Please note that the devices listed in this proc file appear only -after the corresponding OSS-emulation module is loaded. Don't worry -even if "NOT ENABLED IN CONFIG" is shown in it. - - -Device Mapping -============== - -ALSA supports the following OSS device files: - - PCM: - /dev/dspX - /dev/adspX - - Mixer: - /dev/mixerX - - MIDI: - /dev/midi0X - /dev/amidi0X - - Sequencer: - /dev/sequencer - /dev/sequencer2 (aka /dev/music) - -where X is the card number from 0 to 7. - -(NOTE: Some distributions have the device files like /dev/midi0 and - /dev/midi1. They are NOT for OSS but for tclmidi, which is - a totally different thing.) - -Unlike the real OSS, ALSA cannot use the device files more than the -assigned ones. For example, the first card cannot use /dev/dsp1 or -/dev/dsp2, but only /dev/dsp0 and /dev/adsp0. - -As seen above, PCM and MIDI may have two devices. Usually, the first -PCM device (hw:0,0 in ALSA) is mapped to /dev/dsp and the secondary -device (hw:0,1) to /dev/adsp (if available). For MIDI, /dev/midi and -/dev/amidi, respectively. - -You can change this device mapping via the module options of -snd-pcm-oss and snd-rawmidi. In the case of PCM, the following -options are available for snd-pcm-oss: - - dsp_map PCM device number assigned to /dev/dspX - (default = 0) - adsp_map PCM device number assigned to /dev/adspX - (default = 1) - -For example, to map the third PCM device (hw:0,2) to /dev/adsp0, -define like this: - - options snd-pcm-oss adsp_map=2 - -The options take arrays. For configuring the second card, specify -two entries separated by comma. For example, to map the third PCM -device on the second card to /dev/adsp1, define like below: - - options snd-pcm-oss adsp_map=0,2 - -To change the mapping of MIDI devices, the following options are -available for snd-rawmidi: - - midi_map MIDI device number assigned to /dev/midi0X - (default = 0) - amidi_map MIDI device number assigned to /dev/amidi0X - (default = 1) - -For example, to assign the third MIDI device on the first card to -/dev/midi00, define as follows: - - options snd-rawmidi midi_map=2 - - -PCM Mode -======== - -As default, ALSA emulates the OSS PCM with so-called plugin layer, -i.e. tries to convert the sample format, rate or channels -automatically when the card doesn't support it natively. -This will lead to some problems for some applications like quake or -wine, especially if they use the card only in the MMAP mode. - -In such a case, you can change the behavior of PCM per application by -writing a command to the proc file. There is a proc file for each PCM -stream, /proc/asound/cardX/pcmY[cp]/oss, where X is the card number -(zero-based), Y the PCM device number (zero-based), and 'p' is for -playback and 'c' for capture, respectively. Note that this proc file -exists only after snd-pcm-oss module is loaded. - -The command sequence has the following syntax: - - app_name fragments fragment_size [options] - -app_name is the name of application with (higher priority) or without -path. -fragments specifies the number of fragments or zero if no specific -number is given. -fragment_size is the size of fragment in bytes or zero if not given. -options is the optional parameters. The following options are -available: - - disable the application tries to open a pcm device for - this channel but does not want to use it. - direct don't use plugins - block force block open mode - non-block force non-block open mode - partial-frag write also partial fragments (affects playback only) - no-silence do not fill silence ahead to avoid clicks - -The disable option is useful when one stream direction (playback or -capture) is not handled correctly by the application although the -hardware itself does support both directions. -The direct option is used, as mentioned above, to bypass the automatic -conversion and useful for MMAP-applications. -For example, to playback the first PCM device without plugins for -quake, send a command via echo like the following: - - % echo "quake 0 0 direct" > /proc/asound/card0/pcm0p/oss - -While quake wants only playback, you may append the second command -to notify driver that only this direction is about to be allocated: - - % echo "quake 0 0 disable" > /proc/asound/card0/pcm0c/oss - -The permission of proc files depend on the module options of snd. -As default it's set as root, so you'll likely need to be superuser for -sending the command above. - -The block and non-block options are used to change the behavior of -opening the device file. - -As default, ALSA behaves as original OSS drivers, i.e. does not block -the file when it's busy. The -EBUSY error is returned in this case. - -This blocking behavior can be changed globally via nonblock_open -module option of snd-pcm-oss. For using the blocking mode as default -for OSS devices, define like the following: - - options snd-pcm-oss nonblock_open=0 - -The partial-frag and no-silence commands have been added recently. -Both commands are for optimization use only. The former command -specifies to invoke the write transfer only when the whole fragment is -filled. The latter stops writing the silence data ahead -automatically. Both are disabled as default. - -You can check the currently defined configuration by reading the proc -file. The read image can be sent to the proc file again, hence you -can save the current configuration - - % cat /proc/asound/card0/pcm0p/oss > /somewhere/oss-cfg - -and restore it like - - % cat /somewhere/oss-cfg > /proc/asound/card0/pcm0p/oss - -Also, for clearing all the current configuration, send "erase" command -as below: - - % echo "erase" > /proc/asound/card0/pcm0p/oss - - -Mixer Elements -============== - -Since ALSA has completely different mixer interface, the emulation of -OSS mixer is relatively complicated. ALSA builds up a mixer element -from several different ALSA (mixer) controls based on the name -string. For example, the volume element SOUND_MIXER_PCM is composed -from "PCM Playback Volume" and "PCM Playback Switch" controls for the -playback direction and from "PCM Capture Volume" and "PCM Capture -Switch" for the capture directory (if exists). When the PCM volume of -OSS is changed, all the volume and switch controls above are adjusted -automatically. - -As default, ALSA uses the following control for OSS volumes: - - OSS volume ALSA control Index - ----------------------------------------------------- - SOUND_MIXER_VOLUME Master 0 - SOUND_MIXER_BASS Tone Control - Bass 0 - SOUND_MIXER_TREBLE Tone Control - Treble 0 - SOUND_MIXER_SYNTH Synth 0 - SOUND_MIXER_PCM PCM 0 - SOUND_MIXER_SPEAKER PC Speaker 0 - SOUND_MIXER_LINE Line 0 - SOUND_MIXER_MIC Mic 0 - SOUND_MIXER_CD CD 0 - SOUND_MIXER_IMIX Monitor Mix 0 - SOUND_MIXER_ALTPCM PCM 1 - SOUND_MIXER_RECLEV (not assigned) - SOUND_MIXER_IGAIN Capture 0 - SOUND_MIXER_OGAIN Playback 0 - SOUND_MIXER_LINE1 Aux 0 - SOUND_MIXER_LINE2 Aux 1 - SOUND_MIXER_LINE3 Aux 2 - SOUND_MIXER_DIGITAL1 Digital 0 - SOUND_MIXER_DIGITAL2 Digital 1 - SOUND_MIXER_DIGITAL3 Digital 2 - SOUND_MIXER_PHONEIN Phone 0 - SOUND_MIXER_PHONEOUT Phone 1 - SOUND_MIXER_VIDEO Video 0 - SOUND_MIXER_RADIO Radio 0 - SOUND_MIXER_MONITOR Monitor 0 - -The second column is the base-string of the corresponding ALSA -control. In fact, the controls with "XXX [Playback|Capture] -[Volume|Switch]" will be checked in addition. - -The current assignment of these mixer elements is listed in the proc -file, /proc/asound/cardX/oss_mixer, which will be like the following - - VOLUME "Master" 0 - BASS "" 0 - TREBLE "" 0 - SYNTH "" 0 - PCM "PCM" 0 - ... - -where the first column is the OSS volume element, the second column -the base-string of the corresponding ALSA control, and the third the -control index. When the string is empty, it means that the -corresponding OSS control is not available. - -For changing the assignment, you can write the configuration to this -proc file. For example, to map "Wave Playback" to the PCM volume, -send the command like the following: - - % echo 'VOLUME "Wave Playback" 0' > /proc/asound/card0/oss_mixer - -The command is exactly as same as listed in the proc file. You can -change one or more elements, one volume per line. In the last -example, both "Wave Playback Volume" and "Wave Playback Switch" will -be affected when PCM volume is changed. - -Like the case of PCM proc file, the permission of proc files depend on -the module options of snd. you'll likely need to be superuser for -sending the command above. - -As well as in the case of PCM proc file, you can save and restore the -current mixer configuration by reading and writing the whole file -image. - - -Duplex Streams -============== - -Note that when attempting to use a single device file for playback and -capture, the OSS API provides no way to set the format, sample rate or -number of channels different in each direction. Thus - io_handle = open("device", O_RDWR) -will only function correctly if the values are the same in each direction. - -To use different values in the two directions, use both - input_handle = open("device", O_RDONLY) - output_handle = open("device", O_WRONLY) -and set the values for the corresponding handle. - - -Unsupported Features -==================== - -MMAP on ICE1712 driver ----------------------- -ICE1712 supports only the unconventional format, interleaved -10-channels 24bit (packed in 32bit) format. Therefore you cannot mmap -the buffer as the conventional (mono or 2-channels, 8 or 16bit) format -on OSS. - diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst index dd4fcbcb2b92..5b3033c556d0 100644 --- a/Documentation/sound/designs/index.rst +++ b/Documentation/sound/designs/index.rst @@ -7,3 +7,4 @@ Designs and Implementations channel-mapping-api procfile powersave + oss-emulation diff --git a/Documentation/sound/designs/oss-emulation.rst b/Documentation/sound/designs/oss-emulation.rst new file mode 100644 index 000000000000..e8dcb9633e7b --- /dev/null +++ b/Documentation/sound/designs/oss-emulation.rst @@ -0,0 +1,336 @@ +============================= +Notes on Kernel OSS-Emulation +============================= + +Jan. 22, 2004 Takashi Iwai + + +Modules +======= + +ALSA provides a powerful OSS emulation on the kernel. +The OSS emulation for PCM, mixer and sequencer devices is implemented +as add-on kernel modules, snd-pcm-oss, snd-mixer-oss and snd-seq-oss. +When you need to access the OSS PCM, mixer or sequencer devices, the +corresponding module has to be loaded. + +These modules are loaded automatically when the corresponding service +is called. The alias is defined ``sound-service-x-y``, where x and y are +the card number and the minor unit number. Usually you don't have to +define these aliases by yourself. + +Only necessary step for auto-loading of OSS modules is to define the +card alias in ``/etc/modprobe.d/alsa.conf``, such as:: + + alias sound-slot-0 snd-emu10k1 + +As the second card, define ``sound-slot-1`` as well. +Note that you can't use the aliased name as the target name (i.e. +``alias sound-slot-0 snd-card-0`` doesn't work any more like the old +modutils). + +The currently available OSS configuration is shown in +/proc/asound/oss/sndstat. This shows in the same syntax of +/dev/sndstat, which is available on the commercial OSS driver. +On ALSA, you can symlink /dev/sndstat to this proc file. + +Please note that the devices listed in this proc file appear only +after the corresponding OSS-emulation module is loaded. Don't worry +even if "NOT ENABLED IN CONFIG" is shown in it. + + +Device Mapping +============== + +ALSA supports the following OSS device files: +:: + + PCM: + /dev/dspX + /dev/adspX + + Mixer: + /dev/mixerX + + MIDI: + /dev/midi0X + /dev/amidi0X + + Sequencer: + /dev/sequencer + /dev/sequencer2 (aka /dev/music) + +where X is the card number from 0 to 7. + +(NOTE: Some distributions have the device files like /dev/midi0 and +/dev/midi1. They are NOT for OSS but for tclmidi, which is +a totally different thing.) + +Unlike the real OSS, ALSA cannot use the device files more than the +assigned ones. For example, the first card cannot use /dev/dsp1 or +/dev/dsp2, but only /dev/dsp0 and /dev/adsp0. + +As seen above, PCM and MIDI may have two devices. Usually, the first +PCM device (``hw:0,0`` in ALSA) is mapped to /dev/dsp and the secondary +device (``hw:0,1``) to /dev/adsp (if available). For MIDI, /dev/midi and +/dev/amidi, respectively. + +You can change this device mapping via the module options of +snd-pcm-oss and snd-rawmidi. In the case of PCM, the following +options are available for snd-pcm-oss: + +dsp_map + PCM device number assigned to /dev/dspX + (default = 0) +adsp_map + PCM device number assigned to /dev/adspX + (default = 1) + +For example, to map the third PCM device (``hw:0,2``) to /dev/adsp0, +define like this: +:: + + options snd-pcm-oss adsp_map=2 + +The options take arrays. For configuring the second card, specify +two entries separated by comma. For example, to map the third PCM +device on the second card to /dev/adsp1, define like below: +:: + + options snd-pcm-oss adsp_map=0,2 + +To change the mapping of MIDI devices, the following options are +available for snd-rawmidi: + +midi_map + MIDI device number assigned to /dev/midi0X + (default = 0) +amidi_map + MIDI device number assigned to /dev/amidi0X + (default = 1) + +For example, to assign the third MIDI device on the first card to +/dev/midi00, define as follows: +:: + + options snd-rawmidi midi_map=2 + + +PCM Mode +======== + +As default, ALSA emulates the OSS PCM with so-called plugin layer, +i.e. tries to convert the sample format, rate or channels +automatically when the card doesn't support it natively. +This will lead to some problems for some applications like quake or +wine, especially if they use the card only in the MMAP mode. + +In such a case, you can change the behavior of PCM per application by +writing a command to the proc file. There is a proc file for each PCM +stream, ``/proc/asound/cardX/pcmY[cp]/oss``, where X is the card number +(zero-based), Y the PCM device number (zero-based), and ``p`` is for +playback and ``c`` for capture, respectively. Note that this proc file +exists only after snd-pcm-oss module is loaded. + +The command sequence has the following syntax: +:: + + app_name fragments fragment_size [options] + +``app_name`` is the name of application with (higher priority) or without +path. +``fragments`` specifies the number of fragments or zero if no specific +number is given. +``fragment_size`` is the size of fragment in bytes or zero if not given. +``options`` is the optional parameters. The following options are +available: + +disable + the application tries to open a pcm device for + this channel but does not want to use it. +direct + don't use plugins +block + force block open mode +non-block + force non-block open mode +partial-frag + write also partial fragments (affects playback only) +no-silence + do not fill silence ahead to avoid clicks + +The ``disable`` option is useful when one stream direction (playback or +capture) is not handled correctly by the application although the +hardware itself does support both directions. +The ``direct`` option is used, as mentioned above, to bypass the automatic +conversion and useful for MMAP-applications. +For example, to playback the first PCM device without plugins for +quake, send a command via echo like the following: +:: + + % echo "quake 0 0 direct" > /proc/asound/card0/pcm0p/oss + +While quake wants only playback, you may append the second command +to notify driver that only this direction is about to be allocated: +:: + + % echo "quake 0 0 disable" > /proc/asound/card0/pcm0c/oss + +The permission of proc files depend on the module options of snd. +As default it's set as root, so you'll likely need to be superuser for +sending the command above. + +The block and non-block options are used to change the behavior of +opening the device file. + +As default, ALSA behaves as original OSS drivers, i.e. does not block +the file when it's busy. The -EBUSY error is returned in this case. + +This blocking behavior can be changed globally via nonblock_open +module option of snd-pcm-oss. For using the blocking mode as default +for OSS devices, define like the following: +:: + + options snd-pcm-oss nonblock_open=0 + +The ``partial-frag`` and ``no-silence`` commands have been added recently. +Both commands are for optimization use only. The former command +specifies to invoke the write transfer only when the whole fragment is +filled. The latter stops writing the silence data ahead +automatically. Both are disabled as default. + +You can check the currently defined configuration by reading the proc +file. The read image can be sent to the proc file again, hence you +can save the current configuration +:: + + % cat /proc/asound/card0/pcm0p/oss > /somewhere/oss-cfg + +and restore it like +:: + + % cat /somewhere/oss-cfg > /proc/asound/card0/pcm0p/oss + +Also, for clearing all the current configuration, send ``erase`` command +as below: +:: + + % echo "erase" > /proc/asound/card0/pcm0p/oss + + +Mixer Elements +============== + +Since ALSA has completely different mixer interface, the emulation of +OSS mixer is relatively complicated. ALSA builds up a mixer element +from several different ALSA (mixer) controls based on the name +string. For example, the volume element SOUND_MIXER_PCM is composed +from "PCM Playback Volume" and "PCM Playback Switch" controls for the +playback direction and from "PCM Capture Volume" and "PCM Capture +Switch" for the capture directory (if exists). When the PCM volume of +OSS is changed, all the volume and switch controls above are adjusted +automatically. + +As default, ALSA uses the following control for OSS volumes: + +==================== ===================== ===== +OSS volume ALSA control Index +==================== ===================== ===== +SOUND_MIXER_VOLUME Master 0 +SOUND_MIXER_BASS Tone Control - Bass 0 +SOUND_MIXER_TREBLE Tone Control - Treble 0 +SOUND_MIXER_SYNTH Synth 0 +SOUND_MIXER_PCM PCM 0 +SOUND_MIXER_SPEAKER PC Speaker 0 +SOUND_MIXER_LINE Line 0 +SOUND_MIXER_MIC Mic 0 +SOUND_MIXER_CD CD 0 +SOUND_MIXER_IMIX Monitor Mix 0 +SOUND_MIXER_ALTPCM PCM 1 +SOUND_MIXER_RECLEV (not assigned) +SOUND_MIXER_IGAIN Capture 0 +SOUND_MIXER_OGAIN Playback 0 +SOUND_MIXER_LINE1 Aux 0 +SOUND_MIXER_LINE2 Aux 1 +SOUND_MIXER_LINE3 Aux 2 +SOUND_MIXER_DIGITAL1 Digital 0 +SOUND_MIXER_DIGITAL2 Digital 1 +SOUND_MIXER_DIGITAL3 Digital 2 +SOUND_MIXER_PHONEIN Phone 0 +SOUND_MIXER_PHONEOUT Phone 1 +SOUND_MIXER_VIDEO Video 0 +SOUND_MIXER_RADIO Radio 0 +SOUND_MIXER_MONITOR Monitor 0 +==================== ===================== ===== + +The second column is the base-string of the corresponding ALSA +control. In fact, the controls with ``XXX [Playback|Capture] +[Volume|Switch]`` will be checked in addition. + +The current assignment of these mixer elements is listed in the proc +file, /proc/asound/cardX/oss_mixer, which will be like the following +:: + + VOLUME "Master" 0 + BASS "" 0 + TREBLE "" 0 + SYNTH "" 0 + PCM "PCM" 0 + ... + +where the first column is the OSS volume element, the second column +the base-string of the corresponding ALSA control, and the third the +control index. When the string is empty, it means that the +corresponding OSS control is not available. + +For changing the assignment, you can write the configuration to this +proc file. For example, to map "Wave Playback" to the PCM volume, +send the command like the following: +:: + + % echo 'VOLUME "Wave Playback" 0' > /proc/asound/card0/oss_mixer + +The command is exactly as same as listed in the proc file. You can +change one or more elements, one volume per line. In the last +example, both "Wave Playback Volume" and "Wave Playback Switch" will +be affected when PCM volume is changed. + +Like the case of PCM proc file, the permission of proc files depend on +the module options of snd. you'll likely need to be superuser for +sending the command above. + +As well as in the case of PCM proc file, you can save and restore the +current mixer configuration by reading and writing the whole file +image. + + +Duplex Streams +============== + +Note that when attempting to use a single device file for playback and +capture, the OSS API provides no way to set the format, sample rate or +number of channels different in each direction. Thus +:: + + io_handle = open("device", O_RDWR) + +will only function correctly if the values are the same in each direction. + +To use different values in the two directions, use both +:: + + input_handle = open("device", O_RDONLY) + output_handle = open("device", O_WRONLY) + +and set the values for the corresponding handle. + + +Unsupported Features +==================== + +MMAP on ICE1712 driver +---------------------- +ICE1712 supports only the unconventional format, interleaved +10-channels 24bit (packed in 32bit) format. Therefore you cannot mmap +the buffer as the conventional (mono or 2-channels, 8 or 16bit) format +on OSS. -- cgit v1.2.3 From 07aecc06eb32ff0010dff69438806b6f200fc1fd Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 16:46:02 +0100 Subject: ALSA: doc: ReSTize seq_oss document Converted from an ancient plain HTML document. It's much readable now! Put to designs subdirectory with a slight rename. Signed-off-by: Takashi Iwai --- Documentation/sound/alsa/seq_oss.html | 409 -------------------------------- Documentation/sound/designs/index.rst | 1 + Documentation/sound/designs/seq-oss.rst | 371 +++++++++++++++++++++++++++++ 3 files changed, 372 insertions(+), 409 deletions(-) delete mode 100644 Documentation/sound/alsa/seq_oss.html create mode 100644 Documentation/sound/designs/seq-oss.rst diff --git a/Documentation/sound/alsa/seq_oss.html b/Documentation/sound/alsa/seq_oss.html deleted file mode 100644 index 9663b45f6fde..000000000000 --- a/Documentation/sound/alsa/seq_oss.html +++ /dev/null @@ -1,409 +0,0 @@ - - - - OSS Sequencer Emulation on ALSA - - - -
-

- -

- -
-

-OSS Sequencer Emulation on ALSA

- -
-

Copyright (c) 1998,1999 by Takashi Iwai -<iwai@ww.uni-erlangen.de> -

ver.0.1.8; Nov. 16, 1999 -

- -

- -

-1. Description

-This directory contains the OSS sequencer emulation driver on ALSA. Note -that this program is still in the development state. -

What this does - it provides the emulation of the OSS sequencer, access -via -/dev/sequencer and /dev/music devices. -The most of applications using OSS can run if the appropriate ALSA -sequencer is prepared. -

The following features are emulated by this driver: -

    -
  • -Normal sequencer and MIDI events:
    • - -
    They are converted to the ALSA sequencer events, and sent to the corresponding -port. -
  • -Timer events:
    • - -
    The timer is not selectable by ioctl. The control rate is fixed to -100 regardless of HZ. That is, even on Alpha system, a tick is always -1/100 second. The base rate and tempo can be changed in /dev/music. - -
  • -Patch loading:
    • - -
    It purely depends on the synth drivers whether it's supported since -the patch loading is realized by callback to the synth driver. -
  • -I/O controls:
    • - -
    Most of controls are accepted. Some controls -are dependent on the synth driver, as well as even on original OSS.
-Furthermore, you can find the following advanced features: -
    -
  • -Better queue mechanism:
    • - -
    The events are queued before processing them. -
  • -Multiple applications:
    • - -
    You can run two or more applications simultaneously (even for OSS sequencer)! -However, each MIDI device is exclusive - that is, if a MIDI device is opened -once by some application, other applications can't use it. No such a restriction -in synth devices. -
  • -Real-time event processing:
    • - -
    The events can be processed in real time without using out of bound -ioctl. To switch to real-time mode, send ABSTIME 0 event. The followed -events will be processed in real-time without queued. To switch off the -real-time mode, send RELTIME 0 event. -
  • -/proc interface:
    • - -
    The status of applications and devices can be shown via /proc/asound/seq/oss -at any time. In the later version, configuration will be changed via /proc -interface, too.
- -

-2. Installation

-Run configure script with both sequencer support (--with-sequencer=yes) -and OSS emulation (--with-oss=yes) options. A module snd-seq-oss.o -will be created. If the synth module of your sound card supports for OSS -emulation (so far, only Emu8000 driver), this module will be loaded automatically. -Otherwise, you need to load this module manually. -

At beginning, this module probes all the MIDI ports which have been -already connected to the sequencer. Once after that, the creation and deletion -of ports are watched by announcement mechanism of ALSA sequencer. -

The available synth and MIDI devices can be found in proc interface. -Run "cat /proc/asound/seq/oss", and check the devices. For example, -if you use an AWE64 card, you'll see like the following: -

        OSS sequencer emulation version 0.1.8
-        ALSA client number 63
-        ALSA receiver port 0
-
-        Number of applications: 0
-
-        Number of synth devices: 1
-
-        synth 0: [EMU8000]
-          type 0x1 : subtype 0x20 : voices 32
-          capabilties : ioctl enabled / load_patch enabled
-
-        Number of MIDI devices: 3
-
-        midi 0: [Emu8000 Port-0] ALSA port 65:0
-          capability write / opened none
-
-        midi 1: [Emu8000 Port-1] ALSA port 65:1
-          capability write / opened none
-
-        midi 2: [0: MPU-401 (UART)] ALSA port 64:0
-          capability read/write / opened none
-Note that the device number may be different from the information of -/proc/asound/oss-devices -or ones of the original OSS driver. Use the device number listed in /proc/asound/seq/oss -to play via OSS sequencer emulation. -

-3. Using Synthesizer Devices

-Run your favorite program. I've tested playmidi-2.4, awemidi-0.4.3, gmod-3.1 -and xmp-1.1.5. You can load samples via /dev/sequencer like sfxload, -too. -

If the lowlevel driver supports multiple access to synth devices (like -Emu8000 driver), two or more applications are allowed to run at the same -time. -

-4. Using MIDI Devices

-So far, only MIDI output was tested. MIDI input was not checked at all, -but hopefully it will work. Use the device number listed in /proc/asound/seq/oss. -Be aware that these numbers are mostly different from the list in -/proc/asound/oss-devices. -

-5. Module Options

-The following module options are available: -
    -
  • -maxqlen
    • - -
    specifies the maximum read/write queue length. This queue is private -for OSS sequencer, so that it is independent from the queue length of ALSA -sequencer. Default value is 1024. -
  • -seq_oss_debug
    • - -
    specifies the debug level and accepts zero (= no debug message) or -positive integer. Default value is 0.
- -

-6. Queue Mechanism

-OSS sequencer emulation uses an ALSA priority queue. The -events from /dev/sequencer are processed and put onto the queue -specified by module option. -

All the events from /dev/sequencer are parsed at beginning. -The timing events are also parsed at this moment, so that the events may -be processed in real-time. Sending an event ABSTIME 0 switches the operation -mode to real-time mode, and sending an event RELTIME 0 switches it off. -In the real-time mode, all events are dispatched immediately. -

The queued events are dispatched to the corresponding ALSA sequencer -ports after scheduled time by ALSA sequencer dispatcher. -

If the write-queue is full, the application sleeps until a certain amount -(as default one half) becomes empty in blocking mode. The synchronization -to write timing was implemented, too. -

The input from MIDI devices or echo-back events are stored on read FIFO -queue. If application reads /dev/sequencer in blocking mode, the -process will be awaked. - -

-7. Interface to Synthesizer Device

- -

-7.1. Registration

-To register an OSS synthesizer device, use snd_seq_oss_synth_register -function. -
int snd_seq_oss_synth_register(char *name, int type, int subtype, int nvoices,
-                              snd_seq_oss_callback_t *oper, void *private_data)
-The arguments name, type, subtype and -nvoices -are used for making the appropriate synth_info structure for ioctl. The -return value is an index number of this device. This index must be remembered -for unregister. If registration is failed, -errno will be returned. -

To release this device, call snd_seq_oss_synth_unregister function: -

int snd_seq_oss_synth_unregister(int index),
-where the index is the index number returned by register function. -

-7.2. Callbacks

-OSS synthesizer devices have capability for sample downloading and ioctls -like sample reset. In OSS emulation, these special features are realized -by using callbacks. The registration argument oper is used to specify these -callbacks. The following callback functions must be defined: -
snd_seq_oss_callback_t:
-        int (*open)(snd_seq_oss_arg_t *p, void *closure);
-        int (*close)(snd_seq_oss_arg_t *p);
-        int (*ioctl)(snd_seq_oss_arg_t *p, unsigned int cmd, unsigned long arg);
-        int (*load_patch)(snd_seq_oss_arg_t *p, int format, const char *buf, int offs, int count);
-        int (*reset)(snd_seq_oss_arg_t *p);
-Except for open and close callbacks, they are allowed
-to be NULL.
-
Each callback function takes the argument type snd_seq_oss_arg_t as the
-first argument.
-
struct snd_seq_oss_arg_t {
-        int app_index;
-        int file_mode;
-        int seq_mode;
-        snd_seq_addr_t addr;
-        void *private_data;
-        int event_passing;
-};

-The first three fields, app_index, file_mode and
-seq_mode
-are initialized by OSS sequencer. The app_index is the application
-index which is unique to each application opening OSS sequencer. The
-file_mode
-is bit-flags indicating the file operation mode. See
-seq_oss.h
-for its meaning. The seq_mode is sequencer operation mode. In
-the current version, only SND_OSSSEQ_MODE_SYNTH is used.
-
The next two fields, addr and private_data, must be
-filled by the synth driver at open callback. The addr contains
-the address of ALSA sequencer port which is assigned to this device. If
-the driver allocates memory for private_data, it must be released
-in close callback by itself.
-
The last field, event_passing, indicates how to translate note-on
-/ off events. In PROCESS_EVENTS mode, the note 255 is regarded
-as velocity change, and key pressure event is passed to the port. In PASS_EVENTS
-mode, all note on/off events are passed to the port without modified. PROCESS_KEYPRESS
-mode checks the note above 128 and regards it as key pressure event (mainly
-for Emu8000 driver).
-

-7.2.1. Open Callback

-The open is called at each time this device is opened by an application
-using OSS sequencer. This must not be NULL. Typically, the open callback
-does the following procedure:
-
    
-
  1. 
-Allocate private data record.
    2. 
-
-
  2. 
-Create an ALSA sequencer port.
    3. 
-
-
  3. 
-Set the new port address on arg->addr.
    4. 
-
-
  4. 
-Set the private data record pointer on arg->private_data.
    5. 
-

-Note that the type bit-flags in port_info of this synth port must NOT contain
-TYPE_MIDI_GENERIC
-bit. Instead, TYPE_SPECIFIC should be used. Also, CAP_SUBSCRIPTION
-bit should NOT be included, too. This is necessary to tell it from other
-normal MIDI devices. If the open procedure succeeded, return zero. Otherwise,
-return -errno.
-

-7.2.2 Ioctl Callback

-The ioctl callback is called when the sequencer receives device-specific
-ioctls. The following two ioctls should be processed by this callback:
-
    
-
  • 
-IOCTL_SEQ_RESET_SAMPLES
    • 
-
-
    reset all samples on memory -- return 0
-
  • 
-IOCTL_SYNTH_MEMAVL
    • 
-
-
    return the available memory size
-
  • 
-FM_4OP_ENABLE
    • 
-
-
    can be ignored usually

-The other ioctls are processed inside the sequencer without passing to
-the lowlevel driver.
-

-7.2.3 Load_Patch Callback

-The load_patch callback is used for sample-downloading. This callback
-must read the data on user-space and transfer to each device. Return 0
-if succeeded, and -errno if failed. The format argument is the patch key
-in patch_info record. The buf is user-space pointer where patch_info record
-is stored. The offs can be ignored. The count is total data size of this
-sample data.
-

-7.2.4 Close Callback

-The close callback is called when this device is closed by the
-application. If any private data was allocated in open callback, it must
-be released in the close callback. The deletion of ALSA port should be
-done here, too. This callback must not be NULL.
-

-7.2.5 Reset Callback

-The reset callback is called when sequencer device is reset or
-closed by applications. The callback should turn off the sounds on the
-relevant port immediately, and initialize the status of the port. If this
-callback is undefined, OSS seq sends a HEARTBEAT event to the
-port.
-

-7.3 Events

-Most of the events are processed by sequencer and translated to the adequate
-ALSA sequencer events, so that each synth device can receive by input_event
-callback of ALSA sequencer port. The following ALSA events should be implemented
-by the driver:
-
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
ALSA eventOriginal OSS events
NOTEONSEQ_NOTEON
-
MIDI_NOTEON
NOTESEQ_NOTEOFF
-
MIDI_NOTEOFF
KEYPRESSMIDI_KEY_PRESSURE
CHANPRESSSEQ_AFTERTOUCH
-
MIDI_CHN_PRESSURE
PGMCHANGESEQ_PGMCHANGE
-
MIDI_PGM_CHANGE
PITCHBENDSEQ_CONTROLLER(CTRL_PITCH_BENDER)
-
MIDI_PITCH_BEND
CONTROLLERMIDI_CTL_CHANGE
-
SEQ_BALANCE (with CTL_PAN)
CONTROL14SEQ_CONTROLLER
REGPARAMSEQ_CONTROLLER(CTRL_PITCH_BENDER_RANGE)
SYSEXSEQ_SYSEX

-
-
The most of these behavior can be realized by MIDI emulation driver
-included in the Emu8000 lowlevel driver. In the future release, this module
-will be independent.
-
Some OSS events (SEQ_PRIVATE and SEQ_VOLUME events) are passed as event
-type SND_SEQ_OSS_PRIVATE.  The OSS sequencer passes these event 8 byte
-packets without any modification. The lowlevel driver should process these
-events appropriately.
-

-8. Interface to MIDI Device

-Since the OSS emulation probes the creation and deletion of ALSA MIDI sequencer
-ports automatically by receiving announcement from ALSA sequencer, the
-MIDI devices don't need to be registered explicitly like synth devices.
-However, the MIDI port_info registered to ALSA sequencer must include a group
-name SND_SEQ_GROUP_DEVICE and a capability-bit CAP_READ or
-CAP_WRITE. Also, subscription capabilities, CAP_SUBS_READ or CAP_SUBS_WRITE,
-must be defined, too. If these conditions are not satisfied, the port is not
-registered as OSS sequencer MIDI device.
-
The events via MIDI devices are parsed in OSS sequencer and converted
-to the corresponding ALSA sequencer events. The input from MIDI sequencer
-is also converted to MIDI byte events by OSS sequencer. This works just
-a reverse way of seq_midi module.
-

-9. Known Problems / TODO's

-
-
    
-
  • 
-Patch loading via ALSA instrument layer is not implemented yet.
    • 
-

-
-
-
diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst
index 5b3033c556d0..0ca3a6b0a5ce 100644
--- a/Documentation/sound/designs/index.rst
+++ b/Documentation/sound/designs/index.rst
@@ -8,3 +8,4 @@ Designs and Implementations
    procfile
    powersave
    oss-emulation
+   seq-oss
diff --git a/Documentation/sound/designs/seq-oss.rst b/Documentation/sound/designs/seq-oss.rst
new file mode 100644
index 000000000000..e82ffe0e7f43
--- /dev/null
+++ b/Documentation/sound/designs/seq-oss.rst
@@ -0,0 +1,371 @@
+===============================
+OSS Sequencer Emulation on ALSA
+===============================
+
+Copyright (c) 1998,1999 by Takashi Iwai
+
+ver.0.1.8; Nov. 16, 1999
+
+Description
+===========
+
+This directory contains the OSS sequencer emulation driver on ALSA. Note
+that this program is still in the development state.
+
+What this does - it provides the emulation of the OSS sequencer, access
+via ``/dev/sequencer`` and ``/dev/music`` devices.
+The most of applications using OSS can run if the appropriate ALSA
+sequencer is prepared.
+
+The following features are emulated by this driver:
+
+* Normal sequencer and MIDI events:
+
+    They are converted to the ALSA sequencer events, and sent to the
+    corresponding port.
+
+* Timer events:
+
+    The timer is not selectable by ioctl. The control rate is fixed to
+    100 regardless of HZ. That is, even on Alpha system, a tick is always
+    1/100 second. The base rate and tempo can be changed in ``/dev/music``.
+
+* Patch loading:
+
+    It purely depends on the synth drivers whether it's supported since
+    the patch loading is realized by callback to the synth driver.
+
+* I/O controls:
+
+    Most of controls are accepted. Some controls
+    are dependent on the synth driver, as well as even on original OSS.
+
+Furthermore, you can find the following advanced features:
+
+* Better queue mechanism:
+
+    The events are queued before processing them.
+
+* Multiple applications:
+
+    You can run two or more applications simultaneously (even for OSS
+    sequencer)!
+    However, each MIDI device is exclusive - that is, if a MIDI device
+    is opened once by some application, other applications can't use
+    it. No such a restriction in synth devices.
+
+* Real-time event processing:
+
+    The events can be processed in real time without using out of bound
+    ioctl. To switch to real-time mode, send ABSTIME 0 event. The followed
+    events will be processed in real-time without queued. To switch off the
+    real-time mode, send RELTIME 0 event.
+
+* ``/proc`` interface:
+
+    The status of applications and devices can be shown via
+    ``/proc/asound/seq/oss`` at any time. In the later version,
+    configuration will be changed via ``/proc`` interface, too.
+
+
+Installation
+============
+
+Run configure script with both sequencer support (``--with-sequencer=yes``)
+and OSS emulation (``--with-oss=yes``) options. A module ``snd-seq-oss.o``
+will be created. If the synth module of your sound card supports for OSS
+emulation (so far, only Emu8000 driver), this module will be loaded
+automatically.
+Otherwise, you need to load this module manually.
+
+At beginning, this module probes all the MIDI ports which have been
+already connected to the sequencer. Once after that, the creation and deletion
+of ports are watched by announcement mechanism of ALSA sequencer.
+
+The available synth and MIDI devices can be found in proc interface.
+Run ``cat /proc/asound/seq/oss``, and check the devices. For example,
+if you use an AWE64 card, you'll see like the following:
+::
+
+    OSS sequencer emulation version 0.1.8
+    ALSA client number 63
+    ALSA receiver port 0
+
+    Number of applications: 0
+
+    Number of synth devices: 1
+    synth 0: [EMU8000]
+      type 0x1 : subtype 0x20 : voices 32
+      capabilties : ioctl enabled / load_patch enabled
+
+    Number of MIDI devices: 3
+    midi 0: [Emu8000 Port-0] ALSA port 65:0
+      capability write / opened none
+
+    midi 1: [Emu8000 Port-1] ALSA port 65:1
+      capability write / opened none
+
+    midi 2: [0: MPU-401 (UART)] ALSA port 64:0
+      capability read/write / opened none
+
+Note that the device number may be different from the information of
+``/proc/asound/oss-devices`` or ones of the original OSS driver.
+Use the device number listed in ``/proc/asound/seq/oss``
+to play via OSS sequencer emulation.
+
+Using Synthesizer Devices
+=========================
+
+Run your favorite program. I've tested playmidi-2.4, awemidi-0.4.3, gmod-3.1
+and xmp-1.1.5. You can load samples via ``/dev/sequencer`` like sfxload,
+too.
+
+If the lowlevel driver supports multiple access to synth devices (like
+Emu8000 driver), two or more applications are allowed to run at the same
+time.
+
+Using MIDI Devices
+==================
+
+So far, only MIDI output was tested. MIDI input was not checked at all,
+but hopefully it will work. Use the device number listed in
+``/proc/asound/seq/oss``.
+Be aware that these numbers are mostly different from the list in
+``/proc/asound/oss-devices``.
+
+Module Options
+==============
+
+The following module options are available:
+
+maxqlen
+  specifies the maximum read/write queue length. This queue is private
+  for OSS sequencer, so that it is independent from the queue length of ALSA
+  sequencer. Default value is 1024.
+
+seq_oss_debug
+  specifies the debug level and accepts zero (= no debug message) or
+  positive integer. Default value is 0.
+
+Queue Mechanism
+===============
+
+OSS sequencer emulation uses an ALSA priority queue. The
+events from ``/dev/sequencer`` are processed and put onto the queue
+specified by module option.
+
+All the events from ``/dev/sequencer`` are parsed at beginning.
+The timing events are also parsed at this moment, so that the events may
+be processed in real-time. Sending an event ABSTIME 0 switches the operation
+mode to real-time mode, and sending an event RELTIME 0 switches it off.
+In the real-time mode, all events are dispatched immediately.
+
+The queued events are dispatched to the corresponding ALSA sequencer
+ports after scheduled time by ALSA sequencer dispatcher.
+
+If the write-queue is full, the application sleeps until a certain amount
+(as default one half) becomes empty in blocking mode. The synchronization
+to write timing was implemented, too.
+
+The input from MIDI devices or echo-back events are stored on read FIFO
+queue. If application reads ``/dev/sequencer`` in blocking mode, the
+process will be awaked.
+
+Interface to Synthesizer Device
+===============================
+
+Registration
+------------
+
+To register an OSS synthesizer device, use snd_seq_oss_synth_register()
+function:
+::
+
+  int snd_seq_oss_synth_register(char *name, int type, int subtype, int nvoices,
+          snd_seq_oss_callback_t *oper, void *private_data)
+
+The arguments ``name``, ``type``, ``subtype`` and ``nvoices``
+are used for making the appropriate synth_info structure for ioctl. The
+return value is an index number of this device. This index must be remembered
+for unregister. If registration is failed, -errno will be returned.
+
+To release this device, call snd_seq_oss_synth_unregister() function:
+::
+
+  int snd_seq_oss_synth_unregister(int index)
+
+where the ``index`` is the index number returned by register function.
+
+Callbacks
+---------
+
+OSS synthesizer devices have capability for sample downloading and ioctls
+like sample reset. In OSS emulation, these special features are realized
+by using callbacks. The registration argument oper is used to specify these
+callbacks. The following callback functions must be defined:
+::
+
+  snd_seq_oss_callback_t:
+   int (*open)(snd_seq_oss_arg_t *p, void *closure);
+   int (*close)(snd_seq_oss_arg_t *p);
+   int (*ioctl)(snd_seq_oss_arg_t *p, unsigned int cmd, unsigned long arg);
+   int (*load_patch)(snd_seq_oss_arg_t *p, int format, const char *buf, int offs, int count);
+   int (*reset)(snd_seq_oss_arg_t *p);
+
+Except for ``open`` and ``close`` callbacks, they are allowed to be NULL.
+
+Each callback function takes the argument type ``snd_seq_oss_arg_t`` as the
+first argument.
+::
+
+  struct snd_seq_oss_arg_t {
+      int app_index;
+      int file_mode;
+      int seq_mode;
+      snd_seq_addr_t addr;
+      void *private_data;
+      int event_passing;
+  };
+
+The first three fields, ``app_index``, ``file_mode`` and ``seq_mode``
+are initialized by OSS sequencer. The ``app_index`` is the application
+index which is unique to each application opening OSS sequencer. The
+``file_mode`` is bit-flags indicating the file operation mode. See
+``seq_oss.h`` for its meaning. The ``seq_mode`` is sequencer operation
+mode. In the current version, only ``SND_OSSSEQ_MODE_SYNTH`` is used.
+
+The next two fields, ``addr`` and ``private_data``, must be
+filled by the synth driver at open callback. The ``addr`` contains
+the address of ALSA sequencer port which is assigned to this device. If
+the driver allocates memory for ``private_data``, it must be released
+in close callback by itself.
+
+The last field, ``event_passing``, indicates how to translate note-on
+/ off events. In ``PROCESS_EVENTS`` mode, the note 255 is regarded
+as velocity change, and key pressure event is passed to the port. In
+``PASS_EVENTS`` mode, all note on/off events are passed to the port
+without modified. ``PROCESS_KEYPRESS`` mode checks the note above 128
+and regards it as key pressure event (mainly for Emu8000 driver).
+
+Open Callback
+-------------
+
+The ``open`` is called at each time this device is opened by an application
+using OSS sequencer. This must not be NULL. Typically, the open callback
+does the following procedure:
+
+#. Allocate private data record.
+#. Create an ALSA sequencer port.
+#. Set the new port address on ``arg->addr``.
+#. Set the private data record pointer on ``arg->private_data``.
+
+Note that the type bit-flags in port_info of this synth port must NOT contain
+``TYPE_MIDI_GENERIC``
+bit. Instead, ``TYPE_SPECIFIC`` should be used. Also, ``CAP_SUBSCRIPTION``
+bit should NOT be included, too. This is necessary to tell it from other
+normal MIDI devices. If the open procedure succeeded, return zero. Otherwise,
+return -errno.
+
+Ioctl Callback
+--------------
+
+The ``ioctl`` callback is called when the sequencer receives device-specific
+ioctls. The following two ioctls should be processed by this callback:
+
+IOCTL_SEQ_RESET_SAMPLES
+    reset all samples on memory -- return 0
+
+IOCTL_SYNTH_MEMAVL
+    return the available memory size
+
+FM_4OP_ENABLE
+    can be ignored usually
+
+The other ioctls are processed inside the sequencer without passing to
+the lowlevel driver.
+
+Load_Patch Callback
+-------------------
+
+The ``load_patch`` callback is used for sample-downloading. This callback
+must read the data on user-space and transfer to each device. Return 0
+if succeeded, and -errno if failed. The format argument is the patch key
+in patch_info record. The buf is user-space pointer where patch_info record
+is stored. The offs can be ignored. The count is total data size of this
+sample data.
+
+Close Callback
+--------------
+
+The ``close`` callback is called when this device is closed by the
+application. If any private data was allocated in open callback, it must
+be released in the close callback. The deletion of ALSA port should be
+done here, too. This callback must not be NULL.
+
+Reset Callback
+--------------
+
+The ``reset`` callback is called when sequencer device is reset or
+closed by applications. The callback should turn off the sounds on the
+relevant port immediately, and initialize the status of the port. If this
+callback is undefined, OSS seq sends a ``HEARTBEAT`` event to the
+port.
+
+Events
+======
+
+Most of the events are processed by sequencer and translated to the adequate
+ALSA sequencer events, so that each synth device can receive by input_event
+callback of ALSA sequencer port. The following ALSA events should be
+implemented by the driver:
+
+=============	===================
+ALSA event	Original OSS events
+=============	===================
+NOTEON		SEQ_NOTEON, MIDI_NOTEON
+NOTE		SEQ_NOTEOFF, MIDI_NOTEOFF
+KEYPRESS	MIDI_KEY_PRESSURE
+CHANPRESS	SEQ_AFTERTOUCH, MIDI_CHN_PRESSURE
+PGMCHANGE	SEQ_PGMCHANGE, MIDI_PGM_CHANGE
+PITCHBEND	SEQ_CONTROLLER(CTRL_PITCH_BENDER),
+		MIDI_PITCH_BEND
+CONTROLLER	MIDI_CTL_CHANGE,
+		SEQ_BALANCE (with CTL_PAN)
+CONTROL14	SEQ_CONTROLLER
+REGPARAM	SEQ_CONTROLLER(CTRL_PITCH_BENDER_RANGE)
+SYSEX		SEQ_SYSEX
+=============	===================
+
+The most of these behavior can be realized by MIDI emulation driver
+included in the Emu8000 lowlevel driver. In the future release, this module
+will be independent.
+
+Some OSS events (``SEQ_PRIVATE`` and ``SEQ_VOLUME`` events) are passed as event
+type SND_SEQ_OSS_PRIVATE.  The OSS sequencer passes these event 8 byte
+packets without any modification. The lowlevel driver should process these
+events appropriately.
+
+Interface to MIDI Device
+========================
+
+Since the OSS emulation probes the creation and deletion of ALSA MIDI
+sequencer ports automatically by receiving announcement from ALSA
+sequencer, the MIDI devices don't need to be registered explicitly
+like synth devices.
+However, the MIDI port_info registered to ALSA sequencer must include
+a group name ``SND_SEQ_GROUP_DEVICE`` and a capability-bit
+``CAP_READ`` or ``CAP_WRITE``. Also, subscription capabilities,
+``CAP_SUBS_READ`` or ``CAP_SUBS_WRITE``, must be defined, too. If
+these conditions are not satisfied, the port is not registered as OSS
+sequencer MIDI device.
+
+The events via MIDI devices are parsed in OSS sequencer and converted
+to the corresponding ALSA sequencer events. The input from MIDI sequencer
+is also converted to MIDI byte events by OSS sequencer. This works just
+a reverse way of seq_midi module.
+
+Known Problems / TODO's
+=======================
+
+* Patch loading via ALSA instrument layer is not implemented yet.
+
-- 
cgit v1.2.3


From 5a481fe309e79df2e713d7ea32175f121b251069 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Wed, 9 Nov 2016 17:55:28 +0100
Subject: ALSA: doc: ReSTize ControlNames.txt

A simple conversion from a plain text file.
Put to designs subdirectory.

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/ControlNames.txt     | 107 -------------------
 Documentation/sound/designs/control-names.rst | 142 ++++++++++++++++++++++++++
 Documentation/sound/designs/index.rst         |   1 +
 3 files changed, 143 insertions(+), 107 deletions(-)
 delete mode 100644 Documentation/sound/alsa/ControlNames.txt
 create mode 100644 Documentation/sound/designs/control-names.rst

diff --git a/Documentation/sound/alsa/ControlNames.txt b/Documentation/sound/alsa/ControlNames.txt
deleted file mode 100644
index 3fc1cf50d28e..000000000000
--- a/Documentation/sound/alsa/ControlNames.txt
+++ /dev/null
@@ -1,107 +0,0 @@
-This document describes standard names of mixer controls.
-
-Syntax: [LOCATION] SOURCE [CHANNEL] [DIRECTION] FUNCTION
-
-DIRECTION:
-  	(both directions)
-  Playback
-  Capture
-  Bypass Playback
-  Bypass Capture
-
-FUNCTION:
-  Switch	(on/off switch)
-  Volume
-  Route		(route control, hardware specific)
-
-CHANNEL:
-       (channel independent, or applies to all channels)
-  Front
-  Surround      (rear left/right in 4.0/5.1 surround)
-  CLFE
-  Center
-  LFE
-  Side          (side left/right for 7.1 surround)
-
-LOCATION:       (physical location of source)
-  Front
-  Rear
-  Dock          (docking station)
-  Internal
-
-SOURCE:
-  Master
-  Master Mono
-  Hardware Master
-  Speaker	(internal speaker)
-  Bass Speaker	(internal LFE speaker)
-  Headphone
-  Line Out
-  Beep		(beep generator)
-  Phone
-  Phone Input
-  Phone Output
-  Synth
-  FM
-  Mic
-  Headset Mic	(mic part of combined headset jack - 4-pin headphone + mic)
-  Headphone Mic	(mic part of either/or - 3-pin headphone or mic)
-  Line		(input only, use "Line Out" for output)
-  CD
-  Video
-  Zoom Video
-  Aux
-  PCM
-  PCM Pan
-  Loopback
-  Analog Loopback	(D/A -> A/D loopback)
-  Digital Loopback	(playback -> capture loopback - without analog path)
-  Mono
-  Mono Output
-  Multi
-  ADC
-  Wave
-  Music
-  I2S
-  IEC958
-  HDMI
-  SPDIF		(output only)
-  SPDIF In
-  Digital In
-  HDMI/DP	(either HDMI or DisplayPort)
-
-Exceptions (deprecated):
-  [Analogue|Digital] Capture Source
-  [Analogue|Digital] Capture Switch	(aka input gain switch)
-  [Analogue|Digital] Capture Volume	(aka input gain volume)
-  [Analogue|Digital] Playback Switch	(aka output gain switch)
-  [Analogue|Digital] Playback Volume	(aka output gain volume)
-  Tone Control - Switch
-  Tone Control - Bass
-  Tone Control - Treble
-  3D Control - Switch
-  3D Control - Center
-  3D Control - Depth
-  3D Control - Wide
-  3D Control - Space
-  3D Control - Level
-  Mic Boost [(?dB)]
-
-PCM interface:
-
-  Sample Clock Source	{ "Word", "Internal", "AutoSync" }
-  Clock Sync Status	{ "Lock", "Sync", "No Lock" }
-  External Rate		/* external capture rate */
-  Capture Rate		/* capture rate taken from external source */
-
-IEC958 (S/PDIF) interface:
-
-  IEC958 [...] [Playback|Capture] Switch	/* turn on/off the IEC958 interface */
-  IEC958 [...] [Playback|Capture] Volume	/* digital volume control */
-  IEC958 [...] [Playback|Capture] Default	/* default or global value - read/write */
-  IEC958 [...] [Playback|Capture] Mask		/* consumer and professional mask */
-  IEC958 [...] [Playback|Capture] Con Mask	/* consumer mask */
-  IEC958 [...] [Playback|Capture] Pro Mask	/* professional mask */
-  IEC958 [...] [Playback|Capture] PCM Stream	/* the settings assigned to a PCM stream */
-  IEC958 Q-subcode [Playback|Capture] Default	/* Q-subcode bits */
-  IEC958 Preamble [Playback|Capture] Default	/* burst preamble words (4*16bits) */
diff --git a/Documentation/sound/designs/control-names.rst b/Documentation/sound/designs/control-names.rst
new file mode 100644
index 000000000000..7fedd0f33cd9
--- /dev/null
+++ b/Documentation/sound/designs/control-names.rst
@@ -0,0 +1,142 @@
+===========================
+Standard ALSA Control Names
+===========================
+
+This document describes standard names of mixer controls.
+
+Standard Syntax
+---------------
+Syntax: [LOCATION] SOURCE [CHANNEL] [DIRECTION] FUNCTION
+
+
+DIRECTION
+~~~~~~~~~
+================	===============
+		both directions
+Playback		one direction
+Capture			one direction
+Bypass Playback		one direction
+Bypass Capture		one direction
+================	===============
+
+FUNCTION
+~~~~~~~~
+========	=================================
+Switch		on/off switch
+Volume		amplifier
+Route		route control, hardware specific
+========	=================================
+
+CHANNEL
+~~~~~~~
+============	==================================================
+	channel independent, or applies to all channels
+Front		front left/right channels
+Surround	rear left/right in 4.0/5.1 surround
+CLFE		C/LFE channels
+Center		center cannel
+LFE		LFE channel
+Side		side left/right for 7.1 surround
+============	==================================================
+
+LOCATION (Physical location of source)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+============	=====================
+Front		front position
+Rear		rear position
+Dock		on docking station
+Internal	internal
+============	=====================
+
+SOURCE
+~~~~~~
+===================	=================================================
+Master
+Master Mono
+Hardware Master
+Speaker			internal speaker
+Bass Speaker		internal LFE speaker
+Headphone
+Line Out
+Beep			beep generator
+Phone
+Phone Input
+Phone Output
+Synth
+FM
+Mic
+Headset Mic		mic part of combined headset jack - 4-pin
+			headphone + mic
+Headphone Mic		mic part of either/or - 3-pin headphone or mic
+Line			input only, use "Line Out" for output
+CD
+Video
+Zoom Video
+Aux
+PCM
+PCM Pan
+Loopback
+Analog Loopback		D/A -> A/D loopback
+Digital Loopback	playback -> capture loopback -
+			without analog path
+Mono
+Mono Output
+Multi
+ADC
+Wave
+Music
+I2S
+IEC958
+HDMI
+SPDIF			output only
+SPDIF In
+Digital In
+HDMI/DP			either HDMI or DisplayPort
+===================	=================================================
+
+Exceptions (deprecated)
+-----------------------
+
+=====================================	=======================
+[Analogue|Digital] Capture Source
+[Analogue|Digital] Capture Switch	aka input gain switch
+[Analogue|Digital] Capture Volume	aka input gain volume
+[Analogue|Digital] Playback Switch	aka output gain switch
+[Analogue|Digital] Playback Volume	aka output gain volume
+Tone Control - Switch
+Tone Control - Bass
+Tone Control - Treble
+3D Control - Switch
+3D Control - Center
+3D Control - Depth
+3D Control - Wide
+3D Control - Space
+3D Control - Level
+Mic Boost [(?dB)]
+=====================================	=======================
+
+PCM interface
+-------------
+
+===================	========================================
+Sample Clock Source	{ "Word", "Internal", "AutoSync" }
+Clock Sync Status	{ "Lock", "Sync", "No Lock" }
+External Rate		external capture rate
+Capture Rate		capture rate taken from external source
+===================	========================================
+
+IEC958 (S/PDIF) interface
+-------------------------
+
+============================================	======================================
+IEC958 [...] [Playback|Capture] Switch		turn on/off the IEC958 interface
+IEC958 [...] [Playback|Capture] Volume		digital volume control
+IEC958 [...] [Playback|Capture] Default		default or global value - read/write
+IEC958 [...] [Playback|Capture] Mask		consumer and professional mask
+IEC958 [...] [Playback|Capture] Con Mask	consumer mask
+IEC958 [...] [Playback|Capture] Pro Mask	professional mask
+IEC958 [...] [Playback|Capture] PCM Stream	the settings assigned to a PCM stream
+IEC958 Q-subcode [Playback|Capture] Default	Q-subcode bits
+
+IEC958 Preamble [Playback|Capture] Default	burst preamble words (4*16bits)
+============================================	======================================
diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst
index 0ca3a6b0a5ce..e53a5fac0acf 100644
--- a/Documentation/sound/designs/index.rst
+++ b/Documentation/sound/designs/index.rst
@@ -4,6 +4,7 @@ Designs and Implementations
 .. toctree::
    :maxdepth: 2
 
+   control-names
    channel-mapping-api
    procfile
    powersave
-- 
cgit v1.2.3


From e9df12c3bac69e2cdfd76d7717bed92dee7cd617 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 10:58:05 +0100
Subject: ALSA: doc: ReSTize compress-offload document

A simple conversion from a plain text file.
Put to designs subdirectory.

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/compress_offload.txt    | 234 ----------------------
 Documentation/sound/designs/compress-offload.rst | 245 +++++++++++++++++++++++
 Documentation/sound/designs/index.rst            |   1 +
 3 files changed, 246 insertions(+), 234 deletions(-)
 delete mode 100644 Documentation/sound/alsa/compress_offload.txt
 create mode 100644 Documentation/sound/designs/compress-offload.rst

diff --git a/Documentation/sound/alsa/compress_offload.txt b/Documentation/sound/alsa/compress_offload.txt
deleted file mode 100644
index 8ba556a131c3..000000000000
--- a/Documentation/sound/alsa/compress_offload.txt
+++ /dev/null
@@ -1,234 +0,0 @@
-		compress_offload.txt
-		=====================
-	Pierre-Louis.Bossart 
-		Vinod Koul 
-
-Overview
-
-Since its early days, the ALSA API was defined with PCM support or
-constant bitrates payloads such as IEC61937 in mind. Arguments and
-returned values in frames are the norm, making it a challenge to
-extend the existing API to compressed data streams.
-
-In recent years, audio digital signal processors (DSP) were integrated
-in system-on-chip designs, and DSPs are also integrated in audio
-codecs. Processing compressed data on such DSPs results in a dramatic
-reduction of power consumption compared to host-based
-processing. Support for such hardware has not been very good in Linux,
-mostly because of a lack of a generic API available in the mainline
-kernel.
-
-Rather than requiring a compatibility break with an API change of the
-ALSA PCM interface, a new 'Compressed Data' API is introduced to
-provide a control and data-streaming interface for audio DSPs.
-
-The design of this API was inspired by the 2-year experience with the
-Intel Moorestown SOC, with many corrections required to upstream the
-API in the mainline kernel instead of the staging tree and make it
-usable by others.
-
-Requirements
-
-The main requirements are:
-
-- separation between byte counts and time. Compressed formats may have
-  a header per file, per frame, or no header at all. The payload size
-  may vary from frame-to-frame. As a result, it is not possible to
-  estimate reliably the duration of audio buffers when handling
-  compressed data. Dedicated mechanisms are required to allow for
-  reliable audio-video synchronization, which requires precise
-  reporting of the number of samples rendered at any given time.
-
-- Handling of multiple formats. PCM data only requires a specification
-  of the sampling rate, number of channels and bits per sample. In
-  contrast, compressed data comes in a variety of formats. Audio DSPs
-  may also provide support for a limited number of audio encoders and
-  decoders embedded in firmware, or may support more choices through
-  dynamic download of libraries.
-
-- Focus on main formats. This API provides support for the most
-  popular formats used for audio and video capture and playback. It is
-  likely that as audio compression technology advances, new formats
-  will be added.
-
-- Handling of multiple configurations. Even for a given format like
-  AAC, some implementations may support AAC multichannel but HE-AAC
-  stereo. Likewise WMA10 level M3 may require too much memory and cpu
-  cycles. The new API needs to provide a generic way of listing these
-  formats.
-
-- Rendering/Grabbing only. This API does not provide any means of
-  hardware acceleration, where PCM samples are provided back to
-  user-space for additional processing. This API focuses instead on
-  streaming compressed data to a DSP, with the assumption that the
-  decoded samples are routed to a physical output or logical back-end.
-
- - Complexity hiding. Existing user-space multimedia frameworks all
-  have existing enums/structures for each compressed format. This new
-  API assumes the existence of a platform-specific compatibility layer
-  to expose, translate and make use of the capabilities of the audio
-  DSP, eg. Android HAL or PulseAudio sinks. By construction, regular
-  applications are not supposed to make use of this API.
-
-
-Design
-
-The new API shares a number of concepts with the PCM API for flow
-control. Start, pause, resume, drain and stop commands have the same
-semantics no matter what the content is.
-
-The concept of memory ring buffer divided in a set of fragments is
-borrowed from the ALSA PCM API. However, only sizes in bytes can be
-specified.
-
-Seeks/trick modes are assumed to be handled by the host.
-
-The notion of rewinds/forwards is not supported. Data committed to the
-ring buffer cannot be invalidated, except when dropping all buffers.
-
-The Compressed Data API does not make any assumptions on how the data
-is transmitted to the audio DSP. DMA transfers from main memory to an
-embedded audio cluster or to a SPI interface for external DSPs are
-possible. As in the ALSA PCM case, a core set of routines is exposed;
-each driver implementer will have to write support for a set of
-mandatory routines and possibly make use of optional ones.
-
-The main additions are
-
-- get_caps
-This routine returns the list of audio formats supported. Querying the
-codecs on a capture stream will return encoders, decoders will be
-listed for playback streams.
-
-- get_codec_caps For each codec, this routine returns a list of
-capabilities. The intent is to make sure all the capabilities
-correspond to valid settings, and to minimize the risks of
-configuration failures. For example, for a complex codec such as AAC,
-the number of channels supported may depend on a specific profile. If
-the capabilities were exposed with a single descriptor, it may happen
-that a specific combination of profiles/channels/formats may not be
-supported. Likewise, embedded DSPs have limited memory and cpu cycles,
-it is likely that some implementations make the list of capabilities
-dynamic and dependent on existing workloads. In addition to codec
-settings, this routine returns the minimum buffer size handled by the
-implementation. This information can be a function of the DMA buffer
-sizes, the number of bytes required to synchronize, etc, and can be
-used by userspace to define how much needs to be written in the ring
-buffer before playback can start.
-
-- set_params
-This routine sets the configuration chosen for a specific codec. The
-most important field in the parameters is the codec type; in most
-cases decoders will ignore other fields, while encoders will strictly
-comply to the settings
-
-- get_params
-This routines returns the actual settings used by the DSP. Changes to
-the settings should remain the exception.
-
-- get_timestamp
-The timestamp becomes a multiple field structure. It lists the number
-of bytes transferred, the number of samples processed and the number
-of samples rendered/grabbed. All these values can be used to determine
-the average bitrate, figure out if the ring buffer needs to be
-refilled or the delay due to decoding/encoding/io on the DSP.
-
-Note that the list of codecs/profiles/modes was derived from the
-OpenMAX AL specification instead of reinventing the wheel.
-Modifications include:
-- Addition of FLAC and IEC formats
-- Merge of encoder/decoder capabilities
-- Profiles/modes listed as bitmasks to make descriptors more compact
-- Addition of set_params for decoders (missing in OpenMAX AL)
-- Addition of AMR/AMR-WB encoding modes (missing in OpenMAX AL)
-- Addition of format information for WMA
-- Addition of encoding options when required (derived from OpenMAX IL)
-- Addition of rateControlSupported (missing in OpenMAX AL)
-
-Gapless Playback
-================
-When playing thru an album, the decoders have the ability to skip the encoder
-delay and padding and directly move from one track content to another. The end
-user can perceive this as gapless playback as we don't have silence while
-switching from one track to another
-
-Also, there might be low-intensity noises due to encoding. Perfect gapless is
-difficult to reach with all types of compressed data, but works fine with most
-music content. The decoder needs to know the encoder delay and encoder padding.
-So we need to pass this to DSP. This metadata is extracted from ID3/MP4 headers
-and are not present by default in the bitstream, hence the need for a new
-interface to pass this information to the DSP. Also DSP and userspace needs to
-switch from one track to another and start using data for second track.
-
-The main additions are:
-
-- set_metadata
-This routine sets the encoder delay and encoder padding. This can be used by
-decoder to strip the silence. This needs to be set before the data in the track
-is written.
-
-- set_next_track
-This routine tells DSP that metadata and write operation sent after this would
-correspond to subsequent track
-
-- partial drain
-This is called when end of file is reached. The userspace can inform DSP that
-EOF is reached and now DSP can start skipping padding delay. Also next write
-data would belong to next track
-
-Sequence flow for gapless would be:
-- Open
-- Get caps / codec caps
-- Set params
-- Set metadata of the first track
-- Fill data of the first track
-- Trigger start
-- User-space finished sending all,
-- Indicate next track data by sending set_next_track
-- Set metadata of the next track
-- then call partial_drain to flush most of buffer in DSP
-- Fill data of the next track
-- DSP switches to second track
-(note: order for partial_drain and write for next track can be reversed as well)
-
-Not supported:
-
-- Support for VoIP/circuit-switched calls is not the target of this
-  API. Support for dynamic bit-rate changes would require a tight
-  coupling between the DSP and the host stack, limiting power savings.
-
-- Packet-loss concealment is not supported. This would require an
-  additional interface to let the decoder synthesize data when frames
-  are lost during transmission. This may be added in the future.
-
-- Volume control/routing is not handled by this API. Devices exposing a
-  compressed data interface will be considered as regular ALSA devices;
-  volume changes and routing information will be provided with regular
-  ALSA kcontrols.
-
-- Embedded audio effects. Such effects should be enabled in the same
-  manner, no matter if the input was PCM or compressed.
-
-- multichannel IEC encoding. Unclear if this is required.
-
-- Encoding/decoding acceleration is not supported as mentioned
-  above. It is possible to route the output of a decoder to a capture
-  stream, or even implement transcoding capabilities. This routing
-  would be enabled with ALSA kcontrols.
-
-- Audio policy/resource management. This API does not provide any
-  hooks to query the utilization of the audio DSP, nor any preemption
-  mechanisms.
-
-- No notion of underrun/overrun. Since the bytes written are compressed
-  in nature and data written/read doesn't translate directly to
-  rendered output in time, this does not deal with underrun/overrun and
-  maybe dealt in user-library
-
-Credits:
-- Mark Brown and Liam Girdwood for discussions on the need for this API
-- Harsha Priya for her work on intel_sst compressed API
-- Rakesh Ughreja for valuable feedback
-- Sing Nallasellan, Sikkandar Madar and Prasanna Samaga for
-  demonstrating and quantifying the benefits of audio offload on a
-  real platform.
diff --git a/Documentation/sound/designs/compress-offload.rst b/Documentation/sound/designs/compress-offload.rst
new file mode 100644
index 000000000000..ad4bfbdacc83
--- /dev/null
+++ b/Documentation/sound/designs/compress-offload.rst
@@ -0,0 +1,245 @@
+=========================
+ALSA Compress-Offload API
+=========================
+
+Pierre-Louis.Bossart 
+
+Vinod Koul 
+
+
+Overview
+========
+Since its early days, the ALSA API was defined with PCM support or
+constant bitrates payloads such as IEC61937 in mind. Arguments and
+returned values in frames are the norm, making it a challenge to
+extend the existing API to compressed data streams.
+
+In recent years, audio digital signal processors (DSP) were integrated
+in system-on-chip designs, and DSPs are also integrated in audio
+codecs. Processing compressed data on such DSPs results in a dramatic
+reduction of power consumption compared to host-based
+processing. Support for such hardware has not been very good in Linux,
+mostly because of a lack of a generic API available in the mainline
+kernel.
+
+Rather than requiring a compatibility break with an API change of the
+ALSA PCM interface, a new 'Compressed Data' API is introduced to
+provide a control and data-streaming interface for audio DSPs.
+
+The design of this API was inspired by the 2-year experience with the
+Intel Moorestown SOC, with many corrections required to upstream the
+API in the mainline kernel instead of the staging tree and make it
+usable by others.
+
+
+Requirements
+============
+The main requirements are:
+
+- separation between byte counts and time. Compressed formats may have
+  a header per file, per frame, or no header at all. The payload size
+  may vary from frame-to-frame. As a result, it is not possible to
+  estimate reliably the duration of audio buffers when handling
+  compressed data. Dedicated mechanisms are required to allow for
+  reliable audio-video synchronization, which requires precise
+  reporting of the number of samples rendered at any given time.
+
+- Handling of multiple formats. PCM data only requires a specification
+  of the sampling rate, number of channels and bits per sample. In
+  contrast, compressed data comes in a variety of formats. Audio DSPs
+  may also provide support for a limited number of audio encoders and
+  decoders embedded in firmware, or may support more choices through
+  dynamic download of libraries.
+
+- Focus on main formats. This API provides support for the most
+  popular formats used for audio and video capture and playback. It is
+  likely that as audio compression technology advances, new formats
+  will be added.
+
+- Handling of multiple configurations. Even for a given format like
+  AAC, some implementations may support AAC multichannel but HE-AAC
+  stereo. Likewise WMA10 level M3 may require too much memory and cpu
+  cycles. The new API needs to provide a generic way of listing these
+  formats.
+
+- Rendering/Grabbing only. This API does not provide any means of
+  hardware acceleration, where PCM samples are provided back to
+  user-space for additional processing. This API focuses instead on
+  streaming compressed data to a DSP, with the assumption that the
+  decoded samples are routed to a physical output or logical back-end.
+
+- Complexity hiding. Existing user-space multimedia frameworks all
+  have existing enums/structures for each compressed format. This new
+  API assumes the existence of a platform-specific compatibility layer
+  to expose, translate and make use of the capabilities of the audio
+  DSP, eg. Android HAL or PulseAudio sinks. By construction, regular
+  applications are not supposed to make use of this API.
+
+
+Design
+======
+The new API shares a number of concepts with the PCM API for flow
+control. Start, pause, resume, drain and stop commands have the same
+semantics no matter what the content is.
+
+The concept of memory ring buffer divided in a set of fragments is
+borrowed from the ALSA PCM API. However, only sizes in bytes can be
+specified.
+
+Seeks/trick modes are assumed to be handled by the host.
+
+The notion of rewinds/forwards is not supported. Data committed to the
+ring buffer cannot be invalidated, except when dropping all buffers.
+
+The Compressed Data API does not make any assumptions on how the data
+is transmitted to the audio DSP. DMA transfers from main memory to an
+embedded audio cluster or to a SPI interface for external DSPs are
+possible. As in the ALSA PCM case, a core set of routines is exposed;
+each driver implementer will have to write support for a set of
+mandatory routines and possibly make use of optional ones.
+
+The main additions are
+
+get_caps
+  This routine returns the list of audio formats supported. Querying the
+  codecs on a capture stream will return encoders, decoders will be
+  listed for playback streams.
+
+get_codec_caps
+  For each codec, this routine returns a list of
+  capabilities. The intent is to make sure all the capabilities
+  correspond to valid settings, and to minimize the risks of
+  configuration failures. For example, for a complex codec such as AAC,
+  the number of channels supported may depend on a specific profile. If
+  the capabilities were exposed with a single descriptor, it may happen
+  that a specific combination of profiles/channels/formats may not be
+  supported. Likewise, embedded DSPs have limited memory and cpu cycles,
+  it is likely that some implementations make the list of capabilities
+  dynamic and dependent on existing workloads. In addition to codec
+  settings, this routine returns the minimum buffer size handled by the
+  implementation. This information can be a function of the DMA buffer
+  sizes, the number of bytes required to synchronize, etc, and can be
+  used by userspace to define how much needs to be written in the ring
+  buffer before playback can start.
+
+set_params
+  This routine sets the configuration chosen for a specific codec. The
+  most important field in the parameters is the codec type; in most
+  cases decoders will ignore other fields, while encoders will strictly
+  comply to the settings
+
+get_params
+  This routines returns the actual settings used by the DSP. Changes to
+  the settings should remain the exception.
+
+get_timestamp
+  The timestamp becomes a multiple field structure. It lists the number
+  of bytes transferred, the number of samples processed and the number
+  of samples rendered/grabbed. All these values can be used to determine
+  the average bitrate, figure out if the ring buffer needs to be
+  refilled or the delay due to decoding/encoding/io on the DSP.
+
+Note that the list of codecs/profiles/modes was derived from the
+OpenMAX AL specification instead of reinventing the wheel.
+Modifications include:
+- Addition of FLAC and IEC formats
+- Merge of encoder/decoder capabilities
+- Profiles/modes listed as bitmasks to make descriptors more compact
+- Addition of set_params for decoders (missing in OpenMAX AL)
+- Addition of AMR/AMR-WB encoding modes (missing in OpenMAX AL)
+- Addition of format information for WMA
+- Addition of encoding options when required (derived from OpenMAX IL)
+- Addition of rateControlSupported (missing in OpenMAX AL)
+
+
+Gapless Playback
+================
+When playing thru an album, the decoders have the ability to skip the encoder
+delay and padding and directly move from one track content to another. The end
+user can perceive this as gapless playback as we don't have silence while
+switching from one track to another
+
+Also, there might be low-intensity noises due to encoding. Perfect gapless is
+difficult to reach with all types of compressed data, but works fine with most
+music content. The decoder needs to know the encoder delay and encoder padding.
+So we need to pass this to DSP. This metadata is extracted from ID3/MP4 headers
+and are not present by default in the bitstream, hence the need for a new
+interface to pass this information to the DSP. Also DSP and userspace needs to
+switch from one track to another and start using data for second track.
+
+The main additions are:
+
+set_metadata
+  This routine sets the encoder delay and encoder padding. This can be used by
+  decoder to strip the silence. This needs to be set before the data in the track
+  is written.
+
+set_next_track
+  This routine tells DSP that metadata and write operation sent after this would
+  correspond to subsequent track
+
+partial drain
+  This is called when end of file is reached. The userspace can inform DSP that
+  EOF is reached and now DSP can start skipping padding delay. Also next write
+  data would belong to next track
+
+Sequence flow for gapless would be:
+- Open
+- Get caps / codec caps
+- Set params
+- Set metadata of the first track
+- Fill data of the first track
+- Trigger start
+- User-space finished sending all,
+- Indicate next track data by sending set_next_track
+- Set metadata of the next track
+- then call partial_drain to flush most of buffer in DSP
+- Fill data of the next track
+- DSP switches to second track
+
+(note: order for partial_drain and write for next track can be reversed as well)
+
+
+Not supported
+=============
+- Support for VoIP/circuit-switched calls is not the target of this
+  API. Support for dynamic bit-rate changes would require a tight
+  coupling between the DSP and the host stack, limiting power savings.
+
+- Packet-loss concealment is not supported. This would require an
+  additional interface to let the decoder synthesize data when frames
+  are lost during transmission. This may be added in the future.
+
+- Volume control/routing is not handled by this API. Devices exposing a
+  compressed data interface will be considered as regular ALSA devices;
+  volume changes and routing information will be provided with regular
+  ALSA kcontrols.
+
+- Embedded audio effects. Such effects should be enabled in the same
+  manner, no matter if the input was PCM or compressed.
+
+- multichannel IEC encoding. Unclear if this is required.
+
+- Encoding/decoding acceleration is not supported as mentioned
+  above. It is possible to route the output of a decoder to a capture
+  stream, or even implement transcoding capabilities. This routing
+  would be enabled with ALSA kcontrols.
+
+- Audio policy/resource management. This API does not provide any
+  hooks to query the utilization of the audio DSP, nor any preemption
+  mechanisms.
+
+- No notion of underrun/overrun. Since the bytes written are compressed
+  in nature and data written/read doesn't translate directly to
+  rendered output in time, this does not deal with underrun/overrun and
+  maybe dealt in user-library
+
+
+Credits
+=======
+- Mark Brown and Liam Girdwood for discussions on the need for this API
+- Harsha Priya for her work on intel_sst compressed API
+- Rakesh Ughreja for valuable feedback
+- Sing Nallasellan, Sikkandar Madar and Prasanna Samaga for
+  demonstrating and quantifying the benefits of audio offload on a
+  real platform.
diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst
index e53a5fac0acf..f7ca11307033 100644
--- a/Documentation/sound/designs/index.rst
+++ b/Documentation/sound/designs/index.rst
@@ -6,6 +6,7 @@ Designs and Implementations
 
    control-names
    channel-mapping-api
+   compress-offload
    procfile
    powersave
    oss-emulation
-- 
cgit v1.2.3


From 20a1d0f44d9447a68c387a2f561db4720302fb7c Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 11:06:55 +0100
Subject: ALSA: doc: ReSTize timestamping document

A simple conversion from a plain text file.
Put to designs subdirectory.

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/timestamping.txt    | 200 -------------------------
 Documentation/sound/designs/index.rst        |   1 +
 Documentation/sound/designs/timestamping.rst | 215 +++++++++++++++++++++++++++
 3 files changed, 216 insertions(+), 200 deletions(-)
 delete mode 100644 Documentation/sound/alsa/timestamping.txt
 create mode 100644 Documentation/sound/designs/timestamping.rst

diff --git a/Documentation/sound/alsa/timestamping.txt b/Documentation/sound/alsa/timestamping.txt
deleted file mode 100644
index 9d579aefbffd..000000000000
--- a/Documentation/sound/alsa/timestamping.txt
+++ /dev/null
@@ -1,200 +0,0 @@
-The ALSA API can provide two different system timestamps:
-
-- Trigger_tstamp is the system time snapshot taken when the .trigger
-callback is invoked. This snapshot is taken by the ALSA core in the
-general case, but specific hardware may have synchronization
-capabilities or conversely may only be able to provide a correct
-estimate with a delay. In the latter two cases, the low-level driver
-is responsible for updating the trigger_tstamp at the most appropriate
-and precise moment. Applications should not rely solely on the first
-trigger_tstamp but update their internal calculations if the driver
-provides a refined estimate with a delay.
-
-- tstamp is the current system timestamp updated during the last
-event or application query.
-The difference (tstamp - trigger_tstamp) defines the elapsed time.
-
-The ALSA API provides two basic pieces of information, avail
-and delay, which combined with the trigger and current system
-timestamps allow for applications to keep track of the 'fullness' of
-the ring buffer and the amount of queued samples.
-
-The use of these different pointers and time information depends on
-the application needs:
-
-- 'avail' reports how much can be written in the ring buffer
-- 'delay' reports the time it will take to hear a new sample after all
-queued samples have been played out.
-
-When timestamps are enabled, the avail/delay information is reported
-along with a snapshot of system time. Applications can select from
-CLOCK_REALTIME (NTP corrections including going backwards),
-CLOCK_MONOTONIC (NTP corrections but never going backwards),
-CLOCK_MONOTIC_RAW (without NTP corrections) and change the mode
-dynamically with sw_params
-
-
-The ALSA API also provide an audio_tstamp which reflects the passage
-of time as measured by different components of audio hardware.  In
-ascii-art, this could be represented as follows (for the playback
-case):
-
-
---------------------------------------------------------------> time
-  ^               ^              ^                ^           ^
-  |               |              |                |           |
- analog         link            dma              app       FullBuffer
- time           time           time              time        time
-  |               |              |                |           |
-  |< codec delay >|<--hw delay-->||<---avail->|
-  |<----------------- delay---------------------->|           |
-			         |<----ring buffer length---->|
-
-The analog time is taken at the last stage of the playback, as close
-as possible to the actual transducer
-
-The link time is taken at the output of the SoC/chipset as the samples
-are pushed on a link. The link time can be directly measured if
-supported in hardware by sample counters or wallclocks (e.g. with
-HDAudio 24MHz or PTP clock for networked solutions) or indirectly
-estimated (e.g. with the frame counter in USB).
-
-The DMA time is measured using counters - typically the least reliable
-of all measurements due to the bursty nature of DMA transfers.
-
-The app time corresponds to the time tracked by an application after
-writing in the ring buffer.
-
-The application can query the hardware capabilities, define which
-audio time it wants reported by selecting the relevant settings in
-audio_tstamp_config fields, thus get an estimate of the timestamp
-accuracy. It can also request the delay-to-analog be included in the
-measurement. Direct access to the link time is very interesting on
-platforms that provide an embedded DSP; measuring directly the link
-time with dedicated hardware, possibly synchronized with system time,
-removes the need to keep track of internal DSP processing times and
-latency.
-
-In case the application requests an audio tstamp that is not supported
-in hardware/low-level driver, the type is overridden as DEFAULT and the
-timestamp will report the DMA time based on the hw_pointer value.
-
-For backwards compatibility with previous implementations that did not
-provide timestamp selection, with a zero-valued COMPAT timestamp type
-the results will default to the HDAudio wall clock for playback
-streams and to the DMA time (hw_ptr) in all other cases.
-
-The audio timestamp accuracy can be returned to user-space, so that
-appropriate decisions are made:
-
-- for dma time (default), the granularity of the transfers can be
-  inferred from the steps between updates and in turn provide
-  information on how much the application pointer can be rewound
-  safely.
-
-- the link time can be used to track long-term drifts between audio
-  and system time using the (tstamp-trigger_tstamp)/audio_tstamp
-  ratio, the precision helps define how much smoothing/low-pass
-  filtering is required. The link time can be either reset on startup
-  or reported as is (the latter being useful to compare progress of
-  different streams - but may require the wallclock to be always
-  running and not wrap-around during idle periods). If supported in
-  hardware, the absolute link time could also be used to define a
-  precise start time (patches WIP)
-
-- including the delay in the audio timestamp may
-  counter-intuitively not increase the precision of timestamps, e.g. if a
-  codec includes variable-latency DSP processing or a chain of
-  hardware components the delay is typically not known with precision.
-
-The accuracy is reported in nanosecond units (using an unsigned 32-bit
-word), which gives a max precision of 4.29s, more than enough for
-audio applications...
-
-Due to the varied nature of timestamping needs, even for a single
-application, the audio_tstamp_config can be changed dynamically. In
-the STATUS ioctl, the parameters are read-only and do not allow for
-any application selection. To work around this limitation without
-impacting legacy applications, a new STATUS_EXT ioctl is introduced
-with read/write parameters. ALSA-lib will be modified to make use of
-STATUS_EXT and effectively deprecate STATUS.
-
-The ALSA API only allows for a single audio timestamp to be reported
-at a time. This is a conscious design decision, reading the audio
-timestamps from hardware registers or from IPC takes time, the more
-timestamps are read the more imprecise the combined measurements
-are. To avoid any interpretation issues, a single (system, audio)
-timestamp is reported. Applications that need different timestamps
-will be required to issue multiple queries and perform an
-interpolation of the results
-
-In some hardware-specific configuration, the system timestamp is
-latched by a low-level audio subsystem, and the information provided
-back to the driver. Due to potential delays in the communication with
-the hardware, there is a risk of misalignment with the avail and delay
-information. To make sure applications are not confused, a
-driver_timestamp field is added in the snd_pcm_status structure; this
-timestamp shows when the information is put together by the driver
-before returning from the STATUS and STATUS_EXT ioctl. in most cases
-this driver_timestamp will be identical to the regular system tstamp.
-
-Examples of typestamping with HDaudio:
-
-1. DMA timestamp, no compensation for DMA+analog delay
-$ ./audio_time  -p --ts_type=1
-playback: systime: 341121338 nsec, audio time 342000000 nsec, 	systime delta -878662
-playback: systime: 426236663 nsec, audio time 427187500 nsec, 	systime delta -950837
-playback: systime: 597080580 nsec, audio time 598000000 nsec, 	systime delta -919420
-playback: systime: 682059782 nsec, audio time 683020833 nsec, 	systime delta -961051
-playback: systime: 852896415 nsec, audio time 853854166 nsec, 	systime delta -957751
-playback: systime: 937903344 nsec, audio time 938854166 nsec, 	systime delta -950822
-
-2. DMA timestamp, compensation for DMA+analog delay
-$ ./audio_time  -p --ts_type=1 -d
-playback: systime: 341053347 nsec, audio time 341062500 nsec, 	systime delta -9153
-playback: systime: 426072447 nsec, audio time 426062500 nsec, 	systime delta 9947
-playback: systime: 596899518 nsec, audio time 596895833 nsec, 	systime delta 3685
-playback: systime: 681915317 nsec, audio time 681916666 nsec, 	systime delta -1349
-playback: systime: 852741306 nsec, audio time 852750000 nsec, 	systime delta -8694
-
-3. link timestamp, compensation for DMA+analog delay
-$ ./audio_time  -p --ts_type=2 -d
-playback: systime: 341060004 nsec, audio time 341062791 nsec, 	systime delta -2787
-playback: systime: 426242074 nsec, audio time 426244875 nsec, 	systime delta -2801
-playback: systime: 597080992 nsec, audio time 597084583 nsec, 	systime delta -3591
-playback: systime: 682084512 nsec, audio time 682088291 nsec, 	systime delta -3779
-playback: systime: 852936229 nsec, audio time 852940916 nsec, 	systime delta -4687
-playback: systime: 938107562 nsec, audio time 938112708 nsec, 	systime delta -5146
-
-Example 1 shows that the timestamp at the DMA level is close to 1ms
-ahead of the actual playback time (as a side time this sort of
-measurement can help define rewind safeguards). Compensating for the
-DMA-link delay in example 2 helps remove the hardware buffering but
-the information is still very jittery, with up to one sample of
-error. In example 3 where the timestamps are measured with the link
-wallclock, the timestamps show a monotonic behavior and a lower
-dispersion.
-
-Example 3 and 4 are with USB audio class. Example 3 shows a high
-offset between audio time and system time due to buffering. Example 4
-shows how compensating for the delay exposes a 1ms accuracy (due to
-the use of the frame counter by the driver)
-
-Example 3: DMA timestamp, no compensation for delay, delta of ~5ms
-$ ./audio_time -p -Dhw:1 -t1
-playback: systime: 120174019 nsec, audio time 125000000 nsec, 	systime delta -4825981
-playback: systime: 245041136 nsec, audio time 250000000 nsec, 	systime delta -4958864
-playback: systime: 370106088 nsec, audio time 375000000 nsec, 	systime delta -4893912
-playback: systime: 495040065 nsec, audio time 500000000 nsec, 	systime delta -4959935
-playback: systime: 620038179 nsec, audio time 625000000 nsec, 	systime delta -4961821
-playback: systime: 745087741 nsec, audio time 750000000 nsec, 	systime delta -4912259
-playback: systime: 870037336 nsec, audio time 875000000 nsec, 	systime delta -4962664
-
-Example 4: DMA timestamp, compensation for delay, delay of ~1ms
-$ ./audio_time -p -Dhw:1 -t1 -d
-playback: systime: 120190520 nsec, audio time 120000000 nsec, 	systime delta 190520
-playback: systime: 245036740 nsec, audio time 244000000 nsec, 	systime delta 1036740
-playback: systime: 370034081 nsec, audio time 369000000 nsec, 	systime delta 1034081
-playback: systime: 495159907 nsec, audio time 494000000 nsec, 	systime delta 1159907
-playback: systime: 620098824 nsec, audio time 619000000 nsec, 	systime delta 1098824
-playback: systime: 745031847 nsec, audio time 744000000 nsec, 	systime delta 1031847
diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst
index f7ca11307033..798b1a44bbbd 100644
--- a/Documentation/sound/designs/index.rst
+++ b/Documentation/sound/designs/index.rst
@@ -7,6 +7,7 @@ Designs and Implementations
    control-names
    channel-mapping-api
    compress-offload
+   timestamping
    procfile
    powersave
    oss-emulation
diff --git a/Documentation/sound/designs/timestamping.rst b/Documentation/sound/designs/timestamping.rst
new file mode 100644
index 000000000000..2b0fff503415
--- /dev/null
+++ b/Documentation/sound/designs/timestamping.rst
@@ -0,0 +1,215 @@
+=====================
+ALSA PCM Timestamping
+=====================
+
+The ALSA API can provide two different system timestamps:
+
+- Trigger_tstamp is the system time snapshot taken when the .trigger
+  callback is invoked. This snapshot is taken by the ALSA core in the
+  general case, but specific hardware may have synchronization
+  capabilities or conversely may only be able to provide a correct
+  estimate with a delay. In the latter two cases, the low-level driver
+  is responsible for updating the trigger_tstamp at the most appropriate
+  and precise moment. Applications should not rely solely on the first
+  trigger_tstamp but update their internal calculations if the driver
+  provides a refined estimate with a delay.
+
+- tstamp is the current system timestamp updated during the last
+  event or application query.
+  The difference (tstamp - trigger_tstamp) defines the elapsed time.
+
+The ALSA API provides two basic pieces of information, avail
+and delay, which combined with the trigger and current system
+timestamps allow for applications to keep track of the 'fullness' of
+the ring buffer and the amount of queued samples.
+
+The use of these different pointers and time information depends on
+the application needs:
+
+- ``avail`` reports how much can be written in the ring buffer
+- ``delay`` reports the time it will take to hear a new sample after all
+  queued samples have been played out.
+
+When timestamps are enabled, the avail/delay information is reported
+along with a snapshot of system time. Applications can select from
+``CLOCK_REALTIME`` (NTP corrections including going backwards),
+``CLOCK_MONOTONIC`` (NTP corrections but never going backwards),
+``CLOCK_MONOTIC_RAW`` (without NTP corrections) and change the mode
+dynamically with sw_params
+
+
+The ALSA API also provide an audio_tstamp which reflects the passage
+of time as measured by different components of audio hardware.  In
+ascii-art, this could be represented as follows (for the playback
+case):
+::
+
+  --------------------------------------------------------------> time
+    ^               ^              ^                ^           ^
+    |               |              |                |           |
+   analog         link            dma              app       FullBuffer
+   time           time           time              time        time
+    |               |              |                |           |
+    |< codec delay >|<--hw delay-->||<---avail->|
+    |<----------------- delay---------------------->|           |
+                                   |<----ring buffer length---->|
+
+
+The analog time is taken at the last stage of the playback, as close
+as possible to the actual transducer
+
+The link time is taken at the output of the SoC/chipset as the samples
+are pushed on a link. The link time can be directly measured if
+supported in hardware by sample counters or wallclocks (e.g. with
+HDAudio 24MHz or PTP clock for networked solutions) or indirectly
+estimated (e.g. with the frame counter in USB).
+
+The DMA time is measured using counters - typically the least reliable
+of all measurements due to the bursty nature of DMA transfers.
+
+The app time corresponds to the time tracked by an application after
+writing in the ring buffer.
+
+The application can query the hardware capabilities, define which
+audio time it wants reported by selecting the relevant settings in
+audio_tstamp_config fields, thus get an estimate of the timestamp
+accuracy. It can also request the delay-to-analog be included in the
+measurement. Direct access to the link time is very interesting on
+platforms that provide an embedded DSP; measuring directly the link
+time with dedicated hardware, possibly synchronized with system time,
+removes the need to keep track of internal DSP processing times and
+latency.
+
+In case the application requests an audio tstamp that is not supported
+in hardware/low-level driver, the type is overridden as DEFAULT and the
+timestamp will report the DMA time based on the hw_pointer value.
+
+For backwards compatibility with previous implementations that did not
+provide timestamp selection, with a zero-valued COMPAT timestamp type
+the results will default to the HDAudio wall clock for playback
+streams and to the DMA time (hw_ptr) in all other cases.
+
+The audio timestamp accuracy can be returned to user-space, so that
+appropriate decisions are made:
+
+- for dma time (default), the granularity of the transfers can be
+  inferred from the steps between updates and in turn provide
+  information on how much the application pointer can be rewound
+  safely.
+
+- the link time can be used to track long-term drifts between audio
+  and system time using the (tstamp-trigger_tstamp)/audio_tstamp
+  ratio, the precision helps define how much smoothing/low-pass
+  filtering is required. The link time can be either reset on startup
+  or reported as is (the latter being useful to compare progress of
+  different streams - but may require the wallclock to be always
+  running and not wrap-around during idle periods). If supported in
+  hardware, the absolute link time could also be used to define a
+  precise start time (patches WIP)
+
+- including the delay in the audio timestamp may
+  counter-intuitively not increase the precision of timestamps, e.g. if a
+  codec includes variable-latency DSP processing or a chain of
+  hardware components the delay is typically not known with precision.
+
+The accuracy is reported in nanosecond units (using an unsigned 32-bit
+word), which gives a max precision of 4.29s, more than enough for
+audio applications...
+
+Due to the varied nature of timestamping needs, even for a single
+application, the audio_tstamp_config can be changed dynamically. In
+the ``STATUS`` ioctl, the parameters are read-only and do not allow for
+any application selection. To work around this limitation without
+impacting legacy applications, a new ``STATUS_EXT`` ioctl is introduced
+with read/write parameters. ALSA-lib will be modified to make use of
+``STATUS_EXT`` and effectively deprecate ``STATUS``.
+
+The ALSA API only allows for a single audio timestamp to be reported
+at a time. This is a conscious design decision, reading the audio
+timestamps from hardware registers or from IPC takes time, the more
+timestamps are read the more imprecise the combined measurements
+are. To avoid any interpretation issues, a single (system, audio)
+timestamp is reported. Applications that need different timestamps
+will be required to issue multiple queries and perform an
+interpolation of the results
+
+In some hardware-specific configuration, the system timestamp is
+latched by a low-level audio subsystem, and the information provided
+back to the driver. Due to potential delays in the communication with
+the hardware, there is a risk of misalignment with the avail and delay
+information. To make sure applications are not confused, a
+driver_timestamp field is added in the snd_pcm_status structure; this
+timestamp shows when the information is put together by the driver
+before returning from the ``STATUS`` and ``STATUS_EXT`` ioctl. in most cases
+this driver_timestamp will be identical to the regular system tstamp.
+
+Examples of typestamping with HDaudio:
+
+1. DMA timestamp, no compensation for DMA+analog delay
+::
+
+  $ ./audio_time  -p --ts_type=1
+  playback: systime: 341121338 nsec, audio time 342000000 nsec, 	systime delta -878662
+  playback: systime: 426236663 nsec, audio time 427187500 nsec, 	systime delta -950837
+  playback: systime: 597080580 nsec, audio time 598000000 nsec, 	systime delta -919420
+  playback: systime: 682059782 nsec, audio time 683020833 nsec, 	systime delta -961051
+  playback: systime: 852896415 nsec, audio time 853854166 nsec, 	systime delta -957751
+  playback: systime: 937903344 nsec, audio time 938854166 nsec, 	systime delta -950822
+
+2. DMA timestamp, compensation for DMA+analog delay
+::
+
+  $ ./audio_time  -p --ts_type=1 -d
+  playback: systime: 341053347 nsec, audio time 341062500 nsec, 	systime delta -9153
+  playback: systime: 426072447 nsec, audio time 426062500 nsec, 	systime delta 9947
+  playback: systime: 596899518 nsec, audio time 596895833 nsec, 	systime delta 3685
+  playback: systime: 681915317 nsec, audio time 681916666 nsec, 	systime delta -1349
+  playback: systime: 852741306 nsec, audio time 852750000 nsec, 	systime delta -8694
+
+3. link timestamp, compensation for DMA+analog delay
+::
+
+  $ ./audio_time  -p --ts_type=2 -d
+  playback: systime: 341060004 nsec, audio time 341062791 nsec, 	systime delta -2787
+  playback: systime: 426242074 nsec, audio time 426244875 nsec, 	systime delta -2801
+  playback: systime: 597080992 nsec, audio time 597084583 nsec, 	systime delta -3591
+  playback: systime: 682084512 nsec, audio time 682088291 nsec, 	systime delta -3779
+  playback: systime: 852936229 nsec, audio time 852940916 nsec, 	systime delta -4687
+  playback: systime: 938107562 nsec, audio time 938112708 nsec, 	systime delta -5146
+
+Example 1 shows that the timestamp at the DMA level is close to 1ms
+ahead of the actual playback time (as a side time this sort of
+measurement can help define rewind safeguards). Compensating for the
+DMA-link delay in example 2 helps remove the hardware buffering but
+the information is still very jittery, with up to one sample of
+error. In example 3 where the timestamps are measured with the link
+wallclock, the timestamps show a monotonic behavior and a lower
+dispersion.
+
+Example 3 and 4 are with USB audio class. Example 3 shows a high
+offset between audio time and system time due to buffering. Example 4
+shows how compensating for the delay exposes a 1ms accuracy (due to
+the use of the frame counter by the driver)
+
+Example 3: DMA timestamp, no compensation for delay, delta of ~5ms
+::
+
+  $ ./audio_time -p -Dhw:1 -t1
+  playback: systime: 120174019 nsec, audio time 125000000 nsec, 	systime delta -4825981
+  playback: systime: 245041136 nsec, audio time 250000000 nsec, 	systime delta -4958864
+  playback: systime: 370106088 nsec, audio time 375000000 nsec, 	systime delta -4893912
+  playback: systime: 495040065 nsec, audio time 500000000 nsec, 	systime delta -4959935
+  playback: systime: 620038179 nsec, audio time 625000000 nsec, 	systime delta -4961821
+  playback: systime: 745087741 nsec, audio time 750000000 nsec, 	systime delta -4912259
+  playback: systime: 870037336 nsec, audio time 875000000 nsec, 	systime delta -4962664
+
+Example 4: DMA timestamp, compensation for delay, delay of ~1ms
+::
+
+  $ ./audio_time -p -Dhw:1 -t1 -d
+  playback: systime: 120190520 nsec, audio time 120000000 nsec, 	systime delta 190520
+  playback: systime: 245036740 nsec, audio time 244000000 nsec, 	systime delta 1036740
+  playback: systime: 370034081 nsec, audio time 369000000 nsec, 	systime delta 1034081
+  playback: systime: 495159907 nsec, audio time 494000000 nsec, 	systime delta 1159907
+  playback: systime: 620098824 nsec, audio time 619000000 nsec, 	systime delta 1098824
+  playback: systime: 745031847 nsec, audio time 744000000 nsec, 	systime delta 1031847
-- 
cgit v1.2.3


From df3a57105c04a7bfe0874316a9e6ec968c35a6f5 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 11:10:35 +0100
Subject: ALSA: doc: ReSTize Jack-Controls.txt

A simple conversion from a plain text file.
Put to designs subdirectory.

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/Jack-Controls.txt    | 43 ------------------------
 Documentation/sound/designs/index.rst         |  1 +
 Documentation/sound/designs/jack-controls.rst | 48 +++++++++++++++++++++++++++
 3 files changed, 49 insertions(+), 43 deletions(-)
 delete mode 100644 Documentation/sound/alsa/Jack-Controls.txt
 create mode 100644 Documentation/sound/designs/jack-controls.rst

diff --git a/Documentation/sound/alsa/Jack-Controls.txt b/Documentation/sound/alsa/Jack-Controls.txt
deleted file mode 100644
index fe1c5e0c8555..000000000000
--- a/Documentation/sound/alsa/Jack-Controls.txt
+++ /dev/null
@@ -1,43 +0,0 @@
-Why we need Jack kcontrols
-==========================
-
-ALSA uses kcontrols to export audio controls(switch, volume, Mux, ...)
-to user space. This means userspace applications like pulseaudio can
-switch off headphones and switch on speakers when no headphones are
-pluged in.
-
-The old ALSA jack code only created input devices for each registered
-jack. These jack input devices are not readable by userspace devices
-that run as non root.
-
-The new jack code creates embedded jack kcontrols for each jack that
-can be read by any process.
-
-This can be combined with UCM to allow userspace to route audio more
-intelligently based on jack insertion or removal events.
-
-Jack Kcontrol Internals
-=======================
-
-Each jack will have a kcontrol list, so that we can create a kcontrol
-and attach it to the jack, at jack creation stage. We can also add a
-kcontrol to an existing jack, at anytime when required.
-
-Those kcontrols will be freed automatically when the Jack is freed.
-
-How to use jack kcontrols
-=========================
-
-In order to keep compatibility, snd_jack_new() has been modified by
-adding two params :-
-
- - @initial_kctl: if true, create a kcontrol and add it to the jack
-	list.
- - @phantom_jack: Don't create a input device for phantom jacks.
-
-HDA jacks can set phantom_jack to true in order to create a phantom
-jack and set initial_kctl to true to create an initial kcontrol with
-the correct id.
-
-ASoC jacks should set initial_kctl as false. The pin name will be
-assigned as the jack kcontrol name.
diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst
index 798b1a44bbbd..04dcdae3e4f2 100644
--- a/Documentation/sound/designs/index.rst
+++ b/Documentation/sound/designs/index.rst
@@ -8,6 +8,7 @@ Designs and Implementations
    channel-mapping-api
    compress-offload
    timestamping
+   jack-controls
    procfile
    powersave
    oss-emulation
diff --git a/Documentation/sound/designs/jack-controls.rst b/Documentation/sound/designs/jack-controls.rst
new file mode 100644
index 000000000000..ae25b1531bb0
--- /dev/null
+++ b/Documentation/sound/designs/jack-controls.rst
@@ -0,0 +1,48 @@
+==================
+ALSA Jack Controls
+==================
+
+Why we need Jack kcontrols
+==========================
+
+ALSA uses kcontrols to export audio controls(switch, volume, Mux, ...)
+to user space. This means userspace applications like pulseaudio can
+switch off headphones and switch on speakers when no headphones are
+pluged in.
+
+The old ALSA jack code only created input devices for each registered
+jack. These jack input devices are not readable by userspace devices
+that run as non root.
+
+The new jack code creates embedded jack kcontrols for each jack that
+can be read by any process.
+
+This can be combined with UCM to allow userspace to route audio more
+intelligently based on jack insertion or removal events.
+
+Jack Kcontrol Internals
+=======================
+
+Each jack will have a kcontrol list, so that we can create a kcontrol
+and attach it to the jack, at jack creation stage. We can also add a
+kcontrol to an existing jack, at anytime when required.
+
+Those kcontrols will be freed automatically when the Jack is freed.
+
+How to use jack kcontrols
+=========================
+
+In order to keep compatibility, snd_jack_new() has been modified by
+adding two params:
+
+initial_kctl
+  if true, create a kcontrol and add it to the jack list.
+phantom_jack
+  Don't create a input device for phantom jacks.
+
+HDA jacks can set phantom_jack to true in order to create a phantom
+jack and set initial_kctl to true to create an initial kcontrol with
+the correct id.
+
+ASoC jacks should set initial_kctl as false. The pin name will be
+assigned as the jack kcontrol name.
-- 
cgit v1.2.3


From f59c3c6d87d6f7e1593ca874b755265cf08f8714 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Wed, 9 Nov 2016 17:04:22 +0100
Subject: ALSA: doc: ReSTize Joystick document

A conversion from a simple text file.
A new subdirectory, cards, was created to contain the card-specific
information like this one.

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/Joystick.txt  | 86 --------------------------------
 Documentation/sound/cards/index.rst    |  7 +++
 Documentation/sound/cards/joystick.rst | 91 ++++++++++++++++++++++++++++++++++
 Documentation/sound/index.rst          |  1 +
 4 files changed, 99 insertions(+), 86 deletions(-)
 delete mode 100644 Documentation/sound/alsa/Joystick.txt
 create mode 100644 Documentation/sound/cards/index.rst
 create mode 100644 Documentation/sound/cards/joystick.rst

diff --git a/Documentation/sound/alsa/Joystick.txt b/Documentation/sound/alsa/Joystick.txt
deleted file mode 100644
index ccda41b10f8a..000000000000
--- a/Documentation/sound/alsa/Joystick.txt
+++ /dev/null
@@ -1,86 +0,0 @@
-Analog Joystick Support on ALSA Drivers
-=======================================
-                          Oct. 14, 2003
-           Takashi Iwai 
-
-General
--------
-
-First of all, you need to enable GAMEPORT support on Linux kernel for
-using a joystick with the ALSA driver.  For the details of gameport
-support, refer to Documentation/input/joystick.txt.
-
-The joystick support of ALSA drivers is different between ISA and PCI
-cards.  In the case of ISA (PnP) cards, it's usually handled by the
-independent module (ns558).  Meanwhile, the ALSA PCI drivers have the
-built-in gameport support.  Hence, when the ALSA PCI driver is built
-in the kernel, CONFIG_GAMEPORT must be 'y', too.  Otherwise, the
-gameport support on that card will be (silently) disabled.
-
-Some adapter modules probe the physical connection of the device at
-the load time.  It'd be safer to plug in the joystick device before
-loading the module.
-
-
-PCI Cards
----------
-
-For PCI cards, the joystick is enabled when the appropriate module
-option is specified.  Some drivers don't need options, and the
-joystick support is always enabled.  In the former ALSA version, there
-was a dynamic control API for the joystick activation.  It was
-changed, however, to the static module options because of the system
-stability and the resource management.
-
-The following PCI drivers support the joystick natively.
-
-    Driver	Module Option	Available Values
-    ---------------------------------------------------------------------------
-    als4000	joystick_port	0 = disable (default), 1 = auto-detect,
-                                manual: any address (e.g. 0x200)
-    au88x0	N/A		N/A
-    azf3328	joystick	0 = disable, 1 = enable, -1 = auto (default)
-    ens1370	joystick	0 = disable (default), 1 = enable
-    ens1371	joystick_port	0 = disable (default), 1 = auto-detect,
-                                manual: 0x200, 0x208, 0x210, 0x218
-    cmipci	joystick_port	0 = disable (default), 1 = auto-detect,
-                                manual: any address (e.g. 0x200)
-    cs4281	N/A		N/A
-    cs46xx	N/A		N/A
-    es1938	N/A		N/A
-    es1968	joystick	0 = disable (default), 1 = enable
-    sonicvibes	N/A		N/A
-    trident	N/A		N/A
-    via82xx(*1)	joystick	0 = disable (default), 1 = enable
-    ymfpci	joystick_port	0 = disable (default), 1 = auto-detect,
-                                manual: 0x201, 0x202, 0x204, 0x205(*2)
-    ---------------------------------------------------------------------------
-
-    *1)  VIA686A/B only
-    *2)  With YMF744/754 chips, the port address can be chosen arbitrarily
-
-The following drivers don't support gameport natively, but there are
-additional modules.  Load the corresponding module to add the gameport
-support.
-
-    Driver	Additional Module
-    -----------------------------
-    emu10k1	emu10k1-gp
-    fm801	fm801-gp
-    -----------------------------
-
-Note: the "pcigame" and "cs461x" modules are for the OSS drivers only.
-      These ALSA drivers (cs46xx, trident and au88x0) have the
-      built-in gameport support.
-
-As mentioned above, ALSA PCI drivers have the built-in gameport
-support, so you don't have to load ns558 module.  Just load "joydev"
-and the appropriate adapter module (e.g. "analog").
-
-
-ISA Cards
----------
-
-ALSA ISA drivers don't have the built-in gameport support.
-Instead, you need to load "ns558" module in addition to "joydev" and
-the adapter module (e.g. "analog").
diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
new file mode 100644
index 000000000000..e1f4b78c75d6
--- /dev/null
+++ b/Documentation/sound/cards/index.rst
@@ -0,0 +1,7 @@
+Card-Specific Information
+=========================
+
+.. toctree::
+   :maxdepth: 2
+
+   joystick
diff --git a/Documentation/sound/cards/joystick.rst b/Documentation/sound/cards/joystick.rst
new file mode 100644
index 000000000000..a6e468c81d02
--- /dev/null
+++ b/Documentation/sound/cards/joystick.rst
@@ -0,0 +1,91 @@
+=======================================
+Analog Joystick Support on ALSA Drivers
+=======================================
+
+Oct. 14, 2003
+
+Takashi Iwai 
+
+General
+-------
+
+First of all, you need to enable GAMEPORT support on Linux kernel for
+using a joystick with the ALSA driver.  For the details of gameport
+support, refer to Documentation/input/joystick.txt.
+
+The joystick support of ALSA drivers is different between ISA and PCI
+cards.  In the case of ISA (PnP) cards, it's usually handled by the
+independent module (ns558).  Meanwhile, the ALSA PCI drivers have the
+built-in gameport support.  Hence, when the ALSA PCI driver is built
+in the kernel, CONFIG_GAMEPORT must be 'y', too.  Otherwise, the
+gameport support on that card will be (silently) disabled.
+
+Some adapter modules probe the physical connection of the device at
+the load time.  It'd be safer to plug in the joystick device before
+loading the module.
+
+
+PCI Cards
+---------
+
+For PCI cards, the joystick is enabled when the appropriate module
+option is specified.  Some drivers don't need options, and the
+joystick support is always enabled.  In the former ALSA version, there
+was a dynamic control API for the joystick activation.  It was
+changed, however, to the static module options because of the system
+stability and the resource management.
+
+The following PCI drivers support the joystick natively.
+
+==============	=============	============================================
+Driver		Module Option	Available Values
+==============	=============	============================================
+als4000		joystick_port	0 = disable (default), 1 = auto-detect,
+	                        manual: any address (e.g. 0x200)
+au88x0		N/A		N/A
+azf3328		joystick	0 = disable, 1 = enable, -1 = auto (default)
+ens1370		joystick	0 = disable (default), 1 = enable
+ens1371		joystick_port	0 = disable (default), 1 = auto-detect,
+	                        manual: 0x200, 0x208, 0x210, 0x218
+cmipci		joystick_port	0 = disable (default), 1 = auto-detect,
+	                        manual: any address (e.g. 0x200)
+cs4281		N/A		N/A
+cs46xx		N/A		N/A
+es1938		N/A		N/A
+es1968		joystick	0 = disable (default), 1 = enable
+sonicvibes	N/A		N/A
+trident		N/A		N/A
+via82xx [#f1]_	joystick	0 = disable (default), 1 = enable
+ymfpci		joystick_port	0 = disable (default), 1 = auto-detect,
+	                        manual: 0x201, 0x202, 0x204, 0x205 [#f2]_
+==============	=============	============================================
+
+.. [#f1] VIA686A/B only
+.. [#f2] With YMF744/754 chips, the port address can be chosen arbitrarily
+
+The following drivers don't support gameport natively, but there are
+additional modules.  Load the corresponding module to add the gameport
+support.
+
+=======	=================
+Driver	Additional Module
+=======	=================
+emu10k1	emu10k1-gp
+fm801	fm801-gp
+=======	=================
+
+Note: the "pcigame" and "cs461x" modules are for the OSS drivers only.
+These ALSA drivers (cs46xx, trident and au88x0) have the
+built-in gameport support.
+
+As mentioned above, ALSA PCI drivers have the built-in gameport
+support, so you don't have to load ns558 module.  Just load "joydev"
+and the appropriate adapter module (e.g. "analog").
+
+
+ISA Cards
+---------
+
+ALSA ISA drivers don't have the built-in gameport support.
+Instead, you need to load "ns558" module in addition to "joydev" and
+the adapter module (e.g. "analog").
diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst
index e9fbbfff9d0d..1f5d166f81c4 100644
--- a/Documentation/sound/index.rst
+++ b/Documentation/sound/index.rst
@@ -9,6 +9,7 @@ Linux Sound Subsystem Documentation
    designs/index
    alsa-configuration
    hd-audio/index
+   cards/index
 
 .. only::  subproject
 
-- 
cgit v1.2.3


From 95ee717a8937d1a15ad825e5a6fe8cf0befde290 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Wed, 9 Nov 2016 17:12:34 +0100
Subject: ALSA: doc: ReSTize CMIPCI document

A simple conversion from a plain text file.
Put to cards subdirectory.

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/CMIPCI.txt  | 254 --------------------------------
 Documentation/sound/cards/cmipci.rst | 272 +++++++++++++++++++++++++++++++++++
 Documentation/sound/cards/index.rst  |   1 +
 3 files changed, 273 insertions(+), 254 deletions(-)
 delete mode 100644 Documentation/sound/alsa/CMIPCI.txt
 create mode 100644 Documentation/sound/cards/cmipci.rst

diff --git a/Documentation/sound/alsa/CMIPCI.txt b/Documentation/sound/alsa/CMIPCI.txt
deleted file mode 100644
index 4e36e6e809ca..000000000000
--- a/Documentation/sound/alsa/CMIPCI.txt
+++ /dev/null
@@ -1,254 +0,0 @@
-         Brief Notes on C-Media 8338/8738/8768/8770 Driver
-         =================================================
-
-                   Takashi Iwai 
-
-
-Front/Rear Multi-channel Playback
----------------------------------
-
-CM8x38 chip can use ADC as the second DAC so that two different stereo
-channels can be used for front/rear playbacks.  Since there are two
-DACs, both streams are handled independently unlike the 4/6ch multi-
-channel playbacks in the section below.
-
-As default, ALSA driver assigns the first PCM device (i.e. hw:0,0 for
-card#0) for front and 4/6ch playbacks, while the second PCM device
-(hw:0,1) is assigned to the second DAC for rear playback.
-
-There are slight differences between the two DACs:
-
-- The first DAC supports U8 and S16LE formats, while the second DAC
-  supports only S16LE.
-- The second DAC supports only two channel stereo.
-
-Please note that the CM8x38 DAC doesn't support continuous playback
-rate but only fixed rates: 5512, 8000, 11025, 16000, 22050, 32000,
-44100 and 48000 Hz.
-
-The rear output can be heard only when "Four Channel Mode" switch is
-disabled.  Otherwise no signal will be routed to the rear speakers.
-As default it's turned on.
-
-*** WARNING ***
-When "Four Channel Mode" switch is off, the output from rear speakers
-will be FULL VOLUME regardless of Master and PCM volumes.
-This might damage your audio equipment.  Please disconnect speakers
-before your turn off this switch.
-*** WARNING ***
-
-[ Well.. I once got the output with correct volume (i.e. same with the
-  front one) and was so excited.  It was even with "Four Channel" bit
-  on and "double DAC" mode.  Actually I could hear separate 4 channels
-  from front and rear speakers!  But.. after reboot, all was gone.
-  It's a very pity that I didn't save the register dump at that
-  time..  Maybe there is an unknown register to achieve this... ]
-
-If your card has an extra output jack for the rear output, the rear
-playback should be routed there as default.  If not, there is a
-control switch in the driver "Line-In As Rear", which you can change
-via alsamixer or somewhat else.  When this switch is on, line-in jack
-is used as rear output.
-
-There are two more controls regarding to the rear output.
-The "Exchange DAC" switch is used to exchange front and rear playback
-routes, i.e. the 2nd DAC is output from front output.
-
-
-4/6 Multi-Channel Playback
---------------------------
-
-The recent CM8738 chips support for the 4/6 multi-channel playback
-function.  This is useful especially for AC3 decoding.
-
-When the multi-channel is supported, the driver name has a suffix
-"-MC" such like "CMI8738-MC6".  You can check this name from
-/proc/asound/cards.
-
-When the 4/6-ch output is enabled, the second DAC accepts up to 6 (or
-4) channels.  While the dual DAC supports two different rates or
-formats, the 4/6-ch playback supports only the same condition for all
-channels.  Since the multi-channel playback mode uses both DACs, you
-cannot operate with full-duplex.
-
-The 4.0 and 5.1 modes are defined as the pcm "surround40" and "surround51"
-in alsa-lib.  For example, you can play a WAV file with 6 channels like
-
-	% aplay -Dsurround51 sixchannels.wav
-
-For programming the 4/6 channel playback, you need to specify the PCM
-channels as you like and set the format S16LE.  For example, for playback
-with 4 channels,
-
-	snd_pcm_hw_params_set_access(pcm, hw, SND_PCM_ACCESS_RW_INTERLEAVED);
-	    // or mmap if you like
-	snd_pcm_hw_params_set_format(pcm, hw, SND_PCM_FORMAT_S16_LE);
-	snd_pcm_hw_params_set_channels(pcm, hw, 4);
-
-and use the interleaved 4 channel data.
-
-There are some control switches affecting to the speaker connections:
-
-"Line-In Mode"	- an enum control to change the behavior of line-in
-	jack.  Either "Line-In", "Rear Output" or "Bass Output" can
-	be selected.  The last item is available only with model 039
-	or newer. 
-	When "Rear Output" is chosen, the surround channels 3 and 4
-	are output to line-in jack.
-"Mic-In Mode"	- an enum control to change the behavior of mic-in
-	jack.  Either "Mic-In" or "Center/LFE Output" can be
-	selected. 
-	When "Center/LFE Output" is chosen, the center and bass
-	channels (channels 5 and 6) are output to mic-in jack. 
-
-Digital I/O
------------
-
-The CM8x38 provides the excellent SPDIF capability with very cheap
-price (yes, that's the reason I bought the card :)
-
-The SPDIF playback and capture are done via the third PCM device
-(hw:0,2).  Usually this is assigned to the PCM device "spdif".
-The available rates are 44100 and 48000 Hz.
-For playback with aplay, you can run like below:
-
-	% aplay -Dhw:0,2 foo.wav
-
-or
-
-	% aplay -Dspdif foo.wav
-
-24bit format is also supported experimentally.
-
-The playback and capture over SPDIF use normal DAC and ADC,
-respectively, so you cannot playback both analog and digital streams
-simultaneously.
-
-To enable SPDIF output, you need to turn on "IEC958 Output Switch"
-control via mixer or alsactl ("IEC958" is the official name of
-so-called S/PDIF).  Then you'll see the red light on from the card so
-you know that's working obviously :)
-The SPDIF input is always enabled, so you can hear SPDIF input data
-from line-out with "IEC958 In Monitor" switch at any time (see
-below).
-
-You can play via SPDIF even with the first device (hw:0,0),
-but SPDIF is enabled only when the proper format (S16LE), sample rate
-(441100 or 48000) and channels (2) are used.  Otherwise it's turned
-off.  (Also don't forget to turn on "IEC958 Output Switch", too.)
-
-
-Additionally there are relevant control switches:
-
-"IEC958 Mix Analog" - Mix analog PCM playback and FM-OPL/3 streams and
-	output through SPDIF.  This switch appears only on old chip
-	models (CM8738 033 and 037).
-	Note: without this control you can output PCM to SPDIF.
-	This is "mixing" of streams, so e.g. it's not for AC3 output
-	(see the next section).
-
-"IEC958 In Select"  - Select SPDIF input, the internal CD-in (false)
-	and the external input (true).
-
-"IEC958 Loop"       - SPDIF input data is loop back into SPDIF
-	output (aka bypass)
-
-"IEC958 Copyright"  - Set the copyright bit.
-
-"IEC958 5V"         - Select 0.5V (coax) or 5V (optical) interface.
-	On some cards this doesn't work and you need to change the
-	configuration with hardware dip-switch.
-
-"IEC958 In Monitor" - SPDIF input is routed to DAC.
-
-"IEC958 In Phase Inverse" - Set SPDIF input format as inverse.
-	[FIXME: this doesn't work on all chips..]
-
-"IEC958 In Valid"   - Set input validity flag detection.
-
-Note: When "PCM Playback Switch" is on, you'll hear the digital output
-stream through analog line-out.
-
-
-The AC3 (RAW DIGITAL) OUTPUT
-----------------------------
-
-The driver supports raw digital (typically AC3) i/o over SPDIF.  This
-can be toggled via IEC958 playback control, but usually you need to
-access it via alsa-lib.  See alsa-lib documents for more details.
-
-On the raw digital mode, the "PCM Playback Switch" is automatically
-turned off so that non-audio data is heard from the analog line-out.
-Similarly the following switches are off: "IEC958 Mix Analog" and
-"IEC958 Loop".  The switches are resumed after closing the SPDIF PCM
-device automatically to the previous state.
-
-On the model 033, AC3 is implemented by the software conversion in
-the alsa-lib.  If you need to bypass the software conversion of IEC958
-subframes, pass the "soft_ac3=0" module option.  This doesn't matter
-on the newer models.
-
-
-ANALOG MIXER INTERFACE
-----------------------
-
-The mixer interface on CM8x38 is similar to SB16.
-There are Master, PCM, Synth, CD, Line, Mic and PC Speaker playback
-volumes.  Synth, CD, Line and Mic have playback and capture switches,
-too, as well as SB16.
-
-In addition to the standard SB mixer, CM8x38 provides more functions.
-- PCM playback switch
-- PCM capture switch (to capture the data sent to DAC)
-- Mic Boost switch
-- Mic capture volume
-- Aux playback volume/switch and capture switch
-- 3D control switch
-
-
-MIDI CONTROLLER
----------------
-
-With CMI8338 chips, the MPU401-UART interface is disabled as default.
-You need to set the module option "mpu_port" to a valid I/O port address
-to enable MIDI support.  Valid I/O ports are 0x300, 0x310, 0x320 and
-0x330.  Choose a value that doesn't conflict with other cards.
-
-With CMI8738 and newer chips, the MIDI interface is enabled by default
-and the driver automatically chooses a port address.
-
-There is _no_ hardware wavetable function on this chip (except for
-OPL3 synth below).
-What's said as MIDI synth on Windows is a software synthesizer
-emulation.  On Linux use TiMidity or other softsynth program for
-playing MIDI music.
-
-
-FM OPL/3 Synth
---------------
-
-The FM OPL/3 is also enabled as default only for the first card.
-Set "fm_port" module option for more cards.
-
-The output quality of FM OPL/3 is, however, very weird.
-I don't know why..
-
-CMI8768 and newer chips do not have the FM synth.
-
-
-Joystick and Modem
-------------------
-
-The legacy joystick is supported.  To enable the joystick support, pass
-joystick_port=1 module option.  The value 1 means the auto-detection.
-If the auto-detection fails, try to pass the exact I/O address.
-
-The modem is enabled dynamically via a card control switch "Modem".
-
-
-Debugging Information
----------------------
-
-The registers are shown in /proc/asound/cardX/cmipci.  If you have any
-problem (especially unexpected behavior of mixer), please attach the
-output of this proc file together with the bug report.
diff --git a/Documentation/sound/cards/cmipci.rst b/Documentation/sound/cards/cmipci.rst
new file mode 100644
index 000000000000..9ea1de6ec4ce
--- /dev/null
+++ b/Documentation/sound/cards/cmipci.rst
@@ -0,0 +1,272 @@
+=================================================
+Brief Notes on C-Media 8338/8738/8768/8770 Driver
+=================================================
+
+Takashi Iwai 
+
+
+Front/Rear Multi-channel Playback
+---------------------------------
+
+CM8x38 chip can use ADC as the second DAC so that two different stereo
+channels can be used for front/rear playbacks.  Since there are two
+DACs, both streams are handled independently unlike the 4/6ch multi-
+channel playbacks in the section below.
+
+As default, ALSA driver assigns the first PCM device (i.e. hw:0,0 for
+card#0) for front and 4/6ch playbacks, while the second PCM device
+(hw:0,1) is assigned to the second DAC for rear playback.
+
+There are slight differences between the two DACs:
+
+- The first DAC supports U8 and S16LE formats, while the second DAC
+  supports only S16LE.
+- The second DAC supports only two channel stereo.
+
+Please note that the CM8x38 DAC doesn't support continuous playback
+rate but only fixed rates: 5512, 8000, 11025, 16000, 22050, 32000,
+44100 and 48000 Hz.
+
+The rear output can be heard only when "Four Channel Mode" switch is
+disabled.  Otherwise no signal will be routed to the rear speakers.
+As default it's turned on.
+
+.. WARNING::
+  When "Four Channel Mode" switch is off, the output from rear speakers
+  will be FULL VOLUME regardless of Master and PCM volumes [#]_.
+  This might damage your audio equipment.  Please disconnect speakers
+  before your turn off this switch.
+
+
+.. [#]
+  Well.. I once got the output with correct volume (i.e. same with the
+  front one) and was so excited.  It was even with "Four Channel" bit
+  on and "double DAC" mode.  Actually I could hear separate 4 channels
+  from front and rear speakers!  But.. after reboot, all was gone.
+  It's a very pity that I didn't save the register dump at that
+  time..  Maybe there is an unknown register to achieve this...
+
+If your card has an extra output jack for the rear output, the rear
+playback should be routed there as default.  If not, there is a
+control switch in the driver "Line-In As Rear", which you can change
+via alsamixer or somewhat else.  When this switch is on, line-in jack
+is used as rear output.
+
+There are two more controls regarding to the rear output.
+The "Exchange DAC" switch is used to exchange front and rear playback
+routes, i.e. the 2nd DAC is output from front output.
+
+
+4/6 Multi-Channel Playback
+--------------------------
+
+The recent CM8738 chips support for the 4/6 multi-channel playback
+function.  This is useful especially for AC3 decoding.
+
+When the multi-channel is supported, the driver name has a suffix
+"-MC" such like "CMI8738-MC6".  You can check this name from
+/proc/asound/cards.
+
+When the 4/6-ch output is enabled, the second DAC accepts up to 6 (or
+4) channels.  While the dual DAC supports two different rates or
+formats, the 4/6-ch playback supports only the same condition for all
+channels.  Since the multi-channel playback mode uses both DACs, you
+cannot operate with full-duplex.
+
+The 4.0 and 5.1 modes are defined as the pcm "surround40" and "surround51"
+in alsa-lib.  For example, you can play a WAV file with 6 channels like
+::
+
+	% aplay -Dsurround51 sixchannels.wav
+
+For programming the 4/6 channel playback, you need to specify the PCM
+channels as you like and set the format S16LE.  For example, for playback
+with 4 channels,
+::
+
+	snd_pcm_hw_params_set_access(pcm, hw, SND_PCM_ACCESS_RW_INTERLEAVED);
+	    // or mmap if you like
+	snd_pcm_hw_params_set_format(pcm, hw, SND_PCM_FORMAT_S16_LE);
+	snd_pcm_hw_params_set_channels(pcm, hw, 4);
+
+and use the interleaved 4 channel data.
+
+There are some control switches affecting to the speaker connections:
+
+Line-In Mode
+	an enum control to change the behavior of line-in
+	jack.  Either "Line-In", "Rear Output" or "Bass Output" can
+	be selected.  The last item is available only with model 039
+	or newer. 
+	When "Rear Output" is chosen, the surround channels 3 and 4
+	are output to line-in jack.
+Mic-In Mode
+	an enum control to change the behavior of mic-in
+	jack.  Either "Mic-In" or "Center/LFE Output" can be
+	selected. 
+	When "Center/LFE Output" is chosen, the center and bass
+	channels (channels 5 and 6) are output to mic-in jack. 
+
+Digital I/O
+-----------
+
+The CM8x38 provides the excellent SPDIF capability with very cheap
+price (yes, that's the reason I bought the card :)
+
+The SPDIF playback and capture are done via the third PCM device
+(hw:0,2).  Usually this is assigned to the PCM device "spdif".
+The available rates are 44100 and 48000 Hz.
+For playback with aplay, you can run like below:
+::
+
+	% aplay -Dhw:0,2 foo.wav
+
+or
+
+::
+
+	% aplay -Dspdif foo.wav
+
+24bit format is also supported experimentally.
+
+The playback and capture over SPDIF use normal DAC and ADC,
+respectively, so you cannot playback both analog and digital streams
+simultaneously.
+
+To enable SPDIF output, you need to turn on "IEC958 Output Switch"
+control via mixer or alsactl ("IEC958" is the official name of
+so-called S/PDIF).  Then you'll see the red light on from the card so
+you know that's working obviously :)
+The SPDIF input is always enabled, so you can hear SPDIF input data
+from line-out with "IEC958 In Monitor" switch at any time (see
+below).
+
+You can play via SPDIF even with the first device (hw:0,0),
+but SPDIF is enabled only when the proper format (S16LE), sample rate
+(441100 or 48000) and channels (2) are used.  Otherwise it's turned
+off.  (Also don't forget to turn on "IEC958 Output Switch", too.)
+
+
+Additionally there are relevant control switches:
+
+IEC958 Mix Analog
+	Mix analog PCM playback and FM-OPL/3 streams and
+	output through SPDIF.  This switch appears only on old chip
+	models (CM8738 033 and 037).
+
+	Note: without this control you can output PCM to SPDIF.
+	This is "mixing" of streams, so e.g. it's not for AC3 output
+	(see the next section).
+
+IEC958 In Select
+	Select SPDIF input, the internal CD-in (false)
+	and the external input (true).
+
+IEC958 Loop
+	SPDIF input data is loop back into SPDIF
+	output (aka bypass)
+
+IEC958 Copyright
+	Set the copyright bit.
+
+IEC958 5V
+	Select 0.5V (coax) or 5V (optical) interface.
+	On some cards this doesn't work and you need to change the
+	configuration with hardware dip-switch.
+
+IEC958 In Monitor
+	SPDIF input is routed to DAC.
+
+IEC958 In Phase Inverse
+	Set SPDIF input format as inverse.
+	[FIXME: this doesn't work on all chips..]
+
+IEC958 In Valid
+	Set input validity flag detection.
+
+Note: When "PCM Playback Switch" is on, you'll hear the digital output
+stream through analog line-out.
+
+
+The AC3 (RAW DIGITAL) OUTPUT
+----------------------------
+
+The driver supports raw digital (typically AC3) i/o over SPDIF.  This
+can be toggled via IEC958 playback control, but usually you need to
+access it via alsa-lib.  See alsa-lib documents for more details.
+
+On the raw digital mode, the "PCM Playback Switch" is automatically
+turned off so that non-audio data is heard from the analog line-out.
+Similarly the following switches are off: "IEC958 Mix Analog" and
+"IEC958 Loop".  The switches are resumed after closing the SPDIF PCM
+device automatically to the previous state.
+
+On the model 033, AC3 is implemented by the software conversion in
+the alsa-lib.  If you need to bypass the software conversion of IEC958
+subframes, pass the "soft_ac3=0" module option.  This doesn't matter
+on the newer models.
+
+
+ANALOG MIXER INTERFACE
+----------------------
+
+The mixer interface on CM8x38 is similar to SB16.
+There are Master, PCM, Synth, CD, Line, Mic and PC Speaker playback
+volumes.  Synth, CD, Line and Mic have playback and capture switches,
+too, as well as SB16.
+
+In addition to the standard SB mixer, CM8x38 provides more functions.
+- PCM playback switch
+- PCM capture switch (to capture the data sent to DAC)
+- Mic Boost switch
+- Mic capture volume
+- Aux playback volume/switch and capture switch
+- 3D control switch
+
+
+MIDI CONTROLLER
+---------------
+
+With CMI8338 chips, the MPU401-UART interface is disabled as default.
+You need to set the module option "mpu_port" to a valid I/O port address
+to enable MIDI support.  Valid I/O ports are 0x300, 0x310, 0x320 and
+0x330.  Choose a value that doesn't conflict with other cards.
+
+With CMI8738 and newer chips, the MIDI interface is enabled by default
+and the driver automatically chooses a port address.
+
+There is *no* hardware wavetable function on this chip (except for
+OPL3 synth below).
+What's said as MIDI synth on Windows is a software synthesizer
+emulation.  On Linux use TiMidity or other softsynth program for
+playing MIDI music.
+
+
+FM OPL/3 Synth
+--------------
+
+The FM OPL/3 is also enabled as default only for the first card.
+Set "fm_port" module option for more cards.
+
+The output quality of FM OPL/3 is, however, very weird.
+I don't know why..
+
+CMI8768 and newer chips do not have the FM synth.
+
+
+Joystick and Modem
+------------------
+
+The legacy joystick is supported.  To enable the joystick support, pass
+joystick_port=1 module option.  The value 1 means the auto-detection.
+If the auto-detection fails, try to pass the exact I/O address.
+
+The modem is enabled dynamically via a card control switch "Modem".
+
+
+Debugging Information
+---------------------
+
+The registers are shown in /proc/asound/cardX/cmipci.  If you have any
+problem (especially unexpected behavior of mixer), please attach the
+output of this proc file together with the bug report.
diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index e1f4b78c75d6..67a3073157b9 100644
--- a/Documentation/sound/cards/index.rst
+++ b/Documentation/sound/cards/index.rst
@@ -5,3 +5,4 @@ Card-Specific Information
    :maxdepth: 2
 
    joystick
+   cmipci
-- 
cgit v1.2.3


From ecef1481d516e004a38d9472c403205dcdd1491e Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 16:17:56 +0100
Subject: ALSA: doc: ReSTize SB-Live-mixer document

Another simple conversion from a plain text file.
Put to cards subdirectory.

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/SB-Live-mixer.txt  | 356 --------------------------
 Documentation/sound/cards/index.rst         |   1 +
 Documentation/sound/cards/sb-live-mixer.rst | 373 ++++++++++++++++++++++++++++
 3 files changed, 374 insertions(+), 356 deletions(-)
 delete mode 100644 Documentation/sound/alsa/SB-Live-mixer.txt
 create mode 100644 Documentation/sound/cards/sb-live-mixer.rst

diff --git a/Documentation/sound/alsa/SB-Live-mixer.txt b/Documentation/sound/alsa/SB-Live-mixer.txt
deleted file mode 100644
index f4b5988f450c..000000000000
--- a/Documentation/sound/alsa/SB-Live-mixer.txt
+++ /dev/null
@@ -1,356 +0,0 @@
-
-		Sound Blaster Live mixer / default DSP code
-		===========================================
-
-
-The EMU10K1 chips have a DSP part which can be programmed to support
-various ways of sample processing, which is described here.
-(This article does not deal with the overall functionality of the 
-EMU10K1 chips. See the manuals section for further details.)
-
-The ALSA driver programs this portion of chip by default code
-(can be altered later) which offers the following functionality:
-
-
-1) IEC958 (S/PDIF) raw PCM
---------------------------
-
-This PCM device (it's the 4th PCM device (index 3!) and first subdevice
-(index 0) for a given card) allows to forward 48kHz, stereo, 16-bit
-little endian streams without any modifications to the digital output
-(coaxial or optical). The universal interface allows the creation of up
-to 8 raw PCM devices operating at 48kHz, 16-bit little endian. It would
-be easy to add support for multichannel devices to the current code,
-but the conversion routines exist only for stereo (2-channel streams)
-at the time. 
-
-Look to tram_poke routines in lowlevel/emu10k1/emufx.c for more details.
-
-
-2) Digital mixer controls
--------------------------
-
-These controls are built using the DSP instructions. They offer extended
-functionality. Only the default build-in code in the ALSA driver is described
-here. Note that the controls work as attenuators: the maximum value is the 
-neutral position leaving the signal unchanged. Note that if the  same destination 
-is mentioned in multiple controls, the signal is accumulated and can be wrapped 
-(set to maximal or minimal value without checking of overflow).
-
-
-Explanation of used abbreviations:
-
-DAC    - digital to analog converter
-ADC    - analog to digital converter
-I2S    - one-way three wire serial bus for digital sound by Philips Semiconductors
-         (this standard is used for connecting standalone DAC and ADC converters)
-LFE    - low frequency effects (subwoofer signal)
-AC97   - a chip containing an analog mixer, DAC and ADC converters
-IEC958 - S/PDIF
-FX-bus - the EMU10K1 chip has an effect bus containing 16 accumulators.
-         Each of the synthesizer voices can feed its output to these accumulators
-         and the DSP microcontroller can operate with the resulting sum.
-
-
-name='Wave Playback Volume',index=0
-
-This control is used to attenuate samples for left and right PCM FX-bus
-accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples.
-The result samples are forwarded to the front DAC PCM slots of the AC97 codec.
-
-name='Wave Surround Playback Volume',index=0
-
-This control is used to attenuate samples for left and right PCM FX-bus
-accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples.
-The result samples are forwarded to the rear I2S DACs. These DACs operates
-separately (they are not inside the AC97 codec).
-
-name='Wave Center Playback Volume',index=0
-
-This control is used to attenuate samples for left and right PCM FX-bus
-accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples.
-The result is mixed to mono signal (single channel) and forwarded to
-the ??rear?? right DAC PCM slot of the AC97 codec.
-
-name='Wave LFE Playback Volume',index=0
-
-This control is used to attenuate samples for left and right PCM FX-bus
-accumulators. ALSA uses accumulators 0 and 1 for left and right PCM.
-The result is mixed to mono signal (single channel) and forwarded to
-the ??rear?? left DAC PCM slot of the AC97 codec.
-
-name='Wave Capture Volume',index=0
-name='Wave Capture Switch',index=0
-
-These controls are used to attenuate samples for left and right PCM FX-bus
-accumulator. ALSA uses accumulators 0 and 1 for left and right PCM.
-The result is forwarded to the ADC capture FIFO (thus to the standard capture
-PCM device).
-
-name='Synth Playback Volume',index=0
-
-This control is used to attenuate samples for left and right MIDI FX-bus
-accumulators. ALSA uses accumulators 4 and 5 for left and right MIDI samples.
-The result samples are forwarded to the front DAC PCM slots of the AC97 codec.
-
-name='Synth Capture Volume',index=0
-name='Synth Capture Switch',index=0
-
-These controls are used to attenuate samples for left and right MIDI FX-bus
-accumulator. ALSA uses accumulators 4 and 5 for left and right PCM.
-The result is forwarded to the ADC capture FIFO (thus to the standard capture
-PCM device).
-
-name='Surround Playback Volume',index=0
-
-This control is used to attenuate samples for left and right rear PCM FX-bus
-accumulators. ALSA uses accumulators 2 and 3 for left and right rear PCM samples.
-The result samples are forwarded to the rear I2S DACs. These DACs operate
-separately (they are not inside the AC97 codec).
-
-name='Surround Capture Volume',index=0
-name='Surround Capture Switch',index=0
-
-These controls are used to attenuate samples for left and right rear PCM FX-bus
-accumulators. ALSA uses accumulators 2 and 3 for left and right rear PCM samples.
-The result is forwarded to the ADC capture FIFO (thus to the standard capture
-PCM device).
-
-name='Center Playback Volume',index=0
-
-This control is used to attenuate sample for center PCM FX-bus accumulator.
-ALSA uses accumulator 6 for center PCM sample. The result sample is forwarded
-to the ??rear?? right DAC PCM slot of the AC97 codec.
-
-name='LFE Playback Volume',index=0
-
-This control is used to attenuate sample for center PCM FX-bus accumulator.
-ALSA uses accumulator 6 for center PCM sample. The result sample is forwarded
-to the ??rear?? left DAC PCM slot of the AC97 codec.
-
-name='AC97 Playback Volume',index=0
-
-This control is used to attenuate samples for left and right front ADC PCM slots
-of the AC97 codec. The result samples are forwarded to the front DAC PCM
-slots of the AC97 codec.
-********************************************************************************
-*** Note: This control should be zero for the standard operations, otherwise ***
-*** a digital loopback is activated.                                         ***
-********************************************************************************
-
-name='AC97 Capture Volume',index=0
-
-This control is used to attenuate samples for left and right front ADC PCM slots
-of the AC97 codec. The result is forwarded to the ADC capture FIFO (thus to
-the standard capture PCM device).
-********************************************************************************
-*** Note: This control should be 100 (maximal value), otherwise no analog    ***
-*** inputs of the AC97 codec can be captured (recorded).                     ***
-********************************************************************************
-
-name='IEC958 TTL Playback Volume',index=0
-
-This control is used to attenuate samples from left and right IEC958 TTL
-digital inputs (usually used by a CDROM drive). The result samples are
-forwarded to the front DAC PCM slots of the AC97 codec.
-
-name='IEC958 TTL Capture Volume',index=0
-
-This control is used to attenuate samples from left and right IEC958 TTL
-digital inputs (usually used by a CDROM drive). The result samples are
-forwarded to the ADC capture FIFO (thus to the standard capture PCM device).
-
-name='Zoom Video Playback Volume',index=0
-
-This control is used to attenuate samples from left and right zoom video
-digital inputs (usually used by a CDROM drive). The result samples are
-forwarded to the front DAC PCM slots of the AC97 codec.
-
-name='Zoom Video Capture Volume',index=0
-
-This control is used to attenuate samples from left and right zoom video
-digital inputs (usually used by a CDROM drive). The result samples are
-forwarded to the ADC capture FIFO (thus to the standard capture PCM device).
-
-name='IEC958 LiveDrive Playback Volume',index=0
-
-This control is used to attenuate samples from left and right IEC958 optical
-digital input. The result samples are forwarded to the front DAC PCM slots
-of the AC97 codec.
-
-name='IEC958 LiveDrive Capture Volume',index=0
-
-This control is used to attenuate samples from left and right IEC958 optical
-digital inputs. The result samples are forwarded to the ADC capture FIFO
-(thus to the standard capture PCM device).
-
-name='IEC958 Coaxial Playback Volume',index=0
-
-This control is used to attenuate samples from left and right IEC958 coaxial
-digital inputs. The result samples are forwarded to the front DAC PCM slots
-of the AC97 codec.
-
-name='IEC958 Coaxial Capture Volume',index=0
-
-This control is used to attenuate samples from left and right IEC958 coaxial
-digital inputs. The result samples are forwarded to the ADC capture FIFO
-(thus to the standard capture PCM device).
-
-name='Line LiveDrive Playback Volume',index=0
-name='Line LiveDrive Playback Volume',index=1
-
-This control is used to attenuate samples from left and right I2S ADC
-inputs (on the LiveDrive). The result samples are forwarded to the front
-DAC PCM slots of the AC97 codec.
-
-name='Line LiveDrive Capture Volume',index=1
-name='Line LiveDrive Capture Volume',index=1
-
-This control is used to attenuate samples from left and right I2S ADC
-inputs (on the LiveDrive). The result samples are forwarded to the ADC
-capture FIFO (thus to the standard capture PCM device).
-
-name='Tone Control - Switch',index=0
-
-This control turns the tone control on or off. The samples for front, rear
-and center / LFE outputs are affected.
-
-name='Tone Control - Bass',index=0
-
-This control sets the bass intensity. There is no neutral value!!
-When the tone control code is activated, the samples are always modified.
-The closest value to pure signal is 20.
-
-name='Tone Control - Treble',index=0
-
-This control sets the treble intensity. There is no neutral value!!
-When the tone control code is activated, the samples are always modified.
-The closest value to pure signal is 20.
-
-name='IEC958 Optical Raw Playback Switch',index=0
-
-If this switch is on, then the samples for the IEC958 (S/PDIF) digital
-output are taken only from the raw FX8010 PCM, otherwise standard front
-PCM samples are taken.
-
-name='Headphone Playback Volume',index=1
-
-This control attenuates the samples for the headphone output.
-
-name='Headphone Center Playback Switch',index=1
-
-If this switch is on, then the sample for the center PCM is put to the
-left headphone output (useful for SB Live cards without separate center/LFE
-output).
-
-name='Headphone LFE Playback Switch',index=1
-
-If this switch is on, then the sample for the center PCM is put to the
-right headphone output (useful for SB Live cards without separate center/LFE
-output).
-
-
-3) PCM stream related controls
-------------------------------
-
-name='EMU10K1 PCM Volume',index 0-31
-
-Channel volume attenuation in range 0-0xffff. The maximum value (no
-attenuation) is default. The channel mapping for three values is
-as follows:
-
-	0 - mono, default 0xffff (no attenuation)
-	1 - left, default 0xffff (no attenuation)
-	2 - right, default 0xffff (no attenuation)
-
-name='EMU10K1 PCM Send Routing',index 0-31
-
-This control specifies the destination - FX-bus accumulators. There are
-twelve values with this mapping:
-
-	 0 -  mono, A destination (FX-bus 0-15), default 0
-	 1 -  mono, B destination (FX-bus 0-15), default 1
-	 2 -  mono, C destination (FX-bus 0-15), default 2
-	 3 -  mono, D destination (FX-bus 0-15), default 3
-	 4 -  left, A destination (FX-bus 0-15), default 0
-	 5 -  left, B destination (FX-bus 0-15), default 1
-	 6 -  left, C destination (FX-bus 0-15), default 2
-	 7 -  left, D destination (FX-bus 0-15), default 3
-	 8 - right, A destination (FX-bus 0-15), default 0
-	 9 - right, B destination (FX-bus 0-15), default 1
-	10 - right, C destination (FX-bus 0-15), default 2
-	11 - right, D destination (FX-bus 0-15), default 3
-
-Don't forget that it's illegal to assign a channel to the same FX-bus accumulator 
-more than once (it means 0=0 && 1=0 is an invalid combination).
- 
-name='EMU10K1 PCM Send Volume',index 0-31
-
-It specifies the attenuation (amount) for given destination in range 0-255.
-The channel mapping is following:
-
-	 0 -  mono, A destination attn, default 255 (no attenuation)
-	 1 -  mono, B destination attn, default 255 (no attenuation)
-	 2 -  mono, C destination attn, default 0 (mute)
-	 3 -  mono, D destination attn, default 0 (mute)
-	 4 -  left, A destination attn, default 255 (no attenuation)
-	 5 -  left, B destination attn, default 0 (mute)
-	 6 -  left, C destination attn, default 0 (mute)
-	 7 -  left, D destination attn, default 0 (mute)
-	 8 - right, A destination attn, default 0 (mute)
-	 9 - right, B destination attn, default 255 (no attenuation)
-	10 - right, C destination attn, default 0 (mute)
-	11 - right, D destination attn, default 0 (mute)
-
-
-
-4) MANUALS/PATENTS:
--------------------
-
-ftp://opensource.creative.com/pub/doc
--------------------------------------
-
-        Files:
-        LM4545.pdf      AC97 Codec
-
-        m2049.pdf       The EMU10K1 Digital Audio Processor
-
-        hog63.ps        FX8010 - A DSP Chip Architecture for Audio Effects
-
-
-WIPO Patents
-------------
-        Patent numbers:
-        WO 9901813 (A1) Audio Effects Processor with multiple asynchronous (Jan. 14, 1999)
-                        streams
-
-        WO 9901814 (A1) Processor with Instruction Set for Audio Effects (Jan. 14, 1999)
-
-        WO 9901953 (A1) Audio Effects Processor having Decoupled Instruction
-                        Execution and Audio Data Sequencing (Jan. 14, 1999)
-
-
-US Patents (http://www.uspto.gov/)
-----------------------------------
-
-        US 5925841      Digital Sampling Instrument employing cache memory (Jul. 20, 1999)
-
-        US 5928342      Audio Effects Processor integrated on a single chip (Jul. 27, 1999)
-                        with a multiport memory onto which multiple asynchronous
-                        digital sound samples can be concurrently loaded
-
-        US 5930158      Processor with Instruction Set for Audio Effects (Jul. 27, 1999)
-
-        US 6032235      Memory initialization circuit (Tram) (Feb. 29, 2000)
-
-        US 6138207      Interpolation looping of audio samples in cache connected to    (Oct. 24, 2000)
-                        system bus with prioritization and modification of bus transfers
-                        in accordance with loop ends and minimum block sizes
-
-        US 6151670      Method for conserving memory storage using a (Nov. 21, 2000)
-                        pool of  short term memory registers
-
-        US 6195715      Interrupt control for multiple programs communicating with      (Feb. 27, 2001)
-                        a common interrupt by associating programs to GP registers,
-                        defining interrupt register, polling GP registers, and invoking
-                        callback routine associated with defined interrupt register
diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index 67a3073157b9..294efdb75bc9 100644
--- a/Documentation/sound/cards/index.rst
+++ b/Documentation/sound/cards/index.rst
@@ -6,3 +6,4 @@ Card-Specific Information
 
    joystick
    cmipci
+   sb-live-mixer
diff --git a/Documentation/sound/cards/sb-live-mixer.rst b/Documentation/sound/cards/sb-live-mixer.rst
new file mode 100644
index 000000000000..bcb62fc99bbb
--- /dev/null
+++ b/Documentation/sound/cards/sb-live-mixer.rst
@@ -0,0 +1,373 @@
+===========================================
+Sound Blaster Live mixer / default DSP code
+===========================================
+
+
+The EMU10K1 chips have a DSP part which can be programmed to support
+various ways of sample processing, which is described here.
+(This article does not deal with the overall functionality of the 
+EMU10K1 chips. See the manuals section for further details.)
+
+The ALSA driver programs this portion of chip by default code
+(can be altered later) which offers the following functionality:
+
+
+IEC958 (S/PDIF) raw PCM
+=======================
+
+This PCM device (it's the 4th PCM device (index 3!) and first subdevice
+(index 0) for a given card) allows to forward 48kHz, stereo, 16-bit
+little endian streams without any modifications to the digital output
+(coaxial or optical). The universal interface allows the creation of up
+to 8 raw PCM devices operating at 48kHz, 16-bit little endian. It would
+be easy to add support for multichannel devices to the current code,
+but the conversion routines exist only for stereo (2-channel streams)
+at the time. 
+
+Look to tram_poke routines in lowlevel/emu10k1/emufx.c for more details.
+
+
+Digital mixer controls
+======================
+
+These controls are built using the DSP instructions. They offer extended
+functionality. Only the default build-in code in the ALSA driver is described
+here. Note that the controls work as attenuators: the maximum value is the 
+neutral position leaving the signal unchanged. Note that if the  same destination 
+is mentioned in multiple controls, the signal is accumulated and can be wrapped 
+(set to maximal or minimal value without checking of overflow).
+
+
+Explanation of used abbreviations:
+
+DAC
+	digital to analog converter
+ADC
+	analog to digital converter
+I2S
+	one-way three wire serial bus for digital sound by Philips Semiconductors
+        (this standard is used for connecting standalone DAC and ADC converters)
+LFE
+	low frequency effects (subwoofer signal)
+AC97
+	a chip containing an analog mixer, DAC and ADC converters
+IEC958
+	S/PDIF
+FX-bus
+	the EMU10K1 chip has an effect bus containing 16 accumulators.
+	Each of the synthesizer voices can feed its output to these accumulators
+	and the DSP microcontroller can operate with the resulting sum.
+
+
+``name='Wave Playback Volume',index=0``
+---------------------------------------
+This control is used to attenuate samples for left and right PCM FX-bus
+accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples.
+The result samples are forwarded to the front DAC PCM slots of the AC97 codec.
+
+``name='Wave Surround Playback Volume',index=0``
+------------------------------------------------
+This control is used to attenuate samples for left and right PCM FX-bus
+accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples.
+The result samples are forwarded to the rear I2S DACs. These DACs operates
+separately (they are not inside the AC97 codec).
+
+``name='Wave Center Playback Volume',index=0``
+----------------------------------------------
+This control is used to attenuate samples for left and right PCM FX-bus
+accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples.
+The result is mixed to mono signal (single channel) and forwarded to
+the ??rear?? right DAC PCM slot of the AC97 codec.
+
+``name='Wave LFE Playback Volume',index=0``
+-------------------------------------------
+This control is used to attenuate samples for left and right PCM FX-bus
+accumulators. ALSA uses accumulators 0 and 1 for left and right PCM.
+The result is mixed to mono signal (single channel) and forwarded to
+the ??rear?? left DAC PCM slot of the AC97 codec.
+
+``name='Wave Capture Volume',index=0``, ``name='Wave Capture Switch',index=0``
+------------------------------------------------------------------------------
+These controls are used to attenuate samples for left and right PCM FX-bus
+accumulator. ALSA uses accumulators 0 and 1 for left and right PCM.
+The result is forwarded to the ADC capture FIFO (thus to the standard capture
+PCM device).
+
+``name='Synth Playback Volume',index=0``
+----------------------------------------
+This control is used to attenuate samples for left and right MIDI FX-bus
+accumulators. ALSA uses accumulators 4 and 5 for left and right MIDI samples.
+The result samples are forwarded to the front DAC PCM slots of the AC97 codec.
+
+``name='Synth Capture Volume',index=0``, ``name='Synth Capture Switch',index=0``
+--------------------------------------------------------------------------------
+These controls are used to attenuate samples for left and right MIDI FX-bus
+accumulator. ALSA uses accumulators 4 and 5 for left and right PCM.
+The result is forwarded to the ADC capture FIFO (thus to the standard capture
+PCM device).
+
+``name='Surround Playback Volume',index=0``
+-------------------------------------------
+This control is used to attenuate samples for left and right rear PCM FX-bus
+accumulators. ALSA uses accumulators 2 and 3 for left and right rear PCM samples.
+The result samples are forwarded to the rear I2S DACs. These DACs operate
+separately (they are not inside the AC97 codec).
+
+``name='Surround Capture Volume',index=0``, ``name='Surround Capture Switch',index=0``
+--------------------------------------------------------------------------------------
+These controls are used to attenuate samples for left and right rear PCM FX-bus
+accumulators. ALSA uses accumulators 2 and 3 for left and right rear PCM samples.
+The result is forwarded to the ADC capture FIFO (thus to the standard capture
+PCM device).
+
+``name='Center Playback Volume',index=0``
+-----------------------------------------
+This control is used to attenuate sample for center PCM FX-bus accumulator.
+ALSA uses accumulator 6 for center PCM sample. The result sample is forwarded
+to the ??rear?? right DAC PCM slot of the AC97 codec.
+
+``name='LFE Playback Volume',index=0``
+--------------------------------------
+This control is used to attenuate sample for center PCM FX-bus accumulator.
+ALSA uses accumulator 6 for center PCM sample. The result sample is forwarded
+to the ??rear?? left DAC PCM slot of the AC97 codec.
+
+``name='AC97 Playback Volume',index=0``
+---------------------------------------
+This control is used to attenuate samples for left and right front ADC PCM slots
+of the AC97 codec. The result samples are forwarded to the front DAC PCM
+slots of the AC97 codec.
+
+.. note::
+  This control should be zero for the standard operations, otherwise
+  a digital loopback is activated.
+
+
+``name='AC97 Capture Volume',index=0``
+--------------------------------------
+This control is used to attenuate samples for left and right front ADC PCM slots
+of the AC97 codec. The result is forwarded to the ADC capture FIFO (thus to
+the standard capture PCM device).
+
+.. note::
+   This control should be 100 (maximal value), otherwise no analog
+   inputs of the AC97 codec can be captured (recorded).
+
+``name='IEC958 TTL Playback Volume',index=0``
+---------------------------------------------
+This control is used to attenuate samples from left and right IEC958 TTL
+digital inputs (usually used by a CDROM drive). The result samples are
+forwarded to the front DAC PCM slots of the AC97 codec.
+
+``name='IEC958 TTL Capture Volume',index=0``
+--------------------------------------------
+This control is used to attenuate samples from left and right IEC958 TTL
+digital inputs (usually used by a CDROM drive). The result samples are
+forwarded to the ADC capture FIFO (thus to the standard capture PCM device).
+
+``name='Zoom Video Playback Volume',index=0``
+---------------------------------------------
+This control is used to attenuate samples from left and right zoom video
+digital inputs (usually used by a CDROM drive). The result samples are
+forwarded to the front DAC PCM slots of the AC97 codec.
+
+``name='Zoom Video Capture Volume',index=0``
+--------------------------------------------
+This control is used to attenuate samples from left and right zoom video
+digital inputs (usually used by a CDROM drive). The result samples are
+forwarded to the ADC capture FIFO (thus to the standard capture PCM device).
+
+``name='IEC958 LiveDrive Playback Volume',index=0``
+---------------------------------------------------
+This control is used to attenuate samples from left and right IEC958 optical
+digital input. The result samples are forwarded to the front DAC PCM slots
+of the AC97 codec.
+
+``name='IEC958 LiveDrive Capture Volume',index=0``
+--------------------------------------------------
+This control is used to attenuate samples from left and right IEC958 optical
+digital inputs. The result samples are forwarded to the ADC capture FIFO
+(thus to the standard capture PCM device).
+
+``name='IEC958 Coaxial Playback Volume',index=0``
+-------------------------------------------------
+This control is used to attenuate samples from left and right IEC958 coaxial
+digital inputs. The result samples are forwarded to the front DAC PCM slots
+of the AC97 codec.
+
+``name='IEC958 Coaxial Capture Volume',index=0``
+------------------------------------------------
+This control is used to attenuate samples from left and right IEC958 coaxial
+digital inputs. The result samples are forwarded to the ADC capture FIFO
+(thus to the standard capture PCM device).
+
+``name='Line LiveDrive Playback Volume',index=0``, ``name='Line LiveDrive Playback Volume',index=1``
+----------------------------------------------------------------------------------------------------
+This control is used to attenuate samples from left and right I2S ADC
+inputs (on the LiveDrive). The result samples are forwarded to the front
+DAC PCM slots of the AC97 codec.
+
+``name='Line LiveDrive Capture Volume',index=1``, ``name='Line LiveDrive Capture Volume',index=1``
+--------------------------------------------------------------------------------------------------
+This control is used to attenuate samples from left and right I2S ADC
+inputs (on the LiveDrive). The result samples are forwarded to the ADC
+capture FIFO (thus to the standard capture PCM device).
+
+``name='Tone Control - Switch',index=0``
+----------------------------------------
+This control turns the tone control on or off. The samples for front, rear
+and center / LFE outputs are affected.
+
+``name='Tone Control - Bass',index=0``
+--------------------------------------
+This control sets the bass intensity. There is no neutral value!!
+When the tone control code is activated, the samples are always modified.
+The closest value to pure signal is 20.
+
+``name='Tone Control - Treble',index=0``
+----------------------------------------
+This control sets the treble intensity. There is no neutral value!!
+When the tone control code is activated, the samples are always modified.
+The closest value to pure signal is 20.
+
+``name='IEC958 Optical Raw Playback Switch',index=0``
+-----------------------------------------------------
+If this switch is on, then the samples for the IEC958 (S/PDIF) digital
+output are taken only from the raw FX8010 PCM, otherwise standard front
+PCM samples are taken.
+
+``name='Headphone Playback Volume',index=1``
+--------------------------------------------
+This control attenuates the samples for the headphone output.
+
+``name='Headphone Center Playback Switch',index=1``
+---------------------------------------------------
+If this switch is on, then the sample for the center PCM is put to the
+left headphone output (useful for SB Live cards without separate center/LFE
+output).
+
+``name='Headphone LFE Playback Switch',index=1``
+------------------------------------------------
+If this switch is on, then the sample for the center PCM is put to the
+right headphone output (useful for SB Live cards without separate center/LFE
+output).
+
+
+PCM stream related controls
+===========================
+
+``name='EMU10K1 PCM Volume',index 0-31``
+----------------------------------------
+Channel volume attenuation in range 0-0xffff. The maximum value (no
+attenuation) is default. The channel mapping for three values is
+as follows:
+
+* 0 - mono, default 0xffff (no attenuation)
+* 1 - left, default 0xffff (no attenuation)
+* 2 - right, default 0xffff (no attenuation)
+
+``name='EMU10K1 PCM Send Routing',index 0-31``
+----------------------------------------------
+This control specifies the destination - FX-bus accumulators. There are
+twelve values with this mapping:
+
+*  0 -  mono, A destination (FX-bus 0-15), default 0
+*  1 -  mono, B destination (FX-bus 0-15), default 1
+*  2 -  mono, C destination (FX-bus 0-15), default 2
+*  3 -  mono, D destination (FX-bus 0-15), default 3
+*  4 -  left, A destination (FX-bus 0-15), default 0
+*  5 -  left, B destination (FX-bus 0-15), default 1
+*  6 -  left, C destination (FX-bus 0-15), default 2
+*  7 -  left, D destination (FX-bus 0-15), default 3
+*  8 - right, A destination (FX-bus 0-15), default 0
+*  9 - right, B destination (FX-bus 0-15), default 1
+* 10 - right, C destination (FX-bus 0-15), default 2
+* 11 - right, D destination (FX-bus 0-15), default 3
+
+Don't forget that it's illegal to assign a channel to the same FX-bus accumulator 
+more than once (it means 0=0 && 1=0 is an invalid combination).
+ 
+``name='EMU10K1 PCM Send Volume',index 0-31``
+---------------------------------------------
+It specifies the attenuation (amount) for given destination in range 0-255.
+The channel mapping is following:
+
+*  0 -  mono, A destination attn, default 255 (no attenuation)
+*  1 -  mono, B destination attn, default 255 (no attenuation)
+*  2 -  mono, C destination attn, default 0 (mute)
+*  3 -  mono, D destination attn, default 0 (mute)
+*  4 -  left, A destination attn, default 255 (no attenuation)
+*  5 -  left, B destination attn, default 0 (mute)
+*  6 -  left, C destination attn, default 0 (mute)
+*  7 -  left, D destination attn, default 0 (mute)
+*  8 - right, A destination attn, default 0 (mute)
+*  9 - right, B destination attn, default 255 (no attenuation)
+* 10 - right, C destination attn, default 0 (mute)
+* 11 - right, D destination attn, default 0 (mute)
+
+
+
+MANUALS/PATENTS
+===============
+
+ftp://opensource.creative.com/pub/doc
+-------------------------------------
+
+LM4545.pdf
+	AC97 Codec
+m2049.pdf
+	The EMU10K1 Digital Audio Processor
+hog63.ps
+	FX8010 - A DSP Chip Architecture for Audio Effects
+
+
+WIPO Patents
+------------
+
+WO 9901813 (A1)
+	Audio Effects Processor with multiple asynchronous streams
+	(Jan. 14, 1999)
+
+WO 9901814 (A1)
+	Processor with Instruction Set for Audio Effects (Jan. 14, 1999)
+
+WO 9901953 (A1)
+	Audio Effects Processor having Decoupled Instruction
+        Execution and Audio Data Sequencing (Jan. 14, 1999)
+
+
+US Patents (http://www.uspto.gov/)
+----------------------------------
+
+US 5925841
+	Digital Sampling Instrument employing cache memory (Jul. 20, 1999)
+
+US 5928342
+	Audio Effects Processor integrated on a single chip
+        with a multiport memory onto which multiple asynchronous
+        digital sound samples can be concurrently loaded
+	(Jul. 27, 1999)
+
+US 5930158
+	Processor with Instruction Set for Audio Effects (Jul. 27, 1999)
+
+US 6032235
+	Memory initialization circuit (Tram) (Feb. 29, 2000)
+
+US 6138207
+	Interpolation looping of audio samples in cache connected to
+        system bus with prioritization and modification of bus transfers
+        in accordance with loop ends and minimum block sizes
+	(Oct. 24, 2000)
+
+US 6151670
+	Method for conserving memory storage using a
+        pool of  short term memory registers
+	(Nov. 21, 2000)
+
+US 6195715
+	Interrupt control for multiple programs communicating with
+        a common interrupt by associating programs to GP registers,
+        defining interrupt register, polling GP registers, and invoking
+        callback routine associated with defined interrupt register
+	(Feb. 27, 2001)
-- 
cgit v1.2.3


From 72e69166714bfa7bfafb7a06a8499de472299ab9 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 16:25:42 +0100
Subject: ALSA: doc: ReSTize Audigy-mixer.txt

Another simple conversion from a plain text file.
Put to cards subdirectory.

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/Audigy-mixer.txt  | 345 ---------------------------
 Documentation/sound/cards/audigy-mixer.rst | 368 +++++++++++++++++++++++++++++
 Documentation/sound/cards/index.rst        |   2 +
 3 files changed, 370 insertions(+), 345 deletions(-)
 delete mode 100644 Documentation/sound/alsa/Audigy-mixer.txt
 create mode 100644 Documentation/sound/cards/audigy-mixer.rst

diff --git a/Documentation/sound/alsa/Audigy-mixer.txt b/Documentation/sound/alsa/Audigy-mixer.txt
deleted file mode 100644
index 7f10dc6ff28c..000000000000
--- a/Documentation/sound/alsa/Audigy-mixer.txt
+++ /dev/null
@@ -1,345 +0,0 @@
-
-		Sound Blaster Audigy mixer / default DSP code
-		===========================================
-
-This is based on SB-Live-mixer.txt.
-
-The EMU10K2 chips have a DSP part which can be programmed to support 
-various ways of sample processing, which is described here.
-(This article does not deal with the overall functionality of the 
-EMU10K2 chips. See the manuals section for further details.)
-
-The ALSA driver programs this portion of chip by default code
-(can be altered later) which offers the following functionality:
-
-
-1) Digital mixer controls
--------------------------
-
-These controls are built using the DSP instructions. They offer extended
-functionality. Only the default build-in code in the ALSA driver is described
-here. Note that the controls work as attenuators: the maximum value is the 
-neutral position leaving the signal unchanged. Note that if the  same destination 
-is mentioned in multiple controls, the signal is accumulated and can be wrapped 
-(set to maximal or minimal value without checking of overflow).
-
-
-Explanation of used abbreviations:
-
-DAC    - digital to analog converter
-ADC    - analog to digital converter
-I2S    - one-way three wire serial bus for digital sound by Philips Semiconductors
-         (this standard is used for connecting standalone DAC and ADC converters)
-LFE    - low frequency effects (subwoofer signal)
-AC97   - a chip containing an analog mixer, DAC and ADC converters
-IEC958 - S/PDIF
-FX-bus - the EMU10K2 chip has an effect bus containing 64 accumulators.
-         Each of the synthesizer voices can feed its output to these accumulators
-         and the DSP microcontroller can operate with the resulting sum.
-
-name='PCM Front Playback Volume',index=0
-
-This control is used to attenuate samples for left and right front PCM FX-bus
-accumulators. ALSA uses accumulators 8 and 9 for left and right front PCM 
-samples for 5.1 playback. The result samples are forwarded to the front DAC PCM 
-slots of the Philips DAC.
-
-name='PCM Surround Playback Volume',index=0
-
-This control is used to attenuate samples for left and right surround PCM FX-bus
-accumulators. ALSA uses accumulators 2 and 3 for left and right surround PCM 
-samples for 5.1 playback. The result samples are forwarded to the surround DAC PCM 
-slots of the Philips DAC.
-
-name='PCM Center Playback Volume',index=0
-
-This control is used to attenuate samples for center PCM FX-bus accumulator.
-ALSA uses accumulator 6 for center PCM sample for 5.1 playback. The result sample
-is forwarded to the center DAC PCM slot of the Philips DAC.
-
-name='PCM LFE Playback Volume',index=0
-
-This control is used to attenuate sample for LFE PCM FX-bus accumulator. 
-ALSA uses accumulator 7 for LFE PCM sample for 5.1 playback. The result sample 
-is forwarded to the LFE DAC PCM slot of the Philips DAC.
-
-name='PCM Playback Volume',index=0
-
-This control is used to attenuate samples for left and right PCM FX-bus
-accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples for
-stereo playback. The result samples are forwarded to the front DAC PCM slots 
-of the Philips DAC.
-
-name='PCM Capture Volume',index=0
-
-This control is used to attenuate samples for left and right PCM FX-bus
-accumulator. ALSA uses accumulators 0 and 1 for left and right PCM.
-The result is forwarded to the ADC capture FIFO (thus to the standard capture
-PCM device).
-
-name='Music Playback Volume',index=0
-
-This control is used to attenuate samples for left and right MIDI FX-bus
-accumulators. ALSA uses accumulators 4 and 5 for left and right MIDI samples.
-The result samples are forwarded to the front DAC PCM slots of the AC97 codec.
-
-name='Music Capture Volume',index=0
-
-These controls are used to attenuate samples for left and right MIDI FX-bus
-accumulator. ALSA uses accumulators 4 and 5 for left and right PCM.
-The result is forwarded to the ADC capture FIFO (thus to the standard capture
-PCM device).
-
-name='Mic Playback Volume',index=0
-
-This control is used to attenuate samples for left and right Mic input.
-For Mic input is used AC97 codec. The result samples are forwarded to 
-the front DAC PCM slots of the Philips DAC. Samples are forwarded to Mic
-capture FIFO (device 1 - 16bit/8KHz mono) too without volume control.
-
-name='Mic Capture Volume',index=0
-
-This control is used to attenuate samples for left and right Mic input.
-The result is forwarded to the ADC capture FIFO (thus to the standard capture
-PCM device).
-
-name='Audigy CD Playback Volume',index=0
-
-This control is used to attenuate samples from left and right IEC958 TTL
-digital inputs (usually used by a CDROM drive). The result samples are
-forwarded to the front DAC PCM slots of the Philips DAC.
-
-name='Audigy CD Capture Volume',index=0
-
-This control is used to attenuate samples from left and right IEC958 TTL
-digital inputs (usually used by a CDROM drive). The result samples are
-forwarded to the ADC capture FIFO (thus to the standard capture PCM device).
-
-name='IEC958 Optical Playback Volume',index=0
-
-This control is used to attenuate samples from left and right IEC958 optical
-digital input. The result samples are forwarded to the front DAC PCM slots
-of the Philips DAC.
-
-name='IEC958 Optical Capture Volume',index=0
-
-This control is used to attenuate samples from left and right IEC958 optical
-digital inputs. The result samples are forwarded to the ADC capture FIFO
-(thus to the standard capture PCM device).
-
-name='Line2 Playback Volume',index=0
-
-This control is used to attenuate samples from left and right I2S ADC
-inputs (on the AudigyDrive). The result samples are forwarded to the front
-DAC PCM slots of the Philips DAC.
-
-name='Line2 Capture Volume',index=1
-
-This control is used to attenuate samples from left and right I2S ADC
-inputs (on the AudigyDrive). The result samples are forwarded to the ADC
-capture FIFO (thus to the standard capture PCM device).
-
-name='Analog Mix Playback Volume',index=0
-
-This control is used to attenuate samples from left and right I2S ADC
-inputs from Philips ADC. The result samples are forwarded to the front
-DAC PCM slots of the Philips DAC. This contains mix from analog sources
-like CD, Line In, Aux, ....
-
-name='Analog Mix Capture Volume',index=1
-
-This control is used to attenuate samples from left and right I2S ADC
-inputs Philips ADC. The result samples are forwarded to the ADC
-capture FIFO (thus to the standard capture PCM device).
-
-name='Aux2 Playback Volume',index=0
-
-This control is used to attenuate samples from left and right I2S ADC
-inputs (on the AudigyDrive). The result samples are forwarded to the front
-DAC PCM slots of the Philips DAC.
-
-name='Aux2 Capture Volume',index=1
-
-This control is used to attenuate samples from left and right I2S ADC
-inputs (on the AudigyDrive). The result samples are forwarded to the ADC
-capture FIFO (thus to the standard capture PCM device).
-
-name='Front Playback Volume',index=0
-
-All stereo signals are mixed together and mirrored to surround, center and LFE.
-This control is used to attenuate samples for left and right front speakers of
-this mix.
-
-name='Surround Playback Volume',index=0
-
-All stereo signals are mixed together and mirrored to surround, center and LFE.
-This control is used to attenuate samples for left and right surround speakers of
-this mix.
-
-name='Center Playback Volume',index=0
-
-All stereo signals are mixed together and mirrored to surround, center and LFE.
-This control is used to attenuate sample for center speaker of this mix.
-
-name='LFE Playback Volume',index=0
-
-All stereo signals are mixed together and mirrored to surround, center and LFE.
-This control is used to attenuate sample for LFE speaker of this mix.
-
-name='Tone Control - Switch',index=0
-
-This control turns the tone control on or off. The samples for front, rear
-and center / LFE outputs are affected.
-
-name='Tone Control - Bass',index=0
-
-This control sets the bass intensity. There is no neutral value!!
-When the tone control code is activated, the samples are always modified.
-The closest value to pure signal is 20.
-
-name='Tone Control - Treble',index=0
-
-This control sets the treble intensity. There is no neutral value!!
-When the tone control code is activated, the samples are always modified.
-The closest value to pure signal is 20.
-
-name='Master Playback Volume',index=0
-
-This control is used to attenuate samples for front, surround, center and 
-LFE outputs.
-
-name='IEC958 Optical Raw Playback Switch',index=0
-
-If this switch is on, then the samples for the IEC958 (S/PDIF) digital
-output are taken only from the raw FX8010 PCM, otherwise standard front
-PCM samples are taken.
-
-
-2) PCM stream related controls
-------------------------------
-
-name='EMU10K1 PCM Volume',index 0-31
-
-Channel volume attenuation in range 0-0xffff. The maximum value (no
-attenuation) is default. The channel mapping for three values is
-as follows:
-
-	0 - mono, default 0xffff (no attenuation)
-	1 - left, default 0xffff (no attenuation)
-	2 - right, default 0xffff (no attenuation)
-
-name='EMU10K1 PCM Send Routing',index 0-31
-
-This control specifies the destination - FX-bus accumulators. There 24
-values with this mapping:
-
-	 0 -  mono, A destination (FX-bus 0-63), default 0
-	 1 -  mono, B destination (FX-bus 0-63), default 1
-	 2 -  mono, C destination (FX-bus 0-63), default 2
-	 3 -  mono, D destination (FX-bus 0-63), default 3
-	 4 -  mono, E destination (FX-bus 0-63), default 0
-	 5 -  mono, F destination (FX-bus 0-63), default 0
-	 6 -  mono, G destination (FX-bus 0-63), default 0
-	 7 -  mono, H destination (FX-bus 0-63), default 0
-	 8 -  left, A destination (FX-bus 0-63), default 0
-	 9 -  left, B destination (FX-bus 0-63), default 1
-	10 -  left, C destination (FX-bus 0-63), default 2
-	11 -  left, D destination (FX-bus 0-63), default 3
-	12 -  left, E destination (FX-bus 0-63), default 0
-	13 -  left, F destination (FX-bus 0-63), default 0
-	14 -  left, G destination (FX-bus 0-63), default 0
-	15 -  left, H destination (FX-bus 0-63), default 0
-	16 - right, A destination (FX-bus 0-63), default 0
-	17 - right, B destination (FX-bus 0-63), default 1
-	18 - right, C destination (FX-bus 0-63), default 2
-	19 - right, D destination (FX-bus 0-63), default 3
-	20 - right, E destination (FX-bus 0-63), default 0
-	21 - right, F destination (FX-bus 0-63), default 0
-	22 - right, G destination (FX-bus 0-63), default 0
-	23 - right, H destination (FX-bus 0-63), default 0
-
-Don't forget that it's illegal to assign a channel to the same FX-bus accumulator 
-more than once (it means 0=0 && 1=0 is an invalid combination).
- 
-name='EMU10K1 PCM Send Volume',index 0-31
-
-It specifies the attenuation (amount) for given destination in range 0-255.
-The channel mapping is following:
-
-	 0 -  mono, A destination attn, default 255 (no attenuation)
-	 1 -  mono, B destination attn, default 255 (no attenuation)
-	 2 -  mono, C destination attn, default 0 (mute)
-	 3 -  mono, D destination attn, default 0 (mute)
-	 4 -  mono, E destination attn, default 0 (mute)
-	 5 -  mono, F destination attn, default 0 (mute)
-	 6 -  mono, G destination attn, default 0 (mute)
-	 7 -  mono, H destination attn, default 0 (mute)
-	 8 -  left, A destination attn, default 255 (no attenuation)
-	 9 -  left, B destination attn, default 0 (mute)
-	10 -  left, C destination attn, default 0 (mute)
-	11 -  left, D destination attn, default 0 (mute)
-	12 -  left, E destination attn, default 0 (mute)
-	13 -  left, F destination attn, default 0 (mute)
-	14 -  left, G destination attn, default 0 (mute)
-	15 -  left, H destination attn, default 0 (mute)
-	16 - right, A destination attn, default 0 (mute)
-	17 - right, B destination attn, default 255 (no attenuation)
-	18 - right, C destination attn, default 0 (mute)
-	19 - right, D destination attn, default 0 (mute)
-	20 - right, E destination attn, default 0 (mute)
-	21 - right, F destination attn, default 0 (mute)
-	22 - right, G destination attn, default 0 (mute)
-	23 - right, H destination attn, default 0 (mute)
-
-
-
-4) MANUALS/PATENTS:
--------------------
-
-ftp://opensource.creative.com/pub/doc
--------------------------------------
-
-        Files:
-        LM4545.pdf      AC97 Codec
-
-        m2049.pdf       The EMU10K1 Digital Audio Processor
-
-        hog63.ps        FX8010 - A DSP Chip Architecture for Audio Effects
-
-
-WIPO Patents
-------------
-        Patent numbers:
-        WO 9901813 (A1) Audio Effects Processor with multiple asynchronous (Jan. 14, 1999)
-                        streams
-
-        WO 9901814 (A1) Processor with Instruction Set for Audio Effects (Jan. 14, 1999)
-
-        WO 9901953 (A1) Audio Effects Processor having Decoupled Instruction
-                        Execution and Audio Data Sequencing (Jan. 14, 1999)
-
-
-US Patents (http://www.uspto.gov/)
-----------------------------------
-
-        US 5925841      Digital Sampling Instrument employing cache memory (Jul. 20, 1999)
-
-        US 5928342      Audio Effects Processor integrated on a single chip (Jul. 27, 1999)
-                        with a multiport memory onto which multiple asynchronous
-                        digital sound samples can be concurrently loaded
-
-        US 5930158      Processor with Instruction Set for Audio Effects (Jul. 27, 1999)
-
-        US 6032235      Memory initialization circuit (Tram) (Feb. 29, 2000)
-
-        US 6138207      Interpolation looping of audio samples in cache connected to    (Oct. 24, 2000)
-                        system bus with prioritization and modification of bus transfers
-                        in accordance with loop ends and minimum block sizes
-
-        US 6151670      Method for conserving memory storage using a (Nov. 21, 2000)
-                        pool of  short term memory registers
-
-        US 6195715      Interrupt control for multiple programs communicating with      (Feb. 27, 2001)
-                        a common interrupt by associating programs to GP registers,
-                        defining interrupt register, polling GP registers, and invoking
-                        callback routine associated with defined interrupt register
diff --git a/Documentation/sound/cards/audigy-mixer.rst b/Documentation/sound/cards/audigy-mixer.rst
new file mode 100644
index 000000000000..86213234435f
--- /dev/null
+++ b/Documentation/sound/cards/audigy-mixer.rst
@@ -0,0 +1,368 @@
+=============================================
+Sound Blaster Audigy mixer / default DSP code
+=============================================
+
+This is based on sb-live-mixer.rst.
+
+The EMU10K2 chips have a DSP part which can be programmed to support 
+various ways of sample processing, which is described here.
+(This article does not deal with the overall functionality of the 
+EMU10K2 chips. See the manuals section for further details.)
+
+The ALSA driver programs this portion of chip by default code
+(can be altered later) which offers the following functionality:
+
+
+Digital mixer controls
+======================
+
+These controls are built using the DSP instructions. They offer extended
+functionality. Only the default build-in code in the ALSA driver is described
+here. Note that the controls work as attenuators: the maximum value is the 
+neutral position leaving the signal unchanged. Note that if the  same destination 
+is mentioned in multiple controls, the signal is accumulated and can be wrapped 
+(set to maximal or minimal value without checking of overflow).
+
+
+Explanation of used abbreviations:
+
+DAC
+	digital to analog converter
+ADC
+	analog to digital converter
+I2S
+	one-way three wire serial bus for digital sound by Philips Semiconductors
+        (this standard is used for connecting standalone DAC and ADC converters)
+LFE
+	low frequency effects (subwoofer signal)
+AC97
+	a chip containing an analog mixer, DAC and ADC converters
+IEC958
+	S/PDIF
+FX-bus
+	the EMU10K2 chip has an effect bus containing 64 accumulators.
+        Each of the synthesizer voices can feed its output to these accumulators
+        and the DSP microcontroller can operate with the resulting sum.
+
+name='PCM Front Playback Volume',index=0
+----------------------------------------
+This control is used to attenuate samples for left and right front PCM FX-bus
+accumulators. ALSA uses accumulators 8 and 9 for left and right front PCM 
+samples for 5.1 playback. The result samples are forwarded to the front DAC PCM 
+slots of the Philips DAC.
+
+name='PCM Surround Playback Volume',index=0
+-------------------------------------------
+This control is used to attenuate samples for left and right surround PCM FX-bus
+accumulators. ALSA uses accumulators 2 and 3 for left and right surround PCM 
+samples for 5.1 playback. The result samples are forwarded to the surround DAC PCM 
+slots of the Philips DAC.
+
+name='PCM Center Playback Volume',index=0
+-----------------------------------------
+This control is used to attenuate samples for center PCM FX-bus accumulator.
+ALSA uses accumulator 6 for center PCM sample for 5.1 playback. The result sample
+is forwarded to the center DAC PCM slot of the Philips DAC.
+
+name='PCM LFE Playback Volume',index=0
+--------------------------------------
+This control is used to attenuate sample for LFE PCM FX-bus accumulator. 
+ALSA uses accumulator 7 for LFE PCM sample for 5.1 playback. The result sample 
+is forwarded to the LFE DAC PCM slot of the Philips DAC.
+
+name='PCM Playback Volume',index=0
+----------------------------------
+This control is used to attenuate samples for left and right PCM FX-bus
+accumulators. ALSA uses accumulators 0 and 1 for left and right PCM samples for
+stereo playback. The result samples are forwarded to the front DAC PCM slots 
+of the Philips DAC.
+
+name='PCM Capture Volume',index=0
+---------------------------------
+This control is used to attenuate samples for left and right PCM FX-bus
+accumulator. ALSA uses accumulators 0 and 1 for left and right PCM.
+The result is forwarded to the ADC capture FIFO (thus to the standard capture
+PCM device).
+
+name='Music Playback Volume',index=0
+------------------------------------
+This control is used to attenuate samples for left and right MIDI FX-bus
+accumulators. ALSA uses accumulators 4 and 5 for left and right MIDI samples.
+The result samples are forwarded to the front DAC PCM slots of the AC97 codec.
+
+name='Music Capture Volume',index=0
+-----------------------------------
+These controls are used to attenuate samples for left and right MIDI FX-bus
+accumulator. ALSA uses accumulators 4 and 5 for left and right PCM.
+The result is forwarded to the ADC capture FIFO (thus to the standard capture
+PCM device).
+
+name='Mic Playback Volume',index=0
+----------------------------------
+This control is used to attenuate samples for left and right Mic input.
+For Mic input is used AC97 codec. The result samples are forwarded to 
+the front DAC PCM slots of the Philips DAC. Samples are forwarded to Mic
+capture FIFO (device 1 - 16bit/8KHz mono) too without volume control.
+
+name='Mic Capture Volume',index=0
+---------------------------------
+This control is used to attenuate samples for left and right Mic input.
+The result is forwarded to the ADC capture FIFO (thus to the standard capture
+PCM device).
+
+name='Audigy CD Playback Volume',index=0
+----------------------------------------
+This control is used to attenuate samples from left and right IEC958 TTL
+digital inputs (usually used by a CDROM drive). The result samples are
+forwarded to the front DAC PCM slots of the Philips DAC.
+
+name='Audigy CD Capture Volume',index=0
+---------------------------------------
+This control is used to attenuate samples from left and right IEC958 TTL
+digital inputs (usually used by a CDROM drive). The result samples are
+forwarded to the ADC capture FIFO (thus to the standard capture PCM device).
+
+name='IEC958 Optical Playback Volume',index=0
+---------------------------------------------
+This control is used to attenuate samples from left and right IEC958 optical
+digital input. The result samples are forwarded to the front DAC PCM slots
+of the Philips DAC.
+
+name='IEC958 Optical Capture Volume',index=0
+--------------------------------------------
+This control is used to attenuate samples from left and right IEC958 optical
+digital inputs. The result samples are forwarded to the ADC capture FIFO
+(thus to the standard capture PCM device).
+
+name='Line2 Playback Volume',index=0
+------------------------------------
+This control is used to attenuate samples from left and right I2S ADC
+inputs (on the AudigyDrive). The result samples are forwarded to the front
+DAC PCM slots of the Philips DAC.
+
+name='Line2 Capture Volume',index=1
+-----------------------------------
+This control is used to attenuate samples from left and right I2S ADC
+inputs (on the AudigyDrive). The result samples are forwarded to the ADC
+capture FIFO (thus to the standard capture PCM device).
+
+name='Analog Mix Playback Volume',index=0
+-----------------------------------------
+This control is used to attenuate samples from left and right I2S ADC
+inputs from Philips ADC. The result samples are forwarded to the front
+DAC PCM slots of the Philips DAC. This contains mix from analog sources
+like CD, Line In, Aux, ....
+
+name='Analog Mix Capture Volume',index=1
+----------------------------------------
+This control is used to attenuate samples from left and right I2S ADC
+inputs Philips ADC. The result samples are forwarded to the ADC
+capture FIFO (thus to the standard capture PCM device).
+
+name='Aux2 Playback Volume',index=0
+-----------------------------------
+This control is used to attenuate samples from left and right I2S ADC
+inputs (on the AudigyDrive). The result samples are forwarded to the front
+DAC PCM slots of the Philips DAC.
+
+name='Aux2 Capture Volume',index=1
+----------------------------------
+This control is used to attenuate samples from left and right I2S ADC
+inputs (on the AudigyDrive). The result samples are forwarded to the ADC
+capture FIFO (thus to the standard capture PCM device).
+
+name='Front Playback Volume',index=0
+------------------------------------
+All stereo signals are mixed together and mirrored to surround, center and LFE.
+This control is used to attenuate samples for left and right front speakers of
+this mix.
+
+name='Surround Playback Volume',index=0
+---------------------------------------
+All stereo signals are mixed together and mirrored to surround, center and LFE.
+This control is used to attenuate samples for left and right surround speakers of
+this mix.
+
+name='Center Playback Volume',index=0
+-------------------------------------
+All stereo signals are mixed together and mirrored to surround, center and LFE.
+This control is used to attenuate sample for center speaker of this mix.
+
+name='LFE Playback Volume',index=0
+----------------------------------
+All stereo signals are mixed together and mirrored to surround, center and LFE.
+This control is used to attenuate sample for LFE speaker of this mix.
+
+name='Tone Control - Switch',index=0
+------------------------------------
+This control turns the tone control on or off. The samples for front, rear
+and center / LFE outputs are affected.
+
+name='Tone Control - Bass',index=0
+----------------------------------
+This control sets the bass intensity. There is no neutral value!!
+When the tone control code is activated, the samples are always modified.
+The closest value to pure signal is 20.
+
+name='Tone Control - Treble',index=0
+------------------------------------
+This control sets the treble intensity. There is no neutral value!!
+When the tone control code is activated, the samples are always modified.
+The closest value to pure signal is 20.
+
+name='Master Playback Volume',index=0
+-------------------------------------
+This control is used to attenuate samples for front, surround, center and 
+LFE outputs.
+
+name='IEC958 Optical Raw Playback Switch',index=0
+-------------------------------------------------
+If this switch is on, then the samples for the IEC958 (S/PDIF) digital
+output are taken only from the raw FX8010 PCM, otherwise standard front
+PCM samples are taken.
+
+
+PCM stream related controls
+===========================
+
+name='EMU10K1 PCM Volume',index 0-31
+------------------------------------
+Channel volume attenuation in range 0-0xffff. The maximum value (no
+attenuation) is default. The channel mapping for three values is
+as follows:
+
+* 0 - mono, default 0xffff (no attenuation)
+* 1 - left, default 0xffff (no attenuation)
+* 2 - right, default 0xffff (no attenuation)
+
+name='EMU10K1 PCM Send Routing',index 0-31
+------------------------------------------
+This control specifies the destination - FX-bus accumulators. There 24
+values with this mapping:
+
+* 0 -  mono, A destination (FX-bus 0-63), default 0
+* 1 -  mono, B destination (FX-bus 0-63), default 1
+* 2 -  mono, C destination (FX-bus 0-63), default 2
+* 3 -  mono, D destination (FX-bus 0-63), default 3
+* 4 -  mono, E destination (FX-bus 0-63), default 0
+* 5 -  mono, F destination (FX-bus 0-63), default 0
+* 6 -  mono, G destination (FX-bus 0-63), default 0
+* 7 -  mono, H destination (FX-bus 0-63), default 0
+* 8 -  left, A destination (FX-bus 0-63), default 0
+* 9 -  left, B destination (FX-bus 0-63), default 1
+* 10 -  left, C destination (FX-bus 0-63), default 2
+* 11 -  left, D destination (FX-bus 0-63), default 3
+* 12 -  left, E destination (FX-bus 0-63), default 0
+* 13 -  left, F destination (FX-bus 0-63), default 0
+* 14 -  left, G destination (FX-bus 0-63), default 0
+* 15 -  left, H destination (FX-bus 0-63), default 0
+* 16 - right, A destination (FX-bus 0-63), default 0
+* 17 - right, B destination (FX-bus 0-63), default 1
+* 18 - right, C destination (FX-bus 0-63), default 2
+* 19 - right, D destination (FX-bus 0-63), default 3
+* 20 - right, E destination (FX-bus 0-63), default 0
+* 21 - right, F destination (FX-bus 0-63), default 0
+* 22 - right, G destination (FX-bus 0-63), default 0
+* 23 - right, H destination (FX-bus 0-63), default 0
+
+Don't forget that it's illegal to assign a channel to the same FX-bus accumulator 
+more than once (it means 0=0 && 1=0 is an invalid combination).
+ 
+name='EMU10K1 PCM Send Volume',index 0-31
+-----------------------------------------
+It specifies the attenuation (amount) for given destination in range 0-255.
+The channel mapping is following:
+
+*  0 -  mono, A destination attn, default 255 (no attenuation)
+*  1 -  mono, B destination attn, default 255 (no attenuation)
+*  2 -  mono, C destination attn, default 0 (mute)
+*  3 -  mono, D destination attn, default 0 (mute)
+*  4 -  mono, E destination attn, default 0 (mute)
+*  5 -  mono, F destination attn, default 0 (mute)
+*  6 -  mono, G destination attn, default 0 (mute)
+*  7 -  mono, H destination attn, default 0 (mute)
+*  8 -  left, A destination attn, default 255 (no attenuation)
+*  9 -  left, B destination attn, default 0 (mute)
+* 10 -  left, C destination attn, default 0 (mute)
+* 11 -  left, D destination attn, default 0 (mute)
+* 12 -  left, E destination attn, default 0 (mute)
+* 13 -  left, F destination attn, default 0 (mute)
+* 14 -  left, G destination attn, default 0 (mute)
+* 15 -  left, H destination attn, default 0 (mute)
+* 16 - right, A destination attn, default 0 (mute)
+* 17 - right, B destination attn, default 255 (no attenuation)
+* 18 - right, C destination attn, default 0 (mute)
+* 19 - right, D destination attn, default 0 (mute)
+* 20 - right, E destination attn, default 0 (mute)
+* 21 - right, F destination attn, default 0 (mute)
+* 22 - right, G destination attn, default 0 (mute)
+* 23 - right, H destination attn, default 0 (mute)
+
+
+
+MANUALS/PATENTS
+===============
+
+ftp://opensource.creative.com/pub/doc
+-------------------------------------
+
+LM4545.pdf
+	AC97 Codec
+
+m2049.pdf
+	The EMU10K1 Digital Audio Processor
+
+hog63.ps
+	FX8010 - A DSP Chip Architecture for Audio Effects
+
+
+WIPO Patents
+------------
+
+WO 9901813 (A1)
+	Audio Effects Processor with multiple asynchronous streams
+	(Jan. 14, 1999)
+
+WO 9901814 (A1)
+	Processor with Instruction Set for Audio Effects (Jan. 14, 1999)
+
+WO 9901953 (A1)
+	Audio Effects Processor having Decoupled Instruction
+        Execution and Audio Data Sequencing (Jan. 14, 1999)
+
+
+US Patents (http://www.uspto.gov/)
+----------------------------------
+
+US 5925841
+	Digital Sampling Instrument employing cache memory (Jul. 20, 1999)
+
+US 5928342
+	Audio Effects Processor integrated on a single chip
+        with a multiport memory onto which multiple asynchronous
+        digital sound samples can be concurrently loaded
+	(Jul. 27, 1999)
+
+US 5930158
+	Processor with Instruction Set for Audio Effects (Jul. 27, 1999)
+
+US 6032235
+	Memory initialization circuit (Tram) (Feb. 29, 2000)
+
+US 6138207
+	Interpolation looping of audio samples in cache connected to
+        system bus with prioritization and modification of bus transfers
+        in accordance with loop ends and minimum block sizes
+	(Oct. 24, 2000)
+
+US 6151670
+	Method for conserving memory storage using a
+        pool of  short term memory registers
+	(Nov. 21, 2000)
+
+US 6195715
+	Interrupt control for multiple programs communicating with
+        a common interrupt by associating programs to GP registers,
+        defining interrupt register, polling GP registers, and invoking
+        callback routine associated with defined interrupt register
+	(Feb. 27, 2001)
diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index 294efdb75bc9..c9d7ce4286b2 100644
--- a/Documentation/sound/cards/index.rst
+++ b/Documentation/sound/cards/index.rst
@@ -7,3 +7,5 @@ Card-Specific Information
    joystick
    cmipci
    sb-live-mixer
+   audigy-mixer
+  
-- 
cgit v1.2.3


From e7030c96fc0e08b9d1c4fb1cbedb326a3f46dad3 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 16:31:07 +0100
Subject: ALSA: doc: ReSTize emu10k1-jack.txt

Another simple conversion from a plain text file.
Put to cards directory.

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/emu10k1-jack.txt  | 74 ----------------------------
 Documentation/sound/cards/emu10k1-jack.rst | 78 ++++++++++++++++++++++++++++++
 Documentation/sound/cards/index.rst        |  2 +-
 3 files changed, 79 insertions(+), 75 deletions(-)
 delete mode 100644 Documentation/sound/alsa/emu10k1-jack.txt
 create mode 100644 Documentation/sound/cards/emu10k1-jack.rst

diff --git a/Documentation/sound/alsa/emu10k1-jack.txt b/Documentation/sound/alsa/emu10k1-jack.txt
deleted file mode 100644
index 751d45036a05..000000000000
--- a/Documentation/sound/alsa/emu10k1-jack.txt
+++ /dev/null
@@ -1,74 +0,0 @@
-This document is a guide to using the emu10k1 based devices with JACK for low
-latency, multichannel recording functionality.  All of my recent work to allow
-Linux users to use the full capabilities of their hardware has been inspired 
-by the kX Project.  Without their work I never would have discovered the true
-power of this hardware.
-
-	http://www.kxproject.com
-						- Lee Revell, 2005.03.30
-
-Low latency, multichannel audio with JACK and the emu10k1/emu10k2
------------------------------------------------------------------
-
-Until recently, emu10k1 users on Linux did not have access to the same low
-latency, multichannel features offered by the "kX ASIO" feature of their
-Windows driver.  As of ALSA 1.0.9 this is no more!
-
-For those unfamiliar with kX ASIO, this consists of 16 capture and 16 playback
-channels.  With a post 2.6.9 Linux kernel, latencies down to 64 (1.33 ms) or
-even 32 (0.66ms) frames should work well.
-
-The configuration is slightly more involved than on Windows, as you have to
-select the correct device for JACK to use.  Actually, for qjackctl users it's
-fairly self explanatory - select Duplex, then for capture and playback select
-the multichannel devices, set the in and out channels to 16, and the sample
-rate to 48000Hz.  The command line looks like this:
-
-/usr/local/bin/jackd -R -dalsa -r48000 -p64 -n2 -D -Chw:0,2 -Phw:0,3 -S
-
-This will give you 16 input ports and 16 output ports.
-
-The 16 output ports map onto the 16 FX buses (or the first 16 of 64, for the
-Audigy).  The mapping from FX bus to physical output is described in
-SB-Live-mixer.txt (or Audigy-mixer.txt).
-
-The 16 input ports are connected to the 16 physical inputs.  Contrary to
-popular belief, all emu10k1 cards are multichannel cards.  Which of these
-input channels have physical inputs connected to them depends on the card
-model.  Trial and error is highly recommended; the pinout diagrams
-for the card have been reverse engineered by some enterprising kX users and are 
-available on the internet.  Meterbridge is helpful here, and the kX forums are
-packed with useful information.
-
-Each input port will either correspond to a digital (SPDIF) input, an analog
-input, or nothing.  The one exception is the SBLive! 5.1.  On these devices,
-the second and third input ports are wired to the center/LFE output.  You will
-still see 16 capture channels, but only 14 are available for recording inputs.
-
-This chart, borrowed from kxfxlib/da_asio51.cpp, describes the mapping of JACK
-ports to FXBUS2 (multitrack recording input) and EXTOUT (physical output)
-channels.
-
-/*JACK (& ASIO) mappings on 10k1 5.1 SBLive cards:
---------------------------------------------
-JACK		Epilog		FXBUS2(nr)
---------------------------------------------
-capture_1	asio14		FXBUS2(0xe)
-capture_2	asio15		FXBUS2(0xf)
-capture_3	asio0		FXBUS2(0x0)	
-~capture_4	Center		EXTOUT(0x11)	// mapped to by Center
-~capture_5	LFE		EXTOUT(0x12)	// mapped to by LFE
-capture_6	asio3		FXBUS2(0x3)
-capture_7	asio4		FXBUS2(0x4)
-capture_8	asio5		FXBUS2(0x5)
-capture_9	asio6		FXBUS2(0x6)
-capture_10	asio7		FXBUS2(0x7)
-capture_11	asio8		FXBUS2(0x8)
-capture_12	asio9		FXBUS2(0x9)
-capture_13	asio10		FXBUS2(0xa)
-capture_14	asio11		FXBUS2(0xb)
-capture_15	asio12		FXBUS2(0xc)
-capture_16	asio13		FXBUS2(0xd)
-*/
-
-TODO: describe use of ld10k1/qlo10k1 in conjunction with JACK
diff --git a/Documentation/sound/cards/emu10k1-jack.rst b/Documentation/sound/cards/emu10k1-jack.rst
new file mode 100644
index 000000000000..6597f1ea83f0
--- /dev/null
+++ b/Documentation/sound/cards/emu10k1-jack.rst
@@ -0,0 +1,78 @@
+=================================================================
+Low latency, multichannel audio with JACK and the emu10k1/emu10k2
+=================================================================
+
+This document is a guide to using the emu10k1 based devices with JACK for low
+latency, multichannel recording functionality.  All of my recent work to allow
+Linux users to use the full capabilities of their hardware has been inspired 
+by the kX Project.  Without their work I never would have discovered the true
+power of this hardware.
+
+	http://www.kxproject.com
+						- Lee Revell, 2005.03.30
+
+
+Until recently, emu10k1 users on Linux did not have access to the same low
+latency, multichannel features offered by the "kX ASIO" feature of their
+Windows driver.  As of ALSA 1.0.9 this is no more!
+
+For those unfamiliar with kX ASIO, this consists of 16 capture and 16 playback
+channels.  With a post 2.6.9 Linux kernel, latencies down to 64 (1.33 ms) or
+even 32 (0.66ms) frames should work well.
+
+The configuration is slightly more involved than on Windows, as you have to
+select the correct device for JACK to use.  Actually, for qjackctl users it's
+fairly self explanatory - select Duplex, then for capture and playback select
+the multichannel devices, set the in and out channels to 16, and the sample
+rate to 48000Hz.  The command line looks like this:
+::
+
+  /usr/local/bin/jackd -R -dalsa -r48000 -p64 -n2 -D -Chw:0,2 -Phw:0,3 -S
+
+This will give you 16 input ports and 16 output ports.
+
+The 16 output ports map onto the 16 FX buses (or the first 16 of 64, for the
+Audigy).  The mapping from FX bus to physical output is described in
+sb-live-mixer.rst (or audigy-mixer.rst).
+
+The 16 input ports are connected to the 16 physical inputs.  Contrary to
+popular belief, all emu10k1 cards are multichannel cards.  Which of these
+input channels have physical inputs connected to them depends on the card
+model.  Trial and error is highly recommended; the pinout diagrams
+for the card have been reverse engineered by some enterprising kX users and are 
+available on the internet.  Meterbridge is helpful here, and the kX forums are
+packed with useful information.
+
+Each input port will either correspond to a digital (SPDIF) input, an analog
+input, or nothing.  The one exception is the SBLive! 5.1.  On these devices,
+the second and third input ports are wired to the center/LFE output.  You will
+still see 16 capture channels, but only 14 are available for recording inputs.
+
+This chart, borrowed from kxfxlib/da_asio51.cpp, describes the mapping of JACK
+ports to FXBUS2 (multitrack recording input) and EXTOUT (physical output)
+channels.
+
+JACK (& ASIO) mappings on 10k1 5.1 SBLive cards:
+
+==============  ========        ============
+JACK		Epilog		FXBUS2(nr)
+==============  ========        ============
+capture_1	asio14		FXBUS2(0xe)
+capture_2	asio15		FXBUS2(0xf)
+capture_3	asio0		FXBUS2(0x0)	
+~capture_4	Center		EXTOUT(0x11)	// mapped to by Center
+~capture_5	LFE		EXTOUT(0x12)	// mapped to by LFE
+capture_6	asio3		FXBUS2(0x3)
+capture_7	asio4		FXBUS2(0x4)
+capture_8	asio5		FXBUS2(0x5)
+capture_9	asio6		FXBUS2(0x6)
+capture_10	asio7		FXBUS2(0x7)
+capture_11	asio8		FXBUS2(0x8)
+capture_12	asio9		FXBUS2(0x9)
+capture_13	asio10		FXBUS2(0xa)
+capture_14	asio11		FXBUS2(0xb)
+capture_15	asio12		FXBUS2(0xc)
+capture_16	asio13		FXBUS2(0xd)
+==============  ========        ============
+
+TODO: describe use of ld10k1/qlo10k1 in conjunction with JACK
diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index c9d7ce4286b2..251f1d7675f7 100644
--- a/Documentation/sound/cards/index.rst
+++ b/Documentation/sound/cards/index.rst
@@ -8,4 +8,4 @@ Card-Specific Information
    cmipci
    sb-live-mixer
    audigy-mixer
-  
+   emu10k1-jack
-- 
cgit v1.2.3


From 312c01b1736e81fe0d23217fe537d415785256d2 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 16:32:49 +0100
Subject: ALSA: doc: ReSTize VIA82xx-mixer.txt

Another simple conversion from a plain text file.
Put to cards directory.

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/VIA82xx-mixer.txt  | 8 --------
 Documentation/sound/cards/index.rst         | 1 +
 Documentation/sound/cards/via82xx-mixer.rst | 8 ++++++++
 3 files changed, 9 insertions(+), 8 deletions(-)
 delete mode 100644 Documentation/sound/alsa/VIA82xx-mixer.txt
 create mode 100644 Documentation/sound/cards/via82xx-mixer.rst

diff --git a/Documentation/sound/alsa/VIA82xx-mixer.txt b/Documentation/sound/alsa/VIA82xx-mixer.txt
deleted file mode 100644
index 1b0ac06ba95d..000000000000
--- a/Documentation/sound/alsa/VIA82xx-mixer.txt
+++ /dev/null
@@ -1,8 +0,0 @@
-
-				VIA82xx mixer
-				=============
-
-On many VIA82xx boards, the 'Input Source Select' mixer control does not work.
-Setting it to 'Input2' on such boards will cause recording to hang, or fail
-with EIO (input/output error) via OSS emulation.  This control should be left
-at 'Input1' for such cards.
diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index 251f1d7675f7..4fcb88049ccc 100644
--- a/Documentation/sound/cards/index.rst
+++ b/Documentation/sound/cards/index.rst
@@ -9,3 +9,4 @@ Card-Specific Information
    sb-live-mixer
    audigy-mixer
    emu10k1-jack
+   via82xx-mixer
diff --git a/Documentation/sound/cards/via82xx-mixer.rst b/Documentation/sound/cards/via82xx-mixer.rst
new file mode 100644
index 000000000000..6ee993d4535b
--- /dev/null
+++ b/Documentation/sound/cards/via82xx-mixer.rst
@@ -0,0 +1,8 @@
+=============
+VIA82xx mixer
+=============
+
+On many VIA82xx boards, the ``Input Source Select`` mixer control does not work.
+Setting it to ``Input2`` on such boards will cause recording to hang, or fail
+with EIO (input/output error) via OSS emulation.  This control should be left
+at ``Input1`` for such cards.
-- 
cgit v1.2.3


From 4e47556e345c8c0bd86911a99f28299e3d962140 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 16:52:57 +0100
Subject: ALSA: doc: ReSTize Audiophile-USB.txt

Another simple conversion from a plain text file.
Put to cards directory.

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/Audiophile-Usb.txt  | 442 ---------------------
 Documentation/sound/cards/audiophile-usb.rst | 550 +++++++++++++++++++++++++++
 Documentation/sound/cards/index.rst          |   1 +
 3 files changed, 551 insertions(+), 442 deletions(-)
 delete mode 100644 Documentation/sound/alsa/Audiophile-Usb.txt
 create mode 100644 Documentation/sound/cards/audiophile-usb.rst

diff --git a/Documentation/sound/alsa/Audiophile-Usb.txt b/Documentation/sound/alsa/Audiophile-Usb.txt
deleted file mode 100644
index e7a5ed4dcae8..000000000000
--- a/Documentation/sound/alsa/Audiophile-Usb.txt
+++ /dev/null
@@ -1,442 +0,0 @@
-	Guide to using M-Audio Audiophile USB with ALSA and Jack	v1.5
-	========================================================
-
-	    Thibault Le Meur 
-
-This document is a guide to using the M-Audio Audiophile USB (tm) device with 
-ALSA and JACK.
-
-History
-=======
-* v1.4 - Thibault Le Meur (2007-07-11)
- - Added Low Endianness nature of 16bits-modes
-   found by Hakan Lennestal 
- - Modifying document structure
-* v1.5 - Thibault Le Meur (2007-07-12)
- - Added AC3/DTS passthru info
-
-
-1 - Audiophile USB Specs and correct usage
-==========================================
-
-This part is a reminder of important facts about the functions and limitations 
-of the device.
-
-The device has 4 audio interfaces, and 2 MIDI ports:
- * Analog Stereo Input (Ai)
-   - This port supports 2 pairs of line-level audio inputs (1/4" TS and RCA) 
-   - When the 1/4" TS (jack) connectors are connected, the RCA connectors
-     are disabled
- * Analog Stereo Output (Ao)
- * Digital Stereo Input (Di)
- * Digital Stereo Output (Do)
- * Midi In (Mi)
- * Midi Out (Mo)
-
-The internal DAC/ADC has the following characteristics:
-* sample depth of 16 or 24 bits
-* sample rate from 8kHz to 96kHz
-* Two interfaces can't use different sample depths at the same time.
-Moreover, the Audiophile USB documentation gives the following Warning:
-"Please exit any audio application running before switching between bit depths"
-
-Due to the USB 1.1 bandwidth limitation, a limited number of interfaces can be 
-activated at the same time depending on the audio mode selected:
- * 16-bit/48kHz ==> 4 channels in + 4 channels out
-   - Ai+Ao+Di+Do
- * 24-bit/48kHz ==> 4 channels in + 2 channels out, 
-                    or 2 channels in + 4 channels out
-   - Ai+Ao+Do or Ai+Di+Ao or Ai+Di+Do or Di+Ao+Do
- * 24-bit/96kHz ==> 2 channels in _or_ 2 channels out (half duplex only)
-   - Ai or Ao or Di or Do
-
-Important facts about the Digital interface:
---------------------------------------------
- * The Do port additionally supports surround-encoded AC-3 and DTS passthrough, 
-though I haven't tested it under Linux
-   - Note that in this setup only the Do interface can be enabled
- * Apart from recording an audio digital stream, enabling the Di port is a way 
-to synchronize the device to an external sample clock
-   - As a consequence, the Di port must be enable only if an active Digital 
-source is connected
-   - Enabling Di when no digital source is connected can result in a 
-synchronization error (for instance sound played at an odd sample rate)
-
-
-2 - Audiophile USB MIDI support in ALSA
-=======================================
-
-The Audiophile USB MIDI ports will be automatically supported once the
-following modules have been loaded:
- * snd-usb-audio
- * snd-seq-midi
-
-No additional setting is required.
-
-
-3 - Audiophile USB Audio support in ALSA
-========================================
-
-Audio functions of the Audiophile USB device are handled by the snd-usb-audio 
-module. This module can work in a default mode (without any device-specific 
-parameter), or in an "advanced" mode with the device-specific parameter called 
-"device_setup".
-
-3.1 - Default Alsa driver mode
-------------------------------
-
-The default behavior of the snd-usb-audio driver is to list the device 
-capabilities at startup and activate the required mode when required 
-by the applications: for instance if the user is recording in a 
-24bit-depth-mode and immediately after wants to switch to a 16bit-depth mode,
-the snd-usb-audio module will reconfigure the device on the fly.
-
-This approach has the advantage to let the driver automatically switch from sample 
-rates/depths automatically according to the user's needs. However, those who 
-are using the device under windows know that this is not how the device is meant to
-work: under windows applications must be closed before using the m-audio control
-panel to switch the device working mode. Thus as we'll see in next section, this 
-Default Alsa driver mode can lead to device misconfigurations.
-
-Let's get back to the Default Alsa driver mode for now.  In this case the 
-Audiophile interfaces are mapped to alsa pcm devices in the following 
-way (I suppose the device's index is 1):
- * hw:1,0 is Ao in playback and Di in capture
- * hw:1,1 is Do in playback and Ai in capture
- * hw:1,2 is Do in AC3/DTS passthrough mode
-
-In this mode, the device uses Big Endian byte-encoding so that 
-supported audio format are S16_BE for 16-bit depth modes and S24_3BE for 
-24-bits depth mode.
-
-One exception is the hw:1,2 port which was reported to be Little Endian 
-compliant (supposedly supporting S16_LE) but processes in fact only S16_BE streams.
-This has been fixed in kernel 2.6.23 and above and now the hw:1,2 interface 
-is reported to be big endian in this default driver mode.
-
-Examples:
- * playing a S24_3BE encoded raw file to the Ao port
-   % aplay -D hw:1,0 -c2 -t raw -r48000 -fS24_3BE test.raw
- * recording a  S24_3BE encoded raw file from the Ai port
-   % arecord -D hw:1,1 -c2  -t raw -r48000 -fS24_3BE test.raw
- * playing a S16_BE encoded raw file to the Do port
-   % aplay -D hw:1,1 -c2 -t raw -r48000 -fS16_BE test.raw
- * playing an ac3 sample file to the Do port
-   % aplay -D hw:1,2 --channels=6 ac3_S16_BE_encoded_file.raw
-
-If you're happy with the default Alsa driver mode and don't experience any 
-issue with this mode, then you can skip the following chapter.
-
-3.2 - Advanced module setup
----------------------------
-
-Due to the hardware constraints described above, the device initialization made 
-by the Alsa driver in default mode may result in a corrupted state of the 
-device. For instance, a particularly annoying issue is that the sound captured 
-from the Ai interface sounds distorted (as if boosted with an excessive high
-volume gain).
-
-For people having this problem, the snd-usb-audio module has a new module 
-parameter called "device_setup" (this parameter was introduced in kernel
-release 2.6.17)
-
-3.2.1 - Initializing the working mode of the Audiophile USB
-
-As far as the Audiophile USB device is concerned, this value let the user 
-specify:
- * the sample depth
- * the sample rate
- * whether the Di port is used or not 
-
-When initialized with "device_setup=0x00", the snd-usb-audio module has
-the same behaviour as when the parameter is omitted (see paragraph "Default 
-Alsa driver mode" above)
-
-Others modes are described in the following subsections.
-
-3.2.1.1 - 16-bit modes
-
-The two supported modes are:
-
- * device_setup=0x01
-   - 16bits 48kHz mode with Di disabled
-   - Ai,Ao,Do can be used at the same time
-   - hw:1,0 is not available in capture mode
-   - hw:1,2 is not available
-
- * device_setup=0x11
-   - 16bits 48kHz mode with Di enabled
-   - Ai,Ao,Di,Do can be used at the same time
-   - hw:1,0 is available in capture mode
-   - hw:1,2 is not available
-
-In this modes the device operates only at 16bits-modes. Before kernel 2.6.23,
-the devices where reported to be Big-Endian when in fact they were Little-Endian
-so that playing a file was a matter of using:
-   % aplay -D hw:1,1 -c2 -t raw -r48000 -fS16_BE test_S16_LE.raw
-where "test_S16_LE.raw" was in fact a little-endian sample file.
-
-Thanks to Hakan Lennestal (who discovered the Little-Endiannes of the device in
-these modes) a fix has been committed (expected in kernel 2.6.23) and
-Alsa now reports Little-Endian interfaces. Thus playing a file now is as simple as
-using:
-   % aplay -D hw:1,1 -c2 -t raw -r48000 -fS16_LE test_S16_LE.raw
-
-3.2.1.2 - 24-bit modes
-
-The three supported modes are:
-
- * device_setup=0x09
-   - 24bits 48kHz mode with Di disabled
-   - Ai,Ao,Do can be used at the same time
-   - hw:1,0 is not available in capture mode
-   - hw:1,2 is not available
-
- * device_setup=0x19
-   - 24bits 48kHz mode with Di enabled
-   - 3 ports from {Ai,Ao,Di,Do} can be used at the same time
-   - hw:1,0 is available in capture mode and an active digital source must be 
-     connected to Di
-   - hw:1,2 is not available
-
- * device_setup=0x0D or 0x10
-   - 24bits 96kHz mode
-   - Di is enabled by default for this mode but does not need to be connected 
-     to an active source
-   - Only 1 port from {Ai,Ao,Di,Do} can be used at the same time
-   - hw:1,0 is available in captured mode
-   - hw:1,2 is not available
-
-In these modes the device is only Big-Endian compliant (see "Default Alsa driver 
-mode" above for an aplay command example)
-
-3.2.1.3 - AC3 w/ DTS passthru mode
-
-Thanks to Hakan Lennestal, I now have a report saying that this mode works.
-
- * device_setup=0x03
-   - 16bits 48kHz mode with only the Do port enabled 
-   - AC3 with DTS passthru
-   - Caution with this setup the Do port is mapped to the pcm device hw:1,0
-
-The command line used to playback the AC3/DTS encoded .wav-files in this mode:
-   % aplay -D hw:1,0 --channels=6 ac3_S16_LE_encoded_file.raw
-
-3.2.2 - How to use the device_setup parameter
-----------------------------------------------
-
-The parameter can be given:
-
- * By manually probing the device (as root):
-   # modprobe -r snd-usb-audio
-   # modprobe snd-usb-audio index=1 device_setup=0x09
-
- * Or while configuring the modules options in your modules configuration file
-   (typically a .conf file in /etc/modprobe.d/ directory:
-       alias snd-card-1 snd-usb-audio
-       options snd-usb-audio index=1 device_setup=0x09
-
-CAUTION when initializing the device
--------------------------------------
-
- * Correct initialization on the device requires that device_setup is given to
-   the module BEFORE the device is turned on. So, if you use the "manual probing"
-   method described above, take care to power-on the device AFTER this initialization.
-
- * Failing to respect this will lead to a misconfiguration of the device. In this case
-   turn off the device, unprobe the snd-usb-audio module, then probe it again with
-   correct device_setup parameter and then (and only then) turn on the device again.
-
- * If you've correctly initialized the device in a valid mode and then want to switch
-   to  another mode (possibly with another sample-depth), please use also the following 
-   procedure:
-   - first turn off the device
-   - de-register the snd-usb-audio module (modprobe -r)
-   - change the device_setup parameter by changing the device_setup
-     option in /etc/modprobe.d/*.conf
-   - turn on the device
- * A workaround for this last issue has been applied to kernel 2.6.23, but it may not
-   be enough to ensure the 'stability' of the device initialization.
-
-3.2.3 - Technical details for hackers
--------------------------------------
-This section is for hackers, wanting to understand details about the device
-internals and how Alsa supports it.
-
-3.2.3.1 - Audiophile USB's device_setup structure
-
-If you want to understand the device_setup magic numbers for the Audiophile 
-USB, you need some very basic understanding of binary computation. However, 
-this is not required to use the parameter and you may skip this section.
-
-The device_setup is one byte long and its structure is the following:
-
-       +---+---+---+---+---+---+---+---+
-       | b7| b6| b5| b4| b3| b2| b1| b0|
-       +---+---+---+---+---+---+---+---+
-       | 0 | 0 | 0 | Di|24B|96K|DTS|SET|
-       +---+---+---+---+---+---+---+---+
-
-Where:
- * b0 is the "SET" bit
-   - it MUST be set if device_setup is initialized 
- * b1 is the "DTS" bit
-   - it is set only for Digital output with DTS/AC3
-   - this setup is not tested
- * b2 is the Rate selection flag
-   - When set to "1" the rate range is 48.1-96kHz
-   - Otherwise the sample rate range is 8-48kHz
- * b3 is the bit depth selection flag
-   - When set to "1" samples are 24bits long
-   - Otherwise they are 16bits long
-   - Note that b2 implies b3 as the 96kHz mode is only supported for 24 bits 
-     samples
- * b4 is the Digital input flag
-   - When set to "1" the device assumes that an active digital source is 
-     connected 
-   - You shouldn't enable Di if no source is seen on the port (this leads to 
-     synchronization issues)
-   - b4 is implied by b2 (since only one port is enabled at a time no synch 
-     error can occur) 
- * b5 to b7 are reserved for future uses, and must be set to "0"
-   - might become Ao, Do, Ai, for b7, b6, b4 respectively
-
-Caution:
- * there is no check on the value you will give to device_setup
-   - for instance choosing 0x05 (16bits 96kHz) will fail back to 0x09 since 
-     b2 implies b3. But _there_will_be_no_warning_ in /var/log/messages
- * Hardware constraints due to the USB bus limitation aren't checked
-   - choosing b2 will prepare all interfaces for 24bits/96kHz but you'll
-     only be able to use one at the same time
-
-3.2.3.2 -  USB implementation details for this device
-
-You may safely skip this section if you're not interested in driver 
-hacking.
-
-This section describes some internal aspects of the device and summarizes the 
-data I got by usb-snooping the windows and Linux drivers.
-
-The M-Audio Audiophile USB has 7 USB Interfaces:
-a "USB interface":
- * USB Interface nb.0
- * USB Interface nb.1
-   - Audio Control function
- * USB Interface nb.2
-   - Analog Output
- * USB Interface nb.3
-   - Digital Output
- * USB Interface nb.4
-   - Analog Input
- * USB Interface nb.5
-   - Digital Input
- * USB Interface nb.6
-   - MIDI interface compliant with the MIDIMAN quirk 
-
-Each interface has 5 altsettings (AltSet 1,2,3,4,5) except:
- * Interface 3 (Digital Out) has an extra Alset nb.6 
- * Interface 5 (Digital In) does not have Alset nb.3 and 5 
-
-Here is a short description of the AltSettings capabilities:
- * AltSettings 1 corresponds to
-  - 24-bit depth, 48.1-96kHz sample mode
-  - Adaptive playback (Ao and Do), Synch capture (Ai), or Asynch capture (Di)
- * AltSettings 2 corresponds to
-  - 24-bit depth, 8-48kHz sample mode
-  - Asynch capture and playback  (Ao,Ai,Do,Di)
- * AltSettings 3 corresponds to
-  - 24-bit depth, 8-48kHz sample mode
-  - Synch capture (Ai) and Adaptive playback (Ao,Do)
- * AltSettings 4 corresponds to
-  - 16-bit depth, 8-48kHz sample mode
-  - Asynch capture and playback  (Ao,Ai,Do,Di)
- * AltSettings 5 corresponds to
-  - 16-bit depth, 8-48kHz sample mode
-  - Synch capture (Ai) and Adaptive playback (Ao,Do)
- * AltSettings 6 corresponds to
-  - 16-bit depth, 8-48kHz sample mode
-  - Synch playback (Do), audio format type III IEC1937_AC-3
-
-In order to ensure a correct initialization of the device, the driver 
-_must_know_ how the device will be used:
- * if DTS is chosen, only Interface 2 with AltSet nb.6 must be
-   registered
- * if 96KHz only AltSets nb.1 of each interface must be selected
- * if samples are using 24bits/48KHz then AltSet 2 must me used if
-   Digital input is connected, and only AltSet nb.3 if Digital input
-   is not connected
- * if samples are using 16bits/48KHz then AltSet 4 must me used if
-   Digital input is connected, and only AltSet nb.5 if Digital input
-   is not connected
-
-When device_setup is given as a parameter to the snd-usb-audio module, the 
-parse_audio_endpoints function uses a quirk called 
-"audiophile_skip_setting_quirk" in order to prevent AltSettings not 
-corresponding to device_setup from being registered in the driver.
-
-4 - Audiophile USB and Jack support
-===================================
-
-This section deals with support of the Audiophile USB device in Jack.
-
-There are 2 main potential issues when using Jackd with the device:
-* support for Big-Endian devices in 24-bit modes
-* support for 4-in / 4-out channels
-
-4.1 - Direct support in Jackd
------------------------------
-
-Jack supports big endian devices only in recent versions (thanks to
-Andreas Steinmetz for his first big-endian patch). I can't remember 
-exactly when this support was released into jackd, let's just say that
-with jackd version 0.103.0 it's almost ok (just a small bug is affecting 
-16bits Big-Endian devices, but since you've read carefully the above
-paragraphs, you're now using kernel >= 2.6.23 and your 16bits devices 
-are now Little Endians ;-) ).
-
-You can run jackd with the following command for playback with Ao and
-record with Ai:
-  % jackd -R -dalsa -Phw:1,0 -r48000 -p128 -n2 -D -Chw:1,1
-
-4.2 - Using Alsa plughw
------------------------
-If you don't have a recent Jackd installed, you can downgrade to using
-the Alsa "plug" converter.
-
-For instance here is one way to run Jack with 2 playback channels on Ao and 2 
-capture channels from Ai:
-  % jackd -R -dalsa -dplughw:1 -r48000 -p256 -n2 -D -Cplughw:1,1
-
-However you may see the following warning message:
-"You appear to be using the ALSA software "plug" layer, probably a result of 
-using the "default" ALSA device. This is less efficient than it could be. 
-Consider using a hardware device instead rather than using the plug layer."
-
-4.3 - Getting 2 input and/or output interfaces in Jack
-------------------------------------------------------
-
-As you can see, starting the Jack server this way will only enable 1 stereo
-input (Di or Ai) and 1 stereo output (Ao or Do).
-
-This is due to the following restrictions:
-* Jack can only open one capture device and one playback device at a time
-* The Audiophile USB is seen as 2 (or three) Alsa devices: hw:1,0, hw:1,1
-  (and optionally hw:1,2)
-
-If you want to get Ai+Di and/or Ao+Do support with Jack, you would need to
-combine the Alsa devices into one logical "complex" device.
-
-If you want to give it a try, I recommend reading the information from
-this page: http://www.sound-man.co.uk/linuxaudio/ice1712multi.html
-It is related to another device (ice1712) but can be adapted to suit
-the Audiophile USB.
-
-Enabling multiple Audiophile USB interfaces for Jackd will certainly require:
-* Making sure your Jackd version has the MMAP_COMPLEX patch (see the ice1712 page)
-* (maybe) patching the alsa-lib/src/pcm/pcm_multi.c file (see the ice1712 page)
-* define a multi device (combination of hw:1,0 and hw:1,1) in your .asoundrc
-  file 
-* start jackd with this device
-
-I had no success in testing this for now, if you have any success with this kind 
-of setup, please drop me an email.
diff --git a/Documentation/sound/cards/audiophile-usb.rst b/Documentation/sound/cards/audiophile-usb.rst
new file mode 100644
index 000000000000..a7bb5648331f
--- /dev/null
+++ b/Documentation/sound/cards/audiophile-usb.rst
@@ -0,0 +1,550 @@
+========================================================
+Guide to using M-Audio Audiophile USB with ALSA and Jack
+========================================================
+
+v1.5
+
+Thibault Le Meur 
+
+This document is a guide to using the M-Audio Audiophile USB (tm) device with 
+ALSA and JACK.
+
+History
+=======
+
+* v1.4 - Thibault Le Meur (2007-07-11)
+
+  - Added Low Endianness nature of 16bits-modes
+    found by Hakan Lennestal 
+  - Modifying document structure
+
+* v1.5 - Thibault Le Meur (2007-07-12)
+  - Added AC3/DTS passthru info
+
+
+Audiophile USB Specs and correct usage
+======================================
+
+This part is a reminder of important facts about the functions and limitations 
+of the device.
+
+The device has 4 audio interfaces, and 2 MIDI ports:
+
+ * Analog Stereo Input (Ai)
+
+   - This port supports 2 pairs of line-level audio inputs (1/4" TS and RCA) 
+   - When the 1/4" TS (jack) connectors are connected, the RCA connectors
+     are disabled
+
+ * Analog Stereo Output (Ao)
+ * Digital Stereo Input (Di)
+ * Digital Stereo Output (Do)
+ * Midi In (Mi)
+ * Midi Out (Mo)
+
+The internal DAC/ADC has the following characteristics:
+
+* sample depth of 16 or 24 bits
+* sample rate from 8kHz to 96kHz
+* Two interfaces can't use different sample depths at the same time.
+
+Moreover, the Audiophile USB documentation gives the following Warning:
+  Please exit any audio application running before switching between bit depths
+
+Due to the USB 1.1 bandwidth limitation, a limited number of interfaces can be 
+activated at the same time depending on the audio mode selected:
+
+ * 16-bit/48kHz ==> 4 channels in + 4 channels out
+
+   - Ai+Ao+Di+Do
+
+ * 24-bit/48kHz ==> 4 channels in + 2 channels out, 
+   or 2 channels in + 4 channels out
+
+   - Ai+Ao+Do or Ai+Di+Ao or Ai+Di+Do or Di+Ao+Do
+
+ * 24-bit/96kHz ==> 2 channels in _or_ 2 channels out (half duplex only)
+
+   - Ai or Ao or Di or Do
+
+Important facts about the Digital interface:
+--------------------------------------------
+
+ * The Do port additionally supports surround-encoded AC-3 and DTS passthrough, 
+   though I haven't tested it under Linux
+
+   - Note that in this setup only the Do interface can be enabled
+
+ * Apart from recording an audio digital stream, enabling the Di port is a way 
+   to synchronize the device to an external sample clock
+
+   - As a consequence, the Di port must be enable only if an active Digital 
+     source is connected
+   - Enabling Di when no digital source is connected can result in a 
+     synchronization error (for instance sound played at an odd sample rate)
+
+
+Audiophile USB MIDI support in ALSA
+===================================
+
+The Audiophile USB MIDI ports will be automatically supported once the
+following modules have been loaded:
+
+ * snd-usb-audio
+ * snd-seq-midi
+
+No additional setting is required.
+
+
+Audiophile USB Audio support in ALSA
+====================================
+
+Audio functions of the Audiophile USB device are handled by the snd-usb-audio 
+module. This module can work in a default mode (without any device-specific 
+parameter), or in an "advanced" mode with the device-specific parameter called 
+``device_setup``.
+
+Default Alsa driver mode
+------------------------
+
+The default behavior of the snd-usb-audio driver is to list the device 
+capabilities at startup and activate the required mode when required 
+by the applications: for instance if the user is recording in a 
+24bit-depth-mode and immediately after wants to switch to a 16bit-depth mode,
+the snd-usb-audio module will reconfigure the device on the fly.
+
+This approach has the advantage to let the driver automatically switch from sample 
+rates/depths automatically according to the user's needs. However, those who 
+are using the device under windows know that this is not how the device is meant to
+work: under windows applications must be closed before using the m-audio control
+panel to switch the device working mode. Thus as we'll see in next section, this 
+Default Alsa driver mode can lead to device misconfigurations.
+
+Let's get back to the Default Alsa driver mode for now.  In this case the 
+Audiophile interfaces are mapped to alsa pcm devices in the following 
+way (I suppose the device's index is 1):
+
+ * hw:1,0 is Ao in playback and Di in capture
+ * hw:1,1 is Do in playback and Ai in capture
+ * hw:1,2 is Do in AC3/DTS passthrough mode
+
+In this mode, the device uses Big Endian byte-encoding so that 
+supported audio format are S16_BE for 16-bit depth modes and S24_3BE for 
+24-bits depth mode.
+
+One exception is the hw:1,2 port which was reported to be Little Endian 
+compliant (supposedly supporting S16_LE) but processes in fact only S16_BE streams.
+This has been fixed in kernel 2.6.23 and above and now the hw:1,2 interface 
+is reported to be big endian in this default driver mode.
+
+Examples:
+
+ * playing a S24_3BE encoded raw file to the Ao port::
+
+   % aplay -D hw:1,0 -c2 -t raw -r48000 -fS24_3BE test.raw
+
+ * recording a  S24_3BE encoded raw file from the Ai port::
+
+   % arecord -D hw:1,1 -c2  -t raw -r48000 -fS24_3BE test.raw
+
+ * playing a S16_BE encoded raw file to the Do port::
+
+   % aplay -D hw:1,1 -c2 -t raw -r48000 -fS16_BE test.raw
+
+ * playing an ac3 sample file to the Do port::
+
+   % aplay -D hw:1,2 --channels=6 ac3_S16_BE_encoded_file.raw
+
+If you're happy with the default Alsa driver mode and don't experience any 
+issue with this mode, then you can skip the following chapter.
+
+Advanced module setup
+---------------------
+
+Due to the hardware constraints described above, the device initialization made 
+by the Alsa driver in default mode may result in a corrupted state of the 
+device. For instance, a particularly annoying issue is that the sound captured 
+from the Ai interface sounds distorted (as if boosted with an excessive high
+volume gain).
+
+For people having this problem, the snd-usb-audio module has a new module 
+parameter called ``device_setup`` (this parameter was introduced in kernel
+release 2.6.17)
+
+Initializing the working mode of the Audiophile USB
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As far as the Audiophile USB device is concerned, this value let the user 
+specify:
+
+ * the sample depth
+ * the sample rate
+ * whether the Di port is used or not 
+
+When initialized with ``device_setup=0x00``, the snd-usb-audio module has
+the same behaviour as when the parameter is omitted (see paragraph "Default 
+Alsa driver mode" above)
+
+Others modes are described in the following subsections.
+
+16-bit modes
+~~~~~~~~~~~~
+
+The two supported modes are:
+
+ * ``device_setup=0x01``
+
+   - 16bits 48kHz mode with Di disabled
+   - Ai,Ao,Do can be used at the same time
+   - hw:1,0 is not available in capture mode
+   - hw:1,2 is not available
+
+ * ``device_setup=0x11``
+
+   - 16bits 48kHz mode with Di enabled
+   - Ai,Ao,Di,Do can be used at the same time
+   - hw:1,0 is available in capture mode
+   - hw:1,2 is not available
+
+In this modes the device operates only at 16bits-modes. Before kernel 2.6.23,
+the devices where reported to be Big-Endian when in fact they were Little-Endian
+so that playing a file was a matter of using:
+::
+
+   % aplay -D hw:1,1 -c2 -t raw -r48000 -fS16_BE test_S16_LE.raw
+
+where "test_S16_LE.raw" was in fact a little-endian sample file.
+
+Thanks to Hakan Lennestal (who discovered the Little-Endiannes of the device in
+these modes) a fix has been committed (expected in kernel 2.6.23) and
+Alsa now reports Little-Endian interfaces. Thus playing a file now is as simple as
+using:
+::
+
+   % aplay -D hw:1,1 -c2 -t raw -r48000 -fS16_LE test_S16_LE.raw
+
+
+24-bit modes
+~~~~~~~~~~~~
+
+The three supported modes are:
+
+ * ``device_setup=0x09``
+
+   - 24bits 48kHz mode with Di disabled
+   - Ai,Ao,Do can be used at the same time
+   - hw:1,0 is not available in capture mode
+   - hw:1,2 is not available
+
+ * ``device_setup=0x19``
+
+   - 24bits 48kHz mode with Di enabled
+   - 3 ports from {Ai,Ao,Di,Do} can be used at the same time
+   - hw:1,0 is available in capture mode and an active digital source must be 
+     connected to Di
+   - hw:1,2 is not available
+
+ * ``device_setup=0x0D`` or ``0x10``
+
+   - 24bits 96kHz mode
+   - Di is enabled by default for this mode but does not need to be connected 
+     to an active source
+   - Only 1 port from {Ai,Ao,Di,Do} can be used at the same time
+   - hw:1,0 is available in captured mode
+   - hw:1,2 is not available
+
+In these modes the device is only Big-Endian compliant (see "Default Alsa driver 
+mode" above for an aplay command example)
+
+AC3 w/ DTS passthru mode
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Thanks to Hakan Lennestal, I now have a report saying that this mode works.
+
+ * ``device_setup=0x03``
+
+   - 16bits 48kHz mode with only the Do port enabled 
+   - AC3 with DTS passthru
+   - Caution with this setup the Do port is mapped to the pcm device hw:1,0
+
+The command line used to playback the AC3/DTS encoded .wav-files in this mode:
+::
+
+   % aplay -D hw:1,0 --channels=6 ac3_S16_LE_encoded_file.raw
+
+How to use the ``device_setup`` parameter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The parameter can be given:
+
+ * By manually probing the device (as root):::
+
+   # modprobe -r snd-usb-audio
+   # modprobe snd-usb-audio index=1 device_setup=0x09
+
+ * Or while configuring the modules options in your modules configuration file
+   (typically a .conf file in /etc/modprobe.d/ directory:::
+
+       alias snd-card-1 snd-usb-audio
+       options snd-usb-audio index=1 device_setup=0x09
+
+CAUTION when initializing the device
+-------------------------------------
+
+ * Correct initialization on the device requires that device_setup is given to
+   the module BEFORE the device is turned on. So, if you use the "manual probing"
+   method described above, take care to power-on the device AFTER this initialization.
+
+ * Failing to respect this will lead to a misconfiguration of the device. In this case
+   turn off the device, unprobe the snd-usb-audio module, then probe it again with
+   correct device_setup parameter and then (and only then) turn on the device again.
+
+ * If you've correctly initialized the device in a valid mode and then want to switch
+   to  another mode (possibly with another sample-depth), please use also the following 
+   procedure:
+
+   - first turn off the device
+   - de-register the snd-usb-audio module (modprobe -r)
+   - change the device_setup parameter by changing the device_setup
+     option in ``/etc/modprobe.d/*.conf``
+   - turn on the device
+
+ * A workaround for this last issue has been applied to kernel 2.6.23, but it may not
+   be enough to ensure the 'stability' of the device initialization.
+
+Technical details for hackers
+-----------------------------
+
+This section is for hackers, wanting to understand details about the device
+internals and how Alsa supports it.
+
+Audiophile USB's ``device_setup`` structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to understand the device_setup magic numbers for the Audiophile 
+USB, you need some very basic understanding of binary computation. However, 
+this is not required to use the parameter and you may skip this section.
+
+The device_setup is one byte long and its structure is the following:
+::
+
+       +---+---+---+---+---+---+---+---+
+       | b7| b6| b5| b4| b3| b2| b1| b0|
+       +---+---+---+---+---+---+---+---+
+       | 0 | 0 | 0 | Di|24B|96K|DTS|SET|
+       +---+---+---+---+---+---+---+---+
+
+Where:
+
+ * b0 is the ``SET`` bit
+
+   - it MUST be set if device_setup is initialized 
+
+ * b1 is the ``DTS`` bit
+
+   - it is set only for Digital output with DTS/AC3
+   - this setup is not tested
+
+ * b2 is the Rate selection flag
+
+   - When set to ``1`` the rate range is 48.1-96kHz
+   - Otherwise the sample rate range is 8-48kHz
+
+ * b3 is the bit depth selection flag
+
+   - When set to ``1`` samples are 24bits long
+   - Otherwise they are 16bits long
+   - Note that b2 implies b3 as the 96kHz mode is only supported for 24 bits 
+     samples
+
+ * b4 is the Digital input flag
+
+   - When set to ``1`` the device assumes that an active digital source is 
+     connected 
+   - You shouldn't enable Di if no source is seen on the port (this leads to 
+     synchronization issues)
+   - b4 is implied by b2 (since only one port is enabled at a time no synch 
+     error can occur) 
+
+ * b5 to b7 are reserved for future uses, and must be set to ``0``
+
+   - might become Ao, Do, Ai, for b7, b6, b4 respectively
+
+Caution:
+
+ * there is no check on the value you will give to device_setup
+
+   - for instance choosing 0x05 (16bits 96kHz) will fail back to 0x09 since 
+     b2 implies b3. But _there_will_be_no_warning_ in /var/log/messages
+
+ * Hardware constraints due to the USB bus limitation aren't checked
+
+   - choosing b2 will prepare all interfaces for 24bits/96kHz but you'll
+     only be able to use one at the same time
+
+USB implementation details for this device
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may safely skip this section if you're not interested in driver 
+hacking.
+
+This section describes some internal aspects of the device and summarizes the 
+data I got by usb-snooping the windows and Linux drivers.
+
+The M-Audio Audiophile USB has 7 USB Interfaces:
+a "USB interface":
+
+ * USB Interface nb.0
+ * USB Interface nb.1
+
+   - Audio Control function
+
+ * USB Interface nb.2
+
+   - Analog Output
+
+ * USB Interface nb.3
+
+   - Digital Output
+
+ * USB Interface nb.4
+
+   - Analog Input
+
+ * USB Interface nb.5
+
+   - Digital Input
+
+ * USB Interface nb.6
+
+   - MIDI interface compliant with the MIDIMAN quirk 
+
+Each interface has 5 altsettings (AltSet 1,2,3,4,5) except:
+
+ * Interface 3 (Digital Out) has an extra Alset nb.6 
+ * Interface 5 (Digital In) does not have Alset nb.3 and 5 
+
+Here is a short description of the AltSettings capabilities:
+
+* AltSettings 1 corresponds to
+
+  - 24-bit depth, 48.1-96kHz sample mode
+  - Adaptive playback (Ao and Do), Synch capture (Ai), or Asynch capture (Di)
+
+* AltSettings 2 corresponds to
+
+  - 24-bit depth, 8-48kHz sample mode
+  - Asynch capture and playback  (Ao,Ai,Do,Di)
+
+* AltSettings 3 corresponds to
+
+  - 24-bit depth, 8-48kHz sample mode
+  - Synch capture (Ai) and Adaptive playback (Ao,Do)
+
+* AltSettings 4 corresponds to
+
+  - 16-bit depth, 8-48kHz sample mode
+  - Asynch capture and playback  (Ao,Ai,Do,Di)
+
+* AltSettings 5 corresponds to
+
+  - 16-bit depth, 8-48kHz sample mode
+  - Synch capture (Ai) and Adaptive playback (Ao,Do)
+
+* AltSettings 6 corresponds to
+
+  - 16-bit depth, 8-48kHz sample mode
+  - Synch playback (Do), audio format type III IEC1937_AC-3
+
+In order to ensure a correct initialization of the device, the driver 
+*must* *know* how the device will be used:
+
+ * if DTS is chosen, only Interface 2 with AltSet nb.6 must be
+   registered
+ * if 96KHz only AltSets nb.1 of each interface must be selected
+ * if samples are using 24bits/48KHz then AltSet 2 must me used if
+   Digital input is connected, and only AltSet nb.3 if Digital input
+   is not connected
+ * if samples are using 16bits/48KHz then AltSet 4 must me used if
+   Digital input is connected, and only AltSet nb.5 if Digital input
+   is not connected
+
+When device_setup is given as a parameter to the snd-usb-audio module, the 
+parse_audio_endpoints function uses a quirk called 
+``audiophile_skip_setting_quirk`` in order to prevent AltSettings not 
+corresponding to device_setup from being registered in the driver.
+
+Audiophile USB and Jack support
+===============================
+
+This section deals with support of the Audiophile USB device in Jack.
+
+There are 2 main potential issues when using Jackd with the device:
+
+* support for Big-Endian devices in 24-bit modes
+* support for 4-in / 4-out channels
+
+Direct support in Jackd
+-----------------------
+
+Jack supports big endian devices only in recent versions (thanks to
+Andreas Steinmetz for his first big-endian patch). I can't remember 
+exactly when this support was released into jackd, let's just say that
+with jackd version 0.103.0 it's almost ok (just a small bug is affecting 
+16bits Big-Endian devices, but since you've read carefully the above
+paragraphs, you're now using kernel >= 2.6.23 and your 16bits devices 
+are now Little Endians ;-) ).
+
+You can run jackd with the following command for playback with Ao and
+record with Ai:
+::
+
+  % jackd -R -dalsa -Phw:1,0 -r48000 -p128 -n2 -D -Chw:1,1
+
+Using Alsa plughw
+-----------------
+
+If you don't have a recent Jackd installed, you can downgrade to using
+the Alsa ``plug`` converter.
+
+For instance here is one way to run Jack with 2 playback channels on Ao and 2 
+capture channels from Ai:
+::
+
+  % jackd -R -dalsa -dplughw:1 -r48000 -p256 -n2 -D -Cplughw:1,1
+
+However you may see the following warning message:
+  You appear to be using the ALSA software "plug" layer, probably a result of 
+  using the "default" ALSA device. This is less efficient than it could be. 
+  Consider using a hardware device instead rather than using the plug layer.
+
+Getting 2 input and/or output interfaces in Jack
+------------------------------------------------
+
+As you can see, starting the Jack server this way will only enable 1 stereo
+input (Di or Ai) and 1 stereo output (Ao or Do).
+
+This is due to the following restrictions:
+
+* Jack can only open one capture device and one playback device at a time
+* The Audiophile USB is seen as 2 (or three) Alsa devices: hw:1,0, hw:1,1
+  (and optionally hw:1,2)
+
+If you want to get Ai+Di and/or Ao+Do support with Jack, you would need to
+combine the Alsa devices into one logical "complex" device.
+
+If you want to give it a try, I recommend reading the information from
+this page: http://www.sound-man.co.uk/linuxaudio/ice1712multi.html
+It is related to another device (ice1712) but can be adapted to suit
+the Audiophile USB.
+
+Enabling multiple Audiophile USB interfaces for Jackd will certainly require:
+
+* Making sure your Jackd version has the MMAP_COMPLEX patch (see the ice1712 page)
+* (maybe) patching the alsa-lib/src/pcm/pcm_multi.c file (see the ice1712 page)
+* define a multi device (combination of hw:1,0 and hw:1,1) in your .asoundrc
+  file 
+* start jackd with this device
+
+I had no success in testing this for now, if you have any success with this kind 
+of setup, please drop me an email.
diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index 4fcb88049ccc..e92a4f7e86fc 100644
--- a/Documentation/sound/cards/index.rst
+++ b/Documentation/sound/cards/index.rst
@@ -10,3 +10,4 @@ Card-Specific Information
    audigy-mixer
    emu10k1-jack
    via82xx-mixer
+   audiophile-usb
-- 
cgit v1.2.3


From 3d8e81862ce404d861b75bcb1e7d986e4febb025 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 16:56:09 +0100
Subject: ALSA: doc: ReSTize MIXART.txt

Another simple conversion from a plain text file.
Put to cards directory.

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/MIXART.txt  | 100 -------------------------------
 Documentation/sound/cards/index.rst  |   1 +
 Documentation/sound/cards/mixart.rst | 110 +++++++++++++++++++++++++++++++++++
 3 files changed, 111 insertions(+), 100 deletions(-)
 delete mode 100644 Documentation/sound/alsa/MIXART.txt
 create mode 100644 Documentation/sound/cards/mixart.rst

diff --git a/Documentation/sound/alsa/MIXART.txt b/Documentation/sound/alsa/MIXART.txt
deleted file mode 100644
index 4ee35b4fbe4a..000000000000
--- a/Documentation/sound/alsa/MIXART.txt
+++ /dev/null
@@ -1,100 +0,0 @@
-    Alsa driver for Digigram miXart8 and miXart8AES/EBU soundcards
-	    Digigram 
-
-
-GENERAL
-=======
-
-The miXart8 is a multichannel audio processing and mixing soundcard
-that has 4 stereo audio inputs and 4 stereo audio outputs.
-The miXart8AES/EBU is the same with a add-on card that offers further
-4 digital stereo audio inputs and outputs.
-Furthermore the add-on card offers external clock synchronisation
-(AES/EBU, Word Clock, Time Code and Video Synchro)
-
-The mainboard has a PowerPC that offers onboard mpeg encoding and
-decoding, samplerate conversions and various effects.
-
-The driver don't work properly at all until the certain firmwares
-are loaded, i.e. no PCM nor mixer devices will appear.
-Use the mixartloader that can be found in the alsa-tools package.
-
-
-VERSION 0.1.0
-=============
-
-One miXart8 board will be represented as 4 alsa cards, each with 1
-stereo analog capture 'pcm0c' and 1 stereo analog playback 'pcm0p' device.
-With a miXart8AES/EBU there is in addition 1 stereo digital input
-'pcm1c' and 1 stereo digital output 'pcm1p' per card.
-
-Formats
--------
-U8, S16_LE, S16_BE, S24_3LE, S24_3BE, FLOAT_LE, FLOAT_BE
-Sample rates : 8000 - 48000 Hz continuously
-
-Playback
---------
-For instance the playback devices are configured to have max. 4
-substreams performing hardware mixing. This could be changed to a
-maximum of 24 substreams if wished.
-Mono files will be played on the left and right channel. Each channel
-can be muted for each stream to use 8 analog/digital outputs separately.
-
-Capture
--------
-There is one substream per capture device. For instance only stereo
-formats are supported.
-
-Mixer
------
- and  : analog volume control of playback and capture PCM.
- and  : digital volume control of each analog substream.
- and  : digital volume control of each AES/EBU substream.
- : Loopback from 'pcm0c' to 'pcm0p' with digital volume
-and mute control.
-
-Rem : for best audio quality try to keep a 0 attenuation on the PCM
-and AES volume controls which is set by 219 in the range from 0 to 255
-(about 86% with alsamixer)
-
-
-NOT YET IMPLEMENTED
-===================
-
-- external clock support (AES/EBU, Word Clock, Time Code, Video Sync)
-- MPEG audio formats
-- mono record
-- on-board effects and samplerate conversions
-- linked streams
-
-
-FIRMWARE
-========
-
-[As of 2.6.11, the firmware can be loaded automatically with hotplug
- when CONFIG_FW_LOADER is set.  The mixartloader is necessary only
- for older versions or when you build the driver into kernel.]
- 
-For loading the firmware automatically after the module is loaded, use a
-install command.  For example, add the following entry to
-/etc/modprobe.d/mixart.conf for miXart driver:
-
-	install snd-mixart /sbin/modprobe --first-time -i snd-mixart && \
-			   /usr/bin/mixartloader
-(for 2.2/2.4 kernels, add "post-install snd-mixart /usr/bin/vxloader" to
- /etc/modules.conf, instead.)
-
-The firmware binaries are installed on /usr/share/alsa/firmware
-(or /usr/local/share/alsa/firmware, depending to the prefix option of
-configure).  There will be a miXart.conf file, which define the dsp image
-files.
-
-The firmware files are copyright by Digigram SA
-
-
-COPYRIGHT
-=========
-
-Copyright (c) 2003 Digigram SA 
-Distributable under GPL.
diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index e92a4f7e86fc..0006bc547bb8 100644
--- a/Documentation/sound/cards/index.rst
+++ b/Documentation/sound/cards/index.rst
@@ -11,3 +11,4 @@ Card-Specific Information
    emu10k1-jack
    via82xx-mixer
    audiophile-usb
+   mixart
diff --git a/Documentation/sound/cards/mixart.rst b/Documentation/sound/cards/mixart.rst
new file mode 100644
index 000000000000..48aba98b088f
--- /dev/null
+++ b/Documentation/sound/cards/mixart.rst
@@ -0,0 +1,110 @@
+==============================================================
+Alsa driver for Digigram miXart8 and miXart8AES/EBU soundcards
+==============================================================
+
+Digigram 
+
+
+GENERAL
+=======
+
+The miXart8 is a multichannel audio processing and mixing soundcard
+that has 4 stereo audio inputs and 4 stereo audio outputs.
+The miXart8AES/EBU is the same with a add-on card that offers further
+4 digital stereo audio inputs and outputs.
+Furthermore the add-on card offers external clock synchronisation
+(AES/EBU, Word Clock, Time Code and Video Synchro)
+
+The mainboard has a PowerPC that offers onboard mpeg encoding and
+decoding, samplerate conversions and various effects.
+
+The driver don't work properly at all until the certain firmwares
+are loaded, i.e. no PCM nor mixer devices will appear.
+Use the mixartloader that can be found in the alsa-tools package.
+
+
+VERSION 0.1.0
+=============
+
+One miXart8 board will be represented as 4 alsa cards, each with 1
+stereo analog capture 'pcm0c' and 1 stereo analog playback 'pcm0p' device.
+With a miXart8AES/EBU there is in addition 1 stereo digital input
+'pcm1c' and 1 stereo digital output 'pcm1p' per card.
+
+Formats
+-------
+U8, S16_LE, S16_BE, S24_3LE, S24_3BE, FLOAT_LE, FLOAT_BE
+Sample rates : 8000 - 48000 Hz continuously
+
+Playback
+--------
+For instance the playback devices are configured to have max. 4
+substreams performing hardware mixing. This could be changed to a
+maximum of 24 substreams if wished.
+Mono files will be played on the left and right channel. Each channel
+can be muted for each stream to use 8 analog/digital outputs separately.
+
+Capture
+-------
+There is one substream per capture device. For instance only stereo
+formats are supported.
+
+Mixer
+-----
+ and 
+	analog volume control of playback and capture PCM.
+ and 
+	digital volume control of each analog substream.
+ and 
+	digital volume control of each AES/EBU substream.
+
+	Loopback from 'pcm0c' to 'pcm0p' with digital volume
+	and mute control.
+
+Rem : for best audio quality try to keep a 0 attenuation on the PCM
+and AES volume controls which is set by 219 in the range from 0 to 255
+(about 86% with alsamixer)
+
+
+NOT YET IMPLEMENTED
+===================
+
+- external clock support (AES/EBU, Word Clock, Time Code, Video Sync)
+- MPEG audio formats
+- mono record
+- on-board effects and samplerate conversions
+- linked streams
+
+
+FIRMWARE
+========
+
+[As of 2.6.11, the firmware can be loaded automatically with hotplug
+ when CONFIG_FW_LOADER is set.  The mixartloader is necessary only
+ for older versions or when you build the driver into kernel.]
+ 
+For loading the firmware automatically after the module is loaded, use a
+install command.  For example, add the following entry to
+/etc/modprobe.d/mixart.conf for miXart driver:
+::
+
+	install snd-mixart /sbin/modprobe --first-time -i snd-mixart && \
+			   /usr/bin/mixartloader
+
+
+(for 2.2/2.4 kernels, add "post-install snd-mixart /usr/bin/vxloader" to
+/etc/modules.conf, instead.)
+
+The firmware binaries are installed on /usr/share/alsa/firmware
+(or /usr/local/share/alsa/firmware, depending to the prefix option of
+configure).  There will be a miXart.conf file, which define the dsp image
+files.
+
+The firmware files are copyright by Digigram SA
+
+
+COPYRIGHT
+=========
+
+Copyright (c) 2003 Digigram SA 
+Distributable under GPL.
-- 
cgit v1.2.3


From 7bb97dfdcaca0963d59f986e0a88d5bcd0783552 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 16:59:08 +0100
Subject: ALSA: doc: ReSTize Bt87x.txt

Another	simple conversion from a plain text file.
Put to cards directory.

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/Bt87x.txt  | 78 ----------------------------------
 Documentation/sound/cards/bt87x.rst | 83 +++++++++++++++++++++++++++++++++++++
 Documentation/sound/cards/index.rst |  1 +
 3 files changed, 84 insertions(+), 78 deletions(-)
 delete mode 100644 Documentation/sound/alsa/Bt87x.txt
 create mode 100644 Documentation/sound/cards/bt87x.rst

diff --git a/Documentation/sound/alsa/Bt87x.txt b/Documentation/sound/alsa/Bt87x.txt
deleted file mode 100644
index f158cde8b065..000000000000
--- a/Documentation/sound/alsa/Bt87x.txt
+++ /dev/null
@@ -1,78 +0,0 @@
-Intro
-=====
-
-You might have noticed that the bt878 grabber cards have actually
-_two_ PCI functions:
-
-$ lspci
-[ ... ]
-00:0a.0 Multimedia video controller: Brooktree Corporation Bt878 (rev 02)
-00:0a.1 Multimedia controller: Brooktree Corporation Bt878 (rev 02)
-[ ... ]
-
-The first does video, it is backward compatible to the bt848.  The second
-does audio.  snd-bt87x is a driver for the second function.  It's a sound
-driver which can be used for recording sound (and _only_ recording, no
-playback).  As most TV cards come with a short cable which can be plugged
-into your sound card's line-in you probably don't need this driver if all
-you want to do is just watching TV...
-
-Some cards do not bother to connect anything to the audio input pins of
-the chip, and some other cards use the audio function to transport MPEG
-video data, so it's quite possible that audio recording may not work
-with your card.
-
-
-Driver Status
-=============
-
-The driver is now stable.  However, it doesn't know about many TV cards,
-and it refuses to load for cards it doesn't know.
-
-If the driver complains ("Unknown TV card found, the audio driver will
-not load"), you can specify the load_all=1 option to force the driver to
-try to use the audio capture function of your card.  If the frequency of
-recorded data is not right, try to specify the digital_rate option with
-other values than the default 32000 (often it's 44100 or 64000).
-
-If you have an unknown card, please mail the ID and board name to
-, regardless of whether audio capture works
-or not, so that future versions of this driver know about your card.
-
-
-Audio modes
-===========
-
-The chip knows two different modes (digital/analog).  snd-bt87x
-registers two PCM devices, one for each mode.  They cannot be used at
-the same time.
-
-
-Digital audio mode
-==================
-
-The first device (hw:X,0) gives you 16 bit stereo sound.  The sample
-rate depends on the external source which feeds the Bt87x with digital
-sound via I2S interface.
-
-
-Analog audio mode (A/D)
-=======================
-
-The second device (hw:X,1) gives you 8 or 16 bit mono sound.  Supported
-sample rates are between 119466 and 448000 Hz (yes, these numbers are
-that high).  If you've set the CONFIG_SND_BT87X_OVERCLOCK option, the
-maximum sample rate is 1792000 Hz, but audio data becomes unusable
-beyond 896000 Hz on my card.
-
-The chip has three analog inputs.  Consequently you'll get a mixer
-device to control these.
-
-
-Have fun,
-
-  Clemens
-
-
-Written by Clemens Ladisch 
-big parts copied from btaudio.txt by Gerd Knorr 
diff --git a/Documentation/sound/cards/bt87x.rst b/Documentation/sound/cards/bt87x.rst
new file mode 100644
index 000000000000..912732d3ef9e
--- /dev/null
+++ b/Documentation/sound/cards/bt87x.rst
@@ -0,0 +1,83 @@
+=================
+ALSA BT87x Driver
+=================
+
+Intro
+=====
+
+You might have noticed that the bt878 grabber cards have actually
+*two* PCI functions:
+::
+
+  $ lspci
+  [ ... ]
+  00:0a.0 Multimedia video controller: Brooktree Corporation Bt878 (rev 02)
+  00:0a.1 Multimedia controller: Brooktree Corporation Bt878 (rev 02)
+  [ ... ]
+
+The first does video, it is backward compatible to the bt848.  The second
+does audio.  snd-bt87x is a driver for the second function.  It's a sound
+driver which can be used for recording sound (and *only* recording, no
+playback).  As most TV cards come with a short cable which can be plugged
+into your sound card's line-in you probably don't need this driver if all
+you want to do is just watching TV...
+
+Some cards do not bother to connect anything to the audio input pins of
+the chip, and some other cards use the audio function to transport MPEG
+video data, so it's quite possible that audio recording may not work
+with your card.
+
+
+Driver Status
+=============
+
+The driver is now stable.  However, it doesn't know about many TV cards,
+and it refuses to load for cards it doesn't know.
+
+If the driver complains ("Unknown TV card found, the audio driver will
+not load"), you can specify the ``load_all=1`` option to force the driver to
+try to use the audio capture function of your card.  If the frequency of
+recorded data is not right, try to specify the ``digital_rate`` option with
+other values than the default 32000 (often it's 44100 or 64000).
+
+If you have an unknown card, please mail the ID and board name to
+, regardless of whether audio capture works
+or not, so that future versions of this driver know about your card.
+
+
+Audio modes
+===========
+
+The chip knows two different modes (digital/analog).  snd-bt87x
+registers two PCM devices, one for each mode.  They cannot be used at
+the same time.
+
+
+Digital audio mode
+==================
+
+The first device (hw:X,0) gives you 16 bit stereo sound.  The sample
+rate depends on the external source which feeds the Bt87x with digital
+sound via I2S interface.
+
+
+Analog audio mode (A/D)
+=======================
+
+The second device (hw:X,1) gives you 8 or 16 bit mono sound.  Supported
+sample rates are between 119466 and 448000 Hz (yes, these numbers are
+that high).  If you've set the CONFIG_SND_BT87X_OVERCLOCK option, the
+maximum sample rate is 1792000 Hz, but audio data becomes unusable
+beyond 896000 Hz on my card.
+
+The chip has three analog inputs.  Consequently you'll get a mixer
+device to control these.
+
+
+Have fun,
+
+  Clemens
+
+
+Written by Clemens Ladisch 
+big parts copied from btaudio.txt by Gerd Knorr 
diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index 0006bc547bb8..157372faae06 100644
--- a/Documentation/sound/cards/index.rst
+++ b/Documentation/sound/cards/index.rst
@@ -12,3 +12,4 @@ Card-Specific Information
    via82xx-mixer
    audiophile-usb
    mixart
+   bt87x
-- 
cgit v1.2.3


From a02f5895eee72fe365cdcbd26699a5b5091c9f1e Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 17:07:49 +0100
Subject: ALSA: doc: ReSTize README.maya44

Another	simple conversion from a plain text file.
Put to cards directory.

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/README.maya44 | 163 -----------------------------
 Documentation/sound/cards/index.rst    |   1 +
 Documentation/sound/cards/maya44.rst   | 186 +++++++++++++++++++++++++++++++++
 3 files changed, 187 insertions(+), 163 deletions(-)
 delete mode 100644 Documentation/sound/alsa/README.maya44
 create mode 100644 Documentation/sound/cards/maya44.rst

diff --git a/Documentation/sound/alsa/README.maya44 b/Documentation/sound/alsa/README.maya44
deleted file mode 100644
index 67b2ea1cc31d..000000000000
--- a/Documentation/sound/alsa/README.maya44
+++ /dev/null
@@ -1,163 +0,0 @@
-NOTE: The following is the original document of Rainer's patch that the
-current maya44 code based on.  Some contents might be obsoleted, but I
-keep here as reference -- tiwai
-
-----------------------------------------------------------------
- 
-STATE OF DEVELOPMENT:
-
-This driver is being developed on the initiative of Piotr Makowski (oponek@gmail.com) and financed by Lars Bergmann.
-Development is carried out by Rainer Zimmermann (mail@lightshed.de).
-
-ESI provided a sample Maya44 card for the development work.
-
-However, unfortunately it has turned out difficult to get detailed programming information, so I (Rainer Zimmermann) had to find out some card-specific information by experiment and conjecture. Some information (in particular, several GPIO bits) is still missing.
-
-This is the first testing version of the Maya44 driver released to the alsa-devel mailing list (Feb 5, 2008).
-
-
-The following functions work, as tested by Rainer Zimmermann and Piotr Makowski:
-
-- playback and capture at all sampling rates
-- input/output level
-- crossmixing
-- line/mic switch
-- phantom power switch
-- analogue monitor a.k.a bypass
-
-
-The following functions *should* work, but are not fully tested:
-
-- Channel 3+4 analogue - S/PDIF input switching
-- S/PDIF output
-- all inputs/outputs on the M/IO/DIO extension card
-- internal/external clock selection
-
-
-*In particular, we would appreciate testing of these functions by anyone who has access to an M/IO/DIO extension card.*
-
-
-Things that do not seem to work:
-
-- The level meters ("multi track") in 'alsamixer' do not seem to react to signals in (if this is a bug, it would probably be in the existing ICE1724 code).
-
-- Ardour 2.1 seems to work only via JACK, not using ALSA directly or via OSS. This still needs to be tracked down.
-
-
-DRIVER DETAILS:
-
-the following files were added:
-
-pci/ice1724/maya44.c        - Maya44 specific code
-pci/ice1724/maya44.h
-pci/ice1724/ice1724.patch
-pci/ice1724/ice1724.h.patch - PROPOSED patch to ice1724.h (see SAMPLING RATES)
-i2c/other/wm8776.c  - low-level access routines for Wolfson WM8776 codecs 
-include/wm8776.h
-
-
-Note that the wm8776.c code is meant to be card-independent and does not actually register the codec with the ALSA infrastructure.
-This is done in maya44.c, mainly because some of the WM8776 controls are used in Maya44-specific ways, and should be named appropriately.
-
-
-the following files were created in pci/ice1724, simply #including the corresponding file from the alsa-kernel tree:
-
-wtm.h
-vt1720_mobo.h
-revo.h
-prodigy192.h
-pontis.h
-phase.h
-maya44.h
-juli.h
-aureon.h
-amp.h
-envy24ht.h
-se.h
-prodigy_hifi.h
-
-
-*I hope this is the correct way to do things.*
-
-
-SAMPLING RATES:
-
-The Maya44 card (or more exactly, the Wolfson WM8776 codecs) allow a maximum sampling rate of 192 kHz for playback and 92 kHz for capture.
-
-As the ICE1724 chip only allows one global sampling rate, this is handled as follows:
-
-* setting the sampling rate on any open PCM device on the maya44 card will always set the *global* sampling rate for all playback and capture channels.
-
-* In the current state of the driver, setting rates of up to 192 kHz is permitted even for capture devices.
-
-*AVOID CAPTURING AT RATES ABOVE 96kHz*, even though it may appear to work. The codec cannot actually capture at such rates, meaning poor quality.
-
-
-I propose some additional code for limiting the sampling rate when setting on a capture pcm device. However because of the global sampling rate, this logic would be somewhat problematic.
-
-The proposed code (currently deactivated) is in ice1712.h.patch, ice1724.c and maya44.c (in pci/ice1712).
-
-
-SOUND DEVICES:
-
-PCM devices correspond to inputs/outputs as follows (assuming Maya44 is card #0):
-
-hw:0,0 input - stereo, analog input 1+2
-hw:0,0 output - stereo, analog output 1+2
-hw:0,1 input - stereo, analog input 3+4 OR S/PDIF input
-hw:0,1 output - stereo, analog output 3+4 (and SPDIF out)
-
-
-NAMING OF MIXER CONTROLS:
-
-(for more information about the signal flow, please refer to the block diagram on p.24 of the ESI Maya44 manual, or in the ESI windows software).
-
-
-PCM: (digital) output level for channel 1+2
-PCM 1: same for channel 3+4
-
-Mic Phantom+48V: switch for +48V phantom power for electrostatic microphones on input 1/2.
-    Make sure this is not turned on while any other source is connected to input 1/2.
-    It might damage the source and/or the maya44 card.
-
-Mic/Line input: if switch is on, input jack 1/2 is microphone input (mono), otherwise line input (stereo).
-
-Bypass: analogue bypass from ADC input to output for channel 1+2. Same as "Monitor" in the windows driver.
-Bypass 1: same for channel 3+4.
-
-Crossmix: cross-mixer from channels 1+2 to channels 3+4
-Crossmix 1: cross-mixer from channels 3+4 to channels 1+2
-
-IEC958 Output: switch for S/PDIF output.
-    This is not supported by the ESI windows driver.
-    S/PDIF should output the same signal as channel 3+4. [untested!]
-
-
-Digitial output selectors:
-
-    These switches allow a direct digital routing from the ADCs to the DACs.
-    Each switch determines where the digital input data to one of the DACs comes from.
-    They are not supported by the ESI windows driver.
-    For normal operation, they should all be set to "PCM out".
-
-H/W: Output source channel 1
-H/W 1: Output source channel 2
-H/W 2: Output source channel 3
-H/W 3: Output source channel 4
-
-H/W 4 ... H/W 9: unknown function, left in to enable testing.
-    Possibly some of these control S/PDIF output(s).
-    If these turn out to be unused, they will go away in later driver versions.
-
-Selectable values for each of the digital output selectors are:
-   "PCM out" -> DAC output of the corresponding channel (default setting)
-   "Input 1"...
-   "Input 4" -> direct routing from ADC output of the selected input channel
-
-
---------
-
-Feb 14, 2008
-Rainer Zimmermann
-mail@lightshed.de
-
diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index 157372faae06..6c8e4141df9a 100644
--- a/Documentation/sound/cards/index.rst
+++ b/Documentation/sound/cards/index.rst
@@ -13,3 +13,4 @@ Card-Specific Information
    audiophile-usb
    mixart
    bt87x
+   maya44
diff --git a/Documentation/sound/cards/maya44.rst b/Documentation/sound/cards/maya44.rst
new file mode 100644
index 000000000000..bf09a584b443
--- /dev/null
+++ b/Documentation/sound/cards/maya44.rst
@@ -0,0 +1,186 @@
+=================================
+Notes on Maya44 USB Audio Support
+=================================
+
+.. note::
+   The following is the original document of Rainer's patch that the
+   current maya44 code based on.  Some contents might be obsoleted, but I
+   keep here as reference -- tiwai
+
+Feb 14, 2008
+
+Rainer Zimmermann 
+ 
+STATE OF DEVELOPMENT
+====================
+
+This driver is being developed on the initiative of Piotr Makowski (oponek@gmail.com) and financed by Lars Bergmann.
+Development is carried out by Rainer Zimmermann (mail@lightshed.de).
+
+ESI provided a sample Maya44 card for the development work.
+
+However, unfortunately it has turned out difficult to get detailed programming information, so I (Rainer Zimmermann) had to find out some card-specific information by experiment and conjecture. Some information (in particular, several GPIO bits) is still missing.
+
+This is the first testing version of the Maya44 driver released to the alsa-devel mailing list (Feb 5, 2008).
+
+
+The following functions work, as tested by Rainer Zimmermann and Piotr Makowski:
+
+- playback and capture at all sampling rates
+- input/output level
+- crossmixing
+- line/mic switch
+- phantom power switch
+- analogue monitor a.k.a bypass
+
+
+The following functions *should* work, but are not fully tested:
+
+- Channel 3+4 analogue - S/PDIF input switching
+- S/PDIF output
+- all inputs/outputs on the M/IO/DIO extension card
+- internal/external clock selection
+
+
+*In particular, we would appreciate testing of these functions by anyone who has access to an M/IO/DIO extension card.*
+
+
+Things that do not seem to work:
+
+- The level meters ("multi track") in 'alsamixer' do not seem to react to signals in (if this is a bug, it would probably be in the existing ICE1724 code).
+
+- Ardour 2.1 seems to work only via JACK, not using ALSA directly or via OSS. This still needs to be tracked down.
+
+
+DRIVER DETAILS
+==============
+
+the following files were added:
+
+* pci/ice1724/maya44.c - Maya44 specific code
+* pci/ice1724/maya44.h
+* pci/ice1724/ice1724.patch
+* pci/ice1724/ice1724.h.patch - PROPOSED patch to ice1724.h (see SAMPLING RATES)
+* i2c/other/wm8776.c - low-level access routines for Wolfson WM8776 codecs 
+* include/wm8776.h
+
+
+Note that the wm8776.c code is meant to be card-independent and does not actually register the codec with the ALSA infrastructure.
+This is done in maya44.c, mainly because some of the WM8776 controls are used in Maya44-specific ways, and should be named appropriately.
+
+
+the following files were created in pci/ice1724, simply #including the corresponding file from the alsa-kernel tree:
+
+* wtm.h
+* vt1720_mobo.h
+* revo.h
+* prodigy192.h
+* pontis.h
+* phase.h
+* maya44.h
+* juli.h
+* aureon.h
+* amp.h
+* envy24ht.h
+* se.h
+* prodigy_hifi.h
+
+
+*I hope this is the correct way to do things.*
+
+
+SAMPLING RATES
+==============
+
+The Maya44 card (or more exactly, the Wolfson WM8776 codecs) allow a maximum sampling rate of 192 kHz for playback and 92 kHz for capture.
+
+As the ICE1724 chip only allows one global sampling rate, this is handled as follows:
+
+* setting the sampling rate on any open PCM device on the maya44 card will always set the *global* sampling rate for all playback and capture channels.
+
+* In the current state of the driver, setting rates of up to 192 kHz is permitted even for capture devices.
+
+*AVOID CAPTURING AT RATES ABOVE 96kHz*, even though it may appear to work. The codec cannot actually capture at such rates, meaning poor quality.
+
+
+I propose some additional code for limiting the sampling rate when setting on a capture pcm device. However because of the global sampling rate, this logic would be somewhat problematic.
+
+The proposed code (currently deactivated) is in ice1712.h.patch, ice1724.c and maya44.c (in pci/ice1712).
+
+
+SOUND DEVICES
+=============
+
+PCM devices correspond to inputs/outputs as follows (assuming Maya44 is card #0):
+
+* hw:0,0 input - stereo, analog input 1+2
+* hw:0,0 output - stereo, analog output 1+2
+* hw:0,1 input - stereo, analog input 3+4 OR S/PDIF input
+* hw:0,1 output - stereo, analog output 3+4 (and SPDIF out)
+
+
+NAMING OF MIXER CONTROLS
+========================
+
+(for more information about the signal flow, please refer to the block diagram on p.24 of the ESI Maya44 manual, or in the ESI windows software).
+
+
+PCM
+    (digital) output level for channel 1+2
+PCM 1
+    same for channel 3+4
+
+Mic Phantom+48V
+    switch for +48V phantom power for electrostatic microphones on input 1/2.
+
+    Make sure this is not turned on while any other source is connected to input 1/2.
+    It might damage the source and/or the maya44 card.
+
+Mic/Line input
+    if switch is on, input jack 1/2 is microphone input (mono), otherwise line input (stereo).
+
+Bypass
+    analogue bypass from ADC input to output for channel 1+2. Same as "Monitor" in the windows driver.
+Bypass 1
+    same for channel 3+4.
+
+Crossmix
+    cross-mixer from channels 1+2 to channels 3+4
+Crossmix 1
+    cross-mixer from channels 3+4 to channels 1+2
+
+IEC958 Output
+    switch for S/PDIF output.
+
+    This is not supported by the ESI windows driver.
+    S/PDIF should output the same signal as channel 3+4. [untested!]
+
+
+Digitial output selectors
+    These switches allow a direct digital routing from the ADCs to the DACs.
+    Each switch determines where the digital input data to one of the DACs comes from.
+    They are not supported by the ESI windows driver.
+    For normal operation, they should all be set to "PCM out".
+
+H/W
+    Output source channel 1
+H/W 1
+    Output source channel 2
+H/W 2
+    Output source channel 3
+H/W 3
+    Output source channel 4
+
+H/W 4 ... H/W 9
+    unknown function, left in to enable testing.
+
+    Possibly some of these control S/PDIF output(s).
+    If these turn out to be unused, they will go away in later driver versions.
+
+Selectable values for each of the digital output selectors are:
+
+PCM out
+	DAC output of the corresponding channel (default setting)
+Input 1 ... Input 4
+	direct routing from ADC output of the selected input channel
+
-- 
cgit v1.2.3


From c79b5bb0a36f6290d38d9a4dc126cff5c7f44f2a Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 17:20:32 +0100
Subject: ALSA: doc: ReSTize hdspm.txt

A simple conversion from a plain text file.  Quite a few reformatting
in the end due to the style of the original document.

Put to cards directory.

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/hdspm.txt  | 362 ----------------------------------
 Documentation/sound/cards/hdspm.rst | 379 ++++++++++++++++++++++++++++++++++++
 Documentation/sound/cards/index.rst |   1 +
 3 files changed, 380 insertions(+), 362 deletions(-)
 delete mode 100644 Documentation/sound/alsa/hdspm.txt
 create mode 100644 Documentation/sound/cards/hdspm.rst

diff --git a/Documentation/sound/alsa/hdspm.txt b/Documentation/sound/alsa/hdspm.txt
deleted file mode 100644
index 7ba31948dea7..000000000000
--- a/Documentation/sound/alsa/hdspm.txt
+++ /dev/null
@@ -1,362 +0,0 @@
-Software Interface ALSA-DSP MADI Driver 
-
-(translated from German, so no good English ;-), 
-2004 - winfried ritsch
-
-
-
- Full functionality has been added to the driver. Since some of
- the Controls and startup-options  are ALSA-Standard and only the
- special Controls are described and discussed below.
-
-
- hardware functionality:
-
-   
-   Audio transmission:
-
-     number of channels --  depends on transmission mode
-
-		The number of channels chosen is from 1..Nmax. The reason to
-		use for a lower number of channels is only resource allocation,
-		since unused DMA channels are disabled and less memory is
-		allocated. So also the throughput of the PCI system can be
-		scaled. (Only important for low performance boards).
-
-       Single Speed -- 1..64 channels 
-
-		 (Note: Choosing the 56channel mode for transmission or as
-		 receiver, only 56 are transmitted/received over the MADI, but
-		 all 64 channels are available for the mixer, so channel count
-		 for the driver)
-
-       Double Speed -- 1..32 channels
-
-		 Note: Choosing the 56-channel mode for
-		 transmission/receive-mode , only 28 are transmitted/received
-		 over the MADI, but all 32 channels are available for the mixer,
-		 so channel count for the driver
-
-
-       Quad Speed -- 1..16 channels 
-
-		 Note: Choosing the 56-channel mode for
-		 transmission/receive-mode , only 14 are transmitted/received
-		 over the MADI, but all 16 channels are available for the mixer,
-		 so channel count for the driver
-
-     Format -- signed 32 Bit Little Endian (SNDRV_PCM_FMTBIT_S32_LE)
-
-     Sample Rates --
-
-       Single Speed -- 32000, 44100, 48000
-
-       Double Speed -- 64000, 88200, 96000 (untested)
-
-       Quad Speed -- 128000, 176400, 192000 (untested)
-
-     access-mode -- MMAP (memory mapped), Not interleaved
-     (PCM_NON-INTERLEAVED)
-
-     buffer-sizes -- 64,128,256,512,1024,2048,8192 Samples
-
-     fragments -- 2
-
-     Hardware-pointer -- 2 Modi
-
-
-		 The Card supports the readout of the actual Buffer-pointer,
-		 where DMA reads/writes. Since of the bulk mode of PCI it is only
-		 64 Byte accurate. SO it is not really usable for the
-		 ALSA-mid-level functions (here the buffer-ID gives a better
-		 result), but if MMAP is used by the application. Therefore it
-		 can be configured at load-time with the parameter
-		 precise-pointer.
-
-
-		 (Hint: Experimenting I found that the pointer is maximum 64 to
-		 large never to small. So if you subtract 64 you always have a
-		 safe pointer for writing, which is used on this mode inside
-		 ALSA. In theory now you can get now a latency as low as 16
-		 Samples, which is a quarter of the interrupt possibilities.)
-
-       Precise Pointer -- off
-					interrupt used for pointer-calculation
-
-       Precise Pointer -- on
-					hardware pointer used.
-
-   Controller:
-
-
-	  Since DSP-MADI-Mixer has 8152 Fader, it does not make sense to
-	  use the standard mixer-controls, since this would break most of
-	  (especially graphic) ALSA-Mixer GUIs. So Mixer control has be
-	  provided by a 2-dimensional controller using the
-	  hwdep-interface. 
-
-     Also all 128+256 Peak and RMS-Meter can be accessed via the
-     hwdep-interface. Since it could be a performance problem always
-     copying and converting Peak and RMS-Levels even if you just need
-     one, I decided to export the hardware structure, so that of
-     needed some driver-guru can implement a memory-mapping of mixer
-     or peak-meters over ioctl, or also to do only copying and no
-     conversion. A test-application shows the usage of the controller.
-
-    Latency Controls --- not implemented !!!
-
-
-	   Note: Within the windows-driver the latency is accessible of a
-	   control-panel, but buffer-sizes are controlled with ALSA from
-	   hwparams-calls and should not be changed in run-state, I did not
-	   implement it here.
-
-
-    System Clock -- suspended !!!!
-
-        Name -- "System Clock Mode"
-
-        Access -- Read Write
-
-        Values -- "Master" "Slave"
-
-
-		  !!!! This is a hardware-function but is in conflict with the
-		  Clock-source controller, which is a kind of ALSA-standard. I
-		  makes sense to set the card to a special mode (master at some
-		  frequency or slave), since even not using an Audio-application
-		  a studio should have working synchronisations setup. So use
-		  Clock-source-controller instead !!!!
-
-    Clock Source  
-
-       Name -- "Sample Clock Source"
-
-       Access -- Read Write
-
-       Values -- "AutoSync", "Internal 32.0 kHz", "Internal 44.1 kHz",
-       "Internal 48.0 kHz", "Internal 64.0 kHz", "Internal 88.2 kHz",
-       "Internal 96.0 kHz"
-
-		 Choose between Master at a specific Frequency and so also the
-		 Speed-mode or Slave (Autosync). Also see  "Preferred Sync Ref"
-
-
-       !!!! This is no pure hardware function but was implemented by
-       ALSA by some ALSA-drivers before, so I use it also. !!!
-
-
-    Preferred Sync Ref
-
-       Name -- "Preferred Sync Reference"
-
-       Access -- Read Write
-
-       Values -- "Word" "MADI"
-
-
-		 Within the Auto-sync-Mode the preferred Sync Source can be
-		 chosen. If it is not available another is used if possible.
-
-		 Note: Since MADI has a much higher bit-rate than word-clock, the
-		 card should synchronise better in MADI Mode. But since the
-		 RME-PLL is very good, there are almost no problems with
-		 word-clock too. I never found a difference.
-
-
-    TX 64 channel --- 
-
-       Name -- "TX 64 channels mode"
-
-       Access -- Read Write
-
-       Values -- 0 1
-
-		 Using 64-channel-modus (1) or 56-channel-modus for
-		 MADI-transmission (0).
-
-
-		 Note: This control is for output only. Input-mode is detected
-		 automatically from hardware sending MADI.
-
-
-    Clear TMS ---
-
-       Name -- "Clear Track Marker"
-
-       Access -- Read Write
-
-       Values -- 0 1
-
-
-		 Don't use to lower 5 Audio-bits on AES as additional Bits.
-        
-
-    Safe Mode oder Auto Input --- 
-
-       Name -- "Safe Mode"
-
-       Access -- Read Write
-
-       Values -- 0 1
-
-       (default on)
-
-		 If on (1), then if either the optical or coaxial connection
-		 has a failure, there is a takeover to the working one, with no
-		 sample failure. Its only useful if you use the second as a
-		 backup connection.
-
-    Input --- 
-
-       Name -- "Input Select"
-
-       Access -- Read Write
-
-       Values -- optical coaxial
-
-
-		 Choosing the Input, optical or coaxial. If Safe-mode is active,
-		 this is the preferred Input.
-
--------------- Mixer ----------------------
-
-    Mixer
-
-       Name -- "Mixer"
-
-       Access -- Read Write
-
-       Values -  
-
-
-		 Here as a first value the channel-index is taken to get/set the
-		 corresponding mixer channel, where 0-63 are the input to output
-		 fader and 64-127 the playback to outputs fader. Value 0
-		 is channel muted 0 and 32768 an amplification of  1.
-
-    Chn 1-64
-
-       fast mixer for the ALSA-mixer utils. The diagonal of the
-       mixer-matrix is implemented from playback to output.
-       
-
-    Line Out
-
-       Name  -- "Line Out"
-
-       Access -- Read Write
-
-       Values -- 0 1
-
-		 Switching on and off the analog out, which has nothing to do
-		 with mixing or routing. the analog outs reflects channel 63,64.
-
-
---- information (only read access):
- 
-    Sample Rate
-
-       Name -- "System Sample Rate"
-
-       Access -- Read-only
-
-		 getting the sample rate.
-
-
-    External Rate measured
-
-       Name -- "External Rate"
-
-       Access -- Read only
-
-
-		 Should be "Autosync Rate", but Name used is
-		 ALSA-Scheme. External Sample frequency liked used on Autosync is
-		 reported.
-
-
-    MADI Sync Status
-
-       Name -- "MADI Sync Lock Status"
-
-       Access -- Read
-
-       Values -- 0,1,2
-
-       MADI-Input is 0=Unlocked, 1=Locked, or 2=Synced.
-
-
-    Word Clock Sync Status
-
-       Name -- "Word Clock Lock Status"
-
-       Access -- Read
-
-       Values -- 0,1,2
-
-       Word Clock Input is 0=Unlocked, 1=Locked, or 2=Synced.
-
-    AutoSync
-
-       Name -- "AutoSync Reference"
-
-       Access -- Read
-
-       Values -- "WordClock", "MADI", "None"
-
-		 Sync-Reference is either "WordClock", "MADI" or none.
-
-   RX 64ch --- noch nicht implementiert
-
-       MADI-Receiver is in 64 channel mode oder 56 channel mode.
-
-
-   AB_inp   --- not tested 
-
-		 Used input for Auto-Input.
-
-
-   actual Buffer Position --- not implemented
-
-	   !!! this is a ALSA internal function, so no control is used !!!
-
-
-
-Calling Parameter:
-
-   index int array (min = 1, max = 8), 
-     "Index value for RME HDSPM interface." card-index within ALSA
-
-     note: ALSA-standard
-
-   id string array (min = 1, max = 8), 
-     "ID string for RME HDSPM interface."
-
-     note: ALSA-standard
-
-   enable int array (min = 1, max = 8), 
-     "Enable/disable specific HDSPM sound-cards."
-
-     note: ALSA-standard
-
-   precise_ptr int array (min = 1, max = 8), 
-     "Enable precise pointer, or disable."
-
-     note: Use only when the application supports this (which is a special case).
-
-   line_outs_monitor int array (min = 1, max = 8), 
-     "Send playback streams to analog outs by default."
-
-
-	  note: each playback channel is mixed to the same numbered output
-	  channel (routed). This is against the ALSA-convention, where all
-	  channels have to be muted on after loading the driver, but was
-	  used before on other cards, so i historically use it again)
-
-
-
-   enable_monitor int array (min = 1, max = 8), 
-     "Enable Analog Out on Channel 63/64 by default."
-
-      note: here the analog output is enabled (but not routed).
diff --git a/Documentation/sound/cards/hdspm.rst b/Documentation/sound/cards/hdspm.rst
new file mode 100644
index 000000000000..5373e51ed076
--- /dev/null
+++ b/Documentation/sound/cards/hdspm.rst
@@ -0,0 +1,379 @@
+=======================================
+Software Interface ALSA-DSP MADI Driver 
+=======================================
+
+(translated from German, so no good English ;-), 
+
+2004 - winfried ritsch
+
+
+Full functionality has been added to the driver. Since some of
+the Controls and startup-options  are ALSA-Standard and only the
+special Controls are described and discussed below.
+
+
+Hardware functionality
+======================
+   
+Audio transmission
+------------------
+
+* number of channels --  depends on transmission mode
+
+		The number of channels chosen is from 1..Nmax. The reason to
+		use for a lower number of channels is only resource allocation,
+		since unused DMA channels are disabled and less memory is
+		allocated. So also the throughput of the PCI system can be
+		scaled. (Only important for low performance boards).
+
+* Single Speed -- 1..64 channels 
+
+.. note::
+		 (Note: Choosing the 56channel mode for transmission or as
+		 receiver, only 56 are transmitted/received over the MADI, but
+		 all 64 channels are available for the mixer, so channel count
+		 for the driver)
+
+* Double Speed -- 1..32 channels
+
+.. note::
+		 Note: Choosing the 56-channel mode for
+		 transmission/receive-mode , only 28 are transmitted/received
+		 over the MADI, but all 32 channels are available for the mixer,
+		 so channel count for the driver
+
+
+* Quad Speed -- 1..16 channels 
+
+.. note::
+		 Choosing the 56-channel mode for
+		 transmission/receive-mode , only 14 are transmitted/received
+		 over the MADI, but all 16 channels are available for the mixer,
+		 so channel count for the driver
+
+* Format -- signed 32 Bit Little Endian (SNDRV_PCM_FMTBIT_S32_LE)
+
+* Sample Rates --
+
+       Single Speed -- 32000, 44100, 48000
+
+       Double Speed -- 64000, 88200, 96000 (untested)
+
+       Quad Speed -- 128000, 176400, 192000 (untested)
+
+* access-mode -- MMAP (memory mapped), Not interleaved (PCM_NON-INTERLEAVED)
+
+* buffer-sizes -- 64,128,256,512,1024,2048,8192 Samples
+
+* fragments -- 2
+
+* Hardware-pointer -- 2 Modi
+
+
+		 The Card supports the readout of the actual Buffer-pointer,
+		 where DMA reads/writes. Since of the bulk mode of PCI it is only
+		 64 Byte accurate. SO it is not really usable for the
+		 ALSA-mid-level functions (here the buffer-ID gives a better
+		 result), but if MMAP is used by the application. Therefore it
+		 can be configured at load-time with the parameter
+		 precise-pointer.
+
+
+.. hint::
+		 (Hint: Experimenting I found that the pointer is maximum 64 to
+		 large never to small. So if you subtract 64 you always have a
+		 safe pointer for writing, which is used on this mode inside
+		 ALSA. In theory now you can get now a latency as low as 16
+		 Samples, which is a quarter of the interrupt possibilities.)
+
+   * Precise Pointer -- off
+					interrupt used for pointer-calculation
+				
+   * Precise Pointer -- on
+					hardware pointer used.
+
+Controller
+----------
+
+Since DSP-MADI-Mixer has 8152 Fader, it does not make sense to
+use the standard mixer-controls, since this would break most of
+(especially graphic) ALSA-Mixer GUIs. So Mixer control has be
+provided by a 2-dimensional controller using the
+hwdep-interface. 
+
+Also all 128+256 Peak and RMS-Meter can be accessed via the
+hwdep-interface. Since it could be a performance problem always
+copying and converting Peak and RMS-Levels even if you just need
+one, I decided to export the hardware structure, so that of
+needed some driver-guru can implement a memory-mapping of mixer
+or peak-meters over ioctl, or also to do only copying and no
+conversion. A test-application shows the usage of the controller.
+
+* Latency Controls --- not implemented !!!
+
+.. note::
+	   Note: Within the windows-driver the latency is accessible of a
+	   control-panel, but buffer-sizes are controlled with ALSA from
+	   hwparams-calls and should not be changed in run-state, I did not
+	   implement it here.
+
+
+* System Clock -- suspended !!!!
+
+  * Name -- "System Clock Mode"
+
+  * Access -- Read Write
+    
+  * Values -- "Master" "Slave"
+
+.. note::
+		  !!!! This is a hardware-function but is in conflict with the
+		  Clock-source controller, which is a kind of ALSA-standard. I
+		  makes sense to set the card to a special mode (master at some
+		  frequency or slave), since even not using an Audio-application
+		  a studio should have working synchronisations setup. So use
+		  Clock-source-controller instead !!!!
+
+* Clock Source  
+
+  * Name -- "Sample Clock Source"
+
+  * Access -- Read Write
+
+  * Values -- "AutoSync", "Internal 32.0 kHz", "Internal 44.1 kHz",
+    "Internal 48.0 kHz", "Internal 64.0 kHz", "Internal 88.2 kHz",
+    "Internal 96.0 kHz"
+
+		 Choose between Master at a specific Frequency and so also the
+		 Speed-mode or Slave (Autosync). Also see  "Preferred Sync Ref"
+
+.. warning::
+       !!!! This is no pure hardware function but was implemented by
+       ALSA by some ALSA-drivers before, so I use it also. !!!
+
+
+* Preferred Sync Ref
+
+  * Name -- "Preferred Sync Reference"
+
+  * Access -- Read Write
+
+  * Values -- "Word" "MADI"
+
+
+		 Within the Auto-sync-Mode the preferred Sync Source can be
+		 chosen. If it is not available another is used if possible.
+
+.. note::
+		 Note: Since MADI has a much higher bit-rate than word-clock, the
+		 card should synchronise better in MADI Mode. But since the
+		 RME-PLL is very good, there are almost no problems with
+		 word-clock too. I never found a difference.
+
+
+* TX 64 channel
+
+  * Name -- "TX 64 channels mode"
+
+  * Access -- Read Write
+
+  * Values -- 0 1
+
+		 Using 64-channel-modus (1) or 56-channel-modus for
+		 MADI-transmission (0).
+
+
+.. note::
+		 Note: This control is for output only. Input-mode is detected
+		 automatically from hardware sending MADI.
+
+
+* Clear TMS
+
+  * Name -- "Clear Track Marker"
+
+  * Access -- Read Write
+
+  * Values -- 0 1
+
+
+		 Don't use to lower 5 Audio-bits on AES as additional Bits.
+        
+
+* Safe Mode oder Auto Input
+
+  * Name -- "Safe Mode"
+
+  * Access -- Read Write
+
+  * Values -- 0 1 (default on)
+
+		 If on (1), then if either the optical or coaxial connection
+		 has a failure, there is a takeover to the working one, with no
+		 sample failure. Its only useful if you use the second as a
+		 backup connection.
+
+* Input
+
+  * Name -- "Input Select"
+
+  * Access -- Read Write
+
+  * Values -- optical coaxial
+
+
+		 Choosing the Input, optical or coaxial. If Safe-mode is active,
+		 this is the preferred Input.
+
+Mixer
+-----
+
+* Mixer
+
+  * Name -- "Mixer"
+
+  * Access -- Read Write
+
+  * Values -  
+
+
+		 Here as a first value the channel-index is taken to get/set the
+		 corresponding mixer channel, where 0-63 are the input to output
+		 fader and 64-127 the playback to outputs fader. Value 0
+		 is channel muted 0 and 32768 an amplification of  1.
+
+* Chn 1-64
+
+       fast mixer for the ALSA-mixer utils. The diagonal of the
+       mixer-matrix is implemented from playback to output.
+       
+
+* Line Out
+
+  * Name  -- "Line Out"
+
+  * Access -- Read Write
+
+  * Values -- 0 1
+
+		 Switching on and off the analog out, which has nothing to do
+		 with mixing or routing. the analog outs reflects channel 63,64.
+
+
+Information (only read access)
+------------------------------
+ 
+* Sample Rate
+
+  * Name -- "System Sample Rate"
+
+  * Access -- Read-only
+
+		 getting the sample rate.
+
+
+* External Rate measured
+
+  * Name -- "External Rate"
+
+  * Access -- Read only
+
+
+		 Should be "Autosync Rate", but Name used is
+		 ALSA-Scheme. External Sample frequency liked used on Autosync is
+		 reported.
+
+
+* MADI Sync Status
+
+  * Name -- "MADI Sync Lock Status"
+
+  * Access -- Read
+
+  * Values -- 0,1,2
+
+       MADI-Input is 0=Unlocked, 1=Locked, or 2=Synced.
+
+
+* Word Clock Sync Status
+
+  * Name -- "Word Clock Lock Status"
+
+  * Access -- Read
+
+  * Values -- 0,1,2
+
+       Word Clock Input is 0=Unlocked, 1=Locked, or 2=Synced.
+
+* AutoSync
+
+  * Name -- "AutoSync Reference"
+
+  * Access -- Read
+
+  * Values -- "WordClock", "MADI", "None"
+
+		 Sync-Reference is either "WordClock", "MADI" or none.
+
+* RX 64ch --- noch nicht implementiert
+
+       MADI-Receiver is in 64 channel mode oder 56 channel mode.
+
+
+* AB_inp   --- not tested 
+
+		 Used input for Auto-Input.
+
+
+* actual Buffer Position --- not implemented
+
+	   !!! this is a ALSA internal function, so no control is used !!!
+
+
+
+Calling Parameter
+=================
+
+* index int array (min = 1, max = 8) 
+
+     Index value for RME HDSPM interface. card-index within ALSA
+
+     note: ALSA-standard
+
+* id string array (min = 1, max = 8) 
+
+     ID string for RME HDSPM interface.
+
+     note: ALSA-standard
+
+* enable int array (min = 1, max = 8)
+
+     Enable/disable specific HDSPM sound-cards.
+
+     note: ALSA-standard
+
+* precise_ptr int array (min = 1, max = 8)
+
+     Enable precise pointer, or disable.
+
+.. note::
+     note: Use only when the application supports this (which is a special case).
+
+* line_outs_monitor int array (min = 1, max = 8)
+
+     Send playback streams to analog outs by default.
+
+.. note::
+	  note: each playback channel is mixed to the same numbered output
+	  channel (routed). This is against the ALSA-convention, where all
+	  channels have to be muted on after loading the driver, but was
+	  used before on other cards, so i historically use it again)
+
+
+
+* enable_monitor int array (min = 1, max = 8)
+
+     Enable Analog Out on Channel 63/64 by default.
+
+.. note ::
+      note: here the analog output is enabled (but not routed).
diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index 6c8e4141df9a..b143eff93c87 100644
--- a/Documentation/sound/cards/index.rst
+++ b/Documentation/sound/cards/index.rst
@@ -14,3 +14,4 @@ Card-Specific Information
    mixart
    bt87x
    maya44
+   hdspm
-- 
cgit v1.2.3


From bb02859cd3448f31e00c47c1277e27be0cee7d2a Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 17:33:12 +0100
Subject: ALSA: doc: ReSTize serial-u16550.txt

Yet another simple conversion from a plain text file.
Put to cards directory.

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/serial-u16550.txt  | 88 ---------------------------
 Documentation/sound/cards/index.rst         |  1 +
 Documentation/sound/cards/serial-u16550.rst | 93 +++++++++++++++++++++++++++++
 3 files changed, 94 insertions(+), 88 deletions(-)
 delete mode 100644 Documentation/sound/alsa/serial-u16550.txt
 create mode 100644 Documentation/sound/cards/serial-u16550.rst

diff --git a/Documentation/sound/alsa/serial-u16550.txt b/Documentation/sound/alsa/serial-u16550.txt
deleted file mode 100644
index c1919559d509..000000000000
--- a/Documentation/sound/alsa/serial-u16550.txt
+++ /dev/null
@@ -1,88 +0,0 @@
-
-			Serial UART 16450/16550 MIDI driver
-			===================================
-
-The adaptor module parameter allows you to select either:
-
-  0 - Roland Soundcanvas support (default)
-  1 - Midiator MS-124T support (1)
-  2 - Midiator MS-124W S/A mode (2)
-  3 - MS-124W M/B mode support (3)
-  4 - Generic device with multiple input support (4)
-
-For the Midiator MS-124W, you must set the physical M-S and A-B
-switches on the Midiator to match the driver mode you select.
-
-In Roland Soundcanvas mode, multiple ALSA raw MIDI substreams are supported
-(midiCnD0-midiCnD15).  Whenever you write to a different substream, the driver
-sends the nonstandard MIDI command sequence F5 NN, where NN is the substream
-number plus 1.  Roland modules use this command to switch between different
-"parts", so this feature lets you treat each part as a distinct raw MIDI
-substream. The driver provides no way to send F5 00 (no selection) or to not
-send the F5 NN command sequence at all; perhaps it ought to.
-
-Usage example for simple serial converter:
-
-	/sbin/setserial /dev/ttyS0 uart none
-	/sbin/modprobe snd-serial-u16550 port=0x3f8 irq=4 speed=115200
-
-Usage example for Roland SoundCanvas with 4 MIDI ports:
-
-	/sbin/setserial /dev/ttyS0 uart none
-	/sbin/modprobe snd-serial-u16550 port=0x3f8 irq=4 outs=4
-
-In MS-124T mode, one raw MIDI substream is supported (midiCnD0); the outs
-module parameter is automatically set to 1. The driver sends the same data to
-all four MIDI Out connectors.  Set the A-B switch and the speed module
-parameter to match (A=19200, B=9600).
-
-Usage example for MS-124T, with A-B switch in A position:
-
-	/sbin/setserial /dev/ttyS0 uart none
-	/sbin/modprobe snd-serial-u16550 port=0x3f8 irq=4 adaptor=1 \
-			speed=19200
-
-In MS-124W S/A mode, one raw MIDI substream is supported (midiCnD0);
-the outs module parameter is automatically set to 1. The driver sends
-the same data to all four MIDI Out connectors at full MIDI speed.
-
-Usage example for S/A mode:
-
-	/sbin/setserial /dev/ttyS0 uart none
-	/sbin/modprobe snd-serial-u16550 port=0x3f8 irq=4 adaptor=2
-
-In MS-124W M/B mode, the driver supports 16 ALSA raw MIDI substreams;
-the outs module parameter is automatically set to 16.  The substream
-number gives a bitmask of which MIDI Out connectors the data should be
-sent to, with midiCnD1 sending to Out 1, midiCnD2 to Out 2, midiCnD4 to
-Out 3, and midiCnD8 to Out 4.  Thus midiCnD15 sends the data to all 4 ports.
-As a special case, midiCnD0 also sends to all ports, since it is not useful
-to send the data to no ports.  M/B mode has extra overhead to select the MIDI
-Out for each byte, so the aggregate data rate across all four MIDI Outs is
-at most one byte every 520 us, as compared with the full MIDI data rate of
-one byte every 320 us per port.
-
-Usage example for M/B mode:
-
-	/sbin/setserial /dev/ttyS0 uart none
-	/sbin/modprobe snd-serial-u16550 port=0x3f8 irq=4 adaptor=3
-
-The MS-124W hardware's M/A mode is currently not supported. This mode allows
-the MIDI Outs to act independently at double the aggregate throughput of M/B,
-but does not allow sending the same byte simultaneously to multiple MIDI Outs. 
-The M/A protocol requires the driver to twiddle the modem control lines under
-timing constraints, so it would be a bit more complicated to implement than
-the other modes.
-
-Midiator models other than MS-124W and MS-124T are currently not supported. 
-Note that the suffix letter is significant; the MS-124 and MS-124B are not
-compatible, nor are the other known models MS-101, MS-101B, MS-103, and MS-114.
-I do have documentation (tim.mann@compaq.com) that partially covers these models,
-but no units to experiment with.  The MS-124W support is tested with a real unit.
-The MS-124T support is untested, but should work.
-
-The Generic driver supports multiple input and output substreams over a single
-serial port.  Similar to Roland Soundcanvas mode, F5 NN is used to select the
-appropriate input or output stream (depending on the data direction).
-Additionally, the CTS signal is used to regulate the data flow.  The number of
-inputs is specified by the ins parameter.
diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index b143eff93c87..976ef5eb8f89 100644
--- a/Documentation/sound/cards/index.rst
+++ b/Documentation/sound/cards/index.rst
@@ -15,3 +15,4 @@ Card-Specific Information
    bt87x
    maya44
    hdspm
+   serial-u16550
diff --git a/Documentation/sound/cards/serial-u16550.rst b/Documentation/sound/cards/serial-u16550.rst
new file mode 100644
index 000000000000..197aeacea3da
--- /dev/null
+++ b/Documentation/sound/cards/serial-u16550.rst
@@ -0,0 +1,93 @@
+===================================
+Serial UART 16450/16550 MIDI driver
+===================================
+
+The adaptor module parameter allows you to select either:
+
+* 0 - Roland Soundcanvas support (default)
+* 1 - Midiator MS-124T support (1)
+* 2 - Midiator MS-124W S/A mode (2)
+* 3 - MS-124W M/B mode support (3)
+* 4 - Generic device with multiple input support (4)
+
+For the Midiator MS-124W, you must set the physical M-S and A-B
+switches on the Midiator to match the driver mode you select.
+
+In Roland Soundcanvas mode, multiple ALSA raw MIDI substreams are supported
+(midiCnD0-midiCnD15).  Whenever you write to a different substream, the driver
+sends the nonstandard MIDI command sequence F5 NN, where NN is the substream
+number plus 1.  Roland modules use this command to switch between different
+"parts", so this feature lets you treat each part as a distinct raw MIDI
+substream. The driver provides no way to send F5 00 (no selection) or to not
+send the F5 NN command sequence at all; perhaps it ought to.
+
+Usage example for simple serial converter:
+::
+
+	/sbin/setserial /dev/ttyS0 uart none
+	/sbin/modprobe snd-serial-u16550 port=0x3f8 irq=4 speed=115200
+
+Usage example for Roland SoundCanvas with 4 MIDI ports:
+::
+
+	/sbin/setserial /dev/ttyS0 uart none
+	/sbin/modprobe snd-serial-u16550 port=0x3f8 irq=4 outs=4
+
+In MS-124T mode, one raw MIDI substream is supported (midiCnD0); the outs
+module parameter is automatically set to 1. The driver sends the same data to
+all four MIDI Out connectors.  Set the A-B switch and the speed module
+parameter to match (A=19200, B=9600).
+
+Usage example for MS-124T, with A-B switch in A position:
+::
+
+	/sbin/setserial /dev/ttyS0 uart none
+	/sbin/modprobe snd-serial-u16550 port=0x3f8 irq=4 adaptor=1 \
+			speed=19200
+
+In MS-124W S/A mode, one raw MIDI substream is supported (midiCnD0);
+the outs module parameter is automatically set to 1. The driver sends
+the same data to all four MIDI Out connectors at full MIDI speed.
+
+Usage example for S/A mode:
+::
+
+	/sbin/setserial /dev/ttyS0 uart none
+	/sbin/modprobe snd-serial-u16550 port=0x3f8 irq=4 adaptor=2
+
+In MS-124W M/B mode, the driver supports 16 ALSA raw MIDI substreams;
+the outs module parameter is automatically set to 16.  The substream
+number gives a bitmask of which MIDI Out connectors the data should be
+sent to, with midiCnD1 sending to Out 1, midiCnD2 to Out 2, midiCnD4 to
+Out 3, and midiCnD8 to Out 4.  Thus midiCnD15 sends the data to all 4 ports.
+As a special case, midiCnD0 also sends to all ports, since it is not useful
+to send the data to no ports.  M/B mode has extra overhead to select the MIDI
+Out for each byte, so the aggregate data rate across all four MIDI Outs is
+at most one byte every 520 us, as compared with the full MIDI data rate of
+one byte every 320 us per port.
+
+Usage example for M/B mode:
+::
+
+	/sbin/setserial /dev/ttyS0 uart none
+	/sbin/modprobe snd-serial-u16550 port=0x3f8 irq=4 adaptor=3
+
+The MS-124W hardware's M/A mode is currently not supported. This mode allows
+the MIDI Outs to act independently at double the aggregate throughput of M/B,
+but does not allow sending the same byte simultaneously to multiple MIDI Outs. 
+The M/A protocol requires the driver to twiddle the modem control lines under
+timing constraints, so it would be a bit more complicated to implement than
+the other modes.
+
+Midiator models other than MS-124W and MS-124T are currently not supported. 
+Note that the suffix letter is significant; the MS-124 and MS-124B are not
+compatible, nor are the other known models MS-101, MS-101B, MS-103, and MS-114.
+I do have documentation (tim.mann@compaq.com) that partially covers these models,
+but no units to experiment with.  The MS-124W support is tested with a real unit.
+The MS-124T support is untested, but should work.
+
+The Generic driver supports multiple input and output substreams over a single
+serial port.  Similar to Roland Soundcanvas mode, F5 NN is used to select the
+appropriate input or output stream (depending on the data direction).
+Additionally, the CTS signal is used to regulate the data flow.  The number of
+inputs is specified by the ins parameter.
-- 
cgit v1.2.3


From f336c3f072216a16187b22069681d014dcb43db6 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 17:36:09 +0100
Subject: ALSA: doc: ReSTize img,spdif-in.txt

Yet another simple conversion from a plain text file.
Put to cards directory.

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/img,spdif-in.txt  | 49 ---------------------------
 Documentation/sound/cards/img-spdif-in.rst | 53 ++++++++++++++++++++++++++++++
 Documentation/sound/cards/index.rst        |  1 +
 3 files changed, 54 insertions(+), 49 deletions(-)
 delete mode 100644 Documentation/sound/alsa/img,spdif-in.txt
 create mode 100644 Documentation/sound/cards/img-spdif-in.rst

diff --git a/Documentation/sound/alsa/img,spdif-in.txt b/Documentation/sound/alsa/img,spdif-in.txt
deleted file mode 100644
index 8b7505785fa6..000000000000
--- a/Documentation/sound/alsa/img,spdif-in.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-The Imagination Technologies SPDIF Input controller contains the following
-controls:
-
-name='IEC958 Capture Mask',index=0
-
-This control returns a mask that shows which of the IEC958 status bits
-can be read using the 'IEC958 Capture Default' control.
-
-name='IEC958 Capture Default',index=0
-
-This control returns the status bits contained within the SPDIF stream that
-is being received. The 'IEC958 Capture Mask' shows which bits can be read
-from this control.
-
-name='SPDIF In Multi Frequency Acquire',index=0
-name='SPDIF In Multi Frequency Acquire',index=1
-name='SPDIF In Multi Frequency Acquire',index=2
-name='SPDIF In Multi Frequency Acquire',index=3
-
-This control is used to attempt acquisition of up to four different sample
-rates. The active rate can be obtained by reading the 'SPDIF In Lock Frequency'
-control.
-
-When the value of this control is set to {0,0,0,0}, the rate given to hw_params
-will determine the single rate the block will capture. Else, the rate given to
-hw_params will be ignored, and the block will attempt capture for each of the
-four sample rates set here.
-
-If less than four rates are required, the same rate can be specified more than
-once
-
-name='SPDIF In Lock Frequency',index=0
-
-This control returns the active capture rate, or 0 if a lock has not been
-acquired
-
-name='SPDIF In Lock TRK',index=0
-
-This control is used to modify the locking/jitter rejection characteristics
-of the block. Larger values increase the locking range, but reduce jitter
-rejection.
-
-name='SPDIF In Lock Acquire Threshold',index=0
-
-This control is used to change the threshold at which a lock is acquired.
-
-name='SPDIF In Lock Release Threshold',index=0
-
-This control is used to change the threshold at which a lock is released.
diff --git a/Documentation/sound/cards/img-spdif-in.rst b/Documentation/sound/cards/img-spdif-in.rst
new file mode 100644
index 000000000000..7df9f5ae2609
--- /dev/null
+++ b/Documentation/sound/cards/img-spdif-in.rst
@@ -0,0 +1,53 @@
+================================================
+Imagination Technologies SPDIF Input Controllers
+================================================
+
+The Imagination Technologies SPDIF Input controller contains the following
+controls:
+
+* name='IEC958 Capture Mask',index=0
+
+This control returns a mask that shows which of the IEC958 status bits
+can be read using the 'IEC958 Capture Default' control.
+
+* name='IEC958 Capture Default',index=0
+
+This control returns the status bits contained within the SPDIF stream that
+is being received. The 'IEC958 Capture Mask' shows which bits can be read
+from this control.
+
+* name='SPDIF In Multi Frequency Acquire',index=0
+* name='SPDIF In Multi Frequency Acquire',index=1
+* name='SPDIF In Multi Frequency Acquire',index=2
+* name='SPDIF In Multi Frequency Acquire',index=3
+
+This control is used to attempt acquisition of up to four different sample
+rates. The active rate can be obtained by reading the 'SPDIF In Lock Frequency'
+control.
+
+When the value of this control is set to {0,0,0,0}, the rate given to hw_params
+will determine the single rate the block will capture. Else, the rate given to
+hw_params will be ignored, and the block will attempt capture for each of the
+four sample rates set here.
+
+If less than four rates are required, the same rate can be specified more than
+once
+
+* name='SPDIF In Lock Frequency',index=0
+
+This control returns the active capture rate, or 0 if a lock has not been
+acquired
+
+* name='SPDIF In Lock TRK',index=0
+
+This control is used to modify the locking/jitter rejection characteristics
+of the block. Larger values increase the locking range, but reduce jitter
+rejection.
+
+* name='SPDIF In Lock Acquire Threshold',index=0
+
+This control is used to change the threshold at which a lock is acquired.
+
+* name='SPDIF In Lock Release Threshold',index=0
+
+This control is used to change the threshold at which a lock is released.
diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index 976ef5eb8f89..c016f8c3b88b 100644
--- a/Documentation/sound/cards/index.rst
+++ b/Documentation/sound/cards/index.rst
@@ -16,3 +16,4 @@ Card-Specific Information
    maya44
    hdspm
    serial-u16550
+   img-spdif-in
-- 
cgit v1.2.3


From 8e5336a14476e7350b0cf78a99541de6ed51655c Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 22:11:21 +0100
Subject: ASoC: doc: ReSTize overview.txt

A simple conversion from a plain text file.
Created a new subdirectory, Documentation/sound/soc, for this and
other ASoC documents.

Since the index page contains the TOC, so "Documentation" section got
removed from overview.

Acked-by: Mark Brown 
Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/soc/overview.txt | 95 -------------------------------
 Documentation/sound/index.rst             |  1 +
 Documentation/sound/soc/index.rst         | 10 ++++
 Documentation/sound/soc/overview.rst      | 69 ++++++++++++++++++++++
 4 files changed, 80 insertions(+), 95 deletions(-)
 delete mode 100644 Documentation/sound/alsa/soc/overview.txt
 create mode 100644 Documentation/sound/soc/index.rst
 create mode 100644 Documentation/sound/soc/overview.rst

diff --git a/Documentation/sound/alsa/soc/overview.txt b/Documentation/sound/alsa/soc/overview.txt
deleted file mode 100644
index f3f28b7ae242..000000000000
--- a/Documentation/sound/alsa/soc/overview.txt
+++ /dev/null
@@ -1,95 +0,0 @@
-ALSA SoC Layer
-==============
-
-The overall project goal of the ALSA System on Chip (ASoC) layer is to
-provide better ALSA support for embedded system-on-chip processors (e.g.
-pxa2xx, au1x00, iMX, etc) and portable audio codecs.  Prior to the ASoC
-subsystem there was some support in the kernel for SoC audio, however it
-had some limitations:-
-
-  * Codec drivers were often tightly coupled to the underlying SoC
-    CPU. This is not ideal and leads to code duplication - for example,
-    Linux had different wm8731 drivers for 4 different SoC platforms.
-
-  * There was no standard method to signal user initiated audio events (e.g.
-    Headphone/Mic insertion, Headphone/Mic detection after an insertion
-    event). These are quite common events on portable devices and often require
-    machine specific code to re-route audio, enable amps, etc., after such an
-    event.
-
-  * Drivers tended to power up the entire codec when playing (or
-    recording) audio. This is fine for a PC, but tends to waste a lot of
-    power on portable devices. There was also no support for saving
-    power via changing codec oversampling rates, bias currents, etc.
-
-
-ASoC Design
-===========
-
-The ASoC layer is designed to address these issues and provide the following
-features :-
-
-  * Codec independence. Allows reuse of codec drivers on other platforms
-    and machines.
-
-  * Easy I2S/PCM audio interface setup between codec and SoC. Each SoC
-    interface and codec registers its audio interface capabilities with the
-    core and are subsequently matched and configured when the application
-    hardware parameters are known.
-
-  * Dynamic Audio Power Management (DAPM). DAPM automatically sets the codec to
-    its minimum power state at all times. This includes powering up/down
-    internal power blocks depending on the internal codec audio routing and any
-    active streams.
-
-  * Pop and click reduction. Pops and clicks can be reduced by powering the
-    codec up/down in the correct sequence (including using digital mute). ASoC
-    signals the codec when to change power states.
-
-  * Machine specific controls: Allow machines to add controls to the sound card
-    (e.g. volume control for speaker amplifier).
-
-To achieve all this, ASoC basically splits an embedded audio system into
-multiple re-usable component drivers :-
-
-  * Codec class drivers: The codec class driver is platform independent and
-    contains audio controls, audio interface capabilities, codec DAPM
-    definition and codec IO functions. This class extends to BT, FM and MODEM
-    ICs if required. Codec class drivers should be generic code that can run
-    on any architecture and machine.
-
-  * Platform class drivers: The platform class driver includes the audio DMA
-    engine driver, digital audio interface (DAI) drivers (e.g. I2S, AC97, PCM)
-    and any audio DSP drivers for that platform.
-
-  * Machine class driver: The machine driver class acts as the glue that
-    describes and binds the other component drivers together to form an ALSA
-    "sound card device". It handles any machine specific controls and
-    machine level audio events (e.g. turning on an amp at start of playback).
-
-
-Documentation
-=============
-
-The documentation is spilt into the following sections:-
-
-overview.txt: This file.
-
-codec.txt: Codec driver internals.
-
-DAI.txt: Description of Digital Audio Interface standards and how to configure
-a DAI within your codec and CPU DAI drivers.
-
-dapm.txt: Dynamic Audio Power Management
-
-platform.txt: Platform audio DMA and DAI.
-
-machine.txt: Machine driver internals.
-
-pop_clicks.txt: How to minimise audio artifacts.
-
-clocking.txt: ASoC clocking for best power performance.
-
-jack.txt: ASoC jack detection.
-
-DPCM.txt: Dynamic PCM - Describes DPCM with DSP examples.
diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst
index 1f5d166f81c4..47b89f014e69 100644
--- a/Documentation/sound/index.rst
+++ b/Documentation/sound/index.rst
@@ -7,6 +7,7 @@ Linux Sound Subsystem Documentation
 
    kernel-api/index
    designs/index
+   soc/index
    alsa-configuration
    hd-audio/index
    cards/index
diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
new file mode 100644
index 000000000000..e974fd9f38a3
--- /dev/null
+++ b/Documentation/sound/soc/index.rst
@@ -0,0 +1,10 @@
+==============
+ALSA SoC Layer
+==============
+
+The documentation is spilt into the following sections:-
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
diff --git a/Documentation/sound/soc/overview.rst b/Documentation/sound/soc/overview.rst
new file mode 100644
index 000000000000..dc8370bbfff6
--- /dev/null
+++ b/Documentation/sound/soc/overview.rst
@@ -0,0 +1,69 @@
+=======================
+ALSA SoC Layer Overview
+=======================
+
+The overall project goal of the ALSA System on Chip (ASoC) layer is to
+provide better ALSA support for embedded system-on-chip processors (e.g.
+pxa2xx, au1x00, iMX, etc) and portable audio codecs.  Prior to the ASoC
+subsystem there was some support in the kernel for SoC audio, however it
+had some limitations:-
+
+  * Codec drivers were often tightly coupled to the underlying SoC
+    CPU. This is not ideal and leads to code duplication - for example,
+    Linux had different wm8731 drivers for 4 different SoC platforms.
+
+  * There was no standard method to signal user initiated audio events (e.g.
+    Headphone/Mic insertion, Headphone/Mic detection after an insertion
+    event). These are quite common events on portable devices and often require
+    machine specific code to re-route audio, enable amps, etc., after such an
+    event.
+
+  * Drivers tended to power up the entire codec when playing (or
+    recording) audio. This is fine for a PC, but tends to waste a lot of
+    power on portable devices. There was also no support for saving
+    power via changing codec oversampling rates, bias currents, etc.
+
+
+ASoC Design
+===========
+
+The ASoC layer is designed to address these issues and provide the following
+features :-
+
+  * Codec independence. Allows reuse of codec drivers on other platforms
+    and machines.
+
+  * Easy I2S/PCM audio interface setup between codec and SoC. Each SoC
+    interface and codec registers its audio interface capabilities with the
+    core and are subsequently matched and configured when the application
+    hardware parameters are known.
+
+  * Dynamic Audio Power Management (DAPM). DAPM automatically sets the codec to
+    its minimum power state at all times. This includes powering up/down
+    internal power blocks depending on the internal codec audio routing and any
+    active streams.
+
+  * Pop and click reduction. Pops and clicks can be reduced by powering the
+    codec up/down in the correct sequence (including using digital mute). ASoC
+    signals the codec when to change power states.
+
+  * Machine specific controls: Allow machines to add controls to the sound card
+    (e.g. volume control for speaker amplifier).
+
+To achieve all this, ASoC basically splits an embedded audio system into
+multiple re-usable component drivers :-
+
+  * Codec class drivers: The codec class driver is platform independent and
+    contains audio controls, audio interface capabilities, codec DAPM
+    definition and codec IO functions. This class extends to BT, FM and MODEM
+    ICs if required. Codec class drivers should be generic code that can run
+    on any architecture and machine.
+
+  * Platform class drivers: The platform class driver includes the audio DMA
+    engine driver, digital audio interface (DAI) drivers (e.g. I2S, AC97, PCM)
+    and any audio DSP drivers for that platform.
+
+  * Machine class driver: The machine driver class acts as the glue that
+    describes and binds the other component drivers together to form an ALSA
+    "sound card device". It handles any machine specific controls and
+    machine level audio events (e.g. turning on an amp at start of playback).
-- 
cgit v1.2.3


From 693ba474a39a2c22e1576995139c9bfdd8b554c8 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 22:16:04 +0100
Subject: ASoC: doc: ReSTize codec.txt

A simple conversion from a plain text file.
The section numbers are dropped to align with other documents.

Acked-by: Mark Brown 
Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/soc/codec.txt | 179 -------------------------------
 Documentation/sound/soc/codec.rst      | 190 +++++++++++++++++++++++++++++++++
 Documentation/sound/soc/index.rst      |   1 +
 3 files changed, 191 insertions(+), 179 deletions(-)
 delete mode 100644 Documentation/sound/alsa/soc/codec.txt
 create mode 100644 Documentation/sound/soc/codec.rst

diff --git a/Documentation/sound/alsa/soc/codec.txt b/Documentation/sound/alsa/soc/codec.txt
deleted file mode 100644
index db5f9c9ae149..000000000000
--- a/Documentation/sound/alsa/soc/codec.txt
+++ /dev/null
@@ -1,179 +0,0 @@
-ASoC Codec Class Driver
-=======================
-
-The codec class driver is generic and hardware independent code that configures
-the codec, FM, MODEM, BT or external DSP to provide audio capture and playback.
-It should contain no code that is specific to the target platform or machine.
-All platform and machine specific code should be added to the platform and
-machine drivers respectively.
-
-Each codec class driver *must* provide the following features:-
-
- 1) Codec DAI and PCM configuration
- 2) Codec control IO - using RegMap API
- 3) Mixers and audio controls
- 4) Codec audio operations
- 5) DAPM description.
- 6) DAPM event handler.
-
-Optionally, codec drivers can also provide:-
-
- 7) DAC Digital mute control.
-
-Its probably best to use this guide in conjunction with the existing codec
-driver code in sound/soc/codecs/
-
-ASoC Codec driver breakdown
-===========================
-
-1 - Codec DAI and PCM configuration
------------------------------------
-Each codec driver must have a struct snd_soc_dai_driver to define its DAI and
-PCM capabilities and operations. This struct is exported so that it can be
-registered with the core by your machine driver.
-
-e.g.
-
-static struct snd_soc_dai_ops wm8731_dai_ops = {
-	.prepare	= wm8731_pcm_prepare,
-	.hw_params	= wm8731_hw_params,
-	.shutdown	= wm8731_shutdown,
-	.digital_mute	= wm8731_mute,
-	.set_sysclk	= wm8731_set_dai_sysclk,
-	.set_fmt	= wm8731_set_dai_fmt,
-};
-
-struct snd_soc_dai_driver wm8731_dai = {
-	.name = "wm8731-hifi",
-	.playback = {
-		.stream_name = "Playback",
-		.channels_min = 1,
-		.channels_max = 2,
-		.rates = WM8731_RATES,
-		.formats = WM8731_FORMATS,},
-	.capture = {
-		.stream_name = "Capture",
-		.channels_min = 1,
-		.channels_max = 2,
-		.rates = WM8731_RATES,
-		.formats = WM8731_FORMATS,},
-	.ops = &wm8731_dai_ops,
-	.symmetric_rates = 1,
-};
-
-
-2 - Codec control IO
---------------------
-The codec can usually be controlled via an I2C or SPI style interface
-(AC97 combines control with data in the DAI). The codec driver should use the
-Regmap API for all codec IO. Please see include/linux/regmap.h and existing
-codec drivers for example regmap usage.
-
-
-3 - Mixers and audio controls
------------------------------
-All the codec mixers and audio controls can be defined using the convenience
-macros defined in soc.h.
-
-    #define SOC_SINGLE(xname, reg, shift, mask, invert)
-
-Defines a single control as follows:-
-
-  xname = Control name e.g. "Playback Volume"
-  reg = codec register
-  shift = control bit(s) offset in register
-  mask = control bit size(s) e.g. mask of 7 = 3 bits
-  invert = the control is inverted
-
-Other macros include:-
-
-    #define SOC_DOUBLE(xname, reg, shift_left, shift_right, mask, invert)
-
-A stereo control
-
-    #define SOC_DOUBLE_R(xname, reg_left, reg_right, shift, mask, invert)
-
-A stereo control spanning 2 registers
-
-    #define SOC_ENUM_SINGLE(xreg, xshift, xmask, xtexts)
-
-Defines an single enumerated control as follows:-
-
-   xreg = register
-   xshift = control bit(s) offset in register
-   xmask = control bit(s) size
-   xtexts = pointer to array of strings that describe each setting
-
-   #define SOC_ENUM_DOUBLE(xreg, xshift_l, xshift_r, xmask, xtexts)
-
-Defines a stereo enumerated control
-
-
-4 - Codec Audio Operations
---------------------------
-The codec driver also supports the following ALSA PCM operations:-
-
-/* SoC audio ops */
-struct snd_soc_ops {
-	int (*startup)(struct snd_pcm_substream *);
-	void (*shutdown)(struct snd_pcm_substream *);
-	int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *);
-	int (*hw_free)(struct snd_pcm_substream *);
-	int (*prepare)(struct snd_pcm_substream *);
-};
-
-Please refer to the ALSA driver PCM documentation for details.
-http://www.alsa-project.org/~iwai/writing-an-alsa-driver/
-
-
-5 - DAPM description.
----------------------
-The Dynamic Audio Power Management description describes the codec power
-components and their relationships and registers to the ASoC core.
-Please read dapm.txt for details of building the description.
-
-Please also see the examples in other codec drivers.
-
-
-6 - DAPM event handler
-----------------------
-This function is a callback that handles codec domain PM calls and system
-domain PM calls (e.g. suspend and resume). It is used to put the codec
-to sleep when not in use.
-
-Power states:-
-
-	SNDRV_CTL_POWER_D0: /* full On */
-	/* vref/mid, clk and osc on, active */
-
-	SNDRV_CTL_POWER_D1: /* partial On */
-	SNDRV_CTL_POWER_D2: /* partial On */
-
-	SNDRV_CTL_POWER_D3hot: /* Off, with power */
-	/* everything off except vref/vmid, inactive */
-
-	SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */
-
-
-7 - Codec DAC digital mute control
-----------------------------------
-Most codecs have a digital mute before the DACs that can be used to
-minimise any system noise.  The mute stops any digital data from
-entering the DAC.
-
-A callback can be created that is called by the core for each codec DAI
-when the mute is applied or freed.
-
-i.e.
-
-static int wm8974_mute(struct snd_soc_dai *dai, int mute)
-{
-	struct snd_soc_codec *codec = dai->codec;
-	u16 mute_reg = snd_soc_read(codec, WM8974_DAC) & 0xffbf;
-
-	if (mute)
-		snd_soc_write(codec, WM8974_DAC, mute_reg | 0x40);
-	else
-		snd_soc_write(codec, WM8974_DAC, mute_reg);
-	return 0;
-}
diff --git a/Documentation/sound/soc/codec.rst b/Documentation/sound/soc/codec.rst
new file mode 100644
index 000000000000..f87612b94812
--- /dev/null
+++ b/Documentation/sound/soc/codec.rst
@@ -0,0 +1,190 @@
+=======================
+ASoC Codec Class Driver
+=======================
+
+The codec class driver is generic and hardware independent code that configures
+the codec, FM, MODEM, BT or external DSP to provide audio capture and playback.
+It should contain no code that is specific to the target platform or machine.
+All platform and machine specific code should be added to the platform and
+machine drivers respectively.
+
+Each codec class driver *must* provide the following features:-
+
+1. Codec DAI and PCM configuration
+2. Codec control IO - using RegMap API
+3. Mixers and audio controls
+4. Codec audio operations
+5. DAPM description.
+6. DAPM event handler.
+
+Optionally, codec drivers can also provide:-
+
+7. DAC Digital mute control.
+
+Its probably best to use this guide in conjunction with the existing codec
+driver code in sound/soc/codecs/
+
+ASoC Codec driver breakdown
+===========================
+
+Codec DAI and PCM configuration
+-------------------------------
+Each codec driver must have a struct snd_soc_dai_driver to define its DAI and
+PCM capabilities and operations. This struct is exported so that it can be
+registered with the core by your machine driver.
+
+e.g.
+::
+
+  static struct snd_soc_dai_ops wm8731_dai_ops = {
+	.prepare	= wm8731_pcm_prepare,
+	.hw_params	= wm8731_hw_params,
+	.shutdown	= wm8731_shutdown,
+	.digital_mute	= wm8731_mute,
+	.set_sysclk	= wm8731_set_dai_sysclk,
+	.set_fmt	= wm8731_set_dai_fmt,
+  };
+  
+  struct snd_soc_dai_driver wm8731_dai = {
+	.name = "wm8731-hifi",
+	.playback = {
+		.stream_name = "Playback",
+		.channels_min = 1,
+		.channels_max = 2,
+		.rates = WM8731_RATES,
+		.formats = WM8731_FORMATS,},
+	.capture = {
+		.stream_name = "Capture",
+		.channels_min = 1,
+		.channels_max = 2,
+		.rates = WM8731_RATES,
+		.formats = WM8731_FORMATS,},
+	.ops = &wm8731_dai_ops,
+	.symmetric_rates = 1,
+  };
+
+
+Codec control IO
+----------------
+The codec can usually be controlled via an I2C or SPI style interface
+(AC97 combines control with data in the DAI). The codec driver should use the
+Regmap API for all codec IO. Please see include/linux/regmap.h and existing
+codec drivers for example regmap usage.
+
+
+Mixers and audio controls
+-------------------------
+All the codec mixers and audio controls can be defined using the convenience
+macros defined in soc.h.
+::
+
+    #define SOC_SINGLE(xname, reg, shift, mask, invert)
+
+Defines a single control as follows:-
+::
+
+  xname = Control name e.g. "Playback Volume"
+  reg = codec register
+  shift = control bit(s) offset in register
+  mask = control bit size(s) e.g. mask of 7 = 3 bits
+  invert = the control is inverted
+
+Other macros include:-
+::
+
+    #define SOC_DOUBLE(xname, reg, shift_left, shift_right, mask, invert)
+
+A stereo control
+::
+
+    #define SOC_DOUBLE_R(xname, reg_left, reg_right, shift, mask, invert)
+
+A stereo control spanning 2 registers
+::
+
+    #define SOC_ENUM_SINGLE(xreg, xshift, xmask, xtexts)
+
+Defines an single enumerated control as follows:-
+::
+
+   xreg = register
+   xshift = control bit(s) offset in register
+   xmask = control bit(s) size
+   xtexts = pointer to array of strings that describe each setting
+
+   #define SOC_ENUM_DOUBLE(xreg, xshift_l, xshift_r, xmask, xtexts)
+
+Defines a stereo enumerated control
+
+
+Codec Audio Operations
+----------------------
+The codec driver also supports the following ALSA PCM operations:-
+::
+
+  /* SoC audio ops */
+  struct snd_soc_ops {
+	int (*startup)(struct snd_pcm_substream *);
+	void (*shutdown)(struct snd_pcm_substream *);
+	int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *);
+	int (*hw_free)(struct snd_pcm_substream *);
+	int (*prepare)(struct snd_pcm_substream *);
+  };
+
+Please refer to the ALSA driver PCM documentation for details.
+http://www.alsa-project.org/~iwai/writing-an-alsa-driver/
+
+
+DAPM description
+----------------
+The Dynamic Audio Power Management description describes the codec power
+components and their relationships and registers to the ASoC core.
+Please read dapm.txt for details of building the description.
+
+Please also see the examples in other codec drivers.
+
+
+DAPM event handler
+------------------
+This function is a callback that handles codec domain PM calls and system
+domain PM calls (e.g. suspend and resume). It is used to put the codec
+to sleep when not in use.
+
+Power states:-
+::
+
+	SNDRV_CTL_POWER_D0: /* full On */
+	/* vref/mid, clk and osc on, active */
+
+	SNDRV_CTL_POWER_D1: /* partial On */
+	SNDRV_CTL_POWER_D2: /* partial On */
+
+	SNDRV_CTL_POWER_D3hot: /* Off, with power */
+	/* everything off except vref/vmid, inactive */
+
+	SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */
+
+
+Codec DAC digital mute control
+------------------------------
+Most codecs have a digital mute before the DACs that can be used to
+minimise any system noise.  The mute stops any digital data from
+entering the DAC.
+
+A callback can be created that is called by the core for each codec DAI
+when the mute is applied or freed.
+
+i.e.
+::
+
+  static int wm8974_mute(struct snd_soc_dai *dai, int mute)
+  {
+	struct snd_soc_codec *codec = dai->codec;
+	u16 mute_reg = snd_soc_read(codec, WM8974_DAC) & 0xffbf;
+
+	if (mute)
+		snd_soc_write(codec, WM8974_DAC, mute_reg | 0x40);
+	else
+		snd_soc_write(codec, WM8974_DAC, mute_reg);
+	return 0;
+  }
diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
index e974fd9f38a3..a2e023c91df2 100644
--- a/Documentation/sound/soc/index.rst
+++ b/Documentation/sound/soc/index.rst
@@ -8,3 +8,4 @@ The documentation is spilt into the following sections:-
    :maxdepth: 2
 
    overview
+   codec
-- 
cgit v1.2.3


From e732d1bcd452a040a18242d555996703465c1ca7 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 22:17:40 +0100
Subject: ASoC: doc: ReSTize DAI.txt

A simple conversion from a plain text file with slight reformatting /
corrections.

The file name was changed to lower letters to align with others.

Acked-by: Mark Brown 
Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/soc/DAI.txt | 56 -------------------------------
 Documentation/sound/soc/dai.rst      | 64 ++++++++++++++++++++++++++++++++++++
 Documentation/sound/soc/index.rst    |  1 +
 3 files changed, 65 insertions(+), 56 deletions(-)
 delete mode 100644 Documentation/sound/alsa/soc/DAI.txt
 create mode 100644 Documentation/sound/soc/dai.rst

diff --git a/Documentation/sound/alsa/soc/DAI.txt b/Documentation/sound/alsa/soc/DAI.txt
deleted file mode 100644
index c9679264c559..000000000000
--- a/Documentation/sound/alsa/soc/DAI.txt
+++ /dev/null
@@ -1,56 +0,0 @@
-ASoC currently supports the three main Digital Audio Interfaces (DAI) found on
-SoC controllers and portable audio CODECs today, namely AC97, I2S and PCM.
-
-
-AC97
-====
-
-  AC97 is a five wire interface commonly found on many PC sound cards. It is
-now also popular in many portable devices. This DAI has a reset line and time
-multiplexes its data on its SDATA_OUT (playback) and SDATA_IN (capture) lines.
-The bit clock (BCLK) is always driven by the CODEC (usually 12.288MHz) and the
-frame (FRAME) (usually 48kHz) is always driven by the controller. Each AC97
-frame is 21uS long and is divided into 13 time slots.
-
-The AC97 specification can be found at :-
-http://www.intel.com/p/en_US/business/design
-
-
-I2S
-===
-
- I2S is a common 4 wire DAI used in HiFi, STB and portable devices. The Tx and
-Rx lines are used for audio transmission, whilst the bit clock (BCLK) and
-left/right clock (LRC) synchronise the link. I2S is flexible in that either the
-controller or CODEC can drive (master) the BCLK and LRC clock lines. Bit clock
-usually varies depending on the sample rate and the master system clock
-(SYSCLK). LRCLK is the same as the sample rate. A few devices support separate
-ADC and DAC LRCLKs, this allows for simultaneous capture and playback at
-different sample rates.
-
-I2S has several different operating modes:-
-
- o I2S - MSB is transmitted on the falling edge of the first BCLK after LRC
-         transition.
-
- o Left Justified - MSB is transmitted on transition of LRC.
-
- o Right Justified - MSB is transmitted sample size BCLKs before LRC
-                     transition.
-
-PCM
-===
-
-PCM is another 4 wire interface, very similar to I2S, which can support a more
-flexible protocol. It has bit clock (BCLK) and sync (SYNC) lines that are used
-to synchronise the link whilst the Tx and Rx lines are used to transmit and
-receive the audio data. Bit clock usually varies depending on sample rate
-whilst sync runs at the sample rate. PCM also supports Time Division
-Multiplexing (TDM) in that several devices can use the bus simultaneously (this
-is sometimes referred to as network mode).
-
-Common PCM operating modes:-
-
- o Mode A - MSB is transmitted on falling edge of first BCLK after FRAME/SYNC.
-
- o Mode B - MSB is transmitted on rising edge of FRAME/SYNC.
diff --git a/Documentation/sound/soc/dai.rst b/Documentation/sound/soc/dai.rst
new file mode 100644
index 000000000000..55820e51708f
--- /dev/null
+++ b/Documentation/sound/soc/dai.rst
@@ -0,0 +1,64 @@
+==================================
+ASoC Digital Audio Interface (DAI)
+==================================
+
+ASoC currently supports the three main Digital Audio Interfaces (DAI) found on
+SoC controllers and portable audio CODECs today, namely AC97, I2S and PCM.
+
+
+AC97
+====
+
+AC97 is a five wire interface commonly found on many PC sound cards. It is
+now also popular in many portable devices. This DAI has a reset line and time
+multiplexes its data on its SDATA_OUT (playback) and SDATA_IN (capture) lines.
+The bit clock (BCLK) is always driven by the CODEC (usually 12.288MHz) and the
+frame (FRAME) (usually 48kHz) is always driven by the controller. Each AC97
+frame is 21uS long and is divided into 13 time slots.
+
+The AC97 specification can be found at :
+http://www.intel.com/p/en_US/business/design
+
+
+I2S
+===
+
+I2S is a common 4 wire DAI used in HiFi, STB and portable devices. The Tx and
+Rx lines are used for audio transmission, whilst the bit clock (BCLK) and
+left/right clock (LRC) synchronise the link. I2S is flexible in that either the
+controller or CODEC can drive (master) the BCLK and LRC clock lines. Bit clock
+usually varies depending on the sample rate and the master system clock
+(SYSCLK). LRCLK is the same as the sample rate. A few devices support separate
+ADC and DAC LRCLKs, this allows for simultaneous capture and playback at
+different sample rates.
+
+I2S has several different operating modes:-
+
+I2S
+  MSB is transmitted on the falling edge of the first BCLK after LRC
+  transition.
+
+Left Justified
+  MSB is transmitted on transition of LRC.
+
+Right Justified
+  MSB is transmitted sample size BCLKs before LRC transition.
+
+PCM
+===
+
+PCM is another 4 wire interface, very similar to I2S, which can support a more
+flexible protocol. It has bit clock (BCLK) and sync (SYNC) lines that are used
+to synchronise the link whilst the Tx and Rx lines are used to transmit and
+receive the audio data. Bit clock usually varies depending on sample rate
+whilst sync runs at the sample rate. PCM also supports Time Division
+Multiplexing (TDM) in that several devices can use the bus simultaneously (this
+is sometimes referred to as network mode).
+
+Common PCM operating modes:-
+
+Mode A
+  MSB is transmitted on falling edge of first BCLK after FRAME/SYNC.
+
+Mode B
+  MSB is transmitted on rising edge of FRAME/SYNC.
diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
index a2e023c91df2..aea7ae7e5aad 100644
--- a/Documentation/sound/soc/index.rst
+++ b/Documentation/sound/soc/index.rst
@@ -9,3 +9,4 @@ The documentation is spilt into the following sections:-
 
    overview
    codec
+   dai
-- 
cgit v1.2.3


From 77190f033377634bd494b67ca5a2dbcf685bd462 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 22:19:33 +0100
Subject: ASoC: doc: ReSTize dapm.txt

A simple conversion from a plain text file.
The section numbers and the item numbers are dropped to align with the
ReST format.  Some lists are converted to description lists to be
clearer.

Acked-by: Mark Brown 
Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/soc/dapm.txt | 305 ------------------------------
 Documentation/sound/soc/dapm.rst      | 342 ++++++++++++++++++++++++++++++++++
 Documentation/sound/soc/index.rst     |   1 +
 3 files changed, 343 insertions(+), 305 deletions(-)
 delete mode 100644 Documentation/sound/alsa/soc/dapm.txt
 create mode 100644 Documentation/sound/soc/dapm.rst

diff --git a/Documentation/sound/alsa/soc/dapm.txt b/Documentation/sound/alsa/soc/dapm.txt
deleted file mode 100644
index c45bd79f291e..000000000000
--- a/Documentation/sound/alsa/soc/dapm.txt
+++ /dev/null
@@ -1,305 +0,0 @@
-Dynamic Audio Power Management for Portable Devices
-===================================================
-
-1. Description
-==============
-
-Dynamic Audio Power Management (DAPM) is designed to allow portable
-Linux devices to use the minimum amount of power within the audio
-subsystem at all times. It is independent of other kernel PM and as
-such, can easily co-exist with the other PM systems.
-
-DAPM is also completely transparent to all user space applications as
-all power switching is done within the ASoC core. No code changes or
-recompiling are required for user space applications. DAPM makes power
-switching decisions based upon any audio stream (capture/playback)
-activity and audio mixer settings within the device.
-
-DAPM spans the whole machine. It covers power control within the entire
-audio subsystem, this includes internal codec power blocks and machine
-level power systems.
-
-There are 4 power domains within DAPM
-
-   1. Codec bias domain - VREF, VMID (core codec and audio power)
-      Usually controlled at codec probe/remove and suspend/resume, although
-      can be set at stream time if power is not needed for sidetone, etc.
-
-   2. Platform/Machine domain - physically connected inputs and outputs
-      Is platform/machine and user action specific, is configured by the
-      machine driver and responds to asynchronous events e.g when HP
-      are inserted
-
-   3. Path domain - audio subsystem signal paths
-      Automatically set when mixer and mux settings are changed by the user.
-      e.g. alsamixer, amixer.
-
-   4. Stream domain - DACs and ADCs.
-      Enabled and disabled when stream playback/capture is started and
-      stopped respectively. e.g. aplay, arecord.
-
-All DAPM power switching decisions are made automatically by consulting an audio
-routing map of the whole machine. This map is specific to each machine and
-consists of the interconnections between every audio component (including
-internal codec components). All audio components that effect power are called
-widgets hereafter.
-
-
-2. DAPM Widgets
-===============
-
-Audio DAPM widgets fall into a number of types:-
-
- o Mixer      - Mixes several analog signals into a single analog signal.
- o Mux        - An analog switch that outputs only one of many inputs.
- o PGA        - A programmable gain amplifier or attenuation widget.
- o ADC        - Analog to Digital Converter
- o DAC        - Digital to Analog Converter
- o Switch     - An analog switch
- o Input      - A codec input pin
- o Output     - A codec output pin
- o Headphone  - Headphone (and optional Jack)
- o Mic        - Mic (and optional Jack)
- o Line       - Line Input/Output (and optional Jack)
- o Speaker    - Speaker
- o Supply     - Power or clock supply widget used by other widgets.
- o Regulator  - External regulator that supplies power to audio components.
- o Clock      -	External clock that supplies clock to audio components.
- o AIF IN     - Audio Interface Input (with TDM slot mask).
- o AIF OUT    - Audio Interface Output (with TDM slot mask).
- o Siggen     - Signal Generator.
- o DAI IN     - Digital Audio Interface Input.
- o DAI OUT    - Digital Audio Interface Output.
- o DAI Link   - DAI Link between two DAI structures */
- o Pre        - Special PRE widget (exec before all others)
- o Post       - Special POST widget (exec after all others)
-
-(Widgets are defined in include/sound/soc-dapm.h)
-
-Widgets can be added to the sound card by any of the component driver types.
-There are convenience macros defined in soc-dapm.h that can be used to quickly
-build a list of widgets of the codecs and machines DAPM widgets.
-
-Most widgets have a name, register, shift and invert. Some widgets have extra
-parameters for stream name and kcontrols.
-
-
-2.1 Stream Domain Widgets
--------------------------
-
-Stream Widgets relate to the stream power domain and only consist of ADCs
-(analog to digital converters), DACs (digital to analog converters),
-AIF IN and AIF OUT.
-
-Stream widgets have the following format:-
-
-SND_SOC_DAPM_DAC(name, stream name, reg, shift, invert),
-SND_SOC_DAPM_AIF_IN(name, stream, slot, reg, shift, invert)
-
-NOTE: the stream name must match the corresponding stream name in your codec
-snd_soc_codec_dai.
-
-e.g. stream widgets for HiFi playback and capture
-
-SND_SOC_DAPM_DAC("HiFi DAC", "HiFi Playback", REG, 3, 1),
-SND_SOC_DAPM_ADC("HiFi ADC", "HiFi Capture", REG, 2, 1),
-
-e.g. stream widgets for AIF
-
-SND_SOC_DAPM_AIF_IN("AIF1RX", "AIF1 Playback", 0, SND_SOC_NOPM, 0, 0),
-SND_SOC_DAPM_AIF_OUT("AIF1TX", "AIF1 Capture", 0, SND_SOC_NOPM, 0, 0),
-
-
-2.2 Path Domain Widgets
------------------------
-
-Path domain widgets have a ability to control or affect the audio signal or
-audio paths within the audio subsystem. They have the following form:-
-
-SND_SOC_DAPM_PGA(name, reg, shift, invert, controls, num_controls)
-
-Any widget kcontrols can be set using the controls and num_controls members.
-
-e.g. Mixer widget (the kcontrols are declared first)
-
-/* Output Mixer */
-static const snd_kcontrol_new_t wm8731_output_mixer_controls[] = {
-SOC_DAPM_SINGLE("Line Bypass Switch", WM8731_APANA, 3, 1, 0),
-SOC_DAPM_SINGLE("Mic Sidetone Switch", WM8731_APANA, 5, 1, 0),
-SOC_DAPM_SINGLE("HiFi Playback Switch", WM8731_APANA, 4, 1, 0),
-};
-
-SND_SOC_DAPM_MIXER("Output Mixer", WM8731_PWR, 4, 1, wm8731_output_mixer_controls,
-	ARRAY_SIZE(wm8731_output_mixer_controls)),
-
-If you don't want the mixer elements prefixed with the name of the mixer widget,
-you can use SND_SOC_DAPM_MIXER_NAMED_CTL instead. the parameters are the same
-as for SND_SOC_DAPM_MIXER.
-
-
-2.3 Machine domain Widgets
---------------------------
-
-Machine widgets are different from codec widgets in that they don't have a
-codec register bit associated with them. A machine widget is assigned to each
-machine audio component (non codec or DSP) that can be independently
-powered. e.g.
-
- o Speaker Amp
- o Microphone Bias
- o Jack connectors
-
-A machine widget can have an optional call back.
-
-e.g. Jack connector widget for an external Mic that enables Mic Bias
-when the Mic is inserted:-
-
-static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event)
-{
-	gpio_set_value(SPITZ_GPIO_MIC_BIAS, SND_SOC_DAPM_EVENT_ON(event));
-	return 0;
-}
-
-SND_SOC_DAPM_MIC("Mic Jack", spitz_mic_bias),
-
-
-2.4 Codec (BIAS) Domain
------------------------
-
-The codec bias power domain has no widgets and is handled by the codecs DAPM
-event handler. This handler is called when the codec powerstate is changed wrt
-to any stream event or by kernel PM events.
-
-
-2.5 Virtual Widgets
--------------------
-
-Sometimes widgets exist in the codec or machine audio map that don't have any
-corresponding soft power control. In this case it is necessary to create
-a virtual widget - a widget with no control bits e.g.
-
-SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_DAPM_NOPM, 0, 0, NULL, 0),
-
-This can be used to merge to signal paths together in software.
-
-After all the widgets have been defined, they can then be added to the DAPM
-subsystem individually with a call to snd_soc_dapm_new_control().
-
-
-3. Codec/DSP Widget Interconnections
-====================================
-
-Widgets are connected to each other within the codec, platform and machine by
-audio paths (called interconnections). Each interconnection must be defined in
-order to create a map of all audio paths between widgets.
-
-This is easiest with a diagram of the codec or DSP (and schematic of the machine
-audio system), as it requires joining widgets together via their audio signal
-paths.
-
-e.g., from the WM8731 output mixer (wm8731.c)
-
-The WM8731 output mixer has 3 inputs (sources)
-
- 1. Line Bypass Input
- 2. DAC (HiFi playback)
- 3. Mic Sidetone Input
-
-Each input in this example has a kcontrol associated with it (defined in example
-above) and is connected to the output mixer via its kcontrol name. We can now
-connect the destination widget (wrt audio signal) with its source widgets.
-
-	/* output mixer */
-	{"Output Mixer", "Line Bypass Switch", "Line Input"},
-	{"Output Mixer", "HiFi Playback Switch", "DAC"},
-	{"Output Mixer", "Mic Sidetone Switch", "Mic Bias"},
-
-So we have :-
-
-	Destination Widget  <=== Path Name <=== Source Widget
-
-Or:-
-
-	Sink, Path, Source
-
-Or :-
-
-	"Output Mixer" is connected to the "DAC" via the "HiFi Playback Switch".
-
-When there is no path name connecting widgets (e.g. a direct connection) we
-pass NULL for the path name.
-
-Interconnections are created with a call to:-
-
-snd_soc_dapm_connect_input(codec, sink, path, source);
-
-Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and
-interconnections have been registered with the core. This causes the core to
-scan the codec and machine so that the internal DAPM state matches the
-physical state of the machine.
-
-
-3.1 Machine Widget Interconnections
------------------------------------
-Machine widget interconnections are created in the same way as codec ones and
-directly connect the codec pins to machine level widgets.
-
-e.g. connects the speaker out codec pins to the internal speaker.
-
-	/* ext speaker connected to codec pins LOUT2, ROUT2  */
-	{"Ext Spk", NULL , "ROUT2"},
-	{"Ext Spk", NULL , "LOUT2"},
-
-This allows the DAPM to power on and off pins that are connected (and in use)
-and pins that are NC respectively.
-
-
-4 Endpoint Widgets
-===================
-An endpoint is a start or end point (widget) of an audio signal within the
-machine and includes the codec. e.g.
-
- o Headphone Jack
- o Internal Speaker
- o Internal Mic
- o Mic Jack
- o Codec Pins
-
-Endpoints are added to the DAPM graph so that their usage can be determined in
-order to save power. e.g. NC codecs pins will be switched OFF, unconnected
-jacks can also be switched OFF.
-
-
-5 DAPM Widget Events
-====================
-
-Some widgets can register their interest with the DAPM core in PM events.
-e.g. A Speaker with an amplifier registers a widget so the amplifier can be
-powered only when the spk is in use.
-
-/* turn speaker amplifier on/off depending on use */
-static int corgi_amp_event(struct snd_soc_dapm_widget *w, int event)
-{
-	gpio_set_value(CORGI_GPIO_APM_ON, SND_SOC_DAPM_EVENT_ON(event));
-	return 0;
-}
-
-/* corgi machine dapm widgets */
-static const struct snd_soc_dapm_widget wm8731_dapm_widgets =
-	SND_SOC_DAPM_SPK("Ext Spk", corgi_amp_event);
-
-Please see soc-dapm.h for all other widgets that support events.
-
-
-5.1 Event types
----------------
-
-The following event types are supported by event widgets.
-
-/* dapm event types */
-#define SND_SOC_DAPM_PRE_PMU	0x1 	/* before widget power up */
-#define SND_SOC_DAPM_POST_PMU	0x2		/* after widget power up */
-#define SND_SOC_DAPM_PRE_PMD	0x4 	/* before widget power down */
-#define SND_SOC_DAPM_POST_PMD	0x8		/* after widget power down */
-#define SND_SOC_DAPM_PRE_REG	0x10	/* before audio path setup */
-#define SND_SOC_DAPM_POST_REG	0x20	/* after audio path setup */
diff --git a/Documentation/sound/soc/dapm.rst b/Documentation/sound/soc/dapm.rst
new file mode 100644
index 000000000000..a27f42befa4d
--- /dev/null
+++ b/Documentation/sound/soc/dapm.rst
@@ -0,0 +1,342 @@
+===================================================
+Dynamic Audio Power Management for Portable Devices
+===================================================
+
+Description
+===========
+
+Dynamic Audio Power Management (DAPM) is designed to allow portable
+Linux devices to use the minimum amount of power within the audio
+subsystem at all times. It is independent of other kernel PM and as
+such, can easily co-exist with the other PM systems.
+
+DAPM is also completely transparent to all user space applications as
+all power switching is done within the ASoC core. No code changes or
+recompiling are required for user space applications. DAPM makes power
+switching decisions based upon any audio stream (capture/playback)
+activity and audio mixer settings within the device.
+
+DAPM spans the whole machine. It covers power control within the entire
+audio subsystem, this includes internal codec power blocks and machine
+level power systems.
+
+There are 4 power domains within DAPM
+
+Codec bias domain
+      VREF, VMID (core codec and audio power)
+
+      Usually controlled at codec probe/remove and suspend/resume, although
+      can be set at stream time if power is not needed for sidetone, etc.
+
+Platform/Machine domain
+      physically connected inputs and outputs
+
+      Is platform/machine and user action specific, is configured by the
+      machine driver and responds to asynchronous events e.g when HP
+      are inserted
+
+Path domain
+      audio subsystem signal paths
+
+      Automatically set when mixer and mux settings are changed by the user.
+      e.g. alsamixer, amixer.
+
+Stream domain
+      DACs and ADCs.
+
+      Enabled and disabled when stream playback/capture is started and
+      stopped respectively. e.g. aplay, arecord.
+
+All DAPM power switching decisions are made automatically by consulting an audio
+routing map of the whole machine. This map is specific to each machine and
+consists of the interconnections between every audio component (including
+internal codec components). All audio components that effect power are called
+widgets hereafter.
+
+
+DAPM Widgets
+============
+
+Audio DAPM widgets fall into a number of types:-
+
+Mixer
+	Mixes several analog signals into a single analog signal.
+Mux
+	An analog switch that outputs only one of many inputs.
+PGA
+	A programmable gain amplifier or attenuation widget.
+ADC
+	Analog to Digital Converter
+DAC
+	Digital to Analog Converter
+Switch
+	An analog switch
+Input
+	A codec input pin
+Output
+	A codec output pin
+Headphone
+	Headphone (and optional Jack)
+Mic
+	Mic (and optional Jack)
+Line
+	Line Input/Output (and optional Jack)
+Speaker
+	Speaker
+Supply
+	Power or clock supply widget used by other widgets.
+Regulator
+	External regulator that supplies power to audio components.
+Clock
+	External clock that supplies clock to audio components.
+AIF IN
+	Audio Interface Input (with TDM slot mask).
+AIF OUT
+	Audio Interface Output (with TDM slot mask).
+Siggen
+	Signal Generator.
+DAI IN
+	Digital Audio Interface Input.
+DAI OUT
+	Digital Audio Interface Output.
+DAI Link
+	DAI Link between two DAI structures
+Pre
+	Special PRE widget (exec before all others)
+Post
+	Special POST widget (exec after all others)
+
+(Widgets are defined in include/sound/soc-dapm.h)
+
+Widgets can be added to the sound card by any of the component driver types.
+There are convenience macros defined in soc-dapm.h that can be used to quickly
+build a list of widgets of the codecs and machines DAPM widgets.
+
+Most widgets have a name, register, shift and invert. Some widgets have extra
+parameters for stream name and kcontrols.
+
+
+Stream Domain Widgets
+---------------------
+
+Stream Widgets relate to the stream power domain and only consist of ADCs
+(analog to digital converters), DACs (digital to analog converters),
+AIF IN and AIF OUT.
+
+Stream widgets have the following format:-
+::
+
+  SND_SOC_DAPM_DAC(name, stream name, reg, shift, invert),
+  SND_SOC_DAPM_AIF_IN(name, stream, slot, reg, shift, invert)
+
+NOTE: the stream name must match the corresponding stream name in your codec
+snd_soc_codec_dai.
+
+e.g. stream widgets for HiFi playback and capture
+::
+
+  SND_SOC_DAPM_DAC("HiFi DAC", "HiFi Playback", REG, 3, 1),
+  SND_SOC_DAPM_ADC("HiFi ADC", "HiFi Capture", REG, 2, 1),
+
+e.g. stream widgets for AIF
+::
+
+  SND_SOC_DAPM_AIF_IN("AIF1RX", "AIF1 Playback", 0, SND_SOC_NOPM, 0, 0),
+  SND_SOC_DAPM_AIF_OUT("AIF1TX", "AIF1 Capture", 0, SND_SOC_NOPM, 0, 0),
+
+
+Path Domain Widgets
+-------------------
+
+Path domain widgets have a ability to control or affect the audio signal or
+audio paths within the audio subsystem. They have the following form:-
+::
+
+  SND_SOC_DAPM_PGA(name, reg, shift, invert, controls, num_controls)
+
+Any widget kcontrols can be set using the controls and num_controls members.
+
+e.g. Mixer widget (the kcontrols are declared first)
+::
+
+  /* Output Mixer */
+  static const snd_kcontrol_new_t wm8731_output_mixer_controls[] = {
+  SOC_DAPM_SINGLE("Line Bypass Switch", WM8731_APANA, 3, 1, 0),
+  SOC_DAPM_SINGLE("Mic Sidetone Switch", WM8731_APANA, 5, 1, 0),
+  SOC_DAPM_SINGLE("HiFi Playback Switch", WM8731_APANA, 4, 1, 0),
+  };
+
+  SND_SOC_DAPM_MIXER("Output Mixer", WM8731_PWR, 4, 1, wm8731_output_mixer_controls,
+	ARRAY_SIZE(wm8731_output_mixer_controls)),
+
+If you don't want the mixer elements prefixed with the name of the mixer widget,
+you can use SND_SOC_DAPM_MIXER_NAMED_CTL instead. the parameters are the same
+as for SND_SOC_DAPM_MIXER.
+
+
+Machine domain Widgets
+----------------------
+
+Machine widgets are different from codec widgets in that they don't have a
+codec register bit associated with them. A machine widget is assigned to each
+machine audio component (non codec or DSP) that can be independently
+powered. e.g.
+
+* Speaker Amp
+* Microphone Bias
+* Jack connectors
+
+A machine widget can have an optional call back.
+
+e.g. Jack connector widget for an external Mic that enables Mic Bias
+when the Mic is inserted:-::
+
+  static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event)
+  {
+	gpio_set_value(SPITZ_GPIO_MIC_BIAS, SND_SOC_DAPM_EVENT_ON(event));
+	return 0;
+  }
+
+  SND_SOC_DAPM_MIC("Mic Jack", spitz_mic_bias),
+
+
+Codec (BIAS) Domain
+-------------------
+
+The codec bias power domain has no widgets and is handled by the codecs DAPM
+event handler. This handler is called when the codec powerstate is changed wrt
+to any stream event or by kernel PM events.
+
+
+Virtual Widgets
+---------------
+
+Sometimes widgets exist in the codec or machine audio map that don't have any
+corresponding soft power control. In this case it is necessary to create
+a virtual widget - a widget with no control bits e.g.
+::
+
+  SND_SOC_DAPM_MIXER("AC97 Mixer", SND_SOC_DAPM_NOPM, 0, 0, NULL, 0),
+
+This can be used to merge to signal paths together in software.
+
+After all the widgets have been defined, they can then be added to the DAPM
+subsystem individually with a call to snd_soc_dapm_new_control().
+
+
+Codec/DSP Widget Interconnections
+=================================
+
+Widgets are connected to each other within the codec, platform and machine by
+audio paths (called interconnections). Each interconnection must be defined in
+order to create a map of all audio paths between widgets.
+
+This is easiest with a diagram of the codec or DSP (and schematic of the machine
+audio system), as it requires joining widgets together via their audio signal
+paths.
+
+e.g., from the WM8731 output mixer (wm8731.c)
+
+The WM8731 output mixer has 3 inputs (sources)
+
+1. Line Bypass Input
+2. DAC (HiFi playback)
+3. Mic Sidetone Input
+
+Each input in this example has a kcontrol associated with it (defined in example
+above) and is connected to the output mixer via its kcontrol name. We can now
+connect the destination widget (wrt audio signal) with its source widgets.
+::
+
+	/* output mixer */
+	{"Output Mixer", "Line Bypass Switch", "Line Input"},
+	{"Output Mixer", "HiFi Playback Switch", "DAC"},
+	{"Output Mixer", "Mic Sidetone Switch", "Mic Bias"},
+
+So we have :-
+
+* Destination Widget  <=== Path Name <=== Source Widget, or
+* Sink, Path, Source, or
+* ``Output Mixer`` is connected to the ``DAC`` via the ``HiFi Playback Switch``.
+
+When there is no path name connecting widgets (e.g. a direct connection) we
+pass NULL for the path name.
+
+Interconnections are created with a call to:-
+::
+
+  snd_soc_dapm_connect_input(codec, sink, path, source);
+
+Finally, snd_soc_dapm_new_widgets(codec) must be called after all widgets and
+interconnections have been registered with the core. This causes the core to
+scan the codec and machine so that the internal DAPM state matches the
+physical state of the machine.
+
+
+Machine Widget Interconnections
+-------------------------------
+Machine widget interconnections are created in the same way as codec ones and
+directly connect the codec pins to machine level widgets.
+
+e.g. connects the speaker out codec pins to the internal speaker.
+::
+
+	/* ext speaker connected to codec pins LOUT2, ROUT2  */
+	{"Ext Spk", NULL , "ROUT2"},
+	{"Ext Spk", NULL , "LOUT2"},
+
+This allows the DAPM to power on and off pins that are connected (and in use)
+and pins that are NC respectively.
+
+
+Endpoint Widgets
+================
+An endpoint is a start or end point (widget) of an audio signal within the
+machine and includes the codec. e.g.
+
+* Headphone Jack
+* Internal Speaker
+* Internal Mic
+* Mic Jack
+* Codec Pins
+
+Endpoints are added to the DAPM graph so that their usage can be determined in
+order to save power. e.g. NC codecs pins will be switched OFF, unconnected
+jacks can also be switched OFF.
+
+
+DAPM Widget Events
+==================
+
+Some widgets can register their interest with the DAPM core in PM events.
+e.g. A Speaker with an amplifier registers a widget so the amplifier can be
+powered only when the spk is in use.
+::
+
+  /* turn speaker amplifier on/off depending on use */
+  static int corgi_amp_event(struct snd_soc_dapm_widget *w, int event)
+  {
+	gpio_set_value(CORGI_GPIO_APM_ON, SND_SOC_DAPM_EVENT_ON(event));
+	return 0;
+  }
+
+  /* corgi machine dapm widgets */
+  static const struct snd_soc_dapm_widget wm8731_dapm_widgets =
+	SND_SOC_DAPM_SPK("Ext Spk", corgi_amp_event);
+
+Please see soc-dapm.h for all other widgets that support events.
+
+
+Event types
+-----------
+
+The following event types are supported by event widgets.
+::
+
+  /* dapm event types */
+  #define SND_SOC_DAPM_PRE_PMU	0x1 	/* before widget power up */
+  #define SND_SOC_DAPM_POST_PMU	0x2		/* after widget power up */
+  #define SND_SOC_DAPM_PRE_PMD	0x4 	/* before widget power down */
+  #define SND_SOC_DAPM_POST_PMD	0x8		/* after widget power down */
+  #define SND_SOC_DAPM_PRE_REG	0x10	/* before audio path setup */
+  #define SND_SOC_DAPM_POST_REG	0x20	/* after audio path setup */
diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
index aea7ae7e5aad..0c0c38e582b4 100644
--- a/Documentation/sound/soc/index.rst
+++ b/Documentation/sound/soc/index.rst
@@ -10,3 +10,4 @@ The documentation is spilt into the following sections:-
    overview
    codec
    dai
+   dapm
-- 
cgit v1.2.3


From d8a5d624cc39c416f008e52b940f47cf619dbd9e Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 22:21:56 +0100
Subject: ASoC: doc: ReSTize platform.txt

A simple conversion from a plain text file.

Acked-by: Mark Brown 
Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/soc/platform.txt | 79 -----------------------------
 Documentation/sound/soc/index.rst         |  1 +
 Documentation/sound/soc/platform.rst      | 82 +++++++++++++++++++++++++++++++
 3 files changed, 83 insertions(+), 79 deletions(-)
 delete mode 100644 Documentation/sound/alsa/soc/platform.txt
 create mode 100644 Documentation/sound/soc/platform.rst

diff --git a/Documentation/sound/alsa/soc/platform.txt b/Documentation/sound/alsa/soc/platform.txt
deleted file mode 100644
index 3a08a2c9150c..000000000000
--- a/Documentation/sound/alsa/soc/platform.txt
+++ /dev/null
@@ -1,79 +0,0 @@
-ASoC Platform Driver
-====================
-
-An ASoC platform driver class can be divided into audio DMA drivers, SoC DAI
-drivers and DSP drivers. The platform drivers only target the SoC CPU and must
-have no board specific code.
-
-Audio DMA
-=========
-
-The platform DMA driver optionally supports the following ALSA operations:-
-
-/* SoC audio ops */
-struct snd_soc_ops {
-	int (*startup)(struct snd_pcm_substream *);
-	void (*shutdown)(struct snd_pcm_substream *);
-	int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *);
-	int (*hw_free)(struct snd_pcm_substream *);
-	int (*prepare)(struct snd_pcm_substream *);
-	int (*trigger)(struct snd_pcm_substream *, int);
-};
-
-The platform driver exports its DMA functionality via struct
-snd_soc_platform_driver:-
-
-struct snd_soc_platform_driver {
-	char *name;
-
-	int (*probe)(struct platform_device *pdev);
-	int (*remove)(struct platform_device *pdev);
-	int (*suspend)(struct platform_device *pdev, struct snd_soc_cpu_dai *cpu_dai);
-	int (*resume)(struct platform_device *pdev, struct snd_soc_cpu_dai *cpu_dai);
-
-	/* pcm creation and destruction */
-	int (*pcm_new)(struct snd_card *, struct snd_soc_codec_dai *, struct snd_pcm *);
-	void (*pcm_free)(struct snd_pcm *);
-
-	/*
-	 * For platform caused delay reporting.
-	 * Optional.
-	 */
-	snd_pcm_sframes_t (*delay)(struct snd_pcm_substream *,
-		struct snd_soc_dai *);
-
-	/* platform stream ops */
-	struct snd_pcm_ops *pcm_ops;
-};
-
-Please refer to the ALSA driver documentation for details of audio DMA.
-http://www.alsa-project.org/~iwai/writing-an-alsa-driver/
-
-An example DMA driver is soc/pxa/pxa2xx-pcm.c
-
-
-SoC DAI Drivers
-===============
-
-Each SoC DAI driver must provide the following features:-
-
- 1) Digital audio interface (DAI) description
- 2) Digital audio interface configuration
- 3) PCM's description
- 4) SYSCLK configuration
- 5) Suspend and resume (optional)
-
-Please see codec.txt for a description of items 1 - 4.
-
-
-SoC DSP Drivers
-===============
-
-Each SoC DSP driver usually supplies the following features :-
-
- 1) DAPM graph
- 2) Mixer controls
- 3) DMA IO to/from DSP buffers (if applicable)
- 4) Definition of DSP front end (FE) PCM devices.
-
-Please see DPCM.txt for a description of item 4.
diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
index 0c0c38e582b4..c5a55195bf4d 100644
--- a/Documentation/sound/soc/index.rst
+++ b/Documentation/sound/soc/index.rst
@@ -11,3 +11,4 @@ The documentation is spilt into the following sections:-
    codec
    dai
    dapm
+   platform
diff --git a/Documentation/sound/soc/platform.rst b/Documentation/sound/soc/platform.rst
new file mode 100644
index 000000000000..d5574904d981
--- /dev/null
+++ b/Documentation/sound/soc/platform.rst
@@ -0,0 +1,82 @@
+====================
+ASoC Platform Driver
+====================
+
+An ASoC platform driver class can be divided into audio DMA drivers, SoC DAI
+drivers and DSP drivers. The platform drivers only target the SoC CPU and must
+have no board specific code.
+
+Audio DMA
+=========
+
+The platform DMA driver optionally supports the following ALSA operations:-
+::
+
+  /* SoC audio ops */
+  struct snd_soc_ops {
+	int (*startup)(struct snd_pcm_substream *);
+	void (*shutdown)(struct snd_pcm_substream *);
+	int (*hw_params)(struct snd_pcm_substream *, struct snd_pcm_hw_params *);
+	int (*hw_free)(struct snd_pcm_substream *);
+	int (*prepare)(struct snd_pcm_substream *);
+	int (*trigger)(struct snd_pcm_substream *, int);
+  };
+
+The platform driver exports its DMA functionality via struct
+snd_soc_platform_driver:-
+::
+
+  struct snd_soc_platform_driver {
+	char *name;
+
+	int (*probe)(struct platform_device *pdev);
+	int (*remove)(struct platform_device *pdev);
+	int (*suspend)(struct platform_device *pdev, struct snd_soc_cpu_dai *cpu_dai);
+	int (*resume)(struct platform_device *pdev, struct snd_soc_cpu_dai *cpu_dai);
+
+	/* pcm creation and destruction */
+	int (*pcm_new)(struct snd_card *, struct snd_soc_codec_dai *, struct snd_pcm *);
+	void (*pcm_free)(struct snd_pcm *);
+
+	/*
+	 * For platform caused delay reporting.
+	 * Optional.
+	 */
+	snd_pcm_sframes_t (*delay)(struct snd_pcm_substream *,
+		struct snd_soc_dai *);
+
+	/* platform stream ops */
+	struct snd_pcm_ops *pcm_ops;
+  };
+
+Please refer to the ALSA driver documentation for details of audio DMA.
+http://www.alsa-project.org/~iwai/writing-an-alsa-driver/
+
+An example DMA driver is soc/pxa/pxa2xx-pcm.c
+
+
+SoC DAI Drivers
+===============
+
+Each SoC DAI driver must provide the following features:-
+
+1. Digital audio interface (DAI) description
+2. Digital audio interface configuration
+3. PCM's description
+4. SYSCLK configuration
+5. Suspend and resume (optional)
+
+Please see codec.txt for a description of items 1 - 4.
+
+
+SoC DSP Drivers
+===============
+
+Each SoC DSP driver usually supplies the following features :-
+
+1. DAPM graph
+2. Mixer controls
+3. DMA IO to/from DSP buffers (if applicable)
+4. Definition of DSP front end (FE) PCM devices.
+
+Please see DPCM.txt for a description of item 4.
-- 
cgit v1.2.3


From d9641c9d63909ab452405f0a6a3fd6177a4a6b6d Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 22:23:02 +0100
Subject: ASoC: doc: ReSTize machine.txt

A simple conversion from a plain text file.

Acked-by: Mark Brown 
Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/soc/machine.txt | 93 ------------------------------
 Documentation/sound/soc/index.rst        |  1 +
 Documentation/sound/soc/machine.rst      | 97 ++++++++++++++++++++++++++++++++
 3 files changed, 98 insertions(+), 93 deletions(-)
 delete mode 100644 Documentation/sound/alsa/soc/machine.txt
 create mode 100644 Documentation/sound/soc/machine.rst

diff --git a/Documentation/sound/alsa/soc/machine.txt b/Documentation/sound/alsa/soc/machine.txt
deleted file mode 100644
index 6bf2d2063b52..000000000000
--- a/Documentation/sound/alsa/soc/machine.txt
+++ /dev/null
@@ -1,93 +0,0 @@
-ASoC Machine Driver
-===================
-
-The ASoC machine (or board) driver is the code that glues together all the
-component drivers (e.g. codecs, platforms and DAIs). It also describes the
-relationships between each component which include audio paths, GPIOs,
-interrupts, clocking, jacks and voltage regulators.
-
-The machine driver can contain codec and platform specific code. It registers
-the audio subsystem with the kernel as a platform device and is represented by
-the following struct:-
-
-/* SoC machine */
-struct snd_soc_card {
-	char *name;
-
-	...
-
-	int (*probe)(struct platform_device *pdev);
-	int (*remove)(struct platform_device *pdev);
-
-	/* the pre and post PM functions are used to do any PM work before and
-	 * after the codec and DAIs do any PM work. */
-	int (*suspend_pre)(struct platform_device *pdev, pm_message_t state);
-	int (*suspend_post)(struct platform_device *pdev, pm_message_t state);
-	int (*resume_pre)(struct platform_device *pdev);
-	int (*resume_post)(struct platform_device *pdev);
-
-	...
-
-	/* CPU <--> Codec DAI links  */
-	struct snd_soc_dai_link *dai_link;
-	int num_links;
-
-	...
-};
-
-probe()/remove()
-----------------
-probe/remove are optional. Do any machine specific probe here.
-
-
-suspend()/resume()
-------------------
-The machine driver has pre and post versions of suspend and resume to take care
-of any machine audio tasks that have to be done before or after the codec, DAIs
-and DMA is suspended and resumed. Optional.
-
-
-Machine DAI Configuration
--------------------------
-The machine DAI configuration glues all the codec and CPU DAIs together. It can
-also be used to set up the DAI system clock and for any machine related DAI
-initialisation e.g. the machine audio map can be connected to the codec audio
-map, unconnected codec pins can be set as such.
-
-struct snd_soc_dai_link is used to set up each DAI in your machine. e.g.
-
-/* corgi digital audio interface glue - connects codec <--> CPU */
-static struct snd_soc_dai_link corgi_dai = {
-	.name = "WM8731",
-	.stream_name = "WM8731",
-	.cpu_dai_name = "pxa-is2-dai",
-	.codec_dai_name = "wm8731-hifi",
-	.platform_name = "pxa-pcm-audio",
-	.codec_name = "wm8713-codec.0-001a",
-	.init = corgi_wm8731_init,
-	.ops = &corgi_ops,
-};
-
-struct snd_soc_card then sets up the machine with its DAIs. e.g.
-
-/* corgi audio machine driver */
-static struct snd_soc_card snd_soc_corgi = {
-	.name = "Corgi",
-	.dai_link = &corgi_dai,
-	.num_links = 1,
-};
-
-
-Machine Power Map
------------------
-
-The machine driver can optionally extend the codec power map and to become an
-audio power map of the audio subsystem. This allows for automatic power up/down
-of speaker/HP amplifiers, etc. Codec pins can be connected to the machines jack
-sockets in the machine init function.
-
-
-Machine Controls
-----------------
-
-Machine specific audio mixer controls can be added in the DAI init function.
diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
index c5a55195bf4d..4ac3585e7dd1 100644
--- a/Documentation/sound/soc/index.rst
+++ b/Documentation/sound/soc/index.rst
@@ -12,3 +12,4 @@ The documentation is spilt into the following sections:-
    dai
    dapm
    platform
+   machine
diff --git a/Documentation/sound/soc/machine.rst b/Documentation/sound/soc/machine.rst
new file mode 100644
index 000000000000..515c9444deaf
--- /dev/null
+++ b/Documentation/sound/soc/machine.rst
@@ -0,0 +1,97 @@
+===================
+ASoC Machine Driver
+===================
+
+The ASoC machine (or board) driver is the code that glues together all the
+component drivers (e.g. codecs, platforms and DAIs). It also describes the
+relationships between each component which include audio paths, GPIOs,
+interrupts, clocking, jacks and voltage regulators.
+
+The machine driver can contain codec and platform specific code. It registers
+the audio subsystem with the kernel as a platform device and is represented by
+the following struct:-
+::
+
+  /* SoC machine */
+  struct snd_soc_card {
+	char *name;
+
+	...
+
+	int (*probe)(struct platform_device *pdev);
+	int (*remove)(struct platform_device *pdev);
+
+	/* the pre and post PM functions are used to do any PM work before and
+	 * after the codec and DAIs do any PM work. */
+	int (*suspend_pre)(struct platform_device *pdev, pm_message_t state);
+	int (*suspend_post)(struct platform_device *pdev, pm_message_t state);
+	int (*resume_pre)(struct platform_device *pdev);
+	int (*resume_post)(struct platform_device *pdev);
+
+	...
+
+	/* CPU <--> Codec DAI links  */
+	struct snd_soc_dai_link *dai_link;
+	int num_links;
+
+	...
+  };
+
+probe()/remove()
+----------------
+probe/remove are optional. Do any machine specific probe here.
+
+
+suspend()/resume()
+------------------
+The machine driver has pre and post versions of suspend and resume to take care
+of any machine audio tasks that have to be done before or after the codec, DAIs
+and DMA is suspended and resumed. Optional.
+
+
+Machine DAI Configuration
+-------------------------
+The machine DAI configuration glues all the codec and CPU DAIs together. It can
+also be used to set up the DAI system clock and for any machine related DAI
+initialisation e.g. the machine audio map can be connected to the codec audio
+map, unconnected codec pins can be set as such.
+
+struct snd_soc_dai_link is used to set up each DAI in your machine. e.g.
+::
+
+  /* corgi digital audio interface glue - connects codec <--> CPU */
+  static struct snd_soc_dai_link corgi_dai = {
+	.name = "WM8731",
+	.stream_name = "WM8731",
+	.cpu_dai_name = "pxa-is2-dai",
+	.codec_dai_name = "wm8731-hifi",
+	.platform_name = "pxa-pcm-audio",
+	.codec_name = "wm8713-codec.0-001a",
+	.init = corgi_wm8731_init,
+	.ops = &corgi_ops,
+  };
+
+struct snd_soc_card then sets up the machine with its DAIs. e.g.
+::
+
+  /* corgi audio machine driver */
+  static struct snd_soc_card snd_soc_corgi = {
+	.name = "Corgi",
+	.dai_link = &corgi_dai,
+	.num_links = 1,
+  };
+
+
+Machine Power Map
+-----------------
+
+The machine driver can optionally extend the codec power map and to become an
+audio power map of the audio subsystem. This allows for automatic power up/down
+of speaker/HP amplifiers, etc. Codec pins can be connected to the machines jack
+sockets in the machine init function.
+
+
+Machine Controls
+----------------
+
+Machine specific audio mixer controls can be added in the DAI init function.
-- 
cgit v1.2.3


From c9746eeafca3b5286a0355b895eb48af19d54d2d Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 22:23:58 +0100
Subject: ASoC: doc: ReSTize pops_clicks.txt

A simple conversion from a plain text file.
The file name was changed from "pops_clicks" to "pops-clicks" to align
with others.

Acked-by: Mark Brown 
Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/soc/pops_clicks.txt | 52 --------------------------
 Documentation/sound/soc/index.rst            |  1 +
 Documentation/sound/soc/pops-clicks.rst      | 55 ++++++++++++++++++++++++++++
 3 files changed, 56 insertions(+), 52 deletions(-)
 delete mode 100644 Documentation/sound/alsa/soc/pops_clicks.txt
 create mode 100644 Documentation/sound/soc/pops-clicks.rst

diff --git a/Documentation/sound/alsa/soc/pops_clicks.txt b/Documentation/sound/alsa/soc/pops_clicks.txt
deleted file mode 100644
index e1e74daa4497..000000000000
--- a/Documentation/sound/alsa/soc/pops_clicks.txt
+++ /dev/null
@@ -1,52 +0,0 @@
-Audio Pops and Clicks
-=====================
-
-Pops and clicks are unwanted audio artifacts caused by the powering up and down
-of components within the audio subsystem. This is noticeable on PCs when an
-audio module is either loaded or unloaded (at module load time the sound card is
-powered up and causes a popping noise on the speakers).
-
-Pops and clicks can be more frequent on portable systems with DAPM. This is
-because the components within the subsystem are being dynamically powered
-depending on the audio usage and this can subsequently cause a small pop or
-click every time a component power state is changed.
-
-
-Minimising Playback Pops and Clicks
-===================================
-
-Playback pops in portable audio subsystems cannot be completely eliminated
-currently, however future audio codec hardware will have better pop and click
-suppression.  Pops can be reduced within playback by powering the audio
-components in a specific order. This order is different for startup and
-shutdown and follows some basic rules:-
-
- Startup Order :- DAC --> Mixers --> Output PGA --> Digital Unmute
-
- Shutdown Order :- Digital Mute --> Output PGA --> Mixers --> DAC
-
-This assumes that the codec PCM output path from the DAC is via a mixer and then
-a PGA (programmable gain amplifier) before being output to the speakers.
-
-
-Minimising Capture Pops and Clicks
-==================================
-
-Capture artifacts are somewhat easier to get rid as we can delay activating the
-ADC until all the pops have occurred. This follows similar power rules to
-playback in that components are powered in a sequence depending upon stream
-startup or shutdown.
-
- Startup Order - Input PGA --> Mixers --> ADC
-
- Shutdown Order - ADC --> Mixers --> Input PGA
-
-
-Zipper Noise
-============
-An unwanted zipper noise can occur within the audio playback or capture stream
-when a volume control is changed near its maximum gain value. The zipper noise
-is heard when the gain increase or decrease changes the mean audio signal
-amplitude too quickly. It can be minimised by enabling the zero cross setting
-for each volume control. The ZC forces the gain change to occur when the signal
-crosses the zero amplitude line.
diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
index 4ac3585e7dd1..4dd679927a91 100644
--- a/Documentation/sound/soc/index.rst
+++ b/Documentation/sound/soc/index.rst
@@ -13,3 +13,4 @@ The documentation is spilt into the following sections:-
    dapm
    platform
    machine
+   pops-clicks
diff --git a/Documentation/sound/soc/pops-clicks.rst b/Documentation/sound/soc/pops-clicks.rst
new file mode 100644
index 000000000000..de7eb2a6604a
--- /dev/null
+++ b/Documentation/sound/soc/pops-clicks.rst
@@ -0,0 +1,55 @@
+=====================
+Audio Pops and Clicks
+=====================
+
+Pops and clicks are unwanted audio artifacts caused by the powering up and down
+of components within the audio subsystem. This is noticeable on PCs when an
+audio module is either loaded or unloaded (at module load time the sound card is
+powered up and causes a popping noise on the speakers).
+
+Pops and clicks can be more frequent on portable systems with DAPM. This is
+because the components within the subsystem are being dynamically powered
+depending on the audio usage and this can subsequently cause a small pop or
+click every time a component power state is changed.
+
+
+Minimising Playback Pops and Clicks
+===================================
+
+Playback pops in portable audio subsystems cannot be completely eliminated
+currently, however future audio codec hardware will have better pop and click
+suppression.  Pops can be reduced within playback by powering the audio
+components in a specific order. This order is different for startup and
+shutdown and follows some basic rules:-
+::
+
+   Startup Order :- DAC --> Mixers --> Output PGA --> Digital Unmute
+  
+   Shutdown Order :- Digital Mute --> Output PGA --> Mixers --> DAC
+
+This assumes that the codec PCM output path from the DAC is via a mixer and then
+a PGA (programmable gain amplifier) before being output to the speakers.
+
+
+Minimising Capture Pops and Clicks
+==================================
+
+Capture artifacts are somewhat easier to get rid as we can delay activating the
+ADC until all the pops have occurred. This follows similar power rules to
+playback in that components are powered in a sequence depending upon stream
+startup or shutdown.
+::
+
+   Startup Order - Input PGA --> Mixers --> ADC
+  
+   Shutdown Order - ADC --> Mixers --> Input PGA
+
+
+Zipper Noise
+============
+An unwanted zipper noise can occur within the audio playback or capture stream
+when a volume control is changed near its maximum gain value. The zipper noise
+is heard when the gain increase or decrease changes the mean audio signal
+amplitude too quickly. It can be minimised by enabling the zero cross setting
+for each volume control. The ZC forces the gain change to occur when the signal
+crosses the zero amplitude line.
-- 
cgit v1.2.3


From fb3df950833c1e8c39a82313942e6375f3f498c6 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 22:25:28 +0100
Subject: ASoC: doc: ReSTize clocking.txt

A simple conversion from a plain text file.

Acked-by: Mark Brown 
Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/soc/clocking.txt | 51 -------------------------------
 Documentation/sound/soc/clocking.rst      | 46 ++++++++++++++++++++++++++++
 Documentation/sound/soc/index.rst         |  1 +
 3 files changed, 47 insertions(+), 51 deletions(-)
 delete mode 100644 Documentation/sound/alsa/soc/clocking.txt
 create mode 100644 Documentation/sound/soc/clocking.rst

diff --git a/Documentation/sound/alsa/soc/clocking.txt b/Documentation/sound/alsa/soc/clocking.txt
deleted file mode 100644
index b1300162e01c..000000000000
--- a/Documentation/sound/alsa/soc/clocking.txt
+++ /dev/null
@@ -1,51 +0,0 @@
-Audio Clocking
-==============
-
-This text describes the audio clocking terms in ASoC and digital audio in
-general. Note: Audio clocking can be complex!
-
-
-Master Clock
-------------
-
-Every audio subsystem is driven by a master clock (sometimes referred to as MCLK
-or SYSCLK). This audio master clock can be derived from a number of sources
-(e.g. crystal, PLL, CPU clock) and is responsible for producing the correct
-audio playback and capture sample rates.
-
-Some master clocks (e.g. PLLs and CPU based clocks) are configurable in that
-their speed can be altered by software (depending on the system use and to save
-power). Other master clocks are fixed at a set frequency (i.e. crystals).
-
-
-DAI Clocks
-----------
-The Digital Audio Interface is usually driven by a Bit Clock (often referred to
-as BCLK). This clock is used to drive the digital audio data across the link
-between the codec and CPU.
-
-The DAI also has a frame clock to signal the start of each audio frame. This
-clock is sometimes referred to as LRC (left right clock) or FRAME. This clock
-runs at exactly the sample rate (LRC = Rate).
-
-Bit Clock can be generated as follows:-
-
-BCLK = MCLK / x
-
- or
-
-BCLK = LRC * x
-
- or
-
-BCLK = LRC * Channels * Word Size
-
-This relationship depends on the codec or SoC CPU in particular. In general
-it is best to configure BCLK to the lowest possible speed (depending on your
-rate, number of channels and word size) to save on power.
-
-It is also desirable to use the codec (if possible) to drive (or master) the
-audio clocks as it usually gives more accurate sample rates than the CPU.
-
-
-
diff --git a/Documentation/sound/soc/clocking.rst b/Documentation/sound/soc/clocking.rst
new file mode 100644
index 000000000000..32122d6877a3
--- /dev/null
+++ b/Documentation/sound/soc/clocking.rst
@@ -0,0 +1,46 @@
+==============
+Audio Clocking
+==============
+
+This text describes the audio clocking terms in ASoC and digital audio in
+general. Note: Audio clocking can be complex!
+
+
+Master Clock
+------------
+
+Every audio subsystem is driven by a master clock (sometimes referred to as MCLK
+or SYSCLK). This audio master clock can be derived from a number of sources
+(e.g. crystal, PLL, CPU clock) and is responsible for producing the correct
+audio playback and capture sample rates.
+
+Some master clocks (e.g. PLLs and CPU based clocks) are configurable in that
+their speed can be altered by software (depending on the system use and to save
+power). Other master clocks are fixed at a set frequency (i.e. crystals).
+
+
+DAI Clocks
+----------
+The Digital Audio Interface is usually driven by a Bit Clock (often referred to
+as BCLK). This clock is used to drive the digital audio data across the link
+between the codec and CPU.
+
+The DAI also has a frame clock to signal the start of each audio frame. This
+clock is sometimes referred to as LRC (left right clock) or FRAME. This clock
+runs at exactly the sample rate (LRC = Rate).
+
+Bit Clock can be generated as follows:-
+
+- BCLK = MCLK / x, or
+- BCLK = LRC * x, or
+- BCLK = LRC * Channels * Word Size
+
+This relationship depends on the codec or SoC CPU in particular. In general
+it is best to configure BCLK to the lowest possible speed (depending on your
+rate, number of channels and word size) to save on power.
+
+It is also desirable to use the codec (if possible) to drive (or master) the
+audio clocks as it usually gives more accurate sample rates than the CPU.
+
+
+
diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
index 4dd679927a91..0055abe16e7e 100644
--- a/Documentation/sound/soc/index.rst
+++ b/Documentation/sound/soc/index.rst
@@ -14,3 +14,4 @@ The documentation is spilt into the following sections:-
    platform
    machine
    pops-clicks
+   clocking
-- 
cgit v1.2.3


From 8155258a7d7600e7b92c6193cf23a11e281a9b0b Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 22:26:58 +0100
Subject: ASoC: doc: ReSTize jack.txt

A simple conversion from a plain text file.

Acked-by: Mark Brown 
Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/soc/jack.txt | 71 ----------------------------------
 Documentation/sound/soc/index.rst     |  1 +
 Documentation/sound/soc/jack.rst      | 72 +++++++++++++++++++++++++++++++++++
 3 files changed, 73 insertions(+), 71 deletions(-)
 delete mode 100644 Documentation/sound/alsa/soc/jack.txt
 create mode 100644 Documentation/sound/soc/jack.rst

diff --git a/Documentation/sound/alsa/soc/jack.txt b/Documentation/sound/alsa/soc/jack.txt
deleted file mode 100644
index fcf82a417293..000000000000
--- a/Documentation/sound/alsa/soc/jack.txt
+++ /dev/null
@@ -1,71 +0,0 @@
-ASoC jack detection
-===================
-
-ALSA has a standard API for representing physical jacks to user space,
-the kernel side of which can be seen in include/sound/jack.h.  ASoC
-provides a version of this API adding two additional features:
-
- - It allows more than one jack detection method to work together on one
-   user visible jack.  In embedded systems it is common for multiple
-   to be present on a single jack but handled by separate bits of
-   hardware.
-
- - Integration with DAPM, allowing DAPM endpoints to be updated
-   automatically based on the detected jack status (eg, turning off the
-   headphone outputs if no headphones are present).
-
-This is done by splitting the jacks up into three things working
-together: the jack itself represented by a struct snd_soc_jack, sets of
-snd_soc_jack_pins representing DAPM endpoints to update and blocks of
-code providing jack reporting mechanisms.
-
-For example, a system may have a stereo headset jack with two reporting
-mechanisms, one for the headphone and one for the microphone.  Some
-systems won't be able to use their speaker output while a headphone is
-connected and so will want to make sure to update both speaker and
-headphone when the headphone jack status changes.
-
-The jack - struct snd_soc_jack
-==============================
-
-This represents a physical jack on the system and is what is visible to
-user space.  The jack itself is completely passive, it is set up by the
-machine driver and updated by jack detection methods.
-
-Jacks are created by the machine driver calling snd_soc_jack_new().
-
-snd_soc_jack_pin
-================
-
-These represent a DAPM pin to update depending on some of the status
-bits supported by the jack.  Each snd_soc_jack has zero or more of these
-which are updated automatically.  They are created by the machine driver
-and associated with the jack using snd_soc_jack_add_pins().  The status
-of the endpoint may configured to be the opposite of the jack status if
-required (eg, enabling a built in microphone if a microphone is not
-connected via a jack).
-
-Jack detection methods
-======================
-
-Actual jack detection is done by code which is able to monitor some
-input to the system and update a jack by calling snd_soc_jack_report(),
-specifying a subset of bits to update.  The jack detection code should
-be set up by the machine driver, taking configuration for the jack to
-update and the set of things to report when the jack is connected.
-
-Often this is done based on the status of a GPIO - a handler for this is
-provided by the snd_soc_jack_add_gpio() function.  Other methods are
-also available, for example integrated into CODECs.  One example of
-CODEC integrated jack detection can be see in the WM8350 driver.
-
-Each jack may have multiple reporting mechanisms, though it will need at
-least one to be useful.
-
-Machine drivers
-===============
-
-These are all hooked together by the machine driver depending on the
-system hardware.  The machine driver will set up the snd_soc_jack and
-the list of pins to update then set up one or more jack detection
-mechanisms to update that jack based on their current status.
diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
index 0055abe16e7e..85ec51764e83 100644
--- a/Documentation/sound/soc/index.rst
+++ b/Documentation/sound/soc/index.rst
@@ -15,3 +15,4 @@ The documentation is spilt into the following sections:-
    machine
    pops-clicks
    clocking
+   jack
diff --git a/Documentation/sound/soc/jack.rst b/Documentation/sound/soc/jack.rst
new file mode 100644
index 000000000000..644b99ecba35
--- /dev/null
+++ b/Documentation/sound/soc/jack.rst
@@ -0,0 +1,72 @@
+===================
+ASoC jack detection
+===================
+
+ALSA has a standard API for representing physical jacks to user space,
+the kernel side of which can be seen in include/sound/jack.h.  ASoC
+provides a version of this API adding two additional features:
+
+ - It allows more than one jack detection method to work together on one
+   user visible jack.  In embedded systems it is common for multiple
+   to be present on a single jack but handled by separate bits of
+   hardware.
+
+ - Integration with DAPM, allowing DAPM endpoints to be updated
+   automatically based on the detected jack status (eg, turning off the
+   headphone outputs if no headphones are present).
+
+This is done by splitting the jacks up into three things working
+together: the jack itself represented by a struct snd_soc_jack, sets of
+snd_soc_jack_pins representing DAPM endpoints to update and blocks of
+code providing jack reporting mechanisms.
+
+For example, a system may have a stereo headset jack with two reporting
+mechanisms, one for the headphone and one for the microphone.  Some
+systems won't be able to use their speaker output while a headphone is
+connected and so will want to make sure to update both speaker and
+headphone when the headphone jack status changes.
+
+The jack - struct snd_soc_jack
+==============================
+
+This represents a physical jack on the system and is what is visible to
+user space.  The jack itself is completely passive, it is set up by the
+machine driver and updated by jack detection methods.
+
+Jacks are created by the machine driver calling snd_soc_jack_new().
+
+snd_soc_jack_pin
+================
+
+These represent a DAPM pin to update depending on some of the status
+bits supported by the jack.  Each snd_soc_jack has zero or more of these
+which are updated automatically.  They are created by the machine driver
+and associated with the jack using snd_soc_jack_add_pins().  The status
+of the endpoint may configured to be the opposite of the jack status if
+required (eg, enabling a built in microphone if a microphone is not
+connected via a jack).
+
+Jack detection methods
+======================
+
+Actual jack detection is done by code which is able to monitor some
+input to the system and update a jack by calling snd_soc_jack_report(),
+specifying a subset of bits to update.  The jack detection code should
+be set up by the machine driver, taking configuration for the jack to
+update and the set of things to report when the jack is connected.
+
+Often this is done based on the status of a GPIO - a handler for this is
+provided by the snd_soc_jack_add_gpio() function.  Other methods are
+also available, for example integrated into CODECs.  One example of
+CODEC integrated jack detection can be see in the WM8350 driver.
+
+Each jack may have multiple reporting mechanisms, though it will need at
+least one to be useful.
+
+Machine drivers
+===============
+
+These are all hooked together by the machine driver depending on the
+system hardware.  The machine driver will set up the snd_soc_jack and
+the list of pins to update then set up one or more jack detection
+mechanisms to update that jack based on their current status.
-- 
cgit v1.2.3


From 40433cd34e280bd1a56f54a3898e86863814c824 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 22:29:49 +0100
Subject: ASoC: doc: ReSTize DPCM.txt

A simple conversion from a plain text file.
The file name was renamed to lower letters to align with others.

Acked-by: Mark Brown 
Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/soc/DPCM.txt | 380 --------------------------------
 Documentation/sound/soc/dpcm.rst      | 392 ++++++++++++++++++++++++++++++++++
 Documentation/sound/soc/index.rst     |   1 +
 3 files changed, 393 insertions(+), 380 deletions(-)
 delete mode 100644 Documentation/sound/alsa/soc/DPCM.txt
 create mode 100644 Documentation/sound/soc/dpcm.rst

diff --git a/Documentation/sound/alsa/soc/DPCM.txt b/Documentation/sound/alsa/soc/DPCM.txt
deleted file mode 100644
index 0110180b7ac6..000000000000
--- a/Documentation/sound/alsa/soc/DPCM.txt
+++ /dev/null
@@ -1,380 +0,0 @@
-Dynamic PCM
-===========
-
-1. Description
-==============
-
-Dynamic PCM allows an ALSA PCM device to digitally route its PCM audio to
-various digital endpoints during the PCM stream runtime. e.g. PCM0 can route
-digital audio to I2S DAI0, I2S DAI1 or PDM DAI2. This is useful for on SoC DSP
-drivers that expose several ALSA PCMs and can route to multiple DAIs.
-
-The DPCM runtime routing is determined by the ALSA mixer settings in the same
-way as the analog signal is routed in an ASoC codec driver. DPCM uses a DAPM
-graph representing the DSP internal audio paths and uses the mixer settings to
-determine the patch used by each ALSA PCM.
-
-DPCM re-uses all the existing component codec, platform and DAI drivers without
-any modifications.
-
-
-Phone Audio System with SoC based DSP
--------------------------------------
-
-Consider the following phone audio subsystem. This will be used in this
-document for all examples :-
-
-| Front End PCMs    |  SoC DSP  | Back End DAIs | Audio devices |
-
-                    *************
-PCM0 <------------> *           * <----DAI0-----> Codec Headset
-                    *           *
-PCM1 <------------> *           * <----DAI1-----> Codec Speakers
-                    *   DSP     *
-PCM2 <------------> *           * <----DAI2-----> MODEM
-                    *           *
-PCM3 <------------> *           * <----DAI3-----> BT
-                    *           *
-                    *           * <----DAI4-----> DMIC
-                    *           *
-                    *           * <----DAI5-----> FM
-                    *************
-
-This diagram shows a simple smart phone audio subsystem. It supports Bluetooth,
-FM digital radio, Speakers, Headset Jack, digital microphones and cellular
-modem. This sound card exposes 4 DSP front end (FE) ALSA PCM devices and
-supports 6 back end (BE) DAIs. Each FE PCM can digitally route audio data to any
-of the BE DAIs. The FE PCM devices can also route audio to more than 1 BE DAI.
-
-
-
-Example - DPCM Switching playback from DAI0 to DAI1
----------------------------------------------------
-
-Audio is being played to the Headset. After a while the user removes the headset
-and audio continues playing on the speakers.
-
-Playback on PCM0 to Headset would look like :-
-
-                    *************
-PCM0 <============> *           * <====DAI0=====> Codec Headset
-                    *           *
-PCM1 <------------> *           * <----DAI1-----> Codec Speakers
-                    *   DSP     *
-PCM2 <------------> *           * <----DAI2-----> MODEM
-                    *           *
-PCM3 <------------> *           * <----DAI3-----> BT
-                    *           *
-                    *           * <----DAI4-----> DMIC
-                    *           *
-                    *           * <----DAI5-----> FM
-                    *************
-
-The headset is removed from the jack by user so the speakers must now be used :-
-
-                    *************
-PCM0 <============> *           * <----DAI0-----> Codec Headset
-                    *           *
-PCM1 <------------> *           * <====DAI1=====> Codec Speakers
-                    *   DSP     *
-PCM2 <------------> *           * <----DAI2-----> MODEM
-                    *           *
-PCM3 <------------> *           * <----DAI3-----> BT
-                    *           *
-                    *           * <----DAI4-----> DMIC
-                    *           *
-                    *           * <----DAI5-----> FM
-                    *************
-
-The audio driver processes this as follows :-
-
- 1) Machine driver receives Jack removal event.
-
- 2) Machine driver OR audio HAL disables the Headset path.
-
- 3) DPCM runs the PCM trigger(stop), hw_free(), shutdown() operations on DAI0
-    for headset since the path is now disabled.
-
- 4) Machine driver or audio HAL enables the speaker path.
-
- 5) DPCM runs the PCM ops for startup(), hw_params(), prepapre() and
-    trigger(start) for DAI1 Speakers since the path is enabled.
-
-In this example, the machine driver or userspace audio HAL can alter the routing
-and then DPCM will take care of managing the DAI PCM operations to either bring
-the link up or down. Audio playback does not stop during this transition.
-
-
-
-DPCM machine driver
-===================
-
-The DPCM enabled ASoC machine driver is similar to normal machine drivers
-except that we also have to :-
-
- 1) Define the FE and BE DAI links.
-
- 2) Define any FE/BE PCM operations.
-
- 3) Define widget graph connections.
-
-
-1 FE and BE DAI links
----------------------
-
-| Front End PCMs    |  SoC DSP  | Back End DAIs | Audio devices |
-
-                    *************
-PCM0 <------------> *           * <----DAI0-----> Codec Headset
-                    *           *
-PCM1 <------------> *           * <----DAI1-----> Codec Speakers
-                    *   DSP     *
-PCM2 <------------> *           * <----DAI2-----> MODEM
-                    *           *
-PCM3 <------------> *           * <----DAI3-----> BT
-                    *           *
-                    *           * <----DAI4-----> DMIC
-                    *           *
-                    *           * <----DAI5-----> FM
-                    *************
-
-For the example above we have to define 4 FE DAI links and 6 BE DAI links. The
-FE DAI links are defined as follows :-
-
-static struct snd_soc_dai_link machine_dais[] = {
-	{
-		.name = "PCM0 System",
-		.stream_name = "System Playback",
-		.cpu_dai_name = "System Pin",
-		.platform_name = "dsp-audio",
-		.codec_name = "snd-soc-dummy",
-		.codec_dai_name = "snd-soc-dummy-dai",
-		.dynamic = 1,
-		.trigger = {SND_SOC_DPCM_TRIGGER_POST, SND_SOC_DPCM_TRIGGER_POST},
-		.dpcm_playback = 1,
-	},
-	.....< other FE and BE DAI links here >
-};
-
-This FE DAI link is pretty similar to a regular DAI link except that we also
-set the DAI link to a DPCM FE with the "dynamic = 1". The supported FE stream
-directions should also be set with the "dpcm_playback" and "dpcm_capture"
-flags. There is also an option to specify the ordering of the trigger call for
-each FE. This allows the ASoC core to trigger the DSP before or after the other
-components (as some DSPs have strong requirements for the ordering DAI/DSP
-start and stop sequences).
-
-The FE DAI above sets the codec and code DAIs to dummy devices since the BE is
-dynamic and will change depending on runtime config.
-
-The BE DAIs are configured as follows :-
-
-static struct snd_soc_dai_link machine_dais[] = {
-	.....< FE DAI links here >
-	{
-		.name = "Codec Headset",
-		.cpu_dai_name = "ssp-dai.0",
-		.platform_name = "snd-soc-dummy",
-		.no_pcm = 1,
-		.codec_name = "rt5640.0-001c",
-		.codec_dai_name = "rt5640-aif1",
-		.ignore_suspend = 1,
-		.ignore_pmdown_time = 1,
-		.be_hw_params_fixup = hswult_ssp0_fixup,
-		.ops = &haswell_ops,
-		.dpcm_playback = 1,
-		.dpcm_capture = 1,
-	},
-	.....< other BE DAI links here >
-};
-
-This BE DAI link connects DAI0 to the codec (in this case RT5460 AIF1). It sets
-the "no_pcm" flag to mark it has a BE and sets flags for supported stream
-directions using "dpcm_playback" and "dpcm_capture" above.
-
-The BE has also flags set for ignoring suspend and PM down time. This allows
-the BE to work in a hostless mode where the host CPU is not transferring data
-like a BT phone call :-
-
-                    *************
-PCM0 <------------> *           * <----DAI0-----> Codec Headset
-                    *           *
-PCM1 <------------> *           * <----DAI1-----> Codec Speakers
-                    *   DSP     *
-PCM2 <------------> *           * <====DAI2=====> MODEM
-                    *           *
-PCM3 <------------> *           * <====DAI3=====> BT
-                    *           *
-                    *           * <----DAI4-----> DMIC
-                    *           *
-                    *           * <----DAI5-----> FM
-                    *************
-
-This allows the host CPU to sleep whilst the DSP, MODEM DAI and the BT DAI are
-still in operation.
-
-A BE DAI link can also set the codec to a dummy device if the code is a device
-that is managed externally.
-
-Likewise a BE DAI can also set a dummy cpu DAI if the CPU DAI is managed by the
-DSP firmware.
-
-
-2 FE/BE PCM operations
-----------------------
-
-The BE above also exports some PCM operations and a "fixup" callback. The fixup
-callback is used by the machine driver to (re)configure the DAI based upon the
-FE hw params. i.e. the DSP may perform SRC or ASRC from the FE to BE.
-
-e.g. DSP converts all FE hw params to run at fixed rate of 48k, 16bit, stereo for
-DAI0. This means all FE hw_params have to be fixed in the machine driver for
-DAI0 so that the DAI is running at desired configuration regardless of the FE
-configuration.
-
-static int dai0_fixup(struct snd_soc_pcm_runtime *rtd,
-			struct snd_pcm_hw_params *params)
-{
-	struct snd_interval *rate = hw_param_interval(params,
-			SNDRV_PCM_HW_PARAM_RATE);
-	struct snd_interval *channels = hw_param_interval(params,
-						SNDRV_PCM_HW_PARAM_CHANNELS);
-
-	/* The DSP will covert the FE rate to 48k, stereo */
-	rate->min = rate->max = 48000;
-	channels->min = channels->max = 2;
-
-	/* set DAI0 to 16 bit */
-	snd_mask_set(¶ms->masks[SNDRV_PCM_HW_PARAM_FORMAT -
-				    SNDRV_PCM_HW_PARAM_FIRST_MASK],
-				    SNDRV_PCM_FORMAT_S16_LE);
-	return 0;
-}
-
-The other PCM operation are the same as for regular DAI links. Use as necessary.
-
-
-3 Widget graph connections
---------------------------
-
-The BE DAI links will normally be connected to the graph at initialisation time
-by the ASoC DAPM core. However, if the BE codec or BE DAI is a dummy then this
-has to be set explicitly in the driver :-
-
-/* BE for codec Headset -  DAI0 is dummy and managed by DSP FW */
-{"DAI0 CODEC IN", NULL, "AIF1 Capture"},
-{"AIF1 Playback", NULL, "DAI0 CODEC OUT"},
-
-
-Writing a DPCM DSP driver
-=========================
-
-The DPCM DSP driver looks much like a standard platform class ASoC driver
-combined with elements from a codec class driver. A DSP platform driver must
-implement :-
-
- 1) Front End PCM DAIs - i.e. struct snd_soc_dai_driver.
-
- 2) DAPM graph showing DSP audio routing from FE DAIs to BEs.
-
- 3) DAPM widgets from DSP graph.
-
- 4) Mixers for gains, routing, etc.
-
- 5) DMA configuration.
-
- 6) BE AIF widgets.
-
-Items 6 is important for routing the audio outside of the DSP. AIF need to be
-defined for each BE and each stream direction. e.g for BE DAI0 above we would
-have :-
-
-SND_SOC_DAPM_AIF_IN("DAI0 RX", NULL, 0, SND_SOC_NOPM, 0, 0),
-SND_SOC_DAPM_AIF_OUT("DAI0 TX", NULL, 0, SND_SOC_NOPM, 0, 0),
-
-The BE AIF are used to connect the DSP graph to the graphs for the other
-component drivers (e.g. codec graph).
-
-
-Hostless PCM streams
-====================
-
-A hostless PCM stream is a stream that is not routed through the host CPU. An
-example of this would be a phone call from handset to modem.
-
-
-                    *************
-PCM0 <------------> *           * <----DAI0-----> Codec Headset
-                    *           *
-PCM1 <------------> *           * <====DAI1=====> Codec Speakers/Mic
-                    *   DSP     *
-PCM2 <------------> *           * <====DAI2=====> MODEM
-                    *           *
-PCM3 <------------> *           * <----DAI3-----> BT
-                    *           *
-                    *           * <----DAI4-----> DMIC
-                    *           *
-                    *           * <----DAI5-----> FM
-                    *************
-
-In this case the PCM data is routed via the DSP. The host CPU in this use case
-is only used for control and can sleep during the runtime of the stream.
-
-The host can control the hostless link either by :-
-
- 1) Configuring the link as a CODEC <-> CODEC style link. In this case the link
-    is enabled or disabled by the state of the DAPM graph. This usually means
-    there is a mixer control that can be used to connect or disconnect the path
-    between both DAIs.
-
- 2) Hostless FE. This FE has a virtual connection to the BE DAI links on the DAPM
-    graph. Control is then carried out by the FE as regular PCM operations.
-    This method gives more control over the DAI links, but requires much more
-    userspace code to control the link. Its recommended to use CODEC<->CODEC
-    unless your HW needs more fine grained sequencing of the PCM ops.
-
-
-CODEC <-> CODEC link
---------------------
-
-This DAI link is enabled when DAPM detects a valid path within the DAPM graph.
-The machine driver sets some additional parameters to the DAI link i.e.
-
-static const struct snd_soc_pcm_stream dai_params = {
-	.formats = SNDRV_PCM_FMTBIT_S32_LE,
-	.rate_min = 8000,
-	.rate_max = 8000,
-	.channels_min = 2,
-	.channels_max = 2,
-};
-
-static struct snd_soc_dai_link dais[] = {
-	< ... more DAI links above ... >
-	{
-		.name = "MODEM",
-		.stream_name = "MODEM",
-		.cpu_dai_name = "dai2",
-		.codec_dai_name = "modem-aif1",
-		.codec_name = "modem",
-		.dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF
-				| SND_SOC_DAIFMT_CBM_CFM,
-		.params = &dai_params,
-	}
-	< ... more DAI links here ... >
-
-These parameters are used to configure the DAI hw_params() when DAPM detects a
-valid path and then calls the PCM operations to start the link. DAPM will also
-call the appropriate PCM operations to disable the DAI when the path is no
-longer valid.
-
-
-Hostless FE
------------
-
-The DAI link(s) are enabled by a FE that does not read or write any PCM data.
-This means creating a new FE that is connected with a virtual path to both
-DAI links. The DAI links will be started when the FE PCM is started and stopped
-when the FE PCM is stopped. Note that the FE PCM cannot read or write data in
-this configuration.
-
-
diff --git a/Documentation/sound/soc/dpcm.rst b/Documentation/sound/soc/dpcm.rst
new file mode 100644
index 000000000000..395e5a516282
--- /dev/null
+++ b/Documentation/sound/soc/dpcm.rst
@@ -0,0 +1,392 @@
+===========
+Dynamic PCM
+===========
+
+Description
+===========
+
+Dynamic PCM allows an ALSA PCM device to digitally route its PCM audio to
+various digital endpoints during the PCM stream runtime. e.g. PCM0 can route
+digital audio to I2S DAI0, I2S DAI1 or PDM DAI2. This is useful for on SoC DSP
+drivers that expose several ALSA PCMs and can route to multiple DAIs.
+
+The DPCM runtime routing is determined by the ALSA mixer settings in the same
+way as the analog signal is routed in an ASoC codec driver. DPCM uses a DAPM
+graph representing the DSP internal audio paths and uses the mixer settings to
+determine the patch used by each ALSA PCM.
+
+DPCM re-uses all the existing component codec, platform and DAI drivers without
+any modifications.
+
+
+Phone Audio System with SoC based DSP
+-------------------------------------
+
+Consider the following phone audio subsystem. This will be used in this
+document for all examples :-
+::
+
+  | Front End PCMs    |  SoC DSP  | Back End DAIs | Audio devices |
+  
+                      *************
+  PCM0 <------------> *           * <----DAI0-----> Codec Headset
+                      *           *
+  PCM1 <------------> *           * <----DAI1-----> Codec Speakers
+                      *   DSP     *
+  PCM2 <------------> *           * <----DAI2-----> MODEM
+                      *           *
+  PCM3 <------------> *           * <----DAI3-----> BT
+                      *           *
+                      *           * <----DAI4-----> DMIC
+                      *           *
+                      *           * <----DAI5-----> FM
+                      *************
+
+This diagram shows a simple smart phone audio subsystem. It supports Bluetooth,
+FM digital radio, Speakers, Headset Jack, digital microphones and cellular
+modem. This sound card exposes 4 DSP front end (FE) ALSA PCM devices and
+supports 6 back end (BE) DAIs. Each FE PCM can digitally route audio data to any
+of the BE DAIs. The FE PCM devices can also route audio to more than 1 BE DAI.
+
+
+
+Example - DPCM Switching playback from DAI0 to DAI1
+---------------------------------------------------
+
+Audio is being played to the Headset. After a while the user removes the headset
+and audio continues playing on the speakers.
+
+Playback on PCM0 to Headset would look like :-
+::
+
+                      *************
+  PCM0 <============> *           * <====DAI0=====> Codec Headset
+                      *           *
+  PCM1 <------------> *           * <----DAI1-----> Codec Speakers
+                      *   DSP     *
+  PCM2 <------------> *           * <----DAI2-----> MODEM
+                      *           *
+  PCM3 <------------> *           * <----DAI3-----> BT
+                      *           *
+                      *           * <----DAI4-----> DMIC
+                      *           *
+                      *           * <----DAI5-----> FM
+                      *************
+
+The headset is removed from the jack by user so the speakers must now be used :-
+::
+
+                      *************
+  PCM0 <============> *           * <----DAI0-----> Codec Headset
+                      *           *
+  PCM1 <------------> *           * <====DAI1=====> Codec Speakers
+                      *   DSP     *
+  PCM2 <------------> *           * <----DAI2-----> MODEM
+                      *           *
+  PCM3 <------------> *           * <----DAI3-----> BT
+                      *           *
+                      *           * <----DAI4-----> DMIC
+                      *           *
+                      *           * <----DAI5-----> FM
+                      *************
+
+The audio driver processes this as follows :-
+
+1. Machine driver receives Jack removal event.
+
+2. Machine driver OR audio HAL disables the Headset path.
+
+3. DPCM runs the PCM trigger(stop), hw_free(), shutdown() operations on DAI0
+   for headset since the path is now disabled.
+
+4. Machine driver or audio HAL enables the speaker path.
+
+5. DPCM runs the PCM ops for startup(), hw_params(), prepapre() and
+   trigger(start) for DAI1 Speakers since the path is enabled.
+
+In this example, the machine driver or userspace audio HAL can alter the routing
+and then DPCM will take care of managing the DAI PCM operations to either bring
+the link up or down. Audio playback does not stop during this transition.
+
+
+
+DPCM machine driver
+===================
+
+The DPCM enabled ASoC machine driver is similar to normal machine drivers
+except that we also have to :-
+
+1. Define the FE and BE DAI links.
+
+2. Define any FE/BE PCM operations.
+
+3. Define widget graph connections.
+
+
+FE and BE DAI links
+-------------------
+::
+
+  | Front End PCMs    |  SoC DSP  | Back End DAIs | Audio devices |
+  
+                      *************
+  PCM0 <------------> *           * <----DAI0-----> Codec Headset
+                      *           *
+  PCM1 <------------> *           * <----DAI1-----> Codec Speakers
+                      *   DSP     *
+  PCM2 <------------> *           * <----DAI2-----> MODEM
+                      *           *
+  PCM3 <------------> *           * <----DAI3-----> BT
+                      *           *
+                      *           * <----DAI4-----> DMIC
+                      *           *
+                      *           * <----DAI5-----> FM
+                      *************
+
+For the example above we have to define 4 FE DAI links and 6 BE DAI links. The
+FE DAI links are defined as follows :-
+::
+
+  static struct snd_soc_dai_link machine_dais[] = {
+	{
+		.name = "PCM0 System",
+		.stream_name = "System Playback",
+		.cpu_dai_name = "System Pin",
+		.platform_name = "dsp-audio",
+		.codec_name = "snd-soc-dummy",
+		.codec_dai_name = "snd-soc-dummy-dai",
+		.dynamic = 1,
+		.trigger = {SND_SOC_DPCM_TRIGGER_POST, SND_SOC_DPCM_TRIGGER_POST},
+		.dpcm_playback = 1,
+	},
+	.....< other FE and BE DAI links here >
+  };
+
+This FE DAI link is pretty similar to a regular DAI link except that we also
+set the DAI link to a DPCM FE with the ``dynamic = 1``. The supported FE stream
+directions should also be set with the ``dpcm_playback`` and ``dpcm_capture``
+flags. There is also an option to specify the ordering of the trigger call for
+each FE. This allows the ASoC core to trigger the DSP before or after the other
+components (as some DSPs have strong requirements for the ordering DAI/DSP
+start and stop sequences).
+
+The FE DAI above sets the codec and code DAIs to dummy devices since the BE is
+dynamic and will change depending on runtime config.
+
+The BE DAIs are configured as follows :-
+::
+
+  static struct snd_soc_dai_link machine_dais[] = {
+	.....< FE DAI links here >
+	{
+		.name = "Codec Headset",
+		.cpu_dai_name = "ssp-dai.0",
+		.platform_name = "snd-soc-dummy",
+		.no_pcm = 1,
+		.codec_name = "rt5640.0-001c",
+		.codec_dai_name = "rt5640-aif1",
+		.ignore_suspend = 1,
+		.ignore_pmdown_time = 1,
+		.be_hw_params_fixup = hswult_ssp0_fixup,
+		.ops = &haswell_ops,
+		.dpcm_playback = 1,
+		.dpcm_capture = 1,
+	},
+	.....< other BE DAI links here >
+  };
+
+This BE DAI link connects DAI0 to the codec (in this case RT5460 AIF1). It sets
+the ``no_pcm`` flag to mark it has a BE and sets flags for supported stream
+directions using ``dpcm_playback`` and ``dpcm_capture`` above.
+
+The BE has also flags set for ignoring suspend and PM down time. This allows
+the BE to work in a hostless mode where the host CPU is not transferring data
+like a BT phone call :-
+::
+
+                      *************
+  PCM0 <------------> *           * <----DAI0-----> Codec Headset
+                      *           *
+  PCM1 <------------> *           * <----DAI1-----> Codec Speakers
+                      *   DSP     *
+  PCM2 <------------> *           * <====DAI2=====> MODEM
+                      *           *
+  PCM3 <------------> *           * <====DAI3=====> BT
+                      *           *
+                      *           * <----DAI4-----> DMIC
+                      *           *
+                      *           * <----DAI5-----> FM
+                      *************
+
+This allows the host CPU to sleep whilst the DSP, MODEM DAI and the BT DAI are
+still in operation.
+
+A BE DAI link can also set the codec to a dummy device if the code is a device
+that is managed externally.
+
+Likewise a BE DAI can also set a dummy cpu DAI if the CPU DAI is managed by the
+DSP firmware.
+
+
+FE/BE PCM operations
+--------------------
+
+The BE above also exports some PCM operations and a ``fixup`` callback. The fixup
+callback is used by the machine driver to (re)configure the DAI based upon the
+FE hw params. i.e. the DSP may perform SRC or ASRC from the FE to BE.
+
+e.g. DSP converts all FE hw params to run at fixed rate of 48k, 16bit, stereo for
+DAI0. This means all FE hw_params have to be fixed in the machine driver for
+DAI0 so that the DAI is running at desired configuration regardless of the FE
+configuration.
+::
+
+  static int dai0_fixup(struct snd_soc_pcm_runtime *rtd,
+			struct snd_pcm_hw_params *params)
+  {
+	struct snd_interval *rate = hw_param_interval(params,
+			SNDRV_PCM_HW_PARAM_RATE);
+	struct snd_interval *channels = hw_param_interval(params,
+						SNDRV_PCM_HW_PARAM_CHANNELS);
+
+	/* The DSP will covert the FE rate to 48k, stereo */
+	rate->min = rate->max = 48000;
+	channels->min = channels->max = 2;
+
+	/* set DAI0 to 16 bit */
+	snd_mask_set(¶ms->masks[SNDRV_PCM_HW_PARAM_FORMAT -
+				    SNDRV_PCM_HW_PARAM_FIRST_MASK],
+				    SNDRV_PCM_FORMAT_S16_LE);
+	return 0;
+  }
+
+The other PCM operation are the same as for regular DAI links. Use as necessary.
+
+
+Widget graph connections
+------------------------
+
+The BE DAI links will normally be connected to the graph at initialisation time
+by the ASoC DAPM core. However, if the BE codec or BE DAI is a dummy then this
+has to be set explicitly in the driver :-
+::
+
+  /* BE for codec Headset -  DAI0 is dummy and managed by DSP FW */
+  {"DAI0 CODEC IN", NULL, "AIF1 Capture"},
+  {"AIF1 Playback", NULL, "DAI0 CODEC OUT"},
+
+
+Writing a DPCM DSP driver
+=========================
+
+The DPCM DSP driver looks much like a standard platform class ASoC driver
+combined with elements from a codec class driver. A DSP platform driver must
+implement :-
+
+1. Front End PCM DAIs - i.e. struct snd_soc_dai_driver.
+
+2. DAPM graph showing DSP audio routing from FE DAIs to BEs.
+
+3. DAPM widgets from DSP graph.
+
+4. Mixers for gains, routing, etc.
+
+5. DMA configuration.
+
+6. BE AIF widgets.
+
+Items 6 is important for routing the audio outside of the DSP. AIF need to be
+defined for each BE and each stream direction. e.g for BE DAI0 above we would
+have :-
+::
+
+  SND_SOC_DAPM_AIF_IN("DAI0 RX", NULL, 0, SND_SOC_NOPM, 0, 0),
+  SND_SOC_DAPM_AIF_OUT("DAI0 TX", NULL, 0, SND_SOC_NOPM, 0, 0),
+
+The BE AIF are used to connect the DSP graph to the graphs for the other
+component drivers (e.g. codec graph).
+
+
+Hostless PCM streams
+====================
+
+A hostless PCM stream is a stream that is not routed through the host CPU. An
+example of this would be a phone call from handset to modem.
+::
+
+                      *************
+  PCM0 <------------> *           * <----DAI0-----> Codec Headset
+                      *           *
+  PCM1 <------------> *           * <====DAI1=====> Codec Speakers/Mic
+                      *   DSP     *
+  PCM2 <------------> *           * <====DAI2=====> MODEM
+                      *           *
+  PCM3 <------------> *           * <----DAI3-----> BT
+                      *           *
+                      *           * <----DAI4-----> DMIC
+                      *           *
+                      *           * <----DAI5-----> FM
+                      *************
+
+In this case the PCM data is routed via the DSP. The host CPU in this use case
+is only used for control and can sleep during the runtime of the stream.
+
+The host can control the hostless link either by :-
+
+ 1. Configuring the link as a CODEC <-> CODEC style link. In this case the link
+    is enabled or disabled by the state of the DAPM graph. This usually means
+    there is a mixer control that can be used to connect or disconnect the path
+    between both DAIs.
+
+ 2. Hostless FE. This FE has a virtual connection to the BE DAI links on the DAPM
+    graph. Control is then carried out by the FE as regular PCM operations.
+    This method gives more control over the DAI links, but requires much more
+    userspace code to control the link. Its recommended to use CODEC<->CODEC
+    unless your HW needs more fine grained sequencing of the PCM ops.
+
+
+CODEC <-> CODEC link
+--------------------
+
+This DAI link is enabled when DAPM detects a valid path within the DAPM graph.
+The machine driver sets some additional parameters to the DAI link i.e.
+::
+
+  static const struct snd_soc_pcm_stream dai_params = {
+	.formats = SNDRV_PCM_FMTBIT_S32_LE,
+	.rate_min = 8000,
+	.rate_max = 8000,
+	.channels_min = 2,
+	.channels_max = 2,
+  };
+
+  static struct snd_soc_dai_link dais[] = {
+	< ... more DAI links above ... >
+	{
+		.name = "MODEM",
+		.stream_name = "MODEM",
+		.cpu_dai_name = "dai2",
+		.codec_dai_name = "modem-aif1",
+		.codec_name = "modem",
+		.dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF
+				| SND_SOC_DAIFMT_CBM_CFM,
+		.params = &dai_params,
+	}
+	< ... more DAI links here ... >
+
+These parameters are used to configure the DAI hw_params() when DAPM detects a
+valid path and then calls the PCM operations to start the link. DAPM will also
+call the appropriate PCM operations to disable the DAI when the path is no
+longer valid.
+
+
+Hostless FE
+-----------
+
+The DAI link(s) are enabled by a FE that does not read or write any PCM data.
+This means creating a new FE that is connected with a virtual path to both
+DAI links. The DAI links will be started when the FE PCM is started and stopped
+when the FE PCM is stopped. Note that the FE PCM cannot read or write data in
+this configuration.
+
+
diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
index 85ec51764e83..e142a0f25c5b 100644
--- a/Documentation/sound/soc/index.rst
+++ b/Documentation/sound/soc/index.rst
@@ -16,3 +16,4 @@ The documentation is spilt into the following sections:-
    pops-clicks
    clocking
    jack
+   dpcm
-- 
cgit v1.2.3


From c6ab9e57e84ee015bb9c5de213d9f85e5fd4e085 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Fri, 11 Nov 2016 16:55:29 +0100
Subject: ASoC: doc: ReSTize codec_to_codec.txt

Yet another simple conversion from a plain text file.
Renamed to codec-to-codec.rst to align with others.

Acked-by: Mark Brown 
Signed-off-by: Takashi Iwai 
---
 Documentation/sound/alsa/soc/codec_to_codec.txt | 103 ----------------------
 Documentation/sound/soc/codec-to-codec.rst      | 108 ++++++++++++++++++++++++
 Documentation/sound/soc/index.rst               |   1 +
 3 files changed, 109 insertions(+), 103 deletions(-)
 delete mode 100644 Documentation/sound/alsa/soc/codec_to_codec.txt
 create mode 100644 Documentation/sound/soc/codec-to-codec.rst

diff --git a/Documentation/sound/alsa/soc/codec_to_codec.txt b/Documentation/sound/alsa/soc/codec_to_codec.txt
deleted file mode 100644
index 704a6483652c..000000000000
--- a/Documentation/sound/alsa/soc/codec_to_codec.txt
+++ /dev/null
@@ -1,103 +0,0 @@
-Creating codec to codec dai link for ALSA dapm
-===================================================
-
-Mostly the flow of audio is always from CPU to codec so your system
-will look as below:
-
- ---------          ---------
-|         |  dai   |         |
-    CPU    ------->    codec
-|         |        |         |
- ---------          ---------
-
-In case your system looks as below:
-                     ---------
-                    |         |
-                      codec-2
-                    |         |
-                     ---------
-                         |
-                       dai-2
-                         |
- ----------          ---------
-|          |  dai-1 |         |
-    CPU     ------->  codec-1
-|          |        |         |
- ----------          ---------
-                         |
-                       dai-3
-                         |
-                     ---------
-                    |         |
-                      codec-3
-                    |         |
-                     ---------
-
-Suppose codec-2 is a bluetooth chip and codec-3 is connected to
-a speaker and you have a below scenario:
-codec-2 will receive the audio data and the user wants to play that
-audio through codec-3 without involving the CPU.This
-aforementioned case is the ideal case when codec to codec
-connection should be used.
-
-Your dai_link should appear as below in your machine
-file:
-
-/*
- * this pcm stream only supports 24 bit, 2 channel and
- * 48k sampling rate.
- */
-static const struct snd_soc_pcm_stream dsp_codec_params = {
-        .formats = SNDRV_PCM_FMTBIT_S24_LE,
-        .rate_min = 48000,
-        .rate_max = 48000,
-        .channels_min = 2,
-        .channels_max = 2,
-};
-
-{
-    .name = "CPU-DSP",
-    .stream_name = "CPU-DSP",
-    .cpu_dai_name = "samsung-i2s.0",
-    .codec_name = "codec-2,
-    .codec_dai_name = "codec-2-dai_name",
-    .platform_name = "samsung-i2s.0",
-    .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF
-            | SND_SOC_DAIFMT_CBM_CFM,
-    .ignore_suspend = 1,
-    .params = &dsp_codec_params,
-},
-{
-    .name = "DSP-CODEC",
-    .stream_name = "DSP-CODEC",
-    .cpu_dai_name = "wm0010-sdi2",
-    .codec_name = "codec-3,
-    .codec_dai_name = "codec-3-dai_name",
-    .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF
-            | SND_SOC_DAIFMT_CBM_CFM,
-    .ignore_suspend = 1,
-    .params = &dsp_codec_params,
-},
-
-Above code snippet is motivated from sound/soc/samsung/speyside.c.
-
-Note the "params" callback which lets the dapm know that this
-dai_link is a codec to codec connection.
-
-In dapm core a route is created between cpu_dai playback widget
-and codec_dai capture widget for playback path and vice-versa is
-true for capture path. In order for this aforementioned route to get
-triggered, DAPM needs to find a valid endpoint which could be either
-a sink or source widget corresponding to playback and capture path
-respectively.
-
-In order to trigger this dai_link widget, a thin codec driver for
-the speaker amp can be created as demonstrated in wm8727.c file, it
-sets appropriate constraints for the device even if it needs no control.
-
-Make sure to name your corresponding cpu and codec playback and capture
-dai names ending with "Playback" and "Capture" respectively as dapm core
-will link and power those dais based on the name.
-
-Note that in current device tree there is no way to mark a dai_link
-as codec to codec. However, it may change in future.
diff --git a/Documentation/sound/soc/codec-to-codec.rst b/Documentation/sound/soc/codec-to-codec.rst
new file mode 100644
index 000000000000..810109d7500d
--- /dev/null
+++ b/Documentation/sound/soc/codec-to-codec.rst
@@ -0,0 +1,108 @@
+==============================================
+Creating codec to codec dai link for ALSA dapm
+==============================================
+
+Mostly the flow of audio is always from CPU to codec so your system
+will look as below:
+::
+
+   ---------          ---------
+  |         |  dai   |         |
+      CPU    ------->    codec
+  |         |        |         |
+   ---------          ---------
+
+In case your system looks as below:
+::
+
+                       ---------
+                      |         |
+                        codec-2
+                      |         |
+                      ---------
+                           |
+                         dai-2
+                           |
+   ----------          ---------
+  |          |  dai-1 |         |
+      CPU     ------->  codec-1
+  |          |        |         |
+   ----------          ---------
+                           |
+                         dai-3
+                           |
+                       ---------
+                      |         |
+                        codec-3
+                      |         |
+                       ---------
+
+Suppose codec-2 is a bluetooth chip and codec-3 is connected to
+a speaker and you have a below scenario:
+codec-2 will receive the audio data and the user wants to play that
+audio through codec-3 without involving the CPU.This
+aforementioned case is the ideal case when codec to codec
+connection should be used.
+
+Your dai_link should appear as below in your machine
+file:
+::
+
+ /*
+  * this pcm stream only supports 24 bit, 2 channel and
+  * 48k sampling rate.
+  */
+ static const struct snd_soc_pcm_stream dsp_codec_params = {
+        .formats = SNDRV_PCM_FMTBIT_S24_LE,
+        .rate_min = 48000,
+        .rate_max = 48000,
+        .channels_min = 2,
+        .channels_max = 2,
+ };
+
+ {
+    .name = "CPU-DSP",
+    .stream_name = "CPU-DSP",
+    .cpu_dai_name = "samsung-i2s.0",
+    .codec_name = "codec-2,
+    .codec_dai_name = "codec-2-dai_name",
+    .platform_name = "samsung-i2s.0",
+    .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF
+            | SND_SOC_DAIFMT_CBM_CFM,
+    .ignore_suspend = 1,
+    .params = &dsp_codec_params,
+ },
+ {
+    .name = "DSP-CODEC",
+    .stream_name = "DSP-CODEC",
+    .cpu_dai_name = "wm0010-sdi2",
+    .codec_name = "codec-3,
+    .codec_dai_name = "codec-3-dai_name",
+    .dai_fmt = SND_SOC_DAIFMT_I2S | SND_SOC_DAIFMT_NB_NF
+            | SND_SOC_DAIFMT_CBM_CFM,
+    .ignore_suspend = 1,
+    .params = &dsp_codec_params,
+ },
+
+Above code snippet is motivated from sound/soc/samsung/speyside.c.
+
+Note the "params" callback which lets the dapm know that this
+dai_link is a codec to codec connection.
+
+In dapm core a route is created between cpu_dai playback widget
+and codec_dai capture widget for playback path and vice-versa is
+true for capture path. In order for this aforementioned route to get
+triggered, DAPM needs to find a valid endpoint which could be either
+a sink or source widget corresponding to playback and capture path
+respectively.
+
+In order to trigger this dai_link widget, a thin codec driver for
+the speaker amp can be created as demonstrated in wm8727.c file, it
+sets appropriate constraints for the device even if it needs no control.
+
+Make sure to name your corresponding cpu and codec playback and capture
+dai names ending with "Playback" and "Capture" respectively as dapm core
+will link and power those dais based on the name.
+
+Note that in current device tree there is no way to mark a dai_link
+as codec to codec. However, it may change in future.
diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
index e142a0f25c5b..e57df2dab2fd 100644
--- a/Documentation/sound/soc/index.rst
+++ b/Documentation/sound/soc/index.rst
@@ -17,3 +17,4 @@ The documentation is spilt into the following sections:-
    clocking
    jack
    dpcm
+   codec-to-codec
-- 
cgit v1.2.3


From 3080b056b3d4e38bc4beac337acadf8bd286ac58 Mon Sep 17 00:00:00 2001
From: SeongJae Park 
Date: Tue, 8 Nov 2016 21:26:07 +0900
Subject: docs/driver-api: Apply changed source file names

Few files under dma-buf/ changed their names but the changes didn't
applied to a document that referencing them.  It is causing few
documentation build warnings.  This commit fixes the problems by
applying changed file names on the document.

Signed-off-by: SeongJae Park 
Signed-off-by: Jonathan Corbet 
---
 Documentation/driver-api/infrastructure.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst
index 5d50d6733db3..a0d65eb49055 100644
--- a/Documentation/driver-api/infrastructure.rst
+++ b/Documentation/driver-api/infrastructure.rst
@@ -86,10 +86,10 @@ reservation
 fence
 ~~~~~
 
-.. kernel-doc:: drivers/dma-buf/fence.c
+.. kernel-doc:: drivers/dma-buf/dma-fence.c
    :export:
 
-.. kernel-doc:: include/linux/fence.h
+.. kernel-doc:: include/linux/dma-fence.h
    :internal:
 
 .. kernel-doc:: drivers/dma-buf/seqno-fence.c
@@ -98,10 +98,10 @@ fence
 .. kernel-doc:: include/linux/seqno-fence.h
    :internal:
 
-.. kernel-doc:: drivers/dma-buf/fence-array.c
+.. kernel-doc:: drivers/dma-buf/dma-fence-array.c
    :export:
 
-.. kernel-doc:: include/linux/fence-array.h
+.. kernel-doc:: include/linux/dma-fence-array.h
    :internal:
 
 .. kernel-doc:: drivers/dma-buf/reservation.c
-- 
cgit v1.2.3


From 9544a2daebbaf70bb61f0b02ae481532fc22a379 Mon Sep 17 00:00:00 2001
From: SeongJae Park 
Date: Tue, 8 Nov 2016 21:26:08 +0900
Subject: Documentation: Move translations into a sub-directory

Signed-off-by: SeongJae Park 
Signed-off-by: Jonathan Corbet 
---
 Documentation/ja_JP/HOWTO                          |  637 ----
 Documentation/ja_JP/SubmitChecklist                |  111 -
 Documentation/ja_JP/SubmittingPatches              |  719 -----
 Documentation/ja_JP/stable_api_nonsense.txt        |  263 --
 Documentation/ja_JP/stable_kernel_rules.txt        |   84 -
 Documentation/ko_KR/HOWTO                          |  637 ----
 Documentation/ko_KR/memory-barriers.txt            | 3171 --------------------
 Documentation/ko_KR/stable_api_nonsense.txt        |  195 --
 Documentation/translations/ja_JP/HOWTO             |  637 ++++
 Documentation/translations/ja_JP/SubmitChecklist   |  111 +
 Documentation/translations/ja_JP/SubmittingPatches |  719 +++++
 .../translations/ja_JP/stable_api_nonsense.txt     |  263 ++
 .../translations/ja_JP/stable_kernel_rules.txt     |   84 +
 Documentation/translations/ko_KR/HOWTO             |  637 ++++
 .../translations/ko_KR/memory-barriers.txt         | 3171 ++++++++++++++++++++
 .../translations/ko_KR/stable_api_nonsense.txt     |  195 ++
 Documentation/translations/zh_CN/CodingStyle       |  813 +++++
 Documentation/translations/zh_CN/HOWTO             |  536 ++++
 Documentation/translations/zh_CN/IRQ.txt           |   39 +
 Documentation/translations/zh_CN/SecurityBugs      |   50 +
 Documentation/translations/zh_CN/SubmittingDrivers |  164 +
 Documentation/translations/zh_CN/SubmittingPatches |  412 +++
 Documentation/translations/zh_CN/arm/Booting       |  175 ++
 .../translations/zh_CN/arm/kernel_user_helpers.txt |  284 ++
 Documentation/translations/zh_CN/arm64/booting.txt |  246 ++
 .../zh_CN/arm64/legacy_instructions.txt            |   72 +
 Documentation/translations/zh_CN/arm64/memory.txt  |  114 +
 .../translations/zh_CN/arm64/silicon-errata.txt    |   74 +
 .../translations/zh_CN/arm64/tagged-pointers.txt   |   52 +
 .../translations/zh_CN/basic_profiling.txt         |   71 +
 Documentation/translations/zh_CN/email-clients.txt |  210 ++
 .../translations/zh_CN/filesystems/sysfs.txt       |  372 +++
 Documentation/translations/zh_CN/gpio.txt          |  650 ++++
 Documentation/translations/zh_CN/io_ordering.txt   |   67 +
 Documentation/translations/zh_CN/magic-number.txt  |  153 +
 Documentation/translations/zh_CN/oops-tracing.txt  |  212 ++
 Documentation/translations/zh_CN/sparse.txt        |  100 +
 .../translations/zh_CN/stable_api_nonsense.txt     |  157 +
 .../translations/zh_CN/stable_kernel_rules.txt     |   66 +
 .../translations/zh_CN/video4linux/omap3isp.txt    |  277 ++
 .../zh_CN/video4linux/v4l2-framework.txt           |  976 ++++++
 .../zh_CN/volatile-considered-harmful.txt          |  113 +
 Documentation/zh_CN/CodingStyle                    |  813 -----
 Documentation/zh_CN/HOWTO                          |  536 ----
 Documentation/zh_CN/IRQ.txt                        |   39 -
 Documentation/zh_CN/SecurityBugs                   |   50 -
 Documentation/zh_CN/SubmittingDrivers              |  164 -
 Documentation/zh_CN/SubmittingPatches              |  412 ---
 Documentation/zh_CN/arm/Booting                    |  175 --
 Documentation/zh_CN/arm/kernel_user_helpers.txt    |  284 --
 Documentation/zh_CN/arm64/booting.txt              |  246 --
 Documentation/zh_CN/arm64/legacy_instructions.txt  |   72 -
 Documentation/zh_CN/arm64/memory.txt               |  114 -
 Documentation/zh_CN/arm64/silicon-errata.txt       |   74 -
 Documentation/zh_CN/arm64/tagged-pointers.txt      |   52 -
 Documentation/zh_CN/basic_profiling.txt            |   71 -
 Documentation/zh_CN/email-clients.txt              |  210 --
 Documentation/zh_CN/filesystems/sysfs.txt          |  372 ---
 Documentation/zh_CN/gpio.txt                       |  650 ----
 Documentation/zh_CN/io_ordering.txt                |   67 -
 Documentation/zh_CN/magic-number.txt               |  153 -
 Documentation/zh_CN/oops-tracing.txt               |  212 --
 Documentation/zh_CN/sparse.txt                     |  100 -
 Documentation/zh_CN/stable_api_nonsense.txt        |  157 -
 Documentation/zh_CN/stable_kernel_rules.txt        |   66 -
 Documentation/zh_CN/video4linux/omap3isp.txt       |  277 --
 Documentation/zh_CN/video4linux/v4l2-framework.txt |  976 ------
 .../zh_CN/volatile-considered-harmful.txt          |  113 -
 68 files changed, 12272 insertions(+), 12272 deletions(-)
 delete mode 100644 Documentation/ja_JP/HOWTO
 delete mode 100644 Documentation/ja_JP/SubmitChecklist
 delete mode 100644 Documentation/ja_JP/SubmittingPatches
 delete mode 100644 Documentation/ja_JP/stable_api_nonsense.txt
 delete mode 100644 Documentation/ja_JP/stable_kernel_rules.txt
 delete mode 100644 Documentation/ko_KR/HOWTO
 delete mode 100644 Documentation/ko_KR/memory-barriers.txt
 delete mode 100644 Documentation/ko_KR/stable_api_nonsense.txt
 create mode 100644 Documentation/translations/ja_JP/HOWTO
 create mode 100644 Documentation/translations/ja_JP/SubmitChecklist
 create mode 100644 Documentation/translations/ja_JP/SubmittingPatches
 create mode 100644 Documentation/translations/ja_JP/stable_api_nonsense.txt
 create mode 100644 Documentation/translations/ja_JP/stable_kernel_rules.txt
 create mode 100644 Documentation/translations/ko_KR/HOWTO
 create mode 100644 Documentation/translations/ko_KR/memory-barriers.txt
 create mode 100644 Documentation/translations/ko_KR/stable_api_nonsense.txt
 create mode 100644 Documentation/translations/zh_CN/CodingStyle
 create mode 100644 Documentation/translations/zh_CN/HOWTO
 create mode 100644 Documentation/translations/zh_CN/IRQ.txt
 create mode 100644 Documentation/translations/zh_CN/SecurityBugs
 create mode 100644 Documentation/translations/zh_CN/SubmittingDrivers
 create mode 100644 Documentation/translations/zh_CN/SubmittingPatches
 create mode 100644 Documentation/translations/zh_CN/arm/Booting
 create mode 100644 Documentation/translations/zh_CN/arm/kernel_user_helpers.txt
 create mode 100644 Documentation/translations/zh_CN/arm64/booting.txt
 create mode 100644 Documentation/translations/zh_CN/arm64/legacy_instructions.txt
 create mode 100644 Documentation/translations/zh_CN/arm64/memory.txt
 create mode 100644 Documentation/translations/zh_CN/arm64/silicon-errata.txt
 create mode 100644 Documentation/translations/zh_CN/arm64/tagged-pointers.txt
 create mode 100644 Documentation/translations/zh_CN/basic_profiling.txt
 create mode 100644 Documentation/translations/zh_CN/email-clients.txt
 create mode 100644 Documentation/translations/zh_CN/filesystems/sysfs.txt
 create mode 100644 Documentation/translations/zh_CN/gpio.txt
 create mode 100644 Documentation/translations/zh_CN/io_ordering.txt
 create mode 100644 Documentation/translations/zh_CN/magic-number.txt
 create mode 100644 Documentation/translations/zh_CN/oops-tracing.txt
 create mode 100644 Documentation/translations/zh_CN/sparse.txt
 create mode 100644 Documentation/translations/zh_CN/stable_api_nonsense.txt
 create mode 100644 Documentation/translations/zh_CN/stable_kernel_rules.txt
 create mode 100644 Documentation/translations/zh_CN/video4linux/omap3isp.txt
 create mode 100644 Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
 create mode 100644 Documentation/translations/zh_CN/volatile-considered-harmful.txt
 delete mode 100644 Documentation/zh_CN/CodingStyle
 delete mode 100644 Documentation/zh_CN/HOWTO
 delete mode 100644 Documentation/zh_CN/IRQ.txt
 delete mode 100644 Documentation/zh_CN/SecurityBugs
 delete mode 100644 Documentation/zh_CN/SubmittingDrivers
 delete mode 100644 Documentation/zh_CN/SubmittingPatches
 delete mode 100644 Documentation/zh_CN/arm/Booting
 delete mode 100644 Documentation/zh_CN/arm/kernel_user_helpers.txt
 delete mode 100644 Documentation/zh_CN/arm64/booting.txt
 delete mode 100644 Documentation/zh_CN/arm64/legacy_instructions.txt
 delete mode 100644 Documentation/zh_CN/arm64/memory.txt
 delete mode 100644 Documentation/zh_CN/arm64/silicon-errata.txt
 delete mode 100644 Documentation/zh_CN/arm64/tagged-pointers.txt
 delete mode 100644 Documentation/zh_CN/basic_profiling.txt
 delete mode 100644 Documentation/zh_CN/email-clients.txt
 delete mode 100644 Documentation/zh_CN/filesystems/sysfs.txt
 delete mode 100644 Documentation/zh_CN/gpio.txt
 delete mode 100644 Documentation/zh_CN/io_ordering.txt
 delete mode 100644 Documentation/zh_CN/magic-number.txt
 delete mode 100644 Documentation/zh_CN/oops-tracing.txt
 delete mode 100644 Documentation/zh_CN/sparse.txt
 delete mode 100644 Documentation/zh_CN/stable_api_nonsense.txt
 delete mode 100644 Documentation/zh_CN/stable_kernel_rules.txt
 delete mode 100644 Documentation/zh_CN/video4linux/omap3isp.txt
 delete mode 100644 Documentation/zh_CN/video4linux/v4l2-framework.txt
 delete mode 100644 Documentation/zh_CN/volatile-considered-harmful.txt

diff --git a/Documentation/ja_JP/HOWTO b/Documentation/ja_JP/HOWTO
deleted file mode 100644
index b03fc8047f03..000000000000
--- a/Documentation/ja_JP/HOWTO
+++ /dev/null
@@ -1,637 +0,0 @@
-NOTE:
-This is a version of Documentation/HOWTO translated into Japanese.
-This document is maintained by Tsugikazu Shibata 
-and the JF Project team .
-If you find any difference between this document and the original file
-or a problem with the translation,
-please contact the maintainer of this file or JF project.
-
-Please also note that the purpose of this file is to be easier to read
-for non English (read: Japanese) speakers and is not intended as a
-fork. So if you have any comments or updates for this file, please try
-to update the original English file first.
-
-Last Updated: 2013/07/19
-==================================
-これは、
-linux-3.10/Documentation/HOWTO
-の和訳です。
-
-翻訳団体： JF プロジェクト < http://linuxjf.sourceforge.jp/ >
-翻訳日： 2013/7/19
-翻訳者： Tsugikazu Shibata 
-校正者： 松倉さん 
-         小林 雅典さん (Masanori Kobayasi) 
-         武井伸光さん、
-         かねこさん (Seiji Kaneko) 
-         野口さん (Kenji Noguchi) 
-         河内さん (Takayoshi Kochi) 
-         岩本さん (iwamoto) 
-         内田さん (Satoshi Uchida) 
-==================================
-
-Linux カーネル開発のやり方
--------------------------------
-
-これは上のトピック( Linux カーネル開発のやり方)の重要な事柄を網羅した
-ドキュメントです。ここには Linux カーネル開発者になるための方法と
-Linux カーネル開発コミュニティと共に活動するやり方を学ぶ方法が含まれて
-います。カーネルプログラミングに関する技術的な項目に関することは何も含
-めないようにしていますが、カーネル開発者となるための正しい方向に向かう
-手助けになります。
-
-もし、このドキュメントのどこかが古くなっていた場合には、このドキュメン
-トの最後にリストしたメンテナにパッチを送ってください。
-
-はじめに
----------
-
-あなたは　Linux カーネルの開発者になる方法を学びたいのでしょうか？　そ
-れともあなたは上司から「このデバイスの Linux ドライバを書くように」と
-言われているのでしょうか？　
-この文書の目的は、あなたが踏むべき手順と、コミュニティと一緒にうまく働
-くヒントを書き下すことで、あなたが知るべき全てのことを教えることです。
-また、このコミュニティがなぜ今うまくまわっているのかという理由の一部も
-説明しようと試みています。
-
-
-カーネルは 少量のアーキテクチャ依存部分がアセンブリ言語で書かれている
-以外は大部分は C 言語で書かれています。C言語をよく理解していることはカー
-ネル開発者には必要です。アーキテクチャ向けの低レベル部分の開発をするの
-でなければ、(どんなアーキテクチャでも)アセンブリ(訳注: 言語)は必要あり
-ません。以下の本は、C 言語の十分な知識や何年もの経験に取って代わるもの
-ではありませんが、少なくともリファレンスとしては良い本です。
- - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
- -『プログラミング言語Ｃ第2版』(B.W. カーニハン/D.M. リッチー著 石田晴久訳) [共立出版]
- - "Practical C Programming" by Steve Oualline [O'Reilly]
- - 『C実践プログラミング第3版』(Steve Oualline著 望月康司監訳 谷口功訳) [オライリージャパン]
- - "C:  A Reference Manual" by Harbison and Steele [Prentice Hall]
- - 『新・詳説 C 言語 H&S リファレンス』
-       (サミュエル P ハービソン/ガイ L スティール共著 斉藤 信男監訳)[ソフトバンク]
-
-カーネルは GNU C と GNU ツールチェインを使って書かれています。カーネル
-は ISO C89 仕様に準拠して書く一方で、標準には無い言語拡張を多く使って
-います。カーネルは標準 C ライブラリとは関係がないといった、C 言語フリー
-スタンディング環境です。そのため、C の標準で使えないものもあります。任
-意の long long の除算や浮動小数点は使えません。
-ときどき、カーネルがツールチェインや C 言語拡張に置いている前提がどう
-なっているのかわかりにくいことがあり、また、残念なことに決定的なリファ
-レンスは存在しません。情報を得るには、gcc の info ページ( info gcc )を
-見てください。
-
-あなたは既存の開発コミュニティと一緒に作業する方法を学ぼうとしているこ
-とに留意してください。そのコミュニティは、コーディング、スタイル、
-開発手順について高度な標準を持つ、多様な人の集まりです。
-地理的に分散した大規模なチームに対してもっともうまくいくとわかったこと
-をベースにしながら、これらの標準は長い時間をかけて築かれてきました。
-これらはきちんと文書化されていますから、事前にこれらの標準についてでき
-るだけたくさん学んでください。また皆があなたやあなたの会社のやり方に合わ
-せてくれると思わないでください。
-
-法的問題
-------------
-
-Linux カーネルのソースコードは GPL ライセンスの下でリリースされていま
-す。ライセンスの詳細については、ソースツリーのメインディレクトリに存在
-する、COPYING のファイルを見てください。もしライセンスについてさらに質
-問があれば、Linux Kernel メーリングリストに質問するのではなく、どうぞ
-法律家に相談してください。メーリングリストの人達は法律家ではなく、法的
-問題については彼らの声明はあてにするべきではありません。
-
-GPL に関する共通の質問や回答については、以下を参照してください。
-	http://www.gnu.org/licenses/gpl-faq.html
-
-ドキュメント
-------------
-
-Linux カーネルソースツリーは幅広い範囲のドキュメントを含んでおり、それ
-らはカーネルコミュニティと会話する方法を学ぶのに非常に貴重なものです。
-新しい機能がカーネルに追加される場合、その機能の使い方について説明した
-新しいドキュメントファイルも追加することを勧めます。
-カーネルの変更が、カーネルがユーザ空間に公開しているインターフェイスの
-変更を引き起こす場合、その変更を説明するマニュアルページのパッチや情報
-をマニュアルページのメンテナ mtk.manpages@gmail.com に送り、CC を
-linux-api@ver.kernel.org に送ることを勧めます。
-
-以下はカーネルソースツリーに含まれている読んでおくべきファイルの一覧で
-す-
-
-  README
-    このファイルは Linuxカーネルの簡単な背景とカーネルを設定(訳注
-    configure )し、生成(訳注 build )するために必要なことは何かが書かれ
-    ています。カーネルに関して初めての人はここからスタートすると良いで
-    しょう。
-
-  Documentation/Changes
-     このファイルはカーネルをうまく生成(訳注 build )し、走らせるのに最
-     小限のレベルで必要な数々のソフトウェアパッケージの一覧を示してい
-     ます。
-
-  Documentation/process/coding-style.rst
-    これは Linux カーネルのコーディングスタイルと背景にある理由を記述
-    しています。全ての新しいコードはこのドキュメントにあるガイドライン
-    に従っていることを期待されています。大部分のメンテナはこれらのルー
-    ルに従っているものだけを受け付け、多くの人は正しいスタイルのコード
-    だけをレビューします。
-
-  Documentation/process/submitting-patches.rst
-  Documentation/process/submitting-drivers.rst
-     これらのファイルには、どうやってうまくパッチを作って投稿するかに
-     ついて非常に詳しく書かれており、以下を含みます(これだけに限らない
-     けれども)
-        - Email に含むこと
-        - Email の形式
-        - だれに送るか
-     これらのルールに従えばうまくいくことを保証することではありません
-     が (すべてのパッチは内容とスタイルについて精査を受けるので)、
-     ルールに従わなければ間違いなくうまくいかないでしょう。
-
-     この他にパッチを作る方法についてのよくできた記述は-
-
-	"The Perfect Patch"
-		http://www.ozlabs.org/~akpm/stuff/tpp.txt
-	"Linux kernel patch submission format"
-		http://linux.yyz.us/patch-format.html
-
-  Documentation/process/stable-api-nonsense.rst
-     このファイルはカーネルの中に不変のAPIを持たないことにした意識的な
-     決断の背景にある理由について書かれています。以下のようなことを含
-     んでいます-
-       - サブシステムとの間に層を作ること(コンパチビリティのため?)
-       - オペレーティングシステム間のドライバの移植性
-       - カーネルソースツリーの素早い変更を遅らせる(もしくは素早い変更
-         を妨げる)
-     このドキュメントは Linux 開発の思想を理解するのに非常に重要です。
-     そして、他のOSでの開発者が Linux に移る時にとても重要です。
-
-  Documentation/admin-guide/security-bugs.rst
-    もし Linux カーネルでセキュリティ問題を発見したように思ったら、こ
-    のドキュメントのステップに従ってカーネル開発者に連絡し、問題解決を
-    支援してください。
-
-  Documentation/process/management-style.rst
-    このドキュメントは Linux カーネルのメンテナ達がどう行動するか、
-    彼らの手法の背景にある共有されている精神について記述しています。こ
-    れはカーネル開発の初心者なら（もしくは、単に興味があるだけの人でも）
-    重要です。なぜならこのドキュメントは、カーネルメンテナ達の独特な
-    行動についての多くの誤解や混乱を解消するからです。
-
-  Documentation/process/stable-kernel-rules.rst
-    このファイルはどのように stable カーネルのリリースが行われるかのルー
-    ルが記述されています。そしてこれらのリリースの中のどこかで変更を取
-    り入れてもらいたい場合に何をすれば良いかが示されています。
-
-  Documentation/process/kernel-docs.rst
-　　カーネル開発に付随する外部ドキュメントのリストです。もしあなたが
-    探しているものがカーネル内のドキュメントでみつからなかった場合、
-    このリストをあたってみてください。
-
-  Documentation/process/applying-patches.rst
-    パッチとはなにか、パッチをどうやって様々なカーネルの開発ブランチに
-    適用するのかについて正確に記述した良い入門書です。
-
-カーネルはソースコードから自動的に生成可能な多数のドキュメントを自分自
-身でもっています。これにはカーネル内 API のすべての記述や、どう正しく
-ロックをかけるかの規則が含まれます。このドキュメントは
-Documentation/DocBook/ ディレクトリに作られ、以下のように
-	make pdfdocs
-	make psdocs
-	make htmldocs
-	make mandocs
-コマンドを実行するとメインカーネルのソースディレクトリから
-それぞれ、PDF, Postscript, HTML, man page の形式で生成されます。
-
-カーネル開発者になるには
----------------------------
-
-もしあなたが、Linux カーネル開発について何も知らないならば、
-KernelNewbies プロジェクトを見るべきです
-	http://kernelnewbies.org
-
-このサイトには役に立つメーリングリストがあり、基本的なカーネル開発に関
-するほとんどどんな種類の質問もできます (既に回答されているようなことを
-聞く前にまずはアーカイブを調べてください)。
-またここには、リアルタイムで質問を聞くことができる IRC チャネルや、Linux
-カーネルの開発に関して学ぶのに便利なたくさんの役に立つドキュメントがあ
-ります。
-
-web サイトには、コードの構成、サブシステム、現在存在するプロジェクト(ツ
-リーにあるもの無いものの両方)の基本的な管理情報があります。
-ここには、また、カーネルのコンパイルのやり方やパッチの当て方などの間接
-的な基本情報も記述されています。
-
-あなたがどこからスタートして良いかわからないが、Linux カーネル開発コミュ
-ニティに参加して何かすることをさがしている場合には、Linux kernel
-Janitor's プロジェクトにいけば良いでしょう -
-	http://kernelnewbies.org/KernelJanitors
-ここはそのようなスタートをするのにうってつけの場所です。ここには、
-Linux カーネルソースツリーの中に含まれる、きれいにし、修正しなければな
-らない、単純な問題のリストが記述されています。このプロジェクトに関わる
-開発者と一緒に作業することで、あなたのパッチを Linuxカーネルツリーに入
-れるための基礎を学ぶことができ、そしてもしあなたがまだアイディアを持っ
-ていない場合には、次にやる仕事の方向性が見えてくるかもしれません。
-
-もしあなたが、すでにひとまとまりコードを書いていて、カーネルツリーに入
-れたいと思っていたり、それに関する適切な支援を求めたい場合、カーネル
-メンターズプロジェクトはそのような皆さんを助けるためにできました。
-ここにはメーリングリストがあり、以下から参照できます
-	http://selenic.com/mailman/listinfo/kernel-mentors
-
-実際に Linux カーネルのコードについて修正を加える前に、どうやってその
-コードが動作するのかを理解することが必要です。そのためには、特別なツー
-ルの助けを借りてでも、それを直接よく読むことが最良の方法です(ほとんど
-のトリッキーな部分は十分にコメントしてありますから)。そういうツールで
-特におすすめなのは、Linux クロスリファレンスプロジェクトです。これは、
-自己参照方式で、索引がついた web 形式で、ソースコードを参照することが
-できます。この最新の素晴しいカーネルコードのリポジトリは以下で見つかり
-ます-
-	http://lxr.free-electrons.com/
-
-開発プロセス
------------------------
-
-Linux カーネルの開発プロセスは現在幾つかの異なるメインカーネル「ブラン
-チ」と多数のサブシステム毎のカーネルブランチから構成されます。
-これらのブランチとは-
-  - メインの 3.x カーネルツリー
-  - 3.x.y -stable カーネルツリー
-  - 3.x -git カーネルパッチ
-  - サブシステム毎のカーネルツリーとパッチ
-  - 統合テストのための 3.x -next カーネルツリー
-
-3.x カーネルツリー
------------------
-
-3.x カーネルは Linus Torvalds によってメンテナンスされ、kernel.org
-の pub/linux/kernel/v3.x/ ディレクトリに存在します。この開発プロセスは
-以下のとおり-
-
-  - 新しいカーネルがリリースされた直後に、2週間の特別期間が設けられ、
-    この期間中に、メンテナ達は Linus に大きな差分を送ることができます。
-    このような差分は通常 -next カーネルに数週間含まれてきたパッチです。
-    大きな変更は git(カーネルのソース管理ツール、詳細は
-    http://git-scm.com/ 参照) を使って送るのが好ましいやり方ですが、パッ
-    チファイルの形式のまま送るのでも十分です。
-
-  - 2週間後、-rc1 カーネルがリリースされ、この後にはカーネル全体の安定
-    性に影響をあたえるような新機能は含まない類のパッチしか取り込むこと
-    はできません。新しいドライバ(もしくはファイルシステム)のパッチは
-    -rc1 の後で受け付けられることもあることを覚えておいてください。な
-    ぜなら、変更が独立していて、追加されたコードの外の領域に影響を与え
-    ない限り、退行のリスクは無いからです。-rc1 がリリースされた後、
-    Linus へパッチを送付するのに git を使うこともできますが、パッチは
-    レビューのために、パブリックなメーリングリストへも同時に送る必要が
-    あります。
-
-  - 新しい -rc は Linus が、最新の git ツリーがテスト目的であれば十分
-    に安定した状態にあると判断したときにリリースされます。目標は毎週新
-    しい -rc カーネルをリリースすることです。
-
-  - このプロセスはカーネルが 「準備ができた」と考えられるまで継続しま
-    す。このプロセスはだいたい 6週間継続します。
-
-Andrew Morton が Linux-kernel メーリングリストにカーネルリリースについ
-て書いたことをここで言っておくことは価値があります-
-  「カーネルがいつリリースされるかは誰も知りません。なぜなら、これは現
-  実に認識されたバグの状況によりリリースされるのであり、前もって決めら
-  れた計画によってリリースされるものではないからです。」
-
-3.x.y -stable カーネルツリー
----------------------------
-
-バージョン番号が3つの数字に分かれているカーネルは -stable カーネルです。
-これには、3.x カーネルで見つかったセキュリティ問題や重大な後戻りに対
-する比較的小さい重要な修正が含まれます。
-
-これは、開発/実験的バージョンのテストに協力することに興味が無く、
-最新の安定したカーネルを使いたいユーザに推奨するブランチです。
-
-もし、3.x.y カーネルが存在しない場合には、番号が一番大きい 3.x が
-最新の安定版カーネルです。
-
-3.x.y は "stable" チーム  でメンテされており、必
-要に応じてリリースされます。通常のリリース期間は 2週間毎ですが、差し迫っ
-た問題がなければもう少し長くなることもあります。セキュリティ関連の問題
-の場合はこれに対してだいたいの場合、すぐにリリースがされます。
-
-カーネルツリーに入っている、Documentation/process/stable-kernel-rules.rst ファ
-イルにはどのような種類の変更が -stable ツリーに受け入れ可能か、またリ
-リースプロセスがどう動くかが記述されています。
-
-3.x -git パッチ
-------------------
-
-git リポジトリで管理されているLinus のカーネルツリーの毎日のスナップ
-ショットがあります。(だから -git という名前がついています)。これらのパッ
-チはおおむね毎日リリースされており、Linus のツリーの現状を表します。こ
-れは -rc カーネルと比べて、パッチが大丈夫かどうかも確認しないで自動的
-に生成されるので、より実験的です。
-
-サブシステム毎のカーネルツリーとパッチ
--------------------------------------------
-
-それぞれのカーネルサブシステムのメンテナ達は --- そして多くのカーネル
-サブシステムの開発者達も --- 各自の最新の開発状況をソースリポジトリに
-公開しています。そのため、自分とは異なる領域のカーネルで何が起きている
-かを他の人が見られるようになっています。開発が早く進んでいる領域では、
-開発者は自身の投稿がどのサブシステムカーネルツリーを元にしているか質問
-されるので、その投稿とすでに進行中の他の作業との衝突が避けられます。
-
-大部分のこれらのリポジトリは git ツリーです。しかしその他の SCM や
-quilt シリーズとして公開されているパッチキューも使われています。これら
-のサブシステムリポジトリのアドレスは MAINTAINERS ファイルにリストされ
-ています。これらの多くは http://git.kernel.org/ で参照することができま
-す。
-
-提案されたパッチがこのようなサブシステムツリーにコミットされる前に、メー
-リングリストで事前にレビューにかけられます（以下の対応するセクションを
-参照）。いくつかのカーネルサブシステムでは、このレビューは patchwork
-というツールによって追跡されます。Patchwork は web インターフェイスに
-よってパッチ投稿の表示、パッチへのコメント付けや改訂などができ、そして
-メンテナはパッチに対して、レビュー中、受付済み、拒否というようなマーク
-をつけることができます。大部分のこれらの patchwork のサイトは
-http://patchwork.kernel.org/ でリストされています。
-
-統合テストのための 3.x -next カーネルツリー
----------------------------------------------
-
-サブシステムツリーの更新内容がメインラインの 3.x ツリーにマージされ
-る前に、それらは統合テストされる必要があります。この目的のため、実質的
-に全サブシステムツリーからほぼ毎日プルされてできる特別なテスト用のリ
-ポジトリが存在します-
-       http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
-
-このやり方によって、-next カーネルは次のマージ機会でどんなものがメイン
-ラインカーネルにマージされるか、おおまかなの展望を提供します。-next 
-カーネルの実行テストを行う冒険好きなテスターは大いに歓迎されます
-
-バグレポート
--------------
-
-bugzilla.kernel.org は Linux カーネル開発者がカーネルのバグを追跡する
-場所です。ユーザは見つけたバグの全てをこのツールで報告すべきです。
-どう kernel bugzilla を使うかの詳細は、以下を参照してください-
-	http://bugzilla.kernel.org/page.cgi?id=faq.html
-メインカーネルソースディレクトリにあるファイル admin-guide/reporting-bugs.rst はカーネ
-ルバグらしいものについてどうレポートするかの良いテンプレートであり、問
-題の追跡を助けるためにカーネル開発者にとってどんな情報が必要なのかの詳
-細が書かれています。
-
-バグレポートの管理
--------------------
-
-あなたのハッキングのスキルを訓練する最高の方法のひとつに、他人がレポー
-トしたバグを修正することがあります。あなたがカーネルをより安定化させる
-こに寄与するということだけでなく、あなたは 現実の問題を修正することを
-学び、自分のスキルも強化でき、また他の開発者があなたの存在に気がつき
-ます。バグを修正することは、多くの開発者の中から自分が功績をあげる最善
-の道です、なぜなら多くの人は他人のバグの修正に時間を浪費することを好ま
-ないからです。
-
-すでにレポートされたバグのために仕事をするためには、
-http://bugzilla.kernel.org に行ってください。もし今後のバグレポートに
-ついてアドバイスを受けたいのであれば、bugme-new メーリングリスト(新し
-いバグレポートだけがここにメールされる) または bugme-janitor メーリン
-グリスト(bugzilla の変更毎にここにメールされる)を購読できます。
-
-	http://lists.linux-foundation.org/mailman/listinfo/bugme-new
-	http://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
-
-メーリングリスト
--------------
-
-上のいくつかのドキュメントで述べていますが、コアカーネル開発者の大部分
-は Linux kernel メーリングリストに参加しています。このリストの登録/脱
-退の方法については以下を参照してください-
-	http://vger.kernel.org/vger-lists.html#linux-kernel
-
-このメーリングリストのアーカイブは web 上の多数の場所に存在します。こ
-れらのアーカイブを探すにはサーチエンジンを使いましょう。例えば-
-	http://dir.gmane.org/gmane.linux.kernel
-
-リストに投稿する前にすでにその話題がアーカイブに存在するかどうかを検索
-することを是非やってください。多数の事がすでに詳細に渡って議論されて
-おり、アーカイブにのみ記録されています。
-
-大部分のカーネルサブシステムも自分の個別の開発を実施するメーリングリス
-トを持っています。個々のグループがどんなリストを持っているかは、
-MAINTAINERS ファイルにリストがありますので参照してください。
-
-多くのリストは kernel.org でホストされています。これらの情報は以下にあ
-ります-
-	http://vger.kernel.org/vger-lists.html
-
-メーリングリストを使う場合、良い行動習慣に従うようにしましょう。
-少し安っぽいが、以下の URL は上のリスト(や他のリスト)で会話する場合の
-シンプルなガイドラインを示しています-
-	http://www.albion.com/netiquette/
-
-もし複数の人があなたのメールに返事をした場合、CC: で受ける人のリストは
-だいぶ多くなるでしょう。良い理由がない場合、CC: リストから誰かを削除を
-しないように、また、メーリングリストのアドレスだけにリプライすることの
-ないようにしましょう。1つは送信者から、もう1つはリストからのように、メー
-ルを2回受けることになってもそれに慣れ、しゃれたメールヘッダーを追加し
-てこの状態を変えようとしないように。人々はそのようなことは好みません。
-
-今までのメールでのやりとりとその間のあなたの発言はそのまま残し、
-"John Kernelhacker wrote ...:" の行をあなたのリプライの先頭行にして、
-メールの先頭でなく、各引用行の間にあなたの言いたいことを追加するべきで
-す。
-
-もしパッチをメールに付ける場合は、Documentation/process/submitting-patches.rst に提
-示されているように、それは プレーンな可読テキストにすることを忘れない
-ようにしましょう。カーネル開発者は 添付や圧縮したパッチを扱いたがりま
-せん-
-彼らはあなたのパッチの行毎にコメントを入れたいので、そのためにはそうす
-るしかありません。あなたのメールプログラムが空白やタブを圧縮しないよう
-に確認した方が良いです。最初の良いテストとしては、自分にメールを送って
-みて、そのパッチを自分で当ててみることです。もしそれがうまく行かないな
-ら、あなたのメールプログラムを直してもらうか、正しく動くように変えるべ
-きです。
-
-とりわけ、他の登録者に対する尊敬を表すようにすることを覚えておいてくだ
-さい。
-
-コミュニティと共に働くこと
---------------------------
-
-カーネルコミュニティのゴールは可能なかぎり最高のカーネルを提供すること
-です。あなたがパッチを受け入れてもらうために投稿した場合、それは、技術
-的メリットだけがレビューされます。その際、あなたは何を予想すべきでしょ
-うか?
-  - 批判
-  - コメント
-  - 変更の要求
-  - パッチの正当性の証明要求
-  - 沈黙
-
-思い出してください、ここはあなたのパッチをカーネルに入れる話です。あ
-なたは、あなたのパッチに対する批判とコメントを受け入れるべきで、それら
-を技術的レベルで評価して、パッチを再作成するか、なぜそれらの変更をすべ
-きでないかを明確で簡潔な理由の説明を提供してください。
-もし、あなたのパッチに何も反応がない場合、たまにはメールの山に埋もれて
-見逃され、あなたの投稿が忘れられてしまうこともあるので、数日待って再度
-投稿してください。
-
-あなたがやるべきでないものは?
-  - 質問なしにあなたのパッチが受け入れられると想像すること
-  - 守りに入ること
-  - コメントを無視すること
-  - 要求された変更を何もしないでパッチを出し直すこと
-
-可能な限り最高の技術的解決を求めているコミュニティでは、パッチがどのく
-らい有益なのかについては常に異なる意見があります。あなたは協調的である
-べきですし、また、あなたのアイディアをカーネルに対してうまく合わせるよ
-うにすることが望まれています。もしくは、最低限あなたのアイディアがそれ
-だけの価値があるとすすんで証明するようにしなければなりません。
-正しい解決に向かって進もうという意志がある限り、間違うことがあっても許
-容されることを忘れないでください。
-
-あなたの最初のパッチに単に 1ダースもの修正を求めるリストの返答になるこ
-とも普通のことです。これはあなたのパッチが受け入れられないということで
-は *ありません*、そしてあなた自身に反対することを意味するのでも *ありま
-せん*。単に自分のパッチに対して指摘された問題を全て修正して再送すれば
-良いのです。
-
-
-カーネルコミュニティと企業組織のちがい
------------------------------------------------------------------
-
-カーネルコミュニティは大部分の伝統的な会社の開発環境とは異ったやり方で
-動いています。以下は問題を避けるためにできると良いことのリストです-
-
-  あなたの提案する変更について言うときのうまい言い方：
-
-    - "これは複数の問題を解決します"
-    - "これは2000行のコードを削除します"
-    - "以下のパッチは、私が言おうとしていることを説明するものです"
-    - "私はこれを5つの異なるアーキテクチャでテストしたのですが..."
-    - "以下は一連の小さなパッチ群ですが..."
-    - "これは典型的なマシンでの性能を向上させます.."
-
-  やめた方が良い悪い言い方：
-
-    - このやり方で AIX/ptx/Solaris ではできたので、できるはずだ
-    - 私はこれを20年もの間やってきた、だから
-    - これは、私の会社が金儲けをするために必要だ
-    - これは我々のエンタープライズ向け商品ラインのためである
-    - これは 私が自分のアイディアを記述した、1000ページの設計資料である
-    - 私はこれについて、6ケ月作業している。
-    - 以下は ... に関する5000行のパッチです
-    - 私は現在のぐちゃぐちゃを全部書き直した、それが以下です...
-    - 私は〆切がある、そのためこのパッチは今すぐ適用される必要がある
-
-カーネルコミュニティが大部分の伝統的なソフトウェアエンジニアリングの労
-働環境と異なるもう一つの点は、やりとりに顔を合わせないということです。
-email と irc を第一のコミュニケーションの形とする一つの利点は、性別や
-民族の差別がないことです。Linux カーネルの職場環境は女性や少数民族を受
-容します。なぜなら、email アドレスによってのみあなたが認識されるからで
-す。
-国際的な側面からも活動領域を均等にするようにします。なぜならば、あなた
-は人の名前で性別を想像できないからです。ある男性が アンドレアという名
-前で、女性の名前は パット かもしれません (訳注 Andrea は米国では女性、
-それ以外(欧州など)では男性名として使われることが多い。同様に、Pat は
-Patricia (主に女性名)や Patrick (主に男性名)の略称)。
-Linux カーネルの活動をして、意見を表明したことがある大部分の女性は、前
-向きな経験をもっています。
-
-言葉の壁は英語が得意でない一部の人には問題になります。
-メーリングリストの中できちんとアイディアを交換するには、相当うまく英語
-を操れる必要があることもあります。そのため、あなたは自分のメール
-を送る前に英語で意味が通じているかをチェックすることをお薦めします。
-
-変更を分割する
----------------------
-
-Linux カーネルコミュニティは、一度に大量のコードの塊を喜んで受容するこ
-とはありません。変更は正確に説明される必要があり、議論され、小さい、個
-別の部分に分割する必要があります。これはこれまで多くの会社がやり慣れて
-きたことと全く正反対のことです。あなたのプロポーザルは、開発プロセスのと
-ても早い段階から紹介されるべきです。そうすれば あなたは自分のやってい
-ることにフィードバックを得られます。これは、コミュニティからみれば、あ
-なたが彼らと一緒にやっているように感じられ、単にあなたの提案する機能の
-ゴミ捨て場として使っているのではない、と感じられるでしょう。
-しかし、一度に 50 もの email をメーリングリストに送りつけるようなことは
-やってはいけません、あなたのパッチ群はいつもどんな時でもそれよりは小さ
-くなければなりません。
-
-パッチを分割する理由は以下です-
-
-1) 小さいパッチはあなたのパッチが適用される見込みを大きくします、カー
-   ネルの人達はパッチが正しいかどうかを確認する時間や労力をかけないか
-   らです。5行のパッチはメンテナがたった1秒見るだけで適用できます。
-   しかし、500行のパッチは、正しいことをレビューするのに数時間かかるか
-   もしれません(時間はパッチのサイズなどにより指数関数に比例してかかり
-   ます)
-
-   小さいパッチは何かあったときにデバッグもとても簡単になります。パッ
-   チを1個1個取り除くのは、とても大きなパッチを当てた後に(かつ、何かお
-   かしくなった後で)解剖するのに比べればとても簡単です。
-
-2) 小さいパッチを送るだけでなく、送るまえに、書き直して、シンプルにす
-   る(もしくは、単に順番を変えるだけでも)ことも、とても重要です。
-
-以下はカーネル開発者の Al Viro のたとえ話です：
-
-        "生徒の数学の宿題を採点する先生のことを考えてみてください、先
-        生は生徒が解に到達するまでの試行錯誤を見たいとは思わないでしょ
-        う。先生は簡潔な最高の解を見たいのです。良い生徒はこれを知って
-        おり、そして最終解の前の中間作業を提出することは決してないので
-        す"
-
-        カーネル開発でもこれは同じです。メンテナ達とレビューア達は、
-        問題を解決する解の背後になる思考プロセスを見たいとは思いません。
-        彼らは単純であざやかな解決方法を見たいのです。
-
-あざやかな解を説明するのと、コミュニティと共に仕事をし、未解決の仕事を
-議論することのバランスをキープするのは難しいかもしれません。
-ですから、開発プロセスの早期段階で改善のためのフィードバックをもらうよ
-うにするのも良いですが、変更点を小さい部分に分割して全体ではまだ完成し
-ていない仕事を(部分的に)取り込んでもらえるようにすることも良いことです。
-
-また、でき上がっていないものや、"将来直す" ようなパッチを、本流に含め
-てもらうように送っても、それは受け付けられないことを理解してください。
-
-あなたの変更を正当化する
--------------------
-
-あなたのパッチを分割するのと同時に、なぜその変更を追加しなければならな
-いかを Linux コミュニティに知らせることはとても重要です。新機能は必要
-性と有用性で正当化されなければなりません。
-
-あなたの変更の説明
---------------------
-
-あなたのパッチを送付する場合には、メールの中のテキストで何を言うかにつ
-いて、特別に注意を払ってください。この情報はパッチの ChangeLog に使わ
-れ、いつも皆がみられるように保管されます。これは次のような項目を含め、
-パッチを完全に記述するべきです-
-
-  - なぜ変更が必要か
-  - パッチ全体の設計アプローチ
-  - 実装の詳細
-  - テスト結果
-
-これについて全てがどのようにあるべきかについての詳細は、以下のドキュメ
-ントの ChangeLog セクションを見てください-
-  "The Perfect Patch"
-      http://www.ozlabs.org/~akpm/stuff/tpp.txt
-
-これらのどれもが、時にはとても困難です。これらの慣例を完璧に実施するに
-は数年かかるかもしれません。これは継続的な改善のプロセスであり、そのた
-めには多数の忍耐と決意を必要とするものです。でも、諦めないで、これは可
-能なことです。多数の人がすでにできていますし、彼らも皆最初はあなたと同
-じところからスタートしたのですから。
-
-Paolo Ciarrocchi に感謝、彼は彼の書いた "Development Process"
-(http://lwn.net/Articles/94386/) セクションをこのテキストの原型にする
-ことを許可してくれました。Rundy Dunlap と Gerrit Huizenga はメーリング
-リストでやるべきこととやってはいけないことのリストを提供してくれました。
-以下の人々のレビュー、コメント、貢献に感謝。
-Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers,
-Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi
-Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop,
-David A. Wheeler, Junio Hamano, Michael Kerrisk, と Alex Shepard
-彼らの支援なしでは、このドキュメントはできなかったでしょう。
-
-Maintainer: Greg Kroah-Hartman 
diff --git a/Documentation/ja_JP/SubmitChecklist b/Documentation/ja_JP/SubmitChecklist
deleted file mode 100644
index 60c7c35ac517..000000000000
--- a/Documentation/ja_JP/SubmitChecklist
+++ /dev/null
@@ -1,111 +0,0 @@
-NOTE:
-This is a version of Documentation/process/submit-checklist.rst into Japanese.
-This document is maintained by Takenori Nagano 
-and the JF Project team .
-If you find any difference between this document and the original file
-or a problem with the translation,
-please contact the maintainer of this file or JF project.
-
-Please also note that the purpose of this file is to be easier to read
-for non English (read: Japanese) speakers and is not intended as a
-fork. So if you have any comments or updates of this file, please try
-to update the original English file first.
-
-Last Updated: 2008/07/14
-==================================
-これは、
-linux-2.6.26/Documentation/process/submit-checklist.rst の和訳です。
-
-翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
-翻訳日： 2008/07/14
-翻訳者： Takenori Nagano 
-校正者： Masanori Kobayashi さん 
-==================================
-
-
-Linux カーネルパッチ投稿者向けチェックリスト
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-本書では、パッチをより素早く取り込んでもらいたい開発者が実践すべき基本的な事柄
-をいくつか紹介します。ここにある全ての事柄は、Documentation/process/submitting-patches.rst
-などのLinuxカーネルパッチ投稿に際しての心得を補足するものです。
-
- 1: 妥当なCONFIGオプションや変更されたCONFIGオプション、つまり =y, =m, =n
-    全てで正しくビルドできることを確認してください。その際、gcc及びリンカが
-    warningやerrorを出していないことも確認してください。
-
- 2: allnoconfig, allmodconfig オプションを用いて正しくビルドできることを
-    確認してください。
-
- 3: 手許のクロスコンパイルツールやOSDLのPLMのようなものを用いて、複数の
-    アーキテクチャにおいても正しくビルドできることを確認してください。
-
- 4: 64bit長の'unsigned long'を使用しているppc64は、クロスコンパイルでの
-    チェックに適当なアーキテクチャです。
-
- 5: カーネルコーディングスタイルに準拠しているかどうか確認してください(!)
-
- 6: CONFIGオプションの追加・変更をした場合には、CONFIGメニューが壊れていない
-    ことを確認してください。
-
- 7: 新しくKconfigのオプションを追加する際には、必ずそのhelpも記述してください。
-
- 8: 適切なKconfigの依存関係を考えながら慎重にチェックしてください。
-    ただし、この作業はマシンを使ったテストできちんと行うのがとても困難です。
-    うまくやるには、自分の頭で考えることです。
-
- 9: sparseを利用してちゃんとしたコードチェックをしてください。
-
-10: 'make checkstack' と 'make namespacecheck' を利用し、問題が発見されたら
-    修正してください。'make checkstack' は明示的に問題を示しませんが、どれか
-    １つの関数が512バイトより大きいスタックを使っていれば、修正すべき候補と
-    なります。
-
-11: グローバルなkernel API を説明する kernel-doc をソースの中に含めてください。
-    ( staticな関数においては必須ではありませんが、含めてもらっても結構です )
-    そして、'make htmldocs' もしくは 'make mandocs' を利用して追記した
-    ドキュメントのチェックを行い、問題が見つかった場合には修正を行ってください。
-
-12: CONFIG_PREEMPT, CONFIG_DEBUG_PREEMPT, CONFIG_DEBUG_SLAB,
-    CONFIG_DEBUG_PAGEALLOC, CONFIG_DEBUG_MUTEXES, CONFIG_DEBUG_SPINLOCK,
-    CONFIG_DEBUG_ATOMIC_SLEEP これら全てを同時に有効にして動作確認を
-    行ってください。
-
-13: CONFIG_SMP, CONFIG_PREEMPT を有効にした場合と無効にした場合の両方で
-    ビルドした上、動作確認を行ってください。
-
-14: もしパッチがディスクのI/O性能などに影響を与えるようであれば、
-    'CONFIG_LBDAF'オプションを有効にした場合と無効にした場合の両方で
-    テストを実施してみてください。
-
-15: lockdepの機能を全て有効にした上で、全てのコードパスを評価してください。
-
-16: /proc に新しいエントリを追加した場合には、Documentation/ 配下に
-    必ずドキュメントを追加してください。
-
-17: 新しいブートパラメータを追加した場合には、
-    必ずDocumentation/admin-guide/kernel-parameters.rst に説明を追加してください。
-
-18: 新しくmoduleにパラメータを追加した場合には、MODULE_PARM_DESC()を
-    利用して必ずその説明を記述してください。
-
-19: 新しいuserspaceインタフェースを作成した場合には、Documentation/ABI/ に
-    Documentation/ABI/README を参考にして必ずドキュメントを追加してください。
-
-20: 'make headers_check'を実行して全く問題がないことを確認してください。
-
-21: 少なくともslabアロケーションとpageアロケーションに失敗した場合の
-    挙動について、fault-injectionを利用して確認してください。
-    Documentation/fault-injection/ を参照してください。
-
-    追加したコードがかなりの量であったならば、サブシステム特有の
-    fault-injectionを追加したほうが良いかもしれません。
-
-22: 新たに追加したコードは、`gcc -W'でコンパイルしてください。
-    このオプションは大量の不要なメッセージを出力しますが、
-    "warning: comparison between signed and unsigned" のようなメッセージは、
-    バグを見つけるのに役に立ちます。
-
-23: 投稿したパッチが -mm パッチセットにマージされた後、全ての既存のパッチや
-    VM, VFS およびその他のサブシステムに関する様々な変更と、現時点でも共存
-    できることを確認するテストを行ってください。
diff --git a/Documentation/ja_JP/SubmittingPatches b/Documentation/ja_JP/SubmittingPatches
deleted file mode 100644
index 02139656463e..000000000000
--- a/Documentation/ja_JP/SubmittingPatches
+++ /dev/null
@@ -1,719 +0,0 @@
-NOTE:
-This is a version of Documentation/process/submitting-patches.rst into Japanese.
-This document is maintained by Keiichi KII 
-and the JF Project team .
-If you find any difference between this document and the original file
-or a problem with the translation,
-please contact the maintainer of this file or JF project.
-
-Please also note that the purpose of this file is to be easier to read
-for non English (read: Japanese) speakers and is not intended as a
-fork. So if you have any comments or updates of this file, please try
-to update the original English file first.
-
-Last Updated: 2011/06/09
-
-==================================
-これは、
-linux-2.6.39/Documentation/process/submitting-patches.rst の和訳
-です。
-翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
-翻訳日： 2011/06/09
-翻訳者： Keiichi Kii 
-校正者： Masanari Kobayashi さん 
-         Matsukura さん 
-         Takeshi Hamasaki さん 
-==================================
-
-        Linux カーネルに変更を加えるための Howto
-        又は
-        かの Linus Torvalds の取り扱い説明書
-
-Linux カーネルに変更を加えたいと思っている個人又は会社にとって、パッ
-チの投稿に関連した仕組みに慣れていなければ、その過程は時々みなさんを
-おじけづかせることもあります。この文章はあなたの変更を大いに受け入れ
-てもらえやすくする提案を集めたものです。
-
-コードを投稿する前に、Documentation/process/submit-checklist.rst の項目リストに目
-を通してチェックしてください。もしあなたがドライバーを投稿しようとし
-ているなら、Documentation/process/submitting-drivers.rst にも目を通してください。
-
---------------------------------------------
-セクション1 パッチの作り方と送り方
---------------------------------------------
-
-1) 「 diff -up 」
-------------
-
-パッチの作成には「 diff -up 」又は「 diff -uprN 」を使ってください。
-
-Linux カーネルに対する全ての変更は diff(1) コマンドによるパッチの形式で
-生成してください。パッチを作成するときには、diff(1) コマンドに「 -u 」引
-数を指定して、unified 形式のパッチを作成することを確認してください。また、
-変更がどの C 関数で行われたのかを表示する「 -p 」引数を使ってください。
-この引数は生成した差分をずっと読みやすくしてくれます。パッチは Linux
-カーネルソースの中のサブディレクトリではなく Linux カーネルソースのルート
-ディレクトリを基準にしないといけません。
-
-1個のファイルについてのパッチを作成するためには、ほとんどの場合、
-以下の作業を行えば十分です。
-
-	SRCTREE= linux-2.6
-	MYFILE=  drivers/net/mydriver.c
-
-	cd $SRCTREE
-	cp $MYFILE $MYFILE.orig
-	vi $MYFILE	# make your change
-	cd ..
-	diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
-
-複数のファイルについてのパッチを作成するためには、素の( vanilla )、す
-なわち変更を加えてない Linux カーネルを展開し、自分の Linux カーネル
-ソースとの差分を生成しないといけません。例えば、
-
-	MYSRC= /devel/linux-2.6
-
-	tar xvfz linux-2.6.12.tar.gz
-	mv linux-2.6.12 linux-2.6.12-vanilla
-	diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \
-		linux-2.6.12-vanilla $MYSRC > /tmp/patch
-
-dontdiff ファイルには Linux カーネルのビルドプロセスの過程で生成された
-ファイルの一覧がのっています。そして、それらはパッチを生成する diff(1)
-コマンドで無視されるべきです。dontdiff ファイルは 2.6.12 以後のバージョ
-ンの Linux カーネルソースツリーに含まれています。それより前のバージョン
-の Linux カーネルソースツリーに対する dontdiff ファイルは、
-から取得することができます。
-
-投稿するパッチの中に関係のない余分なファイルが含まれていないことを確
-認してください。diff(1) コマンドで生成したパッチがあなたの意図したとお
-りのものであることを確認してください。
-
-もしあなたのパッチが多くの差分を生み出すのであれば、あなたはパッチ
-を意味のあるひとまとまりごとに分けたいと思うかもしれません。
-これは他のカーネル開発者にとってレビューしやすくなるので、あなたの
-パッチを受け入れてもらうためにはとても重要なことです。これを補助でき
-る多くのスクリプトがあります。
-
-Quilt:
-http://savannah.nongnu.org/projects/quilt
-
-2) パッチに対する説明
-
-パッチの中の変更点に対する技術的な詳細について説明してください。
-
-説明はできる限り具体的に。もっとも悪い説明は「ドライバー X を更新」、
-「ドライバー X に対するバグフィックス」あるいは「このパッチはサブシス
-テム X に対する更新を含んでいます。どうか取り入れてください。」などです。
-
-パッチの説明を Linux カーネルのソースコードマネジメントシステム「 git 」の
-コミットログとして簡単に引用できる形で書けば、メンテナから感謝されるでしょう。
-以下の #15 を見てください。
-
-説明が長くなりだしたのであれば、おそらくそれはパッチを分ける必要がある
-という兆候です。次の #3 を見てください。
-
-パッチ(シリーズ)を(再)投稿する時、十分なパッチの説明とそのパッチが必要な理由を
-パッチに含めてください。ただ「これはパッチ(シリーズ)のバージョン N」とだけ
-書かないでください。そして、パッチをマージする人にパッチの説明を探させそれを
-パッチに追記させるため、過去のバージョンのパッチやそのパッチの URL を参照する
-手間をかけさせないでください。
-つまり、パッチシリーズとその説明は一緒にあるべきです。これはパッチをマージする
-人、レビューする人、どちらのためにもなります。レビューする人の中には、おそらく
-過去のバージョンのパッチを受け取ってもいない人がいます。
-
-登録済みのバグエントリを修正するパッチであれば、そのバグエントリを示すバグ ID
-や URL を明記してください。
-
-3) パッチの分割
-
-意味のあるひとまとまりごとに変更を個々のパッチファイルに分けてください。
-
-例えば、もし1つのドライバーに対するバグフィックスとパフォーマンス強
-化の両方の変更を含んでいるのであれば、その変更を2つ以上のパッチに分
-けてください。もし変更箇所に API の更新と、その新しい API を使う新たな
-ドライバーが含まれているなら、2つのパッチに分けてください。
-
-一方で、もしあなたが多数のファイルに対して意味的に同じ1つの変更を加え
-るのであれば、その変更を1つのパッチにまとめてください。言いかえると、
-意味的に同じ1つの変更は1つのパッチの中に含まれます。
-
-あるパッチが変更を完結させるために他のパッチに依存していたとしても、
-それは問題ありません。パッチの説明の中で「このパッチはパッチ X に依存
-している」と簡単に注意書きをつけてください。
-
-もしパッチをより小さなパッチの集合に凝縮することができないなら、まずは
-15かそこらのパッチを送り、そのレビューと統合を待って下さい。
-
-4) パッチのスタイルチェック
-
-あなたのパッチが基本的な( Linux カーネルの)コーディングスタイルに違反し
-ていないかをチェックして下さい。その詳細を Documentation/process/coding-style.rst で
-見つけることができます。コーディングスタイルの違反はレビューする人の
-時間を無駄にするだけなので、恐らくあなたのパッチは読まれることすらなく
-拒否されるでしょう。
-
-あなたはパッチを投稿する前に最低限パッチスタイルチェッカー
-( scripts/checkpatch.pl )を利用してパッチをチェックすべきです。
-もしパッチに違反がのこっているならば、それらの全てについてあなたは正当な
-理由を示せるようにしておく必要があります。
-
-5) 電子メールの宛先の選び方
-
-MAINTAINERS ファイルとソースコードに目を通してください。そして、その変
-更がメンテナのいる特定のサブシステムに加えられるものであることが分か
-れば、その人に電子メールを送ってください。
-
-もし、メンテナが載っていなかったり、メンテナからの応答がないなら、
-LKML ( linux-kernel@vger.kernel.org )へパッチを送ってください。ほとんど
-のカーネル開発者はこのメーリングリストに目を通しており、変更に対して
-コメントを得ることができます。
-
-15個より多くのパッチを同時に vger.kernel.org のメーリングリストへ送らな
-いでください!!!
-
-Linus Torvalds は Linux カーネルに入る全ての変更に対する最終的な意思決定者
-です。電子メールアドレスは torvalds@linux-foundation.org になります。彼は
-多くの電子メールを受け取っているため、できる限り彼に電子メールを送るのは
-避けるべきです。
-
-バグフィックスであったり、自明な変更であったり、話し合いをほとんど
-必要としないパッチは Linus へ電子メールを送るか CC しなければなりません。
-話し合いを必要としたり、明確なアドバンテージがないパッチは、通常まず
-は LKML へ送られるべきです。パッチが議論された後にだけ、そのパッチを
-Linus へ送るべきです。
-
-6) CC (カーボンコピー)先の選び方
-
-特に理由がないなら、LKML にも CC してください。
-
-Linus 以外のカーネル開発者は変更に気づく必要があり、その結果、彼らはそ
-の変更に対してコメントをくれたり、コードに対してレビューや提案をくれ
-るかもしれません。LKML とは Linux カーネル開発者にとって一番中心的なメー
-リングリストです。USB やフレームバッファデバイスや VFS や SCSI サブシステ
-ムなどの特定のサブシステムに関するメーリングリストもあります。あなた
-の変更に、はっきりと関連のあるメーリングリストについて知りたければ
-MAINTAINERS ファイルを参照してください。
-
-VGER.KERNEL.ORG でホスティングされているメーリングリストの一覧が下記の
-サイトに載っています。
-
-
-もし、変更がユーザランドのカーネルインタフェースに影響を与え
-るのであれば、MAN-PAGES のメンテナ( MAINTAINERS ファイルに一覧
-があります)に man ページのパッチを送ってください。少なくとも
-情報がマニュアルページの中に入ってくるように、変更が起きたという
-通知を送ってください。
-
-たとえ、メンテナが #5 で反応がなかったとしても、メンテナのコードに変更を
-加えたときには、いつもメンテナに CC するのを忘れないようにしてください。
-
-小さなパッチであれば、Trivial Patch Monkey(ちょっとしたパッチを集めている)
-に CC してもいいです。その現管理者については MAINTAINERS
-ファイルを見てください。ちょっとしたパッチとは以下のルールのどれか1つを満たして
-いなければなりません。
- ・ドキュメントのスペルミスの修正
- ・grep(1) コマンドによる検索を困難にしているスペルの修正
- ・コンパイル時の警告の修正(無駄な警告が散乱することは好ましくないた
-   めです)
- ・コンパイル問題の修正(それらの修正が本当に正しい場合に限る)
- ・実行時の問題の修正(それらの修正が本当に問題を修正している場合に限る)
- ・廃止予定の関数やマクロを使用しているコードの除去(例 check_region )
- ・問い合わせ先やドキュメントの修正
- ・移植性のないコードから移植性のあるコードへの置き換え(小さい範囲で
-   あればアーキテクチャ特有のことでも他の人がコピーできます)
- ・作者やメンテナによる修正(すなわち patch monkey の再転送モード)
-
-7) MIME やリンクや圧縮ファイルや添付ファイルではなくプレインテキストのみ
-
-Linus や他のカーネル開発者はあなたが投稿した変更を読んで、コメントでき
-る必要があります。カーネル開発者にとって、あなたが書いたコードの特定の
-部分にコメントをするために、標準的な電子メールクライアントで変更が引用
-できることは重要です。
-
-上記の理由で、すべてのパッチは文中に含める形式の電子メールで投稿さ
-れるべきです。警告：あなたがパッチをコピー&ペーストする際には、パッ
-チを改悪するエディターの折り返し機能に注意してください。
-
-パッチを圧縮の有無に関わらず MIME 形式で添付しないでください。多くのポ
-ピュラーな電子メールクライアントは MIME 形式の添付ファイルをプレーンテ
-キストとして送信するとは限らないでしょう。そうなると、電子メールクラ
-イアントがコードに対するコメントを付けることをできなくします。また、
-MIME 形式の添付ファイルは Linus に手間を取らせることになり、その変更を
-受け入れてもらう可能性が低くなってしまいます。
-
-例外：お使いの電子メールクライアントがパッチをめちゃくちゃにするので
-あれば、誰かが MIME 形式のパッチを再送するよう求めるかもしれません。
-
-余計な変更を加えずにあなたのパッチを送信するための電子メールクライアントの設定
-のヒントについては Documentation/process/email-clients.rst を参照してください。
-
-8) 電子メールのサイズ
-
-パッチを Linus へ送るときは常に #7 の手順に従ってください。
-
-大きなパッチはメーリングリストやメンテナにとって不親切です。パッチが
-未圧縮で 300KB を超えるようであるなら、インターネット上のアクセス可能な
-サーバに保存し、保存場所を示す URL を伝えるほうが適切です。
-
-9) カーネルバージョンの明記
-
-パッチが対象とするカーネルのバージョンをパッチの概要か電子メールの
-サブジェクトに付けることが重要です。
-
-パッチが最新バージョンのカーネルに正しく適用できなければ、Linus は
-そのパッチを採用しないでしょう。
-
-10) がっかりせず再投稿
-
-パッチを投稿した後は、辛抱強く待っていてください。Linus があなたのパッ
-チを気に入って採用すれば、Linus がリリースする次のバージョンのカーネル
-の中で姿を見せるでしょう。
-
-しかし、パッチが次のバージョンのカーネルに入っていないなら、いくつもの
-理由があるのでしょう。その原因を絞り込み、間違っているものを正し、更新
-したパッチを投稿するのはあなたの仕事です。
-
-Linus があなたのパッチに対して何のコメントもなく不採用にすることは極め
-て普通のことです。それは自然な姿です。もし、Linus があなたのパッチを受
-け取っていないのであれば、以下の理由が考えられます。
-* パッチが最新バージョンの Linux カーネルにきちんと適用できなかった
-* パッチが LKML で十分に議論されていなかった
-* スタイルの問題(セクション2を参照)
-* 電子メールフォーマットの問題(このセクションを参照)
-* パッチに対する技術的な問題
-* Linus はたくさんの電子メールを受け取っているので、どさくさに紛れて見
-  失った
-* 不愉快にさせている
-
-判断できない場合は、LKML にコメントを頼んでください。
-
-11) サブジェクトに「 PATCH 」
-
-Linus や LKML への大量の電子メールのために、サブジェクトのプレフィックスに
-「 [PATCH] 」を付けることが慣習となっています。これによって Linus や他の
-カーネル開発者がパッチであるのか、又は、他の議論に関する電子メールであるの
-かをより簡単に識別できます。
-
-12) パッチへの署名
-
-誰が何をしたのかを追いかけやすくするために (特に、パッチが何人かの
-メンテナを経て最終的に Linux カーネルに取り込まれる場合のために)、電子
-メールでやり取りされるパッチに対して「 sign-off 」という手続きを導入し
-ました。
-
-「 sign-off 」とは、パッチがあなたの書いたものであるか、あるいは、
-あなたがそのパッチをオープンソースとして提供する権利を保持している、
-という証明をパッチの説明の末尾に一行記載するというものです。
-ルールはとても単純です。以下の項目を確認して下さい。
-
-        原作者の証明書( DCO ) 1.1
-
-        このプロジェクトに寄与するものとして、以下のことを証明する。
-
-        (a) 本寄与は私が全体又は一部作成したものであり、私がそのファイ
-            ル中に明示されたオープンソースライセンスの下で公開する権利
-            を持っている。もしくは、
-
-        (b) 本寄与は、私が知る限り、適切なオープンソースライセンスでカバ
-            ーされている既存の作品を元にしている。同時に、私はそのライセ
-            ンスの下で、私が全体又は一部作成した修正物を、ファイル中で示
-            される同一のオープンソースライセンスで(異なるライセンスの下で
-            投稿することが許可されている場合を除いて)投稿する権利を持って
-            いる。もしくは、
-
-        (c) 本寄与は(a)、(b)、(c)を証明する第3者から私へ直接提供された
-            ものであり、私はそれに変更を加えていない。
-
-        (d) 私はこのプロジェクトと本寄与が公のものであることに理解及び同意す
-            る。同時に、関与した記録(投稿の際の全ての個人情報と sign-off を
-            含む)が無期限に保全されることと、当該プロジェクト又は関連する
-            オープンソースライセンスに沿った形で再配布されることに理解及び
-            同意する。
-
-もしこれに同意できるなら、以下のような1行を追加してください。
-
-	Signed-off-by: Random J Developer 
-
-実名を使ってください。(残念ですが、偽名や匿名による寄与はできません。)
-
-人によっては sign-off の近くに追加のタグを付加しています。それらは今のところ
-無視されますが、あなたはそのタグを社内の手続きに利用したり、sign-off に特別
-な情報を示したりすることができます。
-
-あなたがサブシステムまたはブランチのメンテナであれば、受け取ったパッチを自身の
-ツリーにマージするために、わずかに変更が必要となる場合があります。なぜなら
-あなたのツリーの中のコードと投稿者のツリーの中のコードは同一ではないためです。
-もし、あなたが厳密に上記ルール(c)にこだわるのであれば、投稿者に再度差分を
-とるよう依頼すべきです。しかし、これは時間とエネルギーを非生産的に浪費する
-ことになります。ルール(b)はあなたにコードを修正する権利を与えてくれます。
-しかし、投稿者のコードを修正し、その修正によるバグを投稿者に押し付けてしまう
-ことはとても失礼なことです。この問題を解決するために、末尾の投稿者の
-Signed-off-by とあなたがその末尾に追加する Signed-off-by の間に、修正を
-加えたことを示す1行を追加することが推奨されています。
-(その1行の書き方に)決まりはありませんが、大括弧の中に電子メールアドレスや氏名
-と修正内容を記載するやり方は目につきやすく、最終段階での変更の責任があなたに
-あることを明確にするのに十分な方法のようです。例えば、
-
-	Signed-off-by: Random J Developer 
-	[lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
-	Signed-off-by: Lucky K Maintainer 
-
-あなたが安定版のブランチを管理しており、作成者のクレジット、変更の追跡、
-修正のマージ、と同時に苦情からの投稿者の保護を行いたい場合、この慣習は特に
-有用となります。いかなる事情があってもチェンジログに出てくる作成者の
-アイデンティティ情報(From ヘッダ)は変更できないことに注意してください。
-
-バックポートする人のための特別な注意事項。追跡を容易に行うために、コミット
-メッセージのトップ(サブジェクト行のすぐ後)にパッチの起源を示す情報を記述する
-ことは一般的で有用な慣習です。例えば、これは 2.6-stable ツリーでの一例です。    
-
-    Date:   Tue May 13 19:10:30 2008 +0000
-
-        SCSI: libiscsi regression in 2.6.25: fix nop timer handling
-
-        commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream
-
-そして、これは 2.4 ツリーでの一例です。
-
-    Date:   Tue May 13 22:12:27 2008 +0200
-
-        wireless, airo: waitbusy() won't delay
-
-        [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
-
-どんな形式であれ、この情報はあなたのツリーを追跡する人やあなたのツリーのバグを
-解決しようとしている人にとって価値のある支援となります。
-
-13) いつ Acked-by: と Cc: を使うのか
-
-「 Signed-off-by: 」タグはその署名者がパッチの開発に関わっていたことやパッチ
-の伝播パスにいたことを示しています。
-
-ある人が直接パッチの準備や作成に関わっていないけれど、その人のパッチに対す
-る承認を記録し、示したいとします。その場合、その人を示すのに Acked-by: が使
-えます。Acked-by: はパッチのチェンジログにも追加されます。
-
-パッチの影響を受けるコードのメンテナがパッチに関わっていなかったり、パッチ
-の伝播パスにいなかった時にも、メンテナは Acked-by: をしばしば利用します。
-
-Acked-by: は Signed-off-by: のように公式なタグではありません。それはメンテナが
-少なくともパッチをレビューし、同意を示しているという記録です。そのような
-ことからパッチをマージする人がメンテナの「うん、良いと思うよ」という発言を
-Acked-by: へ置き換えることがあります。
-
-Acked-by: が必ずしもパッチ全体の承認を示しているわけではありません。例えば、
-あるパッチが複数のサブシステムへ影響を与えており、その中の1つのサブシステム
-のメンテナからの Acked-by: を持っているとします。その場合、Acked-by: は通常
-そのメンテナのコードに影響を与える一部分だけに対する承認を示しています。
-この点は、ご自分で判断してください。(その Acked-by: が)疑わしい場合は、
-メーリングリストアーカイブの中の大元の議論を参照すべきです。
-
-パッチにコメントする機会を持っていたが、その時にコメントしなかった人がいれば、
-その人を指す「Cc:」タグを任意で追加してもかまいません。これは指定された人からの
-明確なアクションなしに付与できる唯一のタグです。
-このタグはパッチに関心があると思われる人達がそのパッチの議論に含まれていたこと
-を明文化します。
-
-14) Reported-by と Tested-by: と Reviewed-by: の利用
-
-他の誰かによって報告された問題を修正するパッチであれば、問題報告者という寄与を
-クレジットするために、Reported-by: タグを追加することを検討してください。
-こまめにバグ報告者をクレジットしていくことで、うまくいけばその人たちが将来再び
-コミュニティの力となってくれるでしょう。
-ただし、報告者の許可無くこのタグを追加しないように注意してください。特に、
-問題が公の場で報告されていなかったのであれば。
-
-Tested-by: タグはタグで指定された人によって(ある環境下で)パッチのテストに成功
-していることを示します。このタグはメンテナにテストが実施済みであることを
-知らせ、将来の関連パッチのテスト協力者を見つける方法を提供し、テスト実施者に
-対するクレジットを保証します。
-
-Reviewed-by: タグは、それとは異なり、下記のレビューア宣言の下にレビューされ、
-受け入れ可能とみなされたパッチであることを示します。
-
-        レビューアによる監督宣言
-
-        私は Reviewed-by: タグを提示することによって、以下のことを明言する。
-
-        (a) 私はメインラインカーネルへの統合に向け、その妥当性及び「即応性
-            (訳注)」を検証し、技術的側面からパッチをレビュー済みである。
-
-        訳注:
-        「即応性」の原文は "readiness"。
-        パッチが十分な品質を持っており、メインラインカーネルへの統合を即座に
-        行うことができる状態であるかどうかを "readiness" という単語で表現
-        している。
-
-        (b) パッチに関するあらゆる問題、懸念、あるいは、疑問は投稿者へ伝達済み
-            である。私はそれらのコメントに対する投稿者の返答に満足している。
-
-        (c) 投稿に伴い改良されるコードがある一方で、現時点で、私は(1)それが
-            カーネルにとって価値のある変更であること、そして、(2)統合に際して
-            議論になり得るような問題はないものと確信している。
-
-        (d) 私はパッチをレビューし適切であると確信している一方で、あらゆる
-            状況においてその宣言した目的や機能が正しく実現することに関して、
-            いかなる保証もしない(特にどこかで明示しない限り)。
-
-Reviewd-by タグはそのパッチがカーネルに対して適切な修正であって、深刻な技術的
-問題を残していないという意見の宣言です。興味のあるレビューアは誰でも(レビュー
-作業を終えたら)パッチに対して Reviewed-by タグを提示できます。このタグは
-レビューアの寄与をクレジットする働き、レビューの進捗の度合いをメンテナに
-知らせる働きを持ちます。そのパッチの領域に詳しく、そして、しっかりとした
-レビューを実施したレビューアによって提供される時、Reviewed-by: タグがあなたの
-パッチをカーネルにマージする可能性を高めるでしょう。
-
-15) 標準的なパッチのフォーマット
-
-標準的なパッチのサブジェクトは以下のとおりです。
-
-    Subject: [PATCH 001/123] subsystem: summary phrase
-
-標準的なパッチの、電子メールのボディは以下の項目を含んでいます。
-
-  - パッチの作成者を明記する「 from 」行
-
-  - 空行
-
-  - 説明本体。これはこのパッチを説明するために無期限のチェンジログ
-    (変更履歴)にコピーされます。
-
-  - 上述した「 Signed-off-by: 」行。これも説明本体と同じくチェン
-    ジログ内にコピーされます。
-
-  - マーカー行は単純に「 --- 」です。
-
-  - 余計なコメントは、チェンジログには不適切です。
-
-  - 実際のパッチ(差分出力)
-
-サブジェクト行のフォーマットは、アルファベット順で電子メールをとても
-ソートしやすいものになっています。(ほとんどの電子メールクライアント
-はソートをサポートしています)パッチのサブジェクトの連番は0詰めであ
-るため、数字でのソートとアルファベットでのソートは同じ結果になります。
-
-電子メールのサブジェクト内のサブシステム表記は、パッチが適用される
-分野またはサブシステムを識別できるようにすべきです。
-
-電子メールのサブジェクトの「summary phrase」はそのパッチの概要を正確
-に表現しなければなりません。「summary phrase」をファイル名にしてはい
-けません。パッチシリーズ中でそれぞれのパッチは同じ「summary phrase」を
-使ってはいけません(「パッチシリーズ」とは順序付けられた関連のある複数の
-パッチ群です)。
-
-あなたの電子メールの「summary phrase」がそのパッチにとって世界で唯一の識別子に
-なるように心がけてください。「summary phrase」は git のチェンジログの中へ
-ずっと伝播していきます。「summary phrase」は、開発者が後でパッチを参照する
-ために議論の中で利用するかもしれません。
-人々はそのパッチに関連した議論を読むために「summary phrase」を使って google で
-検索したがるでしょう。それはまた2、3ヶ月あとで、人々が「gitk」や
-「git log --oneline」のようなツールを使用して何千ものパッチに目を通す時、
-唯一目にとまる情報となるでしょう。
-
-これらの理由のため、「summary phrase」はなぜパッチが必要であるか、パッチが何を
-変更するかの2つの情報をせいぜい70〜75文字で表現していなければなりません。
-「summary phrase」は簡潔であり説明的である表現を目指しつつ、うまく
-まとめられている概要となるべきです。
-
-「summary phrase」は「Subject: [PATCH tag] 」のように、
-大括弧で閉じられたタグを接頭辞として付加してもかまいません。このタグは
-「summary phrase」の一部とは考えませんが、パッチをどのように取り扱うべきかを
-表現します。
-一般的には「v1, v2, v3」のようなバージョン情報を表すタグ(過去のパッチに対する
-コメントを反映するために複数のバージョンのパッチが投稿されているのであれば)、
-「RFC」のようなコメントを要求するタグが挙げられます。パッチシリーズとして4つの
-パッチがあれば、個々のパッチに「1/4, 2/4, 3/4, 4/4」のように番号を付けても
-かまいません。これは開発者がパッチを適用する順番を確実に把握するためです。
-そして、開発者がパッチシリーズの中のすべてのパッチをもらさずレビュー或いは
-適用するのを保証するためです。
-
-サブジェクトの例を二つ
-
-    Subject: [patch 2/5] ext2: improve scalability of bitmap searching
-    Subject: [PATCHv2 001/207] x86: fix eflags tracking
-
-「 from 」行は電子メールのボディの一番最初の行でなければなりません。
-その形式は以下のとおりです。
-
-        From: Original Author 
-
-「 from 」行はチェンジログの中で、そのパッチの作成者としてクレジットされ
-ている人を特定するものです。「 from 」行がかけていると、電子メールのヘッ
-ダーの「 From: 」が、チェンジログの中でパッチの作成者を決定するために使わ
-れるでしょう。
-
-説明本体は無期限のソースのチェンジログにコミットされます。なので、説明
-本体はそのパッチに至った議論の詳細を忘れているある程度の技量を持っている人
-がその詳細を思い出すことができるものでなければなりません。パッチが対処する
-障害の症状(カーネルログメッセージや oops メッセージ等)を記載することは問題に
-対処可能なパッチを求めてコミットログを検索する人々にとって特に有用です。
-パッチがコンパイル問題を解決するのであれば、そのパッチを探している人が見つける
-ことができる情報だけで十分であり、コンパイル時の全てのエラーを含める必要は
-ありません。「summary phrase」と同様に、簡潔であり説明的であることが重要です。
-
-「 --- 」マーカー行はパッチ処理ツールに対して、チェンジログメッセージの終端
-部分を認識させるという重要な役目を果たします。
-
-「 --- 」マーカー行の後の追加コメントの良い使用方法の1つに diffstat コマンド
-があります。diffstat コマンドとは何のファイルが変更され、1ファイル当たり何行
-追加され何行消されたかを示すものです。diffstat コマンドは特に大きなパッチに
-おいて役立ちます。その時点でだけ又はメンテナにとってのみ関係のあるコメント
-は無期限に保存されるチェンジログにとって適切ではありません。そのため、この
-ようなコメントもマーカー行の後に書かれるべきです。
-このようなコメントの良い例として、v1 と v2 のバージョン間で何が変更されたかを
-表す「パッチの変更履歴」が挙げられます。
-
-「 --- 」マーカー行の後に diffstat コマンドの結果を含めるのであれば、ファイル
-名はカーネルソースツリーのトップディレクトリからの表記で列記されるため、横方向
-のスペースをとり過ぎないように、diffstat コマンドにオプション「 -p 1 -w 70 」
-を指定してください(インデントを含めてちょうど80列に合うでしょう)。
-
-適切なパッチのフォーマットの詳細についてはセクション3の参考文献を参照して
-ください。
-
-16) 「git pull」要求の送り方(Linus の電子メールから)
-
-間違ったブランチから引っ張るのを防ぐために、git リポジトリのアドレスと
-ブランチ名を同じ行に1行で記載してください。そうすることで、3回の連続クリック
-で全て選択できます。
-
-正しい形式は下記の通りです。
-
-	"Please pull from
-
-		git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
-
-	 to get these changes:"
-
-その結果、アドレスを自分自身でタイピングして間違えることはなくなります(実際に、
-何度か間違ったブランチから引っ張ってきてしまい、その時に diffstat の結果を
-検証して間違っていることに気づいたことがあります。どこから何を引っ張るべきかを
-「探したり」、正しいブランチ名かどうかを重ねてチェックしたりする必要が
-なくなればより快適になるでしょう)。
-
-diffstat の結果を生成するために「 git diff -M --stat --summary 」を使って
-ください。-M オプションはファイル名の変更を検知でき、--summary オプションは
-新規ファイル、削除されたファイル、名前が変更されたファイルの概要を生成します。
-
--M オプション(ファイル名の変更検知)を指定すると、diffstat の結果はかなり
-異なってきます。git は大規模な変更(追加と削除のペア)をファイル名の変更と
-判断するためです。
-
-------------------------------------
-セクション2 - ヒントとTIPSと小技
-------------------------------------
-
-このセクションは Linux カーネルに変更を適用することに関係のある一般的な
-「お約束」の多くを載せています。物事には例外というものがあります。しか
-し例外を適用するには、本当に妥当な理由が不可欠です。あなたは恐らくこの
-セクションを Linus のコンピュータ・サイエンス101と呼ぶでしょう。
-
-1) Documentation/process/coding-style.rstを参照
-
-言うまでもなく、あなたのコードがこのコーディングスタイルからあまりに
-も逸脱していると、レビューやコメントなしに受け取ってもらえないかもし
-れません。
-
-特筆すべき例外は、コードをあるファイルから別のファイルに移動
-するときです。この場合、コードを移動するパッチでは、移動されるコード
-に関して移動以外の変更を一切加えるべきではありません。これにより、
-コードの移動とあなたが行ったコードの修正を明確に区別できるようにな
-ります。これは実際に何が変更されたかをレビューする際の大きな助けに
-なるとともに、ツールにコードの履歴を追跡させることも容易になります。
-
-投稿するより前にパッチのスタイルチェッカー( scripts/checkpatch.pl )で
-あなたのパッチをチェックしてください。このスタイルチェッカーは最終結
-論としてではなく、指標としてみるべきです。もし、あなたのコードが違反
-はしているが修正するより良く見えるのであれば、おそらくそのままにする
-のがベストです。
-
-スタイルチェッカーによる3段階のレポート:
- - エラー: 間違っている可能性が高い
- - 警告：注意してレビューする必要がある
- - チェック：考慮する必要がある
-
-あなたはパッチに残っている全ての違反について、それがなぜ必要なのか正当な
-理由を示せるようにしておく必要があります。
-
-2) #ifdefは見苦しい
-
-ifdef が散乱したコードは、読むのもメンテナンスするのも面倒です。コードの中
-で ifdef を使わないでください。代わりに、ヘッダファイルの中に ifdef を入れて、
-条件付きで、コードの中で使われる関数を「 static inline 」関数かマクロで定義し
-てください。後はコンパイラが、何もしない箇所を最適化して取り去ってくれるで
-しょう。
-
-まずいコードの簡単な例
-
-	dev = alloc_etherdev (sizeof(struct funky_private));
-	if (!dev)
-		return -ENODEV;
-	#ifdef CONFIG_NET_FUNKINESS
-	init_funky_net(dev);
-	#endif
-
-クリーンアップしたコードの例
-
-(in header)
-	#ifndef CONFIG_NET_FUNKINESS
-	static inline void init_funky_net (struct net_device *d) {}
-	#endif
-
-(in the code itself)
-	dev = alloc_etherdev (sizeof(struct funky_private));
-	if (!dev)
-		return -ENODEV;
-	init_funky_net(dev);
-
-3) マクロより「 static inline 」を推奨
-
-「 static inline 」関数はマクロよりもずっと推奨されています。それらは、
-型安全性があり、長さにも制限が無く、フォーマットの制限もありません。
-gcc においては、マクロと同じくらい軽いです。
-
-マクロは「 static inline 」が明らかに不適切であると分かる場所(高速化パスの
-いくつかの特定のケース)や「 static inline 」関数を使うことができないような
-場所(マクロの引数の文字列連結のような)にだけ使われるべきです。
-
-「 static inline 」は「 static __inline__ 」や「 extern inline 」や
-「 extern __inline__ 」よりも適切です。
-
-4) 設計に凝りすぎるな
-
-それが有用になるかどうか分からないような不明瞭な将来を見越した設計
-をしないでください。「できる限り簡単に、そして、それ以上簡単になら
-ないような設計をしてください。」
-
-----------------------
-セクション3 参考文献
-----------------------
-
-Andrew Morton, "The perfect patch" (tpp).
-  
-
-Jeff Garzik, "Linux kernel patch submission format".
-  
-
-Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
-  
-  
-  
-  
-
-NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
-  
-
-Kernel Documentation/process/coding-style.rst:
-  
-
-Linus Torvalds's mail on the canonical patch format:
-  
-
-Andi Kleen, "On submitting kernel patches"
-  Some strategies to get difficult or controversial changes in.
-  http://halobates.de/on-submitting-patches.pdf
-
---
-
-
diff --git a/Documentation/ja_JP/stable_api_nonsense.txt b/Documentation/ja_JP/stable_api_nonsense.txt
deleted file mode 100644
index a3b40a4bdcfd..000000000000
--- a/Documentation/ja_JP/stable_api_nonsense.txt
+++ /dev/null
@@ -1,263 +0,0 @@
-NOTE:
-This is a version of Documentation/process/stable-api-nonsense.rst into Japanese.
-This document is maintained by IKEDA, Munehiro 
-and the JF Project team .
-If you find any difference between this document and the original file
-or a problem with the translation,
-please contact the maintainer of this file or JF project.
-
-Please also note that the purpose of this file is to be easier to read
-for non English (read: Japanese) speakers and is not intended as a
-fork. So if you have any comments or updates of this file, please try
-to update the original English file first.
-
-Last Updated: 2007/07/18
-==================================
-これは、
-linux-2.6.22-rc4/Documentation/process/stable-api-nonsense.rst の和訳
-です。
-翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
-翻訳日 ： 2007/06/11
-原著作者: Greg Kroah-Hartman < greg at kroah dot com >
-翻訳者 ： 池田 宗広 < m-ikeda at ds dot jp dot nec dot com >
-校正者 ： Masanori Kobayashi さん < zap03216 at nifty dot ne dot jp >
-          Seiji Kaneko さん < skaneko at a2 dot mbn dot or dot jp >
-==================================
-
-
-
-Linux カーネルのドライバインターフェース
-（あなたの質問すべてに対する回答とその他諸々）
-
-Greg Kroah-Hartman 
-
-
-この文書は、なぜ Linux ではバイナリカーネルインターフェースが定義
-されていないのか、またはなぜ不変のカーネルインターフェースを持たな
-いのか、ということを説明するために書かれた。ここでの話題は「カーネ
-ル内部の」インターフェースについてであり、ユーザー空間とのインター
-フェースではないことを理解してほしい。カーネルとユーザー空間とのイ
-ンターフェースとはアプリケーションプログラムが使用するものであり、
-つまりシステムコールのインターフェースがこれに当たる。これは今まで
-長きに渡り、かつ今後も「まさしく」不変である。私は確か 0.9 か何か
-より前のカーネルを使ってビルドした古いプログラムを持っているが、そ
-れは最新の 2.6 カーネルでもきちんと動作する。ユーザー空間とのイン
-ターフェースは、ユーザーとアプリケーションプログラマが不変性を信頼
-してよいものの一つである。
-
-
-要旨
-----
-
-あなたは不変のカーネルインターフェースが必要だと考えているかもしれ
-ないが、実際のところはそうではない。あなたは必要としているものが分
-かっていない。あなたが必要としているものは安定して動作するドライバ
-であり、それはドライバがメインのカーネルツリーに含まれる場合のみ得
-ることができる。ドライバがメインのカーネルツリーに含まれていると、
-他にも多くの良いことがある。それは、Linux をより強固で、安定な、成
-熟したオペレーティングシステムにすることができるということだ。これ
-こそ、そもそもあなたが Linux を使う理由のはずだ。
-
-
-はじめに
---------
-
-カーネル内部のインターフェース変更を心配しなければならないドライバ
-を書きたいなどというのは、変わり者だけだ。この世界のほとんどの人は、
-そのようなドライバがどんなインターフェースを使っているかなど知らな
-いし、そんなドライバのことなど全く気にもかけていない。
-
-
-まず初めに、クローズソースとか、ソースコードの隠蔽とか、バイナリの
-みが配布される使い物にならない代物[訳注(1)]とか、実体はバイナリ
-コードでそれを読み込むためのラッパー部分のみソースコードが公開され
-ているとか、その他用語は何であれ GPL の下にソースコードがリリース
-されていないカーネルドライバに関する法的な問題について、私は「いか
-なる議論も」行うつもりがない。法的な疑問があるのならば、プログラマ
-である私ではなく、弁護士に相談して欲しい。ここでは単に、技術的な問
-題について述べることにする。（法的な問題を軽視しているわけではない。
-それらは実際に存在するし、あなたはそれをいつも気にかけておく必要が
-ある）
-
-訳注(1)
-「使い物にならない代物」の原文は "blob"
-
-
-さてここでは、バイナリカーネルインターフェースについてと、ソースレ
-ベルでのインターフェースの不変性について、という二つの話題を取り上
-げる。この二つは互いに依存する関係にあるが、まずはバイナリインター
-フェースについて議論を行いやっつけてしまおう。
-
-
-バイナリカーネルインターフェース
---------------------------------
-
-もしソースレベルでのインターフェースが不変ならば、バイナリインター
-フェースも当然のように不変である、というのは正しいだろうか？正しく
-ない。Linux カーネルに関する以下の事実を考えてみてほしい。
-  - あなたが使用するＣコンパイラのバージョンによって、カーネル内部
-    の構造体の配置構造は異なったものになる。また、関数は異なった方
-    法でカーネルに含まれることになるかもしれない（例えばインライン
-    関数として扱われたり、扱われなかったりする）。個々の関数がどの
-    ようにコンパイルされるかはそれほど重要ではないが、構造体のパデ
-    ィングが異なるというのは非常に重要である。
-  - あなたがカーネルのビルドオプションをどのように設定するかによっ
-    て、カーネルには広い範囲で異なった事態が起こり得る。
-      - データ構造は異なるデータフィールドを持つかもしれない
-      - いくつかの関数は全く実装されていない状態になり得る
-        （例：SMP向けではないビルドでは、いくつかのロックは中身が
-          カラにコンパイルされる）
-      - カーネル内のメモリは、異なった方法で配置され得る。これはビ
-        ルドオプションに依存している。
-  - Linux は様々な異なるプロセッサアーキテクチャ上で動作する。
-    あるアーキテクチャ用のバイナリドライバを、他のアーキテクチャで
-    正常に動作させる方法はない。
-
-
-ある特定のカーネル設定を使用し、カーネルをビルドしたのと正確に同じ
-Ｃコンパイラを使用して単にカーネルモジュールをコンパイルするだけで
-も、あなたはこれらいくつもの問題に直面することになる。ある特定の
-Linux ディストリビューションの、ある特定のリリースバージョン用にモ
-ジュールを提供しようと思っただけでも、これらの問題を引き起こすには
-十分である。にも関わらず Linux ディストリビューションの数と、サ
-ポートするディストリビューションのリリース数を掛け算し、それら一つ
-一つについてビルドを行ったとしたら、今度はリリースごとのビルドオプ
-ションの違いという悪夢にすぐさま悩まされることになる。また、ディス
-トリビューションの各リリースバージョンには、異なるハードウェア（プ
-ロセッサタイプや種々のオプション）に対応するため、何種類かのカーネ
-ルが含まれているということも理解して欲しい。従って、ある一つのリ
-リースバージョンだけのためにモジュールを作成する場合でも、あなたは
-何バージョンものモジュールを用意しなければならない。
-
-
-信じて欲しい。このような方法でサポートを続けようとするなら、あなた
-はいずれ正気を失うだろう。遠い昔、私はそれがいかに困難なことか、身
-をもって学んだのだ・・・
-
-
-不変のカーネルソースレベルインターフェース
-------------------------------------------
-
-メインカーネルツリーに含まれていない Linux カーネルドライバを継続
-してサポートしていこうとしている人たちとの議論においては、これは極
-めて「引火性の高い」話題である。[訳注(2)]
-
-訳注(2)
-「引火性の高い」の原文は "volatile"。
-volatile には「揮発性の」「爆発しやすい」という意味の他、「変わり
-やすい」「移り気な」という意味がある。
-「（この話題は）爆発的に激しい論争を巻き起こしかねない」ということ
-を、「（カーネルのソースレベルインターフェースは）移ろい行くもので
-ある」ということを連想させる "volatile" という単語で表現している。
-
-
-Linux カーネルの開発は継続的に速いペースで行われ、決して歩みを緩め
-ることがない。その中でカーネル開発者達は、現状のインターフェースに
-あるバグを見つけ、より良い方法を考え出す。彼らはやがて、現状のイン
-ターフェースがより正しく動作するように修正を行う。その過程で関数の
-名前は変更されるかもしれず、構造体は大きく、または小さくなるかもし
-れず、関数の引数は検討しなおされるかもしれない。そのような場合、引
-き続き全てが正常に動作するよう、カーネル内でこれらのインターフェー
-スを使用している個所も全て同時に修正される。
-
-
-具体的な例として、カーネル内の USB インターフェースを挙げる。USB
-サブシステムはこれまでに少なくとも３回の書き直しが行われ、その結果
-インターフェースが変更された。これらの書き直しはいくつかの異なった
-問題を修正するために行われた。
-  - 同期的データストリームが非同期に変更された。これにより多数のド
-    ライバを単純化でき、全てのドライバのスループットが向上した。今
-    やほとんど全ての USB デバイスは、考えられる最高の速度で動作し
-    ている。
-  - USB ドライバが USB サブシステムのコアから行う、データパケット
-    用のメモリ確保方法が変更された。これに伴い、いくつもの文書化さ
-    れたデッドロック条件を回避するため、全ての USB ドライバはより
-    多くの情報を USB コアに提供しなければならないようになっている。
-
-
-このできごとは、数多く存在するクローズソースのオペレーティングシス
-テムとは全く対照的だ。それらは長期に渡り古い USB インターフェース
-をメンテナンスしなければならない。古いインターフェースが残ることで、
-新たな開発者が偶然古いインターフェースを使い、正しくない方法で開発
-を行ってしまう可能性が生じる。これによりシステムの安定性は危険にさ
-らされることになる。
-
-
-上に挙げたどちらの例においても、開発者達はその変更が重要かつ必要で
-あることに合意し、比較的楽にそれを実行した。もし Linux がソースレ
-ベルでインターフェースの不変性を保証しなければならないとしたら、新
-しいインターフェースを作ると同時に、古い、問題のある方を今後ともメ
-ンテナンスするという余計な仕事を USB の開発者にさせなければならな
-い。Linux の USB 開発者は、自分の時間を使って仕事をしている。よっ
-て、価値のない余計な仕事を報酬もなしに実行しろと言うことはできない。
-
-
-セキュリティ問題も、Linux にとっては非常に重要である。ひとたびセキ
-ュリティに関する問題が発見されれば、それは極めて短期間のうちに修正
-される。セキュリティ問題の発生を防ぐための修正は、カーネルの内部イ
-ンターフェースの変更を何度も引き起こしてきた。その際同時に、変更さ
-れたインターフェースを使用する全てのドライバもまた変更された。これ
-により問題が解消し、将来偶然に問題が再発してしまわないことが保証さ
-れる。もし内部インターフェースの変更が許されないとしたら、このよう
-にセキュリティ問題を修正し、将来再発しないことを保証することなど不
-可能なのだ。
-
-
-カーネルのインターフェースは時が経つにつれクリーンナップを受ける。
-誰も使っていないインターフェースは削除される。これにより、可能な限
-りカーネルが小さく保たれ、現役の全てのインターフェースが可能な限り
-テストされることを保証しているのだ。（使われていないインターフェー
-スの妥当性をテストすることは不可能と言っていいだろう）
-
-
-
-これから何をすべきか
------------------------
-
-では、もしメインのカーネルツリーに含まれない Linux カーネルドライ
-バがあったとして、あなたは、つまり開発者は何をするべきだろうか？全
-てのディストリビューションの全てのカーネルバージョン向けにバイナリ
-のドライバを供給することは悪夢であり、カーネルインターフェースの変
-更を追いかけ続けることもまた過酷な仕事だ。
-
-
-答えは簡単。そのドライバをメインのカーネルツリーに入れてしまえばよ
-い。（ここで言及しているのは、GPL に従って公開されるドライバのこと
-だということに注意してほしい。あなたのコードがそれに該当しないなら
-ば、さよなら。幸運を祈ります。ご自分で何とかしてください。Andrew
-と Linus からのコメント＜Andrew と Linus のコメントへのリンクをこ
-こに置く＞をどうぞ）ドライバがメインツリーに入れば、カーネルのイン
-ターフェースが変更された場合、変更を行った開発者によってドライバも
-修正されることになるだろう。あなたはほとんど労力を払うことなしに、
-常にビルド可能できちんと動作するドライバを手に入れることができる。
-
-
-ドライバをメインのカーネルツリーに入れると、非常に好ましい以下の効
-果がある。
-  - ドライバの品質が向上する一方で、（元の開発者にとっての）メンテ
-    ナンスコストは下がる。
-  - あなたのドライバに他の開発者が機能を追加してくれる。
-  - 誰かがあなたのドライバにあるバグを見つけ、修正してくれる。
-  - 誰かがあなたのドライバにある改善点を見つけてくれる。
-  - 外部インターフェースが変更されドライバの更新が必要になった場合、
-    誰かがあなたの代わりに更新してくれる。
-  - ドライバを入れてくれとディストロに頼まなくても、そのドライバは
-    全ての Linux ディストリビューションに自動的に含まれてリリース
-    される。
-
-
-Linux では、他のどのオペレーティングシステムよりも数多くのデバイス
-が「そのまま」使用できるようになった。また Linux は、どのオペレー
-ティングシステムよりも数多くのプロセッサアーキテクチャ上でそれらの
-デバイスを使用することができるようにもなった。このように、Linux の
-開発モデルは実証されており、今後も間違いなく正しい方向へと進んでい
-くだろう。:)
-
-
-
-------
-
-この文書の初期の草稿に対し、Randy Dunlap, Andrew Morton, David
-Brownell, Hanna Linder, Robert Love, Nishanth Aravamudan から査読
-と助言を頂きました。感謝申し上げます。
-
diff --git a/Documentation/ja_JP/stable_kernel_rules.txt b/Documentation/ja_JP/stable_kernel_rules.txt
deleted file mode 100644
index f9249aecba64..000000000000
--- a/Documentation/ja_JP/stable_kernel_rules.txt
+++ /dev/null
@@ -1,84 +0,0 @@
-NOTE:
-This is Japanese translated version of "Documentation/process/stable-kernel-rules.rst".
-This one is maintained by Tsugikazu Shibata 
-and JF Project team .
-If you find difference with original file or problem in translation,
-please contact maintainer of this file or JF project.
-
-Please also note that purpose of this file is easier to read for non
-English natives and do no intended to fork. So, if you have any
-comment or update of this file, please try to update Original(English)
-file at first.
-
-==================================
-これは、
-linux-2.6.29/Documentation/process/stable-kernel-rules.rst
-の和訳です。
-
-翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
-翻訳日： 2009/1/14
-翻訳者： Tsugikazu Shibata 
-校正者： 武井伸光さん、
-         かねこさん (Seiji Kaneko) 
-         小林 雅典さん (Masanori Kobayasi) 
-         野口さん (Kenji Noguchi) 
-         神宮信太郎さん 
-==================================
-
-ずっと知りたかった Linux 2.6 -stable リリースの全て
-
-"-stable" ツリーにどのような種類のパッチが受け入れられるか、どのような
-ものが受け入れられないか、についての規則-
-
- - 明らかに正しく、テストされているものでなければならない。
- - 文脈(変更行の前後)を含めて 100 行より大きくてはいけない。
- - ただ一個のことだけを修正しているべき。
- - 皆を悩ませている本物のバグを修正しなければならない。("これはバグで
-   あるかもしれないが..." のようなものではない)
- - ビルドエラー(CONFIG_BROKENになっているものを除く), oops, ハング、デー
-   タ破壊、現実のセキュリティ問題、その他 "ああ、これはダメだね"という
-   ようなものを修正しなければならない。短く言えば、重大な問題。
- - 新しい device ID とクオークも受け入れられる。
- - どのように競合状態が発生するかの説明も一緒に書かれていない限り、
-   "理論的には競合状態になる"ようなものは不可。
- - いかなる些細な修正も含めることはできない。(スペルの修正、空白のクリー
-   ンアップなど)
- - Documentation/process/submitting-patches.rst の規則に従ったものでなければならない。
- - パッチ自体か同等の修正が Linus のツリーに既に存在しなければならない。
-　 Linus のツリーでのコミットID を -stable へのパッチ投稿の際に引用す
-   ること。
-
--stable ツリーにパッチを送付する手続き-
-
- - 上記の規則に従っているかを確認した後に、stable@vger.kernel.org にパッチ
-   を送る。
- - 送信者はパッチがキューに受け付けられた際には ACK を、却下された場合
-   には NAK を受け取る。この反応は開発者たちのスケジュールによって、数
-   日かかる場合がある。
- - もし受け取られたら、パッチは他の開発者たちと関連するサブシステムの
-   メンテナーによるレビューのために -stable キューに追加される。
- - パッチに stable@vger.kernel.org のアドレスが付加されているときには、それ
-   が Linus のツリーに入る時に自動的に stable チームに email される。
- - セキュリティパッチはこのエイリアス (stable@vger.kernel.org) に送られるべ
-   きではなく、代わりに security@kernel.org のアドレスに送られる。
-
-レビューサイクル-
-
- - -stable メンテナがレビューサイクルを決めるとき、パッチはレビュー委
-   員会とパッチが影響する領域のメンテナ(提供者がその領域のメンテナで無
-   い限り)に送られ、linux-kernel メーリングリストにCCされる。
- - レビュー委員会は 48時間の間に ACK か NAK を出す。
- - もしパッチが委員会のメンバから却下されるか、メンテナ達やメンバが気付
-   かなかった問題が持ちあがり、linux-kernel メンバがパッチに異議を唱え
-   た場合には、パッチはキューから削除される。
- - レビューサイクルの最後に、ACK を受けたパッチは最新の -stable リリー
-   スに追加され、その後に新しい -stable リリースが行われる。
- - セキュリティパッチは、通常のレビューサイクルを通らず、セキュリティ
-   カーネルチームから直接 -stable ツリーに受け付けられる。
-   この手続きの詳細については kernel security チームに問い合わせること。
-
-レビュー委員会-
-
- - この委員会は、このタスクについて活動する多くのボランティアと、少数の
-   非ボランティアのカーネル開発者達で構成されている。
-
diff --git a/Documentation/ko_KR/HOWTO b/Documentation/ko_KR/HOWTO
deleted file mode 100644
index 3b0c15b277e0..000000000000
--- a/Documentation/ko_KR/HOWTO
+++ /dev/null
@@ -1,637 +0,0 @@
-NOTE:
-This is a version of Documentation/process/howto.rst translated into korean
-This document is maintained by Minchan Kim 
-If you find any difference between this document and the original file or
-a problem with the translation, please contact the maintainer of this file.
-
-Please also note that the purpose of this file is to be easier to
-read for non English (read: korean) speakers and is not intended as
-a fork. So if you have any comments or updates for this file please
-try to update the original English file first.
-
-----------------------------------
-
-이 문서는
-Documentation/process/howto.rst
-의 한글 번역입니다.
-
-역자： 김민찬 
-감수： 이제이미 
-
-----------------------------------
-
-
-어떻게 리눅스 커널 개발을 하는가
-================================
-
-이 문서는 커널 개발에 있어 가장 중요한 문서이다. 이 문서는
-리눅스 커널 개발자가 되는 법과 리눅스 커널 개발 커뮤니티와 일하는
-법을 담고있다. 커널 프로그래밍의 기술적인 측면과 관련된 내용들은
-포함하지 않으려고 하였지만 올바른 길로 여러분을 안내하는 데는 도움이
-될 것이다.
-
-이 문서에서 오래된 것을 발견하면 문서의 아래쪽에 나열된 메인테이너에게
-패치를 보내달라.
-
-
-소개
-----
-
-자, 여러분은 리눅스 커널 개발자가 되는 법을 배우고 싶은가? 아니면
-상사로부터"이 장치를 위한 리눅스 드라이버를 작성하시오"라는 말을
-들었는가? 이 문서의 목적은 여러분이 겪게 될 과정과 커뮤니티와 협력하는
-법을 조언하여 여러분의 목적을 달성하기 위해 필요한 것 모두를 알려주기
-위함이다.
-
-커널은 대부분은 C로 작성되어 있고 몇몇 아키텍쳐의 의존적인 부분은
-어셈블리로 작성되어 있다. 커널 개발을 위해 C를 잘 이해하고 있어야 한다.
-여러분이 특정 아키텍쳐의 low-level 개발을 할 것이 아니라면
-어셈블리(특정 아키텍쳐)는 잘 알아야 할 필요는 없다.
-다음의 참고서적들은 기본에 충실한 C 교육이나 수년간의 경험에 견주지는
-못하지만 적어도 참고 용도로는 좋을 것이다
-
- - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
- - "Practical C Programming" by Steve Oualline [O'Reilly]
- - "C:  A Reference Manual" by Harbison and Steele [Prentice Hall]
-
-커널은 GNU C와 GNU 툴체인을 사용하여 작성되었다. 이 툴들은 ISO C89 표준을
-따르는 반면 표준에 있지 않은 많은 확장기능도 가지고 있다. 커널은 표준 C
-라이브러리와는 관계없이 freestanding C 환경이어서 C 표준의 일부는
-지원되지 않는다. 임의의 long long 나누기나 floating point는 지원되지 않는다.
-때론 이런 이유로 커널이 그런 확장 기능을 가진 툴체인을 가지고 만들어졌다는
-것이 이해하기 어려울 수도 있고 게다가 불행하게도 그런 것을 정확하게 설명하는
-어떤 참고문서도 있지 않다. 정보를 얻기 위해서는 gcc info (`info gcc`)페이지를
-살펴보라.
-
-여러분은 기존의 개발 커뮤니티와 협력하는 법을 배우려고 하고 있다는 것을
-기억하라. 코딩, 스타일, 함수에 관한 훌륭한 표준을 가진 사람들이 모인
-다양한 그룹이 있다. 이 표준들은 오랜동안 크고 지역적으로 분산된 팀들에
-의해 가장 좋은 방법으로 일하기 위하여 찾은 것을 기초로 만들어져 왔다.
-그 표준들은 문서화가 잘 되어있기 때문에 가능한한 미리 많은 표준들에
-관하여 배우려고 시도하라. 다른 사람들은 여러분이나 여러분의 회사가
-일하는 방식에 적응하는 것을 원하지는 않는다.
-
-
-법적 문제
----------
-
-리눅스 커널 소스 코드는 GPL로 배포(release)되었다. 소스트리의 메인
-디렉토리에 있는 라이센스에 관하여 상세하게 쓰여 있는 COPYING이라는
-파일을 봐라. 여러분이 라이센스에 관한 더 깊은 문제를 가지고 있다면
-리눅스 커널 메일링 리스트에 묻지말고 변호사와 연락하라. 메일링
-리스트들에 있는 사람들은 변호사가 아니기 때문에 법적 문제에 관하여
-그들의 말에 의지해서는 안된다.
-
-GPL에 관한 잦은 질문들과 답변들은 다음을 참조하라.
-
-    https://www.gnu.org/licenses/gpl-faq.html
-
-
-문서
-----
-
-리눅스 커널 소스 트리는 커널 커뮤니티와 협력하는 법을 배우기위해 훌륭한
-다양한 문서들을 가지고 있다. 새로운 기능들이 커널에 들어가게 될 때,
-그 기능을 어떻게 사용하는지에 관한 설명을 위하여 새로운 문서 파일을
-추가하는 것을 권장한다. 커널이 유저스페이스로 노출하는 인터페이스를
-변경하게 되면 변경을 설명하는 메뉴얼 페이지들에 대한 패치나 정보를
-mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다.
-
-다음은 커널 소스 트리에 있는 읽어야 할 파일들의 리스트이다.
-
-  README
-    이 파일은 리눅스 커널에 관하여 간단한 배경 설명과 커널을 설정하고
-    빌드하기 위해 필요한 것을 설명한다. 커널에 입문하는 사람들은 여기서
-    시작해야 한다.
-
-  :ref:`Documentation/process/changes.rst `
-    이 파일은 커널을 성공적으로 빌드하고 실행시키기 위해 필요한 다양한
-    소프트웨어 패키지들의 최소 버젼을 나열한다.
-
-  :ref:`Documentation/process/coding-style.rst `
-    이 문서는 리눅스 커널 코딩 스타일과 그렇게 한 몇몇 이유를 설명한다.
-    모든 새로운 코드는 이 문서에 가이드라인들을 따라야 한다. 대부분의
-    메인테이너들은 이 규칙을 따르는 패치들만을 받아들일 것이고 많은 사람들이
-    그 패치가 올바른 스타일일 경우만 코드를 검토할 것이다.
-
-  :ref:`Documentation/process/submitting-patches.rst ` 와 :ref:`Documentation/process/submitting-drivers.rst `
-    이 파일들은 성공적으로 패치를 만들고 보내는 법을 다음의 내용들로
-    굉장히 상세히 설명하고 있다(그러나 다음으로 한정되진 않는다).
-
-       - Email 내용들
-       - Email 양식
-       - 그것을 누구에게 보낼지
-
-    이러한 규칙들을 따르는 것이 성공(역자주: 패치가 받아들여 지는 것)을
-    보장하진 않는다(왜냐하면 모든 패치들은 내용과 스타일에 관하여
-    면밀히 검토되기 때문이다). 그러나 규칙을 따르지 않는다면 거의
-    성공하지도 못할 것이다.
-
-    올바른 패치들을 만드는 법에 관한 훌륭한 다른 문서들이 있다.
-
-    "The Perfect Patch"
-        https://www.ozlabs.org/~akpm/stuff/tpp.txt
-
-    "Linux kernel patch submission format"
-        http://linux.yyz.us/patch-format.html
-
-   :ref:`Documentation/process/stable-api-nonsense.rst `
-    이 문서는 의도적으로 커널이 불변하는 API를 갖지 않도록 결정한
-    이유를 설명하며 다음과 같은 것들을 포함한다.
-
-       - 서브시스템 shim-layer(호환성을 위해?)
-       - 운영체제들간의 드라이버 이식성
-       - 커널 소스 트리내에 빠른 변화를 늦추는 것(또는 빠른 변화를 막는 것)
-
-    이 문서는 리눅스 개발 철학을 이해하는데 필수적이며 다른 운영체제에서
-    리눅스로 전향하는 사람들에게는 매우 중요하다.
-
-
-  :ref:`Documentation/admin-guide/security-bugs.rst `
-    여러분들이 리눅스 커널의 보안 문제를 발견했다고 생각한다면 이 문서에
-    나온 단계에 따라서 커널 개발자들에게 알리고 그 문제를 해결할 수 있도록
-    도와 달라.
-
-  :ref:`Documentation/process/management-style.rst `
-    이 문서는 리눅스 커널 메인테이너들이 그들의 방법론에 녹아 있는
-    정신을 어떻게 공유하고 운영하는지를 설명한다. 이것은 커널 개발에 입문하는
-    모든 사람들(또는 커널 개발에 작은 호기심이라도 있는 사람들)이
-    읽어야 할 중요한 문서이다. 왜냐하면 이 문서는 커널 메인테이너들의
-    독특한 행동에 관하여 흔히 있는 오해들과 혼란들을 해소하고 있기
-    때문이다.
-
-  :ref:`Documentation/process/stable_kernel_rules.rst `
-    이 문서는 안정적인 커널 배포가 이루어지는 규칙을 설명하고 있으며
-    여러분들이 이러한 배포들 중 하나에 변경을 하길 원한다면
-    무엇을 해야 하는지를 설명한다.
-
-  :ref:`Documentation/process/kernel-docs.rst `
-    커널 개발에 관계된 외부 문서의 리스트이다. 커널 내의 포함된 문서들
-    중에 여러분이 찾고 싶은 문서를 발견하지 못할 경우 이 리스트를
-    살펴보라.
-
-  :ref:`Documentation/process/applying-patches.rst `
-    패치가 무엇이며 그것을 커널의 다른 개발 브랜치들에 어떻게
-    적용하는지에 관하여 자세히 설명하고 있는 좋은 입문서이다.
-
-커널은 소스 코드 그 자체에서 또는 이것과 같은 ReStructuredText 마크업 (ReST) 을
-통해 자동적으로 만들어질 수 있는 많은 문서들을 가지고 있다. 이것은 커널 내의
-API에 대한 모든 설명, 그리고 락킹을 올바르게 처리하는 법에 관한 규칙을 포함하고
-있다.
-
-모든 그런 문서들은 커널 소스 디렉토리에서 다음 커맨드를 실행하는 것을 통해 PDF
-나 HTML 의 형태로 만들어질 수 있다::
-
-         make pdfdocs
-         make htmldocs
-
-ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된다.  해당
-문서들은 다음의 커맨드를 사용하면 LaTeX 이나 ePub 로도 만들어질 수 있다::
-
-         make latexdocs
-         make epubdocs
-
-현재, ReST 로의 변환이 진행중인, DocBook 으로 쓰인 문서들이 존재한다. 그런
-문서들은 Documentation/DocBook/ 디렉토리 안에 생성될 것이고 다음 커맨드를 통해
-Postscript 나 man page 로도 만들어질 수 있다::
-
-         make psdocs
-         make mandocs
-
-커널 개발자가 되는 것
----------------------
-
-여러분이 리눅스 커널 개발에 관하여 아무것도 모른다면 Linux KernelNewbies
-프로젝트를 봐야 한다.
-
-    https://kernelnewbies.org
-
-그곳은 거의 모든 종류의 기본적인 커널 개발 질문들(질문하기 전에 먼저
-아카이브를 찾아봐라. 과거에 이미 답변되었을 수도 있다)을 할 수 있는 도움이
-될만한 메일링 리스트가 있다. 또한 실시간으로 질문 할 수 있는 IRC 채널도
-가지고 있으며 리눅스 커널 개발을 배우는 데 유용한 문서들을 보유하고 있다.
-
-웹사이트는 코드구성, 서브시스템들, 그리고 현재 프로젝트들
-(트리 내, 외부에 존재하는)에 관한 기본적인 정보들을 가지고 있다. 또한
-그곳은 커널 컴파일이나 패치를 하는 법과 같은 기본적인 것들을  설명한다.
-
-여러분이 어디서 시작해야 할진 모르지만 커널 개발 커뮤니티에 참여할 수
-있는 일들을 찾길 원한다면 리눅스 커널 Janitor 프로젝트를 살펴봐라.
-
-	https://kernelnewbies.org/KernelJanitors
-
-그곳은 시작하기에 훌륭한 장소이다. 그곳은 리눅스 커널 소스 트리내에
-간단히 정리되고 수정될 수 있는 문제들에 관하여 설명한다. 여러분은 이
-프로젝트를 대표하는 개발자들과 일하면서 자신의 패치를 리눅스 커널 트리에
-반영하기 위한 기본적인 것들을 배우게 될것이며 여러분이 아직 아이디어를
-가지고 있지 않다면 다음에 무엇을 해야할지에 관한 방향을 배울 수 있을
-것이다.
-
-여러분들이 이미 커널 트리에 반영하길 원하는 코드 묶음을 가지고 있지만
-올바른 포맷으로 포장하는데 도움이 필요하다면 그러한 문제를 돕기 위해
-만들어진 kernel-mentors 프로젝트가 있다. 그곳은 메일링 리스트이며
-다음에서 참조할 수 있다.
-
-         https://selenic.com/mailman/listinfo/kernel-mentors
-
-리눅스 커널 코드에 실제 변경을 하기 전에 반드시 그 코드가 어떻게
-동작하는지 이해하고 있어야 한다. 코드를 분석하기 위하여 특정한 툴의
-도움을 빌려서라도 코드를 직접 읽는 것보다 좋은 것은 없다(대부분의
-자잘한 부분들은 잘 코멘트되어 있다). 그런 툴들 중에 특히 추천할만한
-것은 Linux Cross-Reference project이며 그것은 자기 참조 방식이며
-소스코드를 인덱스된 웹 페이지들의 형태로 보여준다. 최신의 멋진 커널
-코드 저장소는 다음을 통하여 참조할 수 있다.
-
-      http://lxr.free-electrons.com/
-
-
-개발 프로세스
--------------
-
-리눅스 커널 개발 프로세스는 현재 몇몇 다른 메인 커널 "브랜치들"과
-서브시스템에 특화된 커널 브랜치들로 구성된다. 몇몇 다른 메인
-브랜치들은 다음과 같다.
-
-  - main 4.x 커널 트리
-  - 4.x.y - 안정된 커널 트리
-  - 4.x -git 커널 패치들
-  - 서브시스템을 위한 커널 트리들과 패치들
-  - 4.x - 통합 테스트를 위한 next 커널 트리
-
-4.x 커널 트리
-~~~~~~~~~~~~~
-
-4.x 커널들은 Linus Torvalds가 관리하며 https://kernel.org 의
-pub/linux/kernel/v4.x/ 디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다.
-
-  - 새로운 커널이 배포되자마자 2주의 시간이 주어진다. 이 기간동은
-    메인테이너들은 큰 diff들을 Linus에게 제출할 수 있다. 대개 이 패치들은
-    몇 주 동안 -next 커널내에 이미 있었던 것들이다. 큰 변경들을 제출하는 데
-    선호되는 방법은  git(커널의 소스 관리 툴, 더 많은 정보들은
-    https://git-scm.com/ 에서 참조할 수 있다)를 사용하는 것이지만 순수한
-    패치파일의 형식으로 보내는 것도 무관하다.
-  - 2주 후에 -rc1 커널이 배포되며 지금부터는 전체 커널의 안정성에 영향을
-    미칠수 있는 새로운 기능들을 포함하지 않는 패치들만이 추가될 수 있다.
-    완전히 새로운 드라이버(혹은 파일시스템)는 -rc1 이후에만 받아들여진다는
-    것을 기억해라. 왜냐하면 변경이 자체내에서만 발생하고 추가된 코드가
-    드라이버 외부의 다른 부분에는 영향을 주지 않으므로 그런 변경은
-    회귀(역자주: 이전에는 존재하지 않았지만 새로운 기능추가나 변경으로 인해
-    생겨난 버그)를 일으킬 만한 위험을 가지고 있지 않기 때문이다. -rc1이
-    배포된 이후에 git를 사용하여 패치들을 Linus에게 보낼수 있지만 패치들은
-    공식적인 메일링 리스트로 보내서 검토를 받을 필요가 있다.
-  - 새로운 -rc는 Linus가 현재 git tree가 테스트 하기에 충분히 안정된 상태에
-    있다고 판단될 때마다 배포된다. 목표는 새로운 -rc 커널을 매주 배포하는
-    것이다.
-  - 이러한 프로세스는 커널이 "준비(ready)"되었다고 여겨질때까지 계속된다.
-    프로세스는 대체로 6주간 지속된다.
-
-커널 배포에 있어서 언급할만한 가치가 있는 리눅스 커널 메일링 리스트의
-Andrew Morton의 글이 있다.
-
-        *"커널이 언제 배포될지는 아무도 모른다. 왜냐하면 배포는 알려진
-         버그의 상황에 따라 배포되는 것이지 미리정해 놓은 시간에 따라
-         배포되는 것은 아니기 때문이다."*
-
-4.x.y - 안정 커널 트리
-~~~~~~~~~~~~~~~~~~~~~~
-
-3 자리 숫자로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 4.x
-커널에서 발견된 큰 회귀들이나 보안 문제들 중 비교적 작고 중요한 수정들을
-포함한다.
-
-이것은 가장 최근의 안정적인 커널을 원하는 사용자에게 추천되는 브랜치이며,
-개발/실험적 버젼을 테스트하는 것을 돕고자 하는 사용자들과는 별로 관련이 없다.
-
-어떤 4.x.y 커널도 사용할 수 없다면 그때는 가장 높은 숫자의 4.x
-커널이 현재의 안정 커널이다.
-
-4.x.y는 "stable" 팀에 의해 관리되며 거의 매번 격주로
-배포된다.
-
-커널 트리 문서들 내에 Documentation/process/stable-kernel-rules.rst 파일은 어떤
-종류의 변경들이 -stable 트리로 들어왔는지와 배포 프로세스가 어떻게
-진행되는지를 설명한다.
-
-4.x -git 패치들
-~~~~~~~~~~~~~~~
-
-git 저장소(그러므로 -git이라는 이름이 붙음)에는 날마다 관리되는 Linus의
-커널 트리의 snapshot 들이 있다. 이 패치들은 일반적으로 날마다 배포되며
-Linus의 트리의 현재 상태를 나타낸다. 이 패치들은 정상적인지 조금도
-살펴보지 않고 자동적으로 생성된 것이므로 -rc 커널들 보다도 더 실험적이다.
-
-서브시스템 커널 트리들과 패치들
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-다양한 커널 서브시스템의 메인테이너들 --- 그리고 많은 커널 서브시스템 개발자들
---- 은 그들의 현재 개발 상태를 소스 저장소로 노출한다. 이를 통해 다른 사람들도
-커널의 다른 영역에 어떤 변화가 이루어지고 있는지 알 수 있다. 급속히 개발이
-진행되는 영역이 있고 그렇지 않은 영역이 있으므로, 개발자는 다른 개발자가 제출한
-수정 사항과 자신의 수정사항의 충돌이나 동일한 일을 동시에 두사람이 따로
-진행하는 사태를 방지하기 위해 급속히 개발이 진행되고 있는 영역에 작업의
-베이스를 맞춰줄 것이 요구된다.
-
-대부분의 이러한 저장소는 git 트리지만, git이 아닌 SCM으로 관리되거나, quilt
-시리즈로 제공되는 패치들도 존재한다. 이러한 서브시스템 저장소들은 MAINTAINERS
-파일에 나열되어 있다. 대부분은 https://git.kernel.org 에서 볼 수 있다.
-
-제안된 패치는 서브시스템 트리에 커밋되기 전에 메일링 리스트를 통해
-리뷰된다(아래의 관련 섹션을 참고하기 바란다). 일부 커널 서브시스템의 경우, 이
-리뷰 프로세스는 patchwork라는 도구를 통해 추적된다. patchwork은 등록된 패치와
-패치에 대한 코멘트, 패치의 버전을 볼 수 있는 웹 인터페이스를 제공하고,
-메인테이너는 패치를 리뷰 중, 리뷰 통과, 또는 반려됨으로 표시할 수 있다.
-대부분의 이러한 patchwork 사이트는 https://patchwork.kernel.org/ 또는
-http://patchwork.ozlabs.org/ 에 나열되어 있다.
-
-4.x - 통합 테스트를 위한 next 커널 트리
----------------------------------------
-서브시스템 트리들의 변경사항들은 mainline 4.x 트리로 들어오기 전에 통합
-테스트를 거쳐야 한다. 이런 목적으로, 모든 서브시스템 트리의 변경사항을 거의
-매일 받아가는 특수한 테스트 저장소가 존재한다:
-
-       https://git.kernel.org/?p=linux/kernel/git/sfr/linux-next.git
-
-이런 식으로, -next 커널을 통해 다음 머지 기간에 메인라인 커널에 어떤 변경이
-가해질 것인지 간략히 알 수 있다. 모험심 강한 테스터라면 -next 커널에서 테스트를
-수행하는 것도 좋을 것이다.
-
-
-버그 보고
----------
-
-https://bugzilla.kernel.org는 리눅스 커널 개발자들이 커널의 버그를 추적하는
-곳이다. 사용자들은 발견한 모든 버그들을 보고하기 위하여 이 툴을 사용할 것을
-권장한다.  kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라.
-
-    https://bugzilla.kernel.org/page.cgi?id=faq.html
-
-메인 커널 소스 디렉토리에 있는 admin-guide/reporting-bugs.rst 파일은 커널 버그라고 생각되는
-것을 보고하는 방법에 관한 좋은 템플릿이며 문제를 추적하기 위해서 커널
-개발자들이 필요로 하는 정보가 무엇들인지를 상세히 설명하고 있다.
-
-
-버그 리포트들의 관리
---------------------
-
-여러분의 해킹 기술을 연습하는 가장 좋은 방법 중의 하는 다른 사람들이
-보고한 버그들을 수정하는 것이다. 여러분은 커널을 더욱 안정화시키는데
-도움을 줄 뿐만이 아니라 실제있는 문제들을 수정하는 법을 배우게 되고
-그와 함께 여러분들의 기술은 향상될 것이며 다른 개발자들이 여러분의
-존재에 대해 알게 될 것이다. 버그를 수정하는 것은 개발자들  사이에서
-점수를 얻을 수 있는 가장 좋은 방법중의 하나이다. 왜냐하면 많은 사람들은
-다른 사람들의 버그들을 수정하기 위하여 시간을 낭비하지 않기 때문이다.
-
-이미 보고된 버그 리포트들을 가지고 작업하기 위해서 https://bugzilla.kernel.org
-를 참조하라. 여러분이 앞으로 생겨날 버그 리포트들의 조언자가 되길 원한다면
-bugme-new 메일링 리스트나(새로운 버그 리포트들만이 이곳에서 메일로 전해진다)
-bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메일로 전해진다)
-에 등록하면 된다.
-
-      https://lists.linux-foundation.org/mailman/listinfo/bugme-new
-
-      https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
-
-
-
-메일링 리스트들
----------------
-
-위의 몇몇 문서들이 설명하였지만 핵심 커널 개발자들의 대다수는
-리눅스 커널 메일링 리스트에 참여하고 있다. 리스트에 등록하고 해지하는
-방법에 관한 자세한 사항은 다음에서 참조할 수 있다.
-
-    http://vger.kernel.org/vger-lists.html#linux-kernel
-
-웹상의 많은 다른 곳에도 메일링 리스트의 아카이브들이 있다.
-이러한 아카이브들을 찾으려면 검색 엔진을 사용하라. 예를 들어:
-
-      http://dir.gmane.org/gmane.linux.kernel
-
-여러분이 새로운 문제에 관해 리스트에 올리기 전에 말하고 싶은 주제에 관한
-것을 아카이브에서 먼저 찾아보기를 강력히 권장한다. 이미 상세하게 토론된 많은
-것들이 메일링 리스트의 아카이브에 기록되어 있다.
-
-각각의 커널 서브시스템들의 대부분은 자신들의 개발에 관한 노력들로 이루어진
-분리된 메일링 리스트를 따로 가지고 있다. 다른 그룹들이 무슨 리스트를 가지고
-있는지는 MAINTAINERS 파일을 참조하라.
-
-많은 리스트들은 kernel.org에서 호스트되고 있다. 그 정보들은 다음에서 참조될 수 있다.
-
-         http://vger.kernel.org/vger-lists.html
-
-리스트들을 사용할 때는 올바른 예절을 따를 것을 유념해라.
-대단하진 않지만 다음 URL은 리스트(혹은 모든 리스트)와 대화하는 몇몇 간단한
-가이드라인을 가지고 있다.
-
-         http://www.albion.com/netiquette/
-
-여러 사람들이 여러분의 메일에 응답한다면 CC: 즉 수신 리스트는 꽤 커지게
-될 것이다. 아무 이유없이 CC에서 어떤 사람도 제거하거나 리스트 주소로만
-회신하지 마라. 메일을 보낸 사람으로서 하나를 받고 리스트로부터 또
-하나를 받아 두번 받는 것에 익숙하여 있으니 mail-header를 조작하려고 하지
-말아라. 사람들은 그런 것을 좋아하지 않을 것이다.
-
-여러분의 회신의 문맥을 원래대로 유지해야 한다. 여러분들의 회신의 윗부분에
-"John 커널해커는 작성했다...."를 유지하며 여러분들의 의견을 그 메일의 윗부분에
-작성하지 말고 각 인용한 단락들 사이에 넣어라.
-
-여러분들이 패치들을 메일에 넣는다면 그것들은 Documentation/process/submitting-patches.rst에
-나와있는데로 명백히(plain) 읽을 수 있는 텍스트여야 한다. 커널 개발자들은
-첨부파일이나 압축된 패치들을 원하지 않는다. 그들은 여러분들의 패치의
-각 라인 단위로 코멘트를 하길 원하며 압축하거나 첨부하지 않고 보내는 것이
-그렇게 할 수 있는 유일한 방법이다. 여러분들이 사용하는 메일 프로그램이
-스페이스나 탭 문자들을 조작하지 않는지 확인하라. 가장 좋은 첫 테스트는
-메일을 자신에게 보내보고 스스로 그 패치를 적용해보라. 그것이 동작하지
-않는다면 여러분의 메일 프로그램을 고치던가 제대로 동작하는 프로그램으로
-바꾸어라.
-
-무엇보다도 메일링 리스트의 다른 구독자들에게 보여주려 한다는 것을 기억하라.
-
-
-커뮤니티와 협력하는 법
-----------------------
-
-커널 커뮤니티의 목적은 가능한한 가장 좋은 커널을 제공하는 것이다. 여러분이
-받아들여질 패치를 제출하게 되면 그 패치의 기술적인 이점으로 검토될 것이다.
-그럼 여러분들은 무엇을 기대하고 있어야 하는가?
-
- - 비판
- - 의견
- - 변경을 위한 요구
- - 당위성을 위한 요구
- - 침묵
-
-기억하라. 이것들은 여러분의 패치가 커널로 들어가기 위한 과정이다. 여러분의
-패치들은 비판과 다른 의견을 받을 수 있고 그것들을 기술적인 레벨로 평가하고
-재작업하거나 또는 왜 수정하면 안되는지에 관하여 명료하고 간결한 이유를
-말할 수 있어야 한다. 여러분이 제출한 것에 어떤 응답도 있지 않다면 몇 일을
-기다려보고 다시 시도해라. 때론 너무 많은 메일들 속에 묻혀버리기도 한다.
-
-여러분은 무엇을 해서는 안되는가?
-
- - 여러분의 패치가 아무 질문 없이 받아들여지기를 기대하는 것
- - 방어적이 되는 것
- - 의견을 무시하는 것
- - 요청된 변경을 하지 않고 패치를 다시 제출하는 것
-
-가능한한 가장 좋은 기술적인 해답을 찾고 있는 커뮤니티에서는 항상
-어떤 패치가 얼마나 좋은지에 관하여 다른 의견들이 있을 수 있다. 여러분은
-협조적이어야 하고 기꺼이 여러분의 생각을 커널 내에 맞추어야 한다. 아니면
-적어도 여러분의 것이 가치있다는 것을 증명하여야 한다. 잘못된 것도 여러분이
-올바른 방향의 해결책으로 이끌어갈 의지가 있다면 받아들여질 것이라는 점을
-기억하라.
-
-여러분의 첫 패치에 여러분이 수정해야하는 십여개 정도의 회신이 오는
-경우도 흔하다. 이것은 여러분의 패치가 받아들여지지 않을 것이라는 것을
-의미하는 것이 아니고 개인적으로 여러분에게 감정이 있어서 그러는 것도
-아니다. 간단히 여러분의 패치에 제기된 문제들을 수정하고 그것을 다시
-보내라.
-
-
-커널 커뮤니티와 기업 조직간의 차이점
-------------------------------------
-커널 커뮤니티는 가장 전통적인 회사의 개발 환경과는 다르다. 여기에 여러분들의
-문제를 피하기 위한 목록이 있다.
-
-  여러분들이 제안한 변경들에 관하여 말할 때 좋은 것들 :
-
-    - "이것은 여러 문제들을 해결합니다."
-    - "이것은 2000 라인의 코드를 줄입니다."
-    - "이것은 내가 말하려는 것에 관해 설명하는 패치입니다."
-    - "나는 5개의 다른 아키텍쳐에서 그것을 테스트 했으므로..."
-    - "여기에 일련의 작은 패치들이 있으므로..."
-    - "이것은 일반적인 머신에서 성능을 향상함으로..."
-
-  여러분들이 말할 때 피해야 할 좋지 않은 것들 :
-
-    - "우리는 그것을 AIX/ptx/Solaris에서 이러한 방법으로 했다. 그러므로 그것은 좋은 것임에 틀림없다..."
-    - "나는 20년동안 이것을 해왔다. 그러므로..."
-    - "이것은 돈을 벌기위해 나의 회사가 필요로 하는 것이다."
-    - "이것은 우리의 엔터프라이즈 상품 라인을 위한 것이다."
-    - "여기에 나의 생각을 말하고 있는 1000 페이지 설계 문서가 있다."
-    - "나는 6달동안 이것을 했으니..."
-    - "여기에 5000 라인 짜리 패치가 있으니..."
-    - "나는 현재 뒤죽박죽인 것을 재작성했다. 그리고 여기에..."
-    - "나는 마감시한을 가지고 있으므로 이 패치는 지금 적용될 필요가 있다."
-
-커널 커뮤니티가 전통적인 소프트웨어 엔지니어링 개발 환경들과
-또 다른 점은 얼굴을 보지 않고 일한다는 점이다. 이메일과 irc를 대화의
-주요수단으로 사용하는 것의 한가지 장점은 성별이나 인종의 차별이
-없다는 것이다. 리눅스 커널의 작업 환경에서는 단지 이메일 주소만
-알수 있기 때문에 여성과 소수 민족들도 모두 받아들여진다. 국제적으로
-일하게 되는 측면은 사람의 이름에 근거하여 성별을 추측할 수 없게
-하기때문에 차별을 없애는 데 도움을 준다. Andrea라는 이름을 가진 남자와
-Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅스 커널에서
-작업하며 생각을 표현해왔던 대부분의 여성들은 긍정적인 경험을 가지고
-있다.
-
-언어 장벽은 영어에 익숙하지 않은 몇몇 사람들에게 문제가 될 수도 있다.
-언어의 훌륭한 구사는 메일링 리스트에서 올바르게 자신의 생각을
-표현하기 위하여 필요하다. 그래서 여러분은 이메일을 보내기 전에
-영어를 올바르게 사용하고 있는지를 체크하는 것이 바람직하다.
-
-
-여러분의 변경을 나누어라
-------------------------
-
-리눅스 커널 커뮤니티는 한꺼번에 굉장히 큰 코드의 묶음(chunk)을 쉽게
-받아들이지 않는다. 변경은 적절하게 소개되고, 검토되고, 각각의
-부분으로 작게 나누어져야 한다. 이것은 회사에서 하는 것과는 정확히
-반대되는 것이다. 여러분들의 제안은 개발 초기에 일찍이 소개되야 한다.
-그래서 여러분들은 자신이 하고 있는 것에 관하여 피드백을 받을 수 있게
-된다. 커뮤니티가 여러분들이 커뮤니티와 함께 일하고 있다는 것을
-느끼도록 만들고 커뮤니티가 여러분의 기능을 위한 쓰레기 장으로써
-사용되지 않고 있다는 것을 느끼게 하자. 그러나 메일링 리스트에 한번에
-50개의 이메일을 보내지는 말아라. 여러분들의 일련의 패치들은 항상
-더 작아야 한다.
-
-패치를 나누는 이유는 다음과 같다.
-
-1) 작은 패치들은 여러분의 패치들이 적용될 수 있는 확률을 높여준다.
-   왜냐하면 다른 사람들은 정확성을 검증하기 위하여 많은 시간과 노력을
-   들이기를 원하지 않는다. 5줄의 패치는 메인테이너가 거의 몇 초간 힐끗
-   보면 적용될 수 있다. 그러나 500 줄의 패치는 정확성을 검토하기 위하여
-   몇시간이 걸릴 수도 있다(걸리는 시간은 패치의 크기 혹은 다른 것에
-   비례하여 기하급수적으로 늘어난다).
-
-   패치를 작게 만드는 것은 무엇인가 잘못되었을 때 디버그하는 것을
-   쉽게 만든다. 즉, 그렇게 만드는 것은 매우 큰 패치를 적용한 후에
-   조사하는 것 보다 작은 패치를 적용한 후에 (그리고 몇몇의 것이
-   깨졌을 때) 하나씩 패치들을 제거해가며 디버그 하기 쉽도록 만들어 준다.
-
-2) 작은 패치들을 보내는 것뿐만 아니라 패치들을 제출하기전에 재작성하고
-   간단하게(혹은 간단한게 재배치하여) 하는 것도 중요하다.
-
-여기에 커널 개발자 Al Viro의 이야기가 있다.
-
-    *"학생의 수학 숙제를 채점하는 선생님을 생각해보라. 선생님은 학생들이
-    답을 얻을때까지 겪은 시행착오를 보길 원하지 않는다. 선생님들은
-    간결하고 가장 뛰어난 답을 보길 원한다. 훌륭한 학생은 이것을 알고
-    마지막으로 답을 얻기 전 중간 과정들을 제출하진 않는다.*
-
-    *커널 개발도 마찬가지이다. 메인테이너들과 검토하는 사람들은 문제를
-    풀어나가는 과정속에 숨겨진 과정을 보길 원하진 않는다. 그들은
-    간결하고 멋진 답을 보길 원한다."*
-
-커뮤니티와 협력하며 뛰어난 답을 찾는 것과 여러분들의 끝마치지 못한 작업들
-사이에 균형을 유지해야 하는 것은 어려울지도 모른다. 그러므로 프로세스의
-초반에 여러분의 작업을 향상시키기위한 피드백을 얻는 것 뿐만 아니라
-여러분들의 변경들을 작은 묶음으로 유지해서 심지어는 여러분의 작업의
-모든 부분이 지금은 포함될 준비가 되어있지 않지만 작은 부분은 벌써
-받아들여질 수 있도록 유지하는 것이 바람직하다.
-
-또한 완성되지 않았고 "나중에 수정될 것이다." 와 같은 것들을 포함하는
-패치들은 받아들여지지 않을 것이라는 점을 유념하라.
-
-
-변경을 정당화해라
------------------
-
-여러분들의 나누어진 패치들을 리눅스 커뮤니티가 왜 반영해야 하는지를
-알도록 하는 것은 매우 중요하다. 새로운 기능들이 필요하고 유용하다는
-것은 반드시 그에 합당한 이유가 있어야 한다.
-
-
-변경을 문서화해라
------------------
-
-여러분이 패치를 보내려 할때는 여러분이 무엇을 말하려고 하는지를 충분히
-생각하여 이메일을 작성해야 한다. 이 정보는 패치를 위한 ChangeLog가 될
-것이다. 그리고 항상 그 내용을 보길 원하는 모든 사람들을 위해 보존될
-것이다. 패치는 완벽하게 다음과 같은 내용들을 포함하여 설명해야 한다.
-
-  - 변경이 왜 필요한지
-  - 패치에 관한 전체 설계 접근(approach)
-  - 구현 상세들
-  - 테스트 결과들
-
-이것이 무엇인지 더 자세한 것을 알고 싶다면 다음 문서의 ChageLog 항을 봐라.
-
-   "The Perfect Patch"
-
-    http://www.ozlabs.org/~akpm/stuff/tpp.txt
-
-
-이 모든 것을 하는 것은 매우 어려운 일이다. 완벽히 소화하는 데는 적어도 몇년이
-걸릴 수도 있다. 많은 인내와 결심이 필요한 계속되는 개선의 과정이다. 그러나
-가능한한 포기하지 말라. 많은 사람들은 이전부터 해왔던 것이고 그 사람들도
-정확하게 여러분들이 지금 서 있는 그 곳부터  시작했었다.
-
-
-
-
-----------
-
-"개발 프로세스"(https://lwn.net/Articles/94386/) 섹션을
-작성하는데 있어 참고할 문서를 사용하도록 허락해준 Paolo Ciarrocchi에게
-감사한다. 여러분들이 말해야 할 것과 말해서는 안되는 것의 목록 중 일부를 제공해준
-Randy Dunlap과 Gerrit Huizenga에게 감사한다. 또한 검토와 의견 그리고
-공헌을 아끼지 않은 Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers,
-Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi Kleen,
-Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop,
-David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard에게도 감사를 전한다.
-그들의 도움이 없었다면 이 문서는 존재하지 않았을 것이다.
-
-
-
-메인테이너: Greg Kroah-Hartman 
diff --git a/Documentation/ko_KR/memory-barriers.txt b/Documentation/ko_KR/memory-barriers.txt
deleted file mode 100644
index a3228a676cc1..000000000000
--- a/Documentation/ko_KR/memory-barriers.txt
+++ /dev/null
@@ -1,3171 +0,0 @@
-NOTE:
-This is a version of Documentation/memory-barriers.txt translated into Korean.
-This document is maintained by SeongJae Park .
-If you find any difference between this document and the original file or
-a problem with the translation, please contact the maintainer of this file.
-
-Please also note that the purpose of this file is to be easier to
-read for non English (read: Korean) speakers and is not intended as
-a fork.  So if you have any comments or updates for this file please
-update the original English file first.  The English version is
-definitive, and readers should look there if they have any doubt.
-
-===================================
-이 문서는
-Documentation/memory-barriers.txt
-의 한글 번역입니다.
-
-역자： 박성재 
-===================================
-
-
-			 =========================
-			 리눅스 커널 메모리 배리어
-			 =========================
-
-저자: David Howells 
-      Paul E. McKenney 
-      Will Deacon 
-      Peter Zijlstra 
-
-========
-면책조항
-========
-
-이 문서는 명세서가 아닙니다; 이 문서는 완벽하지 않은데, 간결성을 위해 의도된
-부분도 있고, 의도하진 않았지만 사람에 의해 쓰였다보니 불완전한 부분도 있습니다.
-이 문서는 리눅스에서 제공하는 다양한 메모리 배리어들을 사용하기 위한
-안내서입니다만, 뭔가 이상하다 싶으면 (그런게 많을 겁니다) 질문을 부탁드립니다.
-
-다시 말하지만, 이 문서는 리눅스가 하드웨어에 기대하는 사항에 대한 명세서가
-아닙니다.
-
-이 문서의 목적은 두가지입니다:
-
- (1) 어떤 특정 배리어에 대해 기대할 수 있는 최소한의 기능을 명세하기 위해서,
-     그리고
-
- (2) 사용 가능한 배리어들에 대해 어떻게 사용해야 하는지에 대한 안내를 제공하기
-     위해서.
-
-어떤 아키텍쳐는 특정한 배리어들에 대해서는 여기서 이야기하는 최소한의
-요구사항들보다 많은 기능을 제공할 수도 있습니다만, 여기서 이야기하는
-요구사항들을 충족하지 않는 아키텍쳐가 있다면 그 아키텍쳐가 잘못된 것이란 점을
-알아두시기 바랍니다.
-
-또한, 특정 아키텍쳐에서 일부 배리어는 해당 아키텍쳐의 특수한 동작 방식으로 인해
-해당 배리어의 명시적 사용이 불필요해서 no-op 이 될수도 있음을 알아두시기
-바랍니다.
-
-역자: 본 번역 역시 완벽하지 않은데, 이 역시 부분적으로는 의도된 것이기도
-합니다.  여타 기술 문서들이 그렇듯 완벽한 이해를 위해서는 번역문과 원문을 함께
-읽으시되 번역문을 하나의 가이드로 활용하시길 추천드리며, 발견되는 오역 등에
-대해서는 언제든 의견을 부탁드립니다.  과한 번역으로 인한 오해를 최소화하기 위해
-애매한 부분이 있을 경우에는 어색함이 있더라도 원래의 용어를 차용합니다.
-
-
-=====
-목차:
-=====
-
- (*) 추상 메모리 액세스 모델.
-
-     - 디바이스 오퍼레이션.
-     - 보장사항.
-
- (*) 메모리 배리어란 무엇인가?
-
-     - 메모리 배리어의 종류.
-     - 메모리 배리어에 대해 가정해선 안될 것.
-     - 데이터 의존성 배리어.
-     - 컨트롤 의존성.
-     - SMP 배리어 짝맞추기.
-     - 메모리 배리어 시퀀스의 예.
-     - 읽기 메모리 배리어 vs 로드 예측.
-     - 이행성
-
- (*) 명시적 커널 배리어.
-
-     - 컴파일러 배리어.
-     - CPU 메모리 배리어.
-     - MMIO 쓰기 배리어.
-
- (*) 암묵적 커널 메모리 배리어.
-
-     - 락 Acquisition 함수.
-     - 인터럽트 비활성화 함수.
-     - 슬립과 웨이크업 함수.
-     - 그외의 함수들.
-
- (*) CPU 간 ACQUIRING 배리어의 효과.
-
-     - Acquire vs 메모리 액세스.
-     - Acquire vs I/O 액세스.
-
- (*) 메모리 배리어가 필요한 곳
-
-     - 프로세서간 상호 작용.
-     - 어토믹 오퍼레이션.
-     - 디바이스 액세스.
-     - 인터럽트.
-
- (*) 커널 I/O 배리어의 효과.
-
- (*) 가정되는 가장 완화된 실행 순서 모델.
-
- (*) CPU 캐시의 영향.
-
-     - 캐시 일관성.
-     - 캐시 일관성 vs DMA.
-     - 캐시 일관성 vs MMIO.
-
- (*) CPU 들이 저지르는 일들.
-
-     - 그리고, Alpha 가 있다.
-     - 가상 머신 게스트.
-
- (*) 사용 예.
-
-     - 순환식 버퍼.
-
- (*) 참고 문헌.
-
-
-=======================
-추상 메모리 액세스 모델
-=======================
-
-다음과 같이 추상화된 시스템 모델을 생각해 봅시다:
-
-		            :                :
-		            :                :
-		            :                :
-		+-------+   :   +--------+   :   +-------+
-		|       |   :   |        |   :   |       |
-		|       |   :   |        |   :   |       |
-		| CPU 1 |<----->| Memory |<----->| CPU 2 |
-		|       |   :   |        |   :   |       |
-		|       |   :   |        |   :   |       |
-		+-------+   :   +--------+   :   +-------+
-		    ^       :       ^        :       ^
-		    |       :       |        :       |
-		    |       :       |        :       |
-		    |       :       v        :       |
-		    |       :   +--------+   :       |
-		    |       :   |        |   :       |
-		    |       :   |        |   :       |
-		    +---------->| Device |<----------+
-		            :   |        |   :
-		            :   |        |   :
-		            :   +--------+   :
-		            :                :
-
-프로그램은 여러 메모리 액세스 오퍼레이션을 발생시키고, 각각의 CPU 는 그런
-프로그램들을 실행합니다.  추상화된 CPU 모델에서 메모리 오퍼레이션들의 순서는
-매우 완화되어 있고, CPU 는 프로그램이 인과관계를 어기지 않는 상태로 관리된다고
-보일 수만 있다면 메모리 오퍼레이션을 자신이 원하는 어떤 순서대로든 재배치해
-동작시킬 수 있습니다.  비슷하게, 컴파일러 또한 프로그램의 정상적 동작을 해치지
-않는 한도 내에서는 어떤 순서로든 자신이 원하는 대로 인스트럭션을 재배치 할 수
-있습니다.
-
-따라서 위의 다이어그램에서 한 CPU가 동작시키는 메모리 오퍼레이션이 만들어내는
-변화는 해당 오퍼레이션이 CPU 와 시스템의 다른 부분들 사이의 인터페이스(점선)를
-지나가면서 시스템의 나머지 부분들에 인지됩니다.
-
-
-예를 들어, 다음의 일련의 이벤트들을 생각해 봅시다:
-
-	CPU 1		CPU 2
-	===============	===============
-	{ A == 1; B == 2 }
-	A = 3;		x = B;
-	B = 4;		y = A;
-
-다이어그램의 가운데에 위치한 메모리 시스템에 보여지게 되는 액세스들은 다음의 총
-24개의 조합으로 재구성될 수 있습니다:
-
-	STORE A=3,	STORE B=4,	y=LOAD A->3,	x=LOAD B->4
-	STORE A=3,	STORE B=4,	x=LOAD B->4,	y=LOAD A->3
-	STORE A=3,	y=LOAD A->3,	STORE B=4,	x=LOAD B->4
-	STORE A=3,	y=LOAD A->3,	x=LOAD B->2,	STORE B=4
-	STORE A=3,	x=LOAD B->2,	STORE B=4,	y=LOAD A->3
-	STORE A=3,	x=LOAD B->2,	y=LOAD A->3,	STORE B=4
-	STORE B=4,	STORE A=3,	y=LOAD A->3,	x=LOAD B->4
-	STORE B=4, ...
-	...
-
-따라서 다음의 네가지 조합의 값들이 나올 수 있습니다:
-
-	x == 2, y == 1
-	x == 2, y == 3
-	x == 4, y == 1
-	x == 4, y == 3
-
-
-한발 더 나아가서, 한 CPU 가 메모리 시스템에 반영한 스토어 오퍼레이션들의 결과는
-다른 CPU 에서의 로드 오퍼레이션을 통해 인지되는데, 이 때 스토어가 반영된 순서와
-다른 순서로 인지될 수도 있습니다.
-
-
-예로, 아래의 일련의 이벤트들을 생각해 봅시다:
-
-	CPU 1		CPU 2
-	===============	===============
-	{ A == 1, B == 2, C == 3, P == &A, Q == &C }
-	B = 4;		Q = P;
-	P = &B		D = *Q;
-
-D 로 읽혀지는 값은 CPU 2 에서 P 로부터 읽혀진 주소값에 의존적이기 때문에 여기엔
-분명한 데이터 의존성이 있습니다.  하지만 이 이벤트들의 실행 결과로는 아래의
-결과들이 모두 나타날 수 있습니다:
-
-	(Q == &A) and (D == 1)
-	(Q == &B) and (D == 2)
-	(Q == &B) and (D == 4)
-
-CPU 2 는 *Q 의 로드를 요청하기 전에 P 를 Q 에 넣기 때문에 D 에 C 를 집어넣는
-일은 없음을 알아두세요.
-
-
-디바이스 오퍼레이션
--------------------
-
-일부 디바이스는 자신의 컨트롤 인터페이스를 메모리의 특정 영역으로 매핑해서
-제공하는데(Memory mapped I/O), 해당 컨트롤 레지스터에 접근하는 순서는 매우
-중요합니다.  예를 들어, 어드레스 포트 레지스터 (A) 와 데이터 포트 레지스터 (D)
-를 통해 접근되는 내부 레지스터 집합을 갖는 이더넷 카드를 생각해 봅시다.  내부의
-5번 레지스터를 읽기 위해 다음의 코드가 사용될 수 있습니다:
-
-	*A = 5;
-	x = *D;
-
-하지만, 이건 다음의 두 조합 중 하나로 만들어질 수 있습니다:
-
-	STORE *A = 5, x = LOAD *D
-	x = LOAD *D, STORE *A = 5
-
-두번째 조합은 데이터를 읽어온 _후에_ 주소를 설정하므로, 오동작을 일으킬 겁니다.
-
-
-보장사항
---------
-
-CPU 에게 기대할 수 있는 최소한의 보장사항 몇가지가 있습니다:
-
- (*) 어떤 CPU 든, 의존성이 존재하는 메모리 액세스들은 해당 CPU 자신에게
-     있어서는 순서대로 메모리 시스템에 수행 요청됩니다. 즉, 다음에 대해서:
-
-	Q = READ_ONCE(P); smp_read_barrier_depends(); D = READ_ONCE(*Q);
-
-     CPU 는 다음과 같은 메모리 오퍼레이션 시퀀스를 수행 요청합니다:
-
-	Q = LOAD P, D = LOAD *Q
-
-     그리고 그 시퀀스 내에서의 순서는 항상 지켜집니다.  대부분의 시스템에서
-     smp_read_barrier_depends() 는 아무일도 안하지만 DEC Alpha 에서는
-     명시적으로 사용되어야 합니다.  보통의 경우에는 smp_read_barrier_depends()
-     를 직접 사용하는 대신 rcu_dereference() 같은 것들을 사용해야 함을
-     알아두세요.
-
- (*) 특정 CPU 내에서 겹치는 영역의 메모리에 행해지는 로드와 스토어 들은 해당
-     CPU 안에서는 순서가 바뀌지 않은 것으로 보여집니다.  즉, 다음에 대해서:
-
-	a = READ_ONCE(*X); WRITE_ONCE(*X, b);
-
-     CPU 는 다음의 메모리 오퍼레이션 시퀀스만을 메모리에 요청할 겁니다:
-
-	a = LOAD *X, STORE *X = b
-
-     그리고 다음에 대해서는:
-
-	WRITE_ONCE(*X, c); d = READ_ONCE(*X);
-
-     CPU 는 다음의 수행 요청만을 만들어 냅니다:
-
-	STORE *X = c, d = LOAD *X
-
-     (로드 오퍼레이션과 스토어 오퍼레이션이 겹치는 메모리 영역에 대해
-     수행된다면 해당 오퍼레이션들은 겹친다고 표현됩니다).
-
-그리고 _반드시_ 또는 _절대로_ 가정하거나 가정하지 말아야 하는 것들이 있습니다:
-
- (*) 컴파일러가 READ_ONCE() 나 WRITE_ONCE() 로 보호되지 않은 메모리 액세스를
-     당신이 원하는 대로 할 것이라는 가정은 _절대로_ 해선 안됩니다.  그것들이
-     없다면, 컴파일러는 컴파일러 배리어 섹션에서 다루게 될, 모든 "창의적인"
-     변경들을 만들어낼 권한을 갖게 됩니다.
-
- (*) 개별적인 로드와 스토어들이 주어진 순서대로 요청될 것이라는 가정은 _절대로_
-     하지 말아야 합니다.  이 말은 곧:
-
-	X = *A; Y = *B; *D = Z;
-
-     는 다음의 것들 중 어느 것으로든 만들어질 수 있다는 의미입니다:
-
-	X = LOAD *A,  Y = LOAD *B,  STORE *D = Z
-	X = LOAD *A,  STORE *D = Z, Y = LOAD *B
-	Y = LOAD *B,  X = LOAD *A,  STORE *D = Z
-	Y = LOAD *B,  STORE *D = Z, X = LOAD *A
-	STORE *D = Z, X = LOAD *A,  Y = LOAD *B
-	STORE *D = Z, Y = LOAD *B,  X = LOAD *A
-
- (*) 겹치는 메모리 액세스들은 합쳐지거나 버려질 수 있음을 _반드시_ 가정해야
-     합니다.  다음의 코드는:
-
-	X = *A; Y = *(A + 4);
-
-     다음의 것들 중 뭐든 될 수 있습니다:
-
-	X = LOAD *A; Y = LOAD *(A + 4);
-	Y = LOAD *(A + 4); X = LOAD *A;
-	{X, Y} = LOAD {*A, *(A + 4) };
-
-     그리고:
-
-	*A = X; *(A + 4) = Y;
-
-     는 다음 중 뭐든 될 수 있습니다:
-
-	STORE *A = X; STORE *(A + 4) = Y;
-	STORE *(A + 4) = Y; STORE *A = X;
-	STORE {*A, *(A + 4) } = {X, Y};
-
-그리고 보장사항에 반대되는 것들(anti-guarantees)이 있습니다:
-
- (*) 이 보장사항들은 bitfield 에는 적용되지 않는데, 컴파일러들은 bitfield 를
-     수정하는 코드를 생성할 때 원자성 없는(non-atomic) 읽고-수정하고-쓰는
-     인스트럭션들의 조합을 만드는 경우가 많기 때문입니다.  병렬 알고리즘의
-     동기화에 bitfield 를 사용하려 하지 마십시오.
-
- (*) bitfield 들이 여러 락으로 보호되는 경우라 하더라도, 하나의 bitfield 의
-     모든 필드들은 하나의 락으로 보호되어야 합니다.  만약 한 bitfield 의 두
-     필드가 서로 다른 락으로 보호된다면, 컴파일러의 원자성 없는
-     읽고-수정하고-쓰는 인스트럭션 조합은 한 필드에의 업데이트가 근처의
-     필드에도 영향을 끼치게 할 수 있습니다.
-
- (*) 이 보장사항들은 적절하게 정렬되고 크기가 잡힌 스칼라 변수들에 대해서만
-     적용됩니다.  "적절하게 크기가 잡힌" 이라함은 현재로써는 "char", "short",
-     "int" 그리고 "long" 과 같은 크기의 변수들을 의미합니다.  "적절하게 정렬된"
-     은 자연스런 정렬을 의미하는데, 따라서 "char" 에 대해서는 아무 제약이 없고,
-     "short" 에 대해서는 2바이트 정렬을, "int" 에는 4바이트 정렬을, 그리고
-     "long" 에 대해서는 32-bit 시스템인지 64-bit 시스템인지에 따라 4바이트 또는
-     8바이트 정렬을 의미합니다.  이 보장사항들은 C11 표준에서 소개되었으므로,
-     C11 전의 오래된 컴파일러(예를 들어, gcc 4.6) 를 사용할 때엔 주의하시기
-     바랍니다.  표준에 이 보장사항들은 "memory location" 을 정의하는 3.14
-     섹션에 다음과 같이 설명되어 있습니다:
-     (역자: 인용문이므로 번역하지 않습니다)
-
-	memory location
-		either an object of scalar type, or a maximal sequence
-		of adjacent bit-fields all having nonzero width
-
-		NOTE 1: Two threads of execution can update and access
-		separate memory locations without interfering with
-		each other.
-
-		NOTE 2: A bit-field and an adjacent non-bit-field member
-		are in separate memory locations. The same applies
-		to two bit-fields, if one is declared inside a nested
-		structure declaration and the other is not, or if the two
-		are separated by a zero-length bit-field declaration,
-		or if they are separated by a non-bit-field member
-		declaration. It is not safe to concurrently update two
-		bit-fields in the same structure if all members declared
-		between them are also bit-fields, no matter what the
-		sizes of those intervening bit-fields happen to be.
-
-
-=========================
-메모리 배리어란 무엇인가?
-=========================
-
-앞에서 봤듯이, 상호간 의존성이 없는 메모리 오퍼레이션들은 실제로는 무작위적
-순서로 수행될 수 있으며, 이는 CPU 와 CPU 간의 상호작용이나 I/O 에 문제가 될 수
-있습니다.  따라서 컴파일러와 CPU 가 순서를 바꾸는데 제약을 걸 수 있도록 개입할
-수 있는 어떤 방법이 필요합니다.
-
-메모리 배리어는 그런 개입 수단입니다.  메모리 배리어는 배리어를 사이에 둔 앞과
-뒤 양측의 메모리 오퍼레이션들 간에 부분적 순서가 존재하도록 하는 효과를 줍니다.
-
-시스템의 CPU 들과 여러 디바이스들은 성능을 올리기 위해 명령어 재배치, 실행
-유예, 메모리 오퍼레이션들의 조합, 예측적 로드(speculative load), 브랜치
-예측(speculative branch prediction), 다양한 종류의 캐싱(caching) 등의 다양한
-트릭을 사용할 수 있기 때문에 이런 강제력은 중요합니다.  메모리 배리어들은 이런
-트릭들을 무효로 하거나 억제하는 목적으로 사용되어져서 코드가 여러 CPU 와
-디바이스들 간의 상호작용을 정상적으로 제어할 수 있게 해줍니다.
-
-
-메모리 배리어의 종류
---------------------
-
-메모리 배리어는 네개의 기본 타입으로 분류됩니다:
-
- (1) 쓰기 (또는 스토어) 메모리 배리어.
-
-     쓰기 메모리 배리어는 시스템의 다른 컴포넌트들에 해당 배리어보다 앞서
-     명시된 모든 STORE 오퍼레이션들이 해당 배리어 뒤에 명시된 모든 STORE
-     오퍼레이션들보다 먼저 수행된 것으로 보일 것을 보장합니다.
-
-     쓰기 배리어는 스토어 오퍼레이션들에 대한 부분적 순서 세우기입니다; 로드
-     오퍼레이션들에 대해서는 어떤 영향도 끼치지 않습니다.
-
-     CPU 는 시간의 흐름에 따라 메모리 시스템에 일련의 스토어 오퍼레이션들을
-     하나씩 요청해 집어넣습니다.  쓰기 배리어 앞의 모든 스토어 오퍼레이션들은
-     쓰기 배리어 뒤의 모든 스토어 오퍼레이션들보다 _앞서_ 수행될 겁니다.
-
-     [!] 쓰기 배리어들은 읽기 또는 데이터 의존성 배리어와 함께 짝을 맞춰
-     사용되어야만 함을 알아두세요; "SMP 배리어 짝맞추기" 서브섹션을 참고하세요.
-
-
- (2) 데이터 의존성 배리어.
-
-     데이터 의존성 배리어는 읽기 배리어의 보다 완화된 형태입니다.  두개의 로드
-     오퍼레이션이 있고 두번째 것이 첫번째 것의 결과에 의존하고 있을 때(예:
-     두번째 로드가 참조할 주소를 첫번째 로드가 읽는 경우), 두번째 로드가 읽어올
-     데이터는 첫번째 로드에 의해 그 주소가 얻어지기 전에 업데이트 되어 있음을
-     보장하기 위해서 데이터 의존성 배리어가 필요할 수 있습니다.
-
-     데이터 의존성 배리어는 상호 의존적인 로드 오퍼레이션들 사이의 부분적 순서
-     세우기입니다; 스토어 오퍼레이션들이나 독립적인 로드들, 또는 중복되는
-     로드들에 대해서는 어떤 영향도 끼치지 않습니다.
-
-     (1) 에서 언급했듯이, 시스템의 CPU 들은 메모리 시스템에 일련의 스토어
-     오퍼레이션들을 던져 넣고 있으며, 거기에 관심이 있는 다른 CPU 는 그
-     오퍼레이션들을 메모리 시스템이 실행한 결과를 인지할 수 있습니다.  이처럼
-     다른 CPU 의 스토어 오퍼레이션의 결과에 관심을 두고 있는 CPU 가 수행 요청한
-     데이터 의존성 배리어는, 배리어 앞의 어떤 로드 오퍼레이션이 다른 CPU 에서
-     던져 넣은 스토어 오퍼레이션과 같은 영역을 향했다면, 그런 스토어
-     오퍼레이션들이 만들어내는 결과가 데이터 의존성 배리어 뒤의 로드
-     오퍼레이션들에게는 보일 것을 보장합니다.
-
-     이 순서 세우기 제약에 대한 그림을 보기 위해선 "메모리 배리어 시퀀스의 예"
-     서브섹션을 참고하시기 바랍니다.
-
-     [!] 첫번째 로드는 반드시 _데이터_ 의존성을 가져야지 컨트롤 의존성을 가져야
-     하는게 아님을 알아두십시오.  만약 두번째 로드를 위한 주소가 첫번째 로드에
-     의존적이지만 그 의존성은 조건적이지 그 주소 자체를 가져오는게 아니라면,
-     그것은 _컨트롤_ 의존성이고, 이 경우에는 읽기 배리어나 그보다 강력한
-     무언가가 필요합니다.  더 자세한 내용을 위해서는 "컨트롤 의존성" 서브섹션을
-     참고하시기 바랍니다.
-
-     [!] 데이터 의존성 배리어는 보통 쓰기 배리어들과 함께 짝을 맞춰 사용되어야
-     합니다; "SMP 배리어 짝맞추기" 서브섹션을 참고하세요.
-
-
- (3) 읽기 (또는 로드) 메모리 배리어.
-
-     읽기 배리어는 데이터 의존성 배리어 기능의 보장사항에 더해서 배리어보다
-     앞서 명시된 모든 LOAD 오퍼레이션들이 배리어 뒤에 명시되는 모든 LOAD
-     오퍼레이션들보다 먼저 행해진 것으로 시스템의 다른 컴포넌트들에 보여질 것을
-     보장합니다.
-
-     읽기 배리어는 로드 오퍼레이션에 행해지는 부분적 순서 세우기입니다; 스토어
-     오퍼레이션에 대해서는 어떤 영향도 끼치지 않습니다.
-
-     읽기 메모리 배리어는 데이터 의존성 배리어를 내장하므로 데이터 의존성
-     배리어를 대신할 수 있습니다.
-
-     [!] 읽기 배리어는 일반적으로 쓰기 배리어들과 함께 짝을 맞춰 사용되어야
-     합니다; "SMP 배리어 짝맞추기" 서브섹션을 참고하세요.
-
-
- (4) 범용 메모리 배리어.
-
-     범용(general) 메모리 배리어는 배리어보다 앞서 명시된 모든 LOAD 와 STORE
-     오퍼레이션들이 배리어 뒤에 명시된 모든 LOAD 와 STORE 오퍼레이션들보다
-     먼저 수행된 것으로 시스템의 나머지 컴포넌트들에 보이게 됨을 보장합니다.
-
-     범용 메모리 배리어는 로드와 스토어 모두에 대한 부분적 순서 세우기입니다.
-
-     범용 메모리 배리어는 읽기 메모리 배리어, 쓰기 메모리 배리어 모두를
-     내장하므로, 두 배리어를 모두 대신할 수 있습니다.
-
-
-그리고 두개의 명시적이지 않은 타입이 있습니다:
-
- (5) ACQUIRE 오퍼레이션.
-
-     이 타입의 오퍼레이션은 단방향의 투과성 배리어처럼 동작합니다.  ACQUIRE
-     오퍼레이션 뒤의 모든 메모리 오퍼레이션들이 ACQUIRE 오퍼레이션 후에
-     일어난 것으로 시스템의 나머지 컴포넌트들에 보이게 될 것이 보장됩니다.
-     LOCK 오퍼레이션과 smp_load_acquire(), smp_cond_acquire() 오퍼레이션도
-     ACQUIRE 오퍼레이션에 포함됩니다.  smp_cond_acquire() 오퍼레이션은 컨트롤
-     의존성과 smp_rmb() 를 사용해서 ACQUIRE 의 의미적 요구사항(semantic)을
-     충족시킵니다.
-
-     ACQUIRE 오퍼레이션 앞의 메모리 오퍼레이션들은 ACQUIRE 오퍼레이션 완료 후에
-     수행된 것처럼 보일 수 있습니다.
-
-     ACQUIRE 오퍼레이션은 거의 항상 RELEASE 오퍼레이션과 짝을 지어 사용되어야
-     합니다.
-
-
- (6) RELEASE 오퍼레이션.
-
-     이 타입의 오퍼레이션들도 단방향 투과성 배리어처럼 동작합니다.  RELEASE
-     오퍼레이션 앞의 모든 메모리 오퍼레이션들은 RELEASE 오퍼레이션 전에 완료된
-     것으로 시스템의 다른 컴포넌트들에 보여질 것이 보장됩니다.  UNLOCK 류의
-     오퍼레이션들과 smp_store_release() 오퍼레이션도 RELEASE 오퍼레이션의
-     일종입니다.
-
-     RELEASE 오퍼레이션 뒤의 메모리 오퍼레이션들은 RELEASE 오퍼레이션이
-     완료되기 전에 행해진 것처럼 보일 수 있습니다.
-
-     ACQUIRE 와 RELEASE 오퍼레이션의 사용은 일반적으로 다른 메모리 배리어의
-     필요성을 없앱니다 (하지만 "MMIO 쓰기 배리어" 서브섹션에서 설명되는 예외를
-     알아두세요).  또한, RELEASE+ACQUIRE 조합은 범용 메모리 배리어처럼 동작할
-     것을 보장하지 -않습니다-.  하지만, 어떤 변수에 대한 RELEASE 오퍼레이션을
-     앞서는 메모리 액세스들의 수행 결과는 이 RELEASE 오퍼레이션을 뒤이어 같은
-     변수에 대해 수행된 ACQUIRE 오퍼레이션을 뒤따르는 메모리 액세스에는 보여질
-     것이 보장됩니다.  다르게 말하자면, 주어진 변수의 크리티컬 섹션에서는, 해당
-     변수에 대한 앞의 크리티컬 섹션에서의 모든 액세스들이 완료되었을 것을
-     보장합니다.
-
-     즉, ACQUIRE 는 최소한의 "취득" 동작처럼, 그리고 RELEASE 는 최소한의 "공개"
-     처럼 동작한다는 의미입니다.
-
-atomic_ops.txt 에서 설명되는 어토믹 오퍼레이션들 중에는 완전히 순서잡힌 것들과
-(배리어를 사용하지 않는) 완화된 순서의 것들 외에 ACQUIRE 와 RELEASE 부류의
-것들도 존재합니다.  로드와 스토어를 모두 수행하는 조합된 어토믹 오퍼레이션에서,
-ACQUIRE 는 해당 오퍼레이션의 로드 부분에만 적용되고 RELEASE 는 해당
-오퍼레이션의 스토어 부분에만 적용됩니다.
-
-메모리 배리어들은 두 CPU 간, 또는 CPU 와 디바이스 간에 상호작용의 가능성이 있을
-때에만 필요합니다.  만약 어떤 코드에 그런 상호작용이 없을 것이 보장된다면, 해당
-코드에서는 메모리 배리어를 사용할 필요가 없습니다.
-
-
-이것들은 _최소한의_ 보장사항들임을 알아두세요.  다른 아키텍쳐에서는 더 강력한
-보장사항을 제공할 수도 있습니다만, 그런 보장사항은 아키텍쳐 종속적 코드 이외의
-부분에서는 신뢰되지 _않을_ 겁니다.
-
-
-메모리 배리어에 대해 가정해선 안될 것
--------------------------------------
-
-리눅스 커널 메모리 배리어들이 보장하지 않는 것들이 있습니다:
-
- (*) 메모리 배리어 앞에서 명시된 어떤 메모리 액세스도 메모리 배리어 명령의 수행
-     완료 시점까지 _완료_ 될 것이란 보장은 없습니다; 배리어가 하는 일은 CPU 의
-     액세스 큐에 특정 타입의 액세스들은 넘을 수 없는 선을 긋는 것으로 생각될 수
-     있습니다.
-
- (*) 한 CPU 에서 메모리 배리어를 수행하는게 시스템의 다른 CPU 나 하드웨어에
-     어떤 직접적인 영향을 끼친다는 보장은 존재하지 않습니다.  배리어 수행이
-     만드는 간접적 영향은 두번째 CPU 가 첫번째 CPU 의 액세스들의 결과를
-     바라보는 순서가 됩니다만, 다음 항목을 보세요:
-
- (*) 첫번째 CPU 가 두번째 CPU 의 메모리 액세스들의 결과를 바라볼 때, _설령_
-     두번째 CPU 가 메모리 배리어를 사용한다 해도, 첫번째 CPU _또한_ 그에 맞는
-     메모리 배리어를 사용하지 않는다면 ("SMP 배리어 짝맞추기" 서브섹션을
-     참고하세요) 그 결과가 올바른 순서로 보여진다는 보장은 없습니다.
-
- (*) CPU 바깥의 하드웨어[*] 가 메모리 액세스들의 순서를 바꾸지 않는다는 보장은
-     존재하지 않습니다.  CPU 캐시 일관성 메커니즘은 메모리 배리어의 간접적
-     영향을 CPU 사이에 전파하긴 하지만, 순서대로 전파하지는 않을 수 있습니다.
-
-	[*] 버스 마스터링 DMA 와 일관성에 대해서는 다음을 참고하시기 바랍니다:
-
-	    Documentation/PCI/pci.txt
-	    Documentation/DMA-API-HOWTO.txt
-	    Documentation/DMA-API.txt
-
-
-데이터 의존성 배리어
---------------------
-
-데이터 의존성 배리어의 사용에 있어 지켜야 하는 사항들은 약간 미묘하고, 데이터
-의존성 배리어가 사용되어야 하는 상황도 항상 명백하지는 않습니다.  설명을 위해
-다음의 이벤트 시퀀스를 생각해 봅시다:
-
-	CPU 1		      CPU 2
-	===============	      ===============
-	{ A == 1, B == 2, C == 3, P == &A, Q == &C }
-	B = 4;
-	<쓰기 배리어>
-	WRITE_ONCE(P, &B)
-			      Q = READ_ONCE(P);
-			      D = *Q;
-
-여기엔 분명한 데이터 의존성이 존재하므로, 이 시퀀스가 끝났을 때 Q 는 &A 또는 &B
-일 것이고, 따라서:
-
-	(Q == &A) 는 (D == 1) 를,
-	(Q == &B) 는 (D == 4) 를 의미합니다.
-
-하지만!  CPU 2 는 B 의 업데이트를 인식하기 전에 P 의 업데이트를 인식할 수 있고,
-따라서 다음의 결과가 가능합니다:
-
-	(Q == &B) and (D == 2) ????
-
-이런 결과는 일관성이나 인과 관계 유지가 실패한 것처럼 보일 수도 있겠지만,
-그렇지 않습니다, 그리고 이 현상은 (DEC Alpha 와 같은) 여러 CPU 에서 실제로
-발견될 수 있습니다.
-
-이 문제 상황을 제대로 해결하기 위해, 데이터 의존성 배리어나 그보다 강화된
-무언가가 주소를 읽어올 때와 데이터를 읽어올 때 사이에 추가되어야만 합니다:
-
-	CPU 1		      CPU 2
-	===============	      ===============
-	{ A == 1, B == 2, C == 3, P == &A, Q == &C }
-	B = 4;
-	<쓰기 배리어>
-	WRITE_ONCE(P, &B);
-			      Q = READ_ONCE(P);
-			      <데이터 의존성 배리어>
-			      D = *Q;
-
-이 변경은 앞의 처음 두가지 결과 중 하나만이 발생할 수 있고, 세번째의 결과는
-발생할 수 없도록 합니다.
-
-데이터 의존성 배리어는 의존적 쓰기에 대해서도 순서를 잡아줍니다:
-
-	CPU 1		      CPU 2
-	===============	      ===============
-	{ A == 1, B == 2, C = 3, P == &A, Q == &C }
-	B = 4;
-	<쓰기 배리어>
-	WRITE_ONCE(P, &B);
-			      Q = READ_ONCE(P);
-			      <데이터 의존성 배리어>
-			      *Q = 5;
-
-이 데이터 의존성 배리어는 Q 로의 읽기가 *Q 로의 스토어와 순서를 맞추게
-해줍니다.  이는 다음과 같은 결과를 막습니다:
-
-	(Q == &B) && (B == 4)
-
-이런 패턴은 드물게 사용되어야 함을 알아 두시기 바랍니다.  무엇보다도, 의존성
-순서 규칙의 의도는 쓰기 작업을 -예방- 해서 그로 인해 발생하는 비싼 캐시 미스도
-없애려는 것입니다.  이 패턴은 드물게 발생하는 에러 조건 같은것들을 기록하는데
-사용될 수 있고, 이렇게 배리어를 사용해 순서를 지키게 함으로써 그런 기록이
-사라지는 것을 막습니다.
-
-
-[!] 상당히 비직관적인 이 상황은 분리된 캐시를 가진 기계, 예를 들어 한 캐시
-뱅크가 짝수번 캐시 라인을 처리하고 다른 뱅크는 홀수번 캐시 라인을 처리하는 기계
-등에서 가장 잘 발생합니다.  포인터 P 는 홀수 번호의 캐시 라인에 있고, 변수 B 는
-짝수 번호 캐시 라인에 있다고 생각해 봅시다.  그런 상태에서 읽기 작업을 하는 CPU
-의 짝수번 뱅크는 할 일이 쌓여 매우 바쁘지만 홀수번 뱅크는 할 일이 없어 아무
-일도 하지 않고  있었다면, 포인터 P 는 새 값 (&B) 을, 그리고 변수 B 는 옛날 값
-(2) 을 가지고 있는 상태가 보여질 수도 있습니다.
-
-
-데이터 의존성 배리어는 매우 중요한데, 예를 들어 RCU 시스템에서 그렇습니다.
-include/linux/rcupdate.h 의 rcu_assign_pointer() 와 rcu_dereference() 를
-참고하세요.  여기서 데이터 의존성 배리어는 RCU 로 관리되는 포인터의 타겟을 현재
-타겟에서 수정된 새로운 타겟으로 바꾸는 작업에서 새로 수정된 타겟이 초기화가
-완료되지 않은 채로 보여지는 일이 일어나지 않게 해줍니다.
-
-더 많은 예를 위해선 "캐시 일관성" 서브섹션을 참고하세요.
-
-
-컨트롤 의존성
--------------
-
-로드-로드 컨트롤 의존성은 데이터 의존성 배리어만으로는 정확히 동작할 수가
-없어서 읽기 메모리 배리어를 필요로 합니다.  아래의 코드를 봅시다:
-
-	q = READ_ONCE(a);
-	if (q) {
-		<데이터 의존성 배리어>  /* BUG: No data dependency!!! */
-		p = READ_ONCE(b);
-	}
-
-이 코드는 원하는 대로의 효과를 내지 못할 수 있는데, 이 코드에는 데이터 의존성이
-아니라 컨트롤 의존성이 존재하기 때문으로, 이런 상황에서 CPU 는 실행 속도를 더
-빠르게 하기 위해 분기 조건의 결과를 예측하고 코드를 재배치 할 수 있어서 다른
-CPU 는 b 로부터의 로드 오퍼레이션이 a 로부터의 로드 오퍼레이션보다 먼저 발생한
-걸로 인식할 수 있습니다.  여기에 정말로 필요했던 건 다음과 같습니다:
-
-	q = READ_ONCE(a);
-	if (q) {
-		<읽기 배리어>
-		p = READ_ONCE(b);
-	}
-
-하지만, 스토어 오퍼레이션은 예측적으로 수행되지 않습니다.  즉, 다음 예에서와
-같이 로드-스토어 컨트롤 의존성이 존재하는 경우에는 순서가 -지켜진다-는
-의미입니다.
-
-	q = READ_ONCE(a);
-	if (q) {
-		WRITE_ONCE(b, p);
-	}
-
-컨트롤 의존성은 보통 다른 타입의 배리어들과 짝을 맞춰 사용됩니다.  그렇다곤
-하나, READ_ONCE() 는 반드시 사용해야 함을 부디 명심하세요!  READ_ONCE() 가
-없다면, 컴파일러가 'a' 로부터의 로드를 'a' 로부터의 또다른 로드와, 'b' 로의
-스토어를 'b' 로의 또다른 스토어와 조합해 버려 매우 비직관적인 결과를 초래할 수
-있습니다.
-
-이걸로 끝이 아닌게, 컴파일러가 변수 'a' 의 값이 항상 0이 아니라고 증명할 수
-있다면, 앞의 예에서 "if" 문을 없애서 다음과 같이 최적화 할 수도 있습니다:
-
-	q = a;
-	b = p;  /* BUG: Compiler and CPU can both reorder!!! */
-
-그러니 READ_ONCE() 를 반드시 사용하세요.
-
-다음과 같이 "if" 문의 양갈래 브랜치에 모두 존재하는 동일한 스토어에 대해 순서를
-강제하고 싶은 경우가 있을 수 있습니다:
-
-	q = READ_ONCE(a);
-	if (q) {
-		barrier();
-		WRITE_ONCE(b, p);
-		do_something();
-	} else {
-		barrier();
-		WRITE_ONCE(b, p);
-		do_something_else();
-	}
-
-안타깝게도, 현재의 컴파일러들은 높은 최적화 레벨에서는 이걸 다음과 같이
-바꿔버립니다:
-
-	q = READ_ONCE(a);
-	barrier();
-	WRITE_ONCE(b, p);  /* BUG: No ordering vs. load from a!!! */
-	if (q) {
-		/* WRITE_ONCE(b, p); -- moved up, BUG!!! */
-		do_something();
-	} else {
-		/* WRITE_ONCE(b, p); -- moved up, BUG!!! */
-		do_something_else();
-	}
-
-이제 'a' 에서의 로드와 'b' 로의 스토어 사이에는 조건적 관계가 없기 때문에 CPU
-는 이들의 순서를 바꿀 수 있게 됩니다: 이런 경우에 조건적 관계는 반드시
-필요한데, 모든 컴파일러 최적화가 이루어지고 난 후의 어셈블리 코드에서도
-마찬가지입니다.  따라서, 이 예에서 순서를 지키기 위해서는 smp_store_release()
-와 같은 명시적 메모리 배리어가 필요합니다:
-
-	q = READ_ONCE(a);
-	if (q) {
-		smp_store_release(&b, p);
-		do_something();
-	} else {
-		smp_store_release(&b, p);
-		do_something_else();
-	}
-
-반면에 명시적 메모리 배리어가 없다면, 이런 경우의 순서는 스토어 오퍼레이션들이
-서로 다를 때에만 보장되는데, 예를 들면 다음과 같은 경우입니다:
-
-	q = READ_ONCE(a);
-	if (q) {
-		WRITE_ONCE(b, p);
-		do_something();
-	} else {
-		WRITE_ONCE(b, r);
-		do_something_else();
-	}
-
-처음의 READ_ONCE() 는 컴파일러가 'a' 의 값을 증명해내는 것을 막기 위해 여전히
-필요합니다.
-
-또한, 로컬 변수 'q' 를 가지고 하는 일에 대해 주의해야 하는데, 그러지 않으면
-컴파일러는 그 값을 추측하고 또다시 필요한 조건관계를 없애버릴 수 있습니다.
-예를 들면:
-
-	q = READ_ONCE(a);
-	if (q % MAX) {
-		WRITE_ONCE(b, p);
-		do_something();
-	} else {
-		WRITE_ONCE(b, r);
-		do_something_else();
-	}
-
-만약 MAX 가 1 로 정의된 상수라면, 컴파일러는 (q % MAX) 는 0이란 것을 알아채고,
-위의 코드를 아래와 같이 바꿔버릴 수 있습니다:
-
-	q = READ_ONCE(a);
-	WRITE_ONCE(b, p);
-	do_something_else();
-
-이렇게 되면, CPU 는 변수 'a' 로부터의 로드와 변수 'b' 로의 스토어 사이의 순서를
-지켜줄 필요가 없어집니다.  barrier() 를 추가해 해결해 보고 싶겠지만, 그건
-도움이 안됩니다.  조건 관계는 사라졌고, barrier() 는 이를 되돌리지 못합니다.
-따라서, 이 순서를 지켜야 한다면, MAX 가 1 보다 크다는 것을, 다음과 같은 방법을
-사용해 분명히 해야 합니다:
-
-	q = READ_ONCE(a);
-	BUILD_BUG_ON(MAX <= 1); /* Order load from a with store to b. */
-	if (q % MAX) {
-		WRITE_ONCE(b, p);
-		do_something();
-	} else {
-		WRITE_ONCE(b, r);
-		do_something_else();
-	}
-
-'b' 로의 스토어들은 여전히 서로 다름을 알아두세요.  만약 그것들이 동일하면,
-앞에서 이야기했듯, 컴파일러가 그 스토어 오퍼레이션들을 'if' 문 바깥으로
-끄집어낼 수 있습니다.
-
-또한 이진 조건문 평가에 너무 의존하지 않도록 조심해야 합니다.  다음의 예를
-봅시다:
-
-	q = READ_ONCE(a);
-	if (q || 1 > 0)
-		WRITE_ONCE(b, 1);
-
-첫번째 조건만으로는 브랜치 조건 전체를 거짓으로 만들 수 없고 두번째 조건은 항상
-참이기 때문에, 컴파일러는 이 예를 다음과 같이 바꿔서 컨트롤 의존성을 없애버릴
-수 있습니다:
-
-	q = READ_ONCE(a);
-	WRITE_ONCE(b, 1);
-
-이 예는 컴파일러가 코드를 추측으로 수정할 수 없도록 분명히 해야 한다는 점을
-강조합니다.  조금 더 일반적으로 말해서, READ_ONCE() 는 컴파일러에게 주어진 로드
-오퍼레이션을 위한 코드를 정말로 만들도록 하지만, 컴파일러가 그렇게 만들어진
-코드의 수행 결과를 사용하도록 강제하지는 않습니다.
-
-또한, 컨트롤 의존성은 if 문의 then 절과 else 절에 대해서만 적용됩니다.  상세히
-말해서, 컨트롤 의존성은 if 문을 뒤따르는 코드에는 적용되지 않습니다:
-
-	q = READ_ONCE(a);
-	if (q) {
-		WRITE_ONCE(b, p);
-	} else {
-		WRITE_ONCE(b, r);
-	}
-	WRITE_ONCE(c, 1);  /* BUG: No ordering against the read from "a". */
-
-컴파일러는 volatile 타입에 대한 액세스를 재배치 할 수 없고 이 조건 하의 "b"
-로의 쓰기를 재배치 할 수 없기 때문에 여기에 순서 규칙이 존재한다고 주장하고
-싶을 겁니다.  불행히도 이 경우에, 컴파일러는 다음의 가상의 pseudo-assembly 언어
-코드처럼 "b" 로의 두개의 쓰기 오퍼레이션을 conditional-move 인스트럭션으로
-번역할 수 있습니다:
-
-	ld r1,a
-	ld r2,p
-	ld r3,r
-	cmp r1,$0
-	cmov,ne r4,r2
-	cmov,eq r4,r3
-	st r4,b
-	st $1,c
-
-완화된 순서 규칙의 CPU 는 "a" 로부터의 로드와 "c" 로의 스토어 사이에 어떤
-종류의 의존성도 갖지 않을 겁니다.  이 컨트롤 의존성은 두개의 cmov 인스트럭션과
-거기에 의존하는 스토어 에게만 적용될 겁니다.  짧게 말하자면, 컨트롤 의존성은
-주어진 if 문의 then 절과 else 절에게만 (그리고 이 두 절 내에서 호출되는
-함수들에게까지) 적용되지, 이 if 문을 뒤따르는 코드에는 적용되지 않습니다.
-
-마지막으로, 컨트롤 의존성은 이행성 (transitivity) 을 제공하지 -않습니다-.  이건
-x 와 y 가 둘 다 0 이라는 초기값을 가졌다는 가정 하의 두개의 예제로
-보이겠습니다:
-
-	CPU 0                     CPU 1
-	=======================   =======================
-	r1 = READ_ONCE(x);        r2 = READ_ONCE(y);
-	if (r1 > 0)               if (r2 > 0)
-	  WRITE_ONCE(y, 1);         WRITE_ONCE(x, 1);
-
-	assert(!(r1 == 1 && r2 == 1));
-
-이 두 CPU 예제에서 assert() 의 조건은 항상 참일 것입니다.  그리고, 만약 컨트롤
-의존성이 이행성을 (실제로는 그러지 않지만) 보장한다면, 다음의 CPU 가 추가되어도
-아래의 assert() 조건은 참이 될것입니다:
-
-	CPU 2
-	=====================
-	WRITE_ONCE(x, 2);
-
-	assert(!(r1 == 2 && r2 == 1 && x == 2)); /* FAILS!!! */
-
-하지만 컨트롤 의존성은 이행성을 제공하지 -않기- 때문에, 세개의 CPU 예제가 실행
-완료된 후에 위의 assert() 의 조건은 거짓으로 평가될 수 있습니다.  세개의 CPU
-예제가 순서를 지키길 원한다면, CPU 0 와 CPU 1 코드의 로드와 스토어 사이, "if"
-문 바로 다음에 smp_mb()를 넣어야 합니다.  더 나아가서, 최초의 두 CPU 예제는
-매우 위험하므로 사용되지 않아야 합니다.
-
-이 두개의 예제는 다음 논문:
-http://www.cl.cam.ac.uk/users/pes20/ppc-supplemental/test6.pdf 와
-이 사이트: https://www.cl.cam.ac.uk/~pes20/ppcmem/index.html 에 나온 LB 와 WWC
-리트머스 테스트입니다.
-
-요약하자면:
-
-  (*) 컨트롤 의존성은 앞의 로드들을 뒤의 스토어들에 대해 순서를 맞춰줍니다.
-      하지만, 그 외의 어떤 순서도 보장하지 -않습니다-: 앞의 로드와 뒤의 로드들
-      사이에도, 앞의 스토어와 뒤의 스토어들 사이에도요.  이런 다른 형태의
-      순서가 필요하다면 smp_rmb() 나 smp_wmb()를, 또는, 앞의 스토어들과 뒤의
-      로드들 사이의 순서를 위해서는 smp_mb() 를 사용하세요.
-
-  (*) "if" 문의 양갈래 브랜치가 같은 변수에의 동일한 스토어로 시작한다면, 그
-      스토어들은 각 스토어 앞에 smp_mb() 를 넣거나 smp_store_release() 를
-      사용해서 스토어를 하는 식으로 순서를 맞춰줘야 합니다.  이 문제를 해결하기
-      위해 "if" 문의 양갈래 브랜치의 시작 지점에 barrier() 를 넣는 것만으로는
-      충분한 해결이 되지 않는데, 이는 앞의 예에서 본것과 같이, 컴파일러의
-      최적화는 barrier() 가 의미하는 바를 지키면서도 컨트롤 의존성을 손상시킬
-      수 있기 때문이라는 점을 부디 알아두시기 바랍니다.
-
-  (*) 컨트롤 의존성은 앞의 로드와 뒤의 스토어 사이에 최소 하나의, 실행
-      시점에서의 조건관계를 필요로 하며, 이 조건관계는 앞의 로드와 관계되어야
-      합니다.  만약 컴파일러가 조건 관계를 최적화로 없앨수 있다면, 순서도
-      최적화로 없애버렸을 겁니다.  READ_ONCE() 와 WRITE_ONCE() 의 주의 깊은
-      사용은 주어진 조건 관계를 유지하는데 도움이 될 수 있습니다.
-
-  (*) 컨트롤 의존성을 위해선 컴파일러가 조건관계를 없애버리는 것을 막아야
-      합니다.  주의 깊은 READ_ONCE() 나 atomic{,64}_read() 의 사용이 컨트롤
-      의존성이 사라지지 않게 하는데 도움을 줄 수 있습니다.  더 많은 정보를
-      위해선 "컴파일러 배리어" 섹션을 참고하시기 바랍니다.
-
-  (*) 컨트롤 의존성은 컨트롤 의존성을 갖는 if 문의 then 절과 else 절과 이 두 절
-      내에서 호출되는 함수들에만 적용됩니다.  컨트롤 의존성은 컨트롤 의존성을
-      갖는 if 문을 뒤따르는 코드에는 적용되지 -않습니다-.
-
-  (*) 컨트롤 의존성은 보통 다른 타입의 배리어들과 짝을 맞춰 사용됩니다.
-
-  (*) 컨트롤 의존성은 이행성을 제공하지 -않습니다-.  이행성이 필요하다면,
-      smp_mb() 를 사용하세요.
-
-
-SMP 배리어 짝맞추기
---------------------
-
-CPU 간 상호작용을 다룰 때에 일부 타입의 메모리 배리어는 항상 짝을 맞춰
-사용되어야 합니다.  적절하게 짝을 맞추지 않은 코드는 사실상 에러에 가깝습니다.
-
-범용 배리어들은 범용 배리어끼리도 짝을 맞추지만 이행성이 없는 대부분의 다른
-타입의 배리어들과도 짝을 맞춥니다.  ACQUIRE 배리어는 RELEASE 배리어와 짝을
-맞춥니다만, 둘 다 범용 배리어를 포함해 다른 배리어들과도 짝을 맞출 수 있습니다.
-쓰기 배리어는 데이터 의존성 배리어나 컨트롤 의존성, ACQUIRE 배리어, RELEASE
-배리어, 읽기 배리어, 또는 범용 배리어와 짝을 맞춥니다.  비슷하게 읽기 배리어나
-컨트롤 의존성, 또는 데이터 의존성 배리어는 쓰기 배리어나 ACQUIRE 배리어,
-RELEASE 배리어, 또는 범용 배리어와 짝을 맞추는데, 다음과 같습니다:
-
-	CPU 1		      CPU 2
-	===============	      ===============
-	WRITE_ONCE(a, 1);
-	<쓰기 배리어>
-	WRITE_ONCE(b, 2);     x = READ_ONCE(b);
-			      <읽기 배리어>
-			      y = READ_ONCE(a);
-
-또는:
-
-	CPU 1		      CPU 2
-	===============	      ===============================
-	a = 1;
-	<쓰기 배리어>
-	WRITE_ONCE(b, &a);    x = READ_ONCE(b);
-			      <데이터 의존성 배리어>
-			      y = *x;
-
-또는:
-
-	CPU 1		      CPU 2
-	===============	      ===============================
-	r1 = READ_ONCE(y);
-	<범용 배리어>
-	WRITE_ONCE(y, 1);     if (r2 = READ_ONCE(x)) {
-			         <묵시적 컨트롤 의존성>
-			         WRITE_ONCE(y, 1);
-			      }
-
-	assert(r1 == 0 || r2 == 0);
-
-기본적으로, 여기서의 읽기 배리어는 "더 완화된" 타입일 순 있어도 항상 존재해야
-합니다.
-
-[!] 쓰기 배리어 앞의 스토어 오퍼레이션은 일반적으로 읽기 배리어나 데이터
-의존성 배리어 뒤의 로드 오퍼레이션과 매치될 것이고, 반대도 마찬가지입니다:
-
-	CPU 1                               CPU 2
-	===================                 ===================
-	WRITE_ONCE(a, 1);    }----   --->{  v = READ_ONCE(c);
-	WRITE_ONCE(b, 2);    }    \ /    {  w = READ_ONCE(d);
-	<쓰기 배리어>              \        <읽기 배리어>
-	WRITE_ONCE(c, 3);    }    / \    {  x = READ_ONCE(a);
-	WRITE_ONCE(d, 4);    }----   --->{  y = READ_ONCE(b);
-
-
-메모리 배리어 시퀀스의 예
--------------------------
-
-첫째, 쓰기 배리어는 스토어 오퍼레이션들의 부분적 순서 세우기로 동작합니다.
-아래의 이벤트 시퀀스를 보세요:
-
-	CPU 1
-	=======================
-	STORE A = 1
-	STORE B = 2
-	STORE C = 3
-	<쓰기 배리어>
-	STORE D = 4
-	STORE E = 5
-
-이 이벤트 시퀀스는 메모리 일관성 시스템에 원소끼리의 순서가 존재하지 않는 집합
-{ STORE A, STORE B, STORE C } 가 역시 원소끼리의 순서가 존재하지 않는 집합
-{ STORE D, STORE E } 보다 먼저 일어난 것으로 시스템의 나머지 요소들에 보이도록
-전달됩니다:
-
-	+-------+       :      :
-	|       |       +------+
-	|       |------>| C=3  |     }     /\
-	|       |  :    +------+     }-----  \  -----> 시스템의 나머지 요소에
-	|       |  :    | A=1  |     }        \/       보여질 수 있는 이벤트들
-	|       |  :    +------+     }
-	| CPU 1 |  :    | B=2  |     }
-	|       |       +------+     }
-	|       |   wwwwwwwwwwwwwwww }   <--- 여기서 쓰기 배리어는 배리어 앞의
-	|       |       +------+     }        모든 스토어가 배리어 뒤의 스토어
-	|       |  :    | E=5  |     }        전에 메모리 시스템에 전달되도록
-	|       |  :    +------+     }        합니다
-	|       |------>| D=4  |     }
-	|       |       +------+
-	+-------+       :      :
-	                   |
-	                   | CPU 1 에 의해 메모리 시스템에 전달되는
-	                   | 일련의 스토어 오퍼레이션들
-	                   V
-
-
-둘째, 데이터 의존성 배리어는 데이터 의존적 로드 오퍼레이션들의 부분적 순서
-세우기로 동작합니다.  다음 일련의 이벤트들을 보세요:
-
-	CPU 1			CPU 2
-	=======================	=======================
-		{ B = 7; X = 9; Y = 8; C = &Y }
-	STORE A = 1
-	STORE B = 2
-	<쓰기 배리어>
-	STORE C = &B		LOAD X
-	STORE D = 4		LOAD C (gets &B)
-				LOAD *C (reads B)
-
-여기에 별다른 개입이 없다면, CPU 1 의 쓰기 배리어에도 불구하고 CPU 2 는 CPU 1
-의 이벤트들을 완전히 무작위적 순서로 인지하게 됩니다:
-
-	+-------+       :      :                :       :
-	|       |       +------+                +-------+  | CPU 2 에 인지되는
-	|       |------>| B=2  |-----       --->| Y->8  |  | 업데이트 이벤트
-	|       |  :    +------+     \          +-------+  | 시퀀스
-	| CPU 1 |  :    | A=1  |      \     --->| C->&Y |  V
-	|       |       +------+       |        +-------+
-	|       |   wwwwwwwwwwwwwwww   |        :       :
-	|       |       +------+       |        :       :
-	|       |  :    | C=&B |---    |        :       :       +-------+
-	|       |  :    +------+   \   |        +-------+       |       |
-	|       |------>| D=4  |    ----------->| C->&B |------>|       |
-	|       |       +------+       |        +-------+       |       |
-	+-------+       :      :       |        :       :       |       |
-	                               |        :       :       |       |
-	                               |        :       :       | CPU 2 |
-	                               |        +-------+       |       |
-	    분명히 잘못된        --->  |        | B->7  |------>|       |
-	    B 의 값 인지 (!)           |        +-------+       |       |
-	                               |        :       :       |       |
-	                               |        +-------+       |       |
-	    X 의 로드가 B 의    --->    \       | X->9  |------>|       |
-	    일관성 유지를                \      +-------+       |       |
-	    지연시킴                      ----->| B->2  |       +-------+
-	                                        +-------+
-	                                        :       :
-
-
-앞의 예에서, CPU 2 는 (B 의 값이 될) *C 의 값 읽기가 C 의 LOAD 뒤에 이어짐에도
-B 가 7 이라는 결과를 얻습니다.
-
-하지만, 만약 데이터 의존성 배리어가 C 의 로드와 *C (즉, B) 의 로드 사이에
-있었다면:
-
-	CPU 1			CPU 2
-	=======================	=======================
-		{ B = 7; X = 9; Y = 8; C = &Y }
-	STORE A = 1
-	STORE B = 2
-	<쓰기 배리어>
-	STORE C = &B		LOAD X
-	STORE D = 4		LOAD C (gets &B)
-				<데이터 의존성 배리어>
-				LOAD *C (reads B)
-
-다음과 같이 됩니다:
-
-	+-------+       :      :                :       :
-	|       |       +------+                +-------+
-	|       |------>| B=2  |-----       --->| Y->8  |
-	|       |  :    +------+     \          +-------+
-	| CPU 1 |  :    | A=1  |      \     --->| C->&Y |
-	|       |       +------+       |        +-------+
-	|       |   wwwwwwwwwwwwwwww   |        :       :
-	|       |       +------+       |        :       :
-	|       |  :    | C=&B |---    |        :       :       +-------+
-	|       |  :    +------+   \   |        +-------+       |       |
-	|       |------>| D=4  |    ----------->| C->&B |------>|       |
-	|       |       +------+       |        +-------+       |       |
-	+-------+       :      :       |        :       :       |       |
-	                               |        :       :       |       |
-	                               |        :       :       | CPU 2 |
-	                               |        +-------+       |       |
-	                               |        | X->9  |------>|       |
-	                               |        +-------+       |       |
-	  C 로의 스토어 앞의     --->   \   ddddddddddddddddd   |       |
-	  모든 이벤트 결과가             \      +-------+       |       |
-	  뒤의 로드에게                   ----->| B->2  |------>|       |
-	  보이게 강제한다                       +-------+       |       |
-	                                        :       :       +-------+
-
-
-셋째, 읽기 배리어는 로드 오퍼레이션들에의 부분적 순서 세우기로 동작합니다.
-아래의 일련의 이벤트를 봅시다:
-
-	CPU 1			CPU 2
-	=======================	=======================
-		{ A = 0, B = 9 }
-	STORE A=1
-	<쓰기 배리어>
-	STORE B=2
-				LOAD B
-				LOAD A
-
-CPU 1 은 쓰기 배리어를 쳤지만, 별다른 개입이 없다면 CPU 2 는 CPU 1 에서 행해진
-이벤트의 결과를 무작위적 순서로 인지하게 됩니다.
-
-	+-------+       :      :                :       :
-	|       |       +------+                +-------+
-	|       |------>| A=1  |------      --->| A->0  |
-	|       |       +------+      \         +-------+
-	| CPU 1 |   wwwwwwwwwwwwwwww   \    --->| B->9  |
-	|       |       +------+        |       +-------+
-	|       |------>| B=2  |---     |       :       :
-	|       |       +------+   \    |       :       :       +-------+
-	+-------+       :      :    \   |       +-------+       |       |
-	                             ---------->| B->2  |------>|       |
-	                                |       +-------+       | CPU 2 |
-	                                |       | A->0  |------>|       |
-	                                |       +-------+       |       |
-	                                |       :       :       +-------+
-	                                 \      :       :
-	                                  \     +-------+
-	                                   ---->| A->1  |
-	                                        +-------+
-	                                        :       :
-
-
-하지만, 만약 읽기 배리어가 B 의 로드와 A 의 로드 사이에 존재한다면:
-
-	CPU 1			CPU 2
-	=======================	=======================
-		{ A = 0, B = 9 }
-	STORE A=1
-	<쓰기 배리어>
-	STORE B=2
-				LOAD B
-				<읽기 배리어>
-				LOAD A
-
-CPU 1 에 의해 만들어진 부분적 순서가 CPU 2 에도 그대로 인지됩니다:
-
-	+-------+       :      :                :       :
-	|       |       +------+                +-------+
-	|       |------>| A=1  |------      --->| A->0  |
-	|       |       +------+      \         +-------+
-	| CPU 1 |   wwwwwwwwwwwwwwww   \    --->| B->9  |
-	|       |       +------+        |       +-------+
-	|       |------>| B=2  |---     |       :       :
-	|       |       +------+   \    |       :       :       +-------+
-	+-------+       :      :    \   |       +-------+       |       |
-	                             ---------->| B->2  |------>|       |
-	                                |       +-------+       | CPU 2 |
-	                                |       :       :       |       |
-	                                |       :       :       |       |
-	  여기서 읽기 배리어는   ---->   \  rrrrrrrrrrrrrrrrr   |       |
-	  B 로의 스토어 전의              \     +-------+       |       |
-	  모든 결과를 CPU 2 에             ---->| A->1  |------>|       |
-	  보이도록 한다                         +-------+       |       |
-	                                        :       :       +-------+
-
-
-더 완벽한 설명을 위해, A 의 로드가 읽기 배리어 앞과 뒤에 있으면 어떻게 될지
-생각해 봅시다:
-
-	CPU 1			CPU 2
-	=======================	=======================
-		{ A = 0, B = 9 }
-	STORE A=1
-	<쓰기 배리어>
-	STORE B=2
-				LOAD B
-				LOAD A [first load of A]
-				<읽기 배리어>
-				LOAD A [second load of A]
-
-A 의 로드 두개가 모두 B 의 로드 뒤에 있지만, 서로 다른 값을 얻어올 수
-있습니다:
-
-	+-------+       :      :                :       :
-	|       |       +------+                +-------+
-	|       |------>| A=1  |------      --->| A->0  |
-	|       |       +------+      \         +-------+
-	| CPU 1 |   wwwwwwwwwwwwwwww   \    --->| B->9  |
-	|       |       +------+        |       +-------+
-	|       |------>| B=2  |---     |       :       :
-	|       |       +------+   \    |       :       :       +-------+
-	+-------+       :      :    \   |       +-------+       |       |
-	                             ---------->| B->2  |------>|       |
-	                                |       +-------+       | CPU 2 |
-	                                |       :       :       |       |
-	                                |       :       :       |       |
-	                                |       +-------+       |       |
-	                                |       | A->0  |------>| 1st   |
-	                                |       +-------+       |       |
-	  여기서 읽기 배리어는   ---->   \  rrrrrrrrrrrrrrrrr   |       |
-	  B 로의 스토어 전의              \     +-------+       |       |
-	  모든 결과를 CPU 2 에             ---->| A->1  |------>| 2nd   |
-	  보이도록 한다                         +-------+       |       |
-	                                        :       :       +-------+
-
-
-하지만 CPU 1 에서의 A 업데이트는 읽기 배리어가 완료되기 전에도 보일 수도
-있긴 합니다:
-
-	+-------+       :      :                :       :
-	|       |       +------+                +-------+
-	|       |------>| A=1  |------      --->| A->0  |
-	|       |       +------+      \         +-------+
-	| CPU 1 |   wwwwwwwwwwwwwwww   \    --->| B->9  |
-	|       |       +------+        |       +-------+
-	|       |------>| B=2  |---     |       :       :
-	|       |       +------+   \    |       :       :       +-------+
-	+-------+       :      :    \   |       +-------+       |       |
-	                             ---------->| B->2  |------>|       |
-	                                |       +-------+       | CPU 2 |
-	                                |       :       :       |       |
-	                                 \      :       :       |       |
-	                                  \     +-------+       |       |
-	                                   ---->| A->1  |------>| 1st   |
-	                                        +-------+       |       |
-	                                    rrrrrrrrrrrrrrrrr   |       |
-	                                        +-------+       |       |
-	                                        | A->1  |------>| 2nd   |
-	                                        +-------+       |       |
-	                                        :       :       +-------+
-
-
-여기서 보장되는 건, 만약 B 의 로드가 B == 2 라는 결과를 봤다면, A 에의 두번째
-로드는 항상 A == 1 을 보게 될 것이라는 겁니다.  A 에의 첫번째 로드에는 그런
-보장이 없습니다; A == 0 이거나 A == 1 이거나 둘 중 하나의 결과를 보게 될겁니다.
-
-
-읽기 메모리 배리어 VS 로드 예측
--------------------------------
-
-많은 CPU들이 로드를 예측적으로 (speculatively) 합니다: 어떤 데이터를 메모리에서
-로드해야 하게 될지 예측을 했다면, 해당 데이터를 로드하는 인스트럭션을 실제로는
-아직 만나지 않았더라도 다른 로드 작업이 없어 버스 (bus) 가 아무 일도 하고 있지
-않다면, 그 데이터를 로드합니다.  이후에 실제 로드 인스트럭션이 실행되면 CPU 가
-이미 그 값을 가지고 있기 때문에 그 로드 인스트럭션은 즉시 완료됩니다.
-
-해당 CPU 는 실제로는 그 값이 필요치 않았다는 사실이 나중에 드러날 수도 있는데 -
-해당 로드 인스트럭션이 브랜치로 우회되거나 했을 수 있겠죠 - , 그렇게 되면 앞서
-읽어둔 값을 버리거나 나중의 사용을 위해 캐시에 넣어둘 수 있습니다.
-
-다음을 생각해 봅시다:
-
-	CPU 1			CPU 2
-	=======================	=======================
-				LOAD B
-				DIVIDE		} 나누기 명령은 일반적으로
-				DIVIDE		} 긴 시간을 필요로 합니다
-				LOAD A
-
-는 이렇게 될 수 있습니다:
-
-	                                        :       :       +-------+
-	                                        +-------+       |       |
-	                                    --->| B->2  |------>|       |
-	                                        +-------+       | CPU 2 |
-	                                        :       :DIVIDE |       |
-	                                        +-------+       |       |
-	나누기 하느라 바쁜       --->       --->| A->0  |~~~~   |       |
-	CPU 는 A 의 LOAD 를                     +-------+   ~   |       |
-	예측해서 수행한다                       :       :   ~   |       |
-	                                        :       :DIVIDE |       |
-	                                        :       :   ~   |       |
-	나누기가 끝나면       --->     --->     :       :   ~-->|       |
-	CPU 는 해당 LOAD 를                     :       :       |       |
-	즉각 완료한다                           :       :       +-------+
-
-
-읽기 배리어나 데이터 의존성 배리어를 두번째 로드 직전에 놓는다면:
-
-	CPU 1			CPU 2
-	=======================	=======================
-				LOAD B
-				DIVIDE
-				DIVIDE
-				<읽기 배리어>
-				LOAD A
-
-예측으로 얻어진 값은 사용된 배리어의 타입에 따라서 해당 값이 옳은지 검토되게
-됩니다.  만약 해당 메모리 영역에 변화가 없었다면, 예측으로 얻어두었던 값이
-사용됩니다:
-
-	                                        :       :       +-------+
-	                                        +-------+       |       |
-	                                    --->| B->2  |------>|       |
-	                                        +-------+       | CPU 2 |
-	                                        :       :DIVIDE |       |
-	                                        +-------+       |       |
-	나누기 하느라 바쁜       --->       --->| A->0  |~~~~   |       |
-	CPU 는 A 의 LOAD 를                     +-------+   ~   |       |
-	예측한다                                :       :   ~   |       |
-	                                        :       :DIVIDE |       |
-	                                        :       :   ~   |       |
-	                                        :       :   ~   |       |
-	                                    rrrrrrrrrrrrrrrr~   |       |
-	                                        :       :   ~   |       |
-	                                        :       :   ~-->|       |
-	                                        :       :       |       |
-	                                        :       :       +-------+
-
-
-하지만 다른 CPU 에서 업데이트나 무효화가 있었다면, 그 예측은 무효화되고 그 값은
-다시 읽혀집니다:
-
-	                                        :       :       +-------+
-	                                        +-------+       |       |
-	                                    --->| B->2  |------>|       |
-	                                        +-------+       | CPU 2 |
-	                                        :       :DIVIDE |       |
-	                                        +-------+       |       |
-	나누기 하느라 바쁜       --->       --->| A->0  |~~~~   |       |
-	CPU 는 A 의 LOAD 를                     +-------+   ~   |       |
-	예측한다                                :       :   ~   |       |
-	                                        :       :DIVIDE |       |
-	                                        :       :   ~   |       |
-	                                        :       :   ~   |       |
-	                                    rrrrrrrrrrrrrrrrr   |       |
-	                                        +-------+       |       |
-	예측성 동작은 무효화 되고    --->   --->| A->1  |------>|       |
-	업데이트된 값이 다시 읽혀진다           +-------+       |       |
-	                                        :       :       +-------+
-
-
-이행성
-------
-
-이행성(transitivity)은 실제의 컴퓨터 시스템에서 항상 제공되지는 않는, 순서
-맞추기에 대한 상당히 직관적인 개념입니다.  다음의 예가 이행성을 보여줍니다:
-
-	CPU 1			CPU 2			CPU 3
-	=======================	=======================	=======================
-		{ X = 0, Y = 0 }
-	STORE X=1		LOAD X			STORE Y=1
-				<범용 배리어>		<범용 배리어>
-				LOAD Y			LOAD X
-
-CPU 2 의 X 로드가 1을 리턴했고 Y 로드가 0을 리턴했다고 해봅시다.  이는 CPU 2 의
-X 로드가 CPU 1 의 X 스토어 뒤에 이루어졌고 CPU 2 의 Y 로드는 CPU 3 의 Y 스토어
-전에 이루어졌음을 의미합니다.  그럼 "CPU 3 의 X 로드는 0을 리턴할 수 있나요?"
-
-CPU 2 의 X 로드는 CPU 1 의 스토어 후에 이루어졌으니, CPU 3 의 X 로드는 1을
-리턴하는게 자연스럽습니다.  이런 생각이 이행성의 한 예입니다: CPU A 에서 실행된
-로드가 CPU B 에서의 같은 변수에 대한 로드를 뒤따른다면, CPU A 의 로드는 CPU B
-의 로드가 내놓은 값과 같거나 그 후의 값을 내놓아야 합니다.
-
-리눅스 커널에서 범용 배리어의 사용은 이행성을 보장합니다.  따라서, 앞의 예에서
-CPU 2 의 X 로드가 1을, Y 로드는 0을 리턴했다면, CPU 3 의 X 로드는 반드시 1을
-리턴합니다.
-
-하지만, 읽기나 쓰기 배리어에 대해서는 이행성이 보장되지 -않습니다-.  예를 들어,
-앞의 예에서 CPU 2 의 범용 배리어가 아래처럼 읽기 배리어로 바뀐 경우를 생각해
-봅시다:
-
-	CPU 1			CPU 2			CPU 3
-	=======================	=======================	=======================
-		{ X = 0, Y = 0 }
-	STORE X=1		LOAD X			STORE Y=1
-				<읽기 배리어>		<범용 배리어>
-				LOAD Y			LOAD X
-
-이 코드는 이행성을 갖지 않습니다: 이 예에서는, CPU 2 의 X 로드가 1을
-리턴하고, Y 로드는 0을 리턴하지만 CPU 3 의 X 로드가 0을 리턴하는 것도 완전히
-합법적입니다.
-
-CPU 2 의 읽기 배리어가 자신의 읽기는 순서를 맞춰줘도, CPU 1 의 스토어와의
-순서를 맞춰준다고는 보장할 수 없다는게 핵심입니다.  따라서, CPU 1 과 CPU 2 가
-버퍼나 캐시를 공유하는 시스템에서 이 예제 코드가 실행된다면, CPU 2 는 CPU 1 이
-쓴 값에 좀 빨리 접근할 수 있을 것입니다.  따라서 CPU 1 과 CPU 2 의 접근으로
-조합된 순서를 모든 CPU 가 동의할 수 있도록 하기 위해 범용 배리어가 필요합니다.
-
-범용 배리어는 "글로벌 이행성"을 제공해서, 모든 CPU 들이 오퍼레이션들의 순서에
-동의하게 할 것입니다.  반면, release-acquire 조합은 "로컬 이행성" 만을
-제공해서, 해당 조합이 사용된 CPU 들만이 해당 액세스들의 조합된 순서에 동의함이
-보장됩니다.  예를 들어, 존경스런 Herman Hollerith 의 C 코드로 보면:
-
-	int u, v, x, y, z;
-
-	void cpu0(void)
-	{
-		r0 = smp_load_acquire(&x);
-		WRITE_ONCE(u, 1);
-		smp_store_release(&y, 1);
-	}
-
-	void cpu1(void)
-	{
-		r1 = smp_load_acquire(&y);
-		r4 = READ_ONCE(v);
-		r5 = READ_ONCE(u);
-		smp_store_release(&z, 1);
-	}
-
-	void cpu2(void)
-	{
-		r2 = smp_load_acquire(&z);
-		smp_store_release(&x, 1);
-	}
-
-	void cpu3(void)
-	{
-		WRITE_ONCE(v, 1);
-		smp_mb();
-		r3 = READ_ONCE(u);
-	}
-
-cpu0(), cpu1(), 그리고 cpu2() 는 smp_store_release()/smp_load_acquire() 쌍의
-연결을 통한 로컬 이행성에 동참하고 있으므로, 다음과 같은 결과는 나오지 않을
-겁니다:
-
-	r0 == 1 && r1 == 1 && r2 == 1
-
-더 나아가서, cpu0() 와 cpu1() 사이의 release-acquire 관계로 인해, cpu1() 은
-cpu0() 의 쓰기를 봐야만 하므로, 다음과 같은 결과도 없을 겁니다:
-
-	r1 == 1 && r5 == 0
-
-하지만, release-acquire 타동성은 동참한 CPU 들에만 적용되므로 cpu3() 에는
-적용되지 않습니다.  따라서, 다음과 같은 결과가 가능합니다:
-
-	r0 == 0 && r1 == 1 && r2 == 1 && r3 == 0 && r4 == 0
-
-비슷하게, 다음과 같은 결과도 가능합니다:
-
-	r0 == 0 && r1 == 1 && r2 == 1 && r3 == 0 && r4 == 0 && r5 == 1
-
-cpu0(), cpu1(), 그리고 cpu2() 는 그들의 읽기와 쓰기를 순서대로 보게 되지만,
-release-acquire 체인에 관여되지 않은 CPU 들은 그 순서에 이견을 가질 수
-있습니다.  이런 이견은 smp_load_acquire() 와 smp_store_release() 의 구현에
-사용되는 완화된 메모리 배리어 인스트럭션들은 항상 배리어 앞의 스토어들을 뒤의
-로드들에 앞세울 필요는 없다는 사실에서 기인합니다.  이 말은 cpu3() 는 cpu0() 의
-u 로의 스토어를 cpu1() 의 v 로부터의 로드 뒤에 일어난 것으로 볼 수 있다는
-뜻입니다, cpu0() 와 cpu1() 은 이 두 오퍼레이션이 의도된 순서대로 일어났음에
-모두 동의하는데도 말입니다.
-
-하지만, smp_load_acquire() 는 마술이 아님을 명심하시기 바랍니다.  구체적으로,
-이 함수는 단순히 순서 규칙을 지키며 인자로부터의 읽기를 수행합니다.  이것은
-어떤 특정한 값이 읽힐 것인지는 보장하지 -않습니다-.  따라서, 다음과 같은 결과도
-가능합니다:
-
-	r0 == 0 && r1 == 0 && r2 == 0 && r5 == 0
-
-이런 결과는 어떤 것도 재배치 되지 않는, 순차적 일관성을 가진 가상의
-시스템에서도 일어날 수 있음을 기억해 두시기 바랍니다.
-
-다시 말하지만, 당신의 코드가 글로벌 이행성을 필요로 한다면, 범용 배리어를
-사용하십시오.
-
-
-==================
-명시적 커널 배리어
-==================
-
-리눅스 커널은 서로 다른 단계에서 동작하는 다양한 배리어들을 가지고 있습니다:
-
-  (*) 컴파일러 배리어.
-
-  (*) CPU 메모리 배리어.
-
-  (*) MMIO 쓰기 배리어.
-
-
-컴파일러 배리어
----------------
-
-리눅스 커널은 컴파일러가 메모리 액세스를 재배치 하는 것을 막아주는 명시적인
-컴파일러 배리어를 가지고 있습니다:
-
-	barrier();
-
-이건 범용 배리어입니다 -- barrier() 의 읽기-읽기 나 쓰기-쓰기 변종은 없습니다.
-하지만, READ_ONCE() 와 WRITE_ONCE() 는 특정 액세스들에 대해서만 동작하는
-barrier() 의 완화된 형태로 볼 수 있습니다.
-
-barrier() 함수는 다음과 같은 효과를 갖습니다:
-
- (*) 컴파일러가 barrier() 뒤의 액세스들이 barrier() 앞의 액세스보다 앞으로
-     재배치되지 못하게 합니다.  예를 들어, 인터럽트 핸들러 코드와 인터럽트 당한
-     코드 사이의 통신을 신중히 하기 위해 사용될 수 있습니다.
-
- (*) 루프에서, 컴파일러가 루프 조건에 사용된 변수를 매 이터레이션마다
-     메모리에서 로드하지 않아도 되도록 최적화 하는걸 방지합니다.
-
-READ_ONCE() 와 WRITE_ONCE() 함수는 싱글 쓰레드 코드에서는 문제 없지만 동시성이
-있는 코드에서는 문제가 될 수 있는 모든 최적화를 막습니다.  이런 류의 최적화에
-대한 예를 몇가지 들어보면 다음과 같습니다:
-
- (*) 컴파일러는 같은 변수에 대한 로드와 스토어를 재배치 할 수 있고, 어떤
-     경우에는 CPU가 같은 변수로부터의 로드들을 재배치할 수도 있습니다.  이는
-     다음의 코드가:
-
-	a[0] = x;
-	a[1] = x;
-
-     x 의 예전 값이 a[1] 에, 새 값이 a[0] 에 있게 할 수 있다는 뜻입니다.
-     컴파일러와 CPU가 이런 일을 못하게 하려면 다음과 같이 해야 합니다:
-
-	a[0] = READ_ONCE(x);
-	a[1] = READ_ONCE(x);
-
-     즉, READ_ONCE() 와 WRITE_ONCE() 는 여러 CPU 에서 하나의 변수에 가해지는
-     액세스들에 캐시 일관성을 제공합니다.
-
- (*) 컴파일러는 같은 변수에 대한 연속적인 로드들을 병합할 수 있습니다.  그런
-     병합 작업으로 컴파일러는 다음의 코드를:
-
-	while (tmp = a)
-		do_something_with(tmp);
-
-     다음과 같이, 싱글 쓰레드 코드에서는 말이 되지만 개발자의 의도와 전혀 맞지
-     않는 방향으로 "최적화" 할 수 있습니다:
-
-	if (tmp = a)
-		for (;;)
-			do_something_with(tmp);
-
-     컴파일러가 이런 짓을 하지 못하게 하려면 READ_ONCE() 를 사용하세요:
-
-	while (tmp = READ_ONCE(a))
-		do_something_with(tmp);
-
- (*) 예컨대 레지스터 사용량이 많아 컴파일러가 모든 데이터를 레지스터에 담을 수
-     없는 경우, 컴파일러는 변수를 다시 로드할 수 있습니다.  따라서 컴파일러는
-     앞의 예에서 변수 'tmp' 사용을 최적화로 없애버릴 수 있습니다:
-
-	while (tmp = a)
-		do_something_with(tmp);
-
-     이 코드는 다음과 같이 싱글 쓰레드에서는 완벽하지만 동시성이 존재하는
-     경우엔 치명적인 코드로 바뀔 수 있습니다:
-
-	while (a)
-		do_something_with(a);
-
-     예를 들어, 최적화된 이 코드는 변수 a 가 다른 CPU 에 의해 "while" 문과
-     do_something_with() 호출 사이에 바뀌어 do_something_with() 에 0을 넘길
-     수도 있습니다.
-
-     이번에도, 컴파일러가 그런 짓을 하는걸 막기 위해 READ_ONCE() 를 사용하세요:
-
-	while (tmp = READ_ONCE(a))
-		do_something_with(tmp);
-
-     레지스터가 부족한 상황을 겪는 경우, 컴파일러는 tmp 를 스택에 저장해둘 수도
-     있습니다.  컴파일러가 변수를 다시 읽어들이는건 이렇게 저장해두고 후에 다시
-     읽어들이는데 드는 오버헤드 때문입니다.  그렇게 하는게 싱글 쓰레드
-     코드에서는 안전하므로, 안전하지 않은 경우에는 컴파일러에게 직접 알려줘야
-     합니다.
-
- (*) 컴파일러는 그 값이 무엇일지 알고 있다면 로드를 아예 안할 수도 있습니다.
-     예를 들어, 다음의 코드는 변수 'a' 의 값이 항상 0임을 증명할 수 있다면:
-
-	while (tmp = a)
-		do_something_with(tmp);
-
-     이렇게 최적화 되어버릴 수 있습니다:
-
-	do { } while (0);
-
-     이 변환은 싱글 쓰레드 코드에서는 도움이 되는데 로드와 브랜치를 제거했기
-     때문입니다.  문제는 컴파일러가 'a' 의 값을 업데이트 하는건 현재의 CPU 하나
-     뿐이라는 가정 위에서 증명을 했다는데 있습니다.  만약 변수 'a' 가 공유되어
-     있다면, 컴파일러의 증명은 틀린 것이 될겁니다.  컴파일러는 그 자신이
-     생각하는 것만큼 많은 것을 알고 있지 못함을 컴파일러에게 알리기 위해
-     READ_ONCE() 를 사용하세요:
-
-	while (tmp = READ_ONCE(a))
-		do_something_with(tmp);
-
-     하지만 컴파일러는 READ_ONCE() 뒤에 나오는 값에 대해서도 눈길을 두고 있음을
-     기억하세요.  예를 들어, 다음의 코드에서 MAX 는 전처리기 매크로로, 1의 값을
-     갖는다고 해봅시다:
-
-	while ((tmp = READ_ONCE(a)) % MAX)
-		do_something_with(tmp);
-
-     이렇게 되면 컴파일러는 MAX 를 가지고 수행되는 "%" 오퍼레이터의 결과가 항상
-     0이라는 것을 알게 되고, 컴파일러가 코드를 실질적으로는 존재하지 않는
-     것처럼 최적화 하는 것이 허용되어 버립니다.  ('a' 변수의 로드는 여전히
-     행해질 겁니다.)
-
- (*) 비슷하게, 컴파일러는 변수가 저장하려 하는 값을 이미 가지고 있다는 것을
-     알면 스토어 자체를 제거할 수 있습니다.  이번에도, 컴파일러는 현재의 CPU
-     만이 그 변수에 값을 쓰는 오로지 하나의 존재라고 생각하여 공유된 변수에
-     대해서는 잘못된 일을 하게 됩니다.  예를 들어, 다음과 같은 경우가 있을 수
-     있습니다:
-
-	a = 0;
-	... 변수 a 에 스토어를 하지 않는 코드 ...
-	a = 0;
-
-     컴파일러는 변수 'a' 의 값은 이미 0이라는 것을 알고, 따라서 두번째 스토어를
-     삭제할 겁니다.  만약 다른 CPU 가 그 사이 변수 'a' 에 다른 값을 썼다면
-     황당한 결과가 나올 겁니다.
-
-     컴파일러가 그런 잘못된 추측을 하지 않도록 WRITE_ONCE() 를 사용하세요:
-
-	WRITE_ONCE(a, 0);
-	... 변수 a 에 스토어를 하지 않는 코드 ...
-	WRITE_ONCE(a, 0);
-
- (*) 컴파일러는 하지 말라고 하지 않으면 메모리 액세스들을 재배치 할 수
-     있습니다.  예를 들어, 다음의 프로세스 레벨 코드와 인터럽트 핸들러 사이의
-     상호작용을 생각해 봅시다:
-
-	void process_level(void)
-	{
-		msg = get_message();
-		flag = true;
-	}
-
-	void interrupt_handler(void)
-	{
-		if (flag)
-			process_message(msg);
-	}
-
-     이 코드에는 컴파일러가 process_level() 을 다음과 같이 변환하는 것을 막을
-     수단이 없고, 이런 변환은 싱글쓰레드에서라면 실제로 훌륭한 선택일 수
-     있습니다:
-
-	void process_level(void)
-	{
-		flag = true;
-		msg = get_message();
-	}
-
-     이 두개의 문장 사이에 인터럽트가 발생한다면, interrupt_handler() 는 의미를
-     알 수 없는 메세지를 받을 수도 있습니다.  이걸 막기 위해 다음과 같이
-     WRITE_ONCE() 를 사용하세요:
-
-	void process_level(void)
-	{
-		WRITE_ONCE(msg, get_message());
-		WRITE_ONCE(flag, true);
-	}
-
-	void interrupt_handler(void)
-	{
-		if (READ_ONCE(flag))
-			process_message(READ_ONCE(msg));
-	}
-
-     interrupt_handler() 안에서도 중첩된 인터럽트나 NMI 와 같이 인터럽트 핸들러
-     역시 'flag' 와 'msg' 에 접근하는 또다른 무언가에 인터럽트 될 수 있다면
-     READ_ONCE() 와 WRITE_ONCE() 를 사용해야 함을 기억해 두세요.  만약 그런
-     가능성이 없다면, interrupt_handler() 안에서는 문서화 목적이 아니라면
-     READ_ONCE() 와 WRITE_ONCE() 는 필요치 않습니다.  (근래의 리눅스 커널에서
-     중첩된 인터럽트는 보통 잘 일어나지 않음도 기억해 두세요, 실제로, 어떤
-     인터럽트 핸들러가 인터럽트가 활성화된 채로 리턴하면 WARN_ONCE() 가
-     실행됩니다.)
-
-     컴파일러는 READ_ONCE() 와 WRITE_ONCE() 뒤의 READ_ONCE() 나 WRITE_ONCE(),
-     barrier(), 또는 비슷한 것들을 담고 있지 않은 코드를 움직일 수 있을 것으로
-     가정되어야 합니다.
-
-     이 효과는 barrier() 를 통해서도 만들 수 있지만, READ_ONCE() 와
-     WRITE_ONCE() 가 좀 더 안목 높은 선택입니다: READ_ONCE() 와 WRITE_ONCE()는
-     컴파일러에 주어진 메모리 영역에 대해서만 최적화 가능성을 포기하도록
-     하지만, barrier() 는 컴파일러가 지금까지 기계의 레지스터에 캐시해 놓은
-     모든 메모리 영역의 값을 버려야 하게 하기 때문입니다.  물론, 컴파일러는
-     READ_ONCE() 와 WRITE_ONCE() 가 일어난 순서도 지켜줍니다, CPU 는 당연히
-     그 순서를 지킬 의무가 없지만요.
-
- (*) 컴파일러는 다음의 예에서와 같이 변수에의 스토어를 날조해낼 수도 있습니다:
-
-	if (a)
-		b = a;
-	else
-		b = 42;
-
-     컴파일러는 아래와 같은 최적화로 브랜치를 줄일 겁니다:
-
-	b = 42;
-	if (a)
-		b = a;
-
-     싱글 쓰레드 코드에서 이 최적화는 안전할 뿐 아니라 브랜치 갯수를
-     줄여줍니다.  하지만 안타깝게도, 동시성이 있는 코드에서는 이 최적화는 다른
-     CPU 가 'b' 를 로드할 때, -- 'a' 가 0이 아닌데도 -- 가짜인 값, 42를 보게
-     되는 경우를 가능하게 합니다.  이걸 방지하기 위해 WRITE_ONCE() 를
-     사용하세요:
-
-	if (a)
-		WRITE_ONCE(b, a);
-	else
-		WRITE_ONCE(b, 42);
-
-     컴파일러는 로드를 만들어낼 수도 있습니다.  일반적으로는 문제를 일으키지
-     않지만, 캐시 라인 바운싱을 일으켜 성능과 확장성을 떨어뜨릴 수 있습니다.
-     날조된 로드를 막기 위해선 READ_ONCE() 를 사용하세요.
-
- (*) 정렬된 메모리 주소에 위치한, 한번의 메모리 참조 인스트럭션으로 액세스
-     가능한 크기의 데이터는 하나의 큰 액세스가 여러개의 작은 액세스들로
-     대체되는 "로드 티어링(load tearing)" 과 "스토어 티어링(store tearing)" 을
-     방지합니다.  예를 들어, 주어진 아키텍쳐가 7-bit imeediate field 를 갖는
-     16-bit 스토어 인스트럭션을 제공한다면, 컴파일러는 다음의 32-bit 스토어를
-     구현하는데에 두개의 16-bit store-immediate 명령을 사용하려 할겁니다:
-
-	p = 0x00010002;
-
-     스토어 할 상수를 만들고 그 값을 스토어 하기 위해 두개가 넘는 인스트럭션을
-     사용하게 되는, 이런 종류의 최적화를 GCC 는 실제로 함을 부디 알아 두십시오.
-     이 최적화는 싱글 쓰레드 코드에서는 성공적인 최적화 입니다.  실제로, 근래에
-     발생한 (그리고 고쳐진) 버그는 GCC 가 volatile 스토어에 비정상적으로 이
-     최적화를 사용하게 했습니다.  그런 버그가 없다면, 다음의 예에서
-     WRITE_ONCE() 의 사용은 스토어 티어링을 방지합니다:
-
-	WRITE_ONCE(p, 0x00010002);
-
-     Packed 구조체의 사용 역시 다음의 예처럼  로드 / 스토어 티어링을 유발할 수
-     있습니다:
-
-	struct __attribute__((__packed__)) foo {
-		short a;
-		int b;
-		short c;
-	};
-	struct foo foo1, foo2;
-	...
-
-	foo2.a = foo1.a;
-	foo2.b = foo1.b;
-	foo2.c = foo1.c;
-
-     READ_ONCE() 나 WRITE_ONCE() 도 없고 volatile 마킹도 없기 때문에,
-     컴파일러는 이 세개의 대입문을 두개의 32-bit 로드와 두개의 32-bit 스토어로
-     변환할 수 있습니다.  이는 'foo1.b' 의 값의 로드 티어링과 'foo2.b' 의
-     스토어 티어링을 초래할 겁니다.  이 예에서도 READ_ONCE() 와 WRITE_ONCE()
-     가 티어링을 막을 수 있습니다:
-
-	foo2.a = foo1.a;
-	WRITE_ONCE(foo2.b, READ_ONCE(foo1.b));
-	foo2.c = foo1.c;
-
-그렇지만, volatile 로 마크된 변수에 대해서는 READ_ONCE() 와 WRITE_ONCE() 가
-필요치 않습니다.  예를 들어, 'jiffies' 는 volatile 로 마크되어 있기 때문에,
-READ_ONCE(jiffies) 라고 할 필요가 없습니다.  READ_ONCE() 와 WRITE_ONCE() 가
-실은 volatile 캐스팅으로 구현되어 있어서 인자가 이미 volatile 로 마크되어
-있다면 또다른 효과를 내지는 않기 때문입니다.
-
-이 컴파일러 배리어들은 CPU 에는 직접적 효과를 전혀 만들지 않기 때문에, 결국은
-재배치가 일어날 수도 있음을 부디 기억해 두십시오.
-
-
-CPU 메모리 배리어
------------------
-
-리눅스 커널은 다음의 여덟개 기본 CPU 메모리 배리어를 가지고 있습니다:
-
-	TYPE		MANDATORY		SMP CONDITIONAL
-	===============	=======================	===========================
-	범용		mb()			smp_mb()
-	쓰기		wmb()			smp_wmb()
-	읽기		rmb()			smp_rmb()
-	데이터 의존성	read_barrier_depends()	smp_read_barrier_depends()
-
-
-데이터 의존성 배리어를 제외한 모든 메모리 배리어는 컴파일러 배리어를
-포함합니다.  데이터 의존성은 컴파일러에의 추가적인 순서 보장을 포함하지
-않습니다.
-
-방백: 데이터 의존성이 있는 경우, 컴파일러는 해당 로드를 올바른 순서로 일으킬
-것으로 (예: `a[b]` 는 a[b] 를 로드 하기 전에 b 의 값을 먼저 로드한다)
-기대되지만, C 언어 사양에는 컴파일러가 b 의 값을 추측 (예: 1 과 같음) 해서
-b  로드 전에 a 로드를 하는 코드 (예: tmp = a[1]; if (b != 1) tmp = a[b]; ) 를
-만들지 않아야 한다는 내용 같은 건 없습니다.  또한 컴파일러는 a[b] 를 로드한
-후에 b 를 또다시 로드할 수도 있어서, a[b] 보다 최신 버전의 b 값을 가질 수도
-있습니다.  이런 문제들의 해결책에 대한 의견 일치는 아직 없습니다만, 일단
-READ_ONCE() 매크로부터 보기 시작하는게 좋은 시작이 될겁니다.
-
-SMP 메모리 배리어들은 유니프로세서로 컴파일된 시스템에서는 컴파일러 배리어로
-바뀌는데, 하나의 CPU 는 스스로 일관성을 유지하고, 겹치는 액세스들 역시 올바른
-순서로 행해질 것으로 생각되기 때문입니다.  하지만, 아래의 "Virtual Machine
-Guests" 서브섹션을 참고하십시오.
-
-[!] SMP 시스템에서 공유메모리로의 접근들을 순서 세워야 할 때, SMP 메모리
-배리어는 _반드시_ 사용되어야 함을 기억하세요, 그대신 락을 사용하는 것으로도
-충분하긴 하지만 말이죠.
-
-Mandatory 배리어들은 SMP 시스템에서도 UP 시스템에서도 SMP 효과만 통제하기에는
-불필요한 오버헤드를 갖기 때문에 SMP 효과만 통제하면 되는 곳에는 사용되지 않아야
-합니다.  하지만, 느슨한 순서 규칙의 메모리 I/O 윈도우를 통한 MMIO 의 효과를
-통제할 때에는 mandatory 배리어들이 사용될 수 있습니다.  이 배리어들은
-컴파일러와 CPU 모두 재배치를 못하도록 함으로써 메모리 오퍼레이션들이 디바이스에
-보여지는 순서에도 영향을 주기 때문에, SMP 가 아닌 시스템이라 할지라도 필요할 수
-있습니다.
-
-
-일부 고급 배리어 함수들도 있습니다:
-
- (*) smp_store_mb(var, value)
-
-     이 함수는 특정 변수에 특정 값을 대입하고 범용 메모리 배리어를 칩니다.
-     UP 컴파일에서는 컴파일러 배리어보다 더한 것을 친다고는 보장되지 않습니다.
-
-
- (*) smp_mb__before_atomic();
- (*) smp_mb__after_atomic();
-
-     이것들은 값을 리턴하지 않는 (더하기, 빼기, 증가, 감소와 같은) 어토믹
-     함수들을 위한, 특히 그것들이 레퍼런스 카운팅에 사용될 때를 위한
-     함수들입니다.  이 함수들은 메모리 배리어를 내포하고 있지는 않습니다.
-
-     이것들은 값을 리턴하지 않으며 어토믹한 (set_bit 과 clear_bit 같은) 비트
-     연산에도 사용될 수 있습니다.
-
-     한 예로, 객체 하나를 무효한 것으로 표시하고 그 객체의 레퍼런스 카운트를
-     감소시키는 다음 코드를 보세요:
-
-	obj->dead = 1;
-	smp_mb__before_atomic();
-	atomic_dec(&obj->ref_count);
-
-     이 코드는 객체의 업데이트된 death 마크가 레퍼런스 카운터 감소 동작
-     *전에* 보일 것을 보장합니다.
-
-     더 많은 정보를 위해선 Documentation/atomic_ops.txt 문서를 참고하세요.
-     어디서 이것들을 사용해야 할지 궁금하다면 "어토믹 오퍼레이션" 서브섹션을
-     참고하세요.
-
-
- (*) lockless_dereference();
-
-     이 함수는 smp_read_barrier_depends() 데이터 의존성 배리어를 사용하는
-     포인터 읽어오기 래퍼(wrapper) 함수로 생각될 수 있습니다.
-
-     객체의 라이프타임이 RCU 외의 메커니즘으로 관리된다는 점을 제외하면
-     rcu_dereference() 와도 유사한데, 예를 들면 객체가 시스템이 꺼질 때에만
-     제거되는 경우 등입니다.  또한, lockless_dereference() 은 RCU 와 함께
-     사용될수도, RCU 없이 사용될 수도 있는 일부 데이터 구조에 사용되고
-     있습니다.
-
-
- (*) dma_wmb();
- (*) dma_rmb();
-
-     이것들은 CPU 와 DMA 가능한 디바이스에서 모두 액세스 가능한 공유 메모리의
-     읽기, 쓰기 작업들의 순서를 보장하기 위해 consistent memory 에서 사용하기
-     위한 것들입니다.
-
-     예를 들어, 디바이스와 메모리를 공유하며, 디스크립터 상태 값을 사용해
-     디스크립터가 디바이스에 속해 있는지 아니면 CPU 에 속해 있는지 표시하고,
-     공지용 초인종(doorbell) 을 사용해 업데이트된 디스크립터가 디바이스에 사용
-     가능해졌음을 공지하는 디바이스 드라이버를 생각해 봅시다:
-
-	if (desc->status != DEVICE_OWN) {
-		/* 디스크립터를 소유하기 전에는 데이터를 읽지 않음 */
-		dma_rmb();
-
-		/* 데이터를 읽고 씀 */
-		read_data = desc->data;
-		desc->data = write_data;
-
-		/* 상태 업데이트 전 수정사항을 반영 */
-		dma_wmb();
-
-		/* 소유권을 수정 */
-		desc->status = DEVICE_OWN;
-
-		/* MMIO 를 통해 디바이스에 공지를 하기 전에 메모리를 동기화 */
-		wmb();
-
-		/* 업데이트된 디스크립터의 디바이스에 공지 */
-		writel(DESC_NOTIFY, doorbell);
-	}
-
-     dma_rmb() 는 디스크립터로부터 데이터를 읽어오기 전에 디바이스가 소유권을
-     내놓았음을 보장하게 하고, dma_wmb() 는 디바이스가 자신이 소유권을 다시
-     가졌음을 보기 전에 디스크립터에 데이터가 쓰였음을 보장합니다.  wmb() 는
-     캐시 일관성이 없는 (cache incoherent) MMIO 영역에 쓰기를 시도하기 전에
-     캐시 일관성이 있는 메모리 (cache coherent memory) 쓰기가 완료되었음을
-     보장해주기 위해 필요합니다.
-
-     consistent memory 에 대한 자세한 내용을 위해선 Documentation/DMA-API.txt
-     문서를 참고하세요.
-
-
-MMIO 쓰기 배리어
-----------------
-
-리눅스 커널은 또한 memory-mapped I/O 쓰기를 위한 특별한 배리어도 가지고
-있습니다:
-
-	mmiowb();
-
-이것은 mandatory 쓰기 배리어의 변종으로, 완화된 순서 규칙의 I/O 영역에으로의
-쓰기가 부분적으로 순서를 맞추도록 해줍니다.  이 함수는 CPU->하드웨어 사이를
-넘어서 실제 하드웨어에까지 일부 수준의 영향을 끼칩니다.
-
-더 많은 정보를 위해선 "Acquire vs I/O 액세스" 서브섹션을 참고하세요.
-
-
-=========================
-암묵적 커널 메모리 배리어
-=========================
-
-리눅스 커널의 일부 함수들은 메모리 배리어를 내장하고 있는데, 락(lock)과
-스케쥴링 관련 함수들이 대부분입니다.
-
-여기선 _최소한의_ 보장을 설명합니다; 특정 아키텍쳐에서는 이 설명보다 더 많은
-보장을 제공할 수도 있습니다만 해당 아키텍쳐에 종속적인 코드 외의 부분에서는
-그런 보장을 기대해선 안될겁니다.
-
-
-락 ACQUISITION 함수
--------------------
-
-리눅스 커널은 다양한 락 구성체를 가지고 있습니다:
-
- (*) 스핀 락
- (*) R/W 스핀 락
- (*) 뮤텍스
- (*) 세마포어
- (*) R/W 세마포어
-
-각 구성체마다 모든 경우에 "ACQUIRE" 오퍼레이션과 "RELEASE" 오퍼레이션의 변종이
-존재합니다.  이 오퍼레이션들은 모두 적절한 배리어를 내포하고 있습니다:
-
- (1) ACQUIRE 오퍼레이션의 영향:
-
-     ACQUIRE 뒤에서 요청된 메모리 오퍼레이션은 ACQUIRE 오퍼레이션이 완료된
-     뒤에 완료됩니다.
-
-     ACQUIRE 앞에서 요청된 메모리 오퍼레이션은 ACQUIRE 오퍼레이션이 완료된 후에
-     완료될 수 있습니다.  smp_mb__before_spinlock() 뒤에 ACQUIRE 가 실행되는
-     코드 블록은 블록 앞의 스토어를 블록 뒤의 로드와 스토어에 대해 순서
-     맞춥니다.  이건 smp_mb() 보다 완화된 것임을 기억하세요!  많은 아키텍쳐에서
-     smp_mb__before_spinlock() 은 사실 아무일도 하지 않습니다.
-
- (2) RELEASE 오퍼레이션의 영향:
-
-     RELEASE 앞에서 요청된 메모리 오퍼레이션은 RELEASE 오퍼레이션이 완료되기
-     전에 완료됩니다.
-
-     RELEASE 뒤에서 요청된 메모리 오퍼레이션은 RELEASE 오퍼레이션 완료 전에
-     완료될 수 있습니다.
-
- (3) ACQUIRE vs ACQUIRE 영향:
-
-     어떤 ACQUIRE 오퍼레이션보다 앞에서 요청된 모든 ACQUIRE 오퍼레이션은 그
-     ACQUIRE 오퍼레이션 전에 완료됩니다.
-
- (4) ACQUIRE vs RELEASE implication:
-
-     어떤 RELEASE 오퍼레이션보다 앞서 요청된 ACQUIRE 오퍼레이션은 그 RELEASE
-     오퍼레이션보다 먼저 완료됩니다.
-
- (5) 실패한 조건적 ACQUIRE 영향:
-
-     ACQUIRE 오퍼레이션의 일부 락(lock) 변종은 락이 곧바로 획득하기에는
-     불가능한 상태이거나 락이 획득 가능해지도록 기다리는 도중 시그널을 받거나
-     해서 실패할 수 있습니다.  실패한 락은 어떤 배리어도 내포하지 않습니다.
-
-[!] 참고: 락 ACQUIRE 와 RELEASE 가 단방향 배리어여서 나타나는 현상 중 하나는
-크리티컬 섹션 바깥의 인스트럭션의 영향이 크리티컬 섹션 내부로도 들어올 수
-있다는 것입니다.
-
-RELEASE 후에 요청되는 ACQUIRE 는 전체 메모리 배리어라 여겨지면 안되는데,
-ACQUIRE 앞의 액세스가 ACQUIRE 후에 수행될 수 있고, RELEASE 후의 액세스가
-RELEASE 전에 수행될 수도 있으며, 그 두개의 액세스가 서로를 지나칠 수도 있기
-때문입니다:
-
-	*A = a;
-	ACQUIRE M
-	RELEASE M
-	*B = b;
-
-는 다음과 같이 될 수도 있습니다:
-
-	ACQUIRE M, STORE *B, STORE *A, RELEASE M
-
-ACQUIRE 와 RELEASE 가 락 획득과 해제라면, 그리고 락의 ACQUIRE 와 RELEASE 가
-같은 락 변수에 대한 것이라면, 해당 락을 쥐고 있지 않은 다른 CPU 의 시야에는
-이와 같은 재배치가 일어나는 것으로 보일 수 있습니다.  요약하자면, ACQUIRE 에
-이어 RELEASE 오퍼레이션을 순차적으로 실행하는 행위가 전체 메모리 배리어로
-생각되어선 -안됩니다-.
-
-비슷하게, 앞의 반대 케이스인 RELEASE 와 ACQUIRE 두개 오퍼레이션의 순차적 실행
-역시 전체 메모리 배리어를 내포하지 않습니다.  따라서, RELEASE, ACQUIRE 로
-규정되는 크리티컬 섹션의 CPU 수행은 RELEASE 와 ACQUIRE 를 가로지를 수 있으므로,
-다음과 같은 코드는:
-
-	*A = a;
-	RELEASE M
-	ACQUIRE N
-	*B = b;
-
-다음과 같이 수행될 수 있습니다:
-
-	ACQUIRE N, STORE *B, STORE *A, RELEASE M
-
-이런 재배치는 데드락을 일으킬 수도 있을 것처럼 보일 수 있습니다.  하지만, 그런
-데드락의 조짐이 있다면 RELEASE 는 단순히 완료될 것이므로 데드락은 존재할 수
-없습니다.
-
-	이게 어떻게 올바른 동작을 할 수 있을까요?
-
-	우리가 이야기 하고 있는건 재배치를 하는 CPU 에 대한 이야기이지,
-	컴파일러에 대한 것이 아니란 점이 핵심입니다.  컴파일러 (또는, 개발자)
-	가 오퍼레이션들을 이렇게 재배치하면, 데드락이 일어날 수 -있습-니다.
-
-	하지만 CPU 가 오퍼레이션들을 재배치 했다는걸 생각해 보세요.  이 예에서,
-	어셈블리 코드 상으로는 언락이 락을 앞서게 되어 있습니다.  CPU 가 이를
-	재배치해서 뒤의 락 오퍼레이션을 먼저 실행하게 됩니다.  만약 데드락이
-	존재한다면, 이 락 오퍼레이션은 그저 스핀을 하며 계속해서 락을
-	시도합니다 (또는, 한참 후에겠지만, 잠듭니다).  CPU 는 언젠가는
-	(어셈블리 코드에서는 락을 앞서는) 언락 오퍼레이션을 실행하는데, 이 언락
-	오퍼레이션이 잠재적 데드락을 해결하고, 락 오퍼레이션도 뒤이어 성공하게
-	됩니다.
-
-	하지만 만약 락이 잠을 자는 타입이었다면요?  그런 경우에 코드는
-	스케쥴러로 들어가려 할 거고, 여기서 결국은 메모리 배리어를 만나게
-	되는데, 이 메모리 배리어는 앞의 언락 오퍼레이션이 완료되도록 만들고,
-	데드락은 이번에도 해결됩니다.  잠을 자는 행위와 언락 사이의 경주 상황
-	(race) 도 있을 수 있겠습니다만, 락 관련 기능들은 그런 경주 상황을 모든
-	경우에 제대로 해결할 수 있어야 합니다.
-
-락과 세마포어는 UP 컴파일된 시스템에서의 순서에 대해 보장을 하지 않기 때문에,
-그런 상황에서 인터럽트 비활성화 오퍼레이션과 함께가 아니라면 어떤 일에도 - 특히
-I/O 액세스와 관련해서는 - 제대로 사용될 수 없을 겁니다.
-
-"CPU 간 ACQUIRING 배리어 효과" 섹션도 참고하시기 바랍니다.
-
-
-예를 들어, 다음과 같은 코드를 생각해 봅시다:
-
-	*A = a;
-	*B = b;
-	ACQUIRE
-	*C = c;
-	*D = d;
-	RELEASE
-	*E = e;
-	*F = f;
-
-여기선 다음의 이벤트 시퀀스가 생길 수 있습니다:
-
-	ACQUIRE, {*F,*A}, *E, {*C,*D}, *B, RELEASE
-
-	[+] {*F,*A} 는 조합된 액세스를 의미합니다.
-
-하지만 다음과 같은 건 불가능하죠:
-
-	{*F,*A}, *B,	ACQUIRE, *C, *D,	RELEASE, *E
-	*A, *B, *C,	ACQUIRE, *D,		RELEASE, *E, *F
-	*A, *B,		ACQUIRE, *C,		RELEASE, *D, *E, *F
-	*B,		ACQUIRE, *C, *D,	RELEASE, {*F,*A}, *E
-
-
-
-인터럽트 비활성화 함수
-----------------------
-
-인터럽트를 비활성화 하는 함수 (ACQUIRE 와 동일) 와 인터럽트를 활성화 하는 함수
-(RELEASE 와 동일) 는 컴파일러 배리어처럼만 동작합니다.  따라서, 별도의 메모리
-배리어나 I/O 배리어가 필요한 상황이라면 그 배리어들은 인터럽트 비활성화 함수
-외의 방법으로 제공되어야만 합니다.
-
-
-슬립과 웨이크업 함수
---------------------
-
-글로벌 데이터에 표시된 이벤트에 의해 프로세스를 잠에 빠트리는 것과 깨우는 것은
-해당 이벤트를 기다리는 태스크의 태스크 상태와 그 이벤트를 알리기 위해 사용되는
-글로벌 데이터, 두 데이터간의 상호작용으로 볼 수 있습니다.  이것이 옳은 순서대로
-일어남을 분명히 하기 위해, 프로세스를 잠에 들게 하는 기능과 깨우는 기능은
-몇가지 배리어를 내포합니다.
-
-먼저, 잠을 재우는 쪽은 일반적으로 다음과 같은 이벤트 시퀀스를 따릅니다:
-
-	for (;;) {
-		set_current_state(TASK_UNINTERRUPTIBLE);
-		if (event_indicated)
-			break;
-		schedule();
-	}
-
-set_current_state() 에 의해, 태스크 상태가 바뀐 후 범용 메모리 배리어가
-자동으로 삽입됩니다:
-
-	CPU 1
-	===============================
-	set_current_state();
-	  smp_store_mb();
-	    STORE current->state
-	    <범용 배리어>
-	LOAD event_indicated
-
-set_current_state() 는 다음의 것들로 감싸질 수도 있습니다:
-
-	prepare_to_wait();
-	prepare_to_wait_exclusive();
-
-이것들 역시 상태를 설정한 후 범용 메모리 배리어를 삽입합니다.
-앞의 전체 시퀀스는 다음과 같은 함수들로 한번에 수행 가능한데, 이것들은 모두
-올바른 장소에 메모리 배리어를 삽입합니다:
-
-	wait_event();
-	wait_event_interruptible();
-	wait_event_interruptible_exclusive();
-	wait_event_interruptible_timeout();
-	wait_event_killable();
-	wait_event_timeout();
-	wait_on_bit();
-	wait_on_bit_lock();
-
-
-두번째로, 깨우기를 수행하는 코드는 일반적으로 다음과 같을 겁니다:
-
-	event_indicated = 1;
-	wake_up(&event_wait_queue);
-
-또는:
-
-	event_indicated = 1;
-	wake_up_process(event_daemon);
-
-wake_up() 류에 의해 쓰기 메모리 배리어가 내포됩니다.  만약 그것들이 뭔가를
-깨운다면요.  이 배리어는 태스크 상태가 지워지기 전에 수행되므로, 이벤트를
-알리기 위한 STORE 와 태스크 상태를 TASK_RUNNING 으로 설정하는 STORE 사이에
-위치하게 됩니다.
-
-	CPU 1				CPU 2
-	===============================	===============================
-	set_current_state();		STORE event_indicated
-	  smp_store_mb();		wake_up();
-	    STORE current->state	  <쓰기 배리어>
-	    <범용 배리어>		  STORE current->state
-	LOAD event_indicated
-
-한번더 말합니다만, 이 쓰기 메모리 배리어는 이 코드가 정말로 뭔가를 깨울 때에만
-실행됩니다.  이걸 설명하기 위해, X 와 Y 는 모두 0 으로 초기화 되어 있다는 가정
-하에 아래의 이벤트 시퀀스를 생각해 봅시다:
-
-	CPU 1				CPU 2
-	===============================	===============================
-	X = 1;				STORE event_indicated
-	smp_mb();			wake_up();
-	Y = 1;				wait_event(wq, Y == 1);
-	wake_up();			  load from Y sees 1, no memory barrier
-					load from X might see 0
-
-위 예제에서의 경우와 달리 깨우기가 정말로 행해졌다면, CPU 2 의 X 로드는 1 을
-본다고 보장될 수 있을 겁니다.
-
-사용 가능한 깨우기류 함수들로 다음과 같은 것들이 있습니다:
-
-	complete();
-	wake_up();
-	wake_up_all();
-	wake_up_bit();
-	wake_up_interruptible();
-	wake_up_interruptible_all();
-	wake_up_interruptible_nr();
-	wake_up_interruptible_poll();
-	wake_up_interruptible_sync();
-	wake_up_interruptible_sync_poll();
-	wake_up_locked();
-	wake_up_locked_poll();
-	wake_up_nr();
-	wake_up_poll();
-	wake_up_process();
-
-
-[!] 잠재우는 코드와 깨우는 코드에 내포되는 메모리 배리어들은 깨우기 전에
-이루어진 스토어를 잠재우는 코드가 set_current_state() 를 호출한 후에 행하는
-로드에 대해 순서를 맞추지 _않는다는_ 점을 기억하세요.  예를 들어, 잠재우는
-코드가 다음과 같고:
-
-	set_current_state(TASK_INTERRUPTIBLE);
-	if (event_indicated)
-		break;
-	__set_current_state(TASK_RUNNING);
-	do_something(my_data);
-
-깨우는 코드는 다음과 같다면:
-
-	my_data = value;
-	event_indicated = 1;
-	wake_up(&event_wait_queue);
-
-event_indecated 에의 변경이 잠재우는 코드에게 my_data 에의 변경 후에 이루어진
-것으로 인지될 것이라는 보장이 없습니다.  이런 경우에는 양쪽 코드 모두 각각의
-데이터 액세스 사이에 메모리 배리어를 직접 쳐야 합니다.  따라서 앞의 재우는
-코드는 다음과 같이:
-
-	set_current_state(TASK_INTERRUPTIBLE);
-	if (event_indicated) {
-		smp_rmb();
-		do_something(my_data);
-	}
-
-그리고 깨우는 코드는 다음과 같이 되어야 합니다:
-
-	my_data = value;
-	smp_wmb();
-	event_indicated = 1;
-	wake_up(&event_wait_queue);
-
-
-그외의 함수들
--------------
-
-그외의 배리어를 내포하는 함수들은 다음과 같습니다:
-
- (*) schedule() 과 그 유사한 것들이 완전한 메모리 배리어를 내포합니다.
-
-
-==============================
-CPU 간 ACQUIRING 배리어의 효과
-==============================
-
-SMP 시스템에서의 락 기능들은 더욱 강력한 형태의 배리어를 제공합니다: 이
-배리어는 동일한 락을 사용하는 다른 CPU 들의 메모리 액세스 순서에도 영향을
-끼칩니다.
-
-
-ACQUIRE VS 메모리 액세스
-------------------------
-
-다음의 예를 생각해 봅시다: 시스템은 두개의 스핀락 (M) 과 (Q), 그리고 세개의 CPU
-를 가지고 있습니다; 여기에 다음의 이벤트 시퀀스가 발생합니다:
-
-	CPU 1				CPU 2
-	===============================	===============================
-	WRITE_ONCE(*A, a);		WRITE_ONCE(*E, e);
-	ACQUIRE M			ACQUIRE Q
-	WRITE_ONCE(*B, b);		WRITE_ONCE(*F, f);
-	WRITE_ONCE(*C, c);		WRITE_ONCE(*G, g);
-	RELEASE M			RELEASE Q
-	WRITE_ONCE(*D, d);		WRITE_ONCE(*H, h);
-
-*A 로의 액세스부터 *H 로의 액세스까지가 어떤 순서로 CPU 3 에게 보여질지에
-대해서는 각 CPU 에서의 락 사용에 의해 내포되어 있는 제약을 제외하고는 어떤
-보장도 존재하지 않습니다.  예를 들어, CPU 3 에게 다음과 같은 순서로 보여지는
-것이 가능합니다:
-
-	*E, ACQUIRE M, ACQUIRE Q, *G, *C, *F, *A, *B, RELEASE Q, *D, *H, RELEASE M
-
-하지만 다음과 같이 보이지는 않을 겁니다:
-
-	*B, *C or *D preceding ACQUIRE M
-	*A, *B or *C following RELEASE M
-	*F, *G or *H preceding ACQUIRE Q
-	*E, *F or *G following RELEASE Q
-
-
-
-ACQUIRE VS I/O 액세스
-----------------------
-
-특정한 (특히 NUMA 가 관련된) 환경 하에서 두개의 CPU 에서 동일한 스핀락으로
-보호되는 두개의 크리티컬 섹션 안의 I/O 액세스는 PCI 브릿지에 겹쳐진 I/O
-액세스로 보일 수 있는데, PCI 브릿지는 캐시 일관성 프로토콜과 합을 맞춰야 할
-의무가 없으므로, 필요한 읽기 메모리 배리어가 요청되지 않기 때문입니다.
-
-예를 들어서:
-
-	CPU 1				CPU 2
-	===============================	===============================
-	spin_lock(Q)
-	writel(0, ADDR)
-	writel(1, DATA);
-	spin_unlock(Q);
-					spin_lock(Q);
-					writel(4, ADDR);
-					writel(5, DATA);
-					spin_unlock(Q);
-
-는 PCI 브릿지에 다음과 같이 보일 수 있습니다:
-
-	STORE *ADDR = 0, STORE *ADDR = 4, STORE *DATA = 1, STORE *DATA = 5
-
-이렇게 되면 하드웨어의 오동작을 일으킬 수 있습니다.
-
-
-이런 경우엔 잡아둔 스핀락을 내려놓기 전에 mmiowb() 를 수행해야 하는데, 예를
-들면 다음과 같습니다:
-
-	CPU 1				CPU 2
-	===============================	===============================
-	spin_lock(Q)
-	writel(0, ADDR)
-	writel(1, DATA);
-	mmiowb();
-	spin_unlock(Q);
-					spin_lock(Q);
-					writel(4, ADDR);
-					writel(5, DATA);
-					mmiowb();
-					spin_unlock(Q);
-
-이 코드는 CPU 1 에서 요청된 두개의 스토어가 PCI 브릿지에 CPU 2 에서 요청된
-스토어들보다 먼저 보여짐을 보장합니다.
-
-
-또한, 같은 디바이스에서 스토어를 이어 로드가 수행되면 이 로드는 로드가 수행되기
-전에 스토어가 완료되기를 강제하므로 mmiowb() 의 필요가 없어집니다:
-
-	CPU 1				CPU 2
-	===============================	===============================
-	spin_lock(Q)
-	writel(0, ADDR)
-	a = readl(DATA);
-	spin_unlock(Q);
-					spin_lock(Q);
-					writel(4, ADDR);
-					b = readl(DATA);
-					spin_unlock(Q);
-
-
-더 많은 정보를 위해선 Documenataion/DocBook/deviceiobook.tmpl 을 참고하세요.
-
-
-=========================
-메모리 배리어가 필요한 곳
-=========================
-
-설령 SMP 커널을 사용하더라도 싱글 쓰레드로 동작하는 코드는 올바르게 동작하는
-것으로 보여질 것이기 때문에, 평범한 시스템 운영중에 메모리 오퍼레이션 재배치는
-일반적으로 문제가 되지 않습니다.  하지만, 재배치가 문제가 _될 수 있는_ 네가지
-환경이 있습니다:
-
- (*) 프로세서간 상호 작용.
-
- (*) 어토믹 오퍼레이션.
-
- (*) 디바이스 액세스.
-
- (*) 인터럽트.
-
-
-프로세서간 상호 작용
---------------------
-
-두개 이상의 프로세서를 가진 시스템이 있다면, 시스템의 두개 이상의 CPU 는 동시에
-같은 데이터에 대한 작업을 할 수 있습니다.  이는 동기화 문제를 일으킬 수 있고,
-이 문제를 해결하는 일반적 방법은 락을 사용하는 것입니다.  하지만, 락은 상당히
-비용이 비싸서 가능하면 락을 사용하지 않고 일을 처리하는 것이 낫습니다.  이런
-경우, 두 CPU 모두에 영향을 끼치는 오퍼레이션들은 오동작을 막기 위해 신중하게
-순서가 맞춰져야 합니다.
-
-예를 들어, R/W 세마포어의 느린 수행경로 (slow path) 를 생각해 봅시다.
-세마포어를 위해 대기를 하는 하나의 프로세스가 자신의 스택 중 일부를 이
-세마포어의 대기 프로세스 리스트에 링크한 채로 있습니다:
-
-	struct rw_semaphore {
-		...
-		spinlock_t lock;
-		struct list_head waiters;
-	};
-
-	struct rwsem_waiter {
-		struct list_head list;
-		struct task_struct *task;
-	};
-
-특정 대기 상태 프로세스를 깨우기 위해, up_read() 나 up_write() 함수는 다음과
-같은 일을 합니다:
-
- (1) 다음 대기 상태 프로세스 레코드는 어디있는지 알기 위해 이 대기 상태
-     프로세스 레코드의 next 포인터를 읽습니다;
-
- (2) 이 대기 상태 프로세스의 task 구조체로의 포인터를 읽습니다;
-
- (3) 이 대기 상태 프로세스가 세마포어를 획득했음을 알리기 위해 task
-     포인터를 초기화 합니다;
-
- (4) 해당 태스크에 대해 wake_up_process() 를 호출합니다; 그리고
-
- (5) 해당 대기 상태 프로세스의 task 구조체를 잡고 있던 레퍼런스를 해제합니다.
-
-달리 말하자면, 다음 이벤트 시퀀스를 수행해야 합니다:
-
-	LOAD waiter->list.next;
-	LOAD waiter->task;
-	STORE waiter->task;
-	CALL wakeup
-	RELEASE task
-
-그리고 이 이벤트들이 다른 순서로 수행된다면, 오동작이 일어날 수 있습니다.
-
-한번 세마포어의 대기줄에 들어갔고 세마포어 락을 놓았다면, 해당 대기 프로세스는
-락을 다시는 잡지 않습니다; 대신 자신의 task 포인터가 초기화 되길 기다립니다.
-그 레코드는 대기 프로세스의 스택에 있기 때문에, 리스트의 next 포인터가 읽혀지기
-_전에_ task 포인터가 지워진다면, 다른 CPU 는 해당 대기 프로세스를 시작해 버리고
-up*() 함수가 next 포인터를 읽기 전에 대기 프로세스의 스택을 마구 건드릴 수
-있습니다.
-
-그렇게 되면 위의 이벤트 시퀀스에 어떤 일이 일어나는지 생각해 보죠:
-
-	CPU 1				CPU 2
-	===============================	===============================
-					down_xxx()
-					Queue waiter
-					Sleep
-	up_yyy()
-	LOAD waiter->task;
-	STORE waiter->task;
-					Woken up by other event
-	
-					Resume processing
-					down_xxx() returns
-					call foo()
-					foo() clobbers *waiter
-	
-	LOAD waiter->list.next;
-	--- OOPS ---
-
-이 문제는 세마포어 락의 사용으로 해결될 수도 있겠지만, 그렇게 되면 깨어난 후에
-down_xxx() 함수가 불필요하게 스핀락을 또다시 얻어야만 합니다.
-
-이 문제를 해결하는 방법은 범용 SMP 메모리 배리어를 추가하는 겁니다:
-
-	LOAD waiter->list.next;
-	LOAD waiter->task;
-	smp_mb();
-	STORE waiter->task;
-	CALL wakeup
-	RELEASE task
-
-이 경우에, 배리어는 시스템의 나머지 CPU 들에게 모든 배리어 앞의 메모리 액세스가
-배리어 뒤의 메모리 액세스보다 앞서 일어난 것으로 보이게 만듭니다.  배리어 앞의
-메모리 액세스들이 배리어 명령 자체가 완료되는 시점까지 완료된다고는 보장하지
-_않습니다_.
-
-(이게 문제가 되지 않을) 단일 프로세서 시스템에서 smp_mb() 는 실제로는 그저
-컴파일러가 CPU 안에서의 순서를 바꾸거나 하지 않고 주어진 순서대로 명령을
-내리도록 하는 컴파일러 배리어일 뿐입니다.  오직 하나의 CPU 만 있으니, CPU 의
-의존성 순서 로직이 그 외의 모든것을 알아서 처리할 겁니다.
-
-
-어토믹 오퍼레이션
------------------
-
-어토믹 오퍼레이션은 기술적으로 프로세서간 상호작용으로 분류되며 그 중 일부는
-전체 메모리 배리어를 내포하고 또 일부는 내포하지 않지만, 커널에서 상당히
-의존적으로 사용하는 기능 중 하나입니다.
-
-메모리의 어떤 상태를 수정하고 해당 상태에 대한 (예전의 또는 최신의) 정보를
-리턴하는 어토믹 오퍼레이션은 모두 SMP-조건적 범용 메모리 배리어(smp_mb())를
-실제 오퍼레이션의 앞과 뒤에 내포합니다.  이런 오퍼레이션은 다음의 것들을
-포함합니다:
-
-	xchg();
-	atomic_xchg();			atomic_long_xchg();
-	atomic_inc_return();		atomic_long_inc_return();
-	atomic_dec_return();		atomic_long_dec_return();
-	atomic_add_return();		atomic_long_add_return();
-	atomic_sub_return();		atomic_long_sub_return();
-	atomic_inc_and_test();		atomic_long_inc_and_test();
-	atomic_dec_and_test();		atomic_long_dec_and_test();
-	atomic_sub_and_test();		atomic_long_sub_and_test();
-	atomic_add_negative();		atomic_long_add_negative();
-	test_and_set_bit();
-	test_and_clear_bit();
-	test_and_change_bit();
-
-	/* exchange 조건이 성공할 때 */
-	cmpxchg();
-	atomic_cmpxchg();		atomic_long_cmpxchg();
-	atomic_add_unless();		atomic_long_add_unless();
-
-이것들은 메모리 배리어 효과가 필요한 ACQUIRE 부류와 RELEASE 부류 오퍼레이션들을
-구현할 때, 그리고 객체 해제를 위해 레퍼런스 카운터를 조정할 때, 암묵적 메모리
-배리어 효과가 필요한 곳 등에 사용됩니다.
-
-
-다음의 오퍼레이션들은 메모리 배리어를 내포하지 _않기_ 때문에 문제가 될 수
-있지만, RELEASE 부류의 오퍼레이션들과 같은 것들을 구현할 때 사용될 수도
-있습니다:
-
-	atomic_set();
-	set_bit();
-	clear_bit();
-	change_bit();
-
-이것들을 사용할 때에는 필요하다면 적절한 (예를 들면 smp_mb__before_atomic()
-같은) 메모리 배리어가 명시적으로 함께 사용되어야 합니다.
-
-
-아래의 것들도 메모리 배리어를 내포하지 _않기_ 때문에, 일부 환경에서는 (예를
-들면 smp_mb__before_atomic() 과 같은) 명시적인 메모리 배리어 사용이 필요합니다.
-
-	atomic_add();
-	atomic_sub();
-	atomic_inc();
-	atomic_dec();
-
-이것들이 통계 생성을 위해 사용된다면, 그리고 통계 데이터 사이에 관계가 존재하지
-않는다면 메모리 배리어는 필요치 않을 겁니다.
-
-객체의 수명을 관리하기 위해 레퍼런스 카운팅 목적으로 사용된다면, 레퍼런스
-카운터는 락으로 보호되는 섹션에서만 조정되거나 호출하는 쪽이 이미 충분한
-레퍼런스를 잡고 있을 것이기 때문에 메모리 배리어는 아마 필요 없을 겁니다.
-
-만약 어떤 락을 구성하기 위해 사용된다면, 락 관련 동작은 일반적으로 작업을 특정
-순서대로 진행해야 하므로 메모리 배리어가 필요할 수 있습니다.
-
-기본적으로, 각 사용처에서는 메모리 배리어가 필요한지 아닌지 충분히 고려해야
-합니다.
-
-아래의 오퍼레이션들은 특별한 락 관련 동작들입니다:
-
-	test_and_set_bit_lock();
-	clear_bit_unlock();
-	__clear_bit_unlock();
-
-이것들은 ACQUIRE 류와 RELEASE 류의 오퍼레이션들을 구현합니다.  락 관련 도구를
-구현할 때에는 이것들을 좀 더 선호하는 편이 나은데, 이것들의 구현은 많은
-아키텍쳐에서 최적화 될 수 있기 때문입니다.
-
-[!] 이런 상황에 사용할 수 있는 특수한 메모리 배리어 도구들이 있습니다만, 일부
-CPU 에서는 사용되는 어토믹 인스트럭션 자체에 메모리 배리어가 내포되어 있어서
-어토믹 오퍼레이션과 메모리 배리어를 함께 사용하는 게 불필요한 일이 될 수
-있는데, 그런 경우에 이 특수 메모리 배리어 도구들은 no-op 이 되어 실질적으로
-아무일도 하지 않습니다.
-
-더 많은 내용을 위해선 Documentation/atomic_ops.txt 를 참고하세요.
-
-
-디바이스 액세스
----------------
-
-많은 디바이스가 메모리 매핑 기법으로 제어될 수 있는데, 그렇게 제어되는
-디바이스는 CPU 에는 단지 특정 메모리 영역의 집합처럼 보이게 됩니다.  드라이버는
-그런 디바이스를 제어하기 위해 정확히 올바른 순서로 올바른 메모리 액세스를
-만들어야 합니다.
-
-하지만, 액세스들을 재배치 하거나 조합하거나 병합하는게 더 효율적이라 판단하는
-영리한 CPU 나 컴파일러들을 사용하면 드라이버 코드의 조심스럽게 순서 맞춰진
-액세스들이 디바이스에는 요청된 순서대로 도착하지 못하게 할 수 있는 - 디바이스가
-오동작을 하게 할 - 잠재적 문제가 생길 수 있습니다.
-
-리눅스 커널 내부에서, I/O 는 어떻게 액세스들을 적절히 순차적이게 만들 수 있는지
-알고 있는, - inb() 나 writel() 과 같은 - 적절한 액세스 루틴을 통해 이루어져야만
-합니다.  이것들은 대부분의 경우에는 명시적 메모리 배리어 와 함께 사용될 필요가
-없습니다만, 다음의 두가지 상황에서는 명시적 메모리 배리어가 필요할 수 있습니다:
-
- (1) 일부 시스템에서 I/O 스토어는 모든 CPU 에 일관되게 순서 맞춰지지 않는데,
-     따라서 _모든_ 일반적인 드라이버들에 락이 사용되어야만 하고 이 크리티컬
-     섹션을 빠져나오기 전에 mmiowb() 가 꼭 호출되어야 합니다.
-
- (2) 만약 액세스 함수들이 완화된 메모리 액세스 속성을 갖는 I/O 메모리 윈도우를
-     사용한다면, 순서를 강제하기 위해선 _mandatory_ 메모리 배리어가 필요합니다.
-
-더 많은 정보를 위해선 Documentation/DocBook/deviceiobook.tmpl 을 참고하십시오.
-
-
-인터럽트
---------
-
-드라이버는 자신의 인터럽트 서비스 루틴에 의해 인터럽트 당할 수 있기 때문에
-드라이버의 이 두 부분은 서로의 디바이스 제어 또는 액세스 부분과 상호 간섭할 수
-있습니다.
-
-스스로에게 인터럽트 당하는 걸 불가능하게 하고, 드라이버의 크리티컬한
-오퍼레이션들을 모두 인터럽트가 불가능하게 된 영역에 집어넣거나 하는 방법 (락의
-한 형태) 으로 이런 상호 간섭을 - 최소한 부분적으로라도 - 줄일 수 있습니다.
-드라이버의 인터럽트 루틴이 실행 중인 동안, 해당 드라이버의 코어는 같은 CPU 에서
-수행되지 않을 것이며, 현재의 인터럽트가 처리되는 중에는 또다시 인터럽트가
-일어나지 못하도록 되어 있으니 인터럽트 핸들러는 그에 대해서는 락을 잡지 않아도
-됩니다.
-
-하지만, 어드레스 레지스터와 데이터 레지스터를 갖는 이더넷 카드를 다루는
-드라이버를 생각해 봅시다.  만약 이 드라이버의 코어가 인터럽트를 비활성화시킨
-채로 이더넷 카드와 대화하고 드라이버의 인터럽트 핸들러가 호출되었다면:
-
-	LOCAL IRQ DISABLE
-	writew(ADDR, 3);
-	writew(DATA, y);
-	LOCAL IRQ ENABLE
-	
-	writew(ADDR, 4);
-	q = readw(DATA);
-	
-
-만약 순서 규칙이 충분히 완화되어 있다면 데이터 레지스터에의 스토어는 어드레스
-레지스터에 두번째로 행해지는 스토어 뒤에 일어날 수도 있습니다:
-
-	STORE *ADDR = 3, STORE *ADDR = 4, STORE *DATA = y, q = LOAD *DATA
-
-
-만약 순서 규칙이 충분히 완화되어 있고 묵시적으로든 명시적으로든 배리어가
-사용되지 않았다면 인터럽트 비활성화 섹션에서 일어난 액세스가 바깥으로 새어서
-인터럽트 내에서 일어난 액세스와 섞일 수 있다고 - 그리고 그 반대도 - 가정해야만
-합니다.
-
-그런 영역 안에서 일어나는 I/O 액세스들은 엄격한 순서 규칙의 I/O 레지스터에
-묵시적 I/O 배리어를 형성하는 동기적 (synchronous) 로드 오퍼레이션을 포함하기
-때문에 일반적으로는 이런게 문제가 되지 않습니다.  만약 이걸로는 충분치 않다면
-mmiowb() 가 명시적으로 사용될 필요가 있습니다.
-
-
-하나의 인터럽트 루틴과 별도의 CPU 에서 수행중이며 서로 통신을 하는 두 루틴
-사이에도 비슷한 상황이 일어날 수 있습니다.  만약 그런 경우가 발생할 가능성이
-있다면, 순서를 보장하기 위해 인터럽트 비활성화 락이 사용되어져야만 합니다.
-
-
-======================
-커널 I/O 배리어의 효과
-======================
-
-I/O 메모리에 액세스할 때, 드라이버는 적절한 액세스 함수를 사용해야 합니다:
-
- (*) inX(), outX():
-
-     이것들은 메모리 공간보다는 I/O 공간에 이야기를 하려는 의도로
-     만들어졌습니다만, 그건 기본적으로 CPU 마다 다른 컨셉입니다.  i386 과
-     x86_64 프로세서들은 특별한 I/O 공간 액세스 사이클과 명령어를 실제로 가지고
-     있지만, 다른 많은 CPU 들에는 그런 컨셉이 존재하지 않습니다.
-
-     다른 것들 중에서도 PCI 버스가 I/O 공간 컨셉을 정의하는데, 이는 - i386 과
-     x86_64 같은 CPU 에서 - CPU 의 I/O 공간 컨셉으로 쉽게 매치됩니다.  하지만,
-     대체할 I/O 공간이 없는 CPU 에서는 CPU 의 메모리 맵의 가상 I/O 공간으로
-     매핑될 수도 있습니다.
-
-     이 공간으로의 액세스는 (i386 등에서는) 완전하게 동기화 됩니다만, 중간의
-     (PCI 호스트 브리지와 같은) 브리지들은 이를 완전히 보장하진 않을수도
-     있습니다.
-
-     이것들의 상호간의 순서는 완전하게 보장됩니다.
-
-     다른 타입의 메모리 오퍼레이션, I/O 오퍼레이션에 대한 순서는 완전하게
-     보장되지는 않습니다.
-
- (*) readX(), writeX():
-
-     이것들이 수행 요청되는 CPU 에서 서로에게 완전히 순서가 맞춰지고 독립적으로
-     수행되는지에 대한 보장 여부는 이들이 액세스 하는 메모리 윈도우에 정의된
-     특성에 의해 결정됩니다.  예를 들어, 최신의 i386 아키텍쳐 머신에서는 MTRR
-     레지스터로 이 특성이 조정됩니다.
-
-     일반적으로는, 프리페치 (prefetch) 가능한 디바이스를 액세스 하는게
-     아니라면, 이것들은 완전히 순서가 맞춰지고 결합되지 않게 보장될 겁니다.
-
-     하지만, (PCI 브리지와 같은) 중간의 하드웨어는 자신이 원한다면 집행을
-     연기시킬 수 있습니다; 스토어 명령을 실제로 하드웨어로 내려보내기(flush)
-     위해서는 같은 위치로부터 로드를 하는 방법이 있습니다만[*], PCI 의 경우는
-     같은 디바이스나 환경 구성 영역에서의 로드만으로도 충분할 겁니다.
-
-     [*] 주의! 쓰여진 것과 같은 위치로부터의 로드를 시도하는 것은 오동작을
-	 일으킬 수도 있습니다 - 예로 16650 Rx/Tx 시리얼 레지스터를 생각해
-	 보세요.
-
-     프리페치 가능한 I/O 메모리가 사용되면, 스토어 명령들이 순서를 지키도록
-     하기 위해 mmiowb() 배리어가 필요할 수 있습니다.
-
-     PCI 트랜잭션 사이의 상호작용에 대해 더 많은 정보를 위해선 PCI 명세서를
-     참고하시기 바랍니다.
-
- (*) readX_relaxed(), writeX_relaxed()
-
-     이것들은 readX() 와 writeX() 랑 비슷하지만, 더 완화된 메모리 순서 보장을
-     제공합니다.  구체적으로, 이것들은 일반적 메모리 액세스 (예: DMA 버퍼) 에도
-     LOCK 이나 UNLOCK 오퍼레이션들에도 순서를 보장하지 않습니다.  LOCK 이나
-     UNLOCK 오퍼레이션들에 맞춰지는 순서가 필요하다면, mmiowb() 배리어가 사용될
-     수 있습니다.  같은 주변 장치에의 완화된 액세스끼리는 순서가 지켜짐을 알아
-     두시기 바랍니다.
-
- (*) ioreadX(), iowriteX()
-
-     이것들은 inX()/outX() 나 readX()/writeX() 처럼 실제로 수행하는 액세스의
-     종류에 따라 적절하게 수행될 것입니다.
-
-
-===================================
-가정되는 가장 완화된 실행 순서 모델
-===================================
-
-컨셉적으로 CPU 는 주어진 프로그램에 대해 프로그램 그 자체에는 인과성 (program
-causality) 을 지키는 것처럼 보이게 하지만 일반적으로는 순서를 거의 지켜주지
-않는다고 가정되어야만 합니다.  (i386 이나 x86_64 같은) 일부 CPU 들은 코드
-재배치에 (powerpc 나 frv 와 같은) 다른 것들에 비해 강한 제약을 갖지만, 아키텍쳐
-종속적 코드 이외의 코드에서는 순서에 대한 제약이 가장 완화된 경우 (DEC Alpha)
-를 가정해야 합니다.
-
-이 말은, CPU 에게 주어지는 인스트럭션 스트림 내의 한 인스트럭션이 앞의
-인스트럭션에 종속적이라면 앞의 인스트럭션은 뒤의 종속적 인스트럭션이 실행되기
-전에 완료[*]될 수 있어야 한다는 제약 (달리 말해서, 인과성이 지켜지는 것으로
-보이게 함) 외에는 자신이 원하는 순서대로 - 심지어 병렬적으로도 - 그 스트림을
-실행할 수 있음을 의미합니다
-
- [*] 일부 인스트럭션은 하나 이상의 영향 - 조건 코드를 바꾼다던지, 레지스터나
-     메모리를 바꾼다던지 - 을 만들어내며, 다른 인스트럭션은 다른 효과에
-     종속적일 수 있습니다.
-
-CPU 는 최종적으로 아무 효과도 만들지 않는 인스트럭션 시퀀스는 없애버릴 수도
-있습니다.  예를 들어, 만약 두개의 연속되는 인스트럭션이 둘 다 같은 레지스터에
-직접적인 값 (immediate value) 을 집어넣는다면, 첫번째 인스트럭션은 버려질 수도
-있습니다.
-
-
-비슷하게, 컴파일러 역시 프로그램의 인과성만 지켜준다면 인스트럭션 스트림을
-자신이 보기에 올바르다 생각되는대로 재배치 할 수 있습니다.
-
-
-===============
-CPU 캐시의 영향
-===============
-
-캐시된 메모리 오퍼레이션들이 시스템 전체에 어떻게 인지되는지는 CPU 와 메모리
-사이에 존재하는 캐시들, 그리고 시스템 상태의 일관성을 관리하는 메모리 일관성
-시스템에 상당 부분 영향을 받습니다.
-
-한 CPU 가 시스템의 다른 부분들과 캐시를 통해 상호작용한다면, 메모리 시스템은
-CPU 의 캐시들을 포함해야 하며, CPU 와 CPU 자신의 캐시 사이에서의 동작을 위한
-메모리 배리어를 가져야 합니다. (메모리 배리어는 논리적으로는 다음 그림의
-점선에서 동작합니다):
-
-	    <--- CPU --->         :       <----------- Memory ----------->
-	                          :
-	+--------+    +--------+  :   +--------+    +-----------+
-	|        |    |        |  :   |        |    |           |    +--------+
-	|  CPU   |    | Memory |  :   | CPU    |    |           |    |        |
-	|  Core  |--->| Access |----->| Cache  |<-->|           |    |        |
-	|        |    | Queue  |  :   |        |    |           |--->| Memory |
-	|        |    |        |  :   |        |    |           |    |        |
-	+--------+    +--------+  :   +--------+    |           |    |        |
-	                          :                 | Cache     |    +--------+
-	                          :                 | Coherency |
-	                          :                 | Mechanism |    +--------+
-	+--------+    +--------+  :   +--------+    |           |    |	      |
-	|        |    |        |  :   |        |    |           |    |        |
-	|  CPU   |    | Memory |  :   | CPU    |    |           |--->| Device |
-	|  Core  |--->| Access |----->| Cache  |<-->|           |    |        |
-	|        |    | Queue  |  :   |        |    |           |    |        |
-	|        |    |        |  :   |        |    |           |    +--------+
-	+--------+    +--------+  :   +--------+    +-----------+
-	                          :
-	                          :
-
-특정 로드나 스토어는 해당 오퍼레이션을 요청한 CPU 의 캐시 내에서 동작을 완료할
-수도 있기 때문에 해당 CPU 의 바깥에는 보이지 않을 수 있지만, 다른 CPU 가 관심을
-갖는다면 캐시 일관성 메커니즘이 해당 캐시라인을 해당 CPU 에게 전달하고, 해당
-메모리 영역에 대한 오퍼레이션이 발생할 때마다 그 영향을 전파시키기 때문에, 해당
-오퍼레이션은 메모리에 실제로 액세스를 한것처럼 나타날 것입니다.
-
-CPU 코어는 프로그램의 인과성이 유지된다고만 여겨진다면 인스트럭션들을 어떤
-순서로든 재배치해서 수행할 수 있습니다.  일부 인스트럭션들은 로드나 스토어
-오퍼레이션을 만드는데 이 오퍼레이션들은 이후 수행될 메모리 액세스 큐에 들어가게
-됩니다.  코어는 이 오퍼레이션들을 해당 큐에 어떤 순서로든 원하는대로 넣을 수
-있고, 다른 인스트럭션의 완료를 기다리도록 강제되기 전까지는 수행을 계속합니다.
-
-메모리 배리어가 하는 일은 CPU 쪽에서 메모리 쪽으로 넘어가는 액세스들의 순서,
-그리고 그 액세스의 결과가 시스템의 다른 관찰자들에게 인지되는 순서를 제어하는
-것입니다.
-
-[!] CPU 들은 항상 그들 자신의 로드와 스토어는 프로그램 순서대로 일어난 것으로
-보기 때문에, 주어진 CPU 내에서는 메모리 배리어를 사용할 필요가 _없습니다_.
-
-[!] MMIO 나 다른 디바이스 액세스들은 캐시 시스템을 우회할 수도 있습니다.  우회
-여부는 디바이스가 액세스 되는 메모리 윈도우의 특성에 의해 결정될 수도 있고, CPU
-가 가지고 있을 수 있는 특수한 디바이스 통신 인스트럭션의 사용에 의해서 결정될
-수도 있습니다.
-
-
-캐시 일관성
------------
-
-하지만 삶은 앞에서 이야기한 것처럼 단순하지 않습니다: 캐시들은 일관적일 것으로
-기대되지만, 그 일관성이 순서에도 적용될 거라는 보장은 없습니다.  한 CPU 에서
-만들어진 변경 사항은 최종적으로는 시스템의 모든 CPU 에게 보여지게 되지만, 다른
-CPU 들에게도 같은 순서로 보이게 될 거라는 보장은 없다는 뜻입니다.
-
-
-두개의 CPU (1 & 2) 가 달려 있고, 각 CPU 에 두개의 데이터 캐시(CPU 1 은 A/B 를,
-CPU 2 는 C/D 를 갖습니다)가 병렬로 연결되어 있는 시스템을 다룬다고 생각해
-봅시다:
-
-	            :
-	            :                          +--------+
-	            :      +---------+         |        |
-	+--------+  : +--->| Cache A |<------->|        |
-	|        |  : |    +---------+         |        |
-	|  CPU 1 |<---+                        |        |
-	|        |  : |    +---------+         |        |
-	+--------+  : +--->| Cache B |<------->|        |
-	            :      +---------+         |        |
-	            :                          | Memory |
-	            :      +---------+         | System |
-	+--------+  : +--->| Cache C |<------->|        |
-	|        |  : |    +---------+         |        |
-	|  CPU 2 |<---+                        |        |
-	|        |  : |    +---------+         |        |
-	+--------+  : +--->| Cache D |<------->|        |
-	            :      +---------+         |        |
-	            :                          +--------+
-	            :
-
-이 시스템이 다음과 같은 특성을 갖는다 생각해 봅시다:
-
- (*) 홀수번 캐시라인은 캐시 A, 캐시 C 또는 메모리에 위치할 수 있음;
-
- (*) 짝수번 캐시라인은 캐시 B, 캐시 D 또는 메모리에 위치할 수 있음;
-
- (*) CPU 코어가 한개의 캐시에 접근하는 동안, 다른 캐시는 - 더티 캐시라인을
-     메모리에 내리거나 추측성 로드를 하거나 하기 위해 - 시스템의 다른 부분에
-     액세스 하기 위해 버스를 사용할 수 있음;
-
- (*) 각 캐시는 시스템의 나머지 부분들과 일관성을 맞추기 위해 해당 캐시에
-     적용되어야 할 오퍼레이션들의 큐를 가짐;
-
- (*) 이 일관성 큐는 캐시에 이미 존재하는 라인에 가해지는 평범한 로드에 의해서는
-     비워지지 않는데, 큐의 오퍼레이션들이 이 로드의 결과에 영향을 끼칠 수 있다
-     할지라도 그러함.
-
-이제, 첫번째 CPU 에서 두개의 쓰기 오퍼레이션을 만드는데, 해당 CPU 의 캐시에
-요청된 순서로 오퍼레이션이 도달됨을 보장하기 위해 두 오퍼레이션 사이에 쓰기
-배리어를 사용하는 상황을 상상해 봅시다:
-
-	CPU 1		CPU 2		COMMENT
-	===============	===============	=======================================
-					u == 0, v == 1 and p == &u, q == &u
-	v = 2;
-	smp_wmb();			v 의 변경이 p 의 변경 전에 보일 것을
-					 분명히 함
-				v 는 이제 캐시 A 에 독점적으로 존재함
-	p = &v;
-				p 는 이제 캐시 B 에 독점적으로 존재함
-
-여기서의 쓰기 메모리 배리어는 CPU 1 의 캐시가 올바른 순서로 업데이트 된 것으로
-시스템의 다른 CPU 들이 인지하게 만듭니다.  하지만, 이제 두번째 CPU 가 그 값들을
-읽으려 하는 상황을 생각해 봅시다:
-
-	CPU 1		CPU 2		COMMENT
-	===============	===============	=======================================
-	...
-			q = p;
-			x = *q;
-
-위의 두개의 읽기 오퍼레이션은 예상된 순서로 일어나지 못할 수 있는데, 두번째 CPU
-의 한 캐시에 다른 캐시 이벤트가 발생해 v 를 담고 있는 캐시라인의 해당 캐시에의
-업데이트가 지연되는 사이, p 를 담고 있는 캐시라인은 두번째 CPU 의 다른 캐시에
-업데이트 되어버렸을 수 있기 때문입니다.
-
-	CPU 1		CPU 2		COMMENT
-	===============	===============	=======================================
-					u == 0, v == 1 and p == &u, q == &u
-	v = 2;
-	smp_wmb();
-		
-			
-	p = &v;		q = p;
-			
-		
-			
-			x = *q;
-				캐시에 업데이트 되기 전의 v 를 읽음
-			
-			
-
-기본적으로, 두개의 캐시라인 모두 CPU 2 에 최종적으로는 업데이트 될 것이지만,
-별도의 개입 없이는, 업데이트의 순서가 CPU 1 에서 만들어진 순서와 동일할
-것이라는 보장이 없습니다.
-
-
-여기에 개입하기 위해선, 데이터 의존성 배리어나 읽기 배리어를 로드 오퍼레이션들
-사이에 넣어야 합니다.  이렇게 함으로써 캐시가 다음 요청을 처리하기 전에 일관성
-큐를 처리하도록 강제하게 됩니다.
-
-	CPU 1		CPU 2		COMMENT
-	===============	===============	=======================================
-					u == 0, v == 1 and p == &u, q == &u
-	v = 2;
-	smp_wmb();
-		
-			
-	p = &v;		q = p;
-			
-		
-			
-			smp_read_barrier_depends()
-			
-			
-			x = *q;
-				캐시에 업데이트 된 v 를 읽음
-
-
-이런 부류의 문제는 DEC Alpha 계열 프로세서들에서 발견될 수 있는데, 이들은
-데이터 버스를 좀 더 잘 사용해 성능을 개선할 수 있는, 분할된 캐시를 가지고 있기
-때문입니다.  대부분의 CPU 는 하나의 읽기 오퍼레이션의 메모리 액세스가 다른 읽기
-오퍼레이션에 의존적이라면 데이터 의존성 배리어를 내포시킵니다만, 모두가 그런건
-아니기 때문에 이점에 의존해선 안됩니다.
-
-다른 CPU 들도 분할된 캐시를 가지고 있을 수 있지만, 그런 CPU 들은 평범한 메모리
-액세스를 위해서도 이 분할된 캐시들 사이의 조정을 해야만 합니다.  Alpha 는 가장
-약한 메모리 순서 시맨틱 (semantic) 을 선택함으로써 메모리 배리어가 명시적으로
-사용되지 않았을 때에는 그런 조정이 필요하지 않게 했습니다.
-
-
-캐시 일관성 VS DMA
-------------------
-
-모든 시스템이 DMA 를 하는 디바이스에 대해서까지 캐시 일관성을 유지하지는
-않습니다.  그런 경우, DMA 를 시도하는 디바이스는 RAM 으로부터 잘못된 데이터를
-읽을 수 있는데, 더티 캐시 라인이 CPU 의 캐시에 머무르고 있고, 바뀐 값이 아직
-RAM 에 써지지 않았을 수 있기 때문입니다.  이 문제를 해결하기 위해선, 커널의
-적절한 부분에서 각 CPU 캐시의 문제되는 비트들을 플러시 (flush) 시켜야만 합니다
-(그리고 그것들을 무효화 - invalidation - 시킬 수도 있겠죠).
-
-또한, 디바이스에 의해 RAM 에 DMA 로 쓰여진 값은 디바이스가 쓰기를 완료한 후에
-CPU 의 캐시에서 RAM 으로 쓰여지는 더티 캐시 라인에 의해 덮어써질 수도 있고, CPU
-의 캐시에 존재하는 캐시 라인이 해당 캐시에서 삭제되고 다시 값을 읽어들이기
-전까지는 RAM 이 업데이트 되었다는 사실 자체가 숨겨져 버릴 수도 있습니다.  이
-문제를 해결하기 위해선, 커널의 적절한 부분에서 각 CPU 의 캐시 안의 문제가 되는
-비트들을 무효화 시켜야 합니다.
-
-캐시 관리에 대한 더 많은 정보를 위해선 Documentation/cachetlb.txt 를
-참고하세요.
-
-
-캐시 일관성 VS MMIO
--------------------
-
-Memory mapped I/O 는 일반적으로 CPU 의 메모리 공간 내의 한 윈도우의 특정 부분
-내의 메모리 지역에 이루어지는데, 이 윈도우는 일반적인, RAM 으로 향하는
-윈도우와는 다른 특성을 갖습니다.
-
-그런 특성 가운데 하나는, 일반적으로 그런 액세스는 캐시를 완전히 우회하고
-디바이스 버스로 곧바로 향한다는 것입니다.  이 말은 MMIO 액세스는 먼저
-시작되어서 캐시에서 완료된 메모리 액세스를 추월할 수 있다는 뜻입니다.  이런
-경우엔 메모리 배리어만으로는 충분치 않고, 만약 캐시된 메모리 쓰기 오퍼레이션과
-MMIO 액세스가 어떤 방식으로든 의존적이라면 해당 캐시는 두 오퍼레이션 사이에
-비워져(flush)야만 합니다.
-
-
-======================
-CPU 들이 저지르는 일들
-======================
-
-프로그래머는 CPU 가 메모리 오퍼레이션들을 정확히 요청한대로 수행해 줄 것이라고
-생각하는데, 예를 들어 다음과 같은 코드를 CPU 에게 넘긴다면:
-
-	a = READ_ONCE(*A);
-	WRITE_ONCE(*B, b);
-	c = READ_ONCE(*C);
-	d = READ_ONCE(*D);
-	WRITE_ONCE(*E, e);
-
-CPU 는 다음 인스트럭션을 처리하기 전에 현재의 인스트럭션을 위한 메모리
-오퍼레이션을 완료할 것이라 생각하고, 따라서 시스템 외부에서 관찰하기에도 정해진
-순서대로 오퍼레이션이 수행될 것으로 예상합니다:
-
-	LOAD *A, STORE *B, LOAD *C, LOAD *D, STORE *E.
-
-
-당연하지만, 실제로는 훨씬 엉망입니다.  많은 CPU 와 컴파일러에서 앞의 가정은
-성립하지 못하는데 그 이유는 다음과 같습니다:
-
- (*) 로드 오퍼레이션들은 실행을 계속 해나가기 위해 곧바로 완료될 필요가 있는
-     경우가 많은 반면, 스토어 오퍼레이션들은 종종 별다른 문제 없이 유예될 수
-     있습니다;
-
- (*) 로드 오퍼레이션들은 예측적으로 수행될 수 있으며, 필요없는 로드였다고
-     증명된 예측적 로드의 결과는 버려집니다;
-
- (*) 로드 오퍼레이션들은 예측적으로 수행될 수 있으므로, 예상된 이벤트의
-     시퀀스와 다른 시간에 로드가 이뤄질 수 있습니다;
-
- (*) 메모리 액세스 순서는 CPU 버스와 캐시를 좀 더 잘 사용할 수 있도록 재배치
-     될 수 있습니다;
-
- (*) 로드와 스토어는 인접한 위치에의 액세스들을 일괄적으로 처리할 수 있는
-     메모리나 I/O 하드웨어 (메모리와 PCI 디바이스 둘 다 이게 가능할 수
-     있습니다) 에 대해 요청되는 경우, 개별 오퍼레이션을 위한 트랜잭션 설정
-     비용을 아끼기 위해 조합되어 실행될 수 있습니다; 그리고
-
- (*) 해당 CPU 의 데이터 캐시가 순서에 영향을 끼칠 수도 있고, 캐시 일관성
-     메커니즘이 - 스토어가 실제로 캐시에 도달한다면 - 이 문제를 완화시킬 수는
-     있지만 이 일관성 관리가 다른 CPU 들에도 같은 순서로 전달된다는 보장은
-     없습니다.
-
-따라서, 앞의 코드에 대해 다른 CPU 가 보는 결과는 다음과 같을 수 있습니다:
-
-	LOAD *A, ..., LOAD {*C,*D}, STORE *E, STORE *B
-
-	("LOAD {*C,*D}" 는 조합된 로드입니다)
-
-
-하지만, CPU 는 스스로는 일관적일 것을 보장합니다: CPU _자신_ 의 액세스들은
-자신에게는 메모리 배리어가 없음에도 불구하고 정확히 순서 세워진 것으로 보여질
-것입니다.  예를 들어 다음의 코드가 주어졌다면:
-
-	U = READ_ONCE(*A);
-	WRITE_ONCE(*A, V);
-	WRITE_ONCE(*A, W);
-	X = READ_ONCE(*A);
-	WRITE_ONCE(*A, Y);
-	Z = READ_ONCE(*A);
-
-그리고 외부의 영향에 의한 간섭이 없다고 가정하면, 최종 결과는 다음과 같이
-나타날 것이라고 예상될 수 있습니다:
-
-	U == *A 의 최초 값
-	X == W
-	Z == Y
-	*A == Y
-
-앞의 코드는 CPU 가 다음의 메모리 액세스 시퀀스를 만들도록 할겁니다:
-
-	U=LOAD *A, STORE *A=V, STORE *A=W, X=LOAD *A, STORE *A=Y, Z=LOAD *A
-
-하지만, 별다른 개입이 없고 프로그램의 시야에 이 세상이 여전히 일관적이라고
-보인다는 보장만 지켜진다면 이 시퀀스는 어떤 조합으로든 재구성될 수 있으며, 각
-액세스들은 합쳐지거나 버려질 수 있습니다.  일부 아키텍쳐에서 CPU 는 같은 위치에
-대한 연속적인 로드 오퍼레이션들을 재배치 할 수 있기 때문에 앞의 예에서의
-READ_ONCE() 와 WRITE_ONCE() 는 반드시 존재해야 함을 알아두세요.  그런 종류의
-아키텍쳐에서 READ_ONCE() 와 WRITE_ONCE() 는 이 문제를 막기 위해 필요한 일을
-뭐가 됐든지 하게 되는데, 예를 들어 Itanium 에서는 READ_ONCE() 와 WRITE_ONCE()
-가 사용하는 volatile 캐스팅은 GCC 가 그런 재배치를 방지하는 특수 인스트럭션인
-ld.acq 와 stl.rel 인스트럭션을 각각 만들어 내도록 합니다.
-
-컴파일러 역시 이 시퀀스의 액세스들을 CPU 가 보기도 전에 합치거나 버리거나 뒤로
-미뤄버릴 수 있습니다.
-
-예를 들어:
-
-	*A = V;
-	*A = W;
-
-는 다음과 같이 변형될 수 있습니다:
-
-	*A = W;
-
-따라서, 쓰기 배리어나 WRITE_ONCE() 가 없다면 *A 로의 V 값의 저장의 효과는
-사라진다고 가정될 수 있습니다.  비슷하게:
-
-	*A = Y;
-	Z = *A;
-
-는, 메모리 배리어나 READ_ONCE() 와 WRITE_ONCE() 없이는 다음과 같이 변형될 수
-있습니다:
-
-	*A = Y;
-	Z = Y;
-
-그리고 이 LOAD 오퍼레이션은 CPU 바깥에는 아예 보이지 않습니다.
-
-
-그리고, ALPHA 가 있다
----------------------
-
-DEC Alpha CPU 는 가장 완화된 메모리 순서의 CPU 중 하나입니다.  뿐만 아니라,
-Alpha CPU 의 일부 버전은 분할된 데이터 캐시를 가지고 있어서, 의미적으로
-관계되어 있는 두개의 캐시 라인이 서로 다른 시간에 업데이트 되는게 가능합니다.
-이게 데이터 의존성 배리어가 정말 필요해지는 부분인데, 데이터 의존성 배리어는
-메모리 일관성 시스템과 함께 두개의 캐시를 동기화 시켜서, 포인터 변경과 새로운
-데이터의 발견을 올바른 순서로 일어나게 하기 때문입니다.
-
-리눅스 커널의 메모리 배리어 모델은 Alpha 에 기초해서 정의되었습니다.
-
-위의 "캐시 일관성" 서브섹션을 참고하세요.
-
-
-가상 머신 게스트
-----------------
-
-가상 머신에서 동작하는 게스트들은 게스트 자체는 SMP 지원 없이 컴파일 되었다
-해도 SMP 영향을 받을 수 있습니다.  이건 UP 커널을 사용하면서 SMP 호스트와
-결부되어 발생하는 부작용입니다.  이 경우에는 mandatory 배리어를 사용해서 문제를
-해결할 수 있겠지만 그런 해결은 대부분의 경우 최적의 해결책이 아닙니다.
-
-이 문제를 완벽하게 해결하기 위해, 로우 레벨의 virt_mb() 등의 매크로를 사용할 수
-있습니다. 이것들은 SMP 가 활성화 되어 있다면 smp_mb() 등과 동일한 효과를
-갖습니다만, SMP 와 SMP 아닌 시스템 모두에 대해 동일한 코드를 만들어냅니다.
-예를 들어, 가상 머신 게스트들은 (SMP 일 수 있는) 호스트와 동기화를 할 때에는
-smp_mb() 가 아니라 virt_mb() 를 사용해야 합니다.
-
-이것들은 smp_mb() 류의 것들과 모든 부분에서 동일하며, 특히, MMIO 의 영향에
-대해서는 간여하지 않습니다: MMIO 의 영향을 제어하려면, mandatory 배리어를
-사용하시기 바랍니다.
-
-
-=======
-사용 예
-=======
-
-순환식 버퍼
------------
-
-메모리 배리어는 순환식 버퍼를 생성자(producer)와 소비자(consumer) 사이의
-동기화에 락을 사용하지 않고 구현하는데에 사용될 수 있습니다.  더 자세한 내용을
-위해선 다음을 참고하세요:
-
-	Documentation/circular-buffers.txt
-
-
-=========
-참고 문헌
-=========
-
-Alpha AXP Architecture Reference Manual, Second Edition (Sites & Witek,
-Digital Press)
-	Chapter 5.2: Physical Address Space Characteristics
-	Chapter 5.4: Caches and Write Buffers
-	Chapter 5.5: Data Sharing
-	Chapter 5.6: Read/Write Ordering
-
-AMD64 Architecture Programmer's Manual Volume 2: System Programming
-	Chapter 7.1: Memory-Access Ordering
-	Chapter 7.4: Buffering and Combining Memory Writes
-
-IA-32 Intel Architecture Software Developer's Manual, Volume 3:
-System Programming Guide
-	Chapter 7.1: Locked Atomic Operations
-	Chapter 7.2: Memory Ordering
-	Chapter 7.4: Serializing Instructions
-
-The SPARC Architecture Manual, Version 9
-	Chapter 8: Memory Models
-	Appendix D: Formal Specification of the Memory Models
-	Appendix J: Programming with the Memory Models
-
-UltraSPARC Programmer Reference Manual
-	Chapter 5: Memory Accesses and Cacheability
-	Chapter 15: Sparc-V9 Memory Models
-
-UltraSPARC III Cu User's Manual
-	Chapter 9: Memory Models
-
-UltraSPARC IIIi Processor User's Manual
-	Chapter 8: Memory Models
-
-UltraSPARC Architecture 2005
-	Chapter 9: Memory
-	Appendix D: Formal Specifications of the Memory Models
-
-UltraSPARC T1 Supplement to the UltraSPARC Architecture 2005
-	Chapter 8: Memory Models
-	Appendix F: Caches and Cache Coherency
-
-Solaris Internals, Core Kernel Architecture, p63-68:
-	Chapter 3.3: Hardware Considerations for Locks and
-			Synchronization
-
-Unix Systems for Modern Architectures, Symmetric Multiprocessing and Caching
-for Kernel Programmers:
-	Chapter 13: Other Memory Models
-
-Intel Itanium Architecture Software Developer's Manual: Volume 1:
-	Section 2.6: Speculation
-	Section 4.4: Memory Access
diff --git a/Documentation/ko_KR/stable_api_nonsense.txt b/Documentation/ko_KR/stable_api_nonsense.txt
deleted file mode 100644
index 4d93af1efd61..000000000000
--- a/Documentation/ko_KR/stable_api_nonsense.txt
+++ /dev/null
@@ -1,195 +0,0 @@
-NOTE:
-This is a version of Documentation/process/stable-api-nonsense.rst translated
-into korean
-This document is maintained by Minchan Kim 
-If you find any difference between this document and the original file or
-a problem with the translation, please contact the maintainer of this file.
-
-Please also note that the purpose of this file is to be easier to
-read for non English (read: korean) speakers and is not intended as
-a fork. So if you have any comments or updates for this file please
-try to update the original English file first.
-
-==================================
-이 문서는
-Documentation/process/stable-api-nonsense.rst
-의 한글 번역입니다.
-
-역자： 김민찬 
-감수： 이제이미 
-==================================
-
-리눅스 커널 드라이버 인터페이스
-(여러분들의 모든 질문에 대한 답 그리고 다른 몇가지)
-
-Greg Kroah-Hartman 
-
-이 문서는 리눅스가 왜 바이너리 커널 인터페이스를 갖지 않는지, 왜 변하지
-않는(stable) 커널 인터페이스를 갖지 않는지를 설명하기 위해 쓰여졌다.
-이 문서는 커널과 유저공간 사이의 인터페이스가 아니라 커널 내부의
-인터페이스들을 설명하고 있다는 것을 유념하라. 커널과 유저공간 사이의
-인터페이스는 응용프로그램이 사용하는 syscall 인터페이스이다. 그 인터페이스는
-오랫동안 거의 변하지 않았고 앞으로도 변하지 않을 것이다. 나는 pre 0.9에서
-만들어졌지만 최신의 2.6 커널 배포에서도 잘 동작하는 프로그램을 가지고
-있다. 이 인터페이스는 사용자와 응용프로그램 개발자들이 변하지 않을 것이라고
-여길수 있는 것이다.
-
-
-초록
-----
-여러분은 변하지 않는 커널 인터페이스를 원한다고 생각하지만 실제로는
-그렇지 않으며 심지어는 그것을 알아채지 못한다. 여러분이 원하는 것은
-안정되게 실행되는 드라이버이며 드라이버가 메인 커널 트리에 있을 때
-그런 안정적인 드라이버를 얻을 수 있게 된다. 또한 여러분의 드라이버가
-메인 커널 트리에 있다면 다른 많은 좋은 이점들을 얻게 된다. 그러한 것들이
-리눅스를 강건하고, 안정적이며, 성숙한 운영체제로 만들어 놓음으로써
-여러분들로 하여금 바로 리눅스를 사용하게 만드는 이유이다.
-
-
-소개
-----
-
-커널 내부의 인터페이스가 바뀌는 것을 걱정하며 커널 드라이버를 작성하고
-싶어하는 사람은 정말 이상한 사람이다. 세상의 대다수의 사람들은 이 인터페이스를
-보지못할 것이며 전혀 걱정하지도 않는다.
-
-먼저, 나는 closed 소스, hidden 소스, binary blobs, 소스 wrappers, 또는 GPL로
-배포되었지만 소스 코드를 갖고 있지 않은 커널 드라이버들을 설명하는 어떤 다른
-용어들에 관한 어떤 법적인 문제에 관해서는 언급하지 않을 것이다. 어떤 법적인
-질문들을 가지고 있다면 변호사와 연락하라. 나는 프로그래머이므로 여기서 기술적인
-문제들만을 설명하려고 한다. (법적인 문제를 경시하는 것은 아니다. 그런 문제들은
-엄연히 현실에 있고 여러분들은 항상 그 문제들을 인식하고 있을 필요는 있다.)
-
-자, 두가지의 주요 주제가 있다. 바이너리 커널 인터페이스들과 변하지 않는
-커널 소스 인터페이들. 그것들은 서로 의존성을 가지고 있지만 바이너리
-문제를 먼저 풀고 넘어갈 것이다.
-
-
-
-바이너리 커널 인터페이스
-------------------------
-우리가 변하지 않는 커널 소스 인터페이스를 가지고 있다고 가정하자. 그러면
-바이너리 인터페이스 또한 자연적으로 변하지 않을까? 틀렸다. 리눅스 커널에
-관한 다음 사실들을 생각해보라.
-   - 여러분들이 사용하는 C 컴파일러의 버젼에 따라 다른 커널 자료 구조들은
-     다른 alignmnet들을 갖게 될것이고 다른 방법으로(함수들을 inline으로
-     했느냐, 아니냐) 다른 함수들을 포함하는 것도 가능한다. 중요한 것은
-     개별적인 함수 구성이 아니라 자료 구조 패딩이 달라진다는 점이다.
-   - 여러분이 선택한 커널 빌드 옵션에 따라서 커널은 다양한 것들을 가정할
-     수 있다.
-      - 다른 구조체들은 다른 필드들을 포함할 수 있다.
-      - 몇몇 함수들은 전혀 구현되지 않을 수도 있다(즉, 몇몇 lock들은
-        non-SMP 빌드에서는 사라져 버릴수도 있다).
-      - 커널내에 메모리는 build optoin들에 따라 다른 방법으로 align될수
-        있다.
-      - 리눅스는 많은 다양한 프로세서 아키텍쳐에서 실행된다. 한 아키텍쳐의
-        바이너리 드라이버를 다른 아키텍쳐에서 정상적으로 실행시킬 방법은
-        없다.
-
-커널을 빌드했던 C 컴파일러와 정확하게 같은 것을 사용하고 정확하게 같은
-커널 구성(configuration)을 사용하여 여러분들의 모듈을 빌드하면 간단히
-많은 문제들을 해결할 수 있다. 이렇게 하는 것은 여러분들이 하나의 리눅스
-배포판의 하나의 배포 버젼을 위한 모듈만을 제공한다면 별일 아닐 것이다.
-그러나 각기 다른 리눅스 배포판마다 한번씩 빌드하는 수를 각 리눅스 배포판마다
-제공하는 다른 릴리즈의 수와 곱하게 되면 이번에는 각 릴리즈들의 다른 빌드
-옵션의 악몽과 마주하게  것이다. 또한 각 리눅스 배포판들은 다른 하드웨어
-종류에(다른 프로세서 타입과 다른 옵션들) 맞춰져 있는 많은 다른 커널들을
-배포한다. 그러므로 한번의 배포에서조차 여러분들의 모듈은 여러 버젼을
-만들 필요가 있다.
-
-나를 믿어라. 여러분들은 이러한 종류의 배포를 지원하려고 시도한다면 시간이
-지나면 미칠지경이 될 것이다. 난 이러한 것을 오래전에 아주 어렵게 배웠다...
-
-
-
-변하지않는 커널 소스 인터페이스들
----------------------------------
-
-리눅스 커널 드라이버를 계속해서 메인 커널 트리에 반영하지 않고
-유지보수하려고 하는 사람들과 이 문제를 논의하게 되면 훨씬 더
-"논란의 여지가 많은" 주제가 될 것이다.
-
-리눅스 커널 개발은 끊임없이 빠른 속도로 이루어지고 있으며 결코
-느슨해진 적이 없다. 커널 개발자들이 현재 인터페이스들에서 버그를
-발견하거나 무엇인가 할 수 있는 더 좋은 방법을 찾게 되었다고 하자.
-그들이 발견한 것을 실행한다면 아마도 더 잘 동작하도록 현재 인터페이스들을
-수정하게 될 것이다. 그들이 그런 일을 하게되면 함수 이름들은 변하게 되고,
-구조체들은 늘어나거나 줄어들게 되고, 함수 파라미터들은 재작업될 것이다.
-이러한 일이 발생되면 커널 내에 이 인터페이스를 사용했던 인스턴스들이 동시에
-수정될 것이며 이러한 과정은 모든 것이 계속해서 올바르게 동작할 것이라는
-것을 보장한다.
-
-이러한 것의 한 예로써, 커널 내부의 USB 인터페이스들은 이 서브시스템이
-생긴 이후로 적어도 3번의 다른 재작업을 겪었다. 이 재작업들은 많은 다른
-문제들을 풀었다.
-   - 데이터 스트림들의 동기적인 모델에서 비동기적인 모델로의 변화. 이것은
-     많은 드라이버들의 복잡성을 줄이고 처리량을 향상시켜 현재는 거의 모든
-     USB 장치들의 거의 최대 속도로 실행되고 있다.
-   - USB 드라이버가 USB 코어로부터 데이터 패킷들을 할당받로록 한 변경으로
-     인해서 지금의 모든 드라이버들은 많은 문서화된 데드락을 수정하기 위하여
-     USB 코어에게 더 많은 정보를 제공해야만 한다.
-
-이것은 오랫동안 자신의 오래된 USB 인터페이스들을 유지해야 하는 closed 운영체제들과는
-완전히 반대되는 것이다. closed된 운영체제들은 새로운 개발자들에게 우연히 낡은
-인터페이스를 사용하게 할 기회를 주게되며, 적절하지 못한 방법으로 처리하게 되어
-운영체제의 안정성을 해치는 문제를 야기하게 된다.
-
-이 두가지의 예들 모두, 모든 개발자들은 꼭 이루어져야 하는 중요한 변화들이라고
-동의를 하였고 비교적 적은 고통으로 변경되어졌다. 리눅스가 변하지 않는 소스
-인터페이스를 고집한다면, 새로운 인터페이스가 만들어지게 되며 반면 기존의 오래된
-것들, 그리고 깨진 것들은 계속해서 유지되어야 하며 이러한 일들은 USB 개발자들에게
-또 다른 일거리를 주게 된다. 모든 리눅스 USB 개발자들에게 자신의 그들의 업무를
-마친 후 시간을 투자하여 아무 득도 없는 무료 봉사를 해달라고 하는 것은 가능성이
-희박한 일이다.
-
-보안 문제 역시 리눅스에게는 매우 중요하다. 보안 문제가 발견되면 그것은
-매우 짧은 시간 안에 수정된다. 보안 문제는 그 문제를 해결하기 위하여
-여러번 내부 커널 인터페이스들을 재작업하게 만들었다. 이러한 문제가
-발생하였을 때 그 인터페이스들을 사용하는 모든 드라이버들도 동시에
-수정되어 보안 문제가 앞으로 갑작스럽게 생기지는 않을 것이라는 것을
-보장한다. 내부 인터페이스들의 변경이 허락되지 않으면 이러한 종류의 보안
-문제를 수정하고 그것이 다시 발생하지 않을 것이라고 보장하는 것은 가능하지
-않을 것이다.
-
-커널 인터페이스들은 계속해서 정리되고 있다. 현재 인터페이스를 사용하는
-사람이 한명도 없다면 그것은 삭제된다. 이것은 커널이 가능한한 가장 작게
-유지되며 존재하는 모든 가능성이 있는 인터페이스들이 테스트된다는 것을
-보장한다(사용되지 않는 인터페이스들은 유효성 검증을 하기가 거의 불가능하다).
-
-
-무엇을 해야 하나
----------------
-자, 여러분이 메인 커널 트리에 있지 않은 리눅스 커널 드라이버를 가지고
-있다면 여러분은 즉, 개발자는 무엇을 해야 하나? 모든 배포판마다 다른
-커널 버젼을 위한 바이너리 드라이버를 배포하는 것은 악몽이며 계속해서
-변하고 있는 커널 인터페이스들의 맞처 유지보수하려고 시도하는 것은 힘든
-일이다.
-
-간단하다. 여러분의 커널 드라이버를 메인 커널 트리에 반영하라(우리는 여기서
-GPL을 따르는 배포 드라이버에 관해 얘기하고 있다는 것을 상기하라. 여러분의
-코드가 이러한 분류에 해당되지 않는다면 행운을 빈다. 여러분 스스로 어떻게든
-해야만 한다). 여러분의 드라이버가 트리에 있게되면 커널 인터페이스가
-변경되더라도 가장 먼저 커널에 변경을 가했던 사람에 의해서 수정될 것이다.
-이것은 여러분의 드라이버가 여러분의 별다른 노력없이 항상 빌드가 가능하며
-동작하는 것을 보장한다.
-
-메인 커널 트리에 여러분의 드라이버를 반영하면 얻게 되는 장점들은 다음과 같다.
-   - 관리에 드는 비용(원래 개발자의)은 줄어줄면서 드라이버의 질은 향상될 것이다.
-   - 다른 개발자들이 여러분의 드라이버에 기능들을 추가 할 것이다.
-   - 다른 사람들은 여러분의 드라이버에 버그를 발견하고 수정할 것이다.
-   - 다른 사람들은 여러분의 드라이버의 개선점을 찾을 줄 것이다.
-   - 외부 인터페이스 변경으로 인해 여러분의 드라이버의 수정이 필요하다면 다른
-     사람들이 드라이버를 업데이트할 것이다.
-   - 여러분의 드라이버는 별다른 노력 없이 모든 리눅스 배포판에  자동적으로
-     추가될 것이다.
-
-리눅스는 다른 운영 체제보다 "쉽게 쓸수 있는(out of the box)" 많은 다른 장치들을
-지원하고 어떤 다른 운영 체제보다 다양한 아키텍쳐위에서 이러한 장치들을 지원하기 때문에
-이러한 증명된 개발 모델은 틀림없이 바로 가고 있는 것이다.
-
-
-
-------
-
-이 문서의 초안을 검토해주고 코멘트 해준 Randy Dunlap, Andrew Morton, David Brownell,
-Hanna Linder, Robert Love, 그리고 Nishanth Aravamudan에게 감사한다.
diff --git a/Documentation/translations/ja_JP/HOWTO b/Documentation/translations/ja_JP/HOWTO
new file mode 100644
index 000000000000..b03fc8047f03
--- /dev/null
+++ b/Documentation/translations/ja_JP/HOWTO
@@ -0,0 +1,637 @@
+NOTE:
+This is a version of Documentation/HOWTO translated into Japanese.
+This document is maintained by Tsugikazu Shibata 
+and the JF Project team .
+If you find any difference between this document and the original file
+or a problem with the translation,
+please contact the maintainer of this file or JF project.
+
+Please also note that the purpose of this file is to be easier to read
+for non English (read: Japanese) speakers and is not intended as a
+fork. So if you have any comments or updates for this file, please try
+to update the original English file first.
+
+Last Updated: 2013/07/19
+==================================
+これは、
+linux-3.10/Documentation/HOWTO
+の和訳です。
+
+翻訳団体： JF プロジェクト < http://linuxjf.sourceforge.jp/ >
+翻訳日： 2013/7/19
+翻訳者： Tsugikazu Shibata 
+校正者： 松倉さん 
+         小林 雅典さん (Masanori Kobayasi) 
+         武井伸光さん、
+         かねこさん (Seiji Kaneko) 
+         野口さん (Kenji Noguchi) 
+         河内さん (Takayoshi Kochi) 
+         岩本さん (iwamoto) 
+         内田さん (Satoshi Uchida) 
+==================================
+
+Linux カーネル開発のやり方
+-------------------------------
+
+これは上のトピック( Linux カーネル開発のやり方)の重要な事柄を網羅した
+ドキュメントです。ここには Linux カーネル開発者になるための方法と
+Linux カーネル開発コミュニティと共に活動するやり方を学ぶ方法が含まれて
+います。カーネルプログラミングに関する技術的な項目に関することは何も含
+めないようにしていますが、カーネル開発者となるための正しい方向に向かう
+手助けになります。
+
+もし、このドキュメントのどこかが古くなっていた場合には、このドキュメン
+トの最後にリストしたメンテナにパッチを送ってください。
+
+はじめに
+---------
+
+あなたは　Linux カーネルの開発者になる方法を学びたいのでしょうか？　そ
+れともあなたは上司から「このデバイスの Linux ドライバを書くように」と
+言われているのでしょうか？　
+この文書の目的は、あなたが踏むべき手順と、コミュニティと一緒にうまく働
+くヒントを書き下すことで、あなたが知るべき全てのことを教えることです。
+また、このコミュニティがなぜ今うまくまわっているのかという理由の一部も
+説明しようと試みています。
+
+
+カーネルは 少量のアーキテクチャ依存部分がアセンブリ言語で書かれている
+以外は大部分は C 言語で書かれています。C言語をよく理解していることはカー
+ネル開発者には必要です。アーキテクチャ向けの低レベル部分の開発をするの
+でなければ、(どんなアーキテクチャでも)アセンブリ(訳注: 言語)は必要あり
+ません。以下の本は、C 言語の十分な知識や何年もの経験に取って代わるもの
+ではありませんが、少なくともリファレンスとしては良い本です。
+ - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
+ -『プログラミング言語Ｃ第2版』(B.W. カーニハン/D.M. リッチー著 石田晴久訳) [共立出版]
+ - "Practical C Programming" by Steve Oualline [O'Reilly]
+ - 『C実践プログラミング第3版』(Steve Oualline著 望月康司監訳 谷口功訳) [オライリージャパン]
+ - "C:  A Reference Manual" by Harbison and Steele [Prentice Hall]
+ - 『新・詳説 C 言語 H&S リファレンス』
+       (サミュエル P ハービソン/ガイ L スティール共著 斉藤 信男監訳)[ソフトバンク]
+
+カーネルは GNU C と GNU ツールチェインを使って書かれています。カーネル
+は ISO C89 仕様に準拠して書く一方で、標準には無い言語拡張を多く使って
+います。カーネルは標準 C ライブラリとは関係がないといった、C 言語フリー
+スタンディング環境です。そのため、C の標準で使えないものもあります。任
+意の long long の除算や浮動小数点は使えません。
+ときどき、カーネルがツールチェインや C 言語拡張に置いている前提がどう
+なっているのかわかりにくいことがあり、また、残念なことに決定的なリファ
+レンスは存在しません。情報を得るには、gcc の info ページ( info gcc )を
+見てください。
+
+あなたは既存の開発コミュニティと一緒に作業する方法を学ぼうとしているこ
+とに留意してください。そのコミュニティは、コーディング、スタイル、
+開発手順について高度な標準を持つ、多様な人の集まりです。
+地理的に分散した大規模なチームに対してもっともうまくいくとわかったこと
+をベースにしながら、これらの標準は長い時間をかけて築かれてきました。
+これらはきちんと文書化されていますから、事前にこれらの標準についてでき
+るだけたくさん学んでください。また皆があなたやあなたの会社のやり方に合わ
+せてくれると思わないでください。
+
+法的問題
+------------
+
+Linux カーネルのソースコードは GPL ライセンスの下でリリースされていま
+す。ライセンスの詳細については、ソースツリーのメインディレクトリに存在
+する、COPYING のファイルを見てください。もしライセンスについてさらに質
+問があれば、Linux Kernel メーリングリストに質問するのではなく、どうぞ
+法律家に相談してください。メーリングリストの人達は法律家ではなく、法的
+問題については彼らの声明はあてにするべきではありません。
+
+GPL に関する共通の質問や回答については、以下を参照してください。
+	http://www.gnu.org/licenses/gpl-faq.html
+
+ドキュメント
+------------
+
+Linux カーネルソースツリーは幅広い範囲のドキュメントを含んでおり、それ
+らはカーネルコミュニティと会話する方法を学ぶのに非常に貴重なものです。
+新しい機能がカーネルに追加される場合、その機能の使い方について説明した
+新しいドキュメントファイルも追加することを勧めます。
+カーネルの変更が、カーネルがユーザ空間に公開しているインターフェイスの
+変更を引き起こす場合、その変更を説明するマニュアルページのパッチや情報
+をマニュアルページのメンテナ mtk.manpages@gmail.com に送り、CC を
+linux-api@ver.kernel.org に送ることを勧めます。
+
+以下はカーネルソースツリーに含まれている読んでおくべきファイルの一覧で
+す-
+
+  README
+    このファイルは Linuxカーネルの簡単な背景とカーネルを設定(訳注
+    configure )し、生成(訳注 build )するために必要なことは何かが書かれ
+    ています。カーネルに関して初めての人はここからスタートすると良いで
+    しょう。
+
+  Documentation/Changes
+     このファイルはカーネルをうまく生成(訳注 build )し、走らせるのに最
+     小限のレベルで必要な数々のソフトウェアパッケージの一覧を示してい
+     ます。
+
+  Documentation/process/coding-style.rst
+    これは Linux カーネルのコーディングスタイルと背景にある理由を記述
+    しています。全ての新しいコードはこのドキュメントにあるガイドライン
+    に従っていることを期待されています。大部分のメンテナはこれらのルー
+    ルに従っているものだけを受け付け、多くの人は正しいスタイルのコード
+    だけをレビューします。
+
+  Documentation/process/submitting-patches.rst
+  Documentation/process/submitting-drivers.rst
+     これらのファイルには、どうやってうまくパッチを作って投稿するかに
+     ついて非常に詳しく書かれており、以下を含みます(これだけに限らない
+     けれども)
+        - Email に含むこと
+        - Email の形式
+        - だれに送るか
+     これらのルールに従えばうまくいくことを保証することではありません
+     が (すべてのパッチは内容とスタイルについて精査を受けるので)、
+     ルールに従わなければ間違いなくうまくいかないでしょう。
+
+     この他にパッチを作る方法についてのよくできた記述は-
+
+	"The Perfect Patch"
+		http://www.ozlabs.org/~akpm/stuff/tpp.txt
+	"Linux kernel patch submission format"
+		http://linux.yyz.us/patch-format.html
+
+  Documentation/process/stable-api-nonsense.rst
+     このファイルはカーネルの中に不変のAPIを持たないことにした意識的な
+     決断の背景にある理由について書かれています。以下のようなことを含
+     んでいます-
+       - サブシステムとの間に層を作ること(コンパチビリティのため?)
+       - オペレーティングシステム間のドライバの移植性
+       - カーネルソースツリーの素早い変更を遅らせる(もしくは素早い変更
+         を妨げる)
+     このドキュメントは Linux 開発の思想を理解するのに非常に重要です。
+     そして、他のOSでの開発者が Linux に移る時にとても重要です。
+
+  Documentation/admin-guide/security-bugs.rst
+    もし Linux カーネルでセキュリティ問題を発見したように思ったら、こ
+    のドキュメントのステップに従ってカーネル開発者に連絡し、問題解決を
+    支援してください。
+
+  Documentation/process/management-style.rst
+    このドキュメントは Linux カーネルのメンテナ達がどう行動するか、
+    彼らの手法の背景にある共有されている精神について記述しています。こ
+    れはカーネル開発の初心者なら（もしくは、単に興味があるだけの人でも）
+    重要です。なぜならこのドキュメントは、カーネルメンテナ達の独特な
+    行動についての多くの誤解や混乱を解消するからです。
+
+  Documentation/process/stable-kernel-rules.rst
+    このファイルはどのように stable カーネルのリリースが行われるかのルー
+    ルが記述されています。そしてこれらのリリースの中のどこかで変更を取
+    り入れてもらいたい場合に何をすれば良いかが示されています。
+
+  Documentation/process/kernel-docs.rst
+　　カーネル開発に付随する外部ドキュメントのリストです。もしあなたが
+    探しているものがカーネル内のドキュメントでみつからなかった場合、
+    このリストをあたってみてください。
+
+  Documentation/process/applying-patches.rst
+    パッチとはなにか、パッチをどうやって様々なカーネルの開発ブランチに
+    適用するのかについて正確に記述した良い入門書です。
+
+カーネルはソースコードから自動的に生成可能な多数のドキュメントを自分自
+身でもっています。これにはカーネル内 API のすべての記述や、どう正しく
+ロックをかけるかの規則が含まれます。このドキュメントは
+Documentation/DocBook/ ディレクトリに作られ、以下のように
+	make pdfdocs
+	make psdocs
+	make htmldocs
+	make mandocs
+コマンドを実行するとメインカーネルのソースディレクトリから
+それぞれ、PDF, Postscript, HTML, man page の形式で生成されます。
+
+カーネル開発者になるには
+---------------------------
+
+もしあなたが、Linux カーネル開発について何も知らないならば、
+KernelNewbies プロジェクトを見るべきです
+	http://kernelnewbies.org
+
+このサイトには役に立つメーリングリストがあり、基本的なカーネル開発に関
+するほとんどどんな種類の質問もできます (既に回答されているようなことを
+聞く前にまずはアーカイブを調べてください)。
+またここには、リアルタイムで質問を聞くことができる IRC チャネルや、Linux
+カーネルの開発に関して学ぶのに便利なたくさんの役に立つドキュメントがあ
+ります。
+
+web サイトには、コードの構成、サブシステム、現在存在するプロジェクト(ツ
+リーにあるもの無いものの両方)の基本的な管理情報があります。
+ここには、また、カーネルのコンパイルのやり方やパッチの当て方などの間接
+的な基本情報も記述されています。
+
+あなたがどこからスタートして良いかわからないが、Linux カーネル開発コミュ
+ニティに参加して何かすることをさがしている場合には、Linux kernel
+Janitor's プロジェクトにいけば良いでしょう -
+	http://kernelnewbies.org/KernelJanitors
+ここはそのようなスタートをするのにうってつけの場所です。ここには、
+Linux カーネルソースツリーの中に含まれる、きれいにし、修正しなければな
+らない、単純な問題のリストが記述されています。このプロジェクトに関わる
+開発者と一緒に作業することで、あなたのパッチを Linuxカーネルツリーに入
+れるための基礎を学ぶことができ、そしてもしあなたがまだアイディアを持っ
+ていない場合には、次にやる仕事の方向性が見えてくるかもしれません。
+
+もしあなたが、すでにひとまとまりコードを書いていて、カーネルツリーに入
+れたいと思っていたり、それに関する適切な支援を求めたい場合、カーネル
+メンターズプロジェクトはそのような皆さんを助けるためにできました。
+ここにはメーリングリストがあり、以下から参照できます
+	http://selenic.com/mailman/listinfo/kernel-mentors
+
+実際に Linux カーネルのコードについて修正を加える前に、どうやってその
+コードが動作するのかを理解することが必要です。そのためには、特別なツー
+ルの助けを借りてでも、それを直接よく読むことが最良の方法です(ほとんど
+のトリッキーな部分は十分にコメントしてありますから)。そういうツールで
+特におすすめなのは、Linux クロスリファレンスプロジェクトです。これは、
+自己参照方式で、索引がついた web 形式で、ソースコードを参照することが
+できます。この最新の素晴しいカーネルコードのリポジトリは以下で見つかり
+ます-
+	http://lxr.free-electrons.com/
+
+開発プロセス
+-----------------------
+
+Linux カーネルの開発プロセスは現在幾つかの異なるメインカーネル「ブラン
+チ」と多数のサブシステム毎のカーネルブランチから構成されます。
+これらのブランチとは-
+  - メインの 3.x カーネルツリー
+  - 3.x.y -stable カーネルツリー
+  - 3.x -git カーネルパッチ
+  - サブシステム毎のカーネルツリーとパッチ
+  - 統合テストのための 3.x -next カーネルツリー
+
+3.x カーネルツリー
+-----------------
+
+3.x カーネルは Linus Torvalds によってメンテナンスされ、kernel.org
+の pub/linux/kernel/v3.x/ ディレクトリに存在します。この開発プロセスは
+以下のとおり-
+
+  - 新しいカーネルがリリースされた直後に、2週間の特別期間が設けられ、
+    この期間中に、メンテナ達は Linus に大きな差分を送ることができます。
+    このような差分は通常 -next カーネルに数週間含まれてきたパッチです。
+    大きな変更は git(カーネルのソース管理ツール、詳細は
+    http://git-scm.com/ 参照) を使って送るのが好ましいやり方ですが、パッ
+    チファイルの形式のまま送るのでも十分です。
+
+  - 2週間後、-rc1 カーネルがリリースされ、この後にはカーネル全体の安定
+    性に影響をあたえるような新機能は含まない類のパッチしか取り込むこと
+    はできません。新しいドライバ(もしくはファイルシステム)のパッチは
+    -rc1 の後で受け付けられることもあることを覚えておいてください。な
+    ぜなら、変更が独立していて、追加されたコードの外の領域に影響を与え
+    ない限り、退行のリスクは無いからです。-rc1 がリリースされた後、
+    Linus へパッチを送付するのに git を使うこともできますが、パッチは
+    レビューのために、パブリックなメーリングリストへも同時に送る必要が
+    あります。
+
+  - 新しい -rc は Linus が、最新の git ツリーがテスト目的であれば十分
+    に安定した状態にあると判断したときにリリースされます。目標は毎週新
+    しい -rc カーネルをリリースすることです。
+
+  - このプロセスはカーネルが 「準備ができた」と考えられるまで継続しま
+    す。このプロセスはだいたい 6週間継続します。
+
+Andrew Morton が Linux-kernel メーリングリストにカーネルリリースについ
+て書いたことをここで言っておくことは価値があります-
+  「カーネルがいつリリースされるかは誰も知りません。なぜなら、これは現
+  実に認識されたバグの状況によりリリースされるのであり、前もって決めら
+  れた計画によってリリースされるものではないからです。」
+
+3.x.y -stable カーネルツリー
+---------------------------
+
+バージョン番号が3つの数字に分かれているカーネルは -stable カーネルです。
+これには、3.x カーネルで見つかったセキュリティ問題や重大な後戻りに対
+する比較的小さい重要な修正が含まれます。
+
+これは、開発/実験的バージョンのテストに協力することに興味が無く、
+最新の安定したカーネルを使いたいユーザに推奨するブランチです。
+
+もし、3.x.y カーネルが存在しない場合には、番号が一番大きい 3.x が
+最新の安定版カーネルです。
+
+3.x.y は "stable" チーム  でメンテされており、必
+要に応じてリリースされます。通常のリリース期間は 2週間毎ですが、差し迫っ
+た問題がなければもう少し長くなることもあります。セキュリティ関連の問題
+の場合はこれに対してだいたいの場合、すぐにリリースがされます。
+
+カーネルツリーに入っている、Documentation/process/stable-kernel-rules.rst ファ
+イルにはどのような種類の変更が -stable ツリーに受け入れ可能か、またリ
+リースプロセスがどう動くかが記述されています。
+
+3.x -git パッチ
+------------------
+
+git リポジトリで管理されているLinus のカーネルツリーの毎日のスナップ
+ショットがあります。(だから -git という名前がついています)。これらのパッ
+チはおおむね毎日リリースされており、Linus のツリーの現状を表します。こ
+れは -rc カーネルと比べて、パッチが大丈夫かどうかも確認しないで自動的
+に生成されるので、より実験的です。
+
+サブシステム毎のカーネルツリーとパッチ
+-------------------------------------------
+
+それぞれのカーネルサブシステムのメンテナ達は --- そして多くのカーネル
+サブシステムの開発者達も --- 各自の最新の開発状況をソースリポジトリに
+公開しています。そのため、自分とは異なる領域のカーネルで何が起きている
+かを他の人が見られるようになっています。開発が早く進んでいる領域では、
+開発者は自身の投稿がどのサブシステムカーネルツリーを元にしているか質問
+されるので、その投稿とすでに進行中の他の作業との衝突が避けられます。
+
+大部分のこれらのリポジトリは git ツリーです。しかしその他の SCM や
+quilt シリーズとして公開されているパッチキューも使われています。これら
+のサブシステムリポジトリのアドレスは MAINTAINERS ファイルにリストされ
+ています。これらの多くは http://git.kernel.org/ で参照することができま
+す。
+
+提案されたパッチがこのようなサブシステムツリーにコミットされる前に、メー
+リングリストで事前にレビューにかけられます（以下の対応するセクションを
+参照）。いくつかのカーネルサブシステムでは、このレビューは patchwork
+というツールによって追跡されます。Patchwork は web インターフェイスに
+よってパッチ投稿の表示、パッチへのコメント付けや改訂などができ、そして
+メンテナはパッチに対して、レビュー中、受付済み、拒否というようなマーク
+をつけることができます。大部分のこれらの patchwork のサイトは
+http://patchwork.kernel.org/ でリストされています。
+
+統合テストのための 3.x -next カーネルツリー
+---------------------------------------------
+
+サブシステムツリーの更新内容がメインラインの 3.x ツリーにマージされ
+る前に、それらは統合テストされる必要があります。この目的のため、実質的
+に全サブシステムツリーからほぼ毎日プルされてできる特別なテスト用のリ
+ポジトリが存在します-
+       http://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
+
+このやり方によって、-next カーネルは次のマージ機会でどんなものがメイン
+ラインカーネルにマージされるか、おおまかなの展望を提供します。-next 
+カーネルの実行テストを行う冒険好きなテスターは大いに歓迎されます
+
+バグレポート
+-------------
+
+bugzilla.kernel.org は Linux カーネル開発者がカーネルのバグを追跡する
+場所です。ユーザは見つけたバグの全てをこのツールで報告すべきです。
+どう kernel bugzilla を使うかの詳細は、以下を参照してください-
+	http://bugzilla.kernel.org/page.cgi?id=faq.html
+メインカーネルソースディレクトリにあるファイル admin-guide/reporting-bugs.rst はカーネ
+ルバグらしいものについてどうレポートするかの良いテンプレートであり、問
+題の追跡を助けるためにカーネル開発者にとってどんな情報が必要なのかの詳
+細が書かれています。
+
+バグレポートの管理
+-------------------
+
+あなたのハッキングのスキルを訓練する最高の方法のひとつに、他人がレポー
+トしたバグを修正することがあります。あなたがカーネルをより安定化させる
+こに寄与するということだけでなく、あなたは 現実の問題を修正することを
+学び、自分のスキルも強化でき、また他の開発者があなたの存在に気がつき
+ます。バグを修正することは、多くの開発者の中から自分が功績をあげる最善
+の道です、なぜなら多くの人は他人のバグの修正に時間を浪費することを好ま
+ないからです。
+
+すでにレポートされたバグのために仕事をするためには、
+http://bugzilla.kernel.org に行ってください。もし今後のバグレポートに
+ついてアドバイスを受けたいのであれば、bugme-new メーリングリスト(新し
+いバグレポートだけがここにメールされる) または bugme-janitor メーリン
+グリスト(bugzilla の変更毎にここにメールされる)を購読できます。
+
+	http://lists.linux-foundation.org/mailman/listinfo/bugme-new
+	http://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
+
+メーリングリスト
+-------------
+
+上のいくつかのドキュメントで述べていますが、コアカーネル開発者の大部分
+は Linux kernel メーリングリストに参加しています。このリストの登録/脱
+退の方法については以下を参照してください-
+	http://vger.kernel.org/vger-lists.html#linux-kernel
+
+このメーリングリストのアーカイブは web 上の多数の場所に存在します。こ
+れらのアーカイブを探すにはサーチエンジンを使いましょう。例えば-
+	http://dir.gmane.org/gmane.linux.kernel
+
+リストに投稿する前にすでにその話題がアーカイブに存在するかどうかを検索
+することを是非やってください。多数の事がすでに詳細に渡って議論されて
+おり、アーカイブにのみ記録されています。
+
+大部分のカーネルサブシステムも自分の個別の開発を実施するメーリングリス
+トを持っています。個々のグループがどんなリストを持っているかは、
+MAINTAINERS ファイルにリストがありますので参照してください。
+
+多くのリストは kernel.org でホストされています。これらの情報は以下にあ
+ります-
+	http://vger.kernel.org/vger-lists.html
+
+メーリングリストを使う場合、良い行動習慣に従うようにしましょう。
+少し安っぽいが、以下の URL は上のリスト(や他のリスト)で会話する場合の
+シンプルなガイドラインを示しています-
+	http://www.albion.com/netiquette/
+
+もし複数の人があなたのメールに返事をした場合、CC: で受ける人のリストは
+だいぶ多くなるでしょう。良い理由がない場合、CC: リストから誰かを削除を
+しないように、また、メーリングリストのアドレスだけにリプライすることの
+ないようにしましょう。1つは送信者から、もう1つはリストからのように、メー
+ルを2回受けることになってもそれに慣れ、しゃれたメールヘッダーを追加し
+てこの状態を変えようとしないように。人々はそのようなことは好みません。
+
+今までのメールでのやりとりとその間のあなたの発言はそのまま残し、
+"John Kernelhacker wrote ...:" の行をあなたのリプライの先頭行にして、
+メールの先頭でなく、各引用行の間にあなたの言いたいことを追加するべきで
+す。
+
+もしパッチをメールに付ける場合は、Documentation/process/submitting-patches.rst に提
+示されているように、それは プレーンな可読テキストにすることを忘れない
+ようにしましょう。カーネル開発者は 添付や圧縮したパッチを扱いたがりま
+せん-
+彼らはあなたのパッチの行毎にコメントを入れたいので、そのためにはそうす
+るしかありません。あなたのメールプログラムが空白やタブを圧縮しないよう
+に確認した方が良いです。最初の良いテストとしては、自分にメールを送って
+みて、そのパッチを自分で当ててみることです。もしそれがうまく行かないな
+ら、あなたのメールプログラムを直してもらうか、正しく動くように変えるべ
+きです。
+
+とりわけ、他の登録者に対する尊敬を表すようにすることを覚えておいてくだ
+さい。
+
+コミュニティと共に働くこと
+--------------------------
+
+カーネルコミュニティのゴールは可能なかぎり最高のカーネルを提供すること
+です。あなたがパッチを受け入れてもらうために投稿した場合、それは、技術
+的メリットだけがレビューされます。その際、あなたは何を予想すべきでしょ
+うか?
+  - 批判
+  - コメント
+  - 変更の要求
+  - パッチの正当性の証明要求
+  - 沈黙
+
+思い出してください、ここはあなたのパッチをカーネルに入れる話です。あ
+なたは、あなたのパッチに対する批判とコメントを受け入れるべきで、それら
+を技術的レベルで評価して、パッチを再作成するか、なぜそれらの変更をすべ
+きでないかを明確で簡潔な理由の説明を提供してください。
+もし、あなたのパッチに何も反応がない場合、たまにはメールの山に埋もれて
+見逃され、あなたの投稿が忘れられてしまうこともあるので、数日待って再度
+投稿してください。
+
+あなたがやるべきでないものは?
+  - 質問なしにあなたのパッチが受け入れられると想像すること
+  - 守りに入ること
+  - コメントを無視すること
+  - 要求された変更を何もしないでパッチを出し直すこと
+
+可能な限り最高の技術的解決を求めているコミュニティでは、パッチがどのく
+らい有益なのかについては常に異なる意見があります。あなたは協調的である
+べきですし、また、あなたのアイディアをカーネルに対してうまく合わせるよ
+うにすることが望まれています。もしくは、最低限あなたのアイディアがそれ
+だけの価値があるとすすんで証明するようにしなければなりません。
+正しい解決に向かって進もうという意志がある限り、間違うことがあっても許
+容されることを忘れないでください。
+
+あなたの最初のパッチに単に 1ダースもの修正を求めるリストの返答になるこ
+とも普通のことです。これはあなたのパッチが受け入れられないということで
+は *ありません*、そしてあなた自身に反対することを意味するのでも *ありま
+せん*。単に自分のパッチに対して指摘された問題を全て修正して再送すれば
+良いのです。
+
+
+カーネルコミュニティと企業組織のちがい
+-----------------------------------------------------------------
+
+カーネルコミュニティは大部分の伝統的な会社の開発環境とは異ったやり方で
+動いています。以下は問題を避けるためにできると良いことのリストです-
+
+  あなたの提案する変更について言うときのうまい言い方：
+
+    - "これは複数の問題を解決します"
+    - "これは2000行のコードを削除します"
+    - "以下のパッチは、私が言おうとしていることを説明するものです"
+    - "私はこれを5つの異なるアーキテクチャでテストしたのですが..."
+    - "以下は一連の小さなパッチ群ですが..."
+    - "これは典型的なマシンでの性能を向上させます.."
+
+  やめた方が良い悪い言い方：
+
+    - このやり方で AIX/ptx/Solaris ではできたので、できるはずだ
+    - 私はこれを20年もの間やってきた、だから
+    - これは、私の会社が金儲けをするために必要だ
+    - これは我々のエンタープライズ向け商品ラインのためである
+    - これは 私が自分のアイディアを記述した、1000ページの設計資料である
+    - 私はこれについて、6ケ月作業している。
+    - 以下は ... に関する5000行のパッチです
+    - 私は現在のぐちゃぐちゃを全部書き直した、それが以下です...
+    - 私は〆切がある、そのためこのパッチは今すぐ適用される必要がある
+
+カーネルコミュニティが大部分の伝統的なソフトウェアエンジニアリングの労
+働環境と異なるもう一つの点は、やりとりに顔を合わせないということです。
+email と irc を第一のコミュニケーションの形とする一つの利点は、性別や
+民族の差別がないことです。Linux カーネルの職場環境は女性や少数民族を受
+容します。なぜなら、email アドレスによってのみあなたが認識されるからで
+す。
+国際的な側面からも活動領域を均等にするようにします。なぜならば、あなた
+は人の名前で性別を想像できないからです。ある男性が アンドレアという名
+前で、女性の名前は パット かもしれません (訳注 Andrea は米国では女性、
+それ以外(欧州など)では男性名として使われることが多い。同様に、Pat は
+Patricia (主に女性名)や Patrick (主に男性名)の略称)。
+Linux カーネルの活動をして、意見を表明したことがある大部分の女性は、前
+向きな経験をもっています。
+
+言葉の壁は英語が得意でない一部の人には問題になります。
+メーリングリストの中できちんとアイディアを交換するには、相当うまく英語
+を操れる必要があることもあります。そのため、あなたは自分のメール
+を送る前に英語で意味が通じているかをチェックすることをお薦めします。
+
+変更を分割する
+---------------------
+
+Linux カーネルコミュニティは、一度に大量のコードの塊を喜んで受容するこ
+とはありません。変更は正確に説明される必要があり、議論され、小さい、個
+別の部分に分割する必要があります。これはこれまで多くの会社がやり慣れて
+きたことと全く正反対のことです。あなたのプロポーザルは、開発プロセスのと
+ても早い段階から紹介されるべきです。そうすれば あなたは自分のやってい
+ることにフィードバックを得られます。これは、コミュニティからみれば、あ
+なたが彼らと一緒にやっているように感じられ、単にあなたの提案する機能の
+ゴミ捨て場として使っているのではない、と感じられるでしょう。
+しかし、一度に 50 もの email をメーリングリストに送りつけるようなことは
+やってはいけません、あなたのパッチ群はいつもどんな時でもそれよりは小さ
+くなければなりません。
+
+パッチを分割する理由は以下です-
+
+1) 小さいパッチはあなたのパッチが適用される見込みを大きくします、カー
+   ネルの人達はパッチが正しいかどうかを確認する時間や労力をかけないか
+   らです。5行のパッチはメンテナがたった1秒見るだけで適用できます。
+   しかし、500行のパッチは、正しいことをレビューするのに数時間かかるか
+   もしれません(時間はパッチのサイズなどにより指数関数に比例してかかり
+   ます)
+
+   小さいパッチは何かあったときにデバッグもとても簡単になります。パッ
+   チを1個1個取り除くのは、とても大きなパッチを当てた後に(かつ、何かお
+   かしくなった後で)解剖するのに比べればとても簡単です。
+
+2) 小さいパッチを送るだけでなく、送るまえに、書き直して、シンプルにす
+   る(もしくは、単に順番を変えるだけでも)ことも、とても重要です。
+
+以下はカーネル開発者の Al Viro のたとえ話です：
+
+        "生徒の数学の宿題を採点する先生のことを考えてみてください、先
+        生は生徒が解に到達するまでの試行錯誤を見たいとは思わないでしょ
+        う。先生は簡潔な最高の解を見たいのです。良い生徒はこれを知って
+        おり、そして最終解の前の中間作業を提出することは決してないので
+        す"
+
+        カーネル開発でもこれは同じです。メンテナ達とレビューア達は、
+        問題を解決する解の背後になる思考プロセスを見たいとは思いません。
+        彼らは単純であざやかな解決方法を見たいのです。
+
+あざやかな解を説明するのと、コミュニティと共に仕事をし、未解決の仕事を
+議論することのバランスをキープするのは難しいかもしれません。
+ですから、開発プロセスの早期段階で改善のためのフィードバックをもらうよ
+うにするのも良いですが、変更点を小さい部分に分割して全体ではまだ完成し
+ていない仕事を(部分的に)取り込んでもらえるようにすることも良いことです。
+
+また、でき上がっていないものや、"将来直す" ようなパッチを、本流に含め
+てもらうように送っても、それは受け付けられないことを理解してください。
+
+あなたの変更を正当化する
+-------------------
+
+あなたのパッチを分割するのと同時に、なぜその変更を追加しなければならな
+いかを Linux コミュニティに知らせることはとても重要です。新機能は必要
+性と有用性で正当化されなければなりません。
+
+あなたの変更の説明
+--------------------
+
+あなたのパッチを送付する場合には、メールの中のテキストで何を言うかにつ
+いて、特別に注意を払ってください。この情報はパッチの ChangeLog に使わ
+れ、いつも皆がみられるように保管されます。これは次のような項目を含め、
+パッチを完全に記述するべきです-
+
+  - なぜ変更が必要か
+  - パッチ全体の設計アプローチ
+  - 実装の詳細
+  - テスト結果
+
+これについて全てがどのようにあるべきかについての詳細は、以下のドキュメ
+ントの ChangeLog セクションを見てください-
+  "The Perfect Patch"
+      http://www.ozlabs.org/~akpm/stuff/tpp.txt
+
+これらのどれもが、時にはとても困難です。これらの慣例を完璧に実施するに
+は数年かかるかもしれません。これは継続的な改善のプロセスであり、そのた
+めには多数の忍耐と決意を必要とするものです。でも、諦めないで、これは可
+能なことです。多数の人がすでにできていますし、彼らも皆最初はあなたと同
+じところからスタートしたのですから。
+
+Paolo Ciarrocchi に感謝、彼は彼の書いた "Development Process"
+(http://lwn.net/Articles/94386/) セクションをこのテキストの原型にする
+ことを許可してくれました。Rundy Dunlap と Gerrit Huizenga はメーリング
+リストでやるべきこととやってはいけないことのリストを提供してくれました。
+以下の人々のレビュー、コメント、貢献に感謝。
+Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers,
+Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi
+Kleen, Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop,
+David A. Wheeler, Junio Hamano, Michael Kerrisk, と Alex Shepard
+彼らの支援なしでは、このドキュメントはできなかったでしょう。
+
+Maintainer: Greg Kroah-Hartman 
diff --git a/Documentation/translations/ja_JP/SubmitChecklist b/Documentation/translations/ja_JP/SubmitChecklist
new file mode 100644
index 000000000000..60c7c35ac517
--- /dev/null
+++ b/Documentation/translations/ja_JP/SubmitChecklist
@@ -0,0 +1,111 @@
+NOTE:
+This is a version of Documentation/process/submit-checklist.rst into Japanese.
+This document is maintained by Takenori Nagano 
+and the JF Project team .
+If you find any difference between this document and the original file
+or a problem with the translation,
+please contact the maintainer of this file or JF project.
+
+Please also note that the purpose of this file is to be easier to read
+for non English (read: Japanese) speakers and is not intended as a
+fork. So if you have any comments or updates of this file, please try
+to update the original English file first.
+
+Last Updated: 2008/07/14
+==================================
+これは、
+linux-2.6.26/Documentation/process/submit-checklist.rst の和訳です。
+
+翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
+翻訳日： 2008/07/14
+翻訳者： Takenori Nagano 
+校正者： Masanori Kobayashi さん 
+==================================
+
+
+Linux カーネルパッチ投稿者向けチェックリスト
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+本書では、パッチをより素早く取り込んでもらいたい開発者が実践すべき基本的な事柄
+をいくつか紹介します。ここにある全ての事柄は、Documentation/process/submitting-patches.rst
+などのLinuxカーネルパッチ投稿に際しての心得を補足するものです。
+
+ 1: 妥当なCONFIGオプションや変更されたCONFIGオプション、つまり =y, =m, =n
+    全てで正しくビルドできることを確認してください。その際、gcc及びリンカが
+    warningやerrorを出していないことも確認してください。
+
+ 2: allnoconfig, allmodconfig オプションを用いて正しくビルドできることを
+    確認してください。
+
+ 3: 手許のクロスコンパイルツールやOSDLのPLMのようなものを用いて、複数の
+    アーキテクチャにおいても正しくビルドできることを確認してください。
+
+ 4: 64bit長の'unsigned long'を使用しているppc64は、クロスコンパイルでの
+    チェックに適当なアーキテクチャです。
+
+ 5: カーネルコーディングスタイルに準拠しているかどうか確認してください(!)
+
+ 6: CONFIGオプションの追加・変更をした場合には、CONFIGメニューが壊れていない
+    ことを確認してください。
+
+ 7: 新しくKconfigのオプションを追加する際には、必ずそのhelpも記述してください。
+
+ 8: 適切なKconfigの依存関係を考えながら慎重にチェックしてください。
+    ただし、この作業はマシンを使ったテストできちんと行うのがとても困難です。
+    うまくやるには、自分の頭で考えることです。
+
+ 9: sparseを利用してちゃんとしたコードチェックをしてください。
+
+10: 'make checkstack' と 'make namespacecheck' を利用し、問題が発見されたら
+    修正してください。'make checkstack' は明示的に問題を示しませんが、どれか
+    １つの関数が512バイトより大きいスタックを使っていれば、修正すべき候補と
+    なります。
+
+11: グローバルなkernel API を説明する kernel-doc をソースの中に含めてください。
+    ( staticな関数においては必須ではありませんが、含めてもらっても結構です )
+    そして、'make htmldocs' もしくは 'make mandocs' を利用して追記した
+    ドキュメントのチェックを行い、問題が見つかった場合には修正を行ってください。
+
+12: CONFIG_PREEMPT, CONFIG_DEBUG_PREEMPT, CONFIG_DEBUG_SLAB,
+    CONFIG_DEBUG_PAGEALLOC, CONFIG_DEBUG_MUTEXES, CONFIG_DEBUG_SPINLOCK,
+    CONFIG_DEBUG_ATOMIC_SLEEP これら全てを同時に有効にして動作確認を
+    行ってください。
+
+13: CONFIG_SMP, CONFIG_PREEMPT を有効にした場合と無効にした場合の両方で
+    ビルドした上、動作確認を行ってください。
+
+14: もしパッチがディスクのI/O性能などに影響を与えるようであれば、
+    'CONFIG_LBDAF'オプションを有効にした場合と無効にした場合の両方で
+    テストを実施してみてください。
+
+15: lockdepの機能を全て有効にした上で、全てのコードパスを評価してください。
+
+16: /proc に新しいエントリを追加した場合には、Documentation/ 配下に
+    必ずドキュメントを追加してください。
+
+17: 新しいブートパラメータを追加した場合には、
+    必ずDocumentation/admin-guide/kernel-parameters.rst に説明を追加してください。
+
+18: 新しくmoduleにパラメータを追加した場合には、MODULE_PARM_DESC()を
+    利用して必ずその説明を記述してください。
+
+19: 新しいuserspaceインタフェースを作成した場合には、Documentation/ABI/ に
+    Documentation/ABI/README を参考にして必ずドキュメントを追加してください。
+
+20: 'make headers_check'を実行して全く問題がないことを確認してください。
+
+21: 少なくともslabアロケーションとpageアロケーションに失敗した場合の
+    挙動について、fault-injectionを利用して確認してください。
+    Documentation/fault-injection/ を参照してください。
+
+    追加したコードがかなりの量であったならば、サブシステム特有の
+    fault-injectionを追加したほうが良いかもしれません。
+
+22: 新たに追加したコードは、`gcc -W'でコンパイルしてください。
+    このオプションは大量の不要なメッセージを出力しますが、
+    "warning: comparison between signed and unsigned" のようなメッセージは、
+    バグを見つけるのに役に立ちます。
+
+23: 投稿したパッチが -mm パッチセットにマージされた後、全ての既存のパッチや
+    VM, VFS およびその他のサブシステムに関する様々な変更と、現時点でも共存
+    できることを確認するテストを行ってください。
diff --git a/Documentation/translations/ja_JP/SubmittingPatches b/Documentation/translations/ja_JP/SubmittingPatches
new file mode 100644
index 000000000000..02139656463e
--- /dev/null
+++ b/Documentation/translations/ja_JP/SubmittingPatches
@@ -0,0 +1,719 @@
+NOTE:
+This is a version of Documentation/process/submitting-patches.rst into Japanese.
+This document is maintained by Keiichi KII 
+and the JF Project team .
+If you find any difference between this document and the original file
+or a problem with the translation,
+please contact the maintainer of this file or JF project.
+
+Please also note that the purpose of this file is to be easier to read
+for non English (read: Japanese) speakers and is not intended as a
+fork. So if you have any comments or updates of this file, please try
+to update the original English file first.
+
+Last Updated: 2011/06/09
+
+==================================
+これは、
+linux-2.6.39/Documentation/process/submitting-patches.rst の和訳
+です。
+翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
+翻訳日： 2011/06/09
+翻訳者： Keiichi Kii 
+校正者： Masanari Kobayashi さん 
+         Matsukura さん 
+         Takeshi Hamasaki さん 
+==================================
+
+        Linux カーネルに変更を加えるための Howto
+        又は
+        かの Linus Torvalds の取り扱い説明書
+
+Linux カーネルに変更を加えたいと思っている個人又は会社にとって、パッ
+チの投稿に関連した仕組みに慣れていなければ、その過程は時々みなさんを
+おじけづかせることもあります。この文章はあなたの変更を大いに受け入れ
+てもらえやすくする提案を集めたものです。
+
+コードを投稿する前に、Documentation/process/submit-checklist.rst の項目リストに目
+を通してチェックしてください。もしあなたがドライバーを投稿しようとし
+ているなら、Documentation/process/submitting-drivers.rst にも目を通してください。
+
+--------------------------------------------
+セクション1 パッチの作り方と送り方
+--------------------------------------------
+
+1) 「 diff -up 」
+------------
+
+パッチの作成には「 diff -up 」又は「 diff -uprN 」を使ってください。
+
+Linux カーネルに対する全ての変更は diff(1) コマンドによるパッチの形式で
+生成してください。パッチを作成するときには、diff(1) コマンドに「 -u 」引
+数を指定して、unified 形式のパッチを作成することを確認してください。また、
+変更がどの C 関数で行われたのかを表示する「 -p 」引数を使ってください。
+この引数は生成した差分をずっと読みやすくしてくれます。パッチは Linux
+カーネルソースの中のサブディレクトリではなく Linux カーネルソースのルート
+ディレクトリを基準にしないといけません。
+
+1個のファイルについてのパッチを作成するためには、ほとんどの場合、
+以下の作業を行えば十分です。
+
+	SRCTREE= linux-2.6
+	MYFILE=  drivers/net/mydriver.c
+
+	cd $SRCTREE
+	cp $MYFILE $MYFILE.orig
+	vi $MYFILE	# make your change
+	cd ..
+	diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
+
+複数のファイルについてのパッチを作成するためには、素の( vanilla )、す
+なわち変更を加えてない Linux カーネルを展開し、自分の Linux カーネル
+ソースとの差分を生成しないといけません。例えば、
+
+	MYSRC= /devel/linux-2.6
+
+	tar xvfz linux-2.6.12.tar.gz
+	mv linux-2.6.12 linux-2.6.12-vanilla
+	diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \
+		linux-2.6.12-vanilla $MYSRC > /tmp/patch
+
+dontdiff ファイルには Linux カーネルのビルドプロセスの過程で生成された
+ファイルの一覧がのっています。そして、それらはパッチを生成する diff(1)
+コマンドで無視されるべきです。dontdiff ファイルは 2.6.12 以後のバージョ
+ンの Linux カーネルソースツリーに含まれています。それより前のバージョン
+の Linux カーネルソースツリーに対する dontdiff ファイルは、
+から取得することができます。
+
+投稿するパッチの中に関係のない余分なファイルが含まれていないことを確
+認してください。diff(1) コマンドで生成したパッチがあなたの意図したとお
+りのものであることを確認してください。
+
+もしあなたのパッチが多くの差分を生み出すのであれば、あなたはパッチ
+を意味のあるひとまとまりごとに分けたいと思うかもしれません。
+これは他のカーネル開発者にとってレビューしやすくなるので、あなたの
+パッチを受け入れてもらうためにはとても重要なことです。これを補助でき
+る多くのスクリプトがあります。
+
+Quilt:
+http://savannah.nongnu.org/projects/quilt
+
+2) パッチに対する説明
+
+パッチの中の変更点に対する技術的な詳細について説明してください。
+
+説明はできる限り具体的に。もっとも悪い説明は「ドライバー X を更新」、
+「ドライバー X に対するバグフィックス」あるいは「このパッチはサブシス
+テム X に対する更新を含んでいます。どうか取り入れてください。」などです。
+
+パッチの説明を Linux カーネルのソースコードマネジメントシステム「 git 」の
+コミットログとして簡単に引用できる形で書けば、メンテナから感謝されるでしょう。
+以下の #15 を見てください。
+
+説明が長くなりだしたのであれば、おそらくそれはパッチを分ける必要がある
+という兆候です。次の #3 を見てください。
+
+パッチ(シリーズ)を(再)投稿する時、十分なパッチの説明とそのパッチが必要な理由を
+パッチに含めてください。ただ「これはパッチ(シリーズ)のバージョン N」とだけ
+書かないでください。そして、パッチをマージする人にパッチの説明を探させそれを
+パッチに追記させるため、過去のバージョンのパッチやそのパッチの URL を参照する
+手間をかけさせないでください。
+つまり、パッチシリーズとその説明は一緒にあるべきです。これはパッチをマージする
+人、レビューする人、どちらのためにもなります。レビューする人の中には、おそらく
+過去のバージョンのパッチを受け取ってもいない人がいます。
+
+登録済みのバグエントリを修正するパッチであれば、そのバグエントリを示すバグ ID
+や URL を明記してください。
+
+3) パッチの分割
+
+意味のあるひとまとまりごとに変更を個々のパッチファイルに分けてください。
+
+例えば、もし1つのドライバーに対するバグフィックスとパフォーマンス強
+化の両方の変更を含んでいるのであれば、その変更を2つ以上のパッチに分
+けてください。もし変更箇所に API の更新と、その新しい API を使う新たな
+ドライバーが含まれているなら、2つのパッチに分けてください。
+
+一方で、もしあなたが多数のファイルに対して意味的に同じ1つの変更を加え
+るのであれば、その変更を1つのパッチにまとめてください。言いかえると、
+意味的に同じ1つの変更は1つのパッチの中に含まれます。
+
+あるパッチが変更を完結させるために他のパッチに依存していたとしても、
+それは問題ありません。パッチの説明の中で「このパッチはパッチ X に依存
+している」と簡単に注意書きをつけてください。
+
+もしパッチをより小さなパッチの集合に凝縮することができないなら、まずは
+15かそこらのパッチを送り、そのレビューと統合を待って下さい。
+
+4) パッチのスタイルチェック
+
+あなたのパッチが基本的な( Linux カーネルの)コーディングスタイルに違反し
+ていないかをチェックして下さい。その詳細を Documentation/process/coding-style.rst で
+見つけることができます。コーディングスタイルの違反はレビューする人の
+時間を無駄にするだけなので、恐らくあなたのパッチは読まれることすらなく
+拒否されるでしょう。
+
+あなたはパッチを投稿する前に最低限パッチスタイルチェッカー
+( scripts/checkpatch.pl )を利用してパッチをチェックすべきです。
+もしパッチに違反がのこっているならば、それらの全てについてあなたは正当な
+理由を示せるようにしておく必要があります。
+
+5) 電子メールの宛先の選び方
+
+MAINTAINERS ファイルとソースコードに目を通してください。そして、その変
+更がメンテナのいる特定のサブシステムに加えられるものであることが分か
+れば、その人に電子メールを送ってください。
+
+もし、メンテナが載っていなかったり、メンテナからの応答がないなら、
+LKML ( linux-kernel@vger.kernel.org )へパッチを送ってください。ほとんど
+のカーネル開発者はこのメーリングリストに目を通しており、変更に対して
+コメントを得ることができます。
+
+15個より多くのパッチを同時に vger.kernel.org のメーリングリストへ送らな
+いでください!!!
+
+Linus Torvalds は Linux カーネルに入る全ての変更に対する最終的な意思決定者
+です。電子メールアドレスは torvalds@linux-foundation.org になります。彼は
+多くの電子メールを受け取っているため、できる限り彼に電子メールを送るのは
+避けるべきです。
+
+バグフィックスであったり、自明な変更であったり、話し合いをほとんど
+必要としないパッチは Linus へ電子メールを送るか CC しなければなりません。
+話し合いを必要としたり、明確なアドバンテージがないパッチは、通常まず
+は LKML へ送られるべきです。パッチが議論された後にだけ、そのパッチを
+Linus へ送るべきです。
+
+6) CC (カーボンコピー)先の選び方
+
+特に理由がないなら、LKML にも CC してください。
+
+Linus 以外のカーネル開発者は変更に気づく必要があり、その結果、彼らはそ
+の変更に対してコメントをくれたり、コードに対してレビューや提案をくれ
+るかもしれません。LKML とは Linux カーネル開発者にとって一番中心的なメー
+リングリストです。USB やフレームバッファデバイスや VFS や SCSI サブシステ
+ムなどの特定のサブシステムに関するメーリングリストもあります。あなた
+の変更に、はっきりと関連のあるメーリングリストについて知りたければ
+MAINTAINERS ファイルを参照してください。
+
+VGER.KERNEL.ORG でホスティングされているメーリングリストの一覧が下記の
+サイトに載っています。
+
+
+もし、変更がユーザランドのカーネルインタフェースに影響を与え
+るのであれば、MAN-PAGES のメンテナ( MAINTAINERS ファイルに一覧
+があります)に man ページのパッチを送ってください。少なくとも
+情報がマニュアルページの中に入ってくるように、変更が起きたという
+通知を送ってください。
+
+たとえ、メンテナが #5 で反応がなかったとしても、メンテナのコードに変更を
+加えたときには、いつもメンテナに CC するのを忘れないようにしてください。
+
+小さなパッチであれば、Trivial Patch Monkey(ちょっとしたパッチを集めている)
+に CC してもいいです。その現管理者については MAINTAINERS
+ファイルを見てください。ちょっとしたパッチとは以下のルールのどれか1つを満たして
+いなければなりません。
+ ・ドキュメントのスペルミスの修正
+ ・grep(1) コマンドによる検索を困難にしているスペルの修正
+ ・コンパイル時の警告の修正(無駄な警告が散乱することは好ましくないた
+   めです)
+ ・コンパイル問題の修正(それらの修正が本当に正しい場合に限る)
+ ・実行時の問題の修正(それらの修正が本当に問題を修正している場合に限る)
+ ・廃止予定の関数やマクロを使用しているコードの除去(例 check_region )
+ ・問い合わせ先やドキュメントの修正
+ ・移植性のないコードから移植性のあるコードへの置き換え(小さい範囲で
+   あればアーキテクチャ特有のことでも他の人がコピーできます)
+ ・作者やメンテナによる修正(すなわち patch monkey の再転送モード)
+
+7) MIME やリンクや圧縮ファイルや添付ファイルではなくプレインテキストのみ
+
+Linus や他のカーネル開発者はあなたが投稿した変更を読んで、コメントでき
+る必要があります。カーネル開発者にとって、あなたが書いたコードの特定の
+部分にコメントをするために、標準的な電子メールクライアントで変更が引用
+できることは重要です。
+
+上記の理由で、すべてのパッチは文中に含める形式の電子メールで投稿さ
+れるべきです。警告：あなたがパッチをコピー&ペーストする際には、パッ
+チを改悪するエディターの折り返し機能に注意してください。
+
+パッチを圧縮の有無に関わらず MIME 形式で添付しないでください。多くのポ
+ピュラーな電子メールクライアントは MIME 形式の添付ファイルをプレーンテ
+キストとして送信するとは限らないでしょう。そうなると、電子メールクラ
+イアントがコードに対するコメントを付けることをできなくします。また、
+MIME 形式の添付ファイルは Linus に手間を取らせることになり、その変更を
+受け入れてもらう可能性が低くなってしまいます。
+
+例外：お使いの電子メールクライアントがパッチをめちゃくちゃにするので
+あれば、誰かが MIME 形式のパッチを再送するよう求めるかもしれません。
+
+余計な変更を加えずにあなたのパッチを送信するための電子メールクライアントの設定
+のヒントについては Documentation/process/email-clients.rst を参照してください。
+
+8) 電子メールのサイズ
+
+パッチを Linus へ送るときは常に #7 の手順に従ってください。
+
+大きなパッチはメーリングリストやメンテナにとって不親切です。パッチが
+未圧縮で 300KB を超えるようであるなら、インターネット上のアクセス可能な
+サーバに保存し、保存場所を示す URL を伝えるほうが適切です。
+
+9) カーネルバージョンの明記
+
+パッチが対象とするカーネルのバージョンをパッチの概要か電子メールの
+サブジェクトに付けることが重要です。
+
+パッチが最新バージョンのカーネルに正しく適用できなければ、Linus は
+そのパッチを採用しないでしょう。
+
+10) がっかりせず再投稿
+
+パッチを投稿した後は、辛抱強く待っていてください。Linus があなたのパッ
+チを気に入って採用すれば、Linus がリリースする次のバージョンのカーネル
+の中で姿を見せるでしょう。
+
+しかし、パッチが次のバージョンのカーネルに入っていないなら、いくつもの
+理由があるのでしょう。その原因を絞り込み、間違っているものを正し、更新
+したパッチを投稿するのはあなたの仕事です。
+
+Linus があなたのパッチに対して何のコメントもなく不採用にすることは極め
+て普通のことです。それは自然な姿です。もし、Linus があなたのパッチを受
+け取っていないのであれば、以下の理由が考えられます。
+* パッチが最新バージョンの Linux カーネルにきちんと適用できなかった
+* パッチが LKML で十分に議論されていなかった
+* スタイルの問題(セクション2を参照)
+* 電子メールフォーマットの問題(このセクションを参照)
+* パッチに対する技術的な問題
+* Linus はたくさんの電子メールを受け取っているので、どさくさに紛れて見
+  失った
+* 不愉快にさせている
+
+判断できない場合は、LKML にコメントを頼んでください。
+
+11) サブジェクトに「 PATCH 」
+
+Linus や LKML への大量の電子メールのために、サブジェクトのプレフィックスに
+「 [PATCH] 」を付けることが慣習となっています。これによって Linus や他の
+カーネル開発者がパッチであるのか、又は、他の議論に関する電子メールであるの
+かをより簡単に識別できます。
+
+12) パッチへの署名
+
+誰が何をしたのかを追いかけやすくするために (特に、パッチが何人かの
+メンテナを経て最終的に Linux カーネルに取り込まれる場合のために)、電子
+メールでやり取りされるパッチに対して「 sign-off 」という手続きを導入し
+ました。
+
+「 sign-off 」とは、パッチがあなたの書いたものであるか、あるいは、
+あなたがそのパッチをオープンソースとして提供する権利を保持している、
+という証明をパッチの説明の末尾に一行記載するというものです。
+ルールはとても単純です。以下の項目を確認して下さい。
+
+        原作者の証明書( DCO ) 1.1
+
+        このプロジェクトに寄与するものとして、以下のことを証明する。
+
+        (a) 本寄与は私が全体又は一部作成したものであり、私がそのファイ
+            ル中に明示されたオープンソースライセンスの下で公開する権利
+            を持っている。もしくは、
+
+        (b) 本寄与は、私が知る限り、適切なオープンソースライセンスでカバ
+            ーされている既存の作品を元にしている。同時に、私はそのライセ
+            ンスの下で、私が全体又は一部作成した修正物を、ファイル中で示
+            される同一のオープンソースライセンスで(異なるライセンスの下で
+            投稿することが許可されている場合を除いて)投稿する権利を持って
+            いる。もしくは、
+
+        (c) 本寄与は(a)、(b)、(c)を証明する第3者から私へ直接提供された
+            ものであり、私はそれに変更を加えていない。
+
+        (d) 私はこのプロジェクトと本寄与が公のものであることに理解及び同意す
+            る。同時に、関与した記録(投稿の際の全ての個人情報と sign-off を
+            含む)が無期限に保全されることと、当該プロジェクト又は関連する
+            オープンソースライセンスに沿った形で再配布されることに理解及び
+            同意する。
+
+もしこれに同意できるなら、以下のような1行を追加してください。
+
+	Signed-off-by: Random J Developer 
+
+実名を使ってください。(残念ですが、偽名や匿名による寄与はできません。)
+
+人によっては sign-off の近くに追加のタグを付加しています。それらは今のところ
+無視されますが、あなたはそのタグを社内の手続きに利用したり、sign-off に特別
+な情報を示したりすることができます。
+
+あなたがサブシステムまたはブランチのメンテナであれば、受け取ったパッチを自身の
+ツリーにマージするために、わずかに変更が必要となる場合があります。なぜなら
+あなたのツリーの中のコードと投稿者のツリーの中のコードは同一ではないためです。
+もし、あなたが厳密に上記ルール(c)にこだわるのであれば、投稿者に再度差分を
+とるよう依頼すべきです。しかし、これは時間とエネルギーを非生産的に浪費する
+ことになります。ルール(b)はあなたにコードを修正する権利を与えてくれます。
+しかし、投稿者のコードを修正し、その修正によるバグを投稿者に押し付けてしまう
+ことはとても失礼なことです。この問題を解決するために、末尾の投稿者の
+Signed-off-by とあなたがその末尾に追加する Signed-off-by の間に、修正を
+加えたことを示す1行を追加することが推奨されています。
+(その1行の書き方に)決まりはありませんが、大括弧の中に電子メールアドレスや氏名
+と修正内容を記載するやり方は目につきやすく、最終段階での変更の責任があなたに
+あることを明確にするのに十分な方法のようです。例えば、
+
+	Signed-off-by: Random J Developer 
+	[lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
+	Signed-off-by: Lucky K Maintainer 
+
+あなたが安定版のブランチを管理しており、作成者のクレジット、変更の追跡、
+修正のマージ、と同時に苦情からの投稿者の保護を行いたい場合、この慣習は特に
+有用となります。いかなる事情があってもチェンジログに出てくる作成者の
+アイデンティティ情報(From ヘッダ)は変更できないことに注意してください。
+
+バックポートする人のための特別な注意事項。追跡を容易に行うために、コミット
+メッセージのトップ(サブジェクト行のすぐ後)にパッチの起源を示す情報を記述する
+ことは一般的で有用な慣習です。例えば、これは 2.6-stable ツリーでの一例です。    
+
+    Date:   Tue May 13 19:10:30 2008 +0000
+
+        SCSI: libiscsi regression in 2.6.25: fix nop timer handling
+
+        commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream
+
+そして、これは 2.4 ツリーでの一例です。
+
+    Date:   Tue May 13 22:12:27 2008 +0200
+
+        wireless, airo: waitbusy() won't delay
+
+        [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
+
+どんな形式であれ、この情報はあなたのツリーを追跡する人やあなたのツリーのバグを
+解決しようとしている人にとって価値のある支援となります。
+
+13) いつ Acked-by: と Cc: を使うのか
+
+「 Signed-off-by: 」タグはその署名者がパッチの開発に関わっていたことやパッチ
+の伝播パスにいたことを示しています。
+
+ある人が直接パッチの準備や作成に関わっていないけれど、その人のパッチに対す
+る承認を記録し、示したいとします。その場合、その人を示すのに Acked-by: が使
+えます。Acked-by: はパッチのチェンジログにも追加されます。
+
+パッチの影響を受けるコードのメンテナがパッチに関わっていなかったり、パッチ
+の伝播パスにいなかった時にも、メンテナは Acked-by: をしばしば利用します。
+
+Acked-by: は Signed-off-by: のように公式なタグではありません。それはメンテナが
+少なくともパッチをレビューし、同意を示しているという記録です。そのような
+ことからパッチをマージする人がメンテナの「うん、良いと思うよ」という発言を
+Acked-by: へ置き換えることがあります。
+
+Acked-by: が必ずしもパッチ全体の承認を示しているわけではありません。例えば、
+あるパッチが複数のサブシステムへ影響を与えており、その中の1つのサブシステム
+のメンテナからの Acked-by: を持っているとします。その場合、Acked-by: は通常
+そのメンテナのコードに影響を与える一部分だけに対する承認を示しています。
+この点は、ご自分で判断してください。(その Acked-by: が)疑わしい場合は、
+メーリングリストアーカイブの中の大元の議論を参照すべきです。
+
+パッチにコメントする機会を持っていたが、その時にコメントしなかった人がいれば、
+その人を指す「Cc:」タグを任意で追加してもかまいません。これは指定された人からの
+明確なアクションなしに付与できる唯一のタグです。
+このタグはパッチに関心があると思われる人達がそのパッチの議論に含まれていたこと
+を明文化します。
+
+14) Reported-by と Tested-by: と Reviewed-by: の利用
+
+他の誰かによって報告された問題を修正するパッチであれば、問題報告者という寄与を
+クレジットするために、Reported-by: タグを追加することを検討してください。
+こまめにバグ報告者をクレジットしていくことで、うまくいけばその人たちが将来再び
+コミュニティの力となってくれるでしょう。
+ただし、報告者の許可無くこのタグを追加しないように注意してください。特に、
+問題が公の場で報告されていなかったのであれば。
+
+Tested-by: タグはタグで指定された人によって(ある環境下で)パッチのテストに成功
+していることを示します。このタグはメンテナにテストが実施済みであることを
+知らせ、将来の関連パッチのテスト協力者を見つける方法を提供し、テスト実施者に
+対するクレジットを保証します。
+
+Reviewed-by: タグは、それとは異なり、下記のレビューア宣言の下にレビューされ、
+受け入れ可能とみなされたパッチであることを示します。
+
+        レビューアによる監督宣言
+
+        私は Reviewed-by: タグを提示することによって、以下のことを明言する。
+
+        (a) 私はメインラインカーネルへの統合に向け、その妥当性及び「即応性
+            (訳注)」を検証し、技術的側面からパッチをレビュー済みである。
+
+        訳注:
+        「即応性」の原文は "readiness"。
+        パッチが十分な品質を持っており、メインラインカーネルへの統合を即座に
+        行うことができる状態であるかどうかを "readiness" という単語で表現
+        している。
+
+        (b) パッチに関するあらゆる問題、懸念、あるいは、疑問は投稿者へ伝達済み
+            である。私はそれらのコメントに対する投稿者の返答に満足している。
+
+        (c) 投稿に伴い改良されるコードがある一方で、現時点で、私は(1)それが
+            カーネルにとって価値のある変更であること、そして、(2)統合に際して
+            議論になり得るような問題はないものと確信している。
+
+        (d) 私はパッチをレビューし適切であると確信している一方で、あらゆる
+            状況においてその宣言した目的や機能が正しく実現することに関して、
+            いかなる保証もしない(特にどこかで明示しない限り)。
+
+Reviewd-by タグはそのパッチがカーネルに対して適切な修正であって、深刻な技術的
+問題を残していないという意見の宣言です。興味のあるレビューアは誰でも(レビュー
+作業を終えたら)パッチに対して Reviewed-by タグを提示できます。このタグは
+レビューアの寄与をクレジットする働き、レビューの進捗の度合いをメンテナに
+知らせる働きを持ちます。そのパッチの領域に詳しく、そして、しっかりとした
+レビューを実施したレビューアによって提供される時、Reviewed-by: タグがあなたの
+パッチをカーネルにマージする可能性を高めるでしょう。
+
+15) 標準的なパッチのフォーマット
+
+標準的なパッチのサブジェクトは以下のとおりです。
+
+    Subject: [PATCH 001/123] subsystem: summary phrase
+
+標準的なパッチの、電子メールのボディは以下の項目を含んでいます。
+
+  - パッチの作成者を明記する「 from 」行
+
+  - 空行
+
+  - 説明本体。これはこのパッチを説明するために無期限のチェンジログ
+    (変更履歴)にコピーされます。
+
+  - 上述した「 Signed-off-by: 」行。これも説明本体と同じくチェン
+    ジログ内にコピーされます。
+
+  - マーカー行は単純に「 --- 」です。
+
+  - 余計なコメントは、チェンジログには不適切です。
+
+  - 実際のパッチ(差分出力)
+
+サブジェクト行のフォーマットは、アルファベット順で電子メールをとても
+ソートしやすいものになっています。(ほとんどの電子メールクライアント
+はソートをサポートしています)パッチのサブジェクトの連番は0詰めであ
+るため、数字でのソートとアルファベットでのソートは同じ結果になります。
+
+電子メールのサブジェクト内のサブシステム表記は、パッチが適用される
+分野またはサブシステムを識別できるようにすべきです。
+
+電子メールのサブジェクトの「summary phrase」はそのパッチの概要を正確
+に表現しなければなりません。「summary phrase」をファイル名にしてはい
+けません。パッチシリーズ中でそれぞれのパッチは同じ「summary phrase」を
+使ってはいけません(「パッチシリーズ」とは順序付けられた関連のある複数の
+パッチ群です)。
+
+あなたの電子メールの「summary phrase」がそのパッチにとって世界で唯一の識別子に
+なるように心がけてください。「summary phrase」は git のチェンジログの中へ
+ずっと伝播していきます。「summary phrase」は、開発者が後でパッチを参照する
+ために議論の中で利用するかもしれません。
+人々はそのパッチに関連した議論を読むために「summary phrase」を使って google で
+検索したがるでしょう。それはまた2、3ヶ月あとで、人々が「gitk」や
+「git log --oneline」のようなツールを使用して何千ものパッチに目を通す時、
+唯一目にとまる情報となるでしょう。
+
+これらの理由のため、「summary phrase」はなぜパッチが必要であるか、パッチが何を
+変更するかの2つの情報をせいぜい70〜75文字で表現していなければなりません。
+「summary phrase」は簡潔であり説明的である表現を目指しつつ、うまく
+まとめられている概要となるべきです。
+
+「summary phrase」は「Subject: [PATCH tag] 」のように、
+大括弧で閉じられたタグを接頭辞として付加してもかまいません。このタグは
+「summary phrase」の一部とは考えませんが、パッチをどのように取り扱うべきかを
+表現します。
+一般的には「v1, v2, v3」のようなバージョン情報を表すタグ(過去のパッチに対する
+コメントを反映するために複数のバージョンのパッチが投稿されているのであれば)、
+「RFC」のようなコメントを要求するタグが挙げられます。パッチシリーズとして4つの
+パッチがあれば、個々のパッチに「1/4, 2/4, 3/4, 4/4」のように番号を付けても
+かまいません。これは開発者がパッチを適用する順番を確実に把握するためです。
+そして、開発者がパッチシリーズの中のすべてのパッチをもらさずレビュー或いは
+適用するのを保証するためです。
+
+サブジェクトの例を二つ
+
+    Subject: [patch 2/5] ext2: improve scalability of bitmap searching
+    Subject: [PATCHv2 001/207] x86: fix eflags tracking
+
+「 from 」行は電子メールのボディの一番最初の行でなければなりません。
+その形式は以下のとおりです。
+
+        From: Original Author 
+
+「 from 」行はチェンジログの中で、そのパッチの作成者としてクレジットされ
+ている人を特定するものです。「 from 」行がかけていると、電子メールのヘッ
+ダーの「 From: 」が、チェンジログの中でパッチの作成者を決定するために使わ
+れるでしょう。
+
+説明本体は無期限のソースのチェンジログにコミットされます。なので、説明
+本体はそのパッチに至った議論の詳細を忘れているある程度の技量を持っている人
+がその詳細を思い出すことができるものでなければなりません。パッチが対処する
+障害の症状(カーネルログメッセージや oops メッセージ等)を記載することは問題に
+対処可能なパッチを求めてコミットログを検索する人々にとって特に有用です。
+パッチがコンパイル問題を解決するのであれば、そのパッチを探している人が見つける
+ことができる情報だけで十分であり、コンパイル時の全てのエラーを含める必要は
+ありません。「summary phrase」と同様に、簡潔であり説明的であることが重要です。
+
+「 --- 」マーカー行はパッチ処理ツールに対して、チェンジログメッセージの終端
+部分を認識させるという重要な役目を果たします。
+
+「 --- 」マーカー行の後の追加コメントの良い使用方法の1つに diffstat コマンド
+があります。diffstat コマンドとは何のファイルが変更され、1ファイル当たり何行
+追加され何行消されたかを示すものです。diffstat コマンドは特に大きなパッチに
+おいて役立ちます。その時点でだけ又はメンテナにとってのみ関係のあるコメント
+は無期限に保存されるチェンジログにとって適切ではありません。そのため、この
+ようなコメントもマーカー行の後に書かれるべきです。
+このようなコメントの良い例として、v1 と v2 のバージョン間で何が変更されたかを
+表す「パッチの変更履歴」が挙げられます。
+
+「 --- 」マーカー行の後に diffstat コマンドの結果を含めるのであれば、ファイル
+名はカーネルソースツリーのトップディレクトリからの表記で列記されるため、横方向
+のスペースをとり過ぎないように、diffstat コマンドにオプション「 -p 1 -w 70 」
+を指定してください(インデントを含めてちょうど80列に合うでしょう)。
+
+適切なパッチのフォーマットの詳細についてはセクション3の参考文献を参照して
+ください。
+
+16) 「git pull」要求の送り方(Linus の電子メールから)
+
+間違ったブランチから引っ張るのを防ぐために、git リポジトリのアドレスと
+ブランチ名を同じ行に1行で記載してください。そうすることで、3回の連続クリック
+で全て選択できます。
+
+正しい形式は下記の通りです。
+
+	"Please pull from
+
+		git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
+
+	 to get these changes:"
+
+その結果、アドレスを自分自身でタイピングして間違えることはなくなります(実際に、
+何度か間違ったブランチから引っ張ってきてしまい、その時に diffstat の結果を
+検証して間違っていることに気づいたことがあります。どこから何を引っ張るべきかを
+「探したり」、正しいブランチ名かどうかを重ねてチェックしたりする必要が
+なくなればより快適になるでしょう)。
+
+diffstat の結果を生成するために「 git diff -M --stat --summary 」を使って
+ください。-M オプションはファイル名の変更を検知でき、--summary オプションは
+新規ファイル、削除されたファイル、名前が変更されたファイルの概要を生成します。
+
+-M オプション(ファイル名の変更検知)を指定すると、diffstat の結果はかなり
+異なってきます。git は大規模な変更(追加と削除のペア)をファイル名の変更と
+判断するためです。
+
+------------------------------------
+セクション2 - ヒントとTIPSと小技
+------------------------------------
+
+このセクションは Linux カーネルに変更を適用することに関係のある一般的な
+「お約束」の多くを載せています。物事には例外というものがあります。しか
+し例外を適用するには、本当に妥当な理由が不可欠です。あなたは恐らくこの
+セクションを Linus のコンピュータ・サイエンス101と呼ぶでしょう。
+
+1) Documentation/process/coding-style.rstを参照
+
+言うまでもなく、あなたのコードがこのコーディングスタイルからあまりに
+も逸脱していると、レビューやコメントなしに受け取ってもらえないかもし
+れません。
+
+特筆すべき例外は、コードをあるファイルから別のファイルに移動
+するときです。この場合、コードを移動するパッチでは、移動されるコード
+に関して移動以外の変更を一切加えるべきではありません。これにより、
+コードの移動とあなたが行ったコードの修正を明確に区別できるようにな
+ります。これは実際に何が変更されたかをレビューする際の大きな助けに
+なるとともに、ツールにコードの履歴を追跡させることも容易になります。
+
+投稿するより前にパッチのスタイルチェッカー( scripts/checkpatch.pl )で
+あなたのパッチをチェックしてください。このスタイルチェッカーは最終結
+論としてではなく、指標としてみるべきです。もし、あなたのコードが違反
+はしているが修正するより良く見えるのであれば、おそらくそのままにする
+のがベストです。
+
+スタイルチェッカーによる3段階のレポート:
+ - エラー: 間違っている可能性が高い
+ - 警告：注意してレビューする必要がある
+ - チェック：考慮する必要がある
+
+あなたはパッチに残っている全ての違反について、それがなぜ必要なのか正当な
+理由を示せるようにしておく必要があります。
+
+2) #ifdefは見苦しい
+
+ifdef が散乱したコードは、読むのもメンテナンスするのも面倒です。コードの中
+で ifdef を使わないでください。代わりに、ヘッダファイルの中に ifdef を入れて、
+条件付きで、コードの中で使われる関数を「 static inline 」関数かマクロで定義し
+てください。後はコンパイラが、何もしない箇所を最適化して取り去ってくれるで
+しょう。
+
+まずいコードの簡単な例
+
+	dev = alloc_etherdev (sizeof(struct funky_private));
+	if (!dev)
+		return -ENODEV;
+	#ifdef CONFIG_NET_FUNKINESS
+	init_funky_net(dev);
+	#endif
+
+クリーンアップしたコードの例
+
+(in header)
+	#ifndef CONFIG_NET_FUNKINESS
+	static inline void init_funky_net (struct net_device *d) {}
+	#endif
+
+(in the code itself)
+	dev = alloc_etherdev (sizeof(struct funky_private));
+	if (!dev)
+		return -ENODEV;
+	init_funky_net(dev);
+
+3) マクロより「 static inline 」を推奨
+
+「 static inline 」関数はマクロよりもずっと推奨されています。それらは、
+型安全性があり、長さにも制限が無く、フォーマットの制限もありません。
+gcc においては、マクロと同じくらい軽いです。
+
+マクロは「 static inline 」が明らかに不適切であると分かる場所(高速化パスの
+いくつかの特定のケース)や「 static inline 」関数を使うことができないような
+場所(マクロの引数の文字列連結のような)にだけ使われるべきです。
+
+「 static inline 」は「 static __inline__ 」や「 extern inline 」や
+「 extern __inline__ 」よりも適切です。
+
+4) 設計に凝りすぎるな
+
+それが有用になるかどうか分からないような不明瞭な将来を見越した設計
+をしないでください。「できる限り簡単に、そして、それ以上簡単になら
+ないような設計をしてください。」
+
+----------------------
+セクション3 参考文献
+----------------------
+
+Andrew Morton, "The perfect patch" (tpp).
+  
+
+Jeff Garzik, "Linux kernel patch submission format".
+  
+
+Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
+  
+  
+  
+  
+
+NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
+  
+
+Kernel Documentation/process/coding-style.rst:
+  
+
+Linus Torvalds's mail on the canonical patch format:
+  
+
+Andi Kleen, "On submitting kernel patches"
+  Some strategies to get difficult or controversial changes in.
+  http://halobates.de/on-submitting-patches.pdf
+
+--
+
+
diff --git a/Documentation/translations/ja_JP/stable_api_nonsense.txt b/Documentation/translations/ja_JP/stable_api_nonsense.txt
new file mode 100644
index 000000000000..a3b40a4bdcfd
--- /dev/null
+++ b/Documentation/translations/ja_JP/stable_api_nonsense.txt
@@ -0,0 +1,263 @@
+NOTE:
+This is a version of Documentation/process/stable-api-nonsense.rst into Japanese.
+This document is maintained by IKEDA, Munehiro 
+and the JF Project team .
+If you find any difference between this document and the original file
+or a problem with the translation,
+please contact the maintainer of this file or JF project.
+
+Please also note that the purpose of this file is to be easier to read
+for non English (read: Japanese) speakers and is not intended as a
+fork. So if you have any comments or updates of this file, please try
+to update the original English file first.
+
+Last Updated: 2007/07/18
+==================================
+これは、
+linux-2.6.22-rc4/Documentation/process/stable-api-nonsense.rst の和訳
+です。
+翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
+翻訳日 ： 2007/06/11
+原著作者: Greg Kroah-Hartman < greg at kroah dot com >
+翻訳者 ： 池田 宗広 < m-ikeda at ds dot jp dot nec dot com >
+校正者 ： Masanori Kobayashi さん < zap03216 at nifty dot ne dot jp >
+          Seiji Kaneko さん < skaneko at a2 dot mbn dot or dot jp >
+==================================
+
+
+
+Linux カーネルのドライバインターフェース
+（あなたの質問すべてに対する回答とその他諸々）
+
+Greg Kroah-Hartman 
+
+
+この文書は、なぜ Linux ではバイナリカーネルインターフェースが定義
+されていないのか、またはなぜ不変のカーネルインターフェースを持たな
+いのか、ということを説明するために書かれた。ここでの話題は「カーネ
+ル内部の」インターフェースについてであり、ユーザー空間とのインター
+フェースではないことを理解してほしい。カーネルとユーザー空間とのイ
+ンターフェースとはアプリケーションプログラムが使用するものであり、
+つまりシステムコールのインターフェースがこれに当たる。これは今まで
+長きに渡り、かつ今後も「まさしく」不変である。私は確か 0.9 か何か
+より前のカーネルを使ってビルドした古いプログラムを持っているが、そ
+れは最新の 2.6 カーネルでもきちんと動作する。ユーザー空間とのイン
+ターフェースは、ユーザーとアプリケーションプログラマが不変性を信頼
+してよいものの一つである。
+
+
+要旨
+----
+
+あなたは不変のカーネルインターフェースが必要だと考えているかもしれ
+ないが、実際のところはそうではない。あなたは必要としているものが分
+かっていない。あなたが必要としているものは安定して動作するドライバ
+であり、それはドライバがメインのカーネルツリーに含まれる場合のみ得
+ることができる。ドライバがメインのカーネルツリーに含まれていると、
+他にも多くの良いことがある。それは、Linux をより強固で、安定な、成
+熟したオペレーティングシステムにすることができるということだ。これ
+こそ、そもそもあなたが Linux を使う理由のはずだ。
+
+
+はじめに
+--------
+
+カーネル内部のインターフェース変更を心配しなければならないドライバ
+を書きたいなどというのは、変わり者だけだ。この世界のほとんどの人は、
+そのようなドライバがどんなインターフェースを使っているかなど知らな
+いし、そんなドライバのことなど全く気にもかけていない。
+
+
+まず初めに、クローズソースとか、ソースコードの隠蔽とか、バイナリの
+みが配布される使い物にならない代物[訳注(1)]とか、実体はバイナリ
+コードでそれを読み込むためのラッパー部分のみソースコードが公開され
+ているとか、その他用語は何であれ GPL の下にソースコードがリリース
+されていないカーネルドライバに関する法的な問題について、私は「いか
+なる議論も」行うつもりがない。法的な疑問があるのならば、プログラマ
+である私ではなく、弁護士に相談して欲しい。ここでは単に、技術的な問
+題について述べることにする。（法的な問題を軽視しているわけではない。
+それらは実際に存在するし、あなたはそれをいつも気にかけておく必要が
+ある）
+
+訳注(1)
+「使い物にならない代物」の原文は "blob"
+
+
+さてここでは、バイナリカーネルインターフェースについてと、ソースレ
+ベルでのインターフェースの不変性について、という二つの話題を取り上
+げる。この二つは互いに依存する関係にあるが、まずはバイナリインター
+フェースについて議論を行いやっつけてしまおう。
+
+
+バイナリカーネルインターフェース
+--------------------------------
+
+もしソースレベルでのインターフェースが不変ならば、バイナリインター
+フェースも当然のように不変である、というのは正しいだろうか？正しく
+ない。Linux カーネルに関する以下の事実を考えてみてほしい。
+  - あなたが使用するＣコンパイラのバージョンによって、カーネル内部
+    の構造体の配置構造は異なったものになる。また、関数は異なった方
+    法でカーネルに含まれることになるかもしれない（例えばインライン
+    関数として扱われたり、扱われなかったりする）。個々の関数がどの
+    ようにコンパイルされるかはそれほど重要ではないが、構造体のパデ
+    ィングが異なるというのは非常に重要である。
+  - あなたがカーネルのビルドオプションをどのように設定するかによっ
+    て、カーネルには広い範囲で異なった事態が起こり得る。
+      - データ構造は異なるデータフィールドを持つかもしれない
+      - いくつかの関数は全く実装されていない状態になり得る
+        （例：SMP向けではないビルドでは、いくつかのロックは中身が
+          カラにコンパイルされる）
+      - カーネル内のメモリは、異なった方法で配置され得る。これはビ
+        ルドオプションに依存している。
+  - Linux は様々な異なるプロセッサアーキテクチャ上で動作する。
+    あるアーキテクチャ用のバイナリドライバを、他のアーキテクチャで
+    正常に動作させる方法はない。
+
+
+ある特定のカーネル設定を使用し、カーネルをビルドしたのと正確に同じ
+Ｃコンパイラを使用して単にカーネルモジュールをコンパイルするだけで
+も、あなたはこれらいくつもの問題に直面することになる。ある特定の
+Linux ディストリビューションの、ある特定のリリースバージョン用にモ
+ジュールを提供しようと思っただけでも、これらの問題を引き起こすには
+十分である。にも関わらず Linux ディストリビューションの数と、サ
+ポートするディストリビューションのリリース数を掛け算し、それら一つ
+一つについてビルドを行ったとしたら、今度はリリースごとのビルドオプ
+ションの違いという悪夢にすぐさま悩まされることになる。また、ディス
+トリビューションの各リリースバージョンには、異なるハードウェア（プ
+ロセッサタイプや種々のオプション）に対応するため、何種類かのカーネ
+ルが含まれているということも理解して欲しい。従って、ある一つのリ
+リースバージョンだけのためにモジュールを作成する場合でも、あなたは
+何バージョンものモジュールを用意しなければならない。
+
+
+信じて欲しい。このような方法でサポートを続けようとするなら、あなた
+はいずれ正気を失うだろう。遠い昔、私はそれがいかに困難なことか、身
+をもって学んだのだ・・・
+
+
+不変のカーネルソースレベルインターフェース
+------------------------------------------
+
+メインカーネルツリーに含まれていない Linux カーネルドライバを継続
+してサポートしていこうとしている人たちとの議論においては、これは極
+めて「引火性の高い」話題である。[訳注(2)]
+
+訳注(2)
+「引火性の高い」の原文は "volatile"。
+volatile には「揮発性の」「爆発しやすい」という意味の他、「変わり
+やすい」「移り気な」という意味がある。
+「（この話題は）爆発的に激しい論争を巻き起こしかねない」ということ
+を、「（カーネルのソースレベルインターフェースは）移ろい行くもので
+ある」ということを連想させる "volatile" という単語で表現している。
+
+
+Linux カーネルの開発は継続的に速いペースで行われ、決して歩みを緩め
+ることがない。その中でカーネル開発者達は、現状のインターフェースに
+あるバグを見つけ、より良い方法を考え出す。彼らはやがて、現状のイン
+ターフェースがより正しく動作するように修正を行う。その過程で関数の
+名前は変更されるかもしれず、構造体は大きく、または小さくなるかもし
+れず、関数の引数は検討しなおされるかもしれない。そのような場合、引
+き続き全てが正常に動作するよう、カーネル内でこれらのインターフェー
+スを使用している個所も全て同時に修正される。
+
+
+具体的な例として、カーネル内の USB インターフェースを挙げる。USB
+サブシステムはこれまでに少なくとも３回の書き直しが行われ、その結果
+インターフェースが変更された。これらの書き直しはいくつかの異なった
+問題を修正するために行われた。
+  - 同期的データストリームが非同期に変更された。これにより多数のド
+    ライバを単純化でき、全てのドライバのスループットが向上した。今
+    やほとんど全ての USB デバイスは、考えられる最高の速度で動作し
+    ている。
+  - USB ドライバが USB サブシステムのコアから行う、データパケット
+    用のメモリ確保方法が変更された。これに伴い、いくつもの文書化さ
+    れたデッドロック条件を回避するため、全ての USB ドライバはより
+    多くの情報を USB コアに提供しなければならないようになっている。
+
+
+このできごとは、数多く存在するクローズソースのオペレーティングシス
+テムとは全く対照的だ。それらは長期に渡り古い USB インターフェース
+をメンテナンスしなければならない。古いインターフェースが残ることで、
+新たな開発者が偶然古いインターフェースを使い、正しくない方法で開発
+を行ってしまう可能性が生じる。これによりシステムの安定性は危険にさ
+らされることになる。
+
+
+上に挙げたどちらの例においても、開発者達はその変更が重要かつ必要で
+あることに合意し、比較的楽にそれを実行した。もし Linux がソースレ
+ベルでインターフェースの不変性を保証しなければならないとしたら、新
+しいインターフェースを作ると同時に、古い、問題のある方を今後ともメ
+ンテナンスするという余計な仕事を USB の開発者にさせなければならな
+い。Linux の USB 開発者は、自分の時間を使って仕事をしている。よっ
+て、価値のない余計な仕事を報酬もなしに実行しろと言うことはできない。
+
+
+セキュリティ問題も、Linux にとっては非常に重要である。ひとたびセキ
+ュリティに関する問題が発見されれば、それは極めて短期間のうちに修正
+される。セキュリティ問題の発生を防ぐための修正は、カーネルの内部イ
+ンターフェースの変更を何度も引き起こしてきた。その際同時に、変更さ
+れたインターフェースを使用する全てのドライバもまた変更された。これ
+により問題が解消し、将来偶然に問題が再発してしまわないことが保証さ
+れる。もし内部インターフェースの変更が許されないとしたら、このよう
+にセキュリティ問題を修正し、将来再発しないことを保証することなど不
+可能なのだ。
+
+
+カーネルのインターフェースは時が経つにつれクリーンナップを受ける。
+誰も使っていないインターフェースは削除される。これにより、可能な限
+りカーネルが小さく保たれ、現役の全てのインターフェースが可能な限り
+テストされることを保証しているのだ。（使われていないインターフェー
+スの妥当性をテストすることは不可能と言っていいだろう）
+
+
+
+これから何をすべきか
+-----------------------
+
+では、もしメインのカーネルツリーに含まれない Linux カーネルドライ
+バがあったとして、あなたは、つまり開発者は何をするべきだろうか？全
+てのディストリビューションの全てのカーネルバージョン向けにバイナリ
+のドライバを供給することは悪夢であり、カーネルインターフェースの変
+更を追いかけ続けることもまた過酷な仕事だ。
+
+
+答えは簡単。そのドライバをメインのカーネルツリーに入れてしまえばよ
+い。（ここで言及しているのは、GPL に従って公開されるドライバのこと
+だということに注意してほしい。あなたのコードがそれに該当しないなら
+ば、さよなら。幸運を祈ります。ご自分で何とかしてください。Andrew
+と Linus からのコメント＜Andrew と Linus のコメントへのリンクをこ
+こに置く＞をどうぞ）ドライバがメインツリーに入れば、カーネルのイン
+ターフェースが変更された場合、変更を行った開発者によってドライバも
+修正されることになるだろう。あなたはほとんど労力を払うことなしに、
+常にビルド可能できちんと動作するドライバを手に入れることができる。
+
+
+ドライバをメインのカーネルツリーに入れると、非常に好ましい以下の効
+果がある。
+  - ドライバの品質が向上する一方で、（元の開発者にとっての）メンテ
+    ナンスコストは下がる。
+  - あなたのドライバに他の開発者が機能を追加してくれる。
+  - 誰かがあなたのドライバにあるバグを見つけ、修正してくれる。
+  - 誰かがあなたのドライバにある改善点を見つけてくれる。
+  - 外部インターフェースが変更されドライバの更新が必要になった場合、
+    誰かがあなたの代わりに更新してくれる。
+  - ドライバを入れてくれとディストロに頼まなくても、そのドライバは
+    全ての Linux ディストリビューションに自動的に含まれてリリース
+    される。
+
+
+Linux では、他のどのオペレーティングシステムよりも数多くのデバイス
+が「そのまま」使用できるようになった。また Linux は、どのオペレー
+ティングシステムよりも数多くのプロセッサアーキテクチャ上でそれらの
+デバイスを使用することができるようにもなった。このように、Linux の
+開発モデルは実証されており、今後も間違いなく正しい方向へと進んでい
+くだろう。:)
+
+
+
+------
+
+この文書の初期の草稿に対し、Randy Dunlap, Andrew Morton, David
+Brownell, Hanna Linder, Robert Love, Nishanth Aravamudan から査読
+と助言を頂きました。感謝申し上げます。
+
diff --git a/Documentation/translations/ja_JP/stable_kernel_rules.txt b/Documentation/translations/ja_JP/stable_kernel_rules.txt
new file mode 100644
index 000000000000..f9249aecba64
--- /dev/null
+++ b/Documentation/translations/ja_JP/stable_kernel_rules.txt
@@ -0,0 +1,84 @@
+NOTE:
+This is Japanese translated version of "Documentation/process/stable-kernel-rules.rst".
+This one is maintained by Tsugikazu Shibata 
+and JF Project team .
+If you find difference with original file or problem in translation,
+please contact maintainer of this file or JF project.
+
+Please also note that purpose of this file is easier to read for non
+English natives and do no intended to fork. So, if you have any
+comment or update of this file, please try to update Original(English)
+file at first.
+
+==================================
+これは、
+linux-2.6.29/Documentation/process/stable-kernel-rules.rst
+の和訳です。
+
+翻訳団体： JF プロジェクト < http://www.linux.or.jp/JF/ >
+翻訳日： 2009/1/14
+翻訳者： Tsugikazu Shibata 
+校正者： 武井伸光さん、
+         かねこさん (Seiji Kaneko) 
+         小林 雅典さん (Masanori Kobayasi) 
+         野口さん (Kenji Noguchi) 
+         神宮信太郎さん 
+==================================
+
+ずっと知りたかった Linux 2.6 -stable リリースの全て
+
+"-stable" ツリーにどのような種類のパッチが受け入れられるか、どのような
+ものが受け入れられないか、についての規則-
+
+ - 明らかに正しく、テストされているものでなければならない。
+ - 文脈(変更行の前後)を含めて 100 行より大きくてはいけない。
+ - ただ一個のことだけを修正しているべき。
+ - 皆を悩ませている本物のバグを修正しなければならない。("これはバグで
+   あるかもしれないが..." のようなものではない)
+ - ビルドエラー(CONFIG_BROKENになっているものを除く), oops, ハング、デー
+   タ破壊、現実のセキュリティ問題、その他 "ああ、これはダメだね"という
+   ようなものを修正しなければならない。短く言えば、重大な問題。
+ - 新しい device ID とクオークも受け入れられる。
+ - どのように競合状態が発生するかの説明も一緒に書かれていない限り、
+   "理論的には競合状態になる"ようなものは不可。
+ - いかなる些細な修正も含めることはできない。(スペルの修正、空白のクリー
+   ンアップなど)
+ - Documentation/process/submitting-patches.rst の規則に従ったものでなければならない。
+ - パッチ自体か同等の修正が Linus のツリーに既に存在しなければならない。
+　 Linus のツリーでのコミットID を -stable へのパッチ投稿の際に引用す
+   ること。
+
+-stable ツリーにパッチを送付する手続き-
+
+ - 上記の規則に従っているかを確認した後に、stable@vger.kernel.org にパッチ
+   を送る。
+ - 送信者はパッチがキューに受け付けられた際には ACK を、却下された場合
+   には NAK を受け取る。この反応は開発者たちのスケジュールによって、数
+   日かかる場合がある。
+ - もし受け取られたら、パッチは他の開発者たちと関連するサブシステムの
+   メンテナーによるレビューのために -stable キューに追加される。
+ - パッチに stable@vger.kernel.org のアドレスが付加されているときには、それ
+   が Linus のツリーに入る時に自動的に stable チームに email される。
+ - セキュリティパッチはこのエイリアス (stable@vger.kernel.org) に送られるべ
+   きではなく、代わりに security@kernel.org のアドレスに送られる。
+
+レビューサイクル-
+
+ - -stable メンテナがレビューサイクルを決めるとき、パッチはレビュー委
+   員会とパッチが影響する領域のメンテナ(提供者がその領域のメンテナで無
+   い限り)に送られ、linux-kernel メーリングリストにCCされる。
+ - レビュー委員会は 48時間の間に ACK か NAK を出す。
+ - もしパッチが委員会のメンバから却下されるか、メンテナ達やメンバが気付
+   かなかった問題が持ちあがり、linux-kernel メンバがパッチに異議を唱え
+   た場合には、パッチはキューから削除される。
+ - レビューサイクルの最後に、ACK を受けたパッチは最新の -stable リリー
+   スに追加され、その後に新しい -stable リリースが行われる。
+ - セキュリティパッチは、通常のレビューサイクルを通らず、セキュリティ
+   カーネルチームから直接 -stable ツリーに受け付けられる。
+   この手続きの詳細については kernel security チームに問い合わせること。
+
+レビュー委員会-
+
+ - この委員会は、このタスクについて活動する多くのボランティアと、少数の
+   非ボランティアのカーネル開発者達で構成されている。
+
diff --git a/Documentation/translations/ko_KR/HOWTO b/Documentation/translations/ko_KR/HOWTO
new file mode 100644
index 000000000000..3b0c15b277e0
--- /dev/null
+++ b/Documentation/translations/ko_KR/HOWTO
@@ -0,0 +1,637 @@
+NOTE:
+This is a version of Documentation/process/howto.rst translated into korean
+This document is maintained by Minchan Kim 
+If you find any difference between this document and the original file or
+a problem with the translation, please contact the maintainer of this file.
+
+Please also note that the purpose of this file is to be easier to
+read for non English (read: korean) speakers and is not intended as
+a fork. So if you have any comments or updates for this file please
+try to update the original English file first.
+
+----------------------------------
+
+이 문서는
+Documentation/process/howto.rst
+의 한글 번역입니다.
+
+역자： 김민찬 
+감수： 이제이미 
+
+----------------------------------
+
+
+어떻게 리눅스 커널 개발을 하는가
+================================
+
+이 문서는 커널 개발에 있어 가장 중요한 문서이다. 이 문서는
+리눅스 커널 개발자가 되는 법과 리눅스 커널 개발 커뮤니티와 일하는
+법을 담고있다. 커널 프로그래밍의 기술적인 측면과 관련된 내용들은
+포함하지 않으려고 하였지만 올바른 길로 여러분을 안내하는 데는 도움이
+될 것이다.
+
+이 문서에서 오래된 것을 발견하면 문서의 아래쪽에 나열된 메인테이너에게
+패치를 보내달라.
+
+
+소개
+----
+
+자, 여러분은 리눅스 커널 개발자가 되는 법을 배우고 싶은가? 아니면
+상사로부터"이 장치를 위한 리눅스 드라이버를 작성하시오"라는 말을
+들었는가? 이 문서의 목적은 여러분이 겪게 될 과정과 커뮤니티와 협력하는
+법을 조언하여 여러분의 목적을 달성하기 위해 필요한 것 모두를 알려주기
+위함이다.
+
+커널은 대부분은 C로 작성되어 있고 몇몇 아키텍쳐의 의존적인 부분은
+어셈블리로 작성되어 있다. 커널 개발을 위해 C를 잘 이해하고 있어야 한다.
+여러분이 특정 아키텍쳐의 low-level 개발을 할 것이 아니라면
+어셈블리(특정 아키텍쳐)는 잘 알아야 할 필요는 없다.
+다음의 참고서적들은 기본에 충실한 C 교육이나 수년간의 경험에 견주지는
+못하지만 적어도 참고 용도로는 좋을 것이다
+
+ - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
+ - "Practical C Programming" by Steve Oualline [O'Reilly]
+ - "C:  A Reference Manual" by Harbison and Steele [Prentice Hall]
+
+커널은 GNU C와 GNU 툴체인을 사용하여 작성되었다. 이 툴들은 ISO C89 표준을
+따르는 반면 표준에 있지 않은 많은 확장기능도 가지고 있다. 커널은 표준 C
+라이브러리와는 관계없이 freestanding C 환경이어서 C 표준의 일부는
+지원되지 않는다. 임의의 long long 나누기나 floating point는 지원되지 않는다.
+때론 이런 이유로 커널이 그런 확장 기능을 가진 툴체인을 가지고 만들어졌다는
+것이 이해하기 어려울 수도 있고 게다가 불행하게도 그런 것을 정확하게 설명하는
+어떤 참고문서도 있지 않다. 정보를 얻기 위해서는 gcc info (`info gcc`)페이지를
+살펴보라.
+
+여러분은 기존의 개발 커뮤니티와 협력하는 법을 배우려고 하고 있다는 것을
+기억하라. 코딩, 스타일, 함수에 관한 훌륭한 표준을 가진 사람들이 모인
+다양한 그룹이 있다. 이 표준들은 오랜동안 크고 지역적으로 분산된 팀들에
+의해 가장 좋은 방법으로 일하기 위하여 찾은 것을 기초로 만들어져 왔다.
+그 표준들은 문서화가 잘 되어있기 때문에 가능한한 미리 많은 표준들에
+관하여 배우려고 시도하라. 다른 사람들은 여러분이나 여러분의 회사가
+일하는 방식에 적응하는 것을 원하지는 않는다.
+
+
+법적 문제
+---------
+
+리눅스 커널 소스 코드는 GPL로 배포(release)되었다. 소스트리의 메인
+디렉토리에 있는 라이센스에 관하여 상세하게 쓰여 있는 COPYING이라는
+파일을 봐라. 여러분이 라이센스에 관한 더 깊은 문제를 가지고 있다면
+리눅스 커널 메일링 리스트에 묻지말고 변호사와 연락하라. 메일링
+리스트들에 있는 사람들은 변호사가 아니기 때문에 법적 문제에 관하여
+그들의 말에 의지해서는 안된다.
+
+GPL에 관한 잦은 질문들과 답변들은 다음을 참조하라.
+
+    https://www.gnu.org/licenses/gpl-faq.html
+
+
+문서
+----
+
+리눅스 커널 소스 트리는 커널 커뮤니티와 협력하는 법을 배우기위해 훌륭한
+다양한 문서들을 가지고 있다. 새로운 기능들이 커널에 들어가게 될 때,
+그 기능을 어떻게 사용하는지에 관한 설명을 위하여 새로운 문서 파일을
+추가하는 것을 권장한다. 커널이 유저스페이스로 노출하는 인터페이스를
+변경하게 되면 변경을 설명하는 메뉴얼 페이지들에 대한 패치나 정보를
+mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다.
+
+다음은 커널 소스 트리에 있는 읽어야 할 파일들의 리스트이다.
+
+  README
+    이 파일은 리눅스 커널에 관하여 간단한 배경 설명과 커널을 설정하고
+    빌드하기 위해 필요한 것을 설명한다. 커널에 입문하는 사람들은 여기서
+    시작해야 한다.
+
+  :ref:`Documentation/process/changes.rst `
+    이 파일은 커널을 성공적으로 빌드하고 실행시키기 위해 필요한 다양한
+    소프트웨어 패키지들의 최소 버젼을 나열한다.
+
+  :ref:`Documentation/process/coding-style.rst `
+    이 문서는 리눅스 커널 코딩 스타일과 그렇게 한 몇몇 이유를 설명한다.
+    모든 새로운 코드는 이 문서에 가이드라인들을 따라야 한다. 대부분의
+    메인테이너들은 이 규칙을 따르는 패치들만을 받아들일 것이고 많은 사람들이
+    그 패치가 올바른 스타일일 경우만 코드를 검토할 것이다.
+
+  :ref:`Documentation/process/submitting-patches.rst ` 와 :ref:`Documentation/process/submitting-drivers.rst `
+    이 파일들은 성공적으로 패치를 만들고 보내는 법을 다음의 내용들로
+    굉장히 상세히 설명하고 있다(그러나 다음으로 한정되진 않는다).
+
+       - Email 내용들
+       - Email 양식
+       - 그것을 누구에게 보낼지
+
+    이러한 규칙들을 따르는 것이 성공(역자주: 패치가 받아들여 지는 것)을
+    보장하진 않는다(왜냐하면 모든 패치들은 내용과 스타일에 관하여
+    면밀히 검토되기 때문이다). 그러나 규칙을 따르지 않는다면 거의
+    성공하지도 못할 것이다.
+
+    올바른 패치들을 만드는 법에 관한 훌륭한 다른 문서들이 있다.
+
+    "The Perfect Patch"
+        https://www.ozlabs.org/~akpm/stuff/tpp.txt
+
+    "Linux kernel patch submission format"
+        http://linux.yyz.us/patch-format.html
+
+   :ref:`Documentation/process/stable-api-nonsense.rst `
+    이 문서는 의도적으로 커널이 불변하는 API를 갖지 않도록 결정한
+    이유를 설명하며 다음과 같은 것들을 포함한다.
+
+       - 서브시스템 shim-layer(호환성을 위해?)
+       - 운영체제들간의 드라이버 이식성
+       - 커널 소스 트리내에 빠른 변화를 늦추는 것(또는 빠른 변화를 막는 것)
+
+    이 문서는 리눅스 개발 철학을 이해하는데 필수적이며 다른 운영체제에서
+    리눅스로 전향하는 사람들에게는 매우 중요하다.
+
+
+  :ref:`Documentation/admin-guide/security-bugs.rst `
+    여러분들이 리눅스 커널의 보안 문제를 발견했다고 생각한다면 이 문서에
+    나온 단계에 따라서 커널 개발자들에게 알리고 그 문제를 해결할 수 있도록
+    도와 달라.
+
+  :ref:`Documentation/process/management-style.rst `
+    이 문서는 리눅스 커널 메인테이너들이 그들의 방법론에 녹아 있는
+    정신을 어떻게 공유하고 운영하는지를 설명한다. 이것은 커널 개발에 입문하는
+    모든 사람들(또는 커널 개발에 작은 호기심이라도 있는 사람들)이
+    읽어야 할 중요한 문서이다. 왜냐하면 이 문서는 커널 메인테이너들의
+    독특한 행동에 관하여 흔히 있는 오해들과 혼란들을 해소하고 있기
+    때문이다.
+
+  :ref:`Documentation/process/stable_kernel_rules.rst `
+    이 문서는 안정적인 커널 배포가 이루어지는 규칙을 설명하고 있으며
+    여러분들이 이러한 배포들 중 하나에 변경을 하길 원한다면
+    무엇을 해야 하는지를 설명한다.
+
+  :ref:`Documentation/process/kernel-docs.rst `
+    커널 개발에 관계된 외부 문서의 리스트이다. 커널 내의 포함된 문서들
+    중에 여러분이 찾고 싶은 문서를 발견하지 못할 경우 이 리스트를
+    살펴보라.
+
+  :ref:`Documentation/process/applying-patches.rst `
+    패치가 무엇이며 그것을 커널의 다른 개발 브랜치들에 어떻게
+    적용하는지에 관하여 자세히 설명하고 있는 좋은 입문서이다.
+
+커널은 소스 코드 그 자체에서 또는 이것과 같은 ReStructuredText 마크업 (ReST) 을
+통해 자동적으로 만들어질 수 있는 많은 문서들을 가지고 있다. 이것은 커널 내의
+API에 대한 모든 설명, 그리고 락킹을 올바르게 처리하는 법에 관한 규칙을 포함하고
+있다.
+
+모든 그런 문서들은 커널 소스 디렉토리에서 다음 커맨드를 실행하는 것을 통해 PDF
+나 HTML 의 형태로 만들어질 수 있다::
+
+         make pdfdocs
+         make htmldocs
+
+ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된다.  해당
+문서들은 다음의 커맨드를 사용하면 LaTeX 이나 ePub 로도 만들어질 수 있다::
+
+         make latexdocs
+         make epubdocs
+
+현재, ReST 로의 변환이 진행중인, DocBook 으로 쓰인 문서들이 존재한다. 그런
+문서들은 Documentation/DocBook/ 디렉토리 안에 생성될 것이고 다음 커맨드를 통해
+Postscript 나 man page 로도 만들어질 수 있다::
+
+         make psdocs
+         make mandocs
+
+커널 개발자가 되는 것
+---------------------
+
+여러분이 리눅스 커널 개발에 관하여 아무것도 모른다면 Linux KernelNewbies
+프로젝트를 봐야 한다.
+
+    https://kernelnewbies.org
+
+그곳은 거의 모든 종류의 기본적인 커널 개발 질문들(질문하기 전에 먼저
+아카이브를 찾아봐라. 과거에 이미 답변되었을 수도 있다)을 할 수 있는 도움이
+될만한 메일링 리스트가 있다. 또한 실시간으로 질문 할 수 있는 IRC 채널도
+가지고 있으며 리눅스 커널 개발을 배우는 데 유용한 문서들을 보유하고 있다.
+
+웹사이트는 코드구성, 서브시스템들, 그리고 현재 프로젝트들
+(트리 내, 외부에 존재하는)에 관한 기본적인 정보들을 가지고 있다. 또한
+그곳은 커널 컴파일이나 패치를 하는 법과 같은 기본적인 것들을  설명한다.
+
+여러분이 어디서 시작해야 할진 모르지만 커널 개발 커뮤니티에 참여할 수
+있는 일들을 찾길 원한다면 리눅스 커널 Janitor 프로젝트를 살펴봐라.
+
+	https://kernelnewbies.org/KernelJanitors
+
+그곳은 시작하기에 훌륭한 장소이다. 그곳은 리눅스 커널 소스 트리내에
+간단히 정리되고 수정될 수 있는 문제들에 관하여 설명한다. 여러분은 이
+프로젝트를 대표하는 개발자들과 일하면서 자신의 패치를 리눅스 커널 트리에
+반영하기 위한 기본적인 것들을 배우게 될것이며 여러분이 아직 아이디어를
+가지고 있지 않다면 다음에 무엇을 해야할지에 관한 방향을 배울 수 있을
+것이다.
+
+여러분들이 이미 커널 트리에 반영하길 원하는 코드 묶음을 가지고 있지만
+올바른 포맷으로 포장하는데 도움이 필요하다면 그러한 문제를 돕기 위해
+만들어진 kernel-mentors 프로젝트가 있다. 그곳은 메일링 리스트이며
+다음에서 참조할 수 있다.
+
+         https://selenic.com/mailman/listinfo/kernel-mentors
+
+리눅스 커널 코드에 실제 변경을 하기 전에 반드시 그 코드가 어떻게
+동작하는지 이해하고 있어야 한다. 코드를 분석하기 위하여 특정한 툴의
+도움을 빌려서라도 코드를 직접 읽는 것보다 좋은 것은 없다(대부분의
+자잘한 부분들은 잘 코멘트되어 있다). 그런 툴들 중에 특히 추천할만한
+것은 Linux Cross-Reference project이며 그것은 자기 참조 방식이며
+소스코드를 인덱스된 웹 페이지들의 형태로 보여준다. 최신의 멋진 커널
+코드 저장소는 다음을 통하여 참조할 수 있다.
+
+      http://lxr.free-electrons.com/
+
+
+개발 프로세스
+-------------
+
+리눅스 커널 개발 프로세스는 현재 몇몇 다른 메인 커널 "브랜치들"과
+서브시스템에 특화된 커널 브랜치들로 구성된다. 몇몇 다른 메인
+브랜치들은 다음과 같다.
+
+  - main 4.x 커널 트리
+  - 4.x.y - 안정된 커널 트리
+  - 4.x -git 커널 패치들
+  - 서브시스템을 위한 커널 트리들과 패치들
+  - 4.x - 통합 테스트를 위한 next 커널 트리
+
+4.x 커널 트리
+~~~~~~~~~~~~~
+
+4.x 커널들은 Linus Torvalds가 관리하며 https://kernel.org 의
+pub/linux/kernel/v4.x/ 디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다.
+
+  - 새로운 커널이 배포되자마자 2주의 시간이 주어진다. 이 기간동은
+    메인테이너들은 큰 diff들을 Linus에게 제출할 수 있다. 대개 이 패치들은
+    몇 주 동안 -next 커널내에 이미 있었던 것들이다. 큰 변경들을 제출하는 데
+    선호되는 방법은  git(커널의 소스 관리 툴, 더 많은 정보들은
+    https://git-scm.com/ 에서 참조할 수 있다)를 사용하는 것이지만 순수한
+    패치파일의 형식으로 보내는 것도 무관하다.
+  - 2주 후에 -rc1 커널이 배포되며 지금부터는 전체 커널의 안정성에 영향을
+    미칠수 있는 새로운 기능들을 포함하지 않는 패치들만이 추가될 수 있다.
+    완전히 새로운 드라이버(혹은 파일시스템)는 -rc1 이후에만 받아들여진다는
+    것을 기억해라. 왜냐하면 변경이 자체내에서만 발생하고 추가된 코드가
+    드라이버 외부의 다른 부분에는 영향을 주지 않으므로 그런 변경은
+    회귀(역자주: 이전에는 존재하지 않았지만 새로운 기능추가나 변경으로 인해
+    생겨난 버그)를 일으킬 만한 위험을 가지고 있지 않기 때문이다. -rc1이
+    배포된 이후에 git를 사용하여 패치들을 Linus에게 보낼수 있지만 패치들은
+    공식적인 메일링 리스트로 보내서 검토를 받을 필요가 있다.
+  - 새로운 -rc는 Linus가 현재 git tree가 테스트 하기에 충분히 안정된 상태에
+    있다고 판단될 때마다 배포된다. 목표는 새로운 -rc 커널을 매주 배포하는
+    것이다.
+  - 이러한 프로세스는 커널이 "준비(ready)"되었다고 여겨질때까지 계속된다.
+    프로세스는 대체로 6주간 지속된다.
+
+커널 배포에 있어서 언급할만한 가치가 있는 리눅스 커널 메일링 리스트의
+Andrew Morton의 글이 있다.
+
+        *"커널이 언제 배포될지는 아무도 모른다. 왜냐하면 배포는 알려진
+         버그의 상황에 따라 배포되는 것이지 미리정해 놓은 시간에 따라
+         배포되는 것은 아니기 때문이다."*
+
+4.x.y - 안정 커널 트리
+~~~~~~~~~~~~~~~~~~~~~~
+
+3 자리 숫자로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 4.x
+커널에서 발견된 큰 회귀들이나 보안 문제들 중 비교적 작고 중요한 수정들을
+포함한다.
+
+이것은 가장 최근의 안정적인 커널을 원하는 사용자에게 추천되는 브랜치이며,
+개발/실험적 버젼을 테스트하는 것을 돕고자 하는 사용자들과는 별로 관련이 없다.
+
+어떤 4.x.y 커널도 사용할 수 없다면 그때는 가장 높은 숫자의 4.x
+커널이 현재의 안정 커널이다.
+
+4.x.y는 "stable" 팀에 의해 관리되며 거의 매번 격주로
+배포된다.
+
+커널 트리 문서들 내에 Documentation/process/stable-kernel-rules.rst 파일은 어떤
+종류의 변경들이 -stable 트리로 들어왔는지와 배포 프로세스가 어떻게
+진행되는지를 설명한다.
+
+4.x -git 패치들
+~~~~~~~~~~~~~~~
+
+git 저장소(그러므로 -git이라는 이름이 붙음)에는 날마다 관리되는 Linus의
+커널 트리의 snapshot 들이 있다. 이 패치들은 일반적으로 날마다 배포되며
+Linus의 트리의 현재 상태를 나타낸다. 이 패치들은 정상적인지 조금도
+살펴보지 않고 자동적으로 생성된 것이므로 -rc 커널들 보다도 더 실험적이다.
+
+서브시스템 커널 트리들과 패치들
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+다양한 커널 서브시스템의 메인테이너들 --- 그리고 많은 커널 서브시스템 개발자들
+--- 은 그들의 현재 개발 상태를 소스 저장소로 노출한다. 이를 통해 다른 사람들도
+커널의 다른 영역에 어떤 변화가 이루어지고 있는지 알 수 있다. 급속히 개발이
+진행되는 영역이 있고 그렇지 않은 영역이 있으므로, 개발자는 다른 개발자가 제출한
+수정 사항과 자신의 수정사항의 충돌이나 동일한 일을 동시에 두사람이 따로
+진행하는 사태를 방지하기 위해 급속히 개발이 진행되고 있는 영역에 작업의
+베이스를 맞춰줄 것이 요구된다.
+
+대부분의 이러한 저장소는 git 트리지만, git이 아닌 SCM으로 관리되거나, quilt
+시리즈로 제공되는 패치들도 존재한다. 이러한 서브시스템 저장소들은 MAINTAINERS
+파일에 나열되어 있다. 대부분은 https://git.kernel.org 에서 볼 수 있다.
+
+제안된 패치는 서브시스템 트리에 커밋되기 전에 메일링 리스트를 통해
+리뷰된다(아래의 관련 섹션을 참고하기 바란다). 일부 커널 서브시스템의 경우, 이
+리뷰 프로세스는 patchwork라는 도구를 통해 추적된다. patchwork은 등록된 패치와
+패치에 대한 코멘트, 패치의 버전을 볼 수 있는 웹 인터페이스를 제공하고,
+메인테이너는 패치를 리뷰 중, 리뷰 통과, 또는 반려됨으로 표시할 수 있다.
+대부분의 이러한 patchwork 사이트는 https://patchwork.kernel.org/ 또는
+http://patchwork.ozlabs.org/ 에 나열되어 있다.
+
+4.x - 통합 테스트를 위한 next 커널 트리
+---------------------------------------
+서브시스템 트리들의 변경사항들은 mainline 4.x 트리로 들어오기 전에 통합
+테스트를 거쳐야 한다. 이런 목적으로, 모든 서브시스템 트리의 변경사항을 거의
+매일 받아가는 특수한 테스트 저장소가 존재한다:
+
+       https://git.kernel.org/?p=linux/kernel/git/sfr/linux-next.git
+
+이런 식으로, -next 커널을 통해 다음 머지 기간에 메인라인 커널에 어떤 변경이
+가해질 것인지 간략히 알 수 있다. 모험심 강한 테스터라면 -next 커널에서 테스트를
+수행하는 것도 좋을 것이다.
+
+
+버그 보고
+---------
+
+https://bugzilla.kernel.org는 리눅스 커널 개발자들이 커널의 버그를 추적하는
+곳이다. 사용자들은 발견한 모든 버그들을 보고하기 위하여 이 툴을 사용할 것을
+권장한다.  kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라.
+
+    https://bugzilla.kernel.org/page.cgi?id=faq.html
+
+메인 커널 소스 디렉토리에 있는 admin-guide/reporting-bugs.rst 파일은 커널 버그라고 생각되는
+것을 보고하는 방법에 관한 좋은 템플릿이며 문제를 추적하기 위해서 커널
+개발자들이 필요로 하는 정보가 무엇들인지를 상세히 설명하고 있다.
+
+
+버그 리포트들의 관리
+--------------------
+
+여러분의 해킹 기술을 연습하는 가장 좋은 방법 중의 하는 다른 사람들이
+보고한 버그들을 수정하는 것이다. 여러분은 커널을 더욱 안정화시키는데
+도움을 줄 뿐만이 아니라 실제있는 문제들을 수정하는 법을 배우게 되고
+그와 함께 여러분들의 기술은 향상될 것이며 다른 개발자들이 여러분의
+존재에 대해 알게 될 것이다. 버그를 수정하는 것은 개발자들  사이에서
+점수를 얻을 수 있는 가장 좋은 방법중의 하나이다. 왜냐하면 많은 사람들은
+다른 사람들의 버그들을 수정하기 위하여 시간을 낭비하지 않기 때문이다.
+
+이미 보고된 버그 리포트들을 가지고 작업하기 위해서 https://bugzilla.kernel.org
+를 참조하라. 여러분이 앞으로 생겨날 버그 리포트들의 조언자가 되길 원한다면
+bugme-new 메일링 리스트나(새로운 버그 리포트들만이 이곳에서 메일로 전해진다)
+bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메일로 전해진다)
+에 등록하면 된다.
+
+      https://lists.linux-foundation.org/mailman/listinfo/bugme-new
+
+      https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
+
+
+
+메일링 리스트들
+---------------
+
+위의 몇몇 문서들이 설명하였지만 핵심 커널 개발자들의 대다수는
+리눅스 커널 메일링 리스트에 참여하고 있다. 리스트에 등록하고 해지하는
+방법에 관한 자세한 사항은 다음에서 참조할 수 있다.
+
+    http://vger.kernel.org/vger-lists.html#linux-kernel
+
+웹상의 많은 다른 곳에도 메일링 리스트의 아카이브들이 있다.
+이러한 아카이브들을 찾으려면 검색 엔진을 사용하라. 예를 들어:
+
+      http://dir.gmane.org/gmane.linux.kernel
+
+여러분이 새로운 문제에 관해 리스트에 올리기 전에 말하고 싶은 주제에 관한
+것을 아카이브에서 먼저 찾아보기를 강력히 권장한다. 이미 상세하게 토론된 많은
+것들이 메일링 리스트의 아카이브에 기록되어 있다.
+
+각각의 커널 서브시스템들의 대부분은 자신들의 개발에 관한 노력들로 이루어진
+분리된 메일링 리스트를 따로 가지고 있다. 다른 그룹들이 무슨 리스트를 가지고
+있는지는 MAINTAINERS 파일을 참조하라.
+
+많은 리스트들은 kernel.org에서 호스트되고 있다. 그 정보들은 다음에서 참조될 수 있다.
+
+         http://vger.kernel.org/vger-lists.html
+
+리스트들을 사용할 때는 올바른 예절을 따를 것을 유념해라.
+대단하진 않지만 다음 URL은 리스트(혹은 모든 리스트)와 대화하는 몇몇 간단한
+가이드라인을 가지고 있다.
+
+         http://www.albion.com/netiquette/
+
+여러 사람들이 여러분의 메일에 응답한다면 CC: 즉 수신 리스트는 꽤 커지게
+될 것이다. 아무 이유없이 CC에서 어떤 사람도 제거하거나 리스트 주소로만
+회신하지 마라. 메일을 보낸 사람으로서 하나를 받고 리스트로부터 또
+하나를 받아 두번 받는 것에 익숙하여 있으니 mail-header를 조작하려고 하지
+말아라. 사람들은 그런 것을 좋아하지 않을 것이다.
+
+여러분의 회신의 문맥을 원래대로 유지해야 한다. 여러분들의 회신의 윗부분에
+"John 커널해커는 작성했다...."를 유지하며 여러분들의 의견을 그 메일의 윗부분에
+작성하지 말고 각 인용한 단락들 사이에 넣어라.
+
+여러분들이 패치들을 메일에 넣는다면 그것들은 Documentation/process/submitting-patches.rst에
+나와있는데로 명백히(plain) 읽을 수 있는 텍스트여야 한다. 커널 개발자들은
+첨부파일이나 압축된 패치들을 원하지 않는다. 그들은 여러분들의 패치의
+각 라인 단위로 코멘트를 하길 원하며 압축하거나 첨부하지 않고 보내는 것이
+그렇게 할 수 있는 유일한 방법이다. 여러분들이 사용하는 메일 프로그램이
+스페이스나 탭 문자들을 조작하지 않는지 확인하라. 가장 좋은 첫 테스트는
+메일을 자신에게 보내보고 스스로 그 패치를 적용해보라. 그것이 동작하지
+않는다면 여러분의 메일 프로그램을 고치던가 제대로 동작하는 프로그램으로
+바꾸어라.
+
+무엇보다도 메일링 리스트의 다른 구독자들에게 보여주려 한다는 것을 기억하라.
+
+
+커뮤니티와 협력하는 법
+----------------------
+
+커널 커뮤니티의 목적은 가능한한 가장 좋은 커널을 제공하는 것이다. 여러분이
+받아들여질 패치를 제출하게 되면 그 패치의 기술적인 이점으로 검토될 것이다.
+그럼 여러분들은 무엇을 기대하고 있어야 하는가?
+
+ - 비판
+ - 의견
+ - 변경을 위한 요구
+ - 당위성을 위한 요구
+ - 침묵
+
+기억하라. 이것들은 여러분의 패치가 커널로 들어가기 위한 과정이다. 여러분의
+패치들은 비판과 다른 의견을 받을 수 있고 그것들을 기술적인 레벨로 평가하고
+재작업하거나 또는 왜 수정하면 안되는지에 관하여 명료하고 간결한 이유를
+말할 수 있어야 한다. 여러분이 제출한 것에 어떤 응답도 있지 않다면 몇 일을
+기다려보고 다시 시도해라. 때론 너무 많은 메일들 속에 묻혀버리기도 한다.
+
+여러분은 무엇을 해서는 안되는가?
+
+ - 여러분의 패치가 아무 질문 없이 받아들여지기를 기대하는 것
+ - 방어적이 되는 것
+ - 의견을 무시하는 것
+ - 요청된 변경을 하지 않고 패치를 다시 제출하는 것
+
+가능한한 가장 좋은 기술적인 해답을 찾고 있는 커뮤니티에서는 항상
+어떤 패치가 얼마나 좋은지에 관하여 다른 의견들이 있을 수 있다. 여러분은
+협조적이어야 하고 기꺼이 여러분의 생각을 커널 내에 맞추어야 한다. 아니면
+적어도 여러분의 것이 가치있다는 것을 증명하여야 한다. 잘못된 것도 여러분이
+올바른 방향의 해결책으로 이끌어갈 의지가 있다면 받아들여질 것이라는 점을
+기억하라.
+
+여러분의 첫 패치에 여러분이 수정해야하는 십여개 정도의 회신이 오는
+경우도 흔하다. 이것은 여러분의 패치가 받아들여지지 않을 것이라는 것을
+의미하는 것이 아니고 개인적으로 여러분에게 감정이 있어서 그러는 것도
+아니다. 간단히 여러분의 패치에 제기된 문제들을 수정하고 그것을 다시
+보내라.
+
+
+커널 커뮤니티와 기업 조직간의 차이점
+------------------------------------
+커널 커뮤니티는 가장 전통적인 회사의 개발 환경과는 다르다. 여기에 여러분들의
+문제를 피하기 위한 목록이 있다.
+
+  여러분들이 제안한 변경들에 관하여 말할 때 좋은 것들 :
+
+    - "이것은 여러 문제들을 해결합니다."
+    - "이것은 2000 라인의 코드를 줄입니다."
+    - "이것은 내가 말하려는 것에 관해 설명하는 패치입니다."
+    - "나는 5개의 다른 아키텍쳐에서 그것을 테스트 했으므로..."
+    - "여기에 일련의 작은 패치들이 있으므로..."
+    - "이것은 일반적인 머신에서 성능을 향상함으로..."
+
+  여러분들이 말할 때 피해야 할 좋지 않은 것들 :
+
+    - "우리는 그것을 AIX/ptx/Solaris에서 이러한 방법으로 했다. 그러므로 그것은 좋은 것임에 틀림없다..."
+    - "나는 20년동안 이것을 해왔다. 그러므로..."
+    - "이것은 돈을 벌기위해 나의 회사가 필요로 하는 것이다."
+    - "이것은 우리의 엔터프라이즈 상품 라인을 위한 것이다."
+    - "여기에 나의 생각을 말하고 있는 1000 페이지 설계 문서가 있다."
+    - "나는 6달동안 이것을 했으니..."
+    - "여기에 5000 라인 짜리 패치가 있으니..."
+    - "나는 현재 뒤죽박죽인 것을 재작성했다. 그리고 여기에..."
+    - "나는 마감시한을 가지고 있으므로 이 패치는 지금 적용될 필요가 있다."
+
+커널 커뮤니티가 전통적인 소프트웨어 엔지니어링 개발 환경들과
+또 다른 점은 얼굴을 보지 않고 일한다는 점이다. 이메일과 irc를 대화의
+주요수단으로 사용하는 것의 한가지 장점은 성별이나 인종의 차별이
+없다는 것이다. 리눅스 커널의 작업 환경에서는 단지 이메일 주소만
+알수 있기 때문에 여성과 소수 민족들도 모두 받아들여진다. 국제적으로
+일하게 되는 측면은 사람의 이름에 근거하여 성별을 추측할 수 없게
+하기때문에 차별을 없애는 데 도움을 준다. Andrea라는 이름을 가진 남자와
+Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅스 커널에서
+작업하며 생각을 표현해왔던 대부분의 여성들은 긍정적인 경험을 가지고
+있다.
+
+언어 장벽은 영어에 익숙하지 않은 몇몇 사람들에게 문제가 될 수도 있다.
+언어의 훌륭한 구사는 메일링 리스트에서 올바르게 자신의 생각을
+표현하기 위하여 필요하다. 그래서 여러분은 이메일을 보내기 전에
+영어를 올바르게 사용하고 있는지를 체크하는 것이 바람직하다.
+
+
+여러분의 변경을 나누어라
+------------------------
+
+리눅스 커널 커뮤니티는 한꺼번에 굉장히 큰 코드의 묶음(chunk)을 쉽게
+받아들이지 않는다. 변경은 적절하게 소개되고, 검토되고, 각각의
+부분으로 작게 나누어져야 한다. 이것은 회사에서 하는 것과는 정확히
+반대되는 것이다. 여러분들의 제안은 개발 초기에 일찍이 소개되야 한다.
+그래서 여러분들은 자신이 하고 있는 것에 관하여 피드백을 받을 수 있게
+된다. 커뮤니티가 여러분들이 커뮤니티와 함께 일하고 있다는 것을
+느끼도록 만들고 커뮤니티가 여러분의 기능을 위한 쓰레기 장으로써
+사용되지 않고 있다는 것을 느끼게 하자. 그러나 메일링 리스트에 한번에
+50개의 이메일을 보내지는 말아라. 여러분들의 일련의 패치들은 항상
+더 작아야 한다.
+
+패치를 나누는 이유는 다음과 같다.
+
+1) 작은 패치들은 여러분의 패치들이 적용될 수 있는 확률을 높여준다.
+   왜냐하면 다른 사람들은 정확성을 검증하기 위하여 많은 시간과 노력을
+   들이기를 원하지 않는다. 5줄의 패치는 메인테이너가 거의 몇 초간 힐끗
+   보면 적용될 수 있다. 그러나 500 줄의 패치는 정확성을 검토하기 위하여
+   몇시간이 걸릴 수도 있다(걸리는 시간은 패치의 크기 혹은 다른 것에
+   비례하여 기하급수적으로 늘어난다).
+
+   패치를 작게 만드는 것은 무엇인가 잘못되었을 때 디버그하는 것을
+   쉽게 만든다. 즉, 그렇게 만드는 것은 매우 큰 패치를 적용한 후에
+   조사하는 것 보다 작은 패치를 적용한 후에 (그리고 몇몇의 것이
+   깨졌을 때) 하나씩 패치들을 제거해가며 디버그 하기 쉽도록 만들어 준다.
+
+2) 작은 패치들을 보내는 것뿐만 아니라 패치들을 제출하기전에 재작성하고
+   간단하게(혹은 간단한게 재배치하여) 하는 것도 중요하다.
+
+여기에 커널 개발자 Al Viro의 이야기가 있다.
+
+    *"학생의 수학 숙제를 채점하는 선생님을 생각해보라. 선생님은 학생들이
+    답을 얻을때까지 겪은 시행착오를 보길 원하지 않는다. 선생님들은
+    간결하고 가장 뛰어난 답을 보길 원한다. 훌륭한 학생은 이것을 알고
+    마지막으로 답을 얻기 전 중간 과정들을 제출하진 않는다.*
+
+    *커널 개발도 마찬가지이다. 메인테이너들과 검토하는 사람들은 문제를
+    풀어나가는 과정속에 숨겨진 과정을 보길 원하진 않는다. 그들은
+    간결하고 멋진 답을 보길 원한다."*
+
+커뮤니티와 협력하며 뛰어난 답을 찾는 것과 여러분들의 끝마치지 못한 작업들
+사이에 균형을 유지해야 하는 것은 어려울지도 모른다. 그러므로 프로세스의
+초반에 여러분의 작업을 향상시키기위한 피드백을 얻는 것 뿐만 아니라
+여러분들의 변경들을 작은 묶음으로 유지해서 심지어는 여러분의 작업의
+모든 부분이 지금은 포함될 준비가 되어있지 않지만 작은 부분은 벌써
+받아들여질 수 있도록 유지하는 것이 바람직하다.
+
+또한 완성되지 않았고 "나중에 수정될 것이다." 와 같은 것들을 포함하는
+패치들은 받아들여지지 않을 것이라는 점을 유념하라.
+
+
+변경을 정당화해라
+-----------------
+
+여러분들의 나누어진 패치들을 리눅스 커뮤니티가 왜 반영해야 하는지를
+알도록 하는 것은 매우 중요하다. 새로운 기능들이 필요하고 유용하다는
+것은 반드시 그에 합당한 이유가 있어야 한다.
+
+
+변경을 문서화해라
+-----------------
+
+여러분이 패치를 보내려 할때는 여러분이 무엇을 말하려고 하는지를 충분히
+생각하여 이메일을 작성해야 한다. 이 정보는 패치를 위한 ChangeLog가 될
+것이다. 그리고 항상 그 내용을 보길 원하는 모든 사람들을 위해 보존될
+것이다. 패치는 완벽하게 다음과 같은 내용들을 포함하여 설명해야 한다.
+
+  - 변경이 왜 필요한지
+  - 패치에 관한 전체 설계 접근(approach)
+  - 구현 상세들
+  - 테스트 결과들
+
+이것이 무엇인지 더 자세한 것을 알고 싶다면 다음 문서의 ChageLog 항을 봐라.
+
+   "The Perfect Patch"
+
+    http://www.ozlabs.org/~akpm/stuff/tpp.txt
+
+
+이 모든 것을 하는 것은 매우 어려운 일이다. 완벽히 소화하는 데는 적어도 몇년이
+걸릴 수도 있다. 많은 인내와 결심이 필요한 계속되는 개선의 과정이다. 그러나
+가능한한 포기하지 말라. 많은 사람들은 이전부터 해왔던 것이고 그 사람들도
+정확하게 여러분들이 지금 서 있는 그 곳부터  시작했었다.
+
+
+
+
+----------
+
+"개발 프로세스"(https://lwn.net/Articles/94386/) 섹션을
+작성하는데 있어 참고할 문서를 사용하도록 허락해준 Paolo Ciarrocchi에게
+감사한다. 여러분들이 말해야 할 것과 말해서는 안되는 것의 목록 중 일부를 제공해준
+Randy Dunlap과 Gerrit Huizenga에게 감사한다. 또한 검토와 의견 그리고
+공헌을 아끼지 않은 Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers,
+Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi Kleen,
+Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop,
+David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard에게도 감사를 전한다.
+그들의 도움이 없었다면 이 문서는 존재하지 않았을 것이다.
+
+
+
+메인테이너: Greg Kroah-Hartman 
diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt
new file mode 100644
index 000000000000..a3228a676cc1
--- /dev/null
+++ b/Documentation/translations/ko_KR/memory-barriers.txt
@@ -0,0 +1,3171 @@
+NOTE:
+This is a version of Documentation/memory-barriers.txt translated into Korean.
+This document is maintained by SeongJae Park .
+If you find any difference between this document and the original file or
+a problem with the translation, please contact the maintainer of this file.
+
+Please also note that the purpose of this file is to be easier to
+read for non English (read: Korean) speakers and is not intended as
+a fork.  So if you have any comments or updates for this file please
+update the original English file first.  The English version is
+definitive, and readers should look there if they have any doubt.
+
+===================================
+이 문서는
+Documentation/memory-barriers.txt
+의 한글 번역입니다.
+
+역자： 박성재 
+===================================
+
+
+			 =========================
+			 리눅스 커널 메모리 배리어
+			 =========================
+
+저자: David Howells 
+      Paul E. McKenney 
+      Will Deacon 
+      Peter Zijlstra 
+
+========
+면책조항
+========
+
+이 문서는 명세서가 아닙니다; 이 문서는 완벽하지 않은데, 간결성을 위해 의도된
+부분도 있고, 의도하진 않았지만 사람에 의해 쓰였다보니 불완전한 부분도 있습니다.
+이 문서는 리눅스에서 제공하는 다양한 메모리 배리어들을 사용하기 위한
+안내서입니다만, 뭔가 이상하다 싶으면 (그런게 많을 겁니다) 질문을 부탁드립니다.
+
+다시 말하지만, 이 문서는 리눅스가 하드웨어에 기대하는 사항에 대한 명세서가
+아닙니다.
+
+이 문서의 목적은 두가지입니다:
+
+ (1) 어떤 특정 배리어에 대해 기대할 수 있는 최소한의 기능을 명세하기 위해서,
+     그리고
+
+ (2) 사용 가능한 배리어들에 대해 어떻게 사용해야 하는지에 대한 안내를 제공하기
+     위해서.
+
+어떤 아키텍쳐는 특정한 배리어들에 대해서는 여기서 이야기하는 최소한의
+요구사항들보다 많은 기능을 제공할 수도 있습니다만, 여기서 이야기하는
+요구사항들을 충족하지 않는 아키텍쳐가 있다면 그 아키텍쳐가 잘못된 것이란 점을
+알아두시기 바랍니다.
+
+또한, 특정 아키텍쳐에서 일부 배리어는 해당 아키텍쳐의 특수한 동작 방식으로 인해
+해당 배리어의 명시적 사용이 불필요해서 no-op 이 될수도 있음을 알아두시기
+바랍니다.
+
+역자: 본 번역 역시 완벽하지 않은데, 이 역시 부분적으로는 의도된 것이기도
+합니다.  여타 기술 문서들이 그렇듯 완벽한 이해를 위해서는 번역문과 원문을 함께
+읽으시되 번역문을 하나의 가이드로 활용하시길 추천드리며, 발견되는 오역 등에
+대해서는 언제든 의견을 부탁드립니다.  과한 번역으로 인한 오해를 최소화하기 위해
+애매한 부분이 있을 경우에는 어색함이 있더라도 원래의 용어를 차용합니다.
+
+
+=====
+목차:
+=====
+
+ (*) 추상 메모리 액세스 모델.
+
+     - 디바이스 오퍼레이션.
+     - 보장사항.
+
+ (*) 메모리 배리어란 무엇인가?
+
+     - 메모리 배리어의 종류.
+     - 메모리 배리어에 대해 가정해선 안될 것.
+     - 데이터 의존성 배리어.
+     - 컨트롤 의존성.
+     - SMP 배리어 짝맞추기.
+     - 메모리 배리어 시퀀스의 예.
+     - 읽기 메모리 배리어 vs 로드 예측.
+     - 이행성
+
+ (*) 명시적 커널 배리어.
+
+     - 컴파일러 배리어.
+     - CPU 메모리 배리어.
+     - MMIO 쓰기 배리어.
+
+ (*) 암묵적 커널 메모리 배리어.
+
+     - 락 Acquisition 함수.
+     - 인터럽트 비활성화 함수.
+     - 슬립과 웨이크업 함수.
+     - 그외의 함수들.
+
+ (*) CPU 간 ACQUIRING 배리어의 효과.
+
+     - Acquire vs 메모리 액세스.
+     - Acquire vs I/O 액세스.
+
+ (*) 메모리 배리어가 필요한 곳
+
+     - 프로세서간 상호 작용.
+     - 어토믹 오퍼레이션.
+     - 디바이스 액세스.
+     - 인터럽트.
+
+ (*) 커널 I/O 배리어의 효과.
+
+ (*) 가정되는 가장 완화된 실행 순서 모델.
+
+ (*) CPU 캐시의 영향.
+
+     - 캐시 일관성.
+     - 캐시 일관성 vs DMA.
+     - 캐시 일관성 vs MMIO.
+
+ (*) CPU 들이 저지르는 일들.
+
+     - 그리고, Alpha 가 있다.
+     - 가상 머신 게스트.
+
+ (*) 사용 예.
+
+     - 순환식 버퍼.
+
+ (*) 참고 문헌.
+
+
+=======================
+추상 메모리 액세스 모델
+=======================
+
+다음과 같이 추상화된 시스템 모델을 생각해 봅시다:
+
+		            :                :
+		            :                :
+		            :                :
+		+-------+   :   +--------+   :   +-------+
+		|       |   :   |        |   :   |       |
+		|       |   :   |        |   :   |       |
+		| CPU 1 |<----->| Memory |<----->| CPU 2 |
+		|       |   :   |        |   :   |       |
+		|       |   :   |        |   :   |       |
+		+-------+   :   +--------+   :   +-------+
+		    ^       :       ^        :       ^
+		    |       :       |        :       |
+		    |       :       |        :       |
+		    |       :       v        :       |
+		    |       :   +--------+   :       |
+		    |       :   |        |   :       |
+		    |       :   |        |   :       |
+		    +---------->| Device |<----------+
+		            :   |        |   :
+		            :   |        |   :
+		            :   +--------+   :
+		            :                :
+
+프로그램은 여러 메모리 액세스 오퍼레이션을 발생시키고, 각각의 CPU 는 그런
+프로그램들을 실행합니다.  추상화된 CPU 모델에서 메모리 오퍼레이션들의 순서는
+매우 완화되어 있고, CPU 는 프로그램이 인과관계를 어기지 않는 상태로 관리된다고
+보일 수만 있다면 메모리 오퍼레이션을 자신이 원하는 어떤 순서대로든 재배치해
+동작시킬 수 있습니다.  비슷하게, 컴파일러 또한 프로그램의 정상적 동작을 해치지
+않는 한도 내에서는 어떤 순서로든 자신이 원하는 대로 인스트럭션을 재배치 할 수
+있습니다.
+
+따라서 위의 다이어그램에서 한 CPU가 동작시키는 메모리 오퍼레이션이 만들어내는
+변화는 해당 오퍼레이션이 CPU 와 시스템의 다른 부분들 사이의 인터페이스(점선)를
+지나가면서 시스템의 나머지 부분들에 인지됩니다.
+
+
+예를 들어, 다음의 일련의 이벤트들을 생각해 봅시다:
+
+	CPU 1		CPU 2
+	===============	===============
+	{ A == 1; B == 2 }
+	A = 3;		x = B;
+	B = 4;		y = A;
+
+다이어그램의 가운데에 위치한 메모리 시스템에 보여지게 되는 액세스들은 다음의 총
+24개의 조합으로 재구성될 수 있습니다:
+
+	STORE A=3,	STORE B=4,	y=LOAD A->3,	x=LOAD B->4
+	STORE A=3,	STORE B=4,	x=LOAD B->4,	y=LOAD A->3
+	STORE A=3,	y=LOAD A->3,	STORE B=4,	x=LOAD B->4
+	STORE A=3,	y=LOAD A->3,	x=LOAD B->2,	STORE B=4
+	STORE A=3,	x=LOAD B->2,	STORE B=4,	y=LOAD A->3
+	STORE A=3,	x=LOAD B->2,	y=LOAD A->3,	STORE B=4
+	STORE B=4,	STORE A=3,	y=LOAD A->3,	x=LOAD B->4
+	STORE B=4, ...
+	...
+
+따라서 다음의 네가지 조합의 값들이 나올 수 있습니다:
+
+	x == 2, y == 1
+	x == 2, y == 3
+	x == 4, y == 1
+	x == 4, y == 3
+
+
+한발 더 나아가서, 한 CPU 가 메모리 시스템에 반영한 스토어 오퍼레이션들의 결과는
+다른 CPU 에서의 로드 오퍼레이션을 통해 인지되는데, 이 때 스토어가 반영된 순서와
+다른 순서로 인지될 수도 있습니다.
+
+
+예로, 아래의 일련의 이벤트들을 생각해 봅시다:
+
+	CPU 1		CPU 2
+	===============	===============
+	{ A == 1, B == 2, C == 3, P == &A, Q == &C }
+	B = 4;		Q = P;
+	P = &B		D = *Q;
+
+D 로 읽혀지는 값은 CPU 2 에서 P 로부터 읽혀진 주소값에 의존적이기 때문에 여기엔
+분명한 데이터 의존성이 있습니다.  하지만 이 이벤트들의 실행 결과로는 아래의
+결과들이 모두 나타날 수 있습니다:
+
+	(Q == &A) and (D == 1)
+	(Q == &B) and (D == 2)
+	(Q == &B) and (D == 4)
+
+CPU 2 는 *Q 의 로드를 요청하기 전에 P 를 Q 에 넣기 때문에 D 에 C 를 집어넣는
+일은 없음을 알아두세요.
+
+
+디바이스 오퍼레이션
+-------------------
+
+일부 디바이스는 자신의 컨트롤 인터페이스를 메모리의 특정 영역으로 매핑해서
+제공하는데(Memory mapped I/O), 해당 컨트롤 레지스터에 접근하는 순서는 매우
+중요합니다.  예를 들어, 어드레스 포트 레지스터 (A) 와 데이터 포트 레지스터 (D)
+를 통해 접근되는 내부 레지스터 집합을 갖는 이더넷 카드를 생각해 봅시다.  내부의
+5번 레지스터를 읽기 위해 다음의 코드가 사용될 수 있습니다:
+
+	*A = 5;
+	x = *D;
+
+하지만, 이건 다음의 두 조합 중 하나로 만들어질 수 있습니다:
+
+	STORE *A = 5, x = LOAD *D
+	x = LOAD *D, STORE *A = 5
+
+두번째 조합은 데이터를 읽어온 _후에_ 주소를 설정하므로, 오동작을 일으킬 겁니다.
+
+
+보장사항
+--------
+
+CPU 에게 기대할 수 있는 최소한의 보장사항 몇가지가 있습니다:
+
+ (*) 어떤 CPU 든, 의존성이 존재하는 메모리 액세스들은 해당 CPU 자신에게
+     있어서는 순서대로 메모리 시스템에 수행 요청됩니다. 즉, 다음에 대해서:
+
+	Q = READ_ONCE(P); smp_read_barrier_depends(); D = READ_ONCE(*Q);
+
+     CPU 는 다음과 같은 메모리 오퍼레이션 시퀀스를 수행 요청합니다:
+
+	Q = LOAD P, D = LOAD *Q
+
+     그리고 그 시퀀스 내에서의 순서는 항상 지켜집니다.  대부분의 시스템에서
+     smp_read_barrier_depends() 는 아무일도 안하지만 DEC Alpha 에서는
+     명시적으로 사용되어야 합니다.  보통의 경우에는 smp_read_barrier_depends()
+     를 직접 사용하는 대신 rcu_dereference() 같은 것들을 사용해야 함을
+     알아두세요.
+
+ (*) 특정 CPU 내에서 겹치는 영역의 메모리에 행해지는 로드와 스토어 들은 해당
+     CPU 안에서는 순서가 바뀌지 않은 것으로 보여집니다.  즉, 다음에 대해서:
+
+	a = READ_ONCE(*X); WRITE_ONCE(*X, b);
+
+     CPU 는 다음의 메모리 오퍼레이션 시퀀스만을 메모리에 요청할 겁니다:
+
+	a = LOAD *X, STORE *X = b
+
+     그리고 다음에 대해서는:
+
+	WRITE_ONCE(*X, c); d = READ_ONCE(*X);
+
+     CPU 는 다음의 수행 요청만을 만들어 냅니다:
+
+	STORE *X = c, d = LOAD *X
+
+     (로드 오퍼레이션과 스토어 오퍼레이션이 겹치는 메모리 영역에 대해
+     수행된다면 해당 오퍼레이션들은 겹친다고 표현됩니다).
+
+그리고 _반드시_ 또는 _절대로_ 가정하거나 가정하지 말아야 하는 것들이 있습니다:
+
+ (*) 컴파일러가 READ_ONCE() 나 WRITE_ONCE() 로 보호되지 않은 메모리 액세스를
+     당신이 원하는 대로 할 것이라는 가정은 _절대로_ 해선 안됩니다.  그것들이
+     없다면, 컴파일러는 컴파일러 배리어 섹션에서 다루게 될, 모든 "창의적인"
+     변경들을 만들어낼 권한을 갖게 됩니다.
+
+ (*) 개별적인 로드와 스토어들이 주어진 순서대로 요청될 것이라는 가정은 _절대로_
+     하지 말아야 합니다.  이 말은 곧:
+
+	X = *A; Y = *B; *D = Z;
+
+     는 다음의 것들 중 어느 것으로든 만들어질 수 있다는 의미입니다:
+
+	X = LOAD *A,  Y = LOAD *B,  STORE *D = Z
+	X = LOAD *A,  STORE *D = Z, Y = LOAD *B
+	Y = LOAD *B,  X = LOAD *A,  STORE *D = Z
+	Y = LOAD *B,  STORE *D = Z, X = LOAD *A
+	STORE *D = Z, X = LOAD *A,  Y = LOAD *B
+	STORE *D = Z, Y = LOAD *B,  X = LOAD *A
+
+ (*) 겹치는 메모리 액세스들은 합쳐지거나 버려질 수 있음을 _반드시_ 가정해야
+     합니다.  다음의 코드는:
+
+	X = *A; Y = *(A + 4);
+
+     다음의 것들 중 뭐든 될 수 있습니다:
+
+	X = LOAD *A; Y = LOAD *(A + 4);
+	Y = LOAD *(A + 4); X = LOAD *A;
+	{X, Y} = LOAD {*A, *(A + 4) };
+
+     그리고:
+
+	*A = X; *(A + 4) = Y;
+
+     는 다음 중 뭐든 될 수 있습니다:
+
+	STORE *A = X; STORE *(A + 4) = Y;
+	STORE *(A + 4) = Y; STORE *A = X;
+	STORE {*A, *(A + 4) } = {X, Y};
+
+그리고 보장사항에 반대되는 것들(anti-guarantees)이 있습니다:
+
+ (*) 이 보장사항들은 bitfield 에는 적용되지 않는데, 컴파일러들은 bitfield 를
+     수정하는 코드를 생성할 때 원자성 없는(non-atomic) 읽고-수정하고-쓰는
+     인스트럭션들의 조합을 만드는 경우가 많기 때문입니다.  병렬 알고리즘의
+     동기화에 bitfield 를 사용하려 하지 마십시오.
+
+ (*) bitfield 들이 여러 락으로 보호되는 경우라 하더라도, 하나의 bitfield 의
+     모든 필드들은 하나의 락으로 보호되어야 합니다.  만약 한 bitfield 의 두
+     필드가 서로 다른 락으로 보호된다면, 컴파일러의 원자성 없는
+     읽고-수정하고-쓰는 인스트럭션 조합은 한 필드에의 업데이트가 근처의
+     필드에도 영향을 끼치게 할 수 있습니다.
+
+ (*) 이 보장사항들은 적절하게 정렬되고 크기가 잡힌 스칼라 변수들에 대해서만
+     적용됩니다.  "적절하게 크기가 잡힌" 이라함은 현재로써는 "char", "short",
+     "int" 그리고 "long" 과 같은 크기의 변수들을 의미합니다.  "적절하게 정렬된"
+     은 자연스런 정렬을 의미하는데, 따라서 "char" 에 대해서는 아무 제약이 없고,
+     "short" 에 대해서는 2바이트 정렬을, "int" 에는 4바이트 정렬을, 그리고
+     "long" 에 대해서는 32-bit 시스템인지 64-bit 시스템인지에 따라 4바이트 또는
+     8바이트 정렬을 의미합니다.  이 보장사항들은 C11 표준에서 소개되었으므로,
+     C11 전의 오래된 컴파일러(예를 들어, gcc 4.6) 를 사용할 때엔 주의하시기
+     바랍니다.  표준에 이 보장사항들은 "memory location" 을 정의하는 3.14
+     섹션에 다음과 같이 설명되어 있습니다:
+     (역자: 인용문이므로 번역하지 않습니다)
+
+	memory location
+		either an object of scalar type, or a maximal sequence
+		of adjacent bit-fields all having nonzero width
+
+		NOTE 1: Two threads of execution can update and access
+		separate memory locations without interfering with
+		each other.
+
+		NOTE 2: A bit-field and an adjacent non-bit-field member
+		are in separate memory locations. The same applies
+		to two bit-fields, if one is declared inside a nested
+		structure declaration and the other is not, or if the two
+		are separated by a zero-length bit-field declaration,
+		or if they are separated by a non-bit-field member
+		declaration. It is not safe to concurrently update two
+		bit-fields in the same structure if all members declared
+		between them are also bit-fields, no matter what the
+		sizes of those intervening bit-fields happen to be.
+
+
+=========================
+메모리 배리어란 무엇인가?
+=========================
+
+앞에서 봤듯이, 상호간 의존성이 없는 메모리 오퍼레이션들은 실제로는 무작위적
+순서로 수행될 수 있으며, 이는 CPU 와 CPU 간의 상호작용이나 I/O 에 문제가 될 수
+있습니다.  따라서 컴파일러와 CPU 가 순서를 바꾸는데 제약을 걸 수 있도록 개입할
+수 있는 어떤 방법이 필요합니다.
+
+메모리 배리어는 그런 개입 수단입니다.  메모리 배리어는 배리어를 사이에 둔 앞과
+뒤 양측의 메모리 오퍼레이션들 간에 부분적 순서가 존재하도록 하는 효과를 줍니다.
+
+시스템의 CPU 들과 여러 디바이스들은 성능을 올리기 위해 명령어 재배치, 실행
+유예, 메모리 오퍼레이션들의 조합, 예측적 로드(speculative load), 브랜치
+예측(speculative branch prediction), 다양한 종류의 캐싱(caching) 등의 다양한
+트릭을 사용할 수 있기 때문에 이런 강제력은 중요합니다.  메모리 배리어들은 이런
+트릭들을 무효로 하거나 억제하는 목적으로 사용되어져서 코드가 여러 CPU 와
+디바이스들 간의 상호작용을 정상적으로 제어할 수 있게 해줍니다.
+
+
+메모리 배리어의 종류
+--------------------
+
+메모리 배리어는 네개의 기본 타입으로 분류됩니다:
+
+ (1) 쓰기 (또는 스토어) 메모리 배리어.
+
+     쓰기 메모리 배리어는 시스템의 다른 컴포넌트들에 해당 배리어보다 앞서
+     명시된 모든 STORE 오퍼레이션들이 해당 배리어 뒤에 명시된 모든 STORE
+     오퍼레이션들보다 먼저 수행된 것으로 보일 것을 보장합니다.
+
+     쓰기 배리어는 스토어 오퍼레이션들에 대한 부분적 순서 세우기입니다; 로드
+     오퍼레이션들에 대해서는 어떤 영향도 끼치지 않습니다.
+
+     CPU 는 시간의 흐름에 따라 메모리 시스템에 일련의 스토어 오퍼레이션들을
+     하나씩 요청해 집어넣습니다.  쓰기 배리어 앞의 모든 스토어 오퍼레이션들은
+     쓰기 배리어 뒤의 모든 스토어 오퍼레이션들보다 _앞서_ 수행될 겁니다.
+
+     [!] 쓰기 배리어들은 읽기 또는 데이터 의존성 배리어와 함께 짝을 맞춰
+     사용되어야만 함을 알아두세요; "SMP 배리어 짝맞추기" 서브섹션을 참고하세요.
+
+
+ (2) 데이터 의존성 배리어.
+
+     데이터 의존성 배리어는 읽기 배리어의 보다 완화된 형태입니다.  두개의 로드
+     오퍼레이션이 있고 두번째 것이 첫번째 것의 결과에 의존하고 있을 때(예:
+     두번째 로드가 참조할 주소를 첫번째 로드가 읽는 경우), 두번째 로드가 읽어올
+     데이터는 첫번째 로드에 의해 그 주소가 얻어지기 전에 업데이트 되어 있음을
+     보장하기 위해서 데이터 의존성 배리어가 필요할 수 있습니다.
+
+     데이터 의존성 배리어는 상호 의존적인 로드 오퍼레이션들 사이의 부분적 순서
+     세우기입니다; 스토어 오퍼레이션들이나 독립적인 로드들, 또는 중복되는
+     로드들에 대해서는 어떤 영향도 끼치지 않습니다.
+
+     (1) 에서 언급했듯이, 시스템의 CPU 들은 메모리 시스템에 일련의 스토어
+     오퍼레이션들을 던져 넣고 있으며, 거기에 관심이 있는 다른 CPU 는 그
+     오퍼레이션들을 메모리 시스템이 실행한 결과를 인지할 수 있습니다.  이처럼
+     다른 CPU 의 스토어 오퍼레이션의 결과에 관심을 두고 있는 CPU 가 수행 요청한
+     데이터 의존성 배리어는, 배리어 앞의 어떤 로드 오퍼레이션이 다른 CPU 에서
+     던져 넣은 스토어 오퍼레이션과 같은 영역을 향했다면, 그런 스토어
+     오퍼레이션들이 만들어내는 결과가 데이터 의존성 배리어 뒤의 로드
+     오퍼레이션들에게는 보일 것을 보장합니다.
+
+     이 순서 세우기 제약에 대한 그림을 보기 위해선 "메모리 배리어 시퀀스의 예"
+     서브섹션을 참고하시기 바랍니다.
+
+     [!] 첫번째 로드는 반드시 _데이터_ 의존성을 가져야지 컨트롤 의존성을 가져야
+     하는게 아님을 알아두십시오.  만약 두번째 로드를 위한 주소가 첫번째 로드에
+     의존적이지만 그 의존성은 조건적이지 그 주소 자체를 가져오는게 아니라면,
+     그것은 _컨트롤_ 의존성이고, 이 경우에는 읽기 배리어나 그보다 강력한
+     무언가가 필요합니다.  더 자세한 내용을 위해서는 "컨트롤 의존성" 서브섹션을
+     참고하시기 바랍니다.
+
+     [!] 데이터 의존성 배리어는 보통 쓰기 배리어들과 함께 짝을 맞춰 사용되어야
+     합니다; "SMP 배리어 짝맞추기" 서브섹션을 참고하세요.
+
+
+ (3) 읽기 (또는 로드) 메모리 배리어.
+
+     읽기 배리어는 데이터 의존성 배리어 기능의 보장사항에 더해서 배리어보다
+     앞서 명시된 모든 LOAD 오퍼레이션들이 배리어 뒤에 명시되는 모든 LOAD
+     오퍼레이션들보다 먼저 행해진 것으로 시스템의 다른 컴포넌트들에 보여질 것을
+     보장합니다.
+
+     읽기 배리어는 로드 오퍼레이션에 행해지는 부분적 순서 세우기입니다; 스토어
+     오퍼레이션에 대해서는 어떤 영향도 끼치지 않습니다.
+
+     읽기 메모리 배리어는 데이터 의존성 배리어를 내장하므로 데이터 의존성
+     배리어를 대신할 수 있습니다.
+
+     [!] 읽기 배리어는 일반적으로 쓰기 배리어들과 함께 짝을 맞춰 사용되어야
+     합니다; "SMP 배리어 짝맞추기" 서브섹션을 참고하세요.
+
+
+ (4) 범용 메모리 배리어.
+
+     범용(general) 메모리 배리어는 배리어보다 앞서 명시된 모든 LOAD 와 STORE
+     오퍼레이션들이 배리어 뒤에 명시된 모든 LOAD 와 STORE 오퍼레이션들보다
+     먼저 수행된 것으로 시스템의 나머지 컴포넌트들에 보이게 됨을 보장합니다.
+
+     범용 메모리 배리어는 로드와 스토어 모두에 대한 부분적 순서 세우기입니다.
+
+     범용 메모리 배리어는 읽기 메모리 배리어, 쓰기 메모리 배리어 모두를
+     내장하므로, 두 배리어를 모두 대신할 수 있습니다.
+
+
+그리고 두개의 명시적이지 않은 타입이 있습니다:
+
+ (5) ACQUIRE 오퍼레이션.
+
+     이 타입의 오퍼레이션은 단방향의 투과성 배리어처럼 동작합니다.  ACQUIRE
+     오퍼레이션 뒤의 모든 메모리 오퍼레이션들이 ACQUIRE 오퍼레이션 후에
+     일어난 것으로 시스템의 나머지 컴포넌트들에 보이게 될 것이 보장됩니다.
+     LOCK 오퍼레이션과 smp_load_acquire(), smp_cond_acquire() 오퍼레이션도
+     ACQUIRE 오퍼레이션에 포함됩니다.  smp_cond_acquire() 오퍼레이션은 컨트롤
+     의존성과 smp_rmb() 를 사용해서 ACQUIRE 의 의미적 요구사항(semantic)을
+     충족시킵니다.
+
+     ACQUIRE 오퍼레이션 앞의 메모리 오퍼레이션들은 ACQUIRE 오퍼레이션 완료 후에
+     수행된 것처럼 보일 수 있습니다.
+
+     ACQUIRE 오퍼레이션은 거의 항상 RELEASE 오퍼레이션과 짝을 지어 사용되어야
+     합니다.
+
+
+ (6) RELEASE 오퍼레이션.
+
+     이 타입의 오퍼레이션들도 단방향 투과성 배리어처럼 동작합니다.  RELEASE
+     오퍼레이션 앞의 모든 메모리 오퍼레이션들은 RELEASE 오퍼레이션 전에 완료된
+     것으로 시스템의 다른 컴포넌트들에 보여질 것이 보장됩니다.  UNLOCK 류의
+     오퍼레이션들과 smp_store_release() 오퍼레이션도 RELEASE 오퍼레이션의
+     일종입니다.
+
+     RELEASE 오퍼레이션 뒤의 메모리 오퍼레이션들은 RELEASE 오퍼레이션이
+     완료되기 전에 행해진 것처럼 보일 수 있습니다.
+
+     ACQUIRE 와 RELEASE 오퍼레이션의 사용은 일반적으로 다른 메모리 배리어의
+     필요성을 없앱니다 (하지만 "MMIO 쓰기 배리어" 서브섹션에서 설명되는 예외를
+     알아두세요).  또한, RELEASE+ACQUIRE 조합은 범용 메모리 배리어처럼 동작할
+     것을 보장하지 -않습니다-.  하지만, 어떤 변수에 대한 RELEASE 오퍼레이션을
+     앞서는 메모리 액세스들의 수행 결과는 이 RELEASE 오퍼레이션을 뒤이어 같은
+     변수에 대해 수행된 ACQUIRE 오퍼레이션을 뒤따르는 메모리 액세스에는 보여질
+     것이 보장됩니다.  다르게 말하자면, 주어진 변수의 크리티컬 섹션에서는, 해당
+     변수에 대한 앞의 크리티컬 섹션에서의 모든 액세스들이 완료되었을 것을
+     보장합니다.
+
+     즉, ACQUIRE 는 최소한의 "취득" 동작처럼, 그리고 RELEASE 는 최소한의 "공개"
+     처럼 동작한다는 의미입니다.
+
+atomic_ops.txt 에서 설명되는 어토믹 오퍼레이션들 중에는 완전히 순서잡힌 것들과
+(배리어를 사용하지 않는) 완화된 순서의 것들 외에 ACQUIRE 와 RELEASE 부류의
+것들도 존재합니다.  로드와 스토어를 모두 수행하는 조합된 어토믹 오퍼레이션에서,
+ACQUIRE 는 해당 오퍼레이션의 로드 부분에만 적용되고 RELEASE 는 해당
+오퍼레이션의 스토어 부분에만 적용됩니다.
+
+메모리 배리어들은 두 CPU 간, 또는 CPU 와 디바이스 간에 상호작용의 가능성이 있을
+때에만 필요합니다.  만약 어떤 코드에 그런 상호작용이 없을 것이 보장된다면, 해당
+코드에서는 메모리 배리어를 사용할 필요가 없습니다.
+
+
+이것들은 _최소한의_ 보장사항들임을 알아두세요.  다른 아키텍쳐에서는 더 강력한
+보장사항을 제공할 수도 있습니다만, 그런 보장사항은 아키텍쳐 종속적 코드 이외의
+부분에서는 신뢰되지 _않을_ 겁니다.
+
+
+메모리 배리어에 대해 가정해선 안될 것
+-------------------------------------
+
+리눅스 커널 메모리 배리어들이 보장하지 않는 것들이 있습니다:
+
+ (*) 메모리 배리어 앞에서 명시된 어떤 메모리 액세스도 메모리 배리어 명령의 수행
+     완료 시점까지 _완료_ 될 것이란 보장은 없습니다; 배리어가 하는 일은 CPU 의
+     액세스 큐에 특정 타입의 액세스들은 넘을 수 없는 선을 긋는 것으로 생각될 수
+     있습니다.
+
+ (*) 한 CPU 에서 메모리 배리어를 수행하는게 시스템의 다른 CPU 나 하드웨어에
+     어떤 직접적인 영향을 끼친다는 보장은 존재하지 않습니다.  배리어 수행이
+     만드는 간접적 영향은 두번째 CPU 가 첫번째 CPU 의 액세스들의 결과를
+     바라보는 순서가 됩니다만, 다음 항목을 보세요:
+
+ (*) 첫번째 CPU 가 두번째 CPU 의 메모리 액세스들의 결과를 바라볼 때, _설령_
+     두번째 CPU 가 메모리 배리어를 사용한다 해도, 첫번째 CPU _또한_ 그에 맞는
+     메모리 배리어를 사용하지 않는다면 ("SMP 배리어 짝맞추기" 서브섹션을
+     참고하세요) 그 결과가 올바른 순서로 보여진다는 보장은 없습니다.
+
+ (*) CPU 바깥의 하드웨어[*] 가 메모리 액세스들의 순서를 바꾸지 않는다는 보장은
+     존재하지 않습니다.  CPU 캐시 일관성 메커니즘은 메모리 배리어의 간접적
+     영향을 CPU 사이에 전파하긴 하지만, 순서대로 전파하지는 않을 수 있습니다.
+
+	[*] 버스 마스터링 DMA 와 일관성에 대해서는 다음을 참고하시기 바랍니다:
+
+	    Documentation/PCI/pci.txt
+	    Documentation/DMA-API-HOWTO.txt
+	    Documentation/DMA-API.txt
+
+
+데이터 의존성 배리어
+--------------------
+
+데이터 의존성 배리어의 사용에 있어 지켜야 하는 사항들은 약간 미묘하고, 데이터
+의존성 배리어가 사용되어야 하는 상황도 항상 명백하지는 않습니다.  설명을 위해
+다음의 이벤트 시퀀스를 생각해 봅시다:
+
+	CPU 1		      CPU 2
+	===============	      ===============
+	{ A == 1, B == 2, C == 3, P == &A, Q == &C }
+	B = 4;
+	<쓰기 배리어>
+	WRITE_ONCE(P, &B)
+			      Q = READ_ONCE(P);
+			      D = *Q;
+
+여기엔 분명한 데이터 의존성이 존재하므로, 이 시퀀스가 끝났을 때 Q 는 &A 또는 &B
+일 것이고, 따라서:
+
+	(Q == &A) 는 (D == 1) 를,
+	(Q == &B) 는 (D == 4) 를 의미합니다.
+
+하지만!  CPU 2 는 B 의 업데이트를 인식하기 전에 P 의 업데이트를 인식할 수 있고,
+따라서 다음의 결과가 가능합니다:
+
+	(Q == &B) and (D == 2) ????
+
+이런 결과는 일관성이나 인과 관계 유지가 실패한 것처럼 보일 수도 있겠지만,
+그렇지 않습니다, 그리고 이 현상은 (DEC Alpha 와 같은) 여러 CPU 에서 실제로
+발견될 수 있습니다.
+
+이 문제 상황을 제대로 해결하기 위해, 데이터 의존성 배리어나 그보다 강화된
+무언가가 주소를 읽어올 때와 데이터를 읽어올 때 사이에 추가되어야만 합니다:
+
+	CPU 1		      CPU 2
+	===============	      ===============
+	{ A == 1, B == 2, C == 3, P == &A, Q == &C }
+	B = 4;
+	<쓰기 배리어>
+	WRITE_ONCE(P, &B);
+			      Q = READ_ONCE(P);
+			      <데이터 의존성 배리어>
+			      D = *Q;
+
+이 변경은 앞의 처음 두가지 결과 중 하나만이 발생할 수 있고, 세번째의 결과는
+발생할 수 없도록 합니다.
+
+데이터 의존성 배리어는 의존적 쓰기에 대해서도 순서를 잡아줍니다:
+
+	CPU 1		      CPU 2
+	===============	      ===============
+	{ A == 1, B == 2, C = 3, P == &A, Q == &C }
+	B = 4;
+	<쓰기 배리어>
+	WRITE_ONCE(P, &B);
+			      Q = READ_ONCE(P);
+			      <데이터 의존성 배리어>
+			      *Q = 5;
+
+이 데이터 의존성 배리어는 Q 로의 읽기가 *Q 로의 스토어와 순서를 맞추게
+해줍니다.  이는 다음과 같은 결과를 막습니다:
+
+	(Q == &B) && (B == 4)
+
+이런 패턴은 드물게 사용되어야 함을 알아 두시기 바랍니다.  무엇보다도, 의존성
+순서 규칙의 의도는 쓰기 작업을 -예방- 해서 그로 인해 발생하는 비싼 캐시 미스도
+없애려는 것입니다.  이 패턴은 드물게 발생하는 에러 조건 같은것들을 기록하는데
+사용될 수 있고, 이렇게 배리어를 사용해 순서를 지키게 함으로써 그런 기록이
+사라지는 것을 막습니다.
+
+
+[!] 상당히 비직관적인 이 상황은 분리된 캐시를 가진 기계, 예를 들어 한 캐시
+뱅크가 짝수번 캐시 라인을 처리하고 다른 뱅크는 홀수번 캐시 라인을 처리하는 기계
+등에서 가장 잘 발생합니다.  포인터 P 는 홀수 번호의 캐시 라인에 있고, 변수 B 는
+짝수 번호 캐시 라인에 있다고 생각해 봅시다.  그런 상태에서 읽기 작업을 하는 CPU
+의 짝수번 뱅크는 할 일이 쌓여 매우 바쁘지만 홀수번 뱅크는 할 일이 없어 아무
+일도 하지 않고  있었다면, 포인터 P 는 새 값 (&B) 을, 그리고 변수 B 는 옛날 값
+(2) 을 가지고 있는 상태가 보여질 수도 있습니다.
+
+
+데이터 의존성 배리어는 매우 중요한데, 예를 들어 RCU 시스템에서 그렇습니다.
+include/linux/rcupdate.h 의 rcu_assign_pointer() 와 rcu_dereference() 를
+참고하세요.  여기서 데이터 의존성 배리어는 RCU 로 관리되는 포인터의 타겟을 현재
+타겟에서 수정된 새로운 타겟으로 바꾸는 작업에서 새로 수정된 타겟이 초기화가
+완료되지 않은 채로 보여지는 일이 일어나지 않게 해줍니다.
+
+더 많은 예를 위해선 "캐시 일관성" 서브섹션을 참고하세요.
+
+
+컨트롤 의존성
+-------------
+
+로드-로드 컨트롤 의존성은 데이터 의존성 배리어만으로는 정확히 동작할 수가
+없어서 읽기 메모리 배리어를 필요로 합니다.  아래의 코드를 봅시다:
+
+	q = READ_ONCE(a);
+	if (q) {
+		<데이터 의존성 배리어>  /* BUG: No data dependency!!! */
+		p = READ_ONCE(b);
+	}
+
+이 코드는 원하는 대로의 효과를 내지 못할 수 있는데, 이 코드에는 데이터 의존성이
+아니라 컨트롤 의존성이 존재하기 때문으로, 이런 상황에서 CPU 는 실행 속도를 더
+빠르게 하기 위해 분기 조건의 결과를 예측하고 코드를 재배치 할 수 있어서 다른
+CPU 는 b 로부터의 로드 오퍼레이션이 a 로부터의 로드 오퍼레이션보다 먼저 발생한
+걸로 인식할 수 있습니다.  여기에 정말로 필요했던 건 다음과 같습니다:
+
+	q = READ_ONCE(a);
+	if (q) {
+		<읽기 배리어>
+		p = READ_ONCE(b);
+	}
+
+하지만, 스토어 오퍼레이션은 예측적으로 수행되지 않습니다.  즉, 다음 예에서와
+같이 로드-스토어 컨트롤 의존성이 존재하는 경우에는 순서가 -지켜진다-는
+의미입니다.
+
+	q = READ_ONCE(a);
+	if (q) {
+		WRITE_ONCE(b, p);
+	}
+
+컨트롤 의존성은 보통 다른 타입의 배리어들과 짝을 맞춰 사용됩니다.  그렇다곤
+하나, READ_ONCE() 는 반드시 사용해야 함을 부디 명심하세요!  READ_ONCE() 가
+없다면, 컴파일러가 'a' 로부터의 로드를 'a' 로부터의 또다른 로드와, 'b' 로의
+스토어를 'b' 로의 또다른 스토어와 조합해 버려 매우 비직관적인 결과를 초래할 수
+있습니다.
+
+이걸로 끝이 아닌게, 컴파일러가 변수 'a' 의 값이 항상 0이 아니라고 증명할 수
+있다면, 앞의 예에서 "if" 문을 없애서 다음과 같이 최적화 할 수도 있습니다:
+
+	q = a;
+	b = p;  /* BUG: Compiler and CPU can both reorder!!! */
+
+그러니 READ_ONCE() 를 반드시 사용하세요.
+
+다음과 같이 "if" 문의 양갈래 브랜치에 모두 존재하는 동일한 스토어에 대해 순서를
+강제하고 싶은 경우가 있을 수 있습니다:
+
+	q = READ_ONCE(a);
+	if (q) {
+		barrier();
+		WRITE_ONCE(b, p);
+		do_something();
+	} else {
+		barrier();
+		WRITE_ONCE(b, p);
+		do_something_else();
+	}
+
+안타깝게도, 현재의 컴파일러들은 높은 최적화 레벨에서는 이걸 다음과 같이
+바꿔버립니다:
+
+	q = READ_ONCE(a);
+	barrier();
+	WRITE_ONCE(b, p);  /* BUG: No ordering vs. load from a!!! */
+	if (q) {
+		/* WRITE_ONCE(b, p); -- moved up, BUG!!! */
+		do_something();
+	} else {
+		/* WRITE_ONCE(b, p); -- moved up, BUG!!! */
+		do_something_else();
+	}
+
+이제 'a' 에서의 로드와 'b' 로의 스토어 사이에는 조건적 관계가 없기 때문에 CPU
+는 이들의 순서를 바꿀 수 있게 됩니다: 이런 경우에 조건적 관계는 반드시
+필요한데, 모든 컴파일러 최적화가 이루어지고 난 후의 어셈블리 코드에서도
+마찬가지입니다.  따라서, 이 예에서 순서를 지키기 위해서는 smp_store_release()
+와 같은 명시적 메모리 배리어가 필요합니다:
+
+	q = READ_ONCE(a);
+	if (q) {
+		smp_store_release(&b, p);
+		do_something();
+	} else {
+		smp_store_release(&b, p);
+		do_something_else();
+	}
+
+반면에 명시적 메모리 배리어가 없다면, 이런 경우의 순서는 스토어 오퍼레이션들이
+서로 다를 때에만 보장되는데, 예를 들면 다음과 같은 경우입니다:
+
+	q = READ_ONCE(a);
+	if (q) {
+		WRITE_ONCE(b, p);
+		do_something();
+	} else {
+		WRITE_ONCE(b, r);
+		do_something_else();
+	}
+
+처음의 READ_ONCE() 는 컴파일러가 'a' 의 값을 증명해내는 것을 막기 위해 여전히
+필요합니다.
+
+또한, 로컬 변수 'q' 를 가지고 하는 일에 대해 주의해야 하는데, 그러지 않으면
+컴파일러는 그 값을 추측하고 또다시 필요한 조건관계를 없애버릴 수 있습니다.
+예를 들면:
+
+	q = READ_ONCE(a);
+	if (q % MAX) {
+		WRITE_ONCE(b, p);
+		do_something();
+	} else {
+		WRITE_ONCE(b, r);
+		do_something_else();
+	}
+
+만약 MAX 가 1 로 정의된 상수라면, 컴파일러는 (q % MAX) 는 0이란 것을 알아채고,
+위의 코드를 아래와 같이 바꿔버릴 수 있습니다:
+
+	q = READ_ONCE(a);
+	WRITE_ONCE(b, p);
+	do_something_else();
+
+이렇게 되면, CPU 는 변수 'a' 로부터의 로드와 변수 'b' 로의 스토어 사이의 순서를
+지켜줄 필요가 없어집니다.  barrier() 를 추가해 해결해 보고 싶겠지만, 그건
+도움이 안됩니다.  조건 관계는 사라졌고, barrier() 는 이를 되돌리지 못합니다.
+따라서, 이 순서를 지켜야 한다면, MAX 가 1 보다 크다는 것을, 다음과 같은 방법을
+사용해 분명히 해야 합니다:
+
+	q = READ_ONCE(a);
+	BUILD_BUG_ON(MAX <= 1); /* Order load from a with store to b. */
+	if (q % MAX) {
+		WRITE_ONCE(b, p);
+		do_something();
+	} else {
+		WRITE_ONCE(b, r);
+		do_something_else();
+	}
+
+'b' 로의 스토어들은 여전히 서로 다름을 알아두세요.  만약 그것들이 동일하면,
+앞에서 이야기했듯, 컴파일러가 그 스토어 오퍼레이션들을 'if' 문 바깥으로
+끄집어낼 수 있습니다.
+
+또한 이진 조건문 평가에 너무 의존하지 않도록 조심해야 합니다.  다음의 예를
+봅시다:
+
+	q = READ_ONCE(a);
+	if (q || 1 > 0)
+		WRITE_ONCE(b, 1);
+
+첫번째 조건만으로는 브랜치 조건 전체를 거짓으로 만들 수 없고 두번째 조건은 항상
+참이기 때문에, 컴파일러는 이 예를 다음과 같이 바꿔서 컨트롤 의존성을 없애버릴
+수 있습니다:
+
+	q = READ_ONCE(a);
+	WRITE_ONCE(b, 1);
+
+이 예는 컴파일러가 코드를 추측으로 수정할 수 없도록 분명히 해야 한다는 점을
+강조합니다.  조금 더 일반적으로 말해서, READ_ONCE() 는 컴파일러에게 주어진 로드
+오퍼레이션을 위한 코드를 정말로 만들도록 하지만, 컴파일러가 그렇게 만들어진
+코드의 수행 결과를 사용하도록 강제하지는 않습니다.
+
+또한, 컨트롤 의존성은 if 문의 then 절과 else 절에 대해서만 적용됩니다.  상세히
+말해서, 컨트롤 의존성은 if 문을 뒤따르는 코드에는 적용되지 않습니다:
+
+	q = READ_ONCE(a);
+	if (q) {
+		WRITE_ONCE(b, p);
+	} else {
+		WRITE_ONCE(b, r);
+	}
+	WRITE_ONCE(c, 1);  /* BUG: No ordering against the read from "a". */
+
+컴파일러는 volatile 타입에 대한 액세스를 재배치 할 수 없고 이 조건 하의 "b"
+로의 쓰기를 재배치 할 수 없기 때문에 여기에 순서 규칙이 존재한다고 주장하고
+싶을 겁니다.  불행히도 이 경우에, 컴파일러는 다음의 가상의 pseudo-assembly 언어
+코드처럼 "b" 로의 두개의 쓰기 오퍼레이션을 conditional-move 인스트럭션으로
+번역할 수 있습니다:
+
+	ld r1,a
+	ld r2,p
+	ld r3,r
+	cmp r1,$0
+	cmov,ne r4,r2
+	cmov,eq r4,r3
+	st r4,b
+	st $1,c
+
+완화된 순서 규칙의 CPU 는 "a" 로부터의 로드와 "c" 로의 스토어 사이에 어떤
+종류의 의존성도 갖지 않을 겁니다.  이 컨트롤 의존성은 두개의 cmov 인스트럭션과
+거기에 의존하는 스토어 에게만 적용될 겁니다.  짧게 말하자면, 컨트롤 의존성은
+주어진 if 문의 then 절과 else 절에게만 (그리고 이 두 절 내에서 호출되는
+함수들에게까지) 적용되지, 이 if 문을 뒤따르는 코드에는 적용되지 않습니다.
+
+마지막으로, 컨트롤 의존성은 이행성 (transitivity) 을 제공하지 -않습니다-.  이건
+x 와 y 가 둘 다 0 이라는 초기값을 가졌다는 가정 하의 두개의 예제로
+보이겠습니다:
+
+	CPU 0                     CPU 1
+	=======================   =======================
+	r1 = READ_ONCE(x);        r2 = READ_ONCE(y);
+	if (r1 > 0)               if (r2 > 0)
+	  WRITE_ONCE(y, 1);         WRITE_ONCE(x, 1);
+
+	assert(!(r1 == 1 && r2 == 1));
+
+이 두 CPU 예제에서 assert() 의 조건은 항상 참일 것입니다.  그리고, 만약 컨트롤
+의존성이 이행성을 (실제로는 그러지 않지만) 보장한다면, 다음의 CPU 가 추가되어도
+아래의 assert() 조건은 참이 될것입니다:
+
+	CPU 2
+	=====================
+	WRITE_ONCE(x, 2);
+
+	assert(!(r1 == 2 && r2 == 1 && x == 2)); /* FAILS!!! */
+
+하지만 컨트롤 의존성은 이행성을 제공하지 -않기- 때문에, 세개의 CPU 예제가 실행
+완료된 후에 위의 assert() 의 조건은 거짓으로 평가될 수 있습니다.  세개의 CPU
+예제가 순서를 지키길 원한다면, CPU 0 와 CPU 1 코드의 로드와 스토어 사이, "if"
+문 바로 다음에 smp_mb()를 넣어야 합니다.  더 나아가서, 최초의 두 CPU 예제는
+매우 위험하므로 사용되지 않아야 합니다.
+
+이 두개의 예제는 다음 논문:
+http://www.cl.cam.ac.uk/users/pes20/ppc-supplemental/test6.pdf 와
+이 사이트: https://www.cl.cam.ac.uk/~pes20/ppcmem/index.html 에 나온 LB 와 WWC
+리트머스 테스트입니다.
+
+요약하자면:
+
+  (*) 컨트롤 의존성은 앞의 로드들을 뒤의 스토어들에 대해 순서를 맞춰줍니다.
+      하지만, 그 외의 어떤 순서도 보장하지 -않습니다-: 앞의 로드와 뒤의 로드들
+      사이에도, 앞의 스토어와 뒤의 스토어들 사이에도요.  이런 다른 형태의
+      순서가 필요하다면 smp_rmb() 나 smp_wmb()를, 또는, 앞의 스토어들과 뒤의
+      로드들 사이의 순서를 위해서는 smp_mb() 를 사용하세요.
+
+  (*) "if" 문의 양갈래 브랜치가 같은 변수에의 동일한 스토어로 시작한다면, 그
+      스토어들은 각 스토어 앞에 smp_mb() 를 넣거나 smp_store_release() 를
+      사용해서 스토어를 하는 식으로 순서를 맞춰줘야 합니다.  이 문제를 해결하기
+      위해 "if" 문의 양갈래 브랜치의 시작 지점에 barrier() 를 넣는 것만으로는
+      충분한 해결이 되지 않는데, 이는 앞의 예에서 본것과 같이, 컴파일러의
+      최적화는 barrier() 가 의미하는 바를 지키면서도 컨트롤 의존성을 손상시킬
+      수 있기 때문이라는 점을 부디 알아두시기 바랍니다.
+
+  (*) 컨트롤 의존성은 앞의 로드와 뒤의 스토어 사이에 최소 하나의, 실행
+      시점에서의 조건관계를 필요로 하며, 이 조건관계는 앞의 로드와 관계되어야
+      합니다.  만약 컴파일러가 조건 관계를 최적화로 없앨수 있다면, 순서도
+      최적화로 없애버렸을 겁니다.  READ_ONCE() 와 WRITE_ONCE() 의 주의 깊은
+      사용은 주어진 조건 관계를 유지하는데 도움이 될 수 있습니다.
+
+  (*) 컨트롤 의존성을 위해선 컴파일러가 조건관계를 없애버리는 것을 막아야
+      합니다.  주의 깊은 READ_ONCE() 나 atomic{,64}_read() 의 사용이 컨트롤
+      의존성이 사라지지 않게 하는데 도움을 줄 수 있습니다.  더 많은 정보를
+      위해선 "컴파일러 배리어" 섹션을 참고하시기 바랍니다.
+
+  (*) 컨트롤 의존성은 컨트롤 의존성을 갖는 if 문의 then 절과 else 절과 이 두 절
+      내에서 호출되는 함수들에만 적용됩니다.  컨트롤 의존성은 컨트롤 의존성을
+      갖는 if 문을 뒤따르는 코드에는 적용되지 -않습니다-.
+
+  (*) 컨트롤 의존성은 보통 다른 타입의 배리어들과 짝을 맞춰 사용됩니다.
+
+  (*) 컨트롤 의존성은 이행성을 제공하지 -않습니다-.  이행성이 필요하다면,
+      smp_mb() 를 사용하세요.
+
+
+SMP 배리어 짝맞추기
+--------------------
+
+CPU 간 상호작용을 다룰 때에 일부 타입의 메모리 배리어는 항상 짝을 맞춰
+사용되어야 합니다.  적절하게 짝을 맞추지 않은 코드는 사실상 에러에 가깝습니다.
+
+범용 배리어들은 범용 배리어끼리도 짝을 맞추지만 이행성이 없는 대부분의 다른
+타입의 배리어들과도 짝을 맞춥니다.  ACQUIRE 배리어는 RELEASE 배리어와 짝을
+맞춥니다만, 둘 다 범용 배리어를 포함해 다른 배리어들과도 짝을 맞출 수 있습니다.
+쓰기 배리어는 데이터 의존성 배리어나 컨트롤 의존성, ACQUIRE 배리어, RELEASE
+배리어, 읽기 배리어, 또는 범용 배리어와 짝을 맞춥니다.  비슷하게 읽기 배리어나
+컨트롤 의존성, 또는 데이터 의존성 배리어는 쓰기 배리어나 ACQUIRE 배리어,
+RELEASE 배리어, 또는 범용 배리어와 짝을 맞추는데, 다음과 같습니다:
+
+	CPU 1		      CPU 2
+	===============	      ===============
+	WRITE_ONCE(a, 1);
+	<쓰기 배리어>
+	WRITE_ONCE(b, 2);     x = READ_ONCE(b);
+			      <읽기 배리어>
+			      y = READ_ONCE(a);
+
+또는:
+
+	CPU 1		      CPU 2
+	===============	      ===============================
+	a = 1;
+	<쓰기 배리어>
+	WRITE_ONCE(b, &a);    x = READ_ONCE(b);
+			      <데이터 의존성 배리어>
+			      y = *x;
+
+또는:
+
+	CPU 1		      CPU 2
+	===============	      ===============================
+	r1 = READ_ONCE(y);
+	<범용 배리어>
+	WRITE_ONCE(y, 1);     if (r2 = READ_ONCE(x)) {
+			         <묵시적 컨트롤 의존성>
+			         WRITE_ONCE(y, 1);
+			      }
+
+	assert(r1 == 0 || r2 == 0);
+
+기본적으로, 여기서의 읽기 배리어는 "더 완화된" 타입일 순 있어도 항상 존재해야
+합니다.
+
+[!] 쓰기 배리어 앞의 스토어 오퍼레이션은 일반적으로 읽기 배리어나 데이터
+의존성 배리어 뒤의 로드 오퍼레이션과 매치될 것이고, 반대도 마찬가지입니다:
+
+	CPU 1                               CPU 2
+	===================                 ===================
+	WRITE_ONCE(a, 1);    }----   --->{  v = READ_ONCE(c);
+	WRITE_ONCE(b, 2);    }    \ /    {  w = READ_ONCE(d);
+	<쓰기 배리어>              \        <읽기 배리어>
+	WRITE_ONCE(c, 3);    }    / \    {  x = READ_ONCE(a);
+	WRITE_ONCE(d, 4);    }----   --->{  y = READ_ONCE(b);
+
+
+메모리 배리어 시퀀스의 예
+-------------------------
+
+첫째, 쓰기 배리어는 스토어 오퍼레이션들의 부분적 순서 세우기로 동작합니다.
+아래의 이벤트 시퀀스를 보세요:
+
+	CPU 1
+	=======================
+	STORE A = 1
+	STORE B = 2
+	STORE C = 3
+	<쓰기 배리어>
+	STORE D = 4
+	STORE E = 5
+
+이 이벤트 시퀀스는 메모리 일관성 시스템에 원소끼리의 순서가 존재하지 않는 집합
+{ STORE A, STORE B, STORE C } 가 역시 원소끼리의 순서가 존재하지 않는 집합
+{ STORE D, STORE E } 보다 먼저 일어난 것으로 시스템의 나머지 요소들에 보이도록
+전달됩니다:
+
+	+-------+       :      :
+	|       |       +------+
+	|       |------>| C=3  |     }     /\
+	|       |  :    +------+     }-----  \  -----> 시스템의 나머지 요소에
+	|       |  :    | A=1  |     }        \/       보여질 수 있는 이벤트들
+	|       |  :    +------+     }
+	| CPU 1 |  :    | B=2  |     }
+	|       |       +------+     }
+	|       |   wwwwwwwwwwwwwwww }   <--- 여기서 쓰기 배리어는 배리어 앞의
+	|       |       +------+     }        모든 스토어가 배리어 뒤의 스토어
+	|       |  :    | E=5  |     }        전에 메모리 시스템에 전달되도록
+	|       |  :    +------+     }        합니다
+	|       |------>| D=4  |     }
+	|       |       +------+
+	+-------+       :      :
+	                   |
+	                   | CPU 1 에 의해 메모리 시스템에 전달되는
+	                   | 일련의 스토어 오퍼레이션들
+	                   V
+
+
+둘째, 데이터 의존성 배리어는 데이터 의존적 로드 오퍼레이션들의 부분적 순서
+세우기로 동작합니다.  다음 일련의 이벤트들을 보세요:
+
+	CPU 1			CPU 2
+	=======================	=======================
+		{ B = 7; X = 9; Y = 8; C = &Y }
+	STORE A = 1
+	STORE B = 2
+	<쓰기 배리어>
+	STORE C = &B		LOAD X
+	STORE D = 4		LOAD C (gets &B)
+				LOAD *C (reads B)
+
+여기에 별다른 개입이 없다면, CPU 1 의 쓰기 배리어에도 불구하고 CPU 2 는 CPU 1
+의 이벤트들을 완전히 무작위적 순서로 인지하게 됩니다:
+
+	+-------+       :      :                :       :
+	|       |       +------+                +-------+  | CPU 2 에 인지되는
+	|       |------>| B=2  |-----       --->| Y->8  |  | 업데이트 이벤트
+	|       |  :    +------+     \          +-------+  | 시퀀스
+	| CPU 1 |  :    | A=1  |      \     --->| C->&Y |  V
+	|       |       +------+       |        +-------+
+	|       |   wwwwwwwwwwwwwwww   |        :       :
+	|       |       +------+       |        :       :
+	|       |  :    | C=&B |---    |        :       :       +-------+
+	|       |  :    +------+   \   |        +-------+       |       |
+	|       |------>| D=4  |    ----------->| C->&B |------>|       |
+	|       |       +------+       |        +-------+       |       |
+	+-------+       :      :       |        :       :       |       |
+	                               |        :       :       |       |
+	                               |        :       :       | CPU 2 |
+	                               |        +-------+       |       |
+	    분명히 잘못된        --->  |        | B->7  |------>|       |
+	    B 의 값 인지 (!)           |        +-------+       |       |
+	                               |        :       :       |       |
+	                               |        +-------+       |       |
+	    X 의 로드가 B 의    --->    \       | X->9  |------>|       |
+	    일관성 유지를                \      +-------+       |       |
+	    지연시킴                      ----->| B->2  |       +-------+
+	                                        +-------+
+	                                        :       :
+
+
+앞의 예에서, CPU 2 는 (B 의 값이 될) *C 의 값 읽기가 C 의 LOAD 뒤에 이어짐에도
+B 가 7 이라는 결과를 얻습니다.
+
+하지만, 만약 데이터 의존성 배리어가 C 의 로드와 *C (즉, B) 의 로드 사이에
+있었다면:
+
+	CPU 1			CPU 2
+	=======================	=======================
+		{ B = 7; X = 9; Y = 8; C = &Y }
+	STORE A = 1
+	STORE B = 2
+	<쓰기 배리어>
+	STORE C = &B		LOAD X
+	STORE D = 4		LOAD C (gets &B)
+				<데이터 의존성 배리어>
+				LOAD *C (reads B)
+
+다음과 같이 됩니다:
+
+	+-------+       :      :                :       :
+	|       |       +------+                +-------+
+	|       |------>| B=2  |-----       --->| Y->8  |
+	|       |  :    +------+     \          +-------+
+	| CPU 1 |  :    | A=1  |      \     --->| C->&Y |
+	|       |       +------+       |        +-------+
+	|       |   wwwwwwwwwwwwwwww   |        :       :
+	|       |       +------+       |        :       :
+	|       |  :    | C=&B |---    |        :       :       +-------+
+	|       |  :    +------+   \   |        +-------+       |       |
+	|       |------>| D=4  |    ----------->| C->&B |------>|       |
+	|       |       +------+       |        +-------+       |       |
+	+-------+       :      :       |        :       :       |       |
+	                               |        :       :       |       |
+	                               |        :       :       | CPU 2 |
+	                               |        +-------+       |       |
+	                               |        | X->9  |------>|       |
+	                               |        +-------+       |       |
+	  C 로의 스토어 앞의     --->   \   ddddddddddddddddd   |       |
+	  모든 이벤트 결과가             \      +-------+       |       |
+	  뒤의 로드에게                   ----->| B->2  |------>|       |
+	  보이게 강제한다                       +-------+       |       |
+	                                        :       :       +-------+
+
+
+셋째, 읽기 배리어는 로드 오퍼레이션들에의 부분적 순서 세우기로 동작합니다.
+아래의 일련의 이벤트를 봅시다:
+
+	CPU 1			CPU 2
+	=======================	=======================
+		{ A = 0, B = 9 }
+	STORE A=1
+	<쓰기 배리어>
+	STORE B=2
+				LOAD B
+				LOAD A
+
+CPU 1 은 쓰기 배리어를 쳤지만, 별다른 개입이 없다면 CPU 2 는 CPU 1 에서 행해진
+이벤트의 결과를 무작위적 순서로 인지하게 됩니다.
+
+	+-------+       :      :                :       :
+	|       |       +------+                +-------+
+	|       |------>| A=1  |------      --->| A->0  |
+	|       |       +------+      \         +-------+
+	| CPU 1 |   wwwwwwwwwwwwwwww   \    --->| B->9  |
+	|       |       +------+        |       +-------+
+	|       |------>| B=2  |---     |       :       :
+	|       |       +------+   \    |       :       :       +-------+
+	+-------+       :      :    \   |       +-------+       |       |
+	                             ---------->| B->2  |------>|       |
+	                                |       +-------+       | CPU 2 |
+	                                |       | A->0  |------>|       |
+	                                |       +-------+       |       |
+	                                |       :       :       +-------+
+	                                 \      :       :
+	                                  \     +-------+
+	                                   ---->| A->1  |
+	                                        +-------+
+	                                        :       :
+
+
+하지만, 만약 읽기 배리어가 B 의 로드와 A 의 로드 사이에 존재한다면:
+
+	CPU 1			CPU 2
+	=======================	=======================
+		{ A = 0, B = 9 }
+	STORE A=1
+	<쓰기 배리어>
+	STORE B=2
+				LOAD B
+				<읽기 배리어>
+				LOAD A
+
+CPU 1 에 의해 만들어진 부분적 순서가 CPU 2 에도 그대로 인지됩니다:
+
+	+-------+       :      :                :       :
+	|       |       +------+                +-------+
+	|       |------>| A=1  |------      --->| A->0  |
+	|       |       +------+      \         +-------+
+	| CPU 1 |   wwwwwwwwwwwwwwww   \    --->| B->9  |
+	|       |       +------+        |       +-------+
+	|       |------>| B=2  |---     |       :       :
+	|       |       +------+   \    |       :       :       +-------+
+	+-------+       :      :    \   |       +-------+       |       |
+	                             ---------->| B->2  |------>|       |
+	                                |       +-------+       | CPU 2 |
+	                                |       :       :       |       |
+	                                |       :       :       |       |
+	  여기서 읽기 배리어는   ---->   \  rrrrrrrrrrrrrrrrr   |       |
+	  B 로의 스토어 전의              \     +-------+       |       |
+	  모든 결과를 CPU 2 에             ---->| A->1  |------>|       |
+	  보이도록 한다                         +-------+       |       |
+	                                        :       :       +-------+
+
+
+더 완벽한 설명을 위해, A 의 로드가 읽기 배리어 앞과 뒤에 있으면 어떻게 될지
+생각해 봅시다:
+
+	CPU 1			CPU 2
+	=======================	=======================
+		{ A = 0, B = 9 }
+	STORE A=1
+	<쓰기 배리어>
+	STORE B=2
+				LOAD B
+				LOAD A [first load of A]
+				<읽기 배리어>
+				LOAD A [second load of A]
+
+A 의 로드 두개가 모두 B 의 로드 뒤에 있지만, 서로 다른 값을 얻어올 수
+있습니다:
+
+	+-------+       :      :                :       :
+	|       |       +------+                +-------+
+	|       |------>| A=1  |------      --->| A->0  |
+	|       |       +------+      \         +-------+
+	| CPU 1 |   wwwwwwwwwwwwwwww   \    --->| B->9  |
+	|       |       +------+        |       +-------+
+	|       |------>| B=2  |---     |       :       :
+	|       |       +------+   \    |       :       :       +-------+
+	+-------+       :      :    \   |       +-------+       |       |
+	                             ---------->| B->2  |------>|       |
+	                                |       +-------+       | CPU 2 |
+	                                |       :       :       |       |
+	                                |       :       :       |       |
+	                                |       +-------+       |       |
+	                                |       | A->0  |------>| 1st   |
+	                                |       +-------+       |       |
+	  여기서 읽기 배리어는   ---->   \  rrrrrrrrrrrrrrrrr   |       |
+	  B 로의 스토어 전의              \     +-------+       |       |
+	  모든 결과를 CPU 2 에             ---->| A->1  |------>| 2nd   |
+	  보이도록 한다                         +-------+       |       |
+	                                        :       :       +-------+
+
+
+하지만 CPU 1 에서의 A 업데이트는 읽기 배리어가 완료되기 전에도 보일 수도
+있긴 합니다:
+
+	+-------+       :      :                :       :
+	|       |       +------+                +-------+
+	|       |------>| A=1  |------      --->| A->0  |
+	|       |       +------+      \         +-------+
+	| CPU 1 |   wwwwwwwwwwwwwwww   \    --->| B->9  |
+	|       |       +------+        |       +-------+
+	|       |------>| B=2  |---     |       :       :
+	|       |       +------+   \    |       :       :       +-------+
+	+-------+       :      :    \   |       +-------+       |       |
+	                             ---------->| B->2  |------>|       |
+	                                |       +-------+       | CPU 2 |
+	                                |       :       :       |       |
+	                                 \      :       :       |       |
+	                                  \     +-------+       |       |
+	                                   ---->| A->1  |------>| 1st   |
+	                                        +-------+       |       |
+	                                    rrrrrrrrrrrrrrrrr   |       |
+	                                        +-------+       |       |
+	                                        | A->1  |------>| 2nd   |
+	                                        +-------+       |       |
+	                                        :       :       +-------+
+
+
+여기서 보장되는 건, 만약 B 의 로드가 B == 2 라는 결과를 봤다면, A 에의 두번째
+로드는 항상 A == 1 을 보게 될 것이라는 겁니다.  A 에의 첫번째 로드에는 그런
+보장이 없습니다; A == 0 이거나 A == 1 이거나 둘 중 하나의 결과를 보게 될겁니다.
+
+
+읽기 메모리 배리어 VS 로드 예측
+-------------------------------
+
+많은 CPU들이 로드를 예측적으로 (speculatively) 합니다: 어떤 데이터를 메모리에서
+로드해야 하게 될지 예측을 했다면, 해당 데이터를 로드하는 인스트럭션을 실제로는
+아직 만나지 않았더라도 다른 로드 작업이 없어 버스 (bus) 가 아무 일도 하고 있지
+않다면, 그 데이터를 로드합니다.  이후에 실제 로드 인스트럭션이 실행되면 CPU 가
+이미 그 값을 가지고 있기 때문에 그 로드 인스트럭션은 즉시 완료됩니다.
+
+해당 CPU 는 실제로는 그 값이 필요치 않았다는 사실이 나중에 드러날 수도 있는데 -
+해당 로드 인스트럭션이 브랜치로 우회되거나 했을 수 있겠죠 - , 그렇게 되면 앞서
+읽어둔 값을 버리거나 나중의 사용을 위해 캐시에 넣어둘 수 있습니다.
+
+다음을 생각해 봅시다:
+
+	CPU 1			CPU 2
+	=======================	=======================
+				LOAD B
+				DIVIDE		} 나누기 명령은 일반적으로
+				DIVIDE		} 긴 시간을 필요로 합니다
+				LOAD A
+
+는 이렇게 될 수 있습니다:
+
+	                                        :       :       +-------+
+	                                        +-------+       |       |
+	                                    --->| B->2  |------>|       |
+	                                        +-------+       | CPU 2 |
+	                                        :       :DIVIDE |       |
+	                                        +-------+       |       |
+	나누기 하느라 바쁜       --->       --->| A->0  |~~~~   |       |
+	CPU 는 A 의 LOAD 를                     +-------+   ~   |       |
+	예측해서 수행한다                       :       :   ~   |       |
+	                                        :       :DIVIDE |       |
+	                                        :       :   ~   |       |
+	나누기가 끝나면       --->     --->     :       :   ~-->|       |
+	CPU 는 해당 LOAD 를                     :       :       |       |
+	즉각 완료한다                           :       :       +-------+
+
+
+읽기 배리어나 데이터 의존성 배리어를 두번째 로드 직전에 놓는다면:
+
+	CPU 1			CPU 2
+	=======================	=======================
+				LOAD B
+				DIVIDE
+				DIVIDE
+				<읽기 배리어>
+				LOAD A
+
+예측으로 얻어진 값은 사용된 배리어의 타입에 따라서 해당 값이 옳은지 검토되게
+됩니다.  만약 해당 메모리 영역에 변화가 없었다면, 예측으로 얻어두었던 값이
+사용됩니다:
+
+	                                        :       :       +-------+
+	                                        +-------+       |       |
+	                                    --->| B->2  |------>|       |
+	                                        +-------+       | CPU 2 |
+	                                        :       :DIVIDE |       |
+	                                        +-------+       |       |
+	나누기 하느라 바쁜       --->       --->| A->0  |~~~~   |       |
+	CPU 는 A 의 LOAD 를                     +-------+   ~   |       |
+	예측한다                                :       :   ~   |       |
+	                                        :       :DIVIDE |       |
+	                                        :       :   ~   |       |
+	                                        :       :   ~   |       |
+	                                    rrrrrrrrrrrrrrrr~   |       |
+	                                        :       :   ~   |       |
+	                                        :       :   ~-->|       |
+	                                        :       :       |       |
+	                                        :       :       +-------+
+
+
+하지만 다른 CPU 에서 업데이트나 무효화가 있었다면, 그 예측은 무효화되고 그 값은
+다시 읽혀집니다:
+
+	                                        :       :       +-------+
+	                                        +-------+       |       |
+	                                    --->| B->2  |------>|       |
+	                                        +-------+       | CPU 2 |
+	                                        :       :DIVIDE |       |
+	                                        +-------+       |       |
+	나누기 하느라 바쁜       --->       --->| A->0  |~~~~   |       |
+	CPU 는 A 의 LOAD 를                     +-------+   ~   |       |
+	예측한다                                :       :   ~   |       |
+	                                        :       :DIVIDE |       |
+	                                        :       :   ~   |       |
+	                                        :       :   ~   |       |
+	                                    rrrrrrrrrrrrrrrrr   |       |
+	                                        +-------+       |       |
+	예측성 동작은 무효화 되고    --->   --->| A->1  |------>|       |
+	업데이트된 값이 다시 읽혀진다           +-------+       |       |
+	                                        :       :       +-------+
+
+
+이행성
+------
+
+이행성(transitivity)은 실제의 컴퓨터 시스템에서 항상 제공되지는 않는, 순서
+맞추기에 대한 상당히 직관적인 개념입니다.  다음의 예가 이행성을 보여줍니다:
+
+	CPU 1			CPU 2			CPU 3
+	=======================	=======================	=======================
+		{ X = 0, Y = 0 }
+	STORE X=1		LOAD X			STORE Y=1
+				<범용 배리어>		<범용 배리어>
+				LOAD Y			LOAD X
+
+CPU 2 의 X 로드가 1을 리턴했고 Y 로드가 0을 리턴했다고 해봅시다.  이는 CPU 2 의
+X 로드가 CPU 1 의 X 스토어 뒤에 이루어졌고 CPU 2 의 Y 로드는 CPU 3 의 Y 스토어
+전에 이루어졌음을 의미합니다.  그럼 "CPU 3 의 X 로드는 0을 리턴할 수 있나요?"
+
+CPU 2 의 X 로드는 CPU 1 의 스토어 후에 이루어졌으니, CPU 3 의 X 로드는 1을
+리턴하는게 자연스럽습니다.  이런 생각이 이행성의 한 예입니다: CPU A 에서 실행된
+로드가 CPU B 에서의 같은 변수에 대한 로드를 뒤따른다면, CPU A 의 로드는 CPU B
+의 로드가 내놓은 값과 같거나 그 후의 값을 내놓아야 합니다.
+
+리눅스 커널에서 범용 배리어의 사용은 이행성을 보장합니다.  따라서, 앞의 예에서
+CPU 2 의 X 로드가 1을, Y 로드는 0을 리턴했다면, CPU 3 의 X 로드는 반드시 1을
+리턴합니다.
+
+하지만, 읽기나 쓰기 배리어에 대해서는 이행성이 보장되지 -않습니다-.  예를 들어,
+앞의 예에서 CPU 2 의 범용 배리어가 아래처럼 읽기 배리어로 바뀐 경우를 생각해
+봅시다:
+
+	CPU 1			CPU 2			CPU 3
+	=======================	=======================	=======================
+		{ X = 0, Y = 0 }
+	STORE X=1		LOAD X			STORE Y=1
+				<읽기 배리어>		<범용 배리어>
+				LOAD Y			LOAD X
+
+이 코드는 이행성을 갖지 않습니다: 이 예에서는, CPU 2 의 X 로드가 1을
+리턴하고, Y 로드는 0을 리턴하지만 CPU 3 의 X 로드가 0을 리턴하는 것도 완전히
+합법적입니다.
+
+CPU 2 의 읽기 배리어가 자신의 읽기는 순서를 맞춰줘도, CPU 1 의 스토어와의
+순서를 맞춰준다고는 보장할 수 없다는게 핵심입니다.  따라서, CPU 1 과 CPU 2 가
+버퍼나 캐시를 공유하는 시스템에서 이 예제 코드가 실행된다면, CPU 2 는 CPU 1 이
+쓴 값에 좀 빨리 접근할 수 있을 것입니다.  따라서 CPU 1 과 CPU 2 의 접근으로
+조합된 순서를 모든 CPU 가 동의할 수 있도록 하기 위해 범용 배리어가 필요합니다.
+
+범용 배리어는 "글로벌 이행성"을 제공해서, 모든 CPU 들이 오퍼레이션들의 순서에
+동의하게 할 것입니다.  반면, release-acquire 조합은 "로컬 이행성" 만을
+제공해서, 해당 조합이 사용된 CPU 들만이 해당 액세스들의 조합된 순서에 동의함이
+보장됩니다.  예를 들어, 존경스런 Herman Hollerith 의 C 코드로 보면:
+
+	int u, v, x, y, z;
+
+	void cpu0(void)
+	{
+		r0 = smp_load_acquire(&x);
+		WRITE_ONCE(u, 1);
+		smp_store_release(&y, 1);
+	}
+
+	void cpu1(void)
+	{
+		r1 = smp_load_acquire(&y);
+		r4 = READ_ONCE(v);
+		r5 = READ_ONCE(u);
+		smp_store_release(&z, 1);
+	}
+
+	void cpu2(void)
+	{
+		r2 = smp_load_acquire(&z);
+		smp_store_release(&x, 1);
+	}
+
+	void cpu3(void)
+	{
+		WRITE_ONCE(v, 1);
+		smp_mb();
+		r3 = READ_ONCE(u);
+	}
+
+cpu0(), cpu1(), 그리고 cpu2() 는 smp_store_release()/smp_load_acquire() 쌍의
+연결을 통한 로컬 이행성에 동참하고 있으므로, 다음과 같은 결과는 나오지 않을
+겁니다:
+
+	r0 == 1 && r1 == 1 && r2 == 1
+
+더 나아가서, cpu0() 와 cpu1() 사이의 release-acquire 관계로 인해, cpu1() 은
+cpu0() 의 쓰기를 봐야만 하므로, 다음과 같은 결과도 없을 겁니다:
+
+	r1 == 1 && r5 == 0
+
+하지만, release-acquire 타동성은 동참한 CPU 들에만 적용되므로 cpu3() 에는
+적용되지 않습니다.  따라서, 다음과 같은 결과가 가능합니다:
+
+	r0 == 0 && r1 == 1 && r2 == 1 && r3 == 0 && r4 == 0
+
+비슷하게, 다음과 같은 결과도 가능합니다:
+
+	r0 == 0 && r1 == 1 && r2 == 1 && r3 == 0 && r4 == 0 && r5 == 1
+
+cpu0(), cpu1(), 그리고 cpu2() 는 그들의 읽기와 쓰기를 순서대로 보게 되지만,
+release-acquire 체인에 관여되지 않은 CPU 들은 그 순서에 이견을 가질 수
+있습니다.  이런 이견은 smp_load_acquire() 와 smp_store_release() 의 구현에
+사용되는 완화된 메모리 배리어 인스트럭션들은 항상 배리어 앞의 스토어들을 뒤의
+로드들에 앞세울 필요는 없다는 사실에서 기인합니다.  이 말은 cpu3() 는 cpu0() 의
+u 로의 스토어를 cpu1() 의 v 로부터의 로드 뒤에 일어난 것으로 볼 수 있다는
+뜻입니다, cpu0() 와 cpu1() 은 이 두 오퍼레이션이 의도된 순서대로 일어났음에
+모두 동의하는데도 말입니다.
+
+하지만, smp_load_acquire() 는 마술이 아님을 명심하시기 바랍니다.  구체적으로,
+이 함수는 단순히 순서 규칙을 지키며 인자로부터의 읽기를 수행합니다.  이것은
+어떤 특정한 값이 읽힐 것인지는 보장하지 -않습니다-.  따라서, 다음과 같은 결과도
+가능합니다:
+
+	r0 == 0 && r1 == 0 && r2 == 0 && r5 == 0
+
+이런 결과는 어떤 것도 재배치 되지 않는, 순차적 일관성을 가진 가상의
+시스템에서도 일어날 수 있음을 기억해 두시기 바랍니다.
+
+다시 말하지만, 당신의 코드가 글로벌 이행성을 필요로 한다면, 범용 배리어를
+사용하십시오.
+
+
+==================
+명시적 커널 배리어
+==================
+
+리눅스 커널은 서로 다른 단계에서 동작하는 다양한 배리어들을 가지고 있습니다:
+
+  (*) 컴파일러 배리어.
+
+  (*) CPU 메모리 배리어.
+
+  (*) MMIO 쓰기 배리어.
+
+
+컴파일러 배리어
+---------------
+
+리눅스 커널은 컴파일러가 메모리 액세스를 재배치 하는 것을 막아주는 명시적인
+컴파일러 배리어를 가지고 있습니다:
+
+	barrier();
+
+이건 범용 배리어입니다 -- barrier() 의 읽기-읽기 나 쓰기-쓰기 변종은 없습니다.
+하지만, READ_ONCE() 와 WRITE_ONCE() 는 특정 액세스들에 대해서만 동작하는
+barrier() 의 완화된 형태로 볼 수 있습니다.
+
+barrier() 함수는 다음과 같은 효과를 갖습니다:
+
+ (*) 컴파일러가 barrier() 뒤의 액세스들이 barrier() 앞의 액세스보다 앞으로
+     재배치되지 못하게 합니다.  예를 들어, 인터럽트 핸들러 코드와 인터럽트 당한
+     코드 사이의 통신을 신중히 하기 위해 사용될 수 있습니다.
+
+ (*) 루프에서, 컴파일러가 루프 조건에 사용된 변수를 매 이터레이션마다
+     메모리에서 로드하지 않아도 되도록 최적화 하는걸 방지합니다.
+
+READ_ONCE() 와 WRITE_ONCE() 함수는 싱글 쓰레드 코드에서는 문제 없지만 동시성이
+있는 코드에서는 문제가 될 수 있는 모든 최적화를 막습니다.  이런 류의 최적화에
+대한 예를 몇가지 들어보면 다음과 같습니다:
+
+ (*) 컴파일러는 같은 변수에 대한 로드와 스토어를 재배치 할 수 있고, 어떤
+     경우에는 CPU가 같은 변수로부터의 로드들을 재배치할 수도 있습니다.  이는
+     다음의 코드가:
+
+	a[0] = x;
+	a[1] = x;
+
+     x 의 예전 값이 a[1] 에, 새 값이 a[0] 에 있게 할 수 있다는 뜻입니다.
+     컴파일러와 CPU가 이런 일을 못하게 하려면 다음과 같이 해야 합니다:
+
+	a[0] = READ_ONCE(x);
+	a[1] = READ_ONCE(x);
+
+     즉, READ_ONCE() 와 WRITE_ONCE() 는 여러 CPU 에서 하나의 변수에 가해지는
+     액세스들에 캐시 일관성을 제공합니다.
+
+ (*) 컴파일러는 같은 변수에 대한 연속적인 로드들을 병합할 수 있습니다.  그런
+     병합 작업으로 컴파일러는 다음의 코드를:
+
+	while (tmp = a)
+		do_something_with(tmp);
+
+     다음과 같이, 싱글 쓰레드 코드에서는 말이 되지만 개발자의 의도와 전혀 맞지
+     않는 방향으로 "최적화" 할 수 있습니다:
+
+	if (tmp = a)
+		for (;;)
+			do_something_with(tmp);
+
+     컴파일러가 이런 짓을 하지 못하게 하려면 READ_ONCE() 를 사용하세요:
+
+	while (tmp = READ_ONCE(a))
+		do_something_with(tmp);
+
+ (*) 예컨대 레지스터 사용량이 많아 컴파일러가 모든 데이터를 레지스터에 담을 수
+     없는 경우, 컴파일러는 변수를 다시 로드할 수 있습니다.  따라서 컴파일러는
+     앞의 예에서 변수 'tmp' 사용을 최적화로 없애버릴 수 있습니다:
+
+	while (tmp = a)
+		do_something_with(tmp);
+
+     이 코드는 다음과 같이 싱글 쓰레드에서는 완벽하지만 동시성이 존재하는
+     경우엔 치명적인 코드로 바뀔 수 있습니다:
+
+	while (a)
+		do_something_with(a);
+
+     예를 들어, 최적화된 이 코드는 변수 a 가 다른 CPU 에 의해 "while" 문과
+     do_something_with() 호출 사이에 바뀌어 do_something_with() 에 0을 넘길
+     수도 있습니다.
+
+     이번에도, 컴파일러가 그런 짓을 하는걸 막기 위해 READ_ONCE() 를 사용하세요:
+
+	while (tmp = READ_ONCE(a))
+		do_something_with(tmp);
+
+     레지스터가 부족한 상황을 겪는 경우, 컴파일러는 tmp 를 스택에 저장해둘 수도
+     있습니다.  컴파일러가 변수를 다시 읽어들이는건 이렇게 저장해두고 후에 다시
+     읽어들이는데 드는 오버헤드 때문입니다.  그렇게 하는게 싱글 쓰레드
+     코드에서는 안전하므로, 안전하지 않은 경우에는 컴파일러에게 직접 알려줘야
+     합니다.
+
+ (*) 컴파일러는 그 값이 무엇일지 알고 있다면 로드를 아예 안할 수도 있습니다.
+     예를 들어, 다음의 코드는 변수 'a' 의 값이 항상 0임을 증명할 수 있다면:
+
+	while (tmp = a)
+		do_something_with(tmp);
+
+     이렇게 최적화 되어버릴 수 있습니다:
+
+	do { } while (0);
+
+     이 변환은 싱글 쓰레드 코드에서는 도움이 되는데 로드와 브랜치를 제거했기
+     때문입니다.  문제는 컴파일러가 'a' 의 값을 업데이트 하는건 현재의 CPU 하나
+     뿐이라는 가정 위에서 증명을 했다는데 있습니다.  만약 변수 'a' 가 공유되어
+     있다면, 컴파일러의 증명은 틀린 것이 될겁니다.  컴파일러는 그 자신이
+     생각하는 것만큼 많은 것을 알고 있지 못함을 컴파일러에게 알리기 위해
+     READ_ONCE() 를 사용하세요:
+
+	while (tmp = READ_ONCE(a))
+		do_something_with(tmp);
+
+     하지만 컴파일러는 READ_ONCE() 뒤에 나오는 값에 대해서도 눈길을 두고 있음을
+     기억하세요.  예를 들어, 다음의 코드에서 MAX 는 전처리기 매크로로, 1의 값을
+     갖는다고 해봅시다:
+
+	while ((tmp = READ_ONCE(a)) % MAX)
+		do_something_with(tmp);
+
+     이렇게 되면 컴파일러는 MAX 를 가지고 수행되는 "%" 오퍼레이터의 결과가 항상
+     0이라는 것을 알게 되고, 컴파일러가 코드를 실질적으로는 존재하지 않는
+     것처럼 최적화 하는 것이 허용되어 버립니다.  ('a' 변수의 로드는 여전히
+     행해질 겁니다.)
+
+ (*) 비슷하게, 컴파일러는 변수가 저장하려 하는 값을 이미 가지고 있다는 것을
+     알면 스토어 자체를 제거할 수 있습니다.  이번에도, 컴파일러는 현재의 CPU
+     만이 그 변수에 값을 쓰는 오로지 하나의 존재라고 생각하여 공유된 변수에
+     대해서는 잘못된 일을 하게 됩니다.  예를 들어, 다음과 같은 경우가 있을 수
+     있습니다:
+
+	a = 0;
+	... 변수 a 에 스토어를 하지 않는 코드 ...
+	a = 0;
+
+     컴파일러는 변수 'a' 의 값은 이미 0이라는 것을 알고, 따라서 두번째 스토어를
+     삭제할 겁니다.  만약 다른 CPU 가 그 사이 변수 'a' 에 다른 값을 썼다면
+     황당한 결과가 나올 겁니다.
+
+     컴파일러가 그런 잘못된 추측을 하지 않도록 WRITE_ONCE() 를 사용하세요:
+
+	WRITE_ONCE(a, 0);
+	... 변수 a 에 스토어를 하지 않는 코드 ...
+	WRITE_ONCE(a, 0);
+
+ (*) 컴파일러는 하지 말라고 하지 않으면 메모리 액세스들을 재배치 할 수
+     있습니다.  예를 들어, 다음의 프로세스 레벨 코드와 인터럽트 핸들러 사이의
+     상호작용을 생각해 봅시다:
+
+	void process_level(void)
+	{
+		msg = get_message();
+		flag = true;
+	}
+
+	void interrupt_handler(void)
+	{
+		if (flag)
+			process_message(msg);
+	}
+
+     이 코드에는 컴파일러가 process_level() 을 다음과 같이 변환하는 것을 막을
+     수단이 없고, 이런 변환은 싱글쓰레드에서라면 실제로 훌륭한 선택일 수
+     있습니다:
+
+	void process_level(void)
+	{
+		flag = true;
+		msg = get_message();
+	}
+
+     이 두개의 문장 사이에 인터럽트가 발생한다면, interrupt_handler() 는 의미를
+     알 수 없는 메세지를 받을 수도 있습니다.  이걸 막기 위해 다음과 같이
+     WRITE_ONCE() 를 사용하세요:
+
+	void process_level(void)
+	{
+		WRITE_ONCE(msg, get_message());
+		WRITE_ONCE(flag, true);
+	}
+
+	void interrupt_handler(void)
+	{
+		if (READ_ONCE(flag))
+			process_message(READ_ONCE(msg));
+	}
+
+     interrupt_handler() 안에서도 중첩된 인터럽트나 NMI 와 같이 인터럽트 핸들러
+     역시 'flag' 와 'msg' 에 접근하는 또다른 무언가에 인터럽트 될 수 있다면
+     READ_ONCE() 와 WRITE_ONCE() 를 사용해야 함을 기억해 두세요.  만약 그런
+     가능성이 없다면, interrupt_handler() 안에서는 문서화 목적이 아니라면
+     READ_ONCE() 와 WRITE_ONCE() 는 필요치 않습니다.  (근래의 리눅스 커널에서
+     중첩된 인터럽트는 보통 잘 일어나지 않음도 기억해 두세요, 실제로, 어떤
+     인터럽트 핸들러가 인터럽트가 활성화된 채로 리턴하면 WARN_ONCE() 가
+     실행됩니다.)
+
+     컴파일러는 READ_ONCE() 와 WRITE_ONCE() 뒤의 READ_ONCE() 나 WRITE_ONCE(),
+     barrier(), 또는 비슷한 것들을 담고 있지 않은 코드를 움직일 수 있을 것으로
+     가정되어야 합니다.
+
+     이 효과는 barrier() 를 통해서도 만들 수 있지만, READ_ONCE() 와
+     WRITE_ONCE() 가 좀 더 안목 높은 선택입니다: READ_ONCE() 와 WRITE_ONCE()는
+     컴파일러에 주어진 메모리 영역에 대해서만 최적화 가능성을 포기하도록
+     하지만, barrier() 는 컴파일러가 지금까지 기계의 레지스터에 캐시해 놓은
+     모든 메모리 영역의 값을 버려야 하게 하기 때문입니다.  물론, 컴파일러는
+     READ_ONCE() 와 WRITE_ONCE() 가 일어난 순서도 지켜줍니다, CPU 는 당연히
+     그 순서를 지킬 의무가 없지만요.
+
+ (*) 컴파일러는 다음의 예에서와 같이 변수에의 스토어를 날조해낼 수도 있습니다:
+
+	if (a)
+		b = a;
+	else
+		b = 42;
+
+     컴파일러는 아래와 같은 최적화로 브랜치를 줄일 겁니다:
+
+	b = 42;
+	if (a)
+		b = a;
+
+     싱글 쓰레드 코드에서 이 최적화는 안전할 뿐 아니라 브랜치 갯수를
+     줄여줍니다.  하지만 안타깝게도, 동시성이 있는 코드에서는 이 최적화는 다른
+     CPU 가 'b' 를 로드할 때, -- 'a' 가 0이 아닌데도 -- 가짜인 값, 42를 보게
+     되는 경우를 가능하게 합니다.  이걸 방지하기 위해 WRITE_ONCE() 를
+     사용하세요:
+
+	if (a)
+		WRITE_ONCE(b, a);
+	else
+		WRITE_ONCE(b, 42);
+
+     컴파일러는 로드를 만들어낼 수도 있습니다.  일반적으로는 문제를 일으키지
+     않지만, 캐시 라인 바운싱을 일으켜 성능과 확장성을 떨어뜨릴 수 있습니다.
+     날조된 로드를 막기 위해선 READ_ONCE() 를 사용하세요.
+
+ (*) 정렬된 메모리 주소에 위치한, 한번의 메모리 참조 인스트럭션으로 액세스
+     가능한 크기의 데이터는 하나의 큰 액세스가 여러개의 작은 액세스들로
+     대체되는 "로드 티어링(load tearing)" 과 "스토어 티어링(store tearing)" 을
+     방지합니다.  예를 들어, 주어진 아키텍쳐가 7-bit imeediate field 를 갖는
+     16-bit 스토어 인스트럭션을 제공한다면, 컴파일러는 다음의 32-bit 스토어를
+     구현하는데에 두개의 16-bit store-immediate 명령을 사용하려 할겁니다:
+
+	p = 0x00010002;
+
+     스토어 할 상수를 만들고 그 값을 스토어 하기 위해 두개가 넘는 인스트럭션을
+     사용하게 되는, 이런 종류의 최적화를 GCC 는 실제로 함을 부디 알아 두십시오.
+     이 최적화는 싱글 쓰레드 코드에서는 성공적인 최적화 입니다.  실제로, 근래에
+     발생한 (그리고 고쳐진) 버그는 GCC 가 volatile 스토어에 비정상적으로 이
+     최적화를 사용하게 했습니다.  그런 버그가 없다면, 다음의 예에서
+     WRITE_ONCE() 의 사용은 스토어 티어링을 방지합니다:
+
+	WRITE_ONCE(p, 0x00010002);
+
+     Packed 구조체의 사용 역시 다음의 예처럼  로드 / 스토어 티어링을 유발할 수
+     있습니다:
+
+	struct __attribute__((__packed__)) foo {
+		short a;
+		int b;
+		short c;
+	};
+	struct foo foo1, foo2;
+	...
+
+	foo2.a = foo1.a;
+	foo2.b = foo1.b;
+	foo2.c = foo1.c;
+
+     READ_ONCE() 나 WRITE_ONCE() 도 없고 volatile 마킹도 없기 때문에,
+     컴파일러는 이 세개의 대입문을 두개의 32-bit 로드와 두개의 32-bit 스토어로
+     변환할 수 있습니다.  이는 'foo1.b' 의 값의 로드 티어링과 'foo2.b' 의
+     스토어 티어링을 초래할 겁니다.  이 예에서도 READ_ONCE() 와 WRITE_ONCE()
+     가 티어링을 막을 수 있습니다:
+
+	foo2.a = foo1.a;
+	WRITE_ONCE(foo2.b, READ_ONCE(foo1.b));
+	foo2.c = foo1.c;
+
+그렇지만, volatile 로 마크된 변수에 대해서는 READ_ONCE() 와 WRITE_ONCE() 가
+필요치 않습니다.  예를 들어, 'jiffies' 는 volatile 로 마크되어 있기 때문에,
+READ_ONCE(jiffies) 라고 할 필요가 없습니다.  READ_ONCE() 와 WRITE_ONCE() 가
+실은 volatile 캐스팅으로 구현되어 있어서 인자가 이미 volatile 로 마크되어
+있다면 또다른 효과를 내지는 않기 때문입니다.
+
+이 컴파일러 배리어들은 CPU 에는 직접적 효과를 전혀 만들지 않기 때문에, 결국은
+재배치가 일어날 수도 있음을 부디 기억해 두십시오.
+
+
+CPU 메모리 배리어
+-----------------
+
+리눅스 커널은 다음의 여덟개 기본 CPU 메모리 배리어를 가지고 있습니다:
+
+	TYPE		MANDATORY		SMP CONDITIONAL
+	===============	=======================	===========================
+	범용		mb()			smp_mb()
+	쓰기		wmb()			smp_wmb()
+	읽기		rmb()			smp_rmb()
+	데이터 의존성	read_barrier_depends()	smp_read_barrier_depends()
+
+
+데이터 의존성 배리어를 제외한 모든 메모리 배리어는 컴파일러 배리어를
+포함합니다.  데이터 의존성은 컴파일러에의 추가적인 순서 보장을 포함하지
+않습니다.
+
+방백: 데이터 의존성이 있는 경우, 컴파일러는 해당 로드를 올바른 순서로 일으킬
+것으로 (예: `a[b]` 는 a[b] 를 로드 하기 전에 b 의 값을 먼저 로드한다)
+기대되지만, C 언어 사양에는 컴파일러가 b 의 값을 추측 (예: 1 과 같음) 해서
+b  로드 전에 a 로드를 하는 코드 (예: tmp = a[1]; if (b != 1) tmp = a[b]; ) 를
+만들지 않아야 한다는 내용 같은 건 없습니다.  또한 컴파일러는 a[b] 를 로드한
+후에 b 를 또다시 로드할 수도 있어서, a[b] 보다 최신 버전의 b 값을 가질 수도
+있습니다.  이런 문제들의 해결책에 대한 의견 일치는 아직 없습니다만, 일단
+READ_ONCE() 매크로부터 보기 시작하는게 좋은 시작이 될겁니다.
+
+SMP 메모리 배리어들은 유니프로세서로 컴파일된 시스템에서는 컴파일러 배리어로
+바뀌는데, 하나의 CPU 는 스스로 일관성을 유지하고, 겹치는 액세스들 역시 올바른
+순서로 행해질 것으로 생각되기 때문입니다.  하지만, 아래의 "Virtual Machine
+Guests" 서브섹션을 참고하십시오.
+
+[!] SMP 시스템에서 공유메모리로의 접근들을 순서 세워야 할 때, SMP 메모리
+배리어는 _반드시_ 사용되어야 함을 기억하세요, 그대신 락을 사용하는 것으로도
+충분하긴 하지만 말이죠.
+
+Mandatory 배리어들은 SMP 시스템에서도 UP 시스템에서도 SMP 효과만 통제하기에는
+불필요한 오버헤드를 갖기 때문에 SMP 효과만 통제하면 되는 곳에는 사용되지 않아야
+합니다.  하지만, 느슨한 순서 규칙의 메모리 I/O 윈도우를 통한 MMIO 의 효과를
+통제할 때에는 mandatory 배리어들이 사용될 수 있습니다.  이 배리어들은
+컴파일러와 CPU 모두 재배치를 못하도록 함으로써 메모리 오퍼레이션들이 디바이스에
+보여지는 순서에도 영향을 주기 때문에, SMP 가 아닌 시스템이라 할지라도 필요할 수
+있습니다.
+
+
+일부 고급 배리어 함수들도 있습니다:
+
+ (*) smp_store_mb(var, value)
+
+     이 함수는 특정 변수에 특정 값을 대입하고 범용 메모리 배리어를 칩니다.
+     UP 컴파일에서는 컴파일러 배리어보다 더한 것을 친다고는 보장되지 않습니다.
+
+
+ (*) smp_mb__before_atomic();
+ (*) smp_mb__after_atomic();
+
+     이것들은 값을 리턴하지 않는 (더하기, 빼기, 증가, 감소와 같은) 어토믹
+     함수들을 위한, 특히 그것들이 레퍼런스 카운팅에 사용될 때를 위한
+     함수들입니다.  이 함수들은 메모리 배리어를 내포하고 있지는 않습니다.
+
+     이것들은 값을 리턴하지 않으며 어토믹한 (set_bit 과 clear_bit 같은) 비트
+     연산에도 사용될 수 있습니다.
+
+     한 예로, 객체 하나를 무효한 것으로 표시하고 그 객체의 레퍼런스 카운트를
+     감소시키는 다음 코드를 보세요:
+
+	obj->dead = 1;
+	smp_mb__before_atomic();
+	atomic_dec(&obj->ref_count);
+
+     이 코드는 객체의 업데이트된 death 마크가 레퍼런스 카운터 감소 동작
+     *전에* 보일 것을 보장합니다.
+
+     더 많은 정보를 위해선 Documentation/atomic_ops.txt 문서를 참고하세요.
+     어디서 이것들을 사용해야 할지 궁금하다면 "어토믹 오퍼레이션" 서브섹션을
+     참고하세요.
+
+
+ (*) lockless_dereference();
+
+     이 함수는 smp_read_barrier_depends() 데이터 의존성 배리어를 사용하는
+     포인터 읽어오기 래퍼(wrapper) 함수로 생각될 수 있습니다.
+
+     객체의 라이프타임이 RCU 외의 메커니즘으로 관리된다는 점을 제외하면
+     rcu_dereference() 와도 유사한데, 예를 들면 객체가 시스템이 꺼질 때에만
+     제거되는 경우 등입니다.  또한, lockless_dereference() 은 RCU 와 함께
+     사용될수도, RCU 없이 사용될 수도 있는 일부 데이터 구조에 사용되고
+     있습니다.
+
+
+ (*) dma_wmb();
+ (*) dma_rmb();
+
+     이것들은 CPU 와 DMA 가능한 디바이스에서 모두 액세스 가능한 공유 메모리의
+     읽기, 쓰기 작업들의 순서를 보장하기 위해 consistent memory 에서 사용하기
+     위한 것들입니다.
+
+     예를 들어, 디바이스와 메모리를 공유하며, 디스크립터 상태 값을 사용해
+     디스크립터가 디바이스에 속해 있는지 아니면 CPU 에 속해 있는지 표시하고,
+     공지용 초인종(doorbell) 을 사용해 업데이트된 디스크립터가 디바이스에 사용
+     가능해졌음을 공지하는 디바이스 드라이버를 생각해 봅시다:
+
+	if (desc->status != DEVICE_OWN) {
+		/* 디스크립터를 소유하기 전에는 데이터를 읽지 않음 */
+		dma_rmb();
+
+		/* 데이터를 읽고 씀 */
+		read_data = desc->data;
+		desc->data = write_data;
+
+		/* 상태 업데이트 전 수정사항을 반영 */
+		dma_wmb();
+
+		/* 소유권을 수정 */
+		desc->status = DEVICE_OWN;
+
+		/* MMIO 를 통해 디바이스에 공지를 하기 전에 메모리를 동기화 */
+		wmb();
+
+		/* 업데이트된 디스크립터의 디바이스에 공지 */
+		writel(DESC_NOTIFY, doorbell);
+	}
+
+     dma_rmb() 는 디스크립터로부터 데이터를 읽어오기 전에 디바이스가 소유권을
+     내놓았음을 보장하게 하고, dma_wmb() 는 디바이스가 자신이 소유권을 다시
+     가졌음을 보기 전에 디스크립터에 데이터가 쓰였음을 보장합니다.  wmb() 는
+     캐시 일관성이 없는 (cache incoherent) MMIO 영역에 쓰기를 시도하기 전에
+     캐시 일관성이 있는 메모리 (cache coherent memory) 쓰기가 완료되었음을
+     보장해주기 위해 필요합니다.
+
+     consistent memory 에 대한 자세한 내용을 위해선 Documentation/DMA-API.txt
+     문서를 참고하세요.
+
+
+MMIO 쓰기 배리어
+----------------
+
+리눅스 커널은 또한 memory-mapped I/O 쓰기를 위한 특별한 배리어도 가지고
+있습니다:
+
+	mmiowb();
+
+이것은 mandatory 쓰기 배리어의 변종으로, 완화된 순서 규칙의 I/O 영역에으로의
+쓰기가 부분적으로 순서를 맞추도록 해줍니다.  이 함수는 CPU->하드웨어 사이를
+넘어서 실제 하드웨어에까지 일부 수준의 영향을 끼칩니다.
+
+더 많은 정보를 위해선 "Acquire vs I/O 액세스" 서브섹션을 참고하세요.
+
+
+=========================
+암묵적 커널 메모리 배리어
+=========================
+
+리눅스 커널의 일부 함수들은 메모리 배리어를 내장하고 있는데, 락(lock)과
+스케쥴링 관련 함수들이 대부분입니다.
+
+여기선 _최소한의_ 보장을 설명합니다; 특정 아키텍쳐에서는 이 설명보다 더 많은
+보장을 제공할 수도 있습니다만 해당 아키텍쳐에 종속적인 코드 외의 부분에서는
+그런 보장을 기대해선 안될겁니다.
+
+
+락 ACQUISITION 함수
+-------------------
+
+리눅스 커널은 다양한 락 구성체를 가지고 있습니다:
+
+ (*) 스핀 락
+ (*) R/W 스핀 락
+ (*) 뮤텍스
+ (*) 세마포어
+ (*) R/W 세마포어
+
+각 구성체마다 모든 경우에 "ACQUIRE" 오퍼레이션과 "RELEASE" 오퍼레이션의 변종이
+존재합니다.  이 오퍼레이션들은 모두 적절한 배리어를 내포하고 있습니다:
+
+ (1) ACQUIRE 오퍼레이션의 영향:
+
+     ACQUIRE 뒤에서 요청된 메모리 오퍼레이션은 ACQUIRE 오퍼레이션이 완료된
+     뒤에 완료됩니다.
+
+     ACQUIRE 앞에서 요청된 메모리 오퍼레이션은 ACQUIRE 오퍼레이션이 완료된 후에
+     완료될 수 있습니다.  smp_mb__before_spinlock() 뒤에 ACQUIRE 가 실행되는
+     코드 블록은 블록 앞의 스토어를 블록 뒤의 로드와 스토어에 대해 순서
+     맞춥니다.  이건 smp_mb() 보다 완화된 것임을 기억하세요!  많은 아키텍쳐에서
+     smp_mb__before_spinlock() 은 사실 아무일도 하지 않습니다.
+
+ (2) RELEASE 오퍼레이션의 영향:
+
+     RELEASE 앞에서 요청된 메모리 오퍼레이션은 RELEASE 오퍼레이션이 완료되기
+     전에 완료됩니다.
+
+     RELEASE 뒤에서 요청된 메모리 오퍼레이션은 RELEASE 오퍼레이션 완료 전에
+     완료될 수 있습니다.
+
+ (3) ACQUIRE vs ACQUIRE 영향:
+
+     어떤 ACQUIRE 오퍼레이션보다 앞에서 요청된 모든 ACQUIRE 오퍼레이션은 그
+     ACQUIRE 오퍼레이션 전에 완료됩니다.
+
+ (4) ACQUIRE vs RELEASE implication:
+
+     어떤 RELEASE 오퍼레이션보다 앞서 요청된 ACQUIRE 오퍼레이션은 그 RELEASE
+     오퍼레이션보다 먼저 완료됩니다.
+
+ (5) 실패한 조건적 ACQUIRE 영향:
+
+     ACQUIRE 오퍼레이션의 일부 락(lock) 변종은 락이 곧바로 획득하기에는
+     불가능한 상태이거나 락이 획득 가능해지도록 기다리는 도중 시그널을 받거나
+     해서 실패할 수 있습니다.  실패한 락은 어떤 배리어도 내포하지 않습니다.
+
+[!] 참고: 락 ACQUIRE 와 RELEASE 가 단방향 배리어여서 나타나는 현상 중 하나는
+크리티컬 섹션 바깥의 인스트럭션의 영향이 크리티컬 섹션 내부로도 들어올 수
+있다는 것입니다.
+
+RELEASE 후에 요청되는 ACQUIRE 는 전체 메모리 배리어라 여겨지면 안되는데,
+ACQUIRE 앞의 액세스가 ACQUIRE 후에 수행될 수 있고, RELEASE 후의 액세스가
+RELEASE 전에 수행될 수도 있으며, 그 두개의 액세스가 서로를 지나칠 수도 있기
+때문입니다:
+
+	*A = a;
+	ACQUIRE M
+	RELEASE M
+	*B = b;
+
+는 다음과 같이 될 수도 있습니다:
+
+	ACQUIRE M, STORE *B, STORE *A, RELEASE M
+
+ACQUIRE 와 RELEASE 가 락 획득과 해제라면, 그리고 락의 ACQUIRE 와 RELEASE 가
+같은 락 변수에 대한 것이라면, 해당 락을 쥐고 있지 않은 다른 CPU 의 시야에는
+이와 같은 재배치가 일어나는 것으로 보일 수 있습니다.  요약하자면, ACQUIRE 에
+이어 RELEASE 오퍼레이션을 순차적으로 실행하는 행위가 전체 메모리 배리어로
+생각되어선 -안됩니다-.
+
+비슷하게, 앞의 반대 케이스인 RELEASE 와 ACQUIRE 두개 오퍼레이션의 순차적 실행
+역시 전체 메모리 배리어를 내포하지 않습니다.  따라서, RELEASE, ACQUIRE 로
+규정되는 크리티컬 섹션의 CPU 수행은 RELEASE 와 ACQUIRE 를 가로지를 수 있으므로,
+다음과 같은 코드는:
+
+	*A = a;
+	RELEASE M
+	ACQUIRE N
+	*B = b;
+
+다음과 같이 수행될 수 있습니다:
+
+	ACQUIRE N, STORE *B, STORE *A, RELEASE M
+
+이런 재배치는 데드락을 일으킬 수도 있을 것처럼 보일 수 있습니다.  하지만, 그런
+데드락의 조짐이 있다면 RELEASE 는 단순히 완료될 것이므로 데드락은 존재할 수
+없습니다.
+
+	이게 어떻게 올바른 동작을 할 수 있을까요?
+
+	우리가 이야기 하고 있는건 재배치를 하는 CPU 에 대한 이야기이지,
+	컴파일러에 대한 것이 아니란 점이 핵심입니다.  컴파일러 (또는, 개발자)
+	가 오퍼레이션들을 이렇게 재배치하면, 데드락이 일어날 수 -있습-니다.
+
+	하지만 CPU 가 오퍼레이션들을 재배치 했다는걸 생각해 보세요.  이 예에서,
+	어셈블리 코드 상으로는 언락이 락을 앞서게 되어 있습니다.  CPU 가 이를
+	재배치해서 뒤의 락 오퍼레이션을 먼저 실행하게 됩니다.  만약 데드락이
+	존재한다면, 이 락 오퍼레이션은 그저 스핀을 하며 계속해서 락을
+	시도합니다 (또는, 한참 후에겠지만, 잠듭니다).  CPU 는 언젠가는
+	(어셈블리 코드에서는 락을 앞서는) 언락 오퍼레이션을 실행하는데, 이 언락
+	오퍼레이션이 잠재적 데드락을 해결하고, 락 오퍼레이션도 뒤이어 성공하게
+	됩니다.
+
+	하지만 만약 락이 잠을 자는 타입이었다면요?  그런 경우에 코드는
+	스케쥴러로 들어가려 할 거고, 여기서 결국은 메모리 배리어를 만나게
+	되는데, 이 메모리 배리어는 앞의 언락 오퍼레이션이 완료되도록 만들고,
+	데드락은 이번에도 해결됩니다.  잠을 자는 행위와 언락 사이의 경주 상황
+	(race) 도 있을 수 있겠습니다만, 락 관련 기능들은 그런 경주 상황을 모든
+	경우에 제대로 해결할 수 있어야 합니다.
+
+락과 세마포어는 UP 컴파일된 시스템에서의 순서에 대해 보장을 하지 않기 때문에,
+그런 상황에서 인터럽트 비활성화 오퍼레이션과 함께가 아니라면 어떤 일에도 - 특히
+I/O 액세스와 관련해서는 - 제대로 사용될 수 없을 겁니다.
+
+"CPU 간 ACQUIRING 배리어 효과" 섹션도 참고하시기 바랍니다.
+
+
+예를 들어, 다음과 같은 코드를 생각해 봅시다:
+
+	*A = a;
+	*B = b;
+	ACQUIRE
+	*C = c;
+	*D = d;
+	RELEASE
+	*E = e;
+	*F = f;
+
+여기선 다음의 이벤트 시퀀스가 생길 수 있습니다:
+
+	ACQUIRE, {*F,*A}, *E, {*C,*D}, *B, RELEASE
+
+	[+] {*F,*A} 는 조합된 액세스를 의미합니다.
+
+하지만 다음과 같은 건 불가능하죠:
+
+	{*F,*A}, *B,	ACQUIRE, *C, *D,	RELEASE, *E
+	*A, *B, *C,	ACQUIRE, *D,		RELEASE, *E, *F
+	*A, *B,		ACQUIRE, *C,		RELEASE, *D, *E, *F
+	*B,		ACQUIRE, *C, *D,	RELEASE, {*F,*A}, *E
+
+
+
+인터럽트 비활성화 함수
+----------------------
+
+인터럽트를 비활성화 하는 함수 (ACQUIRE 와 동일) 와 인터럽트를 활성화 하는 함수
+(RELEASE 와 동일) 는 컴파일러 배리어처럼만 동작합니다.  따라서, 별도의 메모리
+배리어나 I/O 배리어가 필요한 상황이라면 그 배리어들은 인터럽트 비활성화 함수
+외의 방법으로 제공되어야만 합니다.
+
+
+슬립과 웨이크업 함수
+--------------------
+
+글로벌 데이터에 표시된 이벤트에 의해 프로세스를 잠에 빠트리는 것과 깨우는 것은
+해당 이벤트를 기다리는 태스크의 태스크 상태와 그 이벤트를 알리기 위해 사용되는
+글로벌 데이터, 두 데이터간의 상호작용으로 볼 수 있습니다.  이것이 옳은 순서대로
+일어남을 분명히 하기 위해, 프로세스를 잠에 들게 하는 기능과 깨우는 기능은
+몇가지 배리어를 내포합니다.
+
+먼저, 잠을 재우는 쪽은 일반적으로 다음과 같은 이벤트 시퀀스를 따릅니다:
+
+	for (;;) {
+		set_current_state(TASK_UNINTERRUPTIBLE);
+		if (event_indicated)
+			break;
+		schedule();
+	}
+
+set_current_state() 에 의해, 태스크 상태가 바뀐 후 범용 메모리 배리어가
+자동으로 삽입됩니다:
+
+	CPU 1
+	===============================
+	set_current_state();
+	  smp_store_mb();
+	    STORE current->state
+	    <범용 배리어>
+	LOAD event_indicated
+
+set_current_state() 는 다음의 것들로 감싸질 수도 있습니다:
+
+	prepare_to_wait();
+	prepare_to_wait_exclusive();
+
+이것들 역시 상태를 설정한 후 범용 메모리 배리어를 삽입합니다.
+앞의 전체 시퀀스는 다음과 같은 함수들로 한번에 수행 가능한데, 이것들은 모두
+올바른 장소에 메모리 배리어를 삽입합니다:
+
+	wait_event();
+	wait_event_interruptible();
+	wait_event_interruptible_exclusive();
+	wait_event_interruptible_timeout();
+	wait_event_killable();
+	wait_event_timeout();
+	wait_on_bit();
+	wait_on_bit_lock();
+
+
+두번째로, 깨우기를 수행하는 코드는 일반적으로 다음과 같을 겁니다:
+
+	event_indicated = 1;
+	wake_up(&event_wait_queue);
+
+또는:
+
+	event_indicated = 1;
+	wake_up_process(event_daemon);
+
+wake_up() 류에 의해 쓰기 메모리 배리어가 내포됩니다.  만약 그것들이 뭔가를
+깨운다면요.  이 배리어는 태스크 상태가 지워지기 전에 수행되므로, 이벤트를
+알리기 위한 STORE 와 태스크 상태를 TASK_RUNNING 으로 설정하는 STORE 사이에
+위치하게 됩니다.
+
+	CPU 1				CPU 2
+	===============================	===============================
+	set_current_state();		STORE event_indicated
+	  smp_store_mb();		wake_up();
+	    STORE current->state	  <쓰기 배리어>
+	    <범용 배리어>		  STORE current->state
+	LOAD event_indicated
+
+한번더 말합니다만, 이 쓰기 메모리 배리어는 이 코드가 정말로 뭔가를 깨울 때에만
+실행됩니다.  이걸 설명하기 위해, X 와 Y 는 모두 0 으로 초기화 되어 있다는 가정
+하에 아래의 이벤트 시퀀스를 생각해 봅시다:
+
+	CPU 1				CPU 2
+	===============================	===============================
+	X = 1;				STORE event_indicated
+	smp_mb();			wake_up();
+	Y = 1;				wait_event(wq, Y == 1);
+	wake_up();			  load from Y sees 1, no memory barrier
+					load from X might see 0
+
+위 예제에서의 경우와 달리 깨우기가 정말로 행해졌다면, CPU 2 의 X 로드는 1 을
+본다고 보장될 수 있을 겁니다.
+
+사용 가능한 깨우기류 함수들로 다음과 같은 것들이 있습니다:
+
+	complete();
+	wake_up();
+	wake_up_all();
+	wake_up_bit();
+	wake_up_interruptible();
+	wake_up_interruptible_all();
+	wake_up_interruptible_nr();
+	wake_up_interruptible_poll();
+	wake_up_interruptible_sync();
+	wake_up_interruptible_sync_poll();
+	wake_up_locked();
+	wake_up_locked_poll();
+	wake_up_nr();
+	wake_up_poll();
+	wake_up_process();
+
+
+[!] 잠재우는 코드와 깨우는 코드에 내포되는 메모리 배리어들은 깨우기 전에
+이루어진 스토어를 잠재우는 코드가 set_current_state() 를 호출한 후에 행하는
+로드에 대해 순서를 맞추지 _않는다는_ 점을 기억하세요.  예를 들어, 잠재우는
+코드가 다음과 같고:
+
+	set_current_state(TASK_INTERRUPTIBLE);
+	if (event_indicated)
+		break;
+	__set_current_state(TASK_RUNNING);
+	do_something(my_data);
+
+깨우는 코드는 다음과 같다면:
+
+	my_data = value;
+	event_indicated = 1;
+	wake_up(&event_wait_queue);
+
+event_indecated 에의 변경이 잠재우는 코드에게 my_data 에의 변경 후에 이루어진
+것으로 인지될 것이라는 보장이 없습니다.  이런 경우에는 양쪽 코드 모두 각각의
+데이터 액세스 사이에 메모리 배리어를 직접 쳐야 합니다.  따라서 앞의 재우는
+코드는 다음과 같이:
+
+	set_current_state(TASK_INTERRUPTIBLE);
+	if (event_indicated) {
+		smp_rmb();
+		do_something(my_data);
+	}
+
+그리고 깨우는 코드는 다음과 같이 되어야 합니다:
+
+	my_data = value;
+	smp_wmb();
+	event_indicated = 1;
+	wake_up(&event_wait_queue);
+
+
+그외의 함수들
+-------------
+
+그외의 배리어를 내포하는 함수들은 다음과 같습니다:
+
+ (*) schedule() 과 그 유사한 것들이 완전한 메모리 배리어를 내포합니다.
+
+
+==============================
+CPU 간 ACQUIRING 배리어의 효과
+==============================
+
+SMP 시스템에서의 락 기능들은 더욱 강력한 형태의 배리어를 제공합니다: 이
+배리어는 동일한 락을 사용하는 다른 CPU 들의 메모리 액세스 순서에도 영향을
+끼칩니다.
+
+
+ACQUIRE VS 메모리 액세스
+------------------------
+
+다음의 예를 생각해 봅시다: 시스템은 두개의 스핀락 (M) 과 (Q), 그리고 세개의 CPU
+를 가지고 있습니다; 여기에 다음의 이벤트 시퀀스가 발생합니다:
+
+	CPU 1				CPU 2
+	===============================	===============================
+	WRITE_ONCE(*A, a);		WRITE_ONCE(*E, e);
+	ACQUIRE M			ACQUIRE Q
+	WRITE_ONCE(*B, b);		WRITE_ONCE(*F, f);
+	WRITE_ONCE(*C, c);		WRITE_ONCE(*G, g);
+	RELEASE M			RELEASE Q
+	WRITE_ONCE(*D, d);		WRITE_ONCE(*H, h);
+
+*A 로의 액세스부터 *H 로의 액세스까지가 어떤 순서로 CPU 3 에게 보여질지에
+대해서는 각 CPU 에서의 락 사용에 의해 내포되어 있는 제약을 제외하고는 어떤
+보장도 존재하지 않습니다.  예를 들어, CPU 3 에게 다음과 같은 순서로 보여지는
+것이 가능합니다:
+
+	*E, ACQUIRE M, ACQUIRE Q, *G, *C, *F, *A, *B, RELEASE Q, *D, *H, RELEASE M
+
+하지만 다음과 같이 보이지는 않을 겁니다:
+
+	*B, *C or *D preceding ACQUIRE M
+	*A, *B or *C following RELEASE M
+	*F, *G or *H preceding ACQUIRE Q
+	*E, *F or *G following RELEASE Q
+
+
+
+ACQUIRE VS I/O 액세스
+----------------------
+
+특정한 (특히 NUMA 가 관련된) 환경 하에서 두개의 CPU 에서 동일한 스핀락으로
+보호되는 두개의 크리티컬 섹션 안의 I/O 액세스는 PCI 브릿지에 겹쳐진 I/O
+액세스로 보일 수 있는데, PCI 브릿지는 캐시 일관성 프로토콜과 합을 맞춰야 할
+의무가 없으므로, 필요한 읽기 메모리 배리어가 요청되지 않기 때문입니다.
+
+예를 들어서:
+
+	CPU 1				CPU 2
+	===============================	===============================
+	spin_lock(Q)
+	writel(0, ADDR)
+	writel(1, DATA);
+	spin_unlock(Q);
+					spin_lock(Q);
+					writel(4, ADDR);
+					writel(5, DATA);
+					spin_unlock(Q);
+
+는 PCI 브릿지에 다음과 같이 보일 수 있습니다:
+
+	STORE *ADDR = 0, STORE *ADDR = 4, STORE *DATA = 1, STORE *DATA = 5
+
+이렇게 되면 하드웨어의 오동작을 일으킬 수 있습니다.
+
+
+이런 경우엔 잡아둔 스핀락을 내려놓기 전에 mmiowb() 를 수행해야 하는데, 예를
+들면 다음과 같습니다:
+
+	CPU 1				CPU 2
+	===============================	===============================
+	spin_lock(Q)
+	writel(0, ADDR)
+	writel(1, DATA);
+	mmiowb();
+	spin_unlock(Q);
+					spin_lock(Q);
+					writel(4, ADDR);
+					writel(5, DATA);
+					mmiowb();
+					spin_unlock(Q);
+
+이 코드는 CPU 1 에서 요청된 두개의 스토어가 PCI 브릿지에 CPU 2 에서 요청된
+스토어들보다 먼저 보여짐을 보장합니다.
+
+
+또한, 같은 디바이스에서 스토어를 이어 로드가 수행되면 이 로드는 로드가 수행되기
+전에 스토어가 완료되기를 강제하므로 mmiowb() 의 필요가 없어집니다:
+
+	CPU 1				CPU 2
+	===============================	===============================
+	spin_lock(Q)
+	writel(0, ADDR)
+	a = readl(DATA);
+	spin_unlock(Q);
+					spin_lock(Q);
+					writel(4, ADDR);
+					b = readl(DATA);
+					spin_unlock(Q);
+
+
+더 많은 정보를 위해선 Documenataion/DocBook/deviceiobook.tmpl 을 참고하세요.
+
+
+=========================
+메모리 배리어가 필요한 곳
+=========================
+
+설령 SMP 커널을 사용하더라도 싱글 쓰레드로 동작하는 코드는 올바르게 동작하는
+것으로 보여질 것이기 때문에, 평범한 시스템 운영중에 메모리 오퍼레이션 재배치는
+일반적으로 문제가 되지 않습니다.  하지만, 재배치가 문제가 _될 수 있는_ 네가지
+환경이 있습니다:
+
+ (*) 프로세서간 상호 작용.
+
+ (*) 어토믹 오퍼레이션.
+
+ (*) 디바이스 액세스.
+
+ (*) 인터럽트.
+
+
+프로세서간 상호 작용
+--------------------
+
+두개 이상의 프로세서를 가진 시스템이 있다면, 시스템의 두개 이상의 CPU 는 동시에
+같은 데이터에 대한 작업을 할 수 있습니다.  이는 동기화 문제를 일으킬 수 있고,
+이 문제를 해결하는 일반적 방법은 락을 사용하는 것입니다.  하지만, 락은 상당히
+비용이 비싸서 가능하면 락을 사용하지 않고 일을 처리하는 것이 낫습니다.  이런
+경우, 두 CPU 모두에 영향을 끼치는 오퍼레이션들은 오동작을 막기 위해 신중하게
+순서가 맞춰져야 합니다.
+
+예를 들어, R/W 세마포어의 느린 수행경로 (slow path) 를 생각해 봅시다.
+세마포어를 위해 대기를 하는 하나의 프로세스가 자신의 스택 중 일부를 이
+세마포어의 대기 프로세스 리스트에 링크한 채로 있습니다:
+
+	struct rw_semaphore {
+		...
+		spinlock_t lock;
+		struct list_head waiters;
+	};
+
+	struct rwsem_waiter {
+		struct list_head list;
+		struct task_struct *task;
+	};
+
+특정 대기 상태 프로세스를 깨우기 위해, up_read() 나 up_write() 함수는 다음과
+같은 일을 합니다:
+
+ (1) 다음 대기 상태 프로세스 레코드는 어디있는지 알기 위해 이 대기 상태
+     프로세스 레코드의 next 포인터를 읽습니다;
+
+ (2) 이 대기 상태 프로세스의 task 구조체로의 포인터를 읽습니다;
+
+ (3) 이 대기 상태 프로세스가 세마포어를 획득했음을 알리기 위해 task
+     포인터를 초기화 합니다;
+
+ (4) 해당 태스크에 대해 wake_up_process() 를 호출합니다; 그리고
+
+ (5) 해당 대기 상태 프로세스의 task 구조체를 잡고 있던 레퍼런스를 해제합니다.
+
+달리 말하자면, 다음 이벤트 시퀀스를 수행해야 합니다:
+
+	LOAD waiter->list.next;
+	LOAD waiter->task;
+	STORE waiter->task;
+	CALL wakeup
+	RELEASE task
+
+그리고 이 이벤트들이 다른 순서로 수행된다면, 오동작이 일어날 수 있습니다.
+
+한번 세마포어의 대기줄에 들어갔고 세마포어 락을 놓았다면, 해당 대기 프로세스는
+락을 다시는 잡지 않습니다; 대신 자신의 task 포인터가 초기화 되길 기다립니다.
+그 레코드는 대기 프로세스의 스택에 있기 때문에, 리스트의 next 포인터가 읽혀지기
+_전에_ task 포인터가 지워진다면, 다른 CPU 는 해당 대기 프로세스를 시작해 버리고
+up*() 함수가 next 포인터를 읽기 전에 대기 프로세스의 스택을 마구 건드릴 수
+있습니다.
+
+그렇게 되면 위의 이벤트 시퀀스에 어떤 일이 일어나는지 생각해 보죠:
+
+	CPU 1				CPU 2
+	===============================	===============================
+					down_xxx()
+					Queue waiter
+					Sleep
+	up_yyy()
+	LOAD waiter->task;
+	STORE waiter->task;
+					Woken up by other event
+	
+					Resume processing
+					down_xxx() returns
+					call foo()
+					foo() clobbers *waiter
+	
+	LOAD waiter->list.next;
+	--- OOPS ---
+
+이 문제는 세마포어 락의 사용으로 해결될 수도 있겠지만, 그렇게 되면 깨어난 후에
+down_xxx() 함수가 불필요하게 스핀락을 또다시 얻어야만 합니다.
+
+이 문제를 해결하는 방법은 범용 SMP 메모리 배리어를 추가하는 겁니다:
+
+	LOAD waiter->list.next;
+	LOAD waiter->task;
+	smp_mb();
+	STORE waiter->task;
+	CALL wakeup
+	RELEASE task
+
+이 경우에, 배리어는 시스템의 나머지 CPU 들에게 모든 배리어 앞의 메모리 액세스가
+배리어 뒤의 메모리 액세스보다 앞서 일어난 것으로 보이게 만듭니다.  배리어 앞의
+메모리 액세스들이 배리어 명령 자체가 완료되는 시점까지 완료된다고는 보장하지
+_않습니다_.
+
+(이게 문제가 되지 않을) 단일 프로세서 시스템에서 smp_mb() 는 실제로는 그저
+컴파일러가 CPU 안에서의 순서를 바꾸거나 하지 않고 주어진 순서대로 명령을
+내리도록 하는 컴파일러 배리어일 뿐입니다.  오직 하나의 CPU 만 있으니, CPU 의
+의존성 순서 로직이 그 외의 모든것을 알아서 처리할 겁니다.
+
+
+어토믹 오퍼레이션
+-----------------
+
+어토믹 오퍼레이션은 기술적으로 프로세서간 상호작용으로 분류되며 그 중 일부는
+전체 메모리 배리어를 내포하고 또 일부는 내포하지 않지만, 커널에서 상당히
+의존적으로 사용하는 기능 중 하나입니다.
+
+메모리의 어떤 상태를 수정하고 해당 상태에 대한 (예전의 또는 최신의) 정보를
+리턴하는 어토믹 오퍼레이션은 모두 SMP-조건적 범용 메모리 배리어(smp_mb())를
+실제 오퍼레이션의 앞과 뒤에 내포합니다.  이런 오퍼레이션은 다음의 것들을
+포함합니다:
+
+	xchg();
+	atomic_xchg();			atomic_long_xchg();
+	atomic_inc_return();		atomic_long_inc_return();
+	atomic_dec_return();		atomic_long_dec_return();
+	atomic_add_return();		atomic_long_add_return();
+	atomic_sub_return();		atomic_long_sub_return();
+	atomic_inc_and_test();		atomic_long_inc_and_test();
+	atomic_dec_and_test();		atomic_long_dec_and_test();
+	atomic_sub_and_test();		atomic_long_sub_and_test();
+	atomic_add_negative();		atomic_long_add_negative();
+	test_and_set_bit();
+	test_and_clear_bit();
+	test_and_change_bit();
+
+	/* exchange 조건이 성공할 때 */
+	cmpxchg();
+	atomic_cmpxchg();		atomic_long_cmpxchg();
+	atomic_add_unless();		atomic_long_add_unless();
+
+이것들은 메모리 배리어 효과가 필요한 ACQUIRE 부류와 RELEASE 부류 오퍼레이션들을
+구현할 때, 그리고 객체 해제를 위해 레퍼런스 카운터를 조정할 때, 암묵적 메모리
+배리어 효과가 필요한 곳 등에 사용됩니다.
+
+
+다음의 오퍼레이션들은 메모리 배리어를 내포하지 _않기_ 때문에 문제가 될 수
+있지만, RELEASE 부류의 오퍼레이션들과 같은 것들을 구현할 때 사용될 수도
+있습니다:
+
+	atomic_set();
+	set_bit();
+	clear_bit();
+	change_bit();
+
+이것들을 사용할 때에는 필요하다면 적절한 (예를 들면 smp_mb__before_atomic()
+같은) 메모리 배리어가 명시적으로 함께 사용되어야 합니다.
+
+
+아래의 것들도 메모리 배리어를 내포하지 _않기_ 때문에, 일부 환경에서는 (예를
+들면 smp_mb__before_atomic() 과 같은) 명시적인 메모리 배리어 사용이 필요합니다.
+
+	atomic_add();
+	atomic_sub();
+	atomic_inc();
+	atomic_dec();
+
+이것들이 통계 생성을 위해 사용된다면, 그리고 통계 데이터 사이에 관계가 존재하지
+않는다면 메모리 배리어는 필요치 않을 겁니다.
+
+객체의 수명을 관리하기 위해 레퍼런스 카운팅 목적으로 사용된다면, 레퍼런스
+카운터는 락으로 보호되는 섹션에서만 조정되거나 호출하는 쪽이 이미 충분한
+레퍼런스를 잡고 있을 것이기 때문에 메모리 배리어는 아마 필요 없을 겁니다.
+
+만약 어떤 락을 구성하기 위해 사용된다면, 락 관련 동작은 일반적으로 작업을 특정
+순서대로 진행해야 하므로 메모리 배리어가 필요할 수 있습니다.
+
+기본적으로, 각 사용처에서는 메모리 배리어가 필요한지 아닌지 충분히 고려해야
+합니다.
+
+아래의 오퍼레이션들은 특별한 락 관련 동작들입니다:
+
+	test_and_set_bit_lock();
+	clear_bit_unlock();
+	__clear_bit_unlock();
+
+이것들은 ACQUIRE 류와 RELEASE 류의 오퍼레이션들을 구현합니다.  락 관련 도구를
+구현할 때에는 이것들을 좀 더 선호하는 편이 나은데, 이것들의 구현은 많은
+아키텍쳐에서 최적화 될 수 있기 때문입니다.
+
+[!] 이런 상황에 사용할 수 있는 특수한 메모리 배리어 도구들이 있습니다만, 일부
+CPU 에서는 사용되는 어토믹 인스트럭션 자체에 메모리 배리어가 내포되어 있어서
+어토믹 오퍼레이션과 메모리 배리어를 함께 사용하는 게 불필요한 일이 될 수
+있는데, 그런 경우에 이 특수 메모리 배리어 도구들은 no-op 이 되어 실질적으로
+아무일도 하지 않습니다.
+
+더 많은 내용을 위해선 Documentation/atomic_ops.txt 를 참고하세요.
+
+
+디바이스 액세스
+---------------
+
+많은 디바이스가 메모리 매핑 기법으로 제어될 수 있는데, 그렇게 제어되는
+디바이스는 CPU 에는 단지 특정 메모리 영역의 집합처럼 보이게 됩니다.  드라이버는
+그런 디바이스를 제어하기 위해 정확히 올바른 순서로 올바른 메모리 액세스를
+만들어야 합니다.
+
+하지만, 액세스들을 재배치 하거나 조합하거나 병합하는게 더 효율적이라 판단하는
+영리한 CPU 나 컴파일러들을 사용하면 드라이버 코드의 조심스럽게 순서 맞춰진
+액세스들이 디바이스에는 요청된 순서대로 도착하지 못하게 할 수 있는 - 디바이스가
+오동작을 하게 할 - 잠재적 문제가 생길 수 있습니다.
+
+리눅스 커널 내부에서, I/O 는 어떻게 액세스들을 적절히 순차적이게 만들 수 있는지
+알고 있는, - inb() 나 writel() 과 같은 - 적절한 액세스 루틴을 통해 이루어져야만
+합니다.  이것들은 대부분의 경우에는 명시적 메모리 배리어 와 함께 사용될 필요가
+없습니다만, 다음의 두가지 상황에서는 명시적 메모리 배리어가 필요할 수 있습니다:
+
+ (1) 일부 시스템에서 I/O 스토어는 모든 CPU 에 일관되게 순서 맞춰지지 않는데,
+     따라서 _모든_ 일반적인 드라이버들에 락이 사용되어야만 하고 이 크리티컬
+     섹션을 빠져나오기 전에 mmiowb() 가 꼭 호출되어야 합니다.
+
+ (2) 만약 액세스 함수들이 완화된 메모리 액세스 속성을 갖는 I/O 메모리 윈도우를
+     사용한다면, 순서를 강제하기 위해선 _mandatory_ 메모리 배리어가 필요합니다.
+
+더 많은 정보를 위해선 Documentation/DocBook/deviceiobook.tmpl 을 참고하십시오.
+
+
+인터럽트
+--------
+
+드라이버는 자신의 인터럽트 서비스 루틴에 의해 인터럽트 당할 수 있기 때문에
+드라이버의 이 두 부분은 서로의 디바이스 제어 또는 액세스 부분과 상호 간섭할 수
+있습니다.
+
+스스로에게 인터럽트 당하는 걸 불가능하게 하고, 드라이버의 크리티컬한
+오퍼레이션들을 모두 인터럽트가 불가능하게 된 영역에 집어넣거나 하는 방법 (락의
+한 형태) 으로 이런 상호 간섭을 - 최소한 부분적으로라도 - 줄일 수 있습니다.
+드라이버의 인터럽트 루틴이 실행 중인 동안, 해당 드라이버의 코어는 같은 CPU 에서
+수행되지 않을 것이며, 현재의 인터럽트가 처리되는 중에는 또다시 인터럽트가
+일어나지 못하도록 되어 있으니 인터럽트 핸들러는 그에 대해서는 락을 잡지 않아도
+됩니다.
+
+하지만, 어드레스 레지스터와 데이터 레지스터를 갖는 이더넷 카드를 다루는
+드라이버를 생각해 봅시다.  만약 이 드라이버의 코어가 인터럽트를 비활성화시킨
+채로 이더넷 카드와 대화하고 드라이버의 인터럽트 핸들러가 호출되었다면:
+
+	LOCAL IRQ DISABLE
+	writew(ADDR, 3);
+	writew(DATA, y);
+	LOCAL IRQ ENABLE
+	
+	writew(ADDR, 4);
+	q = readw(DATA);
+	
+
+만약 순서 규칙이 충분히 완화되어 있다면 데이터 레지스터에의 스토어는 어드레스
+레지스터에 두번째로 행해지는 스토어 뒤에 일어날 수도 있습니다:
+
+	STORE *ADDR = 3, STORE *ADDR = 4, STORE *DATA = y, q = LOAD *DATA
+
+
+만약 순서 규칙이 충분히 완화되어 있고 묵시적으로든 명시적으로든 배리어가
+사용되지 않았다면 인터럽트 비활성화 섹션에서 일어난 액세스가 바깥으로 새어서
+인터럽트 내에서 일어난 액세스와 섞일 수 있다고 - 그리고 그 반대도 - 가정해야만
+합니다.
+
+그런 영역 안에서 일어나는 I/O 액세스들은 엄격한 순서 규칙의 I/O 레지스터에
+묵시적 I/O 배리어를 형성하는 동기적 (synchronous) 로드 오퍼레이션을 포함하기
+때문에 일반적으로는 이런게 문제가 되지 않습니다.  만약 이걸로는 충분치 않다면
+mmiowb() 가 명시적으로 사용될 필요가 있습니다.
+
+
+하나의 인터럽트 루틴과 별도의 CPU 에서 수행중이며 서로 통신을 하는 두 루틴
+사이에도 비슷한 상황이 일어날 수 있습니다.  만약 그런 경우가 발생할 가능성이
+있다면, 순서를 보장하기 위해 인터럽트 비활성화 락이 사용되어져야만 합니다.
+
+
+======================
+커널 I/O 배리어의 효과
+======================
+
+I/O 메모리에 액세스할 때, 드라이버는 적절한 액세스 함수를 사용해야 합니다:
+
+ (*) inX(), outX():
+
+     이것들은 메모리 공간보다는 I/O 공간에 이야기를 하려는 의도로
+     만들어졌습니다만, 그건 기본적으로 CPU 마다 다른 컨셉입니다.  i386 과
+     x86_64 프로세서들은 특별한 I/O 공간 액세스 사이클과 명령어를 실제로 가지고
+     있지만, 다른 많은 CPU 들에는 그런 컨셉이 존재하지 않습니다.
+
+     다른 것들 중에서도 PCI 버스가 I/O 공간 컨셉을 정의하는데, 이는 - i386 과
+     x86_64 같은 CPU 에서 - CPU 의 I/O 공간 컨셉으로 쉽게 매치됩니다.  하지만,
+     대체할 I/O 공간이 없는 CPU 에서는 CPU 의 메모리 맵의 가상 I/O 공간으로
+     매핑될 수도 있습니다.
+
+     이 공간으로의 액세스는 (i386 등에서는) 완전하게 동기화 됩니다만, 중간의
+     (PCI 호스트 브리지와 같은) 브리지들은 이를 완전히 보장하진 않을수도
+     있습니다.
+
+     이것들의 상호간의 순서는 완전하게 보장됩니다.
+
+     다른 타입의 메모리 오퍼레이션, I/O 오퍼레이션에 대한 순서는 완전하게
+     보장되지는 않습니다.
+
+ (*) readX(), writeX():
+
+     이것들이 수행 요청되는 CPU 에서 서로에게 완전히 순서가 맞춰지고 독립적으로
+     수행되는지에 대한 보장 여부는 이들이 액세스 하는 메모리 윈도우에 정의된
+     특성에 의해 결정됩니다.  예를 들어, 최신의 i386 아키텍쳐 머신에서는 MTRR
+     레지스터로 이 특성이 조정됩니다.
+
+     일반적으로는, 프리페치 (prefetch) 가능한 디바이스를 액세스 하는게
+     아니라면, 이것들은 완전히 순서가 맞춰지고 결합되지 않게 보장될 겁니다.
+
+     하지만, (PCI 브리지와 같은) 중간의 하드웨어는 자신이 원한다면 집행을
+     연기시킬 수 있습니다; 스토어 명령을 실제로 하드웨어로 내려보내기(flush)
+     위해서는 같은 위치로부터 로드를 하는 방법이 있습니다만[*], PCI 의 경우는
+     같은 디바이스나 환경 구성 영역에서의 로드만으로도 충분할 겁니다.
+
+     [*] 주의! 쓰여진 것과 같은 위치로부터의 로드를 시도하는 것은 오동작을
+	 일으킬 수도 있습니다 - 예로 16650 Rx/Tx 시리얼 레지스터를 생각해
+	 보세요.
+
+     프리페치 가능한 I/O 메모리가 사용되면, 스토어 명령들이 순서를 지키도록
+     하기 위해 mmiowb() 배리어가 필요할 수 있습니다.
+
+     PCI 트랜잭션 사이의 상호작용에 대해 더 많은 정보를 위해선 PCI 명세서를
+     참고하시기 바랍니다.
+
+ (*) readX_relaxed(), writeX_relaxed()
+
+     이것들은 readX() 와 writeX() 랑 비슷하지만, 더 완화된 메모리 순서 보장을
+     제공합니다.  구체적으로, 이것들은 일반적 메모리 액세스 (예: DMA 버퍼) 에도
+     LOCK 이나 UNLOCK 오퍼레이션들에도 순서를 보장하지 않습니다.  LOCK 이나
+     UNLOCK 오퍼레이션들에 맞춰지는 순서가 필요하다면, mmiowb() 배리어가 사용될
+     수 있습니다.  같은 주변 장치에의 완화된 액세스끼리는 순서가 지켜짐을 알아
+     두시기 바랍니다.
+
+ (*) ioreadX(), iowriteX()
+
+     이것들은 inX()/outX() 나 readX()/writeX() 처럼 실제로 수행하는 액세스의
+     종류에 따라 적절하게 수행될 것입니다.
+
+
+===================================
+가정되는 가장 완화된 실행 순서 모델
+===================================
+
+컨셉적으로 CPU 는 주어진 프로그램에 대해 프로그램 그 자체에는 인과성 (program
+causality) 을 지키는 것처럼 보이게 하지만 일반적으로는 순서를 거의 지켜주지
+않는다고 가정되어야만 합니다.  (i386 이나 x86_64 같은) 일부 CPU 들은 코드
+재배치에 (powerpc 나 frv 와 같은) 다른 것들에 비해 강한 제약을 갖지만, 아키텍쳐
+종속적 코드 이외의 코드에서는 순서에 대한 제약이 가장 완화된 경우 (DEC Alpha)
+를 가정해야 합니다.
+
+이 말은, CPU 에게 주어지는 인스트럭션 스트림 내의 한 인스트럭션이 앞의
+인스트럭션에 종속적이라면 앞의 인스트럭션은 뒤의 종속적 인스트럭션이 실행되기
+전에 완료[*]될 수 있어야 한다는 제약 (달리 말해서, 인과성이 지켜지는 것으로
+보이게 함) 외에는 자신이 원하는 순서대로 - 심지어 병렬적으로도 - 그 스트림을
+실행할 수 있음을 의미합니다
+
+ [*] 일부 인스트럭션은 하나 이상의 영향 - 조건 코드를 바꾼다던지, 레지스터나
+     메모리를 바꾼다던지 - 을 만들어내며, 다른 인스트럭션은 다른 효과에
+     종속적일 수 있습니다.
+
+CPU 는 최종적으로 아무 효과도 만들지 않는 인스트럭션 시퀀스는 없애버릴 수도
+있습니다.  예를 들어, 만약 두개의 연속되는 인스트럭션이 둘 다 같은 레지스터에
+직접적인 값 (immediate value) 을 집어넣는다면, 첫번째 인스트럭션은 버려질 수도
+있습니다.
+
+
+비슷하게, 컴파일러 역시 프로그램의 인과성만 지켜준다면 인스트럭션 스트림을
+자신이 보기에 올바르다 생각되는대로 재배치 할 수 있습니다.
+
+
+===============
+CPU 캐시의 영향
+===============
+
+캐시된 메모리 오퍼레이션들이 시스템 전체에 어떻게 인지되는지는 CPU 와 메모리
+사이에 존재하는 캐시들, 그리고 시스템 상태의 일관성을 관리하는 메모리 일관성
+시스템에 상당 부분 영향을 받습니다.
+
+한 CPU 가 시스템의 다른 부분들과 캐시를 통해 상호작용한다면, 메모리 시스템은
+CPU 의 캐시들을 포함해야 하며, CPU 와 CPU 자신의 캐시 사이에서의 동작을 위한
+메모리 배리어를 가져야 합니다. (메모리 배리어는 논리적으로는 다음 그림의
+점선에서 동작합니다):
+
+	    <--- CPU --->         :       <----------- Memory ----------->
+	                          :
+	+--------+    +--------+  :   +--------+    +-----------+
+	|        |    |        |  :   |        |    |           |    +--------+
+	|  CPU   |    | Memory |  :   | CPU    |    |           |    |        |
+	|  Core  |--->| Access |----->| Cache  |<-->|           |    |        |
+	|        |    | Queue  |  :   |        |    |           |--->| Memory |
+	|        |    |        |  :   |        |    |           |    |        |
+	+--------+    +--------+  :   +--------+    |           |    |        |
+	                          :                 | Cache     |    +--------+
+	                          :                 | Coherency |
+	                          :                 | Mechanism |    +--------+
+	+--------+    +--------+  :   +--------+    |           |    |	      |
+	|        |    |        |  :   |        |    |           |    |        |
+	|  CPU   |    | Memory |  :   | CPU    |    |           |--->| Device |
+	|  Core  |--->| Access |----->| Cache  |<-->|           |    |        |
+	|        |    | Queue  |  :   |        |    |           |    |        |
+	|        |    |        |  :   |        |    |           |    +--------+
+	+--------+    +--------+  :   +--------+    +-----------+
+	                          :
+	                          :
+
+특정 로드나 스토어는 해당 오퍼레이션을 요청한 CPU 의 캐시 내에서 동작을 완료할
+수도 있기 때문에 해당 CPU 의 바깥에는 보이지 않을 수 있지만, 다른 CPU 가 관심을
+갖는다면 캐시 일관성 메커니즘이 해당 캐시라인을 해당 CPU 에게 전달하고, 해당
+메모리 영역에 대한 오퍼레이션이 발생할 때마다 그 영향을 전파시키기 때문에, 해당
+오퍼레이션은 메모리에 실제로 액세스를 한것처럼 나타날 것입니다.
+
+CPU 코어는 프로그램의 인과성이 유지된다고만 여겨진다면 인스트럭션들을 어떤
+순서로든 재배치해서 수행할 수 있습니다.  일부 인스트럭션들은 로드나 스토어
+오퍼레이션을 만드는데 이 오퍼레이션들은 이후 수행될 메모리 액세스 큐에 들어가게
+됩니다.  코어는 이 오퍼레이션들을 해당 큐에 어떤 순서로든 원하는대로 넣을 수
+있고, 다른 인스트럭션의 완료를 기다리도록 강제되기 전까지는 수행을 계속합니다.
+
+메모리 배리어가 하는 일은 CPU 쪽에서 메모리 쪽으로 넘어가는 액세스들의 순서,
+그리고 그 액세스의 결과가 시스템의 다른 관찰자들에게 인지되는 순서를 제어하는
+것입니다.
+
+[!] CPU 들은 항상 그들 자신의 로드와 스토어는 프로그램 순서대로 일어난 것으로
+보기 때문에, 주어진 CPU 내에서는 메모리 배리어를 사용할 필요가 _없습니다_.
+
+[!] MMIO 나 다른 디바이스 액세스들은 캐시 시스템을 우회할 수도 있습니다.  우회
+여부는 디바이스가 액세스 되는 메모리 윈도우의 특성에 의해 결정될 수도 있고, CPU
+가 가지고 있을 수 있는 특수한 디바이스 통신 인스트럭션의 사용에 의해서 결정될
+수도 있습니다.
+
+
+캐시 일관성
+-----------
+
+하지만 삶은 앞에서 이야기한 것처럼 단순하지 않습니다: 캐시들은 일관적일 것으로
+기대되지만, 그 일관성이 순서에도 적용될 거라는 보장은 없습니다.  한 CPU 에서
+만들어진 변경 사항은 최종적으로는 시스템의 모든 CPU 에게 보여지게 되지만, 다른
+CPU 들에게도 같은 순서로 보이게 될 거라는 보장은 없다는 뜻입니다.
+
+
+두개의 CPU (1 & 2) 가 달려 있고, 각 CPU 에 두개의 데이터 캐시(CPU 1 은 A/B 를,
+CPU 2 는 C/D 를 갖습니다)가 병렬로 연결되어 있는 시스템을 다룬다고 생각해
+봅시다:
+
+	            :
+	            :                          +--------+
+	            :      +---------+         |        |
+	+--------+  : +--->| Cache A |<------->|        |
+	|        |  : |    +---------+         |        |
+	|  CPU 1 |<---+                        |        |
+	|        |  : |    +---------+         |        |
+	+--------+  : +--->| Cache B |<------->|        |
+	            :      +---------+         |        |
+	            :                          | Memory |
+	            :      +---------+         | System |
+	+--------+  : +--->| Cache C |<------->|        |
+	|        |  : |    +---------+         |        |
+	|  CPU 2 |<---+                        |        |
+	|        |  : |    +---------+         |        |
+	+--------+  : +--->| Cache D |<------->|        |
+	            :      +---------+         |        |
+	            :                          +--------+
+	            :
+
+이 시스템이 다음과 같은 특성을 갖는다 생각해 봅시다:
+
+ (*) 홀수번 캐시라인은 캐시 A, 캐시 C 또는 메모리에 위치할 수 있음;
+
+ (*) 짝수번 캐시라인은 캐시 B, 캐시 D 또는 메모리에 위치할 수 있음;
+
+ (*) CPU 코어가 한개의 캐시에 접근하는 동안, 다른 캐시는 - 더티 캐시라인을
+     메모리에 내리거나 추측성 로드를 하거나 하기 위해 - 시스템의 다른 부분에
+     액세스 하기 위해 버스를 사용할 수 있음;
+
+ (*) 각 캐시는 시스템의 나머지 부분들과 일관성을 맞추기 위해 해당 캐시에
+     적용되어야 할 오퍼레이션들의 큐를 가짐;
+
+ (*) 이 일관성 큐는 캐시에 이미 존재하는 라인에 가해지는 평범한 로드에 의해서는
+     비워지지 않는데, 큐의 오퍼레이션들이 이 로드의 결과에 영향을 끼칠 수 있다
+     할지라도 그러함.
+
+이제, 첫번째 CPU 에서 두개의 쓰기 오퍼레이션을 만드는데, 해당 CPU 의 캐시에
+요청된 순서로 오퍼레이션이 도달됨을 보장하기 위해 두 오퍼레이션 사이에 쓰기
+배리어를 사용하는 상황을 상상해 봅시다:
+
+	CPU 1		CPU 2		COMMENT
+	===============	===============	=======================================
+					u == 0, v == 1 and p == &u, q == &u
+	v = 2;
+	smp_wmb();			v 의 변경이 p 의 변경 전에 보일 것을
+					 분명히 함
+				v 는 이제 캐시 A 에 독점적으로 존재함
+	p = &v;
+				p 는 이제 캐시 B 에 독점적으로 존재함
+
+여기서의 쓰기 메모리 배리어는 CPU 1 의 캐시가 올바른 순서로 업데이트 된 것으로
+시스템의 다른 CPU 들이 인지하게 만듭니다.  하지만, 이제 두번째 CPU 가 그 값들을
+읽으려 하는 상황을 생각해 봅시다:
+
+	CPU 1		CPU 2		COMMENT
+	===============	===============	=======================================
+	...
+			q = p;
+			x = *q;
+
+위의 두개의 읽기 오퍼레이션은 예상된 순서로 일어나지 못할 수 있는데, 두번째 CPU
+의 한 캐시에 다른 캐시 이벤트가 발생해 v 를 담고 있는 캐시라인의 해당 캐시에의
+업데이트가 지연되는 사이, p 를 담고 있는 캐시라인은 두번째 CPU 의 다른 캐시에
+업데이트 되어버렸을 수 있기 때문입니다.
+
+	CPU 1		CPU 2		COMMENT
+	===============	===============	=======================================
+					u == 0, v == 1 and p == &u, q == &u
+	v = 2;
+	smp_wmb();
+		
+			
+	p = &v;		q = p;
+			
+		
+			
+			x = *q;
+				캐시에 업데이트 되기 전의 v 를 읽음
+			
+			
+
+기본적으로, 두개의 캐시라인 모두 CPU 2 에 최종적으로는 업데이트 될 것이지만,
+별도의 개입 없이는, 업데이트의 순서가 CPU 1 에서 만들어진 순서와 동일할
+것이라는 보장이 없습니다.
+
+
+여기에 개입하기 위해선, 데이터 의존성 배리어나 읽기 배리어를 로드 오퍼레이션들
+사이에 넣어야 합니다.  이렇게 함으로써 캐시가 다음 요청을 처리하기 전에 일관성
+큐를 처리하도록 강제하게 됩니다.
+
+	CPU 1		CPU 2		COMMENT
+	===============	===============	=======================================
+					u == 0, v == 1 and p == &u, q == &u
+	v = 2;
+	smp_wmb();
+		
+			
+	p = &v;		q = p;
+			
+		
+			
+			smp_read_barrier_depends()
+			
+			
+			x = *q;
+				캐시에 업데이트 된 v 를 읽음
+
+
+이런 부류의 문제는 DEC Alpha 계열 프로세서들에서 발견될 수 있는데, 이들은
+데이터 버스를 좀 더 잘 사용해 성능을 개선할 수 있는, 분할된 캐시를 가지고 있기
+때문입니다.  대부분의 CPU 는 하나의 읽기 오퍼레이션의 메모리 액세스가 다른 읽기
+오퍼레이션에 의존적이라면 데이터 의존성 배리어를 내포시킵니다만, 모두가 그런건
+아니기 때문에 이점에 의존해선 안됩니다.
+
+다른 CPU 들도 분할된 캐시를 가지고 있을 수 있지만, 그런 CPU 들은 평범한 메모리
+액세스를 위해서도 이 분할된 캐시들 사이의 조정을 해야만 합니다.  Alpha 는 가장
+약한 메모리 순서 시맨틱 (semantic) 을 선택함으로써 메모리 배리어가 명시적으로
+사용되지 않았을 때에는 그런 조정이 필요하지 않게 했습니다.
+
+
+캐시 일관성 VS DMA
+------------------
+
+모든 시스템이 DMA 를 하는 디바이스에 대해서까지 캐시 일관성을 유지하지는
+않습니다.  그런 경우, DMA 를 시도하는 디바이스는 RAM 으로부터 잘못된 데이터를
+읽을 수 있는데, 더티 캐시 라인이 CPU 의 캐시에 머무르고 있고, 바뀐 값이 아직
+RAM 에 써지지 않았을 수 있기 때문입니다.  이 문제를 해결하기 위해선, 커널의
+적절한 부분에서 각 CPU 캐시의 문제되는 비트들을 플러시 (flush) 시켜야만 합니다
+(그리고 그것들을 무효화 - invalidation - 시킬 수도 있겠죠).
+
+또한, 디바이스에 의해 RAM 에 DMA 로 쓰여진 값은 디바이스가 쓰기를 완료한 후에
+CPU 의 캐시에서 RAM 으로 쓰여지는 더티 캐시 라인에 의해 덮어써질 수도 있고, CPU
+의 캐시에 존재하는 캐시 라인이 해당 캐시에서 삭제되고 다시 값을 읽어들이기
+전까지는 RAM 이 업데이트 되었다는 사실 자체가 숨겨져 버릴 수도 있습니다.  이
+문제를 해결하기 위해선, 커널의 적절한 부분에서 각 CPU 의 캐시 안의 문제가 되는
+비트들을 무효화 시켜야 합니다.
+
+캐시 관리에 대한 더 많은 정보를 위해선 Documentation/cachetlb.txt 를
+참고하세요.
+
+
+캐시 일관성 VS MMIO
+-------------------
+
+Memory mapped I/O 는 일반적으로 CPU 의 메모리 공간 내의 한 윈도우의 특정 부분
+내의 메모리 지역에 이루어지는데, 이 윈도우는 일반적인, RAM 으로 향하는
+윈도우와는 다른 특성을 갖습니다.
+
+그런 특성 가운데 하나는, 일반적으로 그런 액세스는 캐시를 완전히 우회하고
+디바이스 버스로 곧바로 향한다는 것입니다.  이 말은 MMIO 액세스는 먼저
+시작되어서 캐시에서 완료된 메모리 액세스를 추월할 수 있다는 뜻입니다.  이런
+경우엔 메모리 배리어만으로는 충분치 않고, 만약 캐시된 메모리 쓰기 오퍼레이션과
+MMIO 액세스가 어떤 방식으로든 의존적이라면 해당 캐시는 두 오퍼레이션 사이에
+비워져(flush)야만 합니다.
+
+
+======================
+CPU 들이 저지르는 일들
+======================
+
+프로그래머는 CPU 가 메모리 오퍼레이션들을 정확히 요청한대로 수행해 줄 것이라고
+생각하는데, 예를 들어 다음과 같은 코드를 CPU 에게 넘긴다면:
+
+	a = READ_ONCE(*A);
+	WRITE_ONCE(*B, b);
+	c = READ_ONCE(*C);
+	d = READ_ONCE(*D);
+	WRITE_ONCE(*E, e);
+
+CPU 는 다음 인스트럭션을 처리하기 전에 현재의 인스트럭션을 위한 메모리
+오퍼레이션을 완료할 것이라 생각하고, 따라서 시스템 외부에서 관찰하기에도 정해진
+순서대로 오퍼레이션이 수행될 것으로 예상합니다:
+
+	LOAD *A, STORE *B, LOAD *C, LOAD *D, STORE *E.
+
+
+당연하지만, 실제로는 훨씬 엉망입니다.  많은 CPU 와 컴파일러에서 앞의 가정은
+성립하지 못하는데 그 이유는 다음과 같습니다:
+
+ (*) 로드 오퍼레이션들은 실행을 계속 해나가기 위해 곧바로 완료될 필요가 있는
+     경우가 많은 반면, 스토어 오퍼레이션들은 종종 별다른 문제 없이 유예될 수
+     있습니다;
+
+ (*) 로드 오퍼레이션들은 예측적으로 수행될 수 있으며, 필요없는 로드였다고
+     증명된 예측적 로드의 결과는 버려집니다;
+
+ (*) 로드 오퍼레이션들은 예측적으로 수행될 수 있으므로, 예상된 이벤트의
+     시퀀스와 다른 시간에 로드가 이뤄질 수 있습니다;
+
+ (*) 메모리 액세스 순서는 CPU 버스와 캐시를 좀 더 잘 사용할 수 있도록 재배치
+     될 수 있습니다;
+
+ (*) 로드와 스토어는 인접한 위치에의 액세스들을 일괄적으로 처리할 수 있는
+     메모리나 I/O 하드웨어 (메모리와 PCI 디바이스 둘 다 이게 가능할 수
+     있습니다) 에 대해 요청되는 경우, 개별 오퍼레이션을 위한 트랜잭션 설정
+     비용을 아끼기 위해 조합되어 실행될 수 있습니다; 그리고
+
+ (*) 해당 CPU 의 데이터 캐시가 순서에 영향을 끼칠 수도 있고, 캐시 일관성
+     메커니즘이 - 스토어가 실제로 캐시에 도달한다면 - 이 문제를 완화시킬 수는
+     있지만 이 일관성 관리가 다른 CPU 들에도 같은 순서로 전달된다는 보장은
+     없습니다.
+
+따라서, 앞의 코드에 대해 다른 CPU 가 보는 결과는 다음과 같을 수 있습니다:
+
+	LOAD *A, ..., LOAD {*C,*D}, STORE *E, STORE *B
+
+	("LOAD {*C,*D}" 는 조합된 로드입니다)
+
+
+하지만, CPU 는 스스로는 일관적일 것을 보장합니다: CPU _자신_ 의 액세스들은
+자신에게는 메모리 배리어가 없음에도 불구하고 정확히 순서 세워진 것으로 보여질
+것입니다.  예를 들어 다음의 코드가 주어졌다면:
+
+	U = READ_ONCE(*A);
+	WRITE_ONCE(*A, V);
+	WRITE_ONCE(*A, W);
+	X = READ_ONCE(*A);
+	WRITE_ONCE(*A, Y);
+	Z = READ_ONCE(*A);
+
+그리고 외부의 영향에 의한 간섭이 없다고 가정하면, 최종 결과는 다음과 같이
+나타날 것이라고 예상될 수 있습니다:
+
+	U == *A 의 최초 값
+	X == W
+	Z == Y
+	*A == Y
+
+앞의 코드는 CPU 가 다음의 메모리 액세스 시퀀스를 만들도록 할겁니다:
+
+	U=LOAD *A, STORE *A=V, STORE *A=W, X=LOAD *A, STORE *A=Y, Z=LOAD *A
+
+하지만, 별다른 개입이 없고 프로그램의 시야에 이 세상이 여전히 일관적이라고
+보인다는 보장만 지켜진다면 이 시퀀스는 어떤 조합으로든 재구성될 수 있으며, 각
+액세스들은 합쳐지거나 버려질 수 있습니다.  일부 아키텍쳐에서 CPU 는 같은 위치에
+대한 연속적인 로드 오퍼레이션들을 재배치 할 수 있기 때문에 앞의 예에서의
+READ_ONCE() 와 WRITE_ONCE() 는 반드시 존재해야 함을 알아두세요.  그런 종류의
+아키텍쳐에서 READ_ONCE() 와 WRITE_ONCE() 는 이 문제를 막기 위해 필요한 일을
+뭐가 됐든지 하게 되는데, 예를 들어 Itanium 에서는 READ_ONCE() 와 WRITE_ONCE()
+가 사용하는 volatile 캐스팅은 GCC 가 그런 재배치를 방지하는 특수 인스트럭션인
+ld.acq 와 stl.rel 인스트럭션을 각각 만들어 내도록 합니다.
+
+컴파일러 역시 이 시퀀스의 액세스들을 CPU 가 보기도 전에 합치거나 버리거나 뒤로
+미뤄버릴 수 있습니다.
+
+예를 들어:
+
+	*A = V;
+	*A = W;
+
+는 다음과 같이 변형될 수 있습니다:
+
+	*A = W;
+
+따라서, 쓰기 배리어나 WRITE_ONCE() 가 없다면 *A 로의 V 값의 저장의 효과는
+사라진다고 가정될 수 있습니다.  비슷하게:
+
+	*A = Y;
+	Z = *A;
+
+는, 메모리 배리어나 READ_ONCE() 와 WRITE_ONCE() 없이는 다음과 같이 변형될 수
+있습니다:
+
+	*A = Y;
+	Z = Y;
+
+그리고 이 LOAD 오퍼레이션은 CPU 바깥에는 아예 보이지 않습니다.
+
+
+그리고, ALPHA 가 있다
+---------------------
+
+DEC Alpha CPU 는 가장 완화된 메모리 순서의 CPU 중 하나입니다.  뿐만 아니라,
+Alpha CPU 의 일부 버전은 분할된 데이터 캐시를 가지고 있어서, 의미적으로
+관계되어 있는 두개의 캐시 라인이 서로 다른 시간에 업데이트 되는게 가능합니다.
+이게 데이터 의존성 배리어가 정말 필요해지는 부분인데, 데이터 의존성 배리어는
+메모리 일관성 시스템과 함께 두개의 캐시를 동기화 시켜서, 포인터 변경과 새로운
+데이터의 발견을 올바른 순서로 일어나게 하기 때문입니다.
+
+리눅스 커널의 메모리 배리어 모델은 Alpha 에 기초해서 정의되었습니다.
+
+위의 "캐시 일관성" 서브섹션을 참고하세요.
+
+
+가상 머신 게스트
+----------------
+
+가상 머신에서 동작하는 게스트들은 게스트 자체는 SMP 지원 없이 컴파일 되었다
+해도 SMP 영향을 받을 수 있습니다.  이건 UP 커널을 사용하면서 SMP 호스트와
+결부되어 발생하는 부작용입니다.  이 경우에는 mandatory 배리어를 사용해서 문제를
+해결할 수 있겠지만 그런 해결은 대부분의 경우 최적의 해결책이 아닙니다.
+
+이 문제를 완벽하게 해결하기 위해, 로우 레벨의 virt_mb() 등의 매크로를 사용할 수
+있습니다. 이것들은 SMP 가 활성화 되어 있다면 smp_mb() 등과 동일한 효과를
+갖습니다만, SMP 와 SMP 아닌 시스템 모두에 대해 동일한 코드를 만들어냅니다.
+예를 들어, 가상 머신 게스트들은 (SMP 일 수 있는) 호스트와 동기화를 할 때에는
+smp_mb() 가 아니라 virt_mb() 를 사용해야 합니다.
+
+이것들은 smp_mb() 류의 것들과 모든 부분에서 동일하며, 특히, MMIO 의 영향에
+대해서는 간여하지 않습니다: MMIO 의 영향을 제어하려면, mandatory 배리어를
+사용하시기 바랍니다.
+
+
+=======
+사용 예
+=======
+
+순환식 버퍼
+-----------
+
+메모리 배리어는 순환식 버퍼를 생성자(producer)와 소비자(consumer) 사이의
+동기화에 락을 사용하지 않고 구현하는데에 사용될 수 있습니다.  더 자세한 내용을
+위해선 다음을 참고하세요:
+
+	Documentation/circular-buffers.txt
+
+
+=========
+참고 문헌
+=========
+
+Alpha AXP Architecture Reference Manual, Second Edition (Sites & Witek,
+Digital Press)
+	Chapter 5.2: Physical Address Space Characteristics
+	Chapter 5.4: Caches and Write Buffers
+	Chapter 5.5: Data Sharing
+	Chapter 5.6: Read/Write Ordering
+
+AMD64 Architecture Programmer's Manual Volume 2: System Programming
+	Chapter 7.1: Memory-Access Ordering
+	Chapter 7.4: Buffering and Combining Memory Writes
+
+IA-32 Intel Architecture Software Developer's Manual, Volume 3:
+System Programming Guide
+	Chapter 7.1: Locked Atomic Operations
+	Chapter 7.2: Memory Ordering
+	Chapter 7.4: Serializing Instructions
+
+The SPARC Architecture Manual, Version 9
+	Chapter 8: Memory Models
+	Appendix D: Formal Specification of the Memory Models
+	Appendix J: Programming with the Memory Models
+
+UltraSPARC Programmer Reference Manual
+	Chapter 5: Memory Accesses and Cacheability
+	Chapter 15: Sparc-V9 Memory Models
+
+UltraSPARC III Cu User's Manual
+	Chapter 9: Memory Models
+
+UltraSPARC IIIi Processor User's Manual
+	Chapter 8: Memory Models
+
+UltraSPARC Architecture 2005
+	Chapter 9: Memory
+	Appendix D: Formal Specifications of the Memory Models
+
+UltraSPARC T1 Supplement to the UltraSPARC Architecture 2005
+	Chapter 8: Memory Models
+	Appendix F: Caches and Cache Coherency
+
+Solaris Internals, Core Kernel Architecture, p63-68:
+	Chapter 3.3: Hardware Considerations for Locks and
+			Synchronization
+
+Unix Systems for Modern Architectures, Symmetric Multiprocessing and Caching
+for Kernel Programmers:
+	Chapter 13: Other Memory Models
+
+Intel Itanium Architecture Software Developer's Manual: Volume 1:
+	Section 2.6: Speculation
+	Section 4.4: Memory Access
diff --git a/Documentation/translations/ko_KR/stable_api_nonsense.txt b/Documentation/translations/ko_KR/stable_api_nonsense.txt
new file mode 100644
index 000000000000..4d93af1efd61
--- /dev/null
+++ b/Documentation/translations/ko_KR/stable_api_nonsense.txt
@@ -0,0 +1,195 @@
+NOTE:
+This is a version of Documentation/process/stable-api-nonsense.rst translated
+into korean
+This document is maintained by Minchan Kim 
+If you find any difference between this document and the original file or
+a problem with the translation, please contact the maintainer of this file.
+
+Please also note that the purpose of this file is to be easier to
+read for non English (read: korean) speakers and is not intended as
+a fork. So if you have any comments or updates for this file please
+try to update the original English file first.
+
+==================================
+이 문서는
+Documentation/process/stable-api-nonsense.rst
+의 한글 번역입니다.
+
+역자： 김민찬 
+감수： 이제이미 
+==================================
+
+리눅스 커널 드라이버 인터페이스
+(여러분들의 모든 질문에 대한 답 그리고 다른 몇가지)
+
+Greg Kroah-Hartman 
+
+이 문서는 리눅스가 왜 바이너리 커널 인터페이스를 갖지 않는지, 왜 변하지
+않는(stable) 커널 인터페이스를 갖지 않는지를 설명하기 위해 쓰여졌다.
+이 문서는 커널과 유저공간 사이의 인터페이스가 아니라 커널 내부의
+인터페이스들을 설명하고 있다는 것을 유념하라. 커널과 유저공간 사이의
+인터페이스는 응용프로그램이 사용하는 syscall 인터페이스이다. 그 인터페이스는
+오랫동안 거의 변하지 않았고 앞으로도 변하지 않을 것이다. 나는 pre 0.9에서
+만들어졌지만 최신의 2.6 커널 배포에서도 잘 동작하는 프로그램을 가지고
+있다. 이 인터페이스는 사용자와 응용프로그램 개발자들이 변하지 않을 것이라고
+여길수 있는 것이다.
+
+
+초록
+----
+여러분은 변하지 않는 커널 인터페이스를 원한다고 생각하지만 실제로는
+그렇지 않으며 심지어는 그것을 알아채지 못한다. 여러분이 원하는 것은
+안정되게 실행되는 드라이버이며 드라이버가 메인 커널 트리에 있을 때
+그런 안정적인 드라이버를 얻을 수 있게 된다. 또한 여러분의 드라이버가
+메인 커널 트리에 있다면 다른 많은 좋은 이점들을 얻게 된다. 그러한 것들이
+리눅스를 강건하고, 안정적이며, 성숙한 운영체제로 만들어 놓음으로써
+여러분들로 하여금 바로 리눅스를 사용하게 만드는 이유이다.
+
+
+소개
+----
+
+커널 내부의 인터페이스가 바뀌는 것을 걱정하며 커널 드라이버를 작성하고
+싶어하는 사람은 정말 이상한 사람이다. 세상의 대다수의 사람들은 이 인터페이스를
+보지못할 것이며 전혀 걱정하지도 않는다.
+
+먼저, 나는 closed 소스, hidden 소스, binary blobs, 소스 wrappers, 또는 GPL로
+배포되었지만 소스 코드를 갖고 있지 않은 커널 드라이버들을 설명하는 어떤 다른
+용어들에 관한 어떤 법적인 문제에 관해서는 언급하지 않을 것이다. 어떤 법적인
+질문들을 가지고 있다면 변호사와 연락하라. 나는 프로그래머이므로 여기서 기술적인
+문제들만을 설명하려고 한다. (법적인 문제를 경시하는 것은 아니다. 그런 문제들은
+엄연히 현실에 있고 여러분들은 항상 그 문제들을 인식하고 있을 필요는 있다.)
+
+자, 두가지의 주요 주제가 있다. 바이너리 커널 인터페이스들과 변하지 않는
+커널 소스 인터페이들. 그것들은 서로 의존성을 가지고 있지만 바이너리
+문제를 먼저 풀고 넘어갈 것이다.
+
+
+
+바이너리 커널 인터페이스
+------------------------
+우리가 변하지 않는 커널 소스 인터페이스를 가지고 있다고 가정하자. 그러면
+바이너리 인터페이스 또한 자연적으로 변하지 않을까? 틀렸다. 리눅스 커널에
+관한 다음 사실들을 생각해보라.
+   - 여러분들이 사용하는 C 컴파일러의 버젼에 따라 다른 커널 자료 구조들은
+     다른 alignmnet들을 갖게 될것이고 다른 방법으로(함수들을 inline으로
+     했느냐, 아니냐) 다른 함수들을 포함하는 것도 가능한다. 중요한 것은
+     개별적인 함수 구성이 아니라 자료 구조 패딩이 달라진다는 점이다.
+   - 여러분이 선택한 커널 빌드 옵션에 따라서 커널은 다양한 것들을 가정할
+     수 있다.
+      - 다른 구조체들은 다른 필드들을 포함할 수 있다.
+      - 몇몇 함수들은 전혀 구현되지 않을 수도 있다(즉, 몇몇 lock들은
+        non-SMP 빌드에서는 사라져 버릴수도 있다).
+      - 커널내에 메모리는 build optoin들에 따라 다른 방법으로 align될수
+        있다.
+      - 리눅스는 많은 다양한 프로세서 아키텍쳐에서 실행된다. 한 아키텍쳐의
+        바이너리 드라이버를 다른 아키텍쳐에서 정상적으로 실행시킬 방법은
+        없다.
+
+커널을 빌드했던 C 컴파일러와 정확하게 같은 것을 사용하고 정확하게 같은
+커널 구성(configuration)을 사용하여 여러분들의 모듈을 빌드하면 간단히
+많은 문제들을 해결할 수 있다. 이렇게 하는 것은 여러분들이 하나의 리눅스
+배포판의 하나의 배포 버젼을 위한 모듈만을 제공한다면 별일 아닐 것이다.
+그러나 각기 다른 리눅스 배포판마다 한번씩 빌드하는 수를 각 리눅스 배포판마다
+제공하는 다른 릴리즈의 수와 곱하게 되면 이번에는 각 릴리즈들의 다른 빌드
+옵션의 악몽과 마주하게  것이다. 또한 각 리눅스 배포판들은 다른 하드웨어
+종류에(다른 프로세서 타입과 다른 옵션들) 맞춰져 있는 많은 다른 커널들을
+배포한다. 그러므로 한번의 배포에서조차 여러분들의 모듈은 여러 버젼을
+만들 필요가 있다.
+
+나를 믿어라. 여러분들은 이러한 종류의 배포를 지원하려고 시도한다면 시간이
+지나면 미칠지경이 될 것이다. 난 이러한 것을 오래전에 아주 어렵게 배웠다...
+
+
+
+변하지않는 커널 소스 인터페이스들
+---------------------------------
+
+리눅스 커널 드라이버를 계속해서 메인 커널 트리에 반영하지 않고
+유지보수하려고 하는 사람들과 이 문제를 논의하게 되면 훨씬 더
+"논란의 여지가 많은" 주제가 될 것이다.
+
+리눅스 커널 개발은 끊임없이 빠른 속도로 이루어지고 있으며 결코
+느슨해진 적이 없다. 커널 개발자들이 현재 인터페이스들에서 버그를
+발견하거나 무엇인가 할 수 있는 더 좋은 방법을 찾게 되었다고 하자.
+그들이 발견한 것을 실행한다면 아마도 더 잘 동작하도록 현재 인터페이스들을
+수정하게 될 것이다. 그들이 그런 일을 하게되면 함수 이름들은 변하게 되고,
+구조체들은 늘어나거나 줄어들게 되고, 함수 파라미터들은 재작업될 것이다.
+이러한 일이 발생되면 커널 내에 이 인터페이스를 사용했던 인스턴스들이 동시에
+수정될 것이며 이러한 과정은 모든 것이 계속해서 올바르게 동작할 것이라는
+것을 보장한다.
+
+이러한 것의 한 예로써, 커널 내부의 USB 인터페이스들은 이 서브시스템이
+생긴 이후로 적어도 3번의 다른 재작업을 겪었다. 이 재작업들은 많은 다른
+문제들을 풀었다.
+   - 데이터 스트림들의 동기적인 모델에서 비동기적인 모델로의 변화. 이것은
+     많은 드라이버들의 복잡성을 줄이고 처리량을 향상시켜 현재는 거의 모든
+     USB 장치들의 거의 최대 속도로 실행되고 있다.
+   - USB 드라이버가 USB 코어로부터 데이터 패킷들을 할당받로록 한 변경으로
+     인해서 지금의 모든 드라이버들은 많은 문서화된 데드락을 수정하기 위하여
+     USB 코어에게 더 많은 정보를 제공해야만 한다.
+
+이것은 오랫동안 자신의 오래된 USB 인터페이스들을 유지해야 하는 closed 운영체제들과는
+완전히 반대되는 것이다. closed된 운영체제들은 새로운 개발자들에게 우연히 낡은
+인터페이스를 사용하게 할 기회를 주게되며, 적절하지 못한 방법으로 처리하게 되어
+운영체제의 안정성을 해치는 문제를 야기하게 된다.
+
+이 두가지의 예들 모두, 모든 개발자들은 꼭 이루어져야 하는 중요한 변화들이라고
+동의를 하였고 비교적 적은 고통으로 변경되어졌다. 리눅스가 변하지 않는 소스
+인터페이스를 고집한다면, 새로운 인터페이스가 만들어지게 되며 반면 기존의 오래된
+것들, 그리고 깨진 것들은 계속해서 유지되어야 하며 이러한 일들은 USB 개발자들에게
+또 다른 일거리를 주게 된다. 모든 리눅스 USB 개발자들에게 자신의 그들의 업무를
+마친 후 시간을 투자하여 아무 득도 없는 무료 봉사를 해달라고 하는 것은 가능성이
+희박한 일이다.
+
+보안 문제 역시 리눅스에게는 매우 중요하다. 보안 문제가 발견되면 그것은
+매우 짧은 시간 안에 수정된다. 보안 문제는 그 문제를 해결하기 위하여
+여러번 내부 커널 인터페이스들을 재작업하게 만들었다. 이러한 문제가
+발생하였을 때 그 인터페이스들을 사용하는 모든 드라이버들도 동시에
+수정되어 보안 문제가 앞으로 갑작스럽게 생기지는 않을 것이라는 것을
+보장한다. 내부 인터페이스들의 변경이 허락되지 않으면 이러한 종류의 보안
+문제를 수정하고 그것이 다시 발생하지 않을 것이라고 보장하는 것은 가능하지
+않을 것이다.
+
+커널 인터페이스들은 계속해서 정리되고 있다. 현재 인터페이스를 사용하는
+사람이 한명도 없다면 그것은 삭제된다. 이것은 커널이 가능한한 가장 작게
+유지되며 존재하는 모든 가능성이 있는 인터페이스들이 테스트된다는 것을
+보장한다(사용되지 않는 인터페이스들은 유효성 검증을 하기가 거의 불가능하다).
+
+
+무엇을 해야 하나
+---------------
+자, 여러분이 메인 커널 트리에 있지 않은 리눅스 커널 드라이버를 가지고
+있다면 여러분은 즉, 개발자는 무엇을 해야 하나? 모든 배포판마다 다른
+커널 버젼을 위한 바이너리 드라이버를 배포하는 것은 악몽이며 계속해서
+변하고 있는 커널 인터페이스들의 맞처 유지보수하려고 시도하는 것은 힘든
+일이다.
+
+간단하다. 여러분의 커널 드라이버를 메인 커널 트리에 반영하라(우리는 여기서
+GPL을 따르는 배포 드라이버에 관해 얘기하고 있다는 것을 상기하라. 여러분의
+코드가 이러한 분류에 해당되지 않는다면 행운을 빈다. 여러분 스스로 어떻게든
+해야만 한다). 여러분의 드라이버가 트리에 있게되면 커널 인터페이스가
+변경되더라도 가장 먼저 커널에 변경을 가했던 사람에 의해서 수정될 것이다.
+이것은 여러분의 드라이버가 여러분의 별다른 노력없이 항상 빌드가 가능하며
+동작하는 것을 보장한다.
+
+메인 커널 트리에 여러분의 드라이버를 반영하면 얻게 되는 장점들은 다음과 같다.
+   - 관리에 드는 비용(원래 개발자의)은 줄어줄면서 드라이버의 질은 향상될 것이다.
+   - 다른 개발자들이 여러분의 드라이버에 기능들을 추가 할 것이다.
+   - 다른 사람들은 여러분의 드라이버에 버그를 발견하고 수정할 것이다.
+   - 다른 사람들은 여러분의 드라이버의 개선점을 찾을 줄 것이다.
+   - 외부 인터페이스 변경으로 인해 여러분의 드라이버의 수정이 필요하다면 다른
+     사람들이 드라이버를 업데이트할 것이다.
+   - 여러분의 드라이버는 별다른 노력 없이 모든 리눅스 배포판에  자동적으로
+     추가될 것이다.
+
+리눅스는 다른 운영 체제보다 "쉽게 쓸수 있는(out of the box)" 많은 다른 장치들을
+지원하고 어떤 다른 운영 체제보다 다양한 아키텍쳐위에서 이러한 장치들을 지원하기 때문에
+이러한 증명된 개발 모델은 틀림없이 바로 가고 있는 것이다.
+
+
+
+------
+
+이 문서의 초안을 검토해주고 코멘트 해준 Randy Dunlap, Andrew Morton, David Brownell,
+Hanna Linder, Robert Love, 그리고 Nishanth Aravamudan에게 감사한다.
diff --git a/Documentation/translations/zh_CN/CodingStyle b/Documentation/translations/zh_CN/CodingStyle
new file mode 100644
index 000000000000..b02738042799
--- /dev/null
+++ b/Documentation/translations/zh_CN/CodingStyle
@@ -0,0 +1,813 @@
+Chinese translated version of Documentation/process/coding-style.rst
+
+If you have any comment or update to the content, please post to LKML directly.
+However, if you have problem communicating in English you can also ask the
+Chinese maintainer for help.  Contact the Chinese maintainer, if this
+translation is outdated or there is problem with translation.
+
+Chinese maintainer: Zhang Le 
+---------------------------------------------------------------------
+Documentation/process/coding-style.rst的中文翻译
+
+如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可
+以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。
+
+中文版维护者： 张乐 Zhang Le 
+中文版翻译者： 张乐 Zhang Le 
+中文版校译者： 王聪 Wang Cong 
+               wheelz 
+               管旭东 Xudong Guan 
+               Li Zefan 
+               Wang Chen 
+以下为正文
+---------------------------------------------------------------------
+
+		Linux内核代码风格
+
+这是一个简短的文档，描述了 linux 内核的首选代码风格。代码风格是因人而异的，而且我
+不愿意把自己的观点强加给任何人，但这就像我去做任何事情都必须遵循的原则那样，我也
+希望在绝大多数事上保持这种的态度。请（在写代码时）至少考虑一下这里的代码风格。
+
+首先，我建议你打印一份 GNU 代码规范，然后不要读。烧了它，这是一个具有重大象征性意义
+的动作。
+
+不管怎样，现在我们开始：
+
+
+		第一章：缩进
+
+制表符是 8 个字符，所以缩进也是 8 个字符。有些异端运动试图将缩进变为 4（甚至 2！）
+个字符深，这几乎相当于尝试将圆周率的值定义为 3。
+
+理由：缩进的全部意义就在于清楚的定义一个控制块起止于何处。尤其是当你盯着你的屏幕
+连续看了 20 小时之后，你将会发现大一点的缩进会使你更容易分辨缩进。
+
+现在，有些人会抱怨 8 个字符的缩进会使代码向右边移动的太远，在 80 个字符的终端屏幕上
+就很难读这样的代码。这个问题的答案是，如果你需要 3 级以上的缩进，不管用何种方式你
+的代码已经有问题了，应该修正你的程序。
+
+简而言之，8 个字符的缩进可以让代码更容易阅读，还有一个好处是当你的函数嵌套太深的
+时候可以给你警告。留心这个警告。
+
+在 switch 语句中消除多级缩进的首选的方式是让 “switch” 和从属于它的 “case” 标签
+对齐于同一列，而不要 “两次缩进” “case” 标签。比如：
+
+	switch (suffix) {
+	case 'G':
+	case 'g':
+		mem <<= 30;
+		break;
+	case 'M':
+	case 'm':
+		mem <<= 20;
+		break;
+	case 'K':
+	case 'k':
+		mem <<= 10;
+		/* fall through */
+	default:
+		break;
+	}
+
+不要把多个语句放在一行里，除非你有什么东西要隐藏：
+
+	if (condition) do_this;
+	  do_something_everytime;
+
+也不要在一行里放多个赋值语句。内核代码风格超级简单。就是避免可能导致别人误读的表
+达式。
+
+除了注释、文档和 Kconfig 之外，不要使用空格来缩进，前面的例子是例外，是有意为之。
+
+选用一个好的编辑器，不要在行尾留空格。
+
+
+		第二章：把长的行和字符串打散
+
+代码风格的意义就在于使用平常使用的工具来维持代码的可读性和可维护性。
+
+每一行的长度的限制是 80 列，我们强烈建议您遵守这个惯例。
+
+长于 80 列的语句要打散成有意义的片段。除非超过 80 列能显著增加可读性，并且不会隐藏
+信息。子片段要明显短于母片段，并明显靠右。这同样适用于有着很长参数列表的函数头。
+然而，绝对不要打散对用户可见的字符串，例如 printk 信息，因为这将导致无法 grep 这些
+信息。
+
+		第三章：大括号和空格的放置
+
+C语言风格中另外一个常见问题是大括号的放置。和缩进大小不同，选择或弃用某种放置策
+略并没有多少技术上的原因，不过首选的方式，就像 Kernighan 和 Ritchie 展示给我们的，
+是把起始大括号放在行尾，而把结束大括号放在行首，所以：
+
+	if (x is true) {
+		we do y
+	}
+
+这适用于所有的非函数语句块（if、switch、for、while、do）。比如：
+
+	switch (action) {
+	case KOBJ_ADD:
+		return "add";
+	case KOBJ_REMOVE:
+		return "remove";
+	case KOBJ_CHANGE:
+		return "change";
+	default:
+		return NULL;
+	}
+
+不过，有一个例外，那就是函数：函数的起始大括号放置于下一行的开头，所以：
+
+	int function(int x)
+	{
+		body of function
+	}
+
+全世界的异端可能会抱怨这个不一致性是……呃……不一致的，不过所有思维健全的人都知道
+(a) K&R 是 _正确的_，并且 (b) K&R 是正确的。此外，不管怎样函数都是特殊的（C
+函数是不能嵌套的）。
+
+注意结束大括号独自占据一行，除非它后面跟着同一个语句的剩余部分，也就是 do 语句中的
+“while” 或者 if 语句中的 “else”，像这样：
+
+	do {
+		body of do-loop
+	} while (condition);
+
+和
+
+	if (x == y) {
+		..
+	} else if (x > y) {
+		...
+	} else {
+		....
+	}
+
+理由：K&R。
+
+也请注意这种大括号的放置方式也能使空（或者差不多空的）行的数量最小化，同时不失可
+读性。因此，由于你的屏幕上的新行是不可再生资源（想想 25 行的终端屏幕），你将会有更
+多的空行来放置注释。
+
+当只有一个单独的语句的时候，不用加不必要的大括号。
+
+	if (condition)
+		action();
+
+和
+
+	if (condition)
+		do_this();
+	else
+		do_that();
+
+这并不适用于只有一个条件分支是单语句的情况；这时所有分支都要使用大括号：
+
+	if (condition) {
+		do_this();
+		do_that();
+	} else {
+		otherwise();
+	}
+
+		3.1：空格
+
+Linux 内核的空格使用方式（主要）取决于它是用于函数还是关键字。（大多数）关键字后
+要加一个空格。值得注意的例外是 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);
+
+不要在小括号里的表达式两侧加空格。这是一个反例：
+
+	s = sizeof( struct file );
+
+当声明指针类型或者返回指针类型的函数时，“*” 的首选使用方式是使之靠近变量名或者函
+数名，而不是靠近类型名。例子：
+
+	char *linux_banner;
+	unsigned long long memparse(char *ptr, char **retptr);
+	char *match_strdup(substring_t *s);
+
+在大多数二元和三元操作符两侧使用一个空格，例如下面所有这些操作符：
+
+	=  +  -  <  >  *  /  %  |  &  ^  <=  >=  ==  !=  ?  :
+
+但是一元操作符后不要加空格：
+
+	&  *  +  -  ~  !  sizeof  typeof  alignof  __attribute__  defined
+
+后缀自加和自减一元操作符前不加空格：
+
+	++  --
+
+前缀自加和自减一元操作符后不加空格：
+
+	++  --
+
+‘.’ 和 “->” 结构体成员操作符前后不加空格。
+
+不要在行尾留空白。有些可以自动缩进的编辑器会在新行的行首加入适量的空白，然后你
+就可以直接在那一行输入代码。不过假如你最后没有在那一行输入代码，有些编辑器就不
+会移除已经加入的空白，就像你故意留下一个只有空白的行。包含行尾空白的行就这样产
+生了。
+
+当git发现补丁包含了行尾空白的时候会警告你，并且可以应你的要求去掉行尾空白；不过
+如果你是正在打一系列补丁，这样做会导致后面的补丁失败，因为你改变了补丁的上下文。
+
+
+		第四章：命名
+
+C是一个简朴的语言，你的命名也应该这样。和 Modula-2 和 Pascal 程序员不同，C 程序员
+不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字。C 程序员会称那个变量
+为 “tmp”，这样写起来会更容易，而且至少不会令其难于理解。
+
+不过，虽然混用大小写的名字是不提倡使用的，但是全局变量还是需要一个具描述性的名字
+。称一个全局函数为 “foo” 是一个难以饶恕的错误。
+
+全局变量（只有当你真正需要它们的时候再用它）需要有一个具描述性的名字，就像全局函
+数。如果你有一个可以计算活动用户数量的函数，你应该叫它 “count_active_users()”
+或者类似的名字，你不应该叫它 “cntuser()”。
+
+在函数名中包含函数类型（所谓的匈牙利命名法）是脑子出了问题——编译器知道那些类型而
+且能够检查那些类型，这样做只能把程序员弄糊涂了。难怪微软总是制造出有问题的程序。
+
+本地变量名应该简短，而且能够表达相关的含义。如果你有一些随机的整数型的循环计数器
+，它应该被称为 “i”。叫它 “loop_counter” 并无益处，如果它没有被误解的可能的话。
+类似的，“tmp” 可以用来称呼任意类型的临时变量。
+
+如果你怕混淆了你的本地变量名，你就遇到另一个问题了，叫做函数增长荷尔蒙失衡综合症
+。请看第六章（函数）。
+
+
+		第五章：Typedef
+
+不要使用类似 “vps_t” 之类的东西。
+
+对结构体和指针使用 typedef 是一个错误。当你在代码里看到：
+
+	vps_t a;
+
+这代表什么意思呢？
+
+相反，如果是这样
+
+	struct virtual_container *a;
+
+你就知道 “a” 是什么了。
+
+很多人认为 typedef “能提高可读性”。实际不是这样的。它们只在下列情况下有用：
+
+ (a) 完全不透明的对象（这种情况下要主动使用 typedef 来隐藏这个对象实际上是什么）。
+
+     例如：“pte_t” 等不透明对象，你只能用合适的访问函数来访问它们。
+
+     注意！不透明性和“访问函数”本身是不好的。我们使用 pte_t 等类型的原因在于真的是
+     完全没有任何共用的可访问信息。
+
+ (b) 清楚的整数类型，如此，这层抽象就可以帮助消除到底是 “int” 还是 “long” 的混淆。
+
+     u8/u16/u32 是完全没有问题的 typedef，不过它们更符合类别 (d) 而不是这里。
+
+     再次注意！要这样做，必须事出有因。如果某个变量是 “unsigned long“，那么没有必要
+
+	typedef unsigned long myflags_t;
+
+     不过如果有一个明确的原因，比如它在某种情况下可能会是一个 “unsigned int” 而在
+     其他情况下可能为 “unsigned long”，那么就不要犹豫，请务必使用 typedef。
+
+ (c) 当你使用sparse按字面的创建一个新类型来做类型检查的时候。
+
+ (d) 和标准C99类型相同的类型，在某些例外的情况下。
+
+     虽然让眼睛和脑筋来适应新的标准类型比如 “uint32_t” 不需要花很多时间，可是有些
+     人仍然拒绝使用它们。
+
+     因此，Linux 特有的等同于标准类型的 “u8/u16/u32/u64” 类型和它们的有符号类型是被
+     允许的——尽管在你自己的新代码中，它们不是强制要求要使用的。
+
+     当编辑已经使用了某个类型集的已有代码时，你应该遵循那些代码中已经做出的选择。
+
+ (e) 可以在用户空间安全使用的类型。
+
+     在某些用户空间可见的结构体里，我们不能要求C99类型而且不能用上面提到的 “u32”
+     类型。因此，我们在与用户空间共享的所有结构体中使用 __u32 和类似的类型。
+
+可能还有其他的情况，不过基本的规则是永远不要使用 typedef，除非你可以明确的应用上
+述某个规则中的一个。
+
+总的来说，如果一个指针或者一个结构体里的元素可以合理的被直接访问到，那么它们就不
+应该是一个 typedef。
+
+
+		第六章：函数
+
+函数应该简短而漂亮，并且只完成一件事情。函数应该可以一屏或者两屏显示完（我们都知
+道 ISO/ANSI 屏幕大小是 80x24），只做一件事情，而且把它做好。
+
+一个函数的最大长度是和该函数的复杂度和缩进级数成反比的。所以，如果你有一个理论上
+很简单的只有一个很长（但是简单）的 case 语句的函数，而且你需要在每个 case 里做
+很多很小的事情，这样的函数尽管很长，但也是可以的。
+
+不过，如果你有一个复杂的函数，而且你怀疑一个天分不是很高的高中一年级学生可能甚至
+搞不清楚这个函数的目的，你应该严格的遵守前面提到的长度限制。使用辅助函数，并为之
+取个具描述性的名字（如果你觉得它们的性能很重要的话，可以让编译器内联它们，这样的
+效果往往会比你写一个复杂函数的效果要好。）
+
+函数的另外一个衡量标准是本地变量的数量。此数量不应超过 5－10 个，否则你的函数就有
+问题了。重新考虑一下你的函数，把它分拆成更小的函数。人的大脑一般可以轻松的同时跟
+踪 7 个不同的事物，如果再增多的话，就会糊涂了。即便你聪颖过人，你也可能会记不清你
+2 个星期前做过的事情。
+
+在源文件里，使用空行隔开不同的函数。如果该函数需要被导出，它的 EXPORT* 宏应该紧贴
+在它的结束大括号之下。比如：
+
+	int system_is_up(void)
+	{
+		return system_state == SYSTEM_RUNNING;
+	}
+	EXPORT_SYMBOL(system_is_up);
+
+在函数原型中，包含函数名和它们的数据类型。虽然C语言里没有这样的要求，在 Linux 里这
+是提倡的做法，因为这样可以很简单的给读者提供更多的有价值的信息。
+
+
+		第七章：集中的函数退出途径
+
+虽然被某些人声称已经过时，但是 goto 语句的等价物还是经常被编译器所使用，具体形式是
+无条件跳转指令。
+
+当一个函数从多个位置退出，并且需要做一些类似清理的常见操作时，goto 语句就很方便了。
+如果并不需要清理操作，那么直接 return 即可。
+
+理由是：
+
+- 无条件语句容易理解和跟踪
+- 嵌套程度减小
+- 可以避免由于修改时忘记更新某个单独的退出点而导致的错误
+- 减轻了编译器的工作，无需删除冗余代码;)
+
+	int fun(int a)
+	{
+		int result = 0;
+		char *buffer;
+
+		buffer = kmalloc(SIZE, GFP_KERNEL);
+		if (!buffer)
+			return -ENOMEM;
+
+		if (condition1) {
+			while (loop1) {
+				...
+			}
+			result = 1;
+			goto out_buffer;
+		}
+		...
+	out_buffer:
+		kfree(buffer);
+		return result;
+	}
+
+一个需要注意的常见错误是“一个 err 错误”，就像这样：
+
+	err:
+		kfree(foo->bar);
+		kfree(foo);
+		return ret;
+
+这段代码的错误是，在某些退出路径上 “foo” 是 NULL。通常情况下，通过把它分离成两个
+错误标签 “err_bar:” 和 “err_foo:” 来修复这个错误。
+
+		第八章：注释
+
+注释是好的，不过有过度注释的危险。永远不要在注释里解释你的代码是如何运作的：更好
+的做法是让别人一看你的代码就可以明白，解释写的很差的代码是浪费时间。
+
+一般的，你想要你的注释告诉别人你的代码做了什么，而不是怎么做的。也请你不要把注释
+放在一个函数体内部：如果函数复杂到你需要独立的注释其中的一部分，你很可能需要回到
+第六章看一看。你可以做一些小注释来注明或警告某些很聪明（或者槽糕）的做法，但不要
+加太多。你应该做的，是把注释放在函数的头部，告诉人们它做了什么，也可以加上它做这
+些事情的原因。
+
+当注释内核API函数时，请使用 kernel-doc 格式。请看
+Documentation/kernel-documentation.rst和scripts/kernel-doc 以获得详细信息。
+
+Linux的注释风格是 C89 “/* ... */” 风格。不要使用 C99 风格 “// ...” 注释。
+
+长（多行）的首选注释风格是：
+
+	/*
+	 * This is the preferred style for multi-line
+	 * comments in the Linux kernel source code.
+	 * Please use it consistently.
+	 *
+	 * Description:  A column of asterisks on the left side,
+	 * 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.
+	 */
+
+注释数据也是很重要的，不管是基本类型还是衍生类型。为了方便实现这一点，每一行应只
+声明一个数据（不要使用逗号来一次声明多个数据）。这样你就有空间来为每个数据写一段
+小注释来解释它们的用途了。
+
+
+		第九章：你已经把事情弄糟了
+
+这没什么，我们都是这样。可能你的使用了很长时间 Unix 的朋友已经告诉你 “GNU emacs” 能
+自动帮你格式化 C 源代码，而且你也注意到了，确实是这样，不过它所使用的默认值和我们
+想要的相去甚远（实际上，甚至比随机打的还要差——无数个猴子在 GNU emacs 里打字永远不
+会创造出一个好程序）（译注：请参考 Infinite Monkey Theorem）
+
+所以你要么放弃 GNU emacs，要么改变它让它使用更合理的设定。要采用后一个方案，你可
+以把下面这段粘贴到你的 .emacs 文件里。
+
+(defun c-lineup-arglist-tabs-only (ignored)
+  "Line up argument lists by tabs, not spaces"
+  (let* ((anchor (c-langelem-pos c-syntactic-element))
+         (column (c-langelem-2nd-pos c-syntactic-element))
+         (offset (- (1+ column) anchor))
+         (steps (floor offset c-basic-offset)))
+    (* (max steps 1)
+       c-basic-offset)))
+
+(add-hook 'c-mode-common-hook
+          (lambda ()
+            ;; Add kernel style
+            (c-add-style
+             "linux-tabs-only"
+             '("linux" (c-offsets-alist
+                        (arglist-cont-nonempty
+                         c-lineup-gcc-asm-reg
+                         c-lineup-arglist-tabs-only))))))
+
+(add-hook 'c-mode-hook
+          (lambda ()
+            (let ((filename (buffer-file-name)))
+              ;; Enable kernel mode for the appropriate files
+              (when (and filename
+                         (string-match (expand-file-name "~/src/linux-trees")
+                                       filename))
+                (setq indent-tabs-mode t)
+                (setq show-trailing-whitespace t)
+                (c-set-style "linux-tabs-only")))))
+
+这会让 emacs 在 ~/src/linux-trees 目录下的 C 源文件获得更好的内核代码风格。
+
+不过就算你尝试让 emacs 正确的格式化代码失败了，也并不意味着你失去了一切：还可以用
+“indent”。
+
+不过，GNU indent 也有和 GNU emacs 一样有问题的设定，所以你需要给它一些命令选项。不
+过，这还不算太糟糕，因为就算是 GNU indent 的作者也认同 K&R 的权威性（GNU 的人并不是
+坏人，他们只是在这个问题上被严重的误导了），所以你只要给 indent 指定选项 “-kr -i8”
+（代表 “K&R，8 个字符缩进”），或者使用 “scripts/Lindent”，这样就可以以最时髦的方式
+缩进源代码。
+
+“indent” 有很多选项，特别是重新格式化注释的时候，你可能需要看一下它的手册页。不过
+记住：“indent” 不能修正坏的编程习惯。
+
+
+		第十章：Kconfig 配置文件
+
+对于遍布源码树的所有 Kconfig* 配置文件来说，它们缩进方式与 C 代码相比有所不同。紧挨
+在 “config” 定义下面的行缩进一个制表符，帮助信息则再多缩进 2 个空格。比如：
+
+config AUDIT
+	bool "Auditing support"
+	depends on NET
+	help
+	  Enable auditing infrastructure that can be used with another
+	  kernel subsystem, such as SELinux (which requires this for
+	  logging of avc messages output).  Does not do system-call
+	  auditing without CONFIG_AUDITSYSCALL.
+
+而那些危险的功能（比如某些文件系统的写支持）应该在它们的提示字符串里显著的声明这
+一点：
+
+config ADFS_FS_RW
+	bool "ADFS write support (DANGEROUS)"
+	depends on ADFS_FS
+	...
+
+要查看配置文件的完整文档，请看 Documentation/kbuild/kconfig-language.txt。
+
+
+		第十一章：数据结构
+
+如果一个数据结构，在创建和销毁它的单线执行环境之外可见，那么它必须要有一个引用计
+数器。内核里没有垃圾收集（并且内核之外的垃圾收集慢且效率低下），这意味着你绝对需
+要记录你对这种数据结构的使用情况。
+
+引用计数意味着你能够避免上锁，并且允许多个用户并行访问这个数据结构——而不需要担心
+这个数据结构仅仅因为暂时不被使用就消失了，那些用户可能不过是沉睡了一阵或者做了一
+些其他事情而已。
+
+注意上锁不能取代引用计数。上锁是为了保持数据结构的一致性，而引用计数是一个内存管
+理技巧。通常二者都需要，不要把两个搞混了。
+
+很多数据结构实际上有2级引用计数，它们通常有不同“类”的用户。子类计数器统计子类用
+户的数量，每当子类计数器减至零时，全局计数器减一。
+
+这种“多级引用计数”的例子可以在内存管理（“struct mm_struct”：mm_users 和 mm_count）
+和文件系统（“struct super_block”：s_count和s_active）中找到。
+
+记住：如果另一个执行线索可以找到你的数据结构，但是这个数据结构没有引用计数器，这
+里几乎肯定是一个 bug。
+
+
+		第十二章：宏，枚举和RTL
+
+用于定义常量的宏的名字及枚举里的标签需要大写。
+
+#define CONSTANT 0x12345
+
+在定义几个相关的常量时，最好用枚举。
+
+宏的名字请用大写字母，不过形如函数的宏的名字可以用小写字母。
+
+一般的，如果能写成内联函数就不要写成像函数的宏。
+
+含有多个语句的宏应该被包含在一个 do-while 代码块里：
+
+	#define macrofun(a, b, c)			\
+		do {					\
+			if (a == 5)			\
+				do_this(b, c);		\
+		} while (0)
+
+使用宏的时候应避免的事情：
+
+1) 影响控制流程的宏：
+
+	#define FOO(x)					\
+		do {					\
+			if (blah(x) < 0)		\
+				return -EBUGGERED;	\
+		} while (0)
+
+非常不好。它看起来像一个函数，不过却能导致“调用”它的函数退出；不要打乱读者大脑里
+的语法分析器。
+
+2) 依赖于一个固定名字的本地变量的宏：
+
+	#define FOO(val) bar(index, val)
+
+可能看起来像是个不错的东西，不过它非常容易把读代码的人搞糊涂，而且容易导致看起来
+不相关的改动带来错误。
+
+3) 作为左值的带参数的宏： FOO(x) = y；如果有人把 FOO 变成一个内联函数的话，这种用
+法就会出错了。
+
+4) 忘记了优先级：使用表达式定义常量的宏必须将表达式置于一对小括号之内。带参数的
+宏也要注意此类问题。
+
+	#define CONSTANT 0x4000
+	#define CONSTEXP (CONSTANT | 3)
+
+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”。保证这些信息简单、明了、
+无歧义。
+
+内核信息不必以句号（译注：英文句号，即点）结束。
+
+在小括号里打印数字 (%d) 没有任何价值，应该避免这样做。
+
+ 里有一些驱动模型诊断宏，你应该使用它们，以确保信息对应于正确的
+设备和驱动，并且被标记了正确的消息级别。这些宏有：dev_err()，dev_warn()，
+dev_info() 等等。对于那些不和某个特定设备相关连的信息， 定义了
+pr_notice()，pr_info()，pr_warn()，pr_err() 和其他。
+
+写出好的调试信息可以是一个很大的挑战；一旦你写出后，这些信息在远程除错时能提供极大
+的帮助。然而打印调试信息的处理方式同打印非调试信息不同。其他 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()，kmalloc_array()，kcalloc()，vmalloc() 和 vzalloc()。
+请参考 API 文档以获取有关它们的详细信息。
+
+传递结构体大小的首选形式是这样的：
+
+	p = kmalloc(sizeof(*p), ...);
+
+另外一种传递方式中，sizeof 的操作数是结构体的名字，这样会降低可读性，并且可能会引
+入 bug。有可能指针变量类型被改变时，而对应的传递给内存分配函数的 sizeof 的结果不变。
+
+强制转换一个 void 指针返回值是多余的。C 语言本身保证了从 void 指针到其他任何指针类型
+的转换是没有问题的。
+
+分配一个数组的首选形式是这样的：
+
+	p = kmalloc_array(n, sizeof(...), ...);
+
+分配一个零长数组的首选形式是这样的：
+
+	p = kcalloc(n, sizeof(...), ...);
+
+两种形式检查分配大小 n * sizeof(...) 的溢出，如果溢出返回 NULL。
+
+
+		第十五章：内联弊病
+
+有一个常见的误解是内联函数是 gcc 提供的可以让代码运行更快的一个选项。虽然使用内联
+函数有时候是恰当的（比如作为一种替代宏的方式，请看第十二章），不过很多情况下不是
+这样。inline 关键字的过度使用会使内核变大，从而使整个系统运行速度变慢。因为大内核
+会占用更多的指令高速缓存（译注：一级缓存通常是指令缓存和数据缓存分开的）而且会导
+致 pagecache 的可用内存减少。想象一下，一次pagecache未命中就会导致一次磁盘寻址，
+将耗时 5 毫秒。5 毫秒的时间内 CPU 能执行很多很多指令。
+
+一个基本的原则是如果一个函数有 3 行以上，就不要把它变成内联函数。这个原则的一个例
+外是，如果你知道某个参数是一个编译时常量，而且因为这个常量你确定编译器在编译时能
+优化掉你的函数的大部分代码，那仍然可以给它加上 inline 关键字。kmalloc() 内联函数就
+是一个很好的例子。
+
+人们经常主张给 static 的而且只用了一次的函数加上 inline，如此不会有任何损失，因为没
+有什么好权衡的。虽然从技术上说这是正确的，但是实际上这种情况下即使不加 inline gcc
+也可以自动使其内联。而且其他用户可能会要求移除 inline，由此而来的争论会抵消 inline
+自身的潜在价值，得不偿失。
+
+
+		第十六章：函数返回值及命名
+
+函数可以返回很多种不同类型的值，最常见的一种是表明函数执行成功或者失败的值。这样
+的一个值可以表示为一个错误代码整数（-Exxx＝失败，0＝成功）或者一个“成功”布尔值（
+0＝失败，非0＝成功）。
+
+混合使用这两种表达方式是难于发现的 bug 的来源。如果 C 语言本身严格区分整形和布尔型变
+量，那么编译器就能够帮我们发现这些错误……不过 C 语言不区分。为了避免产生这种 bug，请
+遵循下面的惯例：
+
+	如果函数的名字是一个动作或者强制性的命令，那么这个函数应该返回错误代码整
+	数。如果是一个判断，那么函数应该返回一个“成功”布尔值。
+
+比如，“add work” 是一个命令，所以 add_work() 函数在成功时返回 0，在失败时返回 -EBUSY。
+类似的，因为 “PCI device present” 是一个判断，所以 pci_dev_present() 函数在成功找到
+一个匹配的设备时应该返回 1，如果找不到时应该返回 0。
+
+所有导出（译注：EXPORT）的函数都必须遵守这个惯例，所有的公共函数也都应该如此。私
+有（static）函数不需要如此，但是我们也推荐这样做。
+
+返回值是实际计算结果而不是计算是否成功的标志的函数不受此惯例的限制。一般的，他们
+通过返回一些正常值范围之外的结果来表示出错。典型的例子是返回指针的函数，他们使用
+NULL 或者 ERR_PTR 机制来报告错误。
+
+
+		第十七章：不要重新发明内核宏
+
+头文件 include/linux/kernel.h 包含了一些宏，你应该使用它们，而不要自己写一些它们的
+变种。比如，如果你需要计算一个数组的长度，使用这个宏
+
+	#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
+
+类似的，如果你要计算某结构体成员的大小，使用
+
+	#define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
+
+还有可以做严格的类型检查的 min() 和 max() 宏，如果你需要可以使用它们。你可以自己看看
+那个头文件里还定义了什么你可以拿来用的东西，如果有定义的话，你就不应在你的代码里
+自己重新定义。
+
+
+		第十八章：编辑器模式行和其他需要罗嗦的事情
+
+有一些编辑器可以解释嵌入在源文件里的由一些特殊标记标明的配置信息。比如，emacs
+能够解释被标记成这样的行：
+
+	-*- mode: c -*-
+
+或者这样的：
+
+	/*
+	Local Variables:
+	compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
+	End:
+	*/
+
+Vim 能够解释这样的标记：
+
+	/* vim:set sw=8 noet */
+
+不要在源代码中包含任何这样的内容。每个人都有他自己的编辑器配置，你的源文件不应
+该覆盖别人的配置。这包括有关缩进和模式配置的标记。人们可以使用他们自己定制的模
+式，或者使用其他可以产生正确的缩进的巧妙方法。
+
+
+		第十九章：内联汇编
+
+在特定架构的代码中，你也许需要内联汇编来使用 CPU 接口和平台相关功能。在需要
+这么做时，不要犹豫。然而，当 C 可以完成工作时，不要无端地使用内联汇编。如果
+可能，你可以并且应该用 C 和硬件交互。
+
+考虑去写通用一点的内联汇编作为简明的辅助函数，而不是重复写下它们的细节。记住
+内联汇编可以使用 C 参数。
+
+大而特殊的汇编函数应该放在 .S 文件中，对应 C 的原型定义在 C 头文件中。汇编
+函数的 C 原型应该使用 “asmlinkage”。
+
+你可能需要将你的汇编语句标记为 volatile，来阻止 GCC 在没发现任何副作用后就
+移除了它。你不必总是这样做，虽然，这样可以限制不必要的优化。
+
+在写一个包含多条指令的单个内联汇编语句时，把每条指令用引号字符串分离，并写在
+单独一行，在每个字符串结尾，除了 \n\t 结尾之外，在汇编输出中适当地缩进下
+一条指令：
+
+	asm ("magic %reg1, #42\n\t"
+	     "more_magic %reg2, %reg3"
+	     : /* outputs */ : /* inputs */ : /* clobbers */);
+
+
+		第二十章：条件编译
+
+只要可能，就不要在 .c 文件里面使用预处理条件；这样做让代码更难阅读并且逻辑难以
+跟踪。替代方案是，在头文件定义函数在这些 .c 文件中使用这类的条件表达式，提供空
+操作的桩版本（译注：桩程序，是指用来替换一部分功能的程序段）在 #else 情况下，
+再从 .c 文件中无条件地调用这些函数。编译器会避免生成任何桩调用的代码，产生一致
+的结果，但逻辑将更加清晰。
+
+宁可编译整个函数，而不是部分函数或部分表达式。而不是在一个表达式添加 ifdef，
+解析部分或全部表达式到一个单独的辅助函数，并应用条件到该函数内。
+
+如果你有一个在特定配置中可能是未使用的函数或变量，编译器将警告它定义了但未使用，
+标记这个定义为 __maybe_unused 而不是将它包含在一个预处理条件中。（然而，如果
+一个函数或变量总是未使用的，就直接删除它。）
+
+在代码中，可能的情况下，使用 IS_ENABLED 宏来转化某个 Kconfig 标记为 C 的布尔
+表达式，并在正常的 C 条件中使用它：
+
+	if (IS_ENABLED(CONFIG_SOMETHING)) {
+		...
+	}
+
+编译器会无条件地做常数合并，就像使用 #ifdef 那样，包含或排除代码块，所以这不会
+带来任何运行时开销。然而，这种方法依旧允许 C 编译器查看块内的代码，并检查它的正确
+性（语法，类型，符号引用，等等）。因此，如果条件不满足，代码块内的引用符号将不存在，
+你必须继续使用 #ifdef。
+
+在任何有意义的 #if 或 #ifdef 块的末尾（超过几行），在 #endif 同一行的后面写下
+注释，指出该条件表达式被使用。例如：
+
+	#ifdef CONFIG_SOMETHING
+	...
+	#endif /* CONFIG_SOMETHING */
+
+
+		附录 I：参考
+
+The C Programming Language, 第二版
+作者：Brian W. Kernighan 和 Denni M. Ritchie.
+Prentice Hall, Inc., 1988.
+ISBN 0-13-110362-8 (软皮), 0-13-110370-9 (硬皮).
+
+The Practice of Programming
+作者：Brian W. Kernighan 和 Rob Pike.
+Addison-Wesley, Inc., 1999.
+ISBN 0-201-61586-X.
+
+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 process/coding-style.rst，作者 greg@kroah.com 发表于OLS 2002：
+http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
diff --git a/Documentation/translations/zh_CN/HOWTO b/Documentation/translations/zh_CN/HOWTO
new file mode 100644
index 000000000000..11be075ba5fa
--- /dev/null
+++ b/Documentation/translations/zh_CN/HOWTO
@@ -0,0 +1,536 @@
+Chinese translated version of Documentation/process/howto.rst
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Maintainer: Greg Kroah-Hartman 
+Chinese maintainer: Li Yang 
+---------------------------------------------------------------------
+Documentation/process/howto.rst 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+英文版维护者： Greg Kroah-Hartman 
+中文版维护者： 李阳  Li Yang 
+中文版翻译者： 李阳  Li Yang 
+中文版校译者： 钟宇  TripleX Chung 
+               陈琦  Maggie Chen 
+               王聪  Wang Cong 
+
+以下为正文
+---------------------------------------------------------------------
+
+如何参与Linux内核开发
+---------------------
+
+这是一篇将如何参与Linux内核开发的相关问题一网打尽的终极秘笈。它将指导你
+成为一名Linux内核开发者，并且学会如何同Linux内核开发社区合作。它尽可能不
+包括任何关于内核编程的技术细节，但会给你指引一条获得这些知识的正确途径。
+
+如果这篇文章中的任何内容不再适用，请给文末列出的文件维护者发送补丁。
+
+
+入门
+----
+
+你想了解如何成为一名Linux内核开发者？或者老板吩咐你“给这个设备写个Linux
+驱动程序”？这篇文章的目的就是教会你达成这些目标的全部诀窍，它将描述你需
+要经过的流程以及给出如何同内核社区合作的一些提示。它还将试图解释内核社区
+为何这样运作。
+
+Linux内核大部分是由C语言写成的，一些体系结构相关的代码用到了汇编语言。要
+参与内核开发，你必须精通C语言。除非你想为某个架构开发底层代码，否则你并
+不需要了解（任何体系结构的）汇编语言。下面列举的书籍虽然不能替代扎实的C
+语言教育和多年的开发经验，但如果需要的话，做为参考还是不错的：
+ - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
+   《C程序设计语言（第2版·新版）》（徐宝文 李志 译）[机械工业出版社]
+ - "Practical C Programming" by Steve Oualline [O'Reilly]
+   《实用C语言编程（第三版）》（郭大海 译）[中国电力出版社]
+ - "C:  A Reference Manual" by Harbison and Steele [Prentice Hall]
+   《C语言参考手册（原书第5版）》（邱仲潘 等译）[机械工业出版社]
+
+Linux内核使用GNU C和GNU工具链开发。虽然它遵循ISO C89标准，但也用到了一些
+标准中没有定义的扩展。内核是自给自足的C环境，不依赖于标准C库的支持，所以
+并不支持C标准中的部分定义。比如long long类型的大数除法和浮点运算就不允许
+使用。有时候确实很难弄清楚内核对工具链的要求和它所使用的扩展，不幸的是目
+前还没有明确的参考资料可以解释它们。请查阅gcc信息页（使用“info gcc”命令
+显示）获得一些这方面信息。
+
+请记住你是在学习怎么和已经存在的开发社区打交道。它由一群形形色色的人组成，
+他们对代码、风格和过程有着很高的标准。这些标准是在长期实践中总结出来的，
+适应于地理上分散的大型开发团队。它们已经被很好得整理成档，建议你在开发
+之前尽可能多的学习这些标准，而不要期望别人来适应你或者你公司的行为方式。
+
+
+法律问题
+--------
+
+Linux内核源代码都是在GPL（通用公共许可证）的保护下发布的。要了解这种许可
+的细节请查看源代码主目录下的COPYING文件。如果你对它还有更深入问题请联系
+律师，而不要在Linux内核邮件组上提问。因为邮件组里的人并不是律师，不要期
+望他们的话有法律效力。
+
+对于GPL的常见问题和解答，请访问以下链接：
+	http://www.gnu.org/licenses/gpl-faq.html
+
+
+文档
+----
+
+Linux内核代码中包含有大量的文档。这些文档对于学习如何与内核社区互动有着
+不可估量的价值。当一个新的功能被加入内核，最好把解释如何使用这个功能的文
+档也放进内核。当内核的改动导致面向用户空间的接口发生变化时，最好将相关信
+息或手册页(manpages)的补丁发到mtk.manpages@gmail.com，以向手册页(manpages)
+的维护者解释这些变化。
+
+以下是内核代码中需要阅读的文档：
+  README
+    文件简要介绍了Linux内核的背景，并且描述了如何配置和编译内核。内核的
+    新用户应该从这里开始。
+
+  Documentation/process/changes.rst
+    文件给出了用来编译和使用内核所需要的最小软件包列表。
+
+  Documentation/process/coding-style.rst
+    描述Linux内核的代码风格和理由。所有新代码需要遵守这篇文档中定义的规
+    范。大多数维护者只会接收符合规定的补丁，很多人也只会帮忙检查符合风格
+    的代码。
+
+  Documentation/process/submitting-patches.rst
+  Documentation/process/submitting-drivers.rst
+    这两份文档明确描述如何创建和发送补丁，其中包括（但不仅限于)：
+       - 邮件内容
+       - 邮件格式
+       - 选择收件人
+    遵守这些规定并不能保证提交成功（因为所有补丁需要通过严格的内容和风格
+    审查），但是忽视他们几乎就意味着失败。
+
+    其他关于如何正确地生成补丁的优秀文档包括：
+    "The Perfect Patch"
+        http://www.ozlabs.org/~akpm/stuff/tpp.txt
+    "Linux kernel patch submission format"
+        http://linux.yyz.us/patch-format.html
+
+  Documentation/process/stable-api-nonsense.rst
+    论证内核为什么特意不包括稳定的内核内部API，也就是说不包括像这样的特
+    性：
+       - 子系统中间层（为了兼容性？）
+       - 在不同操作系统间易于移植的驱动程序
+       - 减缓（甚至阻止）内核代码的快速变化
+    这篇文档对于理解Linux的开发哲学至关重要。对于将开发平台从其他操作系
+    统转移到Linux的人来说也很重要。
+
+  Documentation/admin-guide/security-bugs.rst
+    如果你认为自己发现了Linux内核的安全性问题，请根据这篇文档中的步骤来
+    提醒其他内核开发者并帮助解决这个问题。
+
+  Documentation/process/management-style.rst
+    描述内核维护者的工作方法及其共有特点。这对于刚刚接触内核开发（或者对
+    它感到好奇）的人来说很重要，因为它解释了很多对于内核维护者独特行为的
+    普遍误解与迷惑。
+
+  Documentation/process/stable-kernel-rules.rst
+    解释了稳定版内核发布的规则，以及如何将改动放入这些版本的步骤。
+
+  Documentation/process/kernel-docs.rst
+    有助于内核开发的外部文档列表。如果你在内核自带的文档中没有找到你想找
+    的内容，可以查看这些文档。
+
+  Documentation/process/applying-patches.rst
+    关于补丁是什么以及如何将它打在不同内核开发分支上的好介绍
+
+内核还拥有大量从代码自动生成的文档。它包含内核内部API的全面介绍以及如何
+妥善处理加锁的规则。生成的文档会放在 Documentation/DocBook/目录下。在内
+核源码的主目录中使用以下不同命令将会分别生成PDF、Postscript、HTML和手册
+页等不同格式的文档：
+    make pdfdocs
+    make psdocs
+    make htmldocs
+    make mandocs
+
+
+如何成为内核开发者
+------------------
+如果你对Linux内核开发一无所知，你应该访问“Linux内核新手”计划：
+	http://kernelnewbies.org
+它拥有一个可以问各种最基本的内核开发问题的邮件列表（在提问之前一定要记得
+查找已往的邮件，确认是否有人已经回答过相同的问题）。它还拥有一个可以获得
+实时反馈的IRC聊天频道，以及大量对于学习Linux内核开发相当有帮助的文档。
+
+网站简要介绍了源代码组织结构、子系统划分以及目前正在进行的项目（包括内核
+中的和单独维护的）。它还提供了一些基本的帮助信息，比如如何编译内核和打补
+丁。
+
+如果你想加入内核开发社区并协助完成一些任务，却找不到从哪里开始，可以访问
+“Linux内核房管员”计划：
+	http://kernelnewbies.org/KernelJanitors
+这是极佳的起点。它提供一个相对简单的任务列表，列出内核代码中需要被重新
+整理或者改正的地方。通过和负责这个计划的开发者们一同工作，你会学到将补丁
+集成进内核的基本原理。如果还没有决定下一步要做什么的话，你还可能会得到方
+向性的指点。
+
+如果你已经有一些现成的代码想要放到内核中，但是需要一些帮助来使它们拥有正
+确的格式。请访问“内核导师”计划。这个计划就是用来帮助你完成这个目标的。它
+是一个邮件列表，地址如下：
+	http://selenic.com/mailman/listinfo/kernel-mentors
+
+在真正动手修改内核代码之前，理解要修改的代码如何运作是必需的。要达到这个
+目的，没什么办法比直接读代码更有效了（大多数花招都会有相应的注释），而且
+一些特制的工具还可以提供帮助。例如，“Linux代码交叉引用”项目就是一个值得
+特别推荐的帮助工具，它将源代码显示在有编目和索引的网页上。其中一个更新及
+时的内核源码库，可以通过以下地址访问：
+	http://sosdg.org/~coywolf/lxr/
+
+
+开发流程
+--------
+
+目前Linux内核开发流程包括几个“主内核分支”和很多子系统相关的内核分支。这
+些分支包括：
+  - 2.6.x主内核源码树
+  - 2.6.x.y -stable内核源码树
+  - 2.6.x -git内核补丁集
+  - 2.6.x -mm内核补丁集
+  - 子系统相关的内核源码树和补丁集
+
+
+2.6.x内核主源码树
+-----------------
+2.6.x内核是由Linus Torvalds（Linux的创造者）亲自维护的。你可以在
+kernel.org网站的pub/linux/kernel/v2.6/目录下找到它。它的开发遵循以下步
+骤：
+  - 每当一个新版本的内核被发布，为期两周的集成窗口将被打开。在这段时间里
+    维护者可以向Linus提交大段的修改，通常这些修改已经被放到-mm内核中几个
+    星期了。提交大量修改的首选方式是使用git工具（内核的代码版本管理工具
+    ，更多的信息可以在http://git-scm.com/获取），不过使用普通补丁也是可以
+    的。
+  - 两个星期以后-rc1版本内核发布。之后只有不包含可能影响整个内核稳定性的
+    新功能的补丁才可能被接受。请注意一个全新的驱动程序（或者文件系统）有
+    可能在-rc1后被接受是因为这样的修改完全独立，不会影响其他的代码，所以
+    没有造成内核退步的风险。在-rc1以后也可以用git向Linus提交补丁，不过所
+    有的补丁需要同时被发送到相应的公众邮件列表以征询意见。
+  - 当Linus认为当前的git源码树已经达到一个合理健全的状态足以发布供人测试
+    时，一个新的-rc版本就会被发布。计划是每周都发布新的-rc版本。
+  - 这个过程一直持续下去直到内核被认为达到足够稳定的状态，持续时间大概是
+    6个星期。
+
+关于内核发布，值得一提的是Andrew Morton在linux-kernel邮件列表中如是说：
+	“没有人知道新内核何时会被发布，因为发布是根据已知bug的情况来决定
+	的，而不是根据一个事先制定好的时间表。”
+
+
+2.6.x.y -stable（稳定版）内核源码树
+-----------------------------------
+由4个数字组成的内核版本号说明此内核是-stable版本。它们包含基于2.6.x版本
+内核的相对较小且至关重要的修补，这些修补针对安全性问题或者严重的内核退步。
+
+这种版本的内核适用于那些期望获得最新的稳定版内核并且不想参与测试开发版或
+者实验版的用户。
+
+如果没有2.6.x.y版本内核存在，那么最新的2.6.x版本内核就相当于是当前的稳定
+版内核。
+
+2.6.x.y版本由“稳定版”小组（邮件地址）维护，一般隔周发
+布新版本。
+
+内核源码中的Documentation/process/stable-kernel-rules.rst文件具体描述了可被稳定
+版内核接受的修改类型以及发布的流程。
+
+
+2.6.x -git补丁集
+----------------
+Linus的内核源码树的每日快照，这个源码树是由git工具管理的（由此得名）。这
+些补丁通常每天更新以反映Linus的源码树的最新状态。它们比-rc版本的内核源码
+树更具试验性质，因为这个补丁集是全自动生成的，没有任何人来确认其是否真正
+健全。
+
+
+2.6.x -mm补丁集
+---------------
+这是由Andrew Morton维护的试验性内核补丁集。Andrew将所有子系统的内核源码
+和补丁拼凑到一起，并且加入了大量从linux-kernel邮件列表中采集的补丁。这个
+源码树是新功能和补丁的试炼场。当补丁在-mm补丁集里证明了其价值以后Andrew
+或者相应子系统的维护者会将补丁发给Linus以便集成进主内核源码树。
+
+在将所有新补丁发给Linus以集成到主内核源码树之前，我们非常鼓励先把这些补
+丁放在-mm版内核源码树中进行测试。
+
+这些内核版本不适合在需要稳定运行的系统上运行，因为运行它们比运行任何其他
+内核分支都更具有风险。
+
+如果你想为内核开发进程提供帮助，请尝试并使用这些内核版本，并在
+linux-kernel邮件列表中提供反馈，告诉大家你遇到了问题还是一切正常。
+
+通常-mm版补丁集不光包括这些额外的试验性补丁，还包括发布时-git版主源码树
+中的改动。
+
+-mm版内核没有固定的发布周期，但是通常在每两个-rc版内核发布之间都会有若干
+个-mm版内核发布（一般是1至3个）。
+
+
+子系统相关内核源码树和补丁集
+----------------------------
+相当一部分内核子系统开发者会公开他们自己的开发源码树，以便其他人能了解内
+核的不同领域正在发生的事情。如上所述，这些源码树会被集成到-mm版本内核中。
+
+下面是目前可用的一些内核源码树的列表：
+  通过git管理的源码树：
+    - Kbuild开发源码树， Sam Ravnborg 
+	git.kernel.org:/pub/scm/linux/kernel/git/sam/kbuild.git
+
+    - ACPI开发源码树, Len Brown 
+	git.kernel.org:/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git
+
+    - 块设备开发源码树, Jens Axboe 
+	git.kernel.org:/pub/scm/linux/kernel/git/axboe/linux-2.6-block.git
+
+    - DRM开发源码树, Dave Airlie 
+	git.kernel.org:/pub/scm/linux/kernel/git/airlied/drm-2.6.git
+
+    - ia64开发源码树, Tony Luck 
+	git.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git
+
+    - ieee1394开发源码树, Jody McIntyre 
+	git.kernel.org:/pub/scm/linux/kernel/git/scjody/ieee1394.git
+
+    - infiniband开发源码树, Roland Dreier 
+	git.kernel.org:/pub/scm/linux/kernel/git/roland/infiniband.git
+
+    - libata开发源码树, Jeff Garzik 
+	git.kernel.org:/pub/scm/linux/kernel/git/jgarzik/libata-dev.git
+
+    - 网络驱动程序开发源码树, Jeff Garzik 
+	git.kernel.org:/pub/scm/linux/kernel/git/jgarzik/netdev-2.6.git
+
+    - pcmcia开发源码树, Dominik Brodowski 
+	git.kernel.org:/pub/scm/linux/kernel/git/brodo/pcmcia-2.6.git
+
+    - SCSI开发源码树, James Bottomley 
+	git.kernel.org:/pub/scm/linux/kernel/git/jejb/scsi-misc-2.6.git
+
+  使用quilt管理的补丁集：
+    - USB, PCI, 驱动程序核心和I2C, Greg Kroah-Hartman 
+	kernel.org/pub/linux/kernel/people/gregkh/gregkh-2.6/
+    - x86-64, 部分i386, Andi Kleen 
+	ftp.firstfloor.org:/pub/ak/x86_64/quilt/
+
+  其他内核源码树可以在http://git.kernel.org的列表中和MAINTAINERS文件里
+  找到。
+
+报告bug
+-------
+
+bugzilla.kernel.org是Linux内核开发者们用来跟踪内核Bug的网站。我们鼓励用
+户在这个工具中报告找到的所有bug。如何使用内核bugzilla的细节请访问：
+	http://test.kernel.org/bugzilla/faq.html
+
+内核源码主目录中的admin-guide/reporting-bugs.rst文件里有一个很好的模板。它指导用户如何报
+告可能的内核bug以及需要提供哪些信息来帮助内核开发者们找到问题的根源。
+
+
+利用bug报告
+-----------
+
+练习内核开发技能的最好办法就是修改其他人报告的bug。你不光可以帮助内核变
+得更加稳定，还可以学会如何解决实际问题从而提高自己的技能，并且让其他开发
+者感受到你的存在。修改bug是赢得其他开发者赞誉的最好办法，因为并不是很多
+人都喜欢浪费时间去修改别人报告的bug。
+
+要尝试修改已知的bug，请访问http://bugzilla.kernel.org网址。如果你想获得
+最新bug的通知，可以订阅bugme-new邮件列表（只有新的bug报告会被寄到这里）
+或者订阅bugme-janitor邮件列表（所有bugzilla的变动都会被寄到这里）。
+
+	https://lists.linux-foundation.org/mailman/listinfo/bugme-new
+	https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
+
+
+邮件列表
+--------
+
+正如上面的文档所描述，大多数的骨干内核开发者都加入了Linux Kernel邮件列
+表。如何订阅和退订列表的细节可以在这里找到：
+	http://vger.kernel.org/vger-lists.html#linux-kernel
+网上很多地方都有这个邮件列表的存档(archive)。可以使用搜索引擎来找到这些
+存档。比如：
+	http://dir.gmane.org/gmane.linux.kernel
+在发信之前，我们强烈建议你先在存档中搜索你想要讨论的问题。很多已经被详细
+讨论过的问题只在邮件列表的存档中可以找到。
+
+大多数内核子系统也有自己独立的邮件列表来协调各自的开发工作。从
+MAINTAINERS文件中可以找到不同话题对应的邮件列表。
+
+很多邮件列表架设在kernel.org服务器上。这些列表的信息可以在这里找到：
+	http://vger.kernel.org/vger-lists.html
+
+在使用这些邮件列表时，请记住保持良好的行为习惯。下面的链接提供了与这些列
+表（或任何其它邮件列表）交流的一些简单规则，虽然内容有点滥竽充数。
+	http://www.albion.com/netiquette/
+
+当有很多人回复你的邮件时，邮件的抄送列表会变得很长。请不要将任何人从抄送
+列表中删除，除非你有足够的理由这么做。也不要只回复到邮件列表。请习惯于同
+一封邮件接收两次（一封来自发送者一封来自邮件列表），而不要试图通过添加一
+些奇特的邮件头来解决这个问题，人们不会喜欢的。
+
+记住保留你所回复内容的上下文和源头。在你回复邮件的顶部保留“某某某说到……”
+这几行。将你的评论加在被引用的段落之间而不要放在邮件的顶部。
+
+如果你在邮件中附带补丁，请确认它们是可以直接阅读的纯文本（如
+Documentation/process/submitting-patches.rst文档中所述）。内核开发者们不希望遇到附件
+或者被压缩了的补丁。只有这样才能保证他们可以直接评论你的每行代码。请确保
+你使用的邮件发送程序不会修改空格和制表符。一个防范性的测试方法是先将邮件
+发送给自己，然后自己尝试是否可以顺利地打上收到的补丁。如果测试不成功，请
+调整或者更换你的邮件发送程序直到它正确工作为止。
+
+总而言之，请尊重其他的邮件列表订阅者。
+
+
+同内核社区合作
+----------------
+
+内核社区的目标就是提供尽善尽美的内核。所以当你提交补丁期望被接受进内核的
+时候，它的技术价值以及其他方面都将被评审。那么你可能会得到什么呢？
+  - 批评
+  - 评论
+  - 要求修改
+  - 要求证明修改的必要性
+  - 沉默
+
+要记住，这些是把补丁放进内核的正常情况。你必须学会听取对补丁的批评和评论，
+从技术层面评估它们，然后要么重写你的补丁要么简明扼要地论证修改是不必要
+的。如果你发的邮件没有得到任何回应，请过几天后再试一次，因为有时信件会湮
+没在茫茫信海中。
+
+你不应该做的事情：
+  - 期望自己的补丁不受任何质疑就直接被接受
+  - 翻脸
+  - 忽略别人的评论
+  - 没有按照别人的要求做任何修改就重新提交
+
+在一个努力追寻最好技术方案的社区里，对于一个补丁有多少好处总会有不同的见
+解。你必须要抱着合作的态度，愿意改变自己的观点来适应内核的风格。或者至少
+愿意去证明你的想法是有价值的。记住，犯错误是允许的，只要你愿意朝着正确的
+方案去努力。
+
+如果你的第一个补丁换来的是一堆修改建议，这是很正常的。这并不代表你的补丁
+不会被接受，也不意味着有人和你作对。你只需要改正所有提出的问题然后重新发
+送你的补丁。
+
+内核社区和公司文化的差异
+------------------------
+
+内核社区的工作模式同大多数传统公司开发队伍的工作模式并不相同。下面这些例
+子，可以帮助你避免某些可能发生问题：
+  用这些话介绍你的修改提案会有好处：
+    - 它同时解决了多个问题
+    - 它删除了2000行代码
+    - 这是补丁，它已经解释了我想要说明的
+    - 我在5种不同的体系结构上测试过它……
+    - 这是一系列小补丁用来……
+    - 这个修改提高了普通机器的性能……
+
+  应该避免如下的说法：
+    - 我们在AIX/ptx/Solaris就是这么做的，所以这么做肯定是好的……
+    - 我做这行已经20年了，所以……
+    - 为了我们公司赚钱考虑必须这么做
+    - 这是我们的企业产品线所需要的
+    - 这里是描述我观点的1000页设计文档
+    - 这是一个5000行的补丁用来……
+    - 我重写了现在乱七八糟的代码，这就是……
+    - 我被规定了最后期限，所以这个补丁需要立刻被接受
+
+另外一个内核社区与大部分传统公司的软件开发队伍不同的地方是无法面对面地交
+流。使用电子邮件和IRC聊天工具做为主要沟通工具的一个好处是性别和种族歧视
+将会更少。Linux内核的工作环境更能接受妇女和少数族群，因为每个人在别人眼
+里只是一个邮件地址。国际化也帮助了公平的实现，因为你无法通过姓名来判断人
+的性别。男人有可能叫李丽，女人也有可能叫王刚。大多数在Linux内核上工作过
+并表达过看法的女性对在linux上工作的经历都给出了正面的评价。
+
+对于一些不习惯使用英语的人来说，语言可能是一个引起问题的障碍。在邮件列表
+中要正确地表达想法必需良好地掌握语言，所以建议你在发送邮件之前最好检查一
+下英文写得是否正确。
+
+
+拆分修改
+--------
+
+Linux内核社区并不喜欢一下接收大段的代码。修改需要被恰当地介绍、讨论并且
+拆分成独立的小段。这几乎完全和公司中的习惯背道而驰。你的想法应该在开发最
+开始的阶段就让大家知道，这样你就可以及时获得对你正在进行的开发的反馈。这
+样也会让社区觉得你是在和他们协作，而不是仅仅把他们当作倾销新功能的对象。
+无论如何，你不要一次性地向邮件列表发送50封信，你的补丁序列应该永远用不到
+这么多。
+
+将补丁拆开的原因如下：
+
+1) 小的补丁更有可能被接受，因为它们不需要太多的时间和精力去验证其正确性。
+   一个5行的补丁，可能在维护者看了一眼以后就会被接受。而500行的补丁则
+   需要数个小时来审查其正确性（所需时间随补丁大小增加大约呈指数级增长）。
+
+   当出了问题的时候，小的补丁也会让调试变得非常容易。一个一个补丁地回溯
+   将会比仔细剖析一个被打上的大补丁（这个补丁破坏了其他东西）容易得多。
+
+2）不光发送小的补丁很重要，在提交之前重新编排、化简（或者仅仅重新排列）
+   补丁也是很重要的。
+
+这里有内核开发者Al Viro打的一个比方：
+	“想象一个老师正在给学生批改数学作业。老师并不希望看到学生为了得
+	到正确解法所进行的尝试和产生的错误。他希望看到的是最干净最优雅的
+	解答。好学生了解这点，绝不会把最终解决之前的中间方案提交上去。”
+
+	内核开发也是这样。维护者和评审者不希望看到一个人在解决问题时的思
+	考过程。他们只希望看到简单和优雅的解决方案。
+
+直接给出一流的解决方案，和社区一起协作讨论尚未完成的工作，这两者之间似乎
+很难找到一个平衡点。所以最好尽早开始收集有利于你进行改进的反馈；同时也要
+保证修改分成很多小块，这样在整个项目都准备好被包含进内核之前，其中的一部
+分可能会先被接收。
+
+必须了解这样做是不可接受的：试图将未完成的工作提交进内核，然后再找时间修
+复。
+
+
+证明修改的必要性
+----------------
+除了将补丁拆成小块，很重要的一点是让Linux社区了解他们为什么需要这样修改。
+你必须证明新功能是有人需要的并且是有用的。
+
+
+记录修改
+--------
+
+当你发送补丁的时候，需要特别留意邮件正文的内容。因为这里的信息将会做为补
+丁的修改记录(ChangeLog)，会被一直保留以备大家查阅。它需要完全地描述补丁，
+包括：
+  - 为什么需要这个修改
+  - 补丁的总体设计
+  - 实现细节
+  - 测试结果
+
+想了解它具体应该看起来像什么，请查阅以下文档中的“ChangeLog”章节：
+  “The Perfect Patch”
+  	 http://www.ozlabs.org/~akpm/stuff/tpp.txt
+
+
+这些事情有时候做起来很难。要在任何方面都做到完美可能需要好几年时间。这是
+一个持续提高的过程，它需要大量的耐心和决心。只要不放弃，你一定可以做到。
+很多人已经做到了，而他们都曾经和现在的你站在同样的起点上。
+
+
+---------------
+感谢Paolo Ciarrocchi允许“开发流程”部分基于他所写的文章
+(http://www.kerneltravel.net/newbie/2.6-development_process)，感谢Randy
+Dunlap和Gerrit Huizenga完善了应该说和不该说的列表。感谢Pat Mochel, Hanna
+Linder, Randy Dunlap, Kay Sievers, Vojtech Pavlik, Jan Kara, Josh Boyer,
+Kees Cook, Andrew Morton, Andi Kleen, Vadim Lobanov, Jesper Juhl, Adrian
+Bunk, Keri Harris, Frans Pop, David A. Wheeler, Junio Hamano, Michael
+Kerrisk和Alex Shepard的评审、建议和贡献。没有他们的帮助，这篇文档是不可
+能完成的。
+
+
+
+英文版维护者： Greg Kroah-Hartman 
diff --git a/Documentation/translations/zh_CN/IRQ.txt b/Documentation/translations/zh_CN/IRQ.txt
new file mode 100644
index 000000000000..956026d5cf82
--- /dev/null
+++ b/Documentation/translations/zh_CN/IRQ.txt
@@ -0,0 +1,39 @@
+Chinese translated version of Documentation/IRQ.txt
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Maintainer: Eric W. Biederman 
+Chinese maintainer: Fu Wei 
+---------------------------------------------------------------------
+Documentation/IRQ.txt 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+英文版维护者： Eric W. Biederman 
+中文版维护者： 傅炜 Fu Wei 
+中文版翻译者： 傅炜 Fu Wei 
+中文版校译者： 傅炜 Fu Wei 
+
+
+以下为正文
+---------------------------------------------------------------------
+何为 IRQ?
+
+一个 IRQ 是来自某个设备的一个中断请求。目前，它们可以来自一个硬件引脚，
+或来自一个数据包。多个设备可能连接到同个硬件引脚，从而共享一个 IRQ。
+
+一个 IRQ 编号是用于告知硬件中断源的内核标识。通常情况下，这是一个
+全局 irq_desc 数组的索引，但是除了在 linux/interrupt.h 中的实现，
+具体的细节是体系结构特定的。
+
+一个 IRQ 编号是设备上某个可能的中断源的枚举。通常情况下，枚举的编号是
+该引脚在系统内中断控制器的所有输入引脚中的编号。对于 ISA 总线中的情况，
+枚举的是在两个 i8259 中断控制器中 16 个输入引脚。
+
+架构可以对 IRQ 编号指定额外的含义，在硬件涉及任何手工配置的情况下，
+是被提倡的。ISA 的 IRQ 是一个分配这类额外含义的典型例子。
diff --git a/Documentation/translations/zh_CN/SecurityBugs b/Documentation/translations/zh_CN/SecurityBugs
new file mode 100644
index 000000000000..2d0fffd122ce
--- /dev/null
+++ b/Documentation/translations/zh_CN/SecurityBugs
@@ -0,0 +1,50 @@
+Chinese translated version of Documentation/admin-guide/security-bugs.rst
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Chinese maintainer: Harry Wei 
+---------------------------------------------------------------------
+Documentation/admin-guide/security-bugs.rst 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+中文版维护者： 贾威威 Harry Wei 
+中文版翻译者： 贾威威 Harry Wei 
+中文版校译者： 贾威威 Harry Wei 
+
+
+以下为正文
+---------------------------------------------------------------------
+Linux内核开发者认为安全非常重要。因此，我们想要知道当一个有关于
+安全的漏洞被发现的时候，并且它可能会被尽快的修复或者公开。请把这个安全
+漏洞报告给Linux内核安全团队。
+
+1) 联系
+
+linux内核安全团队可以通过email来联系。这是
+一组独立的安全工作人员，可以帮助改善漏洞报告并且公布和取消一个修复。安
+全团队有可能会从部分的维护者那里引进额外的帮助来了解并且修复安全漏洞。
+当遇到任何漏洞，所能提供的信息越多就越能诊断和修复。如果你不清楚什么
+是有帮助的信息，那就请重温一下admin-guide/reporting-bugs.rst文件中的概述过程。任
+何攻击性的代码都是非常有用的，未经报告者的同意不会被取消，除非它已经
+被公布于众。
+
+2) 公开
+
+Linux内核安全团队的宗旨就是和漏洞提交者一起处理漏洞的解决方案直
+到公开。我们喜欢尽快地完全公开漏洞。当一个漏洞或者修复还没有被完全地理
+解，解决方案没有通过测试或者供应商协调，可以合理地延迟公开。然而，我们
+期望这些延迟尽可能的短些，是可数的几天，而不是几个星期或者几个月。公开
+日期是通过安全团队和漏洞提供者以及供应商洽谈后的结果。公开时间表是从很
+短（特殊的，它已经被公众所知道）到几个星期。作为一个基本的默认政策，我
+们所期望通知公众的日期是7天的安排。
+
+3) 保密协议
+
+Linux内核安全团队不是一个正式的团体，因此不能加入任何的保密协议。
diff --git a/Documentation/translations/zh_CN/SubmittingDrivers b/Documentation/translations/zh_CN/SubmittingDrivers
new file mode 100644
index 000000000000..929385e4b194
--- /dev/null
+++ b/Documentation/translations/zh_CN/SubmittingDrivers
@@ -0,0 +1,164 @@
+Chinese translated version of Documentation/process/submitting-drivers.rst
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Chinese maintainer: Li Yang 
+---------------------------------------------------------------------
+Documentation/process/submitting-drivers.rst 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+中文版维护者： 李阳  Li Yang 
+中文版翻译者： 李阳  Li Yang 
+中文版校译者： 陈琦 Maggie Chen 
+               王聪 Wang Cong 
+               张巍 Zhang Wei 
+
+以下为正文
+---------------------------------------------------------------------
+
+如何向 Linux 内核提交驱动程序
+-----------------------------
+
+这篇文档将会解释如何向不同的内核源码树提交设备驱动程序。请注意，如果你感
+兴趣的是显卡驱动程序，你也许应该访问 XFree86 项目(http://www.xfree86.org/)
+和／或 X.org 项目 (http://x.org)。
+
+另请参阅 Documentation/process/submitting-patches.rst 文档。
+
+
+分配设备号
+----------
+
+块设备和字符设备的主设备号与从设备号是由 Linux 命名编号分配权威 LANANA（
+现在是 Torben Mathiasen）负责分配。申请的网址是 http://www.lanana.org/。
+即使不准备提交到主流内核的设备驱动也需要在这里分配设备号。有关详细信息，
+请参阅 Documentation/admin-guide/devices.rst。
+
+如果你使用的不是已经分配的设备号，那么当你提交设备驱动的时候，它将会被强
+制分配一个新的设备号，即便这个设备号和你之前发给客户的截然不同。
+
+设备驱动的提交对象
+------------------
+
+Linux 2.0:
+	此内核源码树不接受新的驱动程序。
+
+Linux 2.2:
+	此内核源码树不接受新的驱动程序。
+
+Linux 2.4:
+	如果所属的代码领域在内核的 MAINTAINERS 文件中列有一个总维护者，
+	那么请将驱动程序提交给他。如果此维护者没有回应或者你找不到恰当的
+	维护者，那么请联系 Willy Tarreau 。
+
+Linux 2.6:
+	除了遵循和 2.4 版内核同样的规则外，你还需要在 linux-kernel 邮件
+	列表上跟踪最新的 API 变化。向 Linux 2.6 内核提交驱动的顶级联系人
+	是 Andrew Morton 。
+
+决定设备驱动能否被接受的条件
+----------------------------
+
+许可：		代码必须使用 GNU 通用公开许可证 (GPL) 提交给 Linux，但是
+		我们并不要求 GPL 是唯一的许可。你或许会希望同时使用多种
+		许可证发布，如果希望驱动程序可以被其他开源社区（比如BSD）
+		使用。请参考 include/linux/module.h 文件中所列出的可被
+		接受共存的许可。
+
+版权：		版权所有者必须同意使用 GPL 许可。最好提交者和版权所有者
+		是相同个人或实体。否则，必需列出授权使用 GPL 的版权所有
+		人或实体，以备验证之需。
+
+接口：		如果你的驱动程序使用现成的接口并且和其他同类的驱动程序行
+		为相似，而不是去发明无谓的新接口，那么它将会更容易被接受。
+		如果你需要一个 Linux 和 NT 的通用驱动接口，那么请在用
+		户空间实现它。
+
+代码：		请使用 Documentation/process/coding-style.rst 中所描述的 Linux 代码风
+		格。如果你的某些代码段（例如那些与 Windows 驱动程序包共
+		享的代码段）需要使用其他格式，而你却只希望维护一份代码，
+		那么请将它们很好地区分出来，并且注明原因。
+
+可移植性：	请注意，指针并不永远是 32 位的，不是所有的计算机都使用小
+		尾模式 (little endian) 存储数据，不是所有的人都拥有浮点
+		单元，不要随便在你的驱动程序里嵌入 x86 汇编指令。只能在
+		x86 上运行的驱动程序一般是不受欢迎的。虽然你可能只有 x86
+		硬件，很难测试驱动程序在其他平台上是否可用，但是确保代码
+		可以被轻松地移植却是很简单的。
+
+清晰度：	做到所有人都能修补这个驱动程序将会很有好处，因为这样你将
+		会直接收到修复的补丁而不是 bug 报告。如果你提交一个试图
+		隐藏硬件工作机理的驱动程序，那么它将会被扔进废纸篓。
+
+电源管理：	因为 Linux 正在被很多移动设备和桌面系统使用，所以你的驱
+		动程序也很有可能被使用在这些设备上。它应该支持最基本的电
+		源管理，即在需要的情况下实现系统级休眠和唤醒要用到的
+		.suspend 和 .resume 函数。你应该检查你的驱动程序是否能正
+		确地处理休眠与唤醒，如果实在无法确认，请至少把 .suspend
+		函数定义成返回 -ENOSYS（功能未实现）错误。你还应该尝试确
+		保你的驱动在什么都不干的情况下将耗电降到最低。要获得驱动
+		程序测试的指导，请参阅
+		Documentation/power/drivers-testing.txt。有关驱动程序电
+		源管理问题相对全面的概述，请参阅
+		Documentation/power/admin-guide/devices.rst。
+
+管理：		如果一个驱动程序的作者还在进行有效的维护，那么通常除了那
+		些明显正确且不需要任何检查的补丁以外，其他所有的补丁都会
+		被转发给作者。如果你希望成为驱动程序的联系人和更新者，最
+		好在代码注释中写明并且在 MAINTAINERS 文件中加入这个驱动
+		程序的条目。
+
+不影响设备驱动能否被接受的条件
+------------------------------
+
+供应商：	由硬件供应商来维护驱动程序通常是一件好事。不过，如果源码
+		树里已经有其他人提供了可稳定工作的驱动程序，那么请不要期
+		望“我是供应商”会成为内核改用你的驱动程序的理由。理想的情
+		况是：供应商与现有驱动程序的作者合作，构建一个统一完美的
+		驱动程序。
+
+作者：		驱动程序是由大的 Linux 公司研发还是由你个人编写，并不影
+		响其是否能被内核接受。没有人对内核源码树享有特权。只要你
+		充分了解内核社区，你就会发现这一点。
+
+
+资源列表
+--------
+
+Linux 内核主源码树：
+	ftp.??.kernel.org:/pub/linux/kernel/...
+	?? == 你的国家代码，例如 "cn"、"us"、"uk"、"fr" 等等
+
+Linux 内核邮件列表：
+	linux-kernel@vger.kernel.org
+	[可通过向majordomo@vger.kernel.org发邮件来订阅]
+
+Linux 设备驱动程序，第三版（探讨 2.6.10 版内核）：
+	http://lwn.net/Kernel/LDD3/ （免费版）
+
+LWN.net:
+	每周内核开发活动摘要 - http://lwn.net/
+	2.6 版中 API 的变更：
+		http://lwn.net/Articles/2.6-kernel-api/
+	将旧版内核的驱动程序移植到 2.6 版：
+		http://lwn.net/Articles/driver-porting/
+
+内核新手(KernelNewbies):
+	为新的内核开发者提供文档和帮助
+	http://kernelnewbies.org/
+
+Linux USB项目：
+	http://www.linux-usb.org/
+
+写内核驱动的“不要”（Arjan van de Ven著）:
+	http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf
+
+内核清洁工 (Kernel Janitor):
+	http://kernelnewbies.org/KernelJanitors
diff --git a/Documentation/translations/zh_CN/SubmittingPatches b/Documentation/translations/zh_CN/SubmittingPatches
new file mode 100644
index 000000000000..e9098da8f1a4
--- /dev/null
+++ b/Documentation/translations/zh_CN/SubmittingPatches
@@ -0,0 +1,412 @@
+Chinese translated version of Documentation/process/submitting-patches.rst
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Chinese maintainer: TripleX Chung 
+---------------------------------------------------------------------
+Documentation/process/submitting-patches.rst 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+中文版维护者： 钟宇 TripleX Chung 
+中文版翻译者： 钟宇 TripleX Chung 
+中文版校译者： 李阳 Li Yang 
+               王聪 Wang Cong 
+
+以下为正文
+---------------------------------------------------------------------
+
+   如何让你的改动进入内核
+     或者
+  获得亲爱的 Linus Torvalds 的关注和处理
+----------------------------------
+
+对于想要将改动提交到 Linux 内核的个人或者公司来说，如果不熟悉“规矩”，
+提交的流程会让人畏惧。本文档收集了一系列建议，这些建议可以大大的提高你
+的改动被接受的机会。
+阅读 Documentation/process/submit-checklist.rst 来获得在提交代码前需要检查的项目的列
+表。如果你在提交一个驱动程序，那么同时阅读一下
+Documentation/process/submitting-drivers.rst 。
+
+
+--------------------------
+第一节 - 创建并发送你的改动
+--------------------------
+
+1) "diff -up"
+-----------
+
+使用 "diff -up" 或者 "diff -uprN" 来创建补丁。
+
+所有内核的改动，都是以补丁的形式呈现的，补丁由 diff(1) 生成。创建补丁的
+时候，要确认它是以 "unified diff" 格式创建的，这种格式由 diff(1) 的 '-u'
+参数生成。而且，请使用 '-p' 参数，那样会显示每个改动所在的C函数，使得
+产生的补丁容易读得多。补丁应该基于内核源代码树的根目录，而不是里边的任
+何子目录。
+为一个单独的文件创建补丁，一般来说这样做就够了：
+
+        SRCTREE= linux-2.6
+        MYFILE=  drivers/net/mydriver.c
+
+        cd $SRCTREE
+        cp $MYFILE $MYFILE.orig
+        vi $MYFILE      # make your change
+        cd ..
+        diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
+
+为多个文件创建补丁，你可以解开一个没有修改过的内核源代码树，然后和你自
+己的代码树之间做 diff 。例如：
+
+        MYSRC= /devel/linux-2.6
+
+        tar xvfz linux-2.6.12.tar.gz
+        mv linux-2.6.12 linux-2.6.12-vanilla
+        diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \
+                linux-2.6.12-vanilla $MYSRC > /tmp/patch
+
+"dontdiff" 是内核在编译的时候产生的文件的列表，列表中的文件在 diff(1)
+产生的补丁里会被跳过。"dontdiff" 文件被包含在2.6.12和之后版本的内核源代
+码树中。对于更早的内核版本，你可以从
+ 获取它。
+确定你的补丁里没有包含任何不属于这次补丁提交的额外文件。记得在用diff(1)
+生成补丁之后，审阅一次补丁，以确保准确。
+如果你的改动很散乱，你应该研究一下如何将补丁分割成独立的部分，将改动分
+割成一系列合乎逻辑的步骤。这样更容易让其他内核开发者审核，如果你想你的
+补丁被接受，这是很重要的。下面这些脚本能够帮助你做这件事情：
+Quilt:
+http://savannah.nongnu.org/projects/quilt
+
+2)描述你的改动。
+描述你的改动包含的技术细节。
+
+要多具体就写多具体。最糟糕的描述可能是像下面这些语句：“更新了某驱动程
+序”，“修正了某驱动程序的bug”，或者“这个补丁包含了某子系统的修改，请
+使用。”
+
+如果你的描述开始变长，这表示你也许需要拆分你的补丁了，请看第3小节，
+继续。
+
+3)拆分你的改动
+
+将改动拆分，逻辑类似的放到同一个补丁文件里。
+
+例如，如果你的改动里同时有bug修正和性能优化，那么把这些改动拆分到两个或
+者更多的补丁文件中。如果你的改动包含对API的修改，并且修改了驱动程序来适
+应这些新的API，那么把这些修改分成两个补丁。
+
+另一方面，如果你将一个单独的改动做成多个补丁文件，那么将它们合并成一个
+单独的补丁文件。这样一个逻辑上单独的改动只被包含在一个补丁文件里。
+
+如果有一个补丁依赖另外一个补丁来完成它的改动，那没问题。简单的在你的补
+丁描述里指出“这个补丁依赖某补丁”就好了。
+
+如果你不能将补丁浓缩成更少的文件，那么每次大约发送出15个，然后等待审查
+和整合。
+
+4)选择 e-mail 的收件人
+
+看一遍 MAINTAINERS 文件和源代码，看看你所的改动所在的内核子系统有没有指
+定的维护者。如果有，给他们发e-mail。
+
+如果没有找到维护者，或者维护者没有反馈，将你的补丁发送到内核开发者主邮
+件列表 linux-kernel@vger.kernel.org。大部分的内核开发者都跟踪这个邮件列
+表，可以评价你的改动。
+
+每次不要发送超过15个补丁到 vger 邮件列表！！！
+
+Linus Torvalds 是决定改动能否进入 Linux 内核的最终裁决者。他的 e-mail
+地址是  。他收到的 e-mail 很多，所以一般
+的说，最好别给他发 e-mail。
+
+那些修正bug，“显而易见”的修改或者是类似的只需要很少讨论的补丁可以直接
+发送或者CC给Linus。那些需要讨论或者没有很清楚的好处的补丁，一般先发送到
+linux-kernel邮件列表。只有当补丁被讨论得差不多了，才提交给Linus。
+
+5)选择CC( e-mail 抄送)列表
+
+除非你有理由不这样做，否则CC linux-kernel@vger.kernel.org。
+
+除了 Linus 之外，其他内核开发者也需要注意到你的改动，这样他们才能评论你
+的改动并提供代码审查和建议。linux-kernel 是 Linux 内核开发者主邮件列表
+。其它的邮件列表为特定的子系统提供服务，比如 USB，framebuffer 设备，虚
+拟文件系统，SCSI 子系统，等等。查看 MAINTAINERS 文件来获得和你的改动有
+关的邮件列表。
+
+Majordomo lists of VGER.KERNEL.ORG at:
+        
+
+如果改动影响了用户空间和内核之间的接口，请给 MAN-PAGES 的维护者（列在
+MAINTAINERS 文件里的）发送一个手册页（man-pages）补丁，或者至少通知一下改
+变，让一些信息有途径进入手册页。
+
+即使在第四步的时候，维护者没有作出回应，也要确认在修改他们的代码的时候
+，一直将维护者拷贝到CC列表中。
+
+对于小的补丁，你也许会CC到 Adrian Bunk 管理的搜集琐碎补丁的邮件列表
+(Trivial Patch Monkey)trivial@kernel.org，那里专门收集琐碎的补丁。下面这样
+的补丁会被看作“琐碎的”补丁：
+  文档的拼写修正。
+  修正会影响到 grep(1) 的拼写。
+  警告信息修正(频繁的打印无用的警告是不好的。)
+  编译错误修正（代码逻辑的确是对的，只是编译有问题。）
+  运行时修正（只要真的修正了错误。）
+  移除使用了被废弃的函数/宏的代码(例如 check_region。)
+  联系方式和文档修正。
+  用可移植的代码替换不可移植的代码（即使在体系结构相关的代码中，既然有
+  人拷贝，只要它是琐碎的）
+  任何文件的作者/维护者对该文件的改动（例如 patch monkey 在重传模式下）
+
+EMAIL: trivial@kernel.org
+
+(译注，关于“琐碎补丁”的一些说明：因为原文的这一部分写得比较简单，所以不得不
+违例写一下译注。"trivial"这个英文单词的本意是“琐碎的，不重要的。”但是在这里
+有稍微有一些变化，例如对一些明显的NULL指针的修正，属于运行时修正，会被归类
+到琐碎补丁里。虽然NULL指针的修正很重要，但是这样的修正往往很小而且很容易得到
+检验，所以也被归入琐碎补丁。琐碎补丁更精确的归类应该是
+“simple, localized & easy to verify”，也就是说简单的，局部的和易于检验的。
+trivial@kernel.org邮件列表的目的是针对这样的补丁，为提交者提供一个中心，来
+降低提交的门槛。)
+
+6)没有 MIME 编码，没有链接，没有压缩，没有附件，只有纯文本。
+
+Linus 和其他的内核开发者需要阅读和评论你提交的改动。对于内核开发者来说
+，可以“引用”你的改动很重要，使用一般的 e-mail 工具，他们就可以在你的
+代码的任何位置添加评论。
+
+因为这个原因，所有的提交的补丁都是 e-mail 中“内嵌”的。
+警告：如果你使用剪切-粘贴你的补丁，小心你的编辑器的自动换行功能破坏你的
+补丁。
+
+不要将补丁作为 MIME 编码的附件，不管是否压缩。很多流行的 e-mail 软件不
+是任何时候都将 MIME 编码的附件当作纯文本发送的，这会使得别人无法在你的
+代码中加评论。另外，MIME 编码的附件会让 Linus 多花一点时间来处理，这就
+降低了你的改动被接受的可能性。
+
+警告：一些邮件软件，比如 Mozilla 会将你的信息以如下格式发送：
+---- 邮件头 ----
+Content-Type: text/plain; charset=us-ascii; format=flowed
+---- 邮件头 ----
+问题在于 “format=flowed” 会让接收端的某些邮件软件将邮件中的制表符替换
+成空格以及做一些类似的替换。这样，你发送的时候看起来没问题的补丁就被破
+坏了。
+
+要修正这个问题，只需要将你的 mozilla 的 defaults/pref/mailnews.js 文件
+里的
+pref("mailnews.send_plaintext_flowed", false); // RFC 2646=======
+修改成
+pref("mailnews.display.disable_format_flowed_support", true);
+就可以了。
+
+7) e-mail 的大小
+
+给 Linus 发送补丁的时候，永远按照第6小节说的做。
+
+大的改动对邮件列表不合适，对某些维护者也不合适。如果你的补丁，在不压缩
+的情况下，超过了40kB，那么你最好将补丁放在一个能通过 internet 访问的服
+务器上，然后用指向你的补丁的 URL 替代。
+
+8) 指出你的内核版本
+
+在标题和在补丁的描述中，指出补丁对应的内核的版本，是很重要的。
+
+如果补丁不能干净的在最新版本的内核上打上，Linus 是不会接受它的。
+
+9) 不要气馁，继续提交。
+
+当你提交了改动以后，耐心地等待。如果 Linus 喜欢你的改动并且同意它，那么
+它将在下一个内核发布版本中出现。
+
+然而，如果你的改动没有出现在下一个版本的内核中，可能有若干原因。减少那
+些原因，修正错误，重新提交更新后的改动，是你自己的工作。
+
+Linus不给出任何评论就“丢弃”你的补丁是常见的事情。在系统中这样的事情很
+平常。如果他没有接受你的补丁，也许是由于以下原因：
+* 你的补丁不能在最新版本的内核上干净的打上。
+* 你的补丁在 linux-kernel 邮件列表中没有得到充分的讨论。
+* 风格问题（参照第2小节）
+* 邮件格式问题（重读本节）
+* 你的改动有技术问题。
+* 他收到了成吨的 e-mail，而你的在混乱中丢失了。
+* 你让人为难。
+
+有疑问的时候，在 linux-kernel 邮件列表上请求评论。
+
+10) 在标题上加上 PATCH 的字样
+
+Linus 和 linux-kernel 邮件列表的 e-mail 流量都很高，一个通常的约定是标
+题行以 [PATCH] 开头。这样可以让 Linus 和其他内核开发人员可以从 e-mail
+的讨论中很轻易的将补丁分辨出来。
+
+11）为你的工作签名
+
+为了加强对谁做了何事的追踪，尤其是对那些透过好几层的维护者的补丁，我们
+建议在发送出去的补丁上加一个 “sign-off” 的过程。
+
+"sign-off" 是在补丁的注释的最后的简单的一行文字，认证你编写了它或者其他
+人有权力将它作为开放源代码的补丁传递。规则很简单：如果你能认证如下信息
+：
+      开发者来源证书 1.1
+      对于本项目的贡献，我认证如下信息：
+      （a）这些贡献是完全或者部分的由我创建，我有权利以文件中指出
+       的开放源代码许可证提交它；或者
+      （b）这些贡献基于以前的工作，据我所知，这些以前的工作受恰当的开放
+       源代码许可证保护，而且，根据许可证，我有权提交修改后的贡献，
+       无论是完全还是部分由我创造，这些贡献都使用同一个开放源代码许可证
+       （除非我被允许用其它的许可证），正如文件中指出的；或者
+      （c）这些贡献由认证（a），（b）或者（c）的人直接提供给我，而
+       且我没有修改它。
+      （d）我理解并同意这个项目和贡献是公开的，贡献的记录（包括我
+       一起提交的个人记录，包括 sign-off ）被永久维护并且可以和这个项目
+       或者开放源代码的许可证同步地再发行。
+       那么加入这样一行：
+       Signed-off-by: Random J Developer 
+
+使用你的真名（抱歉，不能使用假名或者匿名。）
+
+有人在最后加上标签。现在这些东西会被忽略，但是你可以这样做，来标记公司
+内部的过程，或者只是指出关于 sign-off 的一些特殊细节。
+
+12）标准补丁格式
+
+标准的补丁，标题行是：
+    Subject: [PATCH 001/123] 子系统:一句话概述
+
+标准补丁的信体存在如下部分：
+
+  - 一个 "from" 行指出补丁作者。
+
+  - 一个空行
+
+  - 说明的主体，这些说明文字会被拷贝到描述该补丁的永久改动记录里。
+
+  - 一个由"---"构成的标记行
+
+  - 不合适放到改动记录里的额外的注解。
+
+  - 补丁本身（diff 输出）
+
+标题行的格式，使得对标题行按字母序排序非常的容易 - 很多 e-mail 客户端都
+可以支持 - 因为序列号是用零填充的，所以按数字排序和按字母排序是一样的。
+
+e-mail 标题中的“子系统”标识哪个内核子系统将被打补丁。
+
+e-mail 标题中的“一句话概述”扼要的描述 e-mail 中的补丁。“一句话概述”
+不应该是一个文件名。对于一个补丁系列（“补丁系列”指一系列的多个相关补
+丁），不要对每个补丁都使用同样的“一句话概述”。
+
+记住 e-mail 的“一句话概述”会成为该补丁的全局唯一标识。它会蔓延到 git
+的改动记录里。然后“一句话概述”会被用在开发者的讨论里，用来指代这个补
+丁。用户将希望通过 google 来搜索"一句话概述"来找到那些讨论这个补丁的文
+章。
+
+一些标题的例子：
+
+    Subject: [patch 2/5] ext2: improve scalability of bitmap searching
+    Subject: [PATCHv2 001/207] x86: fix eflags tracking
+
+"from" 行是信体里的最上面一行，具有如下格式：
+        From: Original Author 
+
+"from" 行指明在永久改动日志里，谁会被确认为作者。如果没有 "from" 行，那
+么邮件头里的 "From: " 行会被用来决定改动日志中的作者。
+
+说明的主题将会被提交到永久的源代码改动日志里，因此对那些早已经不记得和
+这个补丁相关的讨论细节的有能力的读者来说，是有意义的。
+
+"---" 标记行对于补丁处理工具要找到哪里是改动日志信息的结束，是不可缺少
+的。
+
+对于 "---" 标记之后的额外注解，一个好的用途就是用来写 diffstat，用来显
+示修改了什么文件和每个文件都增加和删除了多少行。diffstat 对于比较大的补
+丁特别有用。其余那些只是和时刻或者开发者相关的注解，不合适放到永久的改
+动日志里的，也应该放这里。
+使用 diffstat的选项 "-p 1 -w 70" 这样文件名就会从内核源代码树的目录开始
+，不会占用太宽的空间（很容易适合80列的宽度，也许会有一些缩进。）
+
+在后面的参考资料中能看到适当的补丁格式的更多细节。
+
+-------------------------------
+第二节 提示，建议和诀窍
+-------------------------------
+
+本节包含很多和提交到内核的代码有关的通常的"规则"。事情永远有例外...但是
+你必须真的有好的理由这样做。你可以把本节叫做Linus的计算机科学入门课。
+
+1) 读 Document/process/coding-style.rst
+
+Nuff 说过，如果你的代码和这个偏离太多，那么它有可能会被拒绝，没有更多的
+审查，没有更多的评价。
+
+2) #ifdef 是丑陋的
+混杂了 ifdef 的代码难以阅读和维护。别这样做。作为替代，将你的 ifdef 放
+在头文件里，有条件地定义 "static inline" 函数，或者宏，在代码里用这些东
+西。让编译器把那些"空操作"优化掉。
+
+一个简单的例子，不好的代码：
+
+    dev = alloc_etherdev (sizeof(struct funky_private));
+    if (!dev)
+        return -ENODEV;
+    #ifdef CONFIG_NET_FUNKINESS
+    init_funky_net(dev);
+    #endif
+
+清理后的例子:
+
+(头文件里)
+    #ifndef CONFIG_NET_FUNKINESS
+    static inline void init_funky_net (struct net_device *d) {}
+    #endif
+
+(代码文件里)
+    dev = alloc_etherdev (sizeof(struct funky_private));
+    if (!dev)
+        return -ENODEV;
+    init_funky_net(dev);
+
+3) 'static inline' 比宏好
+
+Static inline 函数相比宏来说，是好得多的选择。Static inline 函数提供了
+类型安全，没有长度限制，没有格式限制，在 gcc 下开销和宏一样小。
+
+宏只在 static inline 函数不是最优的时候[在 fast paths 里有很少的独立的
+案例]，或者不可能用 static inline 函数的时候[例如字符串分配]。
+应该用 'static inline' 而不是 'static __inline__', 'extern inline' 和
+'extern __inline__' 。
+
+4) 不要过度设计
+
+不要试图预计模糊的未来事情，这些事情也许有用也许没有用："让事情尽可能的
+简单，而不是更简单"。
+
+----------------
+第三节 参考文献
+----------------
+
+Andrew Morton, "The perfect patch" (tpp).
+  
+
+Jeff Garzik, "Linux kernel patch submission format".
+  
+
+Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
+  
+  
+  
+  
+
+NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
+  
+
+Kernel Documentation/process/coding-style.rst:
+  
+
+Linus Torvalds's mail on the canonical patch format:
+  
+--
diff --git a/Documentation/translations/zh_CN/arm/Booting b/Documentation/translations/zh_CN/arm/Booting
new file mode 100644
index 000000000000..1fe866f8218f
--- /dev/null
+++ b/Documentation/translations/zh_CN/arm/Booting
@@ -0,0 +1,175 @@
+Chinese translated version of Documentation/arm/Booting
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Maintainer: Russell King 
+Chinese maintainer: Fu Wei 
+---------------------------------------------------------------------
+Documentation/arm/Booting 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+英文版维护者： Russell King 
+中文版维护者： 傅炜  Fu Wei 
+中文版翻译者： 傅炜  Fu Wei 
+中文版校译者： 傅炜  Fu Wei 
+
+以下为正文
+---------------------------------------------------------------------
+
+			启动 ARM Linux
+			==============
+
+作者：Russell King
+日期：2002年5月18日
+
+以下文档适用于 2.4.18-rmk6 及以上版本。
+
+为了启动 ARM Linux，你需要一个引导装载程序（boot loader），
+它是一个在主内核启动前运行的一个小程序。引导装载程序需要初始化各种
+设备，并最终调用 Linux 内核，将信息传递给内核。
+
+从本质上讲，引导装载程序应提供（至少）以下功能：
+
+1、设置和初始化 RAM。
+2、初始化一个串口。
+3、检测机器的类型（machine type）。
+4、设置内核标签列表（tagged list）。
+5、调用内核映像。
+
+
+1、设置和初始化 RAM
+-------------------
+
+现有的引导加载程序:		强制
+新开发的引导加载程序:		强制
+
+引导装载程序应该找到并初始化系统中所有内核用于保持系统变量数据的 RAM。
+这个操作的执行是设备依赖的。（它可能使用内部算法来自动定位和计算所有
+RAM，或可能使用对这个设备已知的 RAM 信息，还可能使用任何引导装载程序
+设计者想到的匹配方法。）
+
+
+2、初始化一个串口
+-----------------------------
+
+现有的引导加载程序:		可选、建议
+新开发的引导加载程序:		可选、建议
+
+引导加载程序应该初始化并使能一个目标板上的串口。这允许内核串口驱动
+自动检测哪个串口用于内核控制台。(一般用于调试或与目标板通信。)
+
+作为替代方案，引导加载程序也可以通过标签列表传递相关的'console='
+选项给内核以指定某个串口，而串口数据格式的选项在以下文档中描述：
+
+       Documentation/admin-guide/kernel-parameters.rst。
+
+
+3、检测机器类型
+--------------------------
+
+现有的引导加载程序:		可选
+新开发的引导加载程序:		强制
+
+引导加载程序应该通过某些方式检测自身所处的机器类型。这是一个硬件
+代码或通过查看所连接的硬件用某些算法得到，这些超出了本文档的范围。
+引导加载程序最终必须能提供一个 MACH_TYPE_xxx 值给内核。
+(详见 linux/arch/arm/tools/mach-types )。
+
+4、设置启动数据
+------------------
+
+现有的引导加载程序:		可选、强烈建议
+新开发的引导加载程序:		强制
+
+引导加载程序必须提供标签列表或者 dtb 映像以传递配置数据给内核。启动
+数据的物理地址通过寄存器 r2 传递给内核。
+
+4a、设置内核标签列表
+--------------------------------
+
+bootloader 必须创建和初始化内核标签列表。一个有效的标签列表以
+ATAG_CORE 标签开始，并以 ATAG_NONE 标签结束。ATAG_CORE 标签可以是
+空的，也可以是非空。一个空 ATAG_CORE 标签其 size 域设置为
+‘2’(0x00000002)。ATAG_NONE 标签的 size 域必须设置为零。
+
+在列表中可以保存任意数量的标签。对于一个重复的标签是追加到之前标签
+所携带的信息之后，还是会覆盖原来的信息，是未定义的。某些标签的行为
+是前者，其他是后者。
+
+bootloader 必须传递一个系统内存的位置和最小值，以及根文件系统位置。
+因此，最小的标签列表如下所示：
+
+		+-----------+
+基地址 ->	| ATAG_CORE |  |
+		+-----------+  |
+		| ATAG_MEM  |  | 地址增长方向
+		+-----------+  |
+		| ATAG_NONE |  |
+		+-----------+  v
+
+标签列表应该保存在系统的 RAM 中。
+
+标签列表必须置于内核自解压和 initrd'bootp' 程序都不会覆盖的内存区。
+建议放在 RAM 的头 16KiB 中。
+
+4b、设置设备树
+-------------------------
+
+bootloader 必须以 64bit 地址对齐的形式加载一个设备树映像(dtb)到系统
+RAM 中，并用启动数据初始化它。dtb 格式在文档
+Documentation/devicetree/booting-without-of.txt 中。内核将会在
+dtb 物理地址处查找 dtb 魔数值（0xd00dfeed），以确定 dtb 是否已经代替
+标签列表被传递进来。
+
+bootloader 必须传递一个系统内存的位置和最小值，以及根文件系统位置。
+dtb 必须置于内核自解压不会覆盖的内存区。建议将其放置于 RAM 的头 16KiB
+中。但是不可将其放置于“0”物理地址处，因为内核认为：r2 中为 0，意味着
+没有标签列表和 dtb 传递过来。
+
+5、调用内核映像
+---------------------------
+
+现有的引导加载程序:		强制
+新开发的引导加载程序:		强制
+
+调用内核映像 zImage 有两个选择。如果 zImge 保存在 flash 中，且是为了
+在 flash 中直接运行而被正确链接的。这样引导加载程序就可以在 flash 中
+直接调用 zImage。
+
+zImage 也可以被放在系统 RAM（任意位置）中被调用。注意：内核使用映像
+基地址的前 16KB RAM 空间来保存页表。建议将映像置于 RAM 的 32KB 处。
+
+对于以上任意一种情况，都必须符合以下启动状态：
+
+- 停止所有 DMA 设备，这样内存数据就不会因为虚假网络包或磁盘数据而被破坏。
+  这可能可以节省你许多的调试时间。
+
+- CPU 寄存器配置
+  r0 = 0，
+  r1 = （在上面 3 中获取的）机器类型码。
+  r2 = 标签列表在系统 RAM 中的物理地址，或
+       设备树块(dtb)在系统 RAM 中的物理地址
+
+- CPU 模式
+  所有形式的中断必须被禁止 (IRQs 和 FIQs)
+  CPU 必须处于 SVC 模式。(对于 Angel 调试有特例存在)
+
+- 缓存，MMUs
+  MMU 必须关闭。
+  指令缓存开启或关闭都可以。
+  数据缓存必须关闭。
+
+- 引导加载程序应该通过直接跳转到内核映像的第一条指令来调用内核映像。
+
+  对于支持 ARM 指令集的 CPU，跳入内核入口时必须处在 ARM 状态，即使
+  对于 Thumb-2 内核也是如此。
+
+  对于仅支持 Thumb 指令集的 CPU，比如 Cortex-M 系列的 CPU，跳入
+  内核入口时必须处于 Thumb 状态。
diff --git a/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt b/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt
new file mode 100644
index 000000000000..cd7fc8f34cf9
--- /dev/null
+++ b/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt
@@ -0,0 +1,284 @@
+Chinese translated version of Documentation/arm/kernel_user_helpers.txt
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Maintainer: Nicolas Pitre 
+		Dave Martin 
+Chinese maintainer: Fu Wei 
+---------------------------------------------------------------------
+Documentation/arm/kernel_user_helpers.txt 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+英文版维护者： Nicolas Pitre 
+		Dave Martin 
+中文版维护者： 傅炜 Fu Wei 
+中文版翻译者： 傅炜 Fu Wei 
+中文版校译者： 宋冬生 Dongsheng Song 
+		傅炜 Fu Wei 
+
+
+以下为正文
+---------------------------------------------------------------------
+内核提供的用户空间辅助代码
+=========================
+
+在内核内存空间的固定地址处，有一个由内核提供并可从用户空间访问的代码
+段。它用于向用户空间提供因在许多 ARM CPU 中未实现的特性和/或指令而需
+内核提供帮助的某些操作。这些代码直接在用户模式下执行的想法是为了获得
+最佳效率，但那些与内核计数器联系过于紧密的部分，则被留给了用户库实现。
+事实上，此代码甚至可能因不同的 CPU 而异，这取决于其可用的指令集或它
+是否为 SMP 系统。换句话说，内核保留在不作出警告的情况下根据需要更改
+这些代码的权利。只有本文档描述的入口及其结果是保证稳定的。
+
+这与完全成熟的 VDSO 实现不同（但两者并不冲突），尽管如此，VDSO 可阻止
+某些通过常量高效跳转到那些代码段的汇编技巧。且由于那些代码段在返回用户
+代码前仅使用少量的代码周期，则一个 VDSO 间接远程调用将会在这些简单的
+操作上增加一个可测量的开销。
+
+在对那些拥有原生支持的新型处理器进行代码优化时，仅在已为其他操作使用
+了类似的新增指令，而导致二进制结果已与早期 ARM 处理器不兼容的情况下，
+用户空间才应绕过这些辅助代码，并在内联函数中实现这些操作（无论是通过
+编译器在代码中直接放置，还是作为库函数调用实现的一部分）。也就是说，
+如果你编译的代码不会为了其他目的使用新指令，则不要仅为了避免使用这些
+内核辅助代码，导致二进制程序无法在早期处理器上运行。
+
+新的辅助代码可能随着时间的推移而增加，所以新内核中的某些辅助代码在旧
+内核中可能不存在。因此，程序必须在对任何辅助代码调用假设是安全之前，
+检测 __kuser_helper_version 的值（见下文）。理想情况下，这种检测应该
+只在进程启动时执行一次；如果内核版本不支持所需辅助代码，则该进程可尽早
+中止执行。
+
+kuser_helper_version
+--------------------
+
+位置:	0xffff0ffc
+
+参考声明:
+
+  extern int32_t __kuser_helper_version;
+
+定义:
+
+  这个区域包含了当前运行内核实现的辅助代码版本号。用户空间可以通过读
+  取此版本号以确定特定的辅助代码是否存在。
+
+使用范例:
+
+#define __kuser_helper_version (*(int32_t *)0xffff0ffc)
+
+void check_kuser_version(void)
+{
+	if (__kuser_helper_version < 2) {
+		fprintf(stderr, "can't do atomic operations, kernel too old\n");
+		abort();
+	}
+}
+
+注意:
+
+  用户空间可以假设这个域的值不会在任何单个进程的生存期内改变。也就
+  是说，这个域可以仅在库的初始化阶段或进程启动阶段读取一次。
+
+kuser_get_tls
+-------------
+
+位置:	0xffff0fe0
+
+参考原型:
+
+  void * __kuser_get_tls(void);
+
+输入:
+
+  lr = 返回地址
+
+输出:
+
+  r0 = TLS 值
+
+被篡改的寄存器:
+
+  无
+
+定义:
+
+  获取之前通过 __ARM_NR_set_tls 系统调用设置的 TLS 值。
+
+使用范例:
+
+typedef void * (__kuser_get_tls_t)(void);
+#define __kuser_get_tls (*(__kuser_get_tls_t *)0xffff0fe0)
+
+void foo()
+{
+	void *tls = __kuser_get_tls();
+	printf("TLS = %p\n", tls);
+}
+
+注意:
+
+  - 仅在 __kuser_helper_version >= 1 时，此辅助代码存在
+    （从内核版本 2.6.12 开始）。
+
+kuser_cmpxchg
+-------------
+
+位置:	0xffff0fc0
+
+参考原型:
+
+  int __kuser_cmpxchg(int32_t oldval, int32_t newval, volatile int32_t *ptr);
+
+输入:
+
+  r0 = oldval
+  r1 = newval
+  r2 = ptr
+  lr = 返回地址
+
+输出:
+
+  r0 = 成功代码 (零或非零)
+  C flag = 如果 r0 == 0 则置 1，如果 r0 != 0 则清零。
+
+被篡改的寄存器:
+
+  r3, ip, flags
+
+定义:
+
+  仅在 *ptr 为 oldval 时原子保存 newval 于 *ptr 中。
+  如果 *ptr 被改变，则返回值为零，否则为非零值。
+  如果 *ptr 被改变，则 C flag 也会被置 1，以实现调用代码中的汇编
+  优化。
+
+使用范例:
+
+typedef int (__kuser_cmpxchg_t)(int oldval, int newval, volatile int *ptr);
+#define __kuser_cmpxchg (*(__kuser_cmpxchg_t *)0xffff0fc0)
+
+int atomic_add(volatile int *ptr, int val)
+{
+	int old, new;
+
+	do {
+		old = *ptr;
+		new = old + val;
+	} while(__kuser_cmpxchg(old, new, ptr));
+
+	return new;
+}
+
+注意:
+
+  - 这个例程已根据需要包含了内存屏障。
+
+  - 仅在 __kuser_helper_version >= 2 时，此辅助代码存在
+    （从内核版本 2.6.12 开始）。
+
+kuser_memory_barrier
+--------------------
+
+位置:	0xffff0fa0
+
+参考原型:
+
+  void __kuser_memory_barrier(void);
+
+输入:
+
+  lr = 返回地址
+
+输出:
+
+  无
+
+被篡改的寄存器:
+
+  无
+
+定义:
+
+  应用于任何需要内存屏障以防止手动数据修改带来的一致性问题，以及
+  __kuser_cmpxchg 中。
+
+使用范例:
+
+typedef void (__kuser_dmb_t)(void);
+#define __kuser_dmb (*(__kuser_dmb_t *)0xffff0fa0)
+
+注意:
+
+  - 仅在 __kuser_helper_version >= 3 时，此辅助代码存在
+    （从内核版本 2.6.15 开始）。
+
+kuser_cmpxchg64
+---------------
+
+位置:	0xffff0f60
+
+参考原型:
+
+  int __kuser_cmpxchg64(const int64_t *oldval,
+                        const int64_t *newval,
+                        volatile int64_t *ptr);
+
+输入:
+
+  r0 = 指向 oldval
+  r1 = 指向 newval
+  r2 = 指向目标值
+  lr = 返回地址
+
+输出:
+
+  r0 = 成功代码 (零或非零)
+  C flag = 如果 r0 == 0 则置 1，如果 r0 != 0 则清零。
+
+被篡改的寄存器:
+
+  r3, lr, flags
+
+定义:
+
+  仅在 *ptr 等于 *oldval 指向的 64 位值时，原子保存 *newval
+  指向的 64 位值于 *ptr 中。如果 *ptr 被改变，则返回值为零，
+  否则为非零值。
+
+  如果 *ptr 被改变，则 C flag 也会被置 1，以实现调用代码中的汇编
+  优化。
+
+使用范例:
+
+typedef int (__kuser_cmpxchg64_t)(const int64_t *oldval,
+                                  const int64_t *newval,
+                                  volatile int64_t *ptr);
+#define __kuser_cmpxchg64 (*(__kuser_cmpxchg64_t *)0xffff0f60)
+
+int64_t atomic_add64(volatile int64_t *ptr, int64_t val)
+{
+	int64_t old, new;
+
+	do {
+		old = *ptr;
+		new = old + val;
+	} while(__kuser_cmpxchg64(&old, &new, ptr));
+
+	return new;
+}
+
+注意:
+
+  - 这个例程已根据需要包含了内存屏障。
+
+  - 由于这个过程的代码长度（此辅助代码跨越 2 个常规的 kuser “槽”），
+    因此 0xffff0f80 不被作为有效的入口点。
+
+  - 仅在 __kuser_helper_version >= 5 时，此辅助代码存在
+    （从内核版本 3.1 开始）。
diff --git a/Documentation/translations/zh_CN/arm64/booting.txt b/Documentation/translations/zh_CN/arm64/booting.txt
new file mode 100644
index 000000000000..c1dd968c5ee9
--- /dev/null
+++ b/Documentation/translations/zh_CN/arm64/booting.txt
@@ -0,0 +1,246 @@
+Chinese translated version of Documentation/arm64/booting.txt
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+M:	Will Deacon 
+zh_CN:	Fu Wei 
+C:	55f058e7574c3615dea4615573a19bdb258696c6
+---------------------------------------------------------------------
+Documentation/arm64/booting.txt 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+英文版维护者： Will Deacon 
+中文版维护者： 傅炜  Fu Wei 
+中文版翻译者： 傅炜  Fu Wei 
+中文版校译者： 傅炜  Fu Wei 
+本文翻译提交时的 Git 检出点为： 55f058e7574c3615dea4615573a19bdb258696c6
+
+以下为正文
+---------------------------------------------------------------------
+			启动 AArch64 Linux
+			==================
+
+作者: Will Deacon 
+日期: 2012 年 09 月 07 日
+
+本文档基于 Russell King 的 ARM 启动文档，且适用于所有公开发布的
+AArch64 Linux 内核代码。
+
+AArch64 异常模型由多个异常级（EL0 - EL3）组成，对于 EL0 和 EL1 异常级
+有对应的安全和非安全模式。EL2 是系统管理级，且仅存在于非安全模式下。
+EL3 是最高特权级，且仅存在于安全模式下。
+
+基于本文档的目的，我们将简单地使用‘引导装载程序’（‘boot loader’）
+这个术语来定义在将控制权交给 Linux 内核前 CPU 上执行的所有软件。
+这可能包含安全监控和系统管理代码，或者它可能只是一些用于准备最小启动
+环境的指令。
+
+基本上，引导装载程序（至少）应实现以下操作：
+
+1、设置和初始化 RAM
+2、设置设备树数据
+3、解压内核映像
+4、调用内核映像
+
+
+1、设置和初始化 RAM
+-----------------
+
+必要性: 强制
+
+引导装载程序应该找到并初始化系统中所有内核用于保持系统变量数据的 RAM。
+这个操作的执行方式因设备而异。（它可能使用内部算法来自动定位和计算所有
+RAM，或可能使用对这个设备已知的 RAM 信息，还可能是引导装载程序设计者
+想到的任何合适的方法。）
+
+
+2、设置设备树数据
+---------------
+
+必要性: 强制
+
+设备树数据块（dtb）必须 8 字节对齐，且大小不能超过 2MB。由于设备树
+数据块将在使能缓存的情况下以 2MB 粒度被映射，故其不能被置于带任意
+特定属性被映射的 2MB 区域内。
+
+注： v4.2 之前的版本同时要求设备树数据块被置于从内核映像以下
+text_offset 字节处算起第一个 512MB 内。
+
+3、解压内核映像
+-------------
+
+必要性: 可选
+
+AArch64 内核当前没有提供自解压代码，因此如果使用了压缩内核映像文件
+（比如 Image.gz），则需要通过引导装载程序（使用 gzip 等）来进行解压。
+若引导装载程序没有实现这个功能，就要使用非压缩内核映像文件。
+
+
+4、调用内核映像
+-------------
+
+必要性: 强制
+
+已解压的内核映像包含一个 64 字节的头，内容如下：
+
+  u32 code0;			/* 可执行代码 */
+  u32 code1;			/* 可执行代码 */
+  u64 text_offset;		/* 映像装载偏移，小端模式 */
+  u64 image_size;		/* 映像实际大小, 小端模式 */
+  u64 flags;			/* 内核旗标, 小端模式 *
+  u64 res2	= 0;		/* 保留 */
+  u64 res3	= 0;		/* 保留 */
+  u64 res4	= 0;		/* 保留 */
+  u32 magic	= 0x644d5241;	/* 魔数, 小端, "ARM\x64" */
+  u32 res5;			/* 保留 （用于 PE COFF 偏移） */
+
+
+映像头注释：
+
+- 自 v3.17 起，除非另有说明，所有域都是小端模式。
+
+- code0/code1 负责跳转到 stext.
+
+- 当通过 EFI 启动时， 最初 code0/code1 被跳过。
+  res5 是到 PE 文件头的偏移，而 PE 文件头含有 EFI 的启动入口点
+  （efi_stub_entry）。当 stub 代码完成了它的使命，它会跳转到 code0
+  继续正常的启动流程。
+
+- v3.17 之前，未明确指定 text_offset 的字节序。此时，image_size 为零，
+  且 text_offset 依照内核字节序为 0x80000。
+  当 image_size 非零，text_offset 为小端模式且是有效值，应被引导加载
+  程序使用。当 image_size 为零，text_offset 可假定为 0x80000。
+
+- flags 域 (v3.17 引入) 为 64 位小端模式，其编码如下：
+  位 0: 	内核字节序。 1 表示大端模式，0 表示小端模式。
+  位 1-2:	内核页大小。
+			0 - 未指定。
+			1 - 4K
+			2 - 16K
+			3 - 64K
+  位 3:		内核物理位置
+			0 - 2MB 对齐基址应尽量靠近内存起始处，因为
+			    其基址以下的内存无法通过线性映射访问
+			1 - 2MB 对齐基址可以在物理内存的任意位置
+  位 4-63:	保留。
+
+- 当 image_size 为零时，引导装载程序应试图在内核映像末尾之后尽可能
+  多地保留空闲内存供内核直接使用。对内存空间的需求量因所选定的内核
+  特性而异, 并无实际限制。
+
+内核映像必须被放置在任意一个可用系统内存 2MB 对齐基址的 text_offset
+字节处，并从该处被调用。2MB 对齐基址和内核映像起始地址之间的区域对于
+内核来说没有特殊意义，且可能被用于其他目的。
+从映像起始地址算起，最少必须准备 image_size 字节的空闲内存供内核使用。
+注： v4.6 之前的版本无法使用内核映像物理偏移以下的内存，所以当时建议
+将映像尽量放置在靠近系统内存起始的地方。
+
+任何提供给内核的内存（甚至在映像起始地址之前），若未从内核中标记为保留
+(如在设备树（dtb）的 memreserve 区域），都将被认为对内核是可用。
+
+在跳转入内核前，必须符合以下状态：
+
+- 停止所有 DMA 设备，这样内存数据就不会因为虚假网络包或磁盘数据而
+  被破坏。这可能可以节省你许多的调试时间。
+
+- 主 CPU 通用寄存器设置
+  x0 = 系统 RAM 中设备树数据块（dtb）的物理地址。
+  x1 = 0 (保留，将来可能使用)
+  x2 = 0 (保留，将来可能使用)
+  x3 = 0 (保留，将来可能使用)
+
+- CPU 模式
+  所有形式的中断必须在 PSTATE.DAIF 中被屏蔽（Debug、SError、IRQ
+  和 FIQ）。
+  CPU 必须处于 EL2（推荐，可访问虚拟化扩展）或非安全 EL1 模式下。
+
+- 高速缓存、MMU
+  MMU 必须关闭。
+  指令缓存开启或关闭皆可。
+  已载入的内核映像的相应内存区必须被清理，以达到缓存一致性点（PoC）。
+  当存在系统缓存或其他使能缓存的一致性主控器时，通常需使用虚拟地址
+  维护其缓存，而非 set/way 操作。
+  遵从通过虚拟地址操作维护构架缓存的系统缓存必须被配置，并可以被使能。
+  而不通过虚拟地址操作维护构架缓存的系统缓存（不推荐），必须被配置且
+  禁用。
+
+  *译者注：对于 PoC 以及缓存相关内容，请参考 ARMv8 构架参考手册
+   ARM DDI 0487A
+
+- 架构计时器
+  CNTFRQ 必须设定为计时器的频率，且 CNTVOFF 必须设定为对所有 CPU
+  都一致的值。如果在 EL1 模式下进入内核，则 CNTHCTL_EL2 中的
+  EL1PCTEN (bit 0) 必须置位。
+
+- 一致性
+  通过内核启动的所有 CPU 在内核入口地址上必须处于相同的一致性域中。
+  这可能要根据具体实现来定义初始化过程，以使能每个CPU上对维护操作的
+  接收。
+
+- 系统寄存器
+  在进入内核映像的异常级中，所有构架中可写的系统寄存器必须通过软件
+  在一个更高的异常级别下初始化，以防止在 未知 状态下运行。
+
+  对于拥有 GICv3 中断控制器并以 v3 模式运行的系统：
+  - 如果 EL3 存在：
+    ICC_SRE_EL3.Enable (位 3) 必须初始化为 0b1。
+    ICC_SRE_EL3.SRE (位 0) 必须初始化为 0b1。
+  - 若内核运行在 EL1：
+    ICC_SRE_EL2.Enable (位 3) 必须初始化为 0b1。
+    ICC_SRE_EL2.SRE (位 0) 必须初始化为 0b1。
+  - 设备树（DT）或 ACPI 表必须描述一个 GICv3 中断控制器。
+
+  对于拥有 GICv3 中断控制器并以兼容（v2）模式运行的系统：
+  - 如果 EL3 存在：
+    ICC_SRE_EL3.SRE (位 0) 必须初始化为 0b0。
+  - 若内核运行在 EL1：
+    ICC_SRE_EL2.SRE (位 0) 必须初始化为 0b0。
+  - 设备树（DT）或 ACPI 表必须描述一个 GICv2 中断控制器。
+
+以上对于 CPU 模式、高速缓存、MMU、架构计时器、一致性、系统寄存器的
+必要条件描述适用于所有 CPU。所有 CPU 必须在同一异常级别跳入内核。
+
+引导装载程序必须在每个 CPU 处于以下状态时跳入内核入口：
+
+- 主 CPU 必须直接跳入内核映像的第一条指令。通过此 CPU 传递的设备树
+  数据块必须在每个 CPU 节点中包含一个 ‘enable-method’ 属性，所
+  支持的 enable-method 请见下文。
+
+  引导装载程序必须生成这些设备树属性，并在跳入内核入口之前将其插入
+  数据块。
+
+- enable-method 为 “spin-table” 的 CPU 必须在它们的 CPU
+  节点中包含一个 ‘cpu-release-addr’ 属性。这个属性标识了一个
+  64 位自然对齐且初始化为零的内存位置。
+
+  这些 CPU 必须在内存保留区（通过设备树中的 /memreserve/ 域传递
+  给内核）中自旋于内核之外，轮询它们的 cpu-release-addr 位置（必须
+  包含在保留区中）。可通过插入 wfe 指令来降低忙循环开销，而主 CPU 将
+  发出 sev 指令。当对 cpu-release-addr 所指位置的读取操作返回非零值
+  时，CPU 必须跳入此值所指向的地址。此值为一个单独的 64 位小端值，
+  因此 CPU 须在跳转前将所读取的值转换为其本身的端模式。
+
+- enable-method 为 “psci” 的 CPU 保持在内核外（比如，在
+  memory 节点中描述为内核空间的内存区外，或在通过设备树 /memreserve/
+  域中描述为内核保留区的空间中）。内核将会发起在 ARM 文档（编号
+  ARM DEN 0022A：用于 ARM 上的电源状态协调接口系统软件）中描述的
+  CPU_ON 调用来将 CPU 带入内核。
+
+  *译者注: ARM DEN 0022A 已更新到 ARM DEN 0022C。
+
+  设备树必须包含一个 ‘psci’ 节点，请参考以下文档：
+  Documentation/devicetree/bindings/arm/psci.txt
+
+
+- 辅助 CPU 通用寄存器设置
+  x0 = 0 (保留，将来可能使用)
+  x1 = 0 (保留，将来可能使用)
+  x2 = 0 (保留，将来可能使用)
+  x3 = 0 (保留，将来可能使用)
diff --git a/Documentation/translations/zh_CN/arm64/legacy_instructions.txt b/Documentation/translations/zh_CN/arm64/legacy_instructions.txt
new file mode 100644
index 000000000000..68362a1ab717
--- /dev/null
+++ b/Documentation/translations/zh_CN/arm64/legacy_instructions.txt
@@ -0,0 +1,72 @@
+Chinese translated version of Documentation/arm64/legacy_instructions.txt
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Maintainer: Punit Agrawal 
+            Suzuki K. Poulose 
+Chinese maintainer: Fu Wei 
+---------------------------------------------------------------------
+Documentation/arm64/legacy_instructions.txt 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+本文翻译提交时的 Git 检出点为： bc465aa9d045feb0e13b4a8f32cc33c1943f62d6
+
+英文版维护者： Punit Agrawal 
+            Suzuki K. Poulose 
+中文版维护者： 傅炜  Fu Wei 
+中文版翻译者： 傅炜  Fu Wei 
+中文版校译者： 傅炜  Fu Wei 
+
+以下为正文
+---------------------------------------------------------------------
+Linux 内核在 arm64 上的移植提供了一个基础框架，以支持构架中正在被淘汰或已废弃指令的模拟执行。
+这个基础框架的代码使用未定义指令钩子（hooks）来支持模拟。如果指令存在，它也允许在硬件中启用该指令。
+
+模拟模式可通过写 sysctl 节点（/proc/sys/abi）来控制。
+不同的执行方式及 sysctl 节点的相应值，解释如下：
+
+* Undef（未定义）
+  值： 0
+  产生未定义指令终止异常。它是那些构架中已废弃的指令，如 SWP，的默认处理方式。
+
+* Emulate（模拟）
+  值： 1
+  使用软件模拟方式。为解决软件迁移问题，这种模拟指令模式的使用是被跟踪的，并会发出速率限制警告。
+  它是那些构架中正在被淘汰的指令，如 CP15 barriers（隔离指令），的默认处理方式。
+
+* Hardware Execution（硬件执行）
+  值： 2
+  虽然标记为正在被淘汰，但一些实现可能提供硬件执行这些指令的使能/禁用操作。
+  使用硬件执行一般会有更好的性能，但将无法收集运行时对正被淘汰指令的使用统计数据。
+
+默认执行模式依赖于指令在构架中状态。正在被淘汰的指令应该以模拟（Emulate）作为默认模式，
+而已废弃的指令必须默认使用未定义（Undef）模式
+
+注意：指令模拟可能无法应对所有情况。更多详情请参考单独的指令注释。
+
+受支持的遗留指令
+-------------
+* SWP{B}
+节点: /proc/sys/abi/swp
+状态: 已废弃
+默认执行方式: Undef (0)
+
+* CP15 Barriers
+节点: /proc/sys/abi/cp15_barrier
+状态: 正被淘汰，不推荐使用
+默认执行方式: Emulate (1)
+
+* SETEND
+节点: /proc/sys/abi/setend
+状态: 正被淘汰，不推荐使用
+默认执行方式: Emulate (1)*
+注：为了使能这个特性，系统中的所有 CPU 必须在 EL0 支持混合字节序。
+如果一个新的 CPU （不支持混合字节序） 在使能这个特性后被热插入系统，
+在应用中可能会出现不可预期的结果。
diff --git a/Documentation/translations/zh_CN/arm64/memory.txt b/Documentation/translations/zh_CN/arm64/memory.txt
new file mode 100644
index 000000000000..19b3a52d5d94
--- /dev/null
+++ b/Documentation/translations/zh_CN/arm64/memory.txt
@@ -0,0 +1,114 @@
+Chinese translated version of Documentation/arm64/memory.txt
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Maintainer: Catalin Marinas 
+Chinese maintainer: Fu Wei 
+---------------------------------------------------------------------
+Documentation/arm64/memory.txt 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+本文翻译提交时的 Git 检出点为： bc465aa9d045feb0e13b4a8f32cc33c1943f62d6
+
+英文版维护者： Catalin Marinas 
+中文版维护者： 傅炜  Fu Wei 
+中文版翻译者： 傅炜  Fu Wei 
+中文版校译者： 傅炜  Fu Wei 
+
+以下为正文
+---------------------------------------------------------------------
+		     Linux 在 AArch64 中的内存布局
+		     ===========================
+
+作者: Catalin Marinas 
+
+本文档描述 AArch64 Linux 内核所使用的虚拟内存布局。此构架可以实现
+页大小为 4KB 的 4 级转换表和页大小为 64KB 的 3 级转换表。
+
+AArch64 Linux 使用 3 级或 4 级转换表，其页大小配置为 4KB，对于用户和内核
+分别都有 39-bit (512GB) 或 48-bit (256TB) 的虚拟地址空间。
+对于页大小为 64KB的配置，仅使用 2 级转换表，有 42-bit (4TB) 的虚拟地址空间，但内存布局相同。
+
+用户地址空间的 63:48 位为 0，而内核地址空间的相应位为 1。TTBRx 的
+选择由虚拟地址的 63 位给出。swapper_pg_dir 仅包含内核（全局）映射，
+而用户 pgd 仅包含用户（非全局）映射。swapper_pg_dir 地址被写入
+TTBR1 中，且从不写入 TTBR0。
+
+
+AArch64 Linux 在页大小为 4KB，并使用 3 级转换表时的内存布局：
+
+起始地址			结束地址			大小		用途
+-----------------------------------------------------------------------
+0000000000000000	0000007fffffffff	 512GB		用户空间
+ffffff8000000000	ffffffffffffffff	 512GB		内核空间
+
+
+AArch64 Linux 在页大小为 4KB，并使用 4 级转换表时的内存布局：
+
+起始地址			结束地址			大小		用途
+-----------------------------------------------------------------------
+0000000000000000	0000ffffffffffff	 256TB		用户空间
+ffff000000000000	ffffffffffffffff	 256TB		内核空间
+
+
+AArch64 Linux 在页大小为 64KB，并使用 2 级转换表时的内存布局：
+
+起始地址			结束地址			大小		用途
+-----------------------------------------------------------------------
+0000000000000000	000003ffffffffff	   4TB		用户空间
+fffffc0000000000	ffffffffffffffff	   4TB		内核空间
+
+
+AArch64 Linux 在页大小为 64KB，并使用 3 级转换表时的内存布局：
+
+起始地址			结束地址			大小		用途
+-----------------------------------------------------------------------
+0000000000000000	0000ffffffffffff	 256TB		用户空间
+ffff000000000000	ffffffffffffffff	 256TB		内核空间
+
+
+更详细的内核虚拟内存布局，请参阅内核启动信息。
+
+
+4KB 页大小的转换表查找：
+
++--------+--------+--------+--------+--------+--------+--------+--------+
+|63    56|55    48|47    40|39    32|31    24|23    16|15     8|7      0|
++--------+--------+--------+--------+--------+--------+--------+--------+
+ |                 |         |         |         |         |
+ |                 |         |         |         |         v
+ |                 |         |         |         |   [11:0]  页内偏移
+ |                 |         |         |         +-> [20:12] L3 索引
+ |                 |         |         +-----------> [29:21] L2 索引
+ |                 |         +---------------------> [38:30] L1 索引
+ |                 +-------------------------------> [47:39] L0 索引
+ +-------------------------------------------------> [63] TTBR0/1
+
+
+64KB 页大小的转换表查找：
+
++--------+--------+--------+--------+--------+--------+--------+--------+
+|63    56|55    48|47    40|39    32|31    24|23    16|15     8|7      0|
++--------+--------+--------+--------+--------+--------+--------+--------+
+ |                 |    |               |              |
+ |                 |    |               |              v
+ |                 |    |               |            [15:0]  页内偏移
+ |                 |    |               +----------> [28:16] L3 索引
+ |                 |    +--------------------------> [41:29] L2 索引
+ |                 +-------------------------------> [47:42] L1 索引
+ +-------------------------------------------------> [63] TTBR0/1
+
+
+当使用 KVM 时, 管理程序（hypervisor）在 EL2 中通过相对内核虚拟地址的
+一个固定偏移来映射内核页（内核虚拟地址的高 24 位设为零）:
+
+起始地址			结束地址			大小		用途
+-----------------------------------------------------------------------
+0000004000000000	0000007fffffffff	 256GB		在 HYP 中映射的内核对象
diff --git a/Documentation/translations/zh_CN/arm64/silicon-errata.txt b/Documentation/translations/zh_CN/arm64/silicon-errata.txt
new file mode 100644
index 000000000000..39477c75c4a4
--- /dev/null
+++ b/Documentation/translations/zh_CN/arm64/silicon-errata.txt
@@ -0,0 +1,74 @@
+Chinese translated version of Documentation/arm64/silicon-errata.txt
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+M:	Will Deacon 
+zh_CN:	Fu Wei 
+C:	1926e54f115725a9248d0c4c65c22acaf94de4c4
+---------------------------------------------------------------------
+Documentation/arm64/silicon-errata.txt 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+英文版维护者： Will Deacon 
+中文版维护者： 傅炜  Fu Wei 
+中文版翻译者： 傅炜  Fu Wei 
+中文版校译者： 傅炜  Fu Wei 
+本文翻译提交时的 Git 检出点为： 1926e54f115725a9248d0c4c65c22acaf94de4c4
+
+以下为正文
+---------------------------------------------------------------------
+                芯片勘误和软件补救措施
+                ==================
+
+作者: Will Deacon 
+日期: 2015年11月27日
+
+一个不幸的现实：硬件经常带有一些所谓的“瑕疵（errata）”，导致其在
+某些特定情况下会违背构架定义的行为。就基于 ARM 的硬件而言，这些瑕疵
+大体可分为以下几类：
+
+  A 类：无可行补救措施的严重缺陷。
+  B 类：有可接受的补救措施的重大或严重缺陷。
+  C 类：在正常操作中不会显现的小瑕疵。
+
+更多资讯，请在 infocenter.arm.com （需注册）中查阅“软件开发者勘误
+笔记”（“Software Developers Errata Notice”）文档。
+
+对于 Linux 而言，B 类缺陷可能需要操作系统的某些特别处理。例如，避免
+一个特殊的代码序列，或是以一种特定的方式配置处理器。在某种不太常见的
+情况下，为将 A 类缺陷当作 C 类处理，可能需要用类似的手段。这些手段被
+统称为“软件补救措施”，且仅在少数情况需要（例如，那些需要一个运行在
+非安全异常级的补救措施 *并且* 能被 Linux 触发的情况）。
+
+对于尚在讨论中的可能对未受瑕疵影响的系统产生干扰的软件补救措施，有一个
+相应的内核配置（Kconfig）选项被加在 “内核特性（Kernel Features）”->
+“基于可选方法框架的 ARM 瑕疵补救措施（ARM errata workarounds via
+the alternatives framework）"。这些选项被默认开启，若探测到受影响的CPU，
+补丁将在运行时被使用。至于对系统运行影响较小的补救措施，内核配置选项
+并不存在，且代码以某种规避瑕疵的方式被构造（带注释为宜）。
+
+这种做法对于在任意内核源代码树中准确地判断出哪个瑕疵已被软件方法所补救
+稍微有点麻烦，所以在 Linux 内核中此文件作为软件补救措施的注册表，
+并将在新的软件补救措施被提交和向后移植（backported）到稳定内核时被更新。
+
+| 实现者         | 受影响的组件    | 勘误编号        | 内核配置                |
++----------------+-----------------+-----------------+-------------------------+
+| ARM            | Cortex-A53      | #826319         | ARM64_ERRATUM_826319    |
+| ARM            | Cortex-A53      | #827319         | ARM64_ERRATUM_827319    |
+| ARM            | Cortex-A53      | #824069         | ARM64_ERRATUM_824069    |
+| ARM            | Cortex-A53      | #819472         | ARM64_ERRATUM_819472    |
+| ARM            | Cortex-A53      | #845719         | ARM64_ERRATUM_845719    |
+| ARM            | Cortex-A53      | #843419         | ARM64_ERRATUM_843419    |
+| ARM            | Cortex-A57      | #832075         | ARM64_ERRATUM_832075    |
+| ARM            | Cortex-A57      | #852523         | N/A                     |
+| ARM            | Cortex-A57      | #834220         | ARM64_ERRATUM_834220    |
+|                |                 |                 |                         |
+| Cavium         | ThunderX ITS    | #22375, #24313  | CAVIUM_ERRATUM_22375    |
+| Cavium         | ThunderX GICv3  | #23154          | CAVIUM_ERRATUM_23154    |
diff --git a/Documentation/translations/zh_CN/arm64/tagged-pointers.txt b/Documentation/translations/zh_CN/arm64/tagged-pointers.txt
new file mode 100644
index 000000000000..2664d1bd5a1c
--- /dev/null
+++ b/Documentation/translations/zh_CN/arm64/tagged-pointers.txt
@@ -0,0 +1,52 @@
+Chinese translated version of Documentation/arm64/tagged-pointers.txt
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Maintainer: Will Deacon 
+Chinese maintainer: Fu Wei 
+---------------------------------------------------------------------
+Documentation/arm64/tagged-pointers.txt 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+英文版维护者： Will Deacon 
+中文版维护者： 傅炜  Fu Wei 
+中文版翻译者： 傅炜  Fu Wei 
+中文版校译者： 傅炜  Fu Wei 
+
+以下为正文
+---------------------------------------------------------------------
+		Linux 在 AArch64 中带标记的虚拟地址
+		=================================
+
+作者: Will Deacon 
+日期: 2013 年 06 月 12 日
+
+本文档简述了在 AArch64 地址转换系统中提供的带标记的虚拟地址及其在
+AArch64 Linux 中的潜在用途。
+
+内核提供的地址转换表配置使通过 TTBR0 完成的虚拟地址转换（即用户空间
+映射），其虚拟地址的最高 8 位（63:56）会被转换硬件所忽略。这种机制
+让这些位可供应用程序自由使用，其注意事项如下：
+
+	(1) 内核要求所有传递到 EL1 的用户空间地址带有 0x00 标记。
+	    这意味着任何携带用户空间虚拟地址的系统调用（syscall）
+	    参数 *必须* 在陷入内核前使它们的最高字节被清零。
+
+	(2) 非零标记在传递信号时不被保存。这意味着在应用程序中利用了
+	    标记的信号处理函数无法依赖 siginfo_t 的用户空间虚拟
+	    地址所携带的包含其内部域信息的标记。此规则的一个例外是
+	    当信号是在调试观察点的异常处理程序中产生的，此时标记的
+	    信息将被保存。
+
+	(3) 当使用带标记的指针时需特别留心，因为仅对两个虚拟地址
+	    的高字节，C 编译器很可能无法判断它们是不同的。
+
+此构架会阻止对带标记的 PC 指针的利用，因此在异常返回时，其高字节
+将被设置成一个为 “55” 的扩展符。
diff --git a/Documentation/translations/zh_CN/basic_profiling.txt b/Documentation/translations/zh_CN/basic_profiling.txt
new file mode 100644
index 000000000000..1e6bf0bdf8f5
--- /dev/null
+++ b/Documentation/translations/zh_CN/basic_profiling.txt
@@ -0,0 +1,71 @@
+Chinese translated version of Documentation/basic_profiling
+
+If you have any comment or update to the content, please post to LKML directly.
+However, if you have problem communicating in English you can also ask the
+Chinese maintainer for help.  Contact the Chinese maintainer, if this
+translation is outdated or there is problem with translation.
+
+Chinese maintainer: Liang Xie 
+---------------------------------------------------------------------
+Documentation/basic_profiling的中文翻译
+
+如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可
+以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。
+
+中文版维护者： 谢良 Liang Xie 
+中文版翻译者： 谢良 Liang Xie 
+中文版校译者：
+以下为正文
+---------------------------------------------------------------------
+
+下面这些说明指令都是非常基础的，如果你想进一步了解请阅读相关专业文档：）
+请不要再在本文档增加新的内容，但可以修复文档中的错误：）(mbligh@aracnet.com)
+感谢John Levon，Dave Hansen等在撰写时的帮助
+
+ 用于表示要测量的目标
+请先确保您已经有正确的System.map / vmlinux配置！
+
+对于linux系统来说，配置vmlinuz最容易的方法可能就是使用“make install”，然后修改
+/sbin/installkernel将vmlinux拷贝到/boot目录，而System.map通常是默认安装好的
+
+Readprofile
+-----------
+2.6系列内核需要版本相对较新的readprofile，比如util-linux 2.12a中包含的，可以从:
+
+http://www.kernel.org/pub/linux/utils/util-linux/ 下载
+
+大部分linux发行版已经包含了.
+
+启用readprofile需要在kernel启动命令行增加”profile=2“
+
+clear		readprofile -r
+		
+dump output	readprofile -m /boot/System.map > captured_profile
+
+Oprofile
+--------
+
+从http://oprofile.sourceforge.net/获取源代码（请参考Changes以获取匹配的版本）
+在kernel启动命令行增加“idle=poll”
+
+配置CONFIG_PROFILING=y和CONFIG_OPROFILE=y然后重启进入新kernel
+
+./configure --with-kernel-support
+make install
+
+想得到好的测量结果，请确保启用了本地APIC特性。如果opreport显示有0Hz CPU，
+说明APIC特性没有开启。另外注意idle=poll选项可能有损性能。
+
+One time setup:
+		opcontrol --setup --vmlinux=/boot/vmlinux
+
+clear		opcontrol --reset
+start		opcontrol --start
+		
+stop		opcontrol --stop
+dump output	opreport >  output_file
+
+如果只看kernel相关的报告结果，请运行命令 opreport -l /boot/vmlinux > output_file
+
+通过reset选项可以清理过期统计数据，相当于重启的效果。
+
diff --git a/Documentation/translations/zh_CN/email-clients.txt b/Documentation/translations/zh_CN/email-clients.txt
new file mode 100644
index 000000000000..ec31d97e8d0e
--- /dev/null
+++ b/Documentation/translations/zh_CN/email-clients.txt
@@ -0,0 +1,210 @@
+Chinese translated version of Documentation/process/email-clients.rst
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Chinese maintainer: Harry Wei 
+---------------------------------------------------------------------
+Documentation/process/email-clients.rst 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+中文版维护者： 贾威威  Harry Wei 
+中文版翻译者： 贾威威  Harry Wei 
+中文版校译者： Yinglin Luan 
+		Xiaochen Wang 
+		yaxinsn 
+
+以下为正文
+---------------------------------------------------------------------
+
+Linux邮件客户端配置信息
+======================================================================
+
+普通配置
+----------------------------------------------------------------------
+Linux内核补丁是通过邮件被提交的，最好把补丁作为邮件体的内嵌文本。有些维护者
+接收附件，但是附件的内容格式应该是"text/plain"。然而，附件一般是不赞成的，
+因为这会使补丁的引用部分在评论过程中变的很困难。
+
+用来发送Linux内核补丁的邮件客户端在发送补丁时应该处于文本的原始状态。例如，
+他们不能改变或者删除制表符或者空格，甚至是在每一行的开头或者结尾。
+
+不要通过"format=flowed"模式发送补丁。这样会引起不可预期以及有害的断行。
+
+不要让你的邮件客户端进行自动换行。这样也会破坏你的补丁。
+
+邮件客户端不能改变文本的字符集编码方式。要发送的补丁只能是ASCII或者UTF-8编码方式，
+如果你使用UTF-8编码方式发送邮件，那么你将会避免一些可能发生的字符集问题。
+
+邮件客户端应该形成并且保持 References: 或者 In-Reply-To: 标题，那么
+邮件话题就不会中断。
+
+复制粘帖(或者剪贴粘帖)通常不能用于补丁，因为制表符会转换为空格。使用xclipboard, xclip
+或者xcutsel也许可以，但是最好测试一下或者避免使用复制粘帖。
+
+不要在使用PGP/GPG署名的邮件中包含补丁。这样会使得很多脚本不能读取和适用于你的补丁。
+（这个问题应该是可以修复的）
+
+在给内核邮件列表发送补丁之前，给自己发送一个补丁是个不错的主意，保存接收到的
+邮件，将补丁用'patch'命令打上，如果成功了，再给内核邮件列表发送。
+
+
+一些邮件客户端提示
+----------------------------------------------------------------------
+这里给出一些详细的MUA配置提示，可以用于给Linux内核发送补丁。这些并不意味是
+所有的软件包配置总结。
+
+说明：
+TUI = 以文本为基础的用户接口
+GUI = 图形界面用户接口
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Alpine (TUI)
+
+配置选项：
+在"Sending Preferences"部分：
+
+- "Do Not Send Flowed Text"必须开启
+- "Strip Whitespace Before Sending"必须关闭
+
+当写邮件时，光标应该放在补丁会出现的地方，然后按下CTRL-R组合键，使指定的
+补丁文件嵌入到邮件中。
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Evolution (GUI)
+
+一些开发者成功的使用它发送补丁
+
+当选择邮件选项：Preformat
+  从Format->Heading->Preformatted (Ctrl-7)或者工具栏
+
+然后使用：
+  Insert->Text File... (Alt-n x)插入补丁文件。
+
+你还可以"diff -Nru old.c new.c | xclip"，选择Preformat，然后使用中间键进行粘帖。
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Kmail (GUI)
+
+一些开发者成功的使用它发送补丁。
+
+默认设置不为HTML格式是合适的；不要启用它。
+
+当书写一封邮件的时候，在选项下面不要选择自动换行。唯一的缺点就是你在邮件中输入的任何文本
+都不会被自动换行，因此你必须在发送补丁之前手动换行。最简单的方法就是启用自动换行来书写邮件，
+然后把它保存为草稿。一旦你在草稿中再次打开它，它已经全部自动换行了，那么你的邮件虽然没有
+选择自动换行，但是还不会失去已有的自动换行。
+
+在邮件的底部，插入补丁之前，放上常用的补丁定界符：三个连字号(---)。
+
+然后在"Message"菜单条目，选择插入文件，接着选取你的补丁文件。还有一个额外的选项，你可以
+通过它配置你的邮件建立工具栏菜单，还可以带上"insert file"图标。
+
+你可以安全地通过GPG标记附件，但是内嵌补丁最好不要使用GPG标记它们。作为内嵌文本的签发补丁，
+当从GPG中提取7位编码时会使他们变的更加复杂。
+
+如果你非要以附件的形式发送补丁，那么就右键点击附件，然后选中属性，突出"Suggest automatic
+display"，这样内嵌附件更容易让读者看到。
+
+当你要保存将要发送的内嵌文本补丁，你可以从消息列表窗格选择包含补丁的邮件，然后右击选择
+"save as"。你可以使用一个没有更改的包含补丁的邮件，如果它是以正确的形式组成。当你正真在它
+自己的窗口之下察看，那时没有选项可以保存邮件--已经有一个这样的bug被汇报到了kmail的bugzilla
+并且希望这将会被处理。邮件是以只针对某个用户可读写的权限被保存的，所以如果你想把邮件复制到其他地方，
+你不得不把他们的权限改为组或者整体可读。
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Lotus Notes (GUI)
+
+不要使用它。
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Mutt (TUI)
+
+很多Linux开发人员使用mutt客户端，所以证明它肯定工作的非常漂亮。
+
+Mutt不自带编辑器，所以不管你使用什么编辑器都不应该带有自动断行。大多数编辑器都带有
+一个"insert file"选项，它可以通过不改变文件内容的方式插入文件。
+
+'vim'作为mutt的编辑器：
+  set editor="vi"
+
+  如果使用xclip，敲入以下命令
+  :set paste
+  按中键之前或者shift-insert或者使用
+  :r filename
+
+如果想要把补丁作为内嵌文本。
+(a)ttach工作的很好，不带有"set paste"。
+
+配置选项：
+它应该以默认设置的形式工作。
+然而，把"send_charset"设置为"us-ascii::utf-8"也是一个不错的主意。
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Pine (TUI)
+
+Pine过去有一些空格删减问题，但是这些现在应该都被修复了。
+
+如果可以，请使用alpine(pine的继承者)
+
+配置选项：
+- 最近的版本需要消除流程文本
+- "no-strip-whitespace-before-send"选项也是需要的。
+
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Sylpheed (GUI)
+
+- 内嵌文本可以很好的工作（或者使用附件）。
+- 允许使用外部的编辑器。
+- 对于目录较多时非常慢。
+- 如果通过non-SSL连接，无法使用TLS SMTP授权。
+- 在组成窗口中有一个很有用的ruler bar。
+- 给地址本中添加地址就不会正确的了解显示名。
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Thunderbird (GUI)
+
+默认情况下，thunderbird很容易损坏文本，但是还有一些方法可以强制它变得更好。
+
+- 在用户帐号设置里，组成和寻址，不要选择"Compose messages in HTML format"。
+
+- 编辑你的Thunderbird配置设置来使它不要拆行使用：user_pref("mailnews.wraplength", 0);
+
+- 编辑你的Thunderbird配置设置，使它不要使用"format=flowed"格式：user_pref("mailnews.
+  send_plaintext_flowed", false);
+
+- 你需要使Thunderbird变为预先格式方式：
+  如果默认情况下你书写的是HTML格式，那不是很难。仅仅从标题栏的下拉框中选择"Preformat"格式。
+  如果默认情况下你书写的是文本格式，你不得把它改为HTML格式（仅仅作为一次性的）来书写新的消息，
+  然后强制使它回到文本格式，否则它就会拆行。要实现它，在写信的图标上使用shift键来使它变为HTML
+  格式，然后标题栏的下拉框中选择"Preformat"格式。
+
+- 允许使用外部的编辑器：
+  针对Thunderbird打补丁最简单的方法就是使用一个"external editor"扩展，然后使用你最喜欢的
+  $EDITOR来读取或者合并补丁到文本中。要实现它，可以下载并且安装这个扩展，然后添加一个使用它的
+  按键View->Toolbars->Customize...最后当你书写信息的时候仅仅点击它就可以了。
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+TkRat (GUI)
+
+可以使用它。使用"Insert file..."或者外部的编辑器。
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Gmail (Web GUI)
+
+不要使用它发送补丁。
+
+Gmail网页客户端自动地把制表符转换为空格。
+
+虽然制表符转换为空格问题可以被外部编辑器解决，同时它还会使用回车换行把每行拆分为78个字符。
+
+另一个问题是Gmail还会把任何不是ASCII的字符的信息改为base64编码。它把东西变的像欧洲人的名字。
+
+                                ###
diff --git a/Documentation/translations/zh_CN/filesystems/sysfs.txt b/Documentation/translations/zh_CN/filesystems/sysfs.txt
new file mode 100644
index 000000000000..7d3b05edb8ce
--- /dev/null
+++ b/Documentation/translations/zh_CN/filesystems/sysfs.txt
@@ -0,0 +1,372 @@
+Chinese translated version of Documentation/filesystems/sysfs.txt
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Maintainer: Patrick Mochel	
+		Mike Murphy 
+Chinese maintainer: Fu Wei 
+---------------------------------------------------------------------
+Documentation/filesystems/sysfs.txt 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+英文版维护者： Patrick Mochel	
+		Mike Murphy 
+中文版维护者： 傅炜 Fu Wei 
+中文版翻译者： 傅炜 Fu Wei 
+中文版校译者： 傅炜 Fu Wei 
+
+
+以下为正文
+---------------------------------------------------------------------
+sysfs - 用于导出内核对象(kobject)的文件系统
+
+Patrick Mochel	
+Mike Murphy 
+
+修订:    16 August 2011
+原始版本:   10 January 2003
+
+
+sysfs 简介:
+~~~~~~~~~~
+
+sysfs 是一个最初基于 ramfs 且位于内存的文件系统。它提供导出内核
+数据结构及其属性，以及它们之间的关联到用户空间的方法。
+
+sysfs 始终与 kobject 的底层结构紧密相关。请阅读
+Documentation/kobject.txt 文档以获得更多关于 kobject 接口的
+信息。
+
+
+使用 sysfs
+~~~~~~~~~~~
+
+只要内核配置中定义了 CONFIG_SYSFS ，sysfs 总是被编译进内核。你可
+通过以下命令挂载它:
+
+    mount -t sysfs sysfs /sys
+
+
+创建目录
+~~~~~~~~
+
+任何 kobject 在系统中注册，就会有一个目录在 sysfs 中被创建。这个
+目录是作为该 kobject 的父对象所在目录的子目录创建的，以准确地传递
+内核的对象层次到用户空间。sysfs 中的顶层目录代表着内核对象层次的
+共同祖先；例如：某些对象属于某个子系统。
+
+Sysfs 在与其目录关联的 kernfs_node 对象中内部保存一个指向实现
+目录的 kobject 的指针。以前，这个 kobject 指针被 sysfs 直接用于
+kobject 文件打开和关闭的引用计数。而现在的 sysfs 实现中，kobject
+引用计数只能通过 sysfs_schedule_callback() 函数直接修改。
+
+
+属性
+~~~~
+
+kobject 的属性可在文件系统中以普通文件的形式导出。Sysfs 为属性定义
+了面向文件 I/O 操作的方法，以提供对内核属性的读写。
+
+
+属性应为 ASCII 码文本文件。以一个文件只存储一个属性值为宜。但一个
+文件只包含一个属性值可能影响效率，所以一个包含相同数据类型的属性值
+数组也被广泛地接受。
+
+混合类型、表达多行数据以及一些怪异的数据格式会遭到强烈反对。这样做是
+很丢脸的,而且其代码会在未通知作者的情况下被重写。
+
+
+一个简单的属性结构定义如下:
+
+struct attribute {
+        char                    * name;
+        struct module		*owner;
+        umode_t                 mode;
+};
+
+
+int sysfs_create_file(struct kobject * kobj, const struct attribute * attr);
+void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr);
+
+
+一个单独的属性结构并不包含读写其属性值的方法。子系统最好为增删特定
+对象类型的属性定义自己的属性结构体和封装函数。
+
+例如:驱动程序模型定义的 device_attribute 结构体如下:
+
+struct device_attribute {
+	struct attribute	attr;
+	ssize_t (*show)(struct device *dev, struct device_attribute *attr,
+			char *buf);
+	ssize_t (*store)(struct device *dev, struct device_attribute *attr,
+			 const char *buf, size_t count);
+};
+
+int device_create_file(struct device *, const struct device_attribute *);
+void device_remove_file(struct device *, const struct device_attribute *);
+
+为了定义设备属性，同时定义了一下辅助宏:
+
+#define DEVICE_ATTR(_name, _mode, _show, _store) \
+struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)
+
+例如:声明
+
+static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
+
+等同于如下代码：
+
+static struct device_attribute dev_attr_foo = {
+       .attr	= {
+		.name = "foo",
+		.mode = S_IWUSR | S_IRUGO,
+		.show = show_foo,
+		.store = store_foo,
+	},
+};
+
+
+子系统特有的回调函数
+~~~~~~~~~~~~~~~~~~~
+
+当一个子系统定义一个新的属性类型时，必须实现一系列的 sysfs 操作，
+以帮助读写调用实现属性所有者的显示和储存方法。
+
+struct sysfs_ops {
+        ssize_t (*show)(struct kobject *, struct attribute *, char *);
+        ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t);
+};
+
+[子系统应已经定义了一个 struct kobj_type 结构体作为这个类型的
+描述符，并在此保存 sysfs_ops 的指针。更多的信息参见 kobject 的
+文档]
+
+sysfs 会为这个类型调用适当的方法。当一个文件被读写时，这个方法会
+将一般的kobject 和 attribute 结构体指针转换为适当的指针类型后
+调用相关联的函数。
+
+
+示例:
+
+#define to_dev(obj) container_of(obj, struct device, kobj)
+#define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)
+
+static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr,
+                             char *buf)
+{
+        struct device_attribute *dev_attr = to_dev_attr(attr);
+        struct device *dev = to_dev(kobj);
+        ssize_t ret = -EIO;
+
+        if (dev_attr->show)
+                ret = dev_attr->show(dev, dev_attr, buf);
+        if (ret >= (ssize_t)PAGE_SIZE) {
+                print_symbol("dev_attr_show: %s returned bad count\n",
+                                (unsigned long)dev_attr->show);
+        }
+        return ret;
+}
+
+
+
+读写属性数据
+~~~~~~~~~~~~
+
+在声明属性时，必须指定 show() 或 store() 方法，以实现属性的
+读或写。这些方法的类型应该和以下的设备属性定义一样简单。
+
+ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf);
+ssize_t (*store)(struct device *dev, struct device_attribute *attr,
+                 const char *buf, size_t count);
+
+也就是说,他们应只以一个处理对象、一个属性和一个缓冲指针作为参数。
+
+sysfs 会分配一个大小为 (PAGE_SIZE) 的缓冲区并传递给这个方法。
+Sysfs 将会为每次读写操作调用一次这个方法。这使得这些方法在执行时
+会出现以下的行为:
+
+- 在读方面（read(2)），show() 方法应该填充整个缓冲区。回想属性
+  应只导出了一个属性值或是一个同类型属性值的数组，所以这个代价将
+  不会不太高。
+
+  这使得用户空间可以局部地读和任意的向前搜索整个文件。如果用户空间
+  向后搜索到零或使用‘0’偏移执行一个pread(2)操作，show()方法将
+  再次被调用，以重新填充缓存。
+
+- 在写方面（write(2)），sysfs 希望在第一次写操作时得到整个缓冲区。
+  之后 Sysfs 传递整个缓冲区给 store() 方法。
+
+  当要写 sysfs 文件时，用户空间进程应首先读取整个文件，修该想要
+  改变的值，然后回写整个缓冲区。
+
+  在读写属性值时，属性方法的执行应操作相同的缓冲区。
+
+注记:
+
+- 写操作导致的 show() 方法重载，会忽略当前文件位置。
+
+- 缓冲区应总是 PAGE_SIZE 大小。对于i386，这个值为4096。
+
+- show() 方法应该返回写入缓冲区的字节数，也就是 snprintf()的
+  返回值。
+
+- show() 应始终使用 snprintf()。
+
+- store() 应返回缓冲区的已用字节数。如果整个缓存都已填满，只需返回
+  count 参数。
+
+- show() 或 store() 可以返回错误值。当得到一个非法值，必须返回一个
+  错误值。
+
+- 一个传递给方法的对象将会通过 sysfs 调用对象内嵌的引用计数固定在
+  内存中。尽管如此，对象代表的物理实体(如设备)可能已不存在。如有必要，
+  应该实现一个检测机制。
+
+一个简单的(未经实验证实的)设备属性实现如下：
+
+static ssize_t show_name(struct device *dev, struct device_attribute *attr,
+                         char *buf)
+{
+	return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name);
+}
+
+static ssize_t store_name(struct device *dev, struct device_attribute *attr,
+                          const char *buf, size_t count)
+{
+        snprintf(dev->name, sizeof(dev->name), "%.*s",
+                 (int)min(count, sizeof(dev->name) - 1), buf);
+	return count;
+}
+
+static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
+
+
+（注意：真正的实现不允许用户空间设置设备名。）
+
+顶层目录布局
+~~~~~~~~~~~~
+
+sysfs 目录的安排显示了内核数据结构之间的关系。
+
+顶层 sysfs 目录如下:
+
+block/
+bus/
+class/
+dev/
+devices/
+firmware/
+net/
+fs/
+
+devices/ 包含了一个设备树的文件系统表示。他直接映射了内部的内核
+设备树，反映了设备的层次结构。
+
+bus/ 包含了内核中各种总线类型的平面目录布局。每个总线目录包含两个
+子目录:
+
+	devices/
+	drivers/
+
+devices/ 包含了系统中出现的每个设备的符号链接，他们指向 root/ 下的
+设备目录。
+
+drivers/ 包含了每个已为特定总线上的设备而挂载的驱动程序的目录(这里
+假定驱动没有跨越多个总线类型)。
+
+fs/ 包含了一个为文件系统设立的目录。现在每个想要导出属性的文件系统必须
+在 fs/ 下创建自己的层次结构(参见Documentation/filesystems/fuse.txt)。
+
+dev/ 包含两个子目录： char/ 和 block/。在这两个子目录中，有以
+: 格式命名的符号链接。这些符号链接指向 sysfs 目录
+中相应的设备。/sys/dev 提供一个通过一个 stat(2) 操作结果，查找
+设备 sysfs 接口快捷的方法。
+
+更多有关 driver-model 的特性信息可以在 Documentation/driver-model/
+中找到。
+
+
+TODO: 完成这一节。
+
+
+当前接口
+~~~~~~~~
+
+以下的接口层普遍存在于当前的sysfs中:
+
+- 设备 (include/linux/device.h)
+----------------------------------
+结构体:
+
+struct device_attribute {
+	struct attribute	attr;
+	ssize_t (*show)(struct device *dev, struct device_attribute *attr,
+			char *buf);
+	ssize_t (*store)(struct device *dev, struct device_attribute *attr,
+			 const char *buf, size_t count);
+};
+
+声明:
+
+DEVICE_ATTR(_name, _mode, _show, _store);
+
+增/删属性:
+
+int device_create_file(struct device *dev, const struct device_attribute * attr);
+void device_remove_file(struct device *dev, const struct device_attribute * attr);
+
+
+- 总线驱动程序 (include/linux/device.h)
+--------------------------------------
+结构体:
+
+struct bus_attribute {
+        struct attribute        attr;
+        ssize_t (*show)(struct bus_type *, char * buf);
+        ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
+};
+
+声明:
+
+BUS_ATTR(_name, _mode, _show, _store)
+
+增/删属性:
+
+int bus_create_file(struct bus_type *, struct bus_attribute *);
+void bus_remove_file(struct bus_type *, struct bus_attribute *);
+
+
+- 设备驱动程序 (include/linux/device.h)
+-----------------------------------------
+
+结构体:
+
+struct driver_attribute {
+        struct attribute        attr;
+        ssize_t (*show)(struct device_driver *, char * buf);
+        ssize_t (*store)(struct device_driver *, const char * buf,
+                         size_t count);
+};
+
+声明:
+
+DRIVER_ATTR(_name, _mode, _show, _store)
+
+增/删属性：
+
+int driver_create_file(struct device_driver *, const struct driver_attribute *);
+void driver_remove_file(struct device_driver *, const struct driver_attribute *);
+
+
+文档
+~~~~
+
+sysfs 目录结构以及其中包含的属性定义了一个内核与用户空间之间的 ABI。
+对于任何 ABI，其自身的稳定和适当的文档是非常重要的。所有新的 sysfs
+属性必须在 Documentation/ABI 中有文档。详见 Documentation/ABI/README。
diff --git a/Documentation/translations/zh_CN/gpio.txt b/Documentation/translations/zh_CN/gpio.txt
new file mode 100644
index 000000000000..bce972521065
--- /dev/null
+++ b/Documentation/translations/zh_CN/gpio.txt
@@ -0,0 +1,650 @@
+Chinese translated version of Documentation/gpio.txt
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Maintainer: Grant Likely 
+		Linus Walleij 
+Chinese maintainer: Fu Wei 
+---------------------------------------------------------------------
+Documentation/gpio.txt 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+英文版维护者： Grant Likely 
+		Linus Walleij 
+中文版维护者： 傅炜 Fu Wei 
+中文版翻译者： 傅炜 Fu Wei 
+中文版校译者： 傅炜 Fu Wei 
+
+
+以下为正文
+---------------------------------------------------------------------
+GPIO 接口
+
+本文档提供了一个在Linux下访问GPIO的公约概述。
+
+这些函数以 gpio_* 作为前缀。其他的函数不允许使用这样的前缀或相关的
+__gpio_* 前缀。
+
+
+什么是GPIO?
+==========
+"通用输入/输出口"(GPIO)是一个灵活的由软件控制的数字信号。他们可
+由多种芯片提供,且对于从事嵌入式和定制硬件的 Linux 开发者来说是
+比较熟悉。每个GPIO 都代表一个连接到特定引脚或球栅阵列(BGA)封装中
+“球珠”的一个位。电路板原理图显示了 GPIO 与外部硬件的连接关系。
+驱动可以编写成通用代码，以使板级启动代码可传递引脚配置数据给驱动。
+
+片上系统 (SOC) 处理器对 GPIO 有很大的依赖。在某些情况下,每个
+非专用引脚都可配置为 GPIO,且大多数芯片都最少有一些 GPIO。
+可编程逻辑器件(类似 FPGA) 可以方便地提供 GPIO。像电源管理和
+音频编解码器这样的多功能芯片经常留有一些这样的引脚来帮助那些引脚
+匮乏的 SOC。同时还有通过 I2C 或 SPI 串行总线连接的“GPIO扩展器”
+芯片。大多数 PC 的南桥有一些拥有 GPIO 能力的引脚 (只有BIOS
+固件才知道如何使用他们)。
+
+GPIO 的实际功能因系统而异。通常用法有:
+
+  - 输出值可写 (高电平=1，低电平=0)。一些芯片也有如何驱动这些值的选项,
+    例如只允许输出一个值、支持“线与”及其他取值类似的模式(值得注意的是
+    “开漏”信号)
+
+  - 输入值可读(1、0)。一些芯片支持引脚在配置为“输出”时回读，这对于类似
+    “线与”的情况(以支持双向信号)是非常有用的。GPIO 控制器可能有输入
+    去毛刺/消抖逻辑,这有时需要软件控制。
+
+  - 输入通常可作为 IRQ 信号,一般是沿触发,但有时是电平触发。这样的 IRQ
+    可能配置为系统唤醒事件,以将系统从低功耗状态下唤醒。
+
+  - 通常一个 GPIO 根据不同产品电路板的需求,可以配置为输入或输出,也有仅
+    支持单向的。
+
+  - 大部分 GPIO 可以在持有自旋锁时访问,但是通常由串行总线扩展的 GPIO
+    不允许持有自旋锁。但某些系统也支持这种类型。
+
+对于给定的电路板,每个 GPIO 都用于某个特定的目的,如监控 MMC/SD 卡的
+插入/移除、检测卡的写保护状态、驱动 LED、配置收发器、模拟串行总线、
+复位硬件看门狗、感知开关状态等等。
+
+
+GPIO 公约
+=========
+注意,这个叫做“公约”，因为这不是强制性的，不遵循这个公约是无伤大雅的，
+因为此时可移植性并不重要。GPIO 常用于板级特定的电路逻辑,甚至可能
+随着电路板的版本而改变，且不可能在不同走线的电路板上使用。仅有在少数
+功能上才具有可移植性，其他功能是平台特定。这也是由于“胶合”的逻辑造成的。
+
+此外，这不需要任何的执行框架，只是一个接口。某个平台可能通过一个简单地
+访问芯片寄存器的内联函数来实现它，其他平台可能通过委托一系列不同的GPIO
+控制器的抽象函数来实现它。(有一些可选的代码能支持这种策略的实现,本文档
+后面会介绍，但作为 GPIO 接口的客户端驱动程序必须与它的实现无关。)
+
+也就是说,如果在他们的平台上支持这个公约，驱动应尽可能的使用它。同时，平台
+必须在 Kconfig 中选择 ARCH_REQUIRE_GPIOLIB 或者 ARCH_WANT_OPTIONAL_GPIOLIB
+选项。那些调用标准 GPIO 函数的驱动应该在 Kconfig 入口中声明依赖GENERIC_GPIO。
+当驱动包含文件:
+
+	#include 
+
+则 GPIO 函数是可用,无论是“真实代码”还是经优化过的语句。如果你遵守
+这个公约，当你的代码完成后，对其他的开发者来说会更容易看懂和维护。
+
+注意，这些操作包含所用平台的 I/O 屏障代码，驱动无须显式地调用他们。
+
+
+标识 GPIO
+---------
+GPIO 是通过无符号整型来标识的,范围是 0 到 MAX_INT。保留“负”数
+用于其他目的,例如标识信号“在这个板子上不可用”或指示错误。未接触底层
+硬件的代码会忽略这些整数。
+
+平台会定义这些整数的用法,且通常使用 #define 来定义 GPIO，这样
+板级特定的启动代码可以直接关联相应的原理图。相对来说，驱动应该仅使用
+启动代码传递过来的 GPIO 编号，使用 platform_data 保存板级特定
+引脚配置数据 (同时还有其他须要的板级特定数据)，避免可能出现的问题。
+
+例如一个平台使用编号 32-159 来标识 GPIO,而在另一个平台使用编号0-63
+标识一组 GPIO 控制器,64-79标识另一类 GPIO 控制器,且在一个含有
+FPGA 的特定板子上使用 80-95。编号不一定要连续,那些平台中，也可以
+使用编号2000-2063来标识一个 I2C 接口的 GPIO 扩展器中的 GPIO。
+
+如果你要初始化一个带有无效 GPIO 编号的结构体,可以使用一些负编码
+(如"-EINVAL")，那将使其永远不会是有效。来测试这样一个结构体中的编号
+是否关联一个 GPIO，你可使用以下断言:
+
+	int gpio_is_valid(int number);
+
+如果编号不存在，则请求和释放 GPIO 的函数将拒绝执行相关操作(见下文)。
+其他编号也可能被拒绝,比如一个编号可能存在，但暂时在给定的电路上不可用。
+
+一个平台是否支持多个 GPIO 控制器为平台特定的实现问题，就像是否可以
+在 GPIO 编号空间中有“空洞”和是否可以在运行时添加新的控制器一样。
+这些问题会影响其他事情，包括相邻的 GPIO 编号是否存在等。
+
+使用 GPIO
+---------
+对于一个 GPIO，系统应该做的第一件事情就是通过 gpio_request()
+函数分配它，见下文。
+
+接下来是设置I/O方向，这通常是在板级启动代码中为所使用的 GPIO 设置
+platform_device 时完成。
+
+	/* 设置为输入或输出, 返回 0 或负的错误代码 */
+	int gpio_direction_input(unsigned gpio);
+	int gpio_direction_output(unsigned gpio, int value);
+
+返回值为零代表成功，否则返回一个负的错误代码。这个返回值需要检查，因为
+get/set(获取/设置)函数调用没法返回错误,且有可能是配置错误。通常，
+你应该在进程上下文中调用这些函数。然而,对于自旋锁安全的 GPIO，在板子
+启动的早期、进程启动前使用他们也是可以的。
+
+对于作为输出的 GPIO，为其提供初始输出值，对于避免在系统启动期间出现
+信号毛刺是很有帮助的。
+
+为了与传统的 GPIO 接口兼容, 在设置一个 GPIO 方向时，如果它还未被申请，
+则隐含了申请那个 GPIO 的操作(见下文)。这种兼容性正在从可选的 gpiolib
+框架中移除。
+
+如果这个 GPIO 编码不存在，或者特定的 GPIO 不能用于那种模式，则方向
+设置可能失败。依赖启动固件来正确地设置方向通常是一个坏主意，因为它可能
+除了启动Linux，并没有做更多的验证工作。(同理, 板子的启动代码可能需要
+将这个复用的引脚设置为 GPIO，并正确地配置上拉/下拉电阻。)
+
+
+访问自旋锁安全的 GPIO
+-------------------
+大多数 GPIO 控制器可以通过内存读/写指令来访问。这些指令不会休眠,可以
+安全地在硬(非线程)中断例程和类似的上下文中完成。
+
+对于那些用 gpio_cansleep()测试总是返回失败的 GPIO(见下文)，使用
+以下的函数访问:
+
+	/* GPIO 输入:返回零或非零 */
+	int gpio_get_value(unsigned gpio);
+
+	/* GPIO 输出 */
+	void gpio_set_value(unsigned gpio, int value);
+
+GPIO值是布尔值，零表示低电平，非零表示高电平。当读取一个输出引脚的值时，
+返回值应该是引脚上的值。这个值不总是和输出值相符，因为存在开漏输出信号和
+输出延迟问题。
+
+以上的 get/set 函数无错误返回值，因为之前 gpio_direction_*()应已检查过
+其是否为“无效GPIO”。此外，还需要注意的是并不是所有平台都可以从输出引脚
+中读取数据，对于不能读取的引脚应总返回零。另外，对那些在原子上下文中无法
+安全访问的 GPIO (译者注：因为访问可能导致休眠)使用这些函数是不合适的
+(见下文)。
+
+在 GPIO 编号(还有输出、值)为常数的情况下,鼓励通过平台特定的实现来优化
+这两个函数来访问 GPIO 值。这种情况(读写一个硬件寄存器)下只需要几条指令
+是很正常的,且无须自旋锁。这种优化函数比起那些在子程序上花费许多指令的
+函数可以使得模拟接口(译者注:例如 GPIO 模拟 I2C、1-wire 或 SPI)的
+应用(在空间和时间上都)更具效率。
+
+
+访问可能休眠的 GPIO
+-----------------
+某些 GPIO 控制器必须通过基于总线(如 I2C 或 SPI)的消息访问。读或写这些
+GPIO 值的命令需要等待其信息排到队首才发送命令，再获得其反馈。期间需要
+休眠，这不能在 IRQ 例程(中断上下文)中执行。
+
+支持此类 GPIO 的平台通过以下函数返回非零值来区分出这种 GPIO。(此函数需要
+一个之前通过 gpio_request 分配到的有效 GPIO 编号):
+
+	int gpio_cansleep(unsigned gpio);
+
+为了访问这种 GPIO,内核定义了一套不同的函数:
+
+	/* GPIO 输入:返回零或非零 ,可能会休眠 */
+	int gpio_get_value_cansleep(unsigned gpio);
+
+	/* GPIO 输出,可能会休眠 */
+	void gpio_set_value_cansleep(unsigned gpio, int value);
+
+
+访问这样的 GPIO 需要一个允许休眠的上下文，例如线程 IRQ 处理例程，并用以上的
+访问函数替换那些没有 cansleep()后缀的自旋锁安全访问函数。
+
+除了这些访问函数可能休眠，且它们操作的 GPIO 不能在硬件 IRQ 处理例程中访问的
+事实，这些处理例程实际上和自旋锁安全的函数是一样的。
+
+** 除此之外 ** 调用设置和配置此类 GPIO 的函数也必须在允许休眠的上下文中，
+因为它们可能也需要访问 GPIO 控制器芯片: (这些设置函数通常在板级启动代码或者
+驱动探测/断开代码中，所以这是一个容易满足的约束条件。)
+
+	gpio_direction_input()
+	gpio_direction_output()
+	gpio_request()
+
+## 	gpio_request_one()
+##	gpio_request_array()
+## 	gpio_free_array()
+
+	gpio_free()
+	gpio_set_debounce()
+
+
+
+声明和释放 GPIO
+----------------------------
+为了有助于捕获系统配置错误,定义了两个函数。
+
+	/* 申请 GPIO, 返回 0 或负的错误代码.
+	 * 非空标签可能有助于诊断.
+	 */
+	int gpio_request(unsigned gpio, const char *label);
+
+	/* 释放之前声明的 GPIO */
+	void gpio_free(unsigned gpio);
+
+将无效的 GPIO 编码传递给 gpio_request()会导致失败，申请一个已使用这个
+函数声明过的 GPIO 也会失败。gpio_request()的返回值必须检查。你应该在
+进程上下文中调用这些函数。然而,对于自旋锁安全的 GPIO,在板子启动的早期、
+进入进程之前是可以申请的。
+
+这个函数完成两个基本的目标。一是标识那些实际上已作为 GPIO 使用的信号线，
+这样便于更好地诊断;系统可能需要服务几百个可用的 GPIO，但是对于任何一个
+给定的电路板通常只有一些被使用。另一个目的是捕获冲突，查明错误:如两个或
+更多驱动错误地认为他们已经独占了某个信号线,或是错误地认为移除一个管理着
+某个已激活信号的驱动是安全的。也就是说，申请 GPIO 的作用类似一种锁机制。
+
+某些平台可能也使用 GPIO 作为电源管理激活信号(例如通过关闭未使用芯片区和
+简单地关闭未使用时钟)。
+
+对于 GPIO 使用 pinctrl 子系统已知的引脚，子系统应该被告知其使用情况；
+一个 gpiolib 驱动的 .request()操作应调用 pinctrl_request_gpio()，
+而 gpiolib 驱动的 .free()操作应调用 pinctrl_free_gpio()。pinctrl
+子系统允许 pinctrl_request_gpio()在某个引脚或引脚组以复用形式“属于”
+一个设备时都成功返回。
+
+任何须将 GPIO 信号导向适当引脚的引脚复用硬件的编程应该发生在 GPIO
+驱动的 .direction_input()或 .direction_output()函数中，以及
+任何输出 GPIO 值的设置之后。这样可使从引脚特殊功能到 GPIO 的转换
+不会在引脚产生毛刺波形。有时当用一个 GPIO 实现其信号驱动一个非 GPIO
+硬件模块的解决方案时，就需要这种机制。
+
+某些平台允许部分或所有 GPIO 信号使用不同的引脚。类似的，GPIO 或引脚的
+其他方面也需要配置，如上拉/下拉。平台软件应该在对这些 GPIO 调用
+gpio_request()前将这类细节配置好，例如使用 pinctrl 子系统的映射表，
+使得 GPIO 的用户无须关注这些细节。
+
+还有一个值得注意的是在释放 GPIO 前，你必须停止使用它。
+
+
+注意:申请一个 GPIO 并没有以任何方式配置它，只不过标识那个 GPIO 处于使用
+状态。必须有另外的代码来处理引脚配置(如控制 GPIO 使用的引脚、上拉/下拉)。
+考虑到大多数情况下声明 GPIO 之后就会立即配置它们,所以定义了以下三个辅助函数:
+
+	/* 申请一个 GPIO 信号, 同时通过特定的'flags'初始化配置,
+	 * 其他和 gpio_request()的参数和返回值相同
+	 *
+	 */
+	int gpio_request_one(unsigned gpio, unsigned long flags, const char *label);
+
+	/* 在单个函数中申请多个 GPIO
+	 */
+	int gpio_request_array(struct gpio *array, size_t num);
+
+	/* 在单个函数中释放多个 GPIO
+	 */
+	void gpio_free_array(struct gpio *array, size_t num);
+
+这里 'flags' 当前定义可指定以下属性:
+
+	* GPIOF_DIR_IN		- 配置方向为输入
+	* GPIOF_DIR_OUT		- 配置方向为输出
+
+	* GPIOF_INIT_LOW	- 在作为输出时,初始值为低电平
+	* GPIOF_INIT_HIGH	- 在作为输出时,初始值为高电平
+	* GPIOF_OPEN_DRAIN	- gpio引脚为开漏信号
+	* GPIOF_OPEN_SOURCE	- gpio引脚为源极开路信号
+
+	* GPIOF_EXPORT_DIR_FIXED	- 将 gpio 导出到 sysfs，并保持方向
+	* GPIOF_EXPORT_DIR_CHANGEABLE	- 同样是导出, 但允许改变方向
+
+因为 GPIOF_INIT_* 仅有在配置为输出的时候才存在,所以有效的组合为:
+
+	* GPIOF_IN		- 配置为输入
+	* GPIOF_OUT_INIT_LOW	- 配置为输出,并初始化为低电平
+	* GPIOF_OUT_INIT_HIGH	- 配置为输出,并初始化为高电平
+
+当设置 flag 为 GPIOF_OPEN_DRAIN 时，则假设引脚是开漏信号。这样的引脚
+将不会在输出模式下置1。这样的引脚需要连接上拉电阻。通过使能这个标志，gpio库
+将会在被要求输出模式下置1时将引脚变为输入状态来使引脚置高。引脚在输出模式下
+通过置0使其输出低电平。
+
+当设置 flag 为 GPIOF_OPEN_SOURCE 时，则假设引脚为源极开路信号。这样的引脚
+将不会在输出模式下置0。这样的引脚需要连接下拉电阻。通过使能这个标志，gpio库
+将会在被要求输出模式下置0时将引脚变为输入状态来使引脚置低。引脚在输出模式下
+通过置1使其输出高电平。
+
+将来这些标志可能扩展到支持更多的属性。
+
+更进一步,为了更简单地声明/释放多个 GPIO,'struct gpio'被引进来封装所有
+这三个领域:
+
+	struct gpio {
+		unsigned	gpio;
+		unsigned long	flags;
+		const char	*label;
+	};
+
+一个典型的用例:
+
+	static struct gpio leds_gpios[] = {
+		{ 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* 默认开启 */
+		{ 33, GPIOF_OUT_INIT_LOW,  "Green LED" }, /* 默认关闭 */
+		{ 34, GPIOF_OUT_INIT_LOW,  "Red LED"   }, /* 默认关闭 */
+		{ 35, GPIOF_OUT_INIT_LOW,  "Blue LED"  }, /* 默认关闭 */
+		{ ... },
+	};
+
+	err = gpio_request_one(31, GPIOF_IN, "Reset Button");
+	if (err)
+		...
+
+	err = gpio_request_array(leds_gpios, ARRAY_SIZE(leds_gpios));
+	if (err)
+		...
+
+	gpio_free_array(leds_gpios, ARRAY_SIZE(leds_gpios));
+
+
+GPIO 映射到 IRQ
+--------------------
+GPIO 编号是无符号整数;IRQ 编号也是。这些构成了两个逻辑上不同的命名空间
+(GPIO 0 不一定使用 IRQ 0)。你可以通过以下函数在它们之间实现映射:
+
+	/* 映射 GPIO 编号到 IRQ 编号 */
+	int gpio_to_irq(unsigned gpio);
+
+	/* 映射 IRQ 编号到 GPIO 编号 (尽量避免使用) */
+	int irq_to_gpio(unsigned irq);
+
+它们的返回值为对应命名空间的相关编号，或是负的错误代码(如果无法映射)。
+(例如,某些 GPIO 无法做为 IRQ 使用。)以下的编号错误是未经检测的:使用一个
+未通过 gpio_direction_input()配置为输入的 GPIO 编号，或者使用一个
+并非来源于gpio_to_irq()的 IRQ 编号。
+
+这两个映射函数可能会在信号编号的加减计算过程上花些时间。它们不可休眠。
+
+gpio_to_irq()返回的非错误值可以传递给 request_irq()或者 free_irq()。
+它们通常通过板级特定的初始化代码存放到平台设备的 IRQ 资源中。注意:IRQ
+触发选项是 IRQ 接口的一部分，如 IRQF_TRIGGER_FALLING，系统唤醒能力
+也是如此。
+
+irq_to_gpio()返回的非错误值大多数通常可以被 gpio_get_value()所使用，
+比如在 IRQ 是沿触发时初始化或更新驱动状态。注意某些平台不支持反映射,所以
+你应该尽量避免使用它。
+
+
+模拟开漏信号
+----------------------------
+有时在只有低电平信号作为实际驱动结果(译者注:多个输出连接于一点，逻辑电平
+结果为所有输出的逻辑与)的时候,共享的信号线需要使用“开漏”信号。(该术语
+适用于 CMOS 管；而 TTL 用“集电极开路”。)一个上拉电阻使信号为高电平。这
+有时被称为“线与”。实际上，从负逻辑(低电平为真)的角度来看，这是一个“线或”。
+
+一个开漏信号的常见例子是共享的低电平使能 IRQ 信号线。此外,有时双向数据总线
+信号也使用漏极开路信号。
+
+某些 GPIO 控制器直接支持开漏输出，还有许多不支持。当你需要开漏信号，但
+硬件又不直接支持的时候，一个常用的方法是用任何即可作输入也可作输出的 GPIO
+引脚来模拟:
+
+ LOW:	gpio_direction_output(gpio, 0) ... 这代码驱动信号并覆盖
+	上拉配置。
+
+ HIGH:	gpio_direction_input(gpio) ... 这代码关闭输出,所以上拉电阻
+	(或其他的一些器件)控制了信号。
+
+如果你将信号线“驱动”为高电平，但是 gpio_get_value(gpio)报告了一个
+低电平(在适当的上升时间后)，你就可以知道是其他的一些组件将共享信号线拉低了。
+这不一定是错误的。一个常见的例子就是 I2C 时钟的延长：一个需要较慢时钟的
+从设备延迟 SCK 的上升沿，而 I2C 主设备相应地调整其信号传输速率。
+
+
+这些公约忽略了什么?
+================
+这些公约忽略的最大一件事就是引脚复用，因为这属于高度芯片特定的属性且
+没有可移植性。某个平台可能不需要明确的复用信息；有的对于任意给定的引脚
+可能只有两个功能选项；有的可能每个引脚有八个功能选项；有的可能可以将
+几个引脚中的任何一个作为给定的 GPIO。(是的，这些例子都来自于当前运行
+Linux 的系统。)
+
+在某些系统中,与引脚复用相关的是配置和使能集成的上、下拉模式。并不是所有
+平台都支持这种模式,或者不会以相同的方式来支持这种模式；且任何给定的电路板
+可能使用外置的上拉(或下拉)电阻,这时芯片上的就不应该使用。(当一个电路需要
+5kOhm 的拉动电阻,芯片上的 100 kOhm 电阻就不能做到。)同样的，驱动能力
+(2 mA vs 20 mA)和电压(1.8V vs 3.3V)是平台特定问题,就像模型一样在
+可配置引脚和 GPIO 之间(没)有一一对应的关系。
+
+还有其他一些系统特定的机制没有在这里指出，例如上述的输入去毛刺和线与输出
+选项。硬件可能支持批量读或写 GPIO，但是那一般是配置相关的：对于处于同一
+块区(bank)的GPIO。(GPIO 通常以 16 或 32 个组成一个区块，一个给定的
+片上系统一般有几个这样的区块。)某些系统可以通过输出 GPIO 触发 IRQ，
+或者从并非以 GPIO 管理的引脚取值。这些机制的相关代码没有必要具有可移植性。
+
+当前，动态定义 GPIO 并不是标准的，例如作为配置一个带有某些 GPIO 扩展器的
+附加电路板的副作用。
+
+GPIO 实现者的框架 (可选)
+=====================
+前面提到了，有一个可选的实现框架，让平台使用相同的编程接口，更加简单地支持
+不同种类的 GPIO 控制器。这个框架称为"gpiolib"。
+
+作为一个辅助调试功能，如果 debugfs 可用，就会有一个 /sys/kernel/debug/gpio
+文件。通过这个框架，它可以列出所有注册的控制器,以及当前正在使用中的 GPIO
+的状态。
+
+
+控制器驱动: gpio_chip
+-------------------
+在框架中每个 GPIO 控制器都包装为一个 "struct gpio_chip"，他包含了
+该类型的每个控制器的常用信息:
+
+ - 设置 GPIO 方向的方法
+ - 用于访问 GPIO 值的方法
+ - 告知调用其方法是否可能休眠的标志
+ - 可选的 debugfs 信息导出方法 (显示类似上拉配置一样的额外状态)
+ - 诊断标签
+
+也包含了来自 device.platform_data 的每个实例的数据：它第一个 GPIO 的
+编号和它可用的 GPIO 的数量。
+
+实现 gpio_chip 的代码应支持多控制器实例，这可能使用驱动模型。那些代码要
+配置每个 gpio_chip，并发起gpiochip_add()。卸载一个 GPIO 控制器很少见，
+但在必要的时候可以使用 gpiochip_remove()。
+
+大部分 gpio_chip 是一个实例特定结构体的一部分，而并不将 GPIO 接口单独
+暴露出来,比如编址、电源管理等。类似编解码器这样的芯片会有复杂的非 GPIO
+状态。
+
+任何一个 debugfs 信息导出方法通常应该忽略还未申请作为 GPIO 的信号线。
+他们可以使用 gpiochip_is_requested()测试，当这个 GPIO 已经申请过了
+就返回相关的标签，否则返回 NULL。
+
+
+平台支持
+-------
+为了支持这个框架，一个平台的 Kconfig 文件将会 "select"(选择)
+ARCH_REQUIRE_GPIOLIB 或 ARCH_WANT_OPTIONAL_GPIOLIB，并让它的
+ 包含 ，同时定义三个方法:
+gpio_get_value()、gpio_set_value()和 gpio_cansleep()。
+
+它也应提供一个 ARCH_NR_GPIOS 的定义值，这样可以更好地反映该平台 GPIO
+的实际数量,节省静态表的空间。(这个定义值应该包含片上系统内建 GPIO 和
+GPIO 扩展器中的数据。)
+
+ARCH_REQUIRE_GPIOLIB 意味着 gpiolib 核心在这个构架中将总是编译进内核。
+
+ARCH_WANT_OPTIONAL_GPIOLIB 意味着 gpiolib 核心默认关闭,且用户可以
+使能它,并将其编译进内核(可选)。
+
+如果这些选项都没被选择,该平台就不通过 GPIO-lib 支持 GPIO,且代码不可以
+被用户使能。
+
+以下这些方法的实现可以直接使用框架代码,并总是通过 gpio_chip 调度:
+
+  #define gpio_get_value	__gpio_get_value
+  #define gpio_set_value	__gpio_set_value
+  #define gpio_cansleep		__gpio_cansleep
+
+这些定义可以用更理想的实现方法替代，那就是使用经过逻辑优化的内联函数来访问
+基于特定片上系统的 GPIO。例如,若引用的 GPIO (寄存器位偏移)是常量“12”，
+读取或设置它可能只需少则两或三个指令，且不会休眠。当这样的优化无法实现时，
+那些函数必须使用框架提供的代码，那就至少要几十条指令才可以实现。对于用 GPIO
+模拟的 I/O 接口, 如此精简指令是很有意义的。
+
+对于片上系统，平台特定代码为片上 GPIO 每个区(bank)定义并注册 gpio_chip
+实例。那些 GPIO 应该根据芯片厂商的文档进行编码/标签,并直接和电路板原理图
+对应。他们应该开始于零并终止于平台特定的限制。这些 GPIO(代码)通常从
+arch_initcall()或者更早的地方集成进平台初始化代码，使这些 GPIO 总是可用，
+且他们通常可以作为 IRQ 使用。
+
+板级支持
+-------
+对于外部 GPIO 控制器(例如 I2C 或 SPI 扩展器、专用芯片、多功能器件、FPGA
+或 CPLD)，大多数常用板级特定代码都可以注册控制器设备，并保证他们的驱动知道
+gpiochip_add()所使用的 GPIO 编号。他们的起始编号通常跟在平台特定的 GPIO
+编号之后。
+
+例如板级启动代码应该创建结构体指明芯片公开的 GPIO 范围，并使用 platform_data
+将其传递给每个 GPIO 扩展器芯片。然后芯片驱动中的 probe()例程可以将这个
+数据传递给 gpiochip_add()。
+
+初始化顺序很重要。例如，如果一个设备依赖基于 I2C 的(扩展)GPIO，那么它的
+probe()例程就应该在那个 GPIO 有效以后才可以被调用。这意味着设备应该在
+GPIO 可以工作之后才可被注册。解决这类依赖的的一种方法是让这种 gpio_chip
+控制器向板级特定代码提供 setup()和 teardown()回调函数。一旦所有必须的
+资源可用之后，这些板级特定的回调函数将会注册设备，并可以在这些 GPIO 控制器
+设备变成无效时移除它们。
+
+
+用户空间的 Sysfs 接口(可选)
+========================
+使用“gpiolib”实现框架的平台可以选择配置一个 GPIO 的 sysfs 用户接口。
+这不同于 debugfs 接口，因为它提供的是对 GPIO方向和值的控制，而不只显示
+一个GPIO 的状态摘要。此外,它可以出现在没有调试支持的产品级系统中。
+
+例如，通过适当的系统硬件文档，用户空间可以知道 GIOP #23 控制 Flash
+存储器的写保护(用于保护其中 Bootloader 分区)。产品的系统升级可能需要
+临时解除这个保护：首先导入一个 GPIO，改变其输出状态，然后在重新使能写保护
+前升级代码。通常情况下,GPIO #23 是不会被触及的，并且内核也不需要知道他。
+
+根据适当的硬件文档，某些系统的用户空间 GPIO 可以用于确定系统配置数据，
+这些数据是标准内核不知道的。在某些任务中，简单的用户空间 GPIO 驱动可能是
+系统真正需要的。
+
+注意：标准内核驱动中已经存在通用的“LED 和按键”GPIO 任务，分别是:
+"leds-gpio" 和 "gpio_keys"。请使用这些来替代直接访问 GPIO，因为集成在
+内核框架中的这类驱动比你在用户空间的代码更好。
+
+
+Sysfs 中的路径
+--------------
+在/sys/class/gpio 中有 3 类入口:
+
+   -	用于在用户空间控制 GPIO 的控制接口;
+
+   -	GPIOs 本身;以及
+
+   -	GPIO 控制器 ("gpio_chip" 实例)。
+
+除了这些标准的文件,还包含“device”符号链接。
+
+控制接口是只写的:
+
+    /sys/class/gpio/
+
+    	"export" ... 用户空间可以通过写其编号到这个文件，要求内核导出
+		一个 GPIO 的控制到用户空间。
+
+		例如: 如果内核代码没有申请 GPIO #19,"echo 19 > export"
+		将会为 GPIO #19 创建一个 "gpio19" 节点。
+
+    	"unexport" ... 导出到用户空间的逆操作。
+
+		例如: "echo 19 > unexport" 将会移除使用"export"文件导出的
+		"gpio19" 节点。
+
+GPIO 信号的路径类似 /sys/class/gpio/gpio42/ (对于 GPIO #42 来说)，
+并有如下的读/写属性:
+
+    /sys/class/gpio/gpioN/
+
+	"direction" ... 读取得到 "in" 或 "out"。这个值通常运行写入。
+		写入"out" 时,其引脚的默认输出为低电平。为了确保无故障运行，
+		"low" 或 "high" 的电平值应该写入 GPIO 的配置，作为初始输出值。
+
+		注意:如果内核不支持改变 GPIO 的方向，或者在导出时内核代码没有
+		明确允许用户空间可以重新配置 GPIO 方向，那么这个属性将不存在。
+
+	"value" ... 读取得到 0 (低电平) 或 1 (高电平)。如果 GPIO 配置为
+		输出,这个值允许写操作。任何非零值都以高电平看待。
+
+		如果引脚可以配置为中断信号，且如果已经配置了产生中断的模式
+		（见"edge"的描述），你可以对这个文件使用轮询操作(poll(2))，
+		且轮询操作会在任何中断触发时返回。如果你使用轮询操作(poll(2))，
+		请在 events 中设置 POLLPRI 和 POLLERR。如果你使用轮询操作
+		(select(2))，请在 exceptfds 设置你期望的文件描述符。在
+		轮询操作(poll(2))返回之后，既可以通过 lseek(2)操作读取
+		sysfs 文件的开始部分，也可以关闭这个文件并重新打开它来读取数据。
+
+	"edge" ... 读取得到“none”、“rising”、“falling”或者“both”。
+		将这些字符串写入这个文件可以选择沿触发模式，会使得轮询操作
+		(select(2))在"value"文件中返回。
+
+		这个文件仅有在这个引脚可以配置为可产生中断输入引脚时，才存在。
+
+	"active_low" ... 读取得到 0 (假) 或 1 (真)。写入任何非零值可以
+		翻转这个属性的(读写)值。已存在或之后通过"edge"属性设置了"rising"
+		和 "falling" 沿触发模式的轮询操作(poll(2))将会遵循这个设置。
+
+GPIO 控制器的路径类似 /sys/class/gpio/gpiochip42/ (对于从#42 GPIO
+开始实现控制的控制器),并有着以下只读属性:
+
+    /sys/class/gpio/gpiochipN/
+
+    	"base" ... 与以上的 N 相同,代表此芯片管理的第一个 GPIO 的编号
+
+    	"label" ... 用于诊断 (并不总是只有唯一值)
+
+    	"ngpio" ... 此控制器所管理的 GPIO 数量(而 GPIO 编号从 N 到
+    		N + ngpio - 1)
+
+大多数情况下,电路板的文档应当标明每个 GPIO 的使用目的。但是那些编号并不总是
+固定的,例如在扩展卡上的 GPIO会根据所使用的主板或所在堆叠架构中其他的板子而
+有所不同。在这种情况下,你可能需要使用 gpiochip 节点(尽可能地结合电路图)来
+确定给定信号所用的 GPIO 编号。
+
+
+从内核代码中导出
+-------------
+内核代码可以明确地管理那些已通过 gpio_request()申请的 GPIO 的导出:
+
+	/* 导出 GPIO 到用户空间 */
+	int gpio_export(unsigned gpio, bool direction_may_change);
+
+	/* gpio_export()的逆操作 */
+	void gpio_unexport();
+
+	/* 创建一个 sysfs 连接到已导出的 GPIO 节点 */
+	int gpio_export_link(struct device *dev, const char *name,
+		unsigned gpio)
+
+在一个内核驱动申请一个 GPIO 之后，它可以通过 gpio_export()使其在 sysfs
+接口中可见。该驱动可以控制信号方向是否可修改。这有助于防止用户空间代码无意间
+破坏重要的系统状态。
+
+这个明确的导出有助于(通过使某些实验更容易来)调试，也可以提供一个始终存在的接口，
+与文档配合作为板级支持包的一部分。
+
+在 GPIO 被导出之后，gpio_export_link()允许在 sysfs 文件系统的任何地方
+创建一个到这个 GPIO sysfs 节点的符号链接。这样驱动就可以通过一个描述性的
+名字，在 sysfs 中他们所拥有的设备下提供一个(到这个 GPIO sysfs 节点的)接口。
diff --git a/Documentation/translations/zh_CN/io_ordering.txt b/Documentation/translations/zh_CN/io_ordering.txt
new file mode 100644
index 000000000000..e592daf4e014
--- /dev/null
+++ b/Documentation/translations/zh_CN/io_ordering.txt
@@ -0,0 +1,67 @@
+Chinese translated version of Documentation/io_orderings.txt
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Chinese maintainer: Lin Yongting 
+---------------------------------------------------------------------
+Documentation/io_ordering.txt 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+中文版维护者： 林永听 Lin Yongting 
+中文版翻译者： 林永听 Lin Yongting 
+中文版校译者： 林永听 Lin Yongting 
+
+
+以下为正文
+---------------------------------------------------------------------
+
+在某些平台上，所谓的内存映射I/O是弱顺序。在这些平台上，驱动开发者有责任
+保证I/O内存映射地址的写操作按程序图意的顺序达到设备。通常读取一个“安全”
+设备寄存器或桥寄存器，触发IO芯片清刷未处理的写操作到达设备后才处理读操作，
+而达到保证目的。驱动程序通常在spinlock保护的临界区退出之前使用这种技术。
+这也可以保证后面的写操作只在前面的写操作之后到达设备（这非常类似于内存
+屏障操作，mb()，不过仅适用于I/O）。
+
+假设一个设备驱动程的具体例子：
+
+        ...
+CPU A:  spin_lock_irqsave(&dev_lock, flags)
+CPU A:  val = readl(my_status);
+CPU A:  ...
+CPU A:  writel(newval, ring_ptr);
+CPU A:  spin_unlock_irqrestore(&dev_lock, flags)
+        ...
+CPU B:  spin_lock_irqsave(&dev_lock, flags)
+CPU B:  val = readl(my_status);
+CPU B:  ...
+CPU B:  writel(newval2, ring_ptr);
+CPU B:  spin_unlock_irqrestore(&dev_lock, flags)
+        ...
+
+上述例子中，设备可能会先接收到newval2的值，然后接收到newval的值，问题就
+发生了。不过很容易通过下面方法来修复：
+
+        ...
+CPU A:  spin_lock_irqsave(&dev_lock, flags)
+CPU A:  val = readl(my_status);
+CPU A:  ...
+CPU A:  writel(newval, ring_ptr);
+CPU A:  (void)readl(safe_register); /* 配置寄存器？*/
+CPU A:  spin_unlock_irqrestore(&dev_lock, flags)
+        ...
+CPU B:  spin_lock_irqsave(&dev_lock, flags)
+CPU B:  val = readl(my_status);
+CPU B:  ...
+CPU B:  writel(newval2, ring_ptr);
+CPU B:  (void)readl(safe_register); /* 配置寄存器？*/
+CPU B:  spin_unlock_irqrestore(&dev_lock, flags)
+
+在解决方案中，读取safe_register寄存器，触发IO芯片清刷未处理的写操作，
+再处理后面的读操作，防止引发数据不一致问题。
diff --git a/Documentation/translations/zh_CN/magic-number.txt b/Documentation/translations/zh_CN/magic-number.txt
new file mode 100644
index 000000000000..e9db693c0a23
--- /dev/null
+++ b/Documentation/translations/zh_CN/magic-number.txt
@@ -0,0 +1,153 @@
+Chinese translated version of Documentation/magic-number.txt
+
+If you have any comment or update to the content, please post to LKML directly.
+However, if you have problem communicating in English you can also ask the
+Chinese maintainer for help.  Contact the Chinese maintainer, if this
+translation is outdated or there is problem with translation.
+
+Chinese maintainer: Jia Wei Wei 
+---------------------------------------------------------------------
+Documentation/magic-number.txt的中文翻译
+
+如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可
+以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。
+
+中文版维护者： 贾威威 Jia Wei Wei 
+中文版翻译者： 贾威威 Jia Wei Wei 
+中文版校译者： 贾威威 Jia Wei Wei 
+
+以下为正文
+---------------------------------------------------------------------
+这个文件是有关当前使用的魔术值注册表。当你给一个结构添加了一个魔术值，你也应该把这个魔术值添加到这个文件，因为我们最好把用于各种结构的魔术值统一起来。
+
+使用魔术值来保护内核数据结构是一个非常好的主意。这就允许你在运行期检查(a)一个结构是否已经被攻击，或者(b)你已经给一个例行程序通过了一个错误的结构。后一种情况特别地有用---特别是当你通过一个空指针指向结构体的时候。tty源码，例如，经常通过特定驱动使用这种方法并且反复地排列特定方面的结构。
+
+使用魔术值的方法是在结构的开始处声明的，如下：
+
+struct tty_ldisc {
+	int	magic;
+	...
+};
+
+当你以后给内核添加增强功能的时候，请遵守这条规则！这样就会节省数不清的调试时间，特别是一些古怪的情况，例如，数组超出范围并且重新写了超出部分。遵守这个规则，‪这些情况可以被快速地，安全地避免。
+
+		Theodore Ts'o
+		  31 Mar 94
+
+给当前的Linux 2.1.55添加魔术表。
+
+		Michael Chastain
+		
+		22 Sep 1997
+
+现在应该最新的Linux 2.1.112.因为在特性冻结期间，不能在2.2.x前改变任何东西。这些条目被数域所排序。
+
+		Krzysztof G.Baranowski
+	        
+		29 Jul 1998
+
+更新魔术表到Linux 2.5.45。刚好越过特性冻结，但是有可能还会有一些新的魔术值在2.6.x之前融入到内核中。
+
+		Petr Baudis
+		
+		03 Nov 2002
+
+更新魔术表到Linux 2.5.74。
+
+		Fabian Frederick
+                
+		09 Jul 2003
+
+魔术名                 地址         结构               所在文件
+===========================================================================
+PG_MAGIC              'P'         pg_{read,write}_hdr include/linux/pg.h
+CMAGIC                0x0111      user              include/linux/a.out.h
+MKISS_DRIVER_MAGIC    0x04bf      mkiss_channel     drivers/net/mkiss.h
+HDLC_MAGIC            0x239e      n_hdlc            drivers/char/n_hdlc.c
+APM_BIOS_MAGIC        0x4101      apm_user          arch/x86/kernel/apm_32.c
+CYCLADES_MAGIC        0x4359      cyclades_port     include/linux/cyclades.h
+DB_MAGIC              0x4442      fc_info           drivers/net/iph5526_novram.c
+DL_MAGIC              0x444d      fc_info           drivers/net/iph5526_novram.c
+FASYNC_MAGIC          0x4601      fasync_struct     include/linux/fs.h
+FF_MAGIC              0x4646      fc_info           drivers/net/iph5526_novram.c
+ISICOM_MAGIC          0x4d54      isi_port          include/linux/isicom.h
+PTY_MAGIC             0x5001                        drivers/char/pty.c
+PPP_MAGIC             0x5002      ppp               include/linux/if_pppvar.h
+SERIAL_MAGIC          0x5301      async_struct      include/linux/serial.h
+SSTATE_MAGIC          0x5302      serial_state      include/linux/serial.h
+SLIP_MAGIC            0x5302      slip              drivers/net/slip.h
+STRIP_MAGIC           0x5303      strip             drivers/net/strip.c
+X25_ASY_MAGIC         0x5303      x25_asy           drivers/net/x25_asy.h
+SIXPACK_MAGIC         0x5304      sixpack           drivers/net/hamradio/6pack.h
+AX25_MAGIC            0x5316      ax_disp           drivers/net/mkiss.h
+TTY_MAGIC             0x5401      tty_struct        include/linux/tty.h
+MGSL_MAGIC            0x5401      mgsl_info         drivers/char/synclink.c
+TTY_DRIVER_MAGIC      0x5402      tty_driver        include/linux/tty_driver.h
+MGSLPC_MAGIC          0x5402      mgslpc_info       drivers/char/pcmcia/synclink_cs.c
+TTY_LDISC_MAGIC       0x5403      tty_ldisc         include/linux/tty_ldisc.h
+USB_SERIAL_MAGIC      0x6702      usb_serial        drivers/usb/serial/usb-serial.h
+FULL_DUPLEX_MAGIC     0x6969                        drivers/net/ethernet/dec/tulip/de2104x.c
+USB_BLUETOOTH_MAGIC   0x6d02      usb_bluetooth     drivers/usb/class/bluetty.c
+RFCOMM_TTY_MAGIC      0x6d02                        net/bluetooth/rfcomm/tty.c
+USB_SERIAL_PORT_MAGIC 0x7301      usb_serial_port   drivers/usb/serial/usb-serial.h
+CG_MAGIC              0x00090255  ufs_cylinder_group include/linux/ufs_fs.h
+RPORT_MAGIC           0x00525001  r_port            drivers/char/rocket_int.h
+LSEMAGIC              0x05091998  lse               drivers/fc4/fc.c
+GDTIOCTL_MAGIC        0x06030f07  gdth_iowr_str     drivers/scsi/gdth_ioctl.h
+RIEBL_MAGIC           0x09051990                    drivers/net/atarilance.c
+NBD_REQUEST_MAGIC     0x12560953  nbd_request       include/linux/nbd.h
+RED_MAGIC2            0x170fc2a5  (any)             mm/slab.c
+BAYCOM_MAGIC          0x19730510  baycom_state      drivers/net/baycom_epp.c
+ISDN_X25IFACE_MAGIC   0x1e75a2b9  isdn_x25iface_proto_data
+                                                    drivers/isdn/isdn_x25iface.h
+ECP_MAGIC             0x21504345  cdkecpsig         include/linux/cdk.h
+LSOMAGIC              0x27091997  lso               drivers/fc4/fc.c
+LSMAGIC               0x2a3b4d2a  ls                drivers/fc4/fc.c
+WANPIPE_MAGIC         0x414C4453  sdla_{dump,exec}  include/linux/wanpipe.h
+CS_CARD_MAGIC         0x43525553  cs_card           sound/oss/cs46xx.c
+LABELCL_MAGIC         0x4857434c  labelcl_info_s    include/asm/ia64/sn/labelcl.h
+ISDN_ASYNC_MAGIC      0x49344C01  modem_info        include/linux/isdn.h
+CTC_ASYNC_MAGIC       0x49344C01  ctc_tty_info      drivers/s390/net/ctctty.c
+ISDN_NET_MAGIC        0x49344C02  isdn_net_local_s  drivers/isdn/i4l/isdn_net_lib.h
+SAVEKMSG_MAGIC2       0x4B4D5347  savekmsg          arch/*/amiga/config.c
+CS_STATE_MAGIC        0x4c4f4749  cs_state          sound/oss/cs46xx.c
+SLAB_C_MAGIC          0x4f17a36d  kmem_cache        mm/slab.c
+COW_MAGIC             0x4f4f4f4d  cow_header_v1     arch/um/drivers/ubd_user.c
+I810_CARD_MAGIC       0x5072696E  i810_card         sound/oss/i810_audio.c
+TRIDENT_CARD_MAGIC    0x5072696E  trident_card      sound/oss/trident.c
+ROUTER_MAGIC          0x524d4157  wan_device        [in wanrouter.h pre 3.9]
+SAVEKMSG_MAGIC1       0x53415645  savekmsg          arch/*/amiga/config.c
+GDA_MAGIC             0x58464552  gda               arch/mips/include/asm/sn/gda.h
+RED_MAGIC1            0x5a2cf071  (any)             mm/slab.c
+EEPROM_MAGIC_VALUE    0x5ab478d2  lanai_dev         drivers/atm/lanai.c
+HDLCDRV_MAGIC         0x5ac6e778  hdlcdrv_state     include/linux/hdlcdrv.h
+PCXX_MAGIC            0x5c6df104  channel           drivers/char/pcxx.h
+KV_MAGIC              0x5f4b565f  kernel_vars_s     arch/mips/include/asm/sn/klkernvars.h
+I810_STATE_MAGIC      0x63657373  i810_state        sound/oss/i810_audio.c
+TRIDENT_STATE_MAGIC   0x63657373  trient_state      sound/oss/trident.c
+M3_CARD_MAGIC         0x646e6f50  m3_card           sound/oss/maestro3.c
+FW_HEADER_MAGIC       0x65726F66  fw_header         drivers/atm/fore200e.h
+SLOT_MAGIC            0x67267321  slot              drivers/hotplug/cpqphp.h
+SLOT_MAGIC            0x67267322  slot              drivers/hotplug/acpiphp.h
+LO_MAGIC              0x68797548  nbd_device        include/linux/nbd.h
+OPROFILE_MAGIC        0x6f70726f  super_block       drivers/oprofile/oprofilefs.h
+M3_STATE_MAGIC        0x734d724d  m3_state          sound/oss/maestro3.c
+VMALLOC_MAGIC         0x87654320  snd_alloc_track   sound/core/memory.c
+KMALLOC_MAGIC         0x87654321  snd_alloc_track   sound/core/memory.c
+PWC_MAGIC             0x89DC10AB  pwc_device        drivers/usb/media/pwc.h
+NBD_REPLY_MAGIC       0x96744668  nbd_reply         include/linux/nbd.h
+ENI155_MAGIC          0xa54b872d  midway_eprom	    drivers/atm/eni.h
+CODA_MAGIC            0xC0DAC0DA  coda_file_info    include/linux/coda_fs_i.h
+DPMEM_MAGIC           0xc0ffee11  gdt_pci_sram      drivers/scsi/gdth.h
+YAM_MAGIC             0xF10A7654  yam_port          drivers/net/hamradio/yam.c
+CCB_MAGIC             0xf2691ad2  ccb               drivers/scsi/ncr53c8xx.c
+QUEUE_MAGIC_FREE      0xf7e1c9a3  queue_entry       drivers/scsi/arm/queue.c
+QUEUE_MAGIC_USED      0xf7e1cc33  queue_entry       drivers/scsi/arm/queue.c
+HTB_CMAGIC            0xFEFAFEF1  htb_class         net/sched/sch_htb.c
+NMI_MAGIC             0x48414d4d455201 nmi_s        arch/mips/include/asm/sn/nmi.h
+
+请注意，在声音记忆管理中仍然有一些特殊的为每个驱动定义的魔术值。查看include/sound/sndmagic.h来获取他们完整的列表信息。很多OSS声音驱动拥有自己从声卡PCI ID构建的魔术值-他们也没有被列在这里。
+
+IrDA子系统也使用了大量的自己的魔术值，查看include/net/irda/irda.h来获取他们完整的信息。
+
+HFS是另外一个比较大的使用魔术值的文件系统-你可以在fs/hfs/hfs.h中找到他们。
diff --git a/Documentation/translations/zh_CN/oops-tracing.txt b/Documentation/translations/zh_CN/oops-tracing.txt
new file mode 100644
index 000000000000..41ab53cc0e83
--- /dev/null
+++ b/Documentation/translations/zh_CN/oops-tracing.txt
@@ -0,0 +1,212 @@
+Chinese translated version of Documentation/admin-guide/oops-tracing.rst
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Chinese maintainer: Dave Young 
+---------------------------------------------------------------------
+Documentation/admin-guide/oops-tracing.rst 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+中文版维护者： 杨瑞 Dave Young 
+中文版翻译者： 杨瑞 Dave Young 
+中文版校译者： 李阳 Li Yang 
+               王聪 Wang Cong 
+
+以下为正文
+---------------------------------------------------------------------
+
+注意： ksymoops 在2.6中是没有用的。 请以原有格式使用Oops(来自dmesg，等等)。
+忽略任何这样那样关于“解码Oops”或者“通过ksymoops运行”的文档。 如果你贴出运行过
+ksymoops的来自2.6的Oops，人们只会让你重贴一次。
+
+快速总结
+-------------
+
+发现Oops并发送给看似相关的内核领域的维护者。别太担心对不上号。如果你不确定就发给
+和你所做的事情相关的代码的负责人。 如果可重现试着描述怎样重构。 那甚至比oops更有
+价值。
+
+如果你对于发送给谁一无所知， 发给linux-kernel@vger.kernel.org。感谢你帮助Linux
+尽可能地稳定。
+
+Oops在哪里?
+----------------------
+
+通常Oops文本由klogd从内核缓冲区里读取并传给syslogd，由syslogd写到syslog文件中，
+典型地是/var/log/messages(依赖于/etc/syslog.conf)。有时klogd崩溃了,这种情况下你
+能够运行dmesg > file来从内核缓冲区中读取数据并保存下来。 否则你可以
+cat /proc/kmsg > file， 然而你必须介入中止传输， kmsg是一个“永不结束的文件”。如
+果机器崩溃坏到你不能输入命令或者磁盘不可用那么你有三种选择:-
+
+（1） 手抄屏幕上的文本待机器重启后再输入计算机。 麻烦但如果没有针对崩溃的准备，
+这是仅有的选择。 另外，你可以用数码相机把屏幕拍下来-不太好，但比没有强。 如果信
+息滚动到了终端的上面，你会发现以高分辩率启动（比如，vga=791）会让你读到更多的文
+本。（注意：这需要vesafb，所以对‘早期’的oops没有帮助）
+
+（2）用串口终端启动（请参看Documentation/admin-guide/serial-console.rst），运行一个null
+modem到另一台机器并用你喜欢的通讯工具获取输出。Minicom工作地很好。
+
+（3）使用Kdump（请参看Documentation/kdump/kdump.txt），
+使用在Documentation/kdump/gdbmacros.txt中定义的dmesg gdb宏，从旧的内存中提取内核
+环形缓冲区。
+
+完整信息
+----------------
+
+注意：以下来自于Linus的邮件适用于2.4内核。 我因为历史原因保留了它，并且因为其中
+一些信息仍然适用。 特别注意的是，请忽略任何ksymoops的引用。
+
+From: Linus Torvalds 
+
+怎样跟踪Oops.. [原发到linux-kernel的一封邮件]
+
+主要的窍门是有五年和这些烦人的oops消息打交道的经验;-)
+
+实际上，你有办法使它更简单。我有两个不同的方法：
+
+	gdb /usr/src/linux/vmlinux
+	gdb> disassemble 
+
+那是发现问题的简单办法，至少如果bug报告做的好的情况下（象这个一样-运行ksymoops
+得到oops发生的函数及函数内的偏移）。
+
+哦，如果报告发生的内核以相同的编译器和相似的配置编译它会有帮助的。
+
+另一件要做的事是反汇编bug报告的“Code”部分：ksymoops也会用正确的工具来做这件事，
+但如果没有那些工具你可以写一个傻程序：
+
+	char str[] = "\xXX\xXX\xXX...";
+	main(){}
+
+并用gcc -g编译它然后执行“disassemble str”（XX部分是由Oops报告的值-你可以仅剪切
+粘贴并用“\x”替换空格-我就是这么做的，因为我懒得写程序自动做这一切）。
+
+另外，你可以用scripts/decodecode这个shell脚本。它的使用方法是：
+decodecode < oops.txt
+
+“Code”之后的十六进制字节可能（在某些架构上）有一些当前指令之前的指令字节以及
+当前和之后的指令字节
+
+Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1
+64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54
+7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0
+
+最后，如果你想知道代码来自哪里，你可以：
+
+	cd /usr/src/linux
+	make fs/buffer.s 	# 或任何产生BUG的文件
+
+然后你会比gdb反汇编更清楚的知道发生了什么。
+
+现在，问题是把你所拥有的所有数据结合起来：C源码（关于它应该怎样的一般知识），
+汇编代码及其反汇编得到的代码（另外还有从“oops”消息得到的寄存器状态-对了解毁坏的
+指针有用，而且当你有了汇编代码你也能拿其它的寄存器和任何它们对应的C表达式做匹配
+）。
+
+实际上，你仅需看看哪里不匹配（这个例子是“Code”反汇编和编译器生成的代码不匹配）。
+然后你须要找出为什么不匹配。通常很简单-你看到代码使用了空指针然后你看代码想知道
+空指针是怎么出现的，还有检查它是否合法..
+
+现在，如果明白这是一项耗时的工作而且需要一丁点儿的专心，没错。这就是我为什么大多
+只是忽略那些没有符号表信息的崩溃报告的原因：简单的说太难查找了（我有一些
+程序用于在内核代码段中搜索特定的模式，而且有时我也已经能找出那些崩溃的地方，但是
+仅仅是找出正确的序列也确实需要相当扎实的内核知识）
+
+_有时_会发生这种情况，我仅看到崩溃中的反汇编代码序列， 然后我马上就明白问题出在
+哪里。这时我才意识到自己干这个工作已经太长时间了;-)
+
+		Linus
+
+
+---------------------------------------------------------------------------
+关于Oops跟踪的注解：
+
+为了帮助Linus和其它内核开发者，klogd纳入了大量的支持来处理保护错误。为了拥有对
+地址解析的完整支持至少应该使用1.3-pl3的sysklogd包。
+
+当保护错误发生时，klogd守护进程自动把内核日志信息中的重要地址翻译成它们相应的符
+号。
+
+klogd执行两种类型的地址解析。首先是静态翻译其次是动态翻译。静态翻译和ksymoops
+一样使用System.map文件。为了做静态翻译klogd守护进程必须在初始化时能找到system
+map文件。关于klogd怎样搜索map文件请参看klogd手册页。
+
+动态地址翻译在使用内核可装载模块时很重要。 因为内核模块的内存是从内核动态内存池
+里分配的，所以不管是模块开始位置还是模块中函数和符号的位置都不是固定的。
+
+内核支持允许程序决定装载哪些模块和它们在内存中位置的系统调用。使用这些系统调用
+klogd守护进程生成一张符号表用于调试发生在可装载模块中的保护错误。
+
+至少klogd会提供产生保护错误的模块名。还可有额外的符号信息供可装载模块开发者选择
+以从模块中输出符号信息。
+
+因为内核模块环境可能是动态的，所以必须有一种机制当模块环境发生改变时来通知klogd
+守护进程。 有一些可用的命令行选项允许klogd向当前执行中的守护进程发送信号，告知符
+号信息应该被刷新了。 更多信息请参看klogd手册页。
+
+sysklogd发布时包含一个补丁修改了modules-2.0.0包，无论何时一个模块装载或者卸载都
+会自动向klogd发送信号。打上这个补丁提供了必要的对调试发生于内核可装载模块的保护
+错误的无缝支持。
+
+以下是被klogd处理过的发生在可装载模块中的一个保护错误例子：
+---------------------------------------------------------------------------
+Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc
+Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000
+Aug 29 09:51:01 blizard kernel: *pde = 00000000
+Aug 29 09:51:01 blizard kernel: Oops: 0002
+Aug 29 09:51:01 blizard kernel: CPU:    0
+Aug 29 09:51:01 blizard kernel: EIP:    0010:[oops:_oops+16/3868]
+Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212
+Aug 29 09:51:01 blizard kernel: eax: 315e97cc   ebx: 003a6f80   ecx: 001be77b   edx: 00237c0c
+Aug 29 09:51:01 blizard kernel: esi: 00000000   edi: bffffdb3   ebp: 00589f90   esp: 00589f8c
+Aug 29 09:51:01 blizard kernel: ds: 0018   es: 0018   fs: 002b   gs: 002b   ss: 0018
+Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000)
+Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001
+Aug 29 09:51:01 blizard kernel:        00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00
+Aug 29 09:51:01 blizard kernel:        bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036
+Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128]
+Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3
+---------------------------------------------------------------------------
+
+Dr. G.W. Wettstein           Oncology Research Div. Computing Facility
+Roger Maris Cancer Center    INTERNET: greg@wind.rmcc.com
+820 4th St. N.
+Fargo, ND  58122
+Phone: 701-234-7556
+
+
+---------------------------------------------------------------------------
+受污染的内核
+
+一些oops报告在程序记数器之后包含字符串'Tainted: '。这表明内核已经被一些东西给污
+染了。 该字符串之后紧跟着一系列的位置敏感的字符，每个代表一个特定的污染值。
+
+  1：'G'如果所有装载的模块都有GPL或相容的许可证，'P'如果装载了任何的专有模块。
+没有模块MODULE_LICENSE或者带有insmod认为是与GPL不相容的的MODULE_LICENSE的模块被
+认定是专有的。
+
+  2：'F'如果有任何通过“insmod -f”被强制装载的模块，' '如果所有模块都被正常装载。
+
+  3：'S'如果oops发生在SMP内核中，运行于没有证明安全运行多处理器的硬件。 当前这种
+情况仅限于几种不支持SMP的速龙处理器。
+
+  4：'R'如果模块通过“insmod -f”被强制装载，' '如果所有模块都被正常装载。
+
+  5：'M'如果任何处理器报告了机器检查异常，' '如果没有发生机器检查异常。
+
+  6：'B'如果页释放函数发现了一个错误的页引用或者一些非预期的页标志。
+
+  7：'U'如果用户或者用户应用程序特别请求设置污染标志，否则' '。
+
+  8：'D'如果内核刚刚死掉，比如有OOPS或者BUG。
+
+使用'Tainted: '字符串的主要原因是要告诉内核调试者，这是否是一个干净的内核亦或发
+生了任何的不正常的事。污染是永久的：即使出错的模块已经被卸载了，污染值仍然存在，
+以表明内核不再值得信任。
diff --git a/Documentation/translations/zh_CN/sparse.txt b/Documentation/translations/zh_CN/sparse.txt
new file mode 100644
index 000000000000..cc144e581515
--- /dev/null
+++ b/Documentation/translations/zh_CN/sparse.txt
@@ -0,0 +1,100 @@
+Chinese translated version of Documentation/sparse.txt
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Chinese maintainer: Li Yang 
+---------------------------------------------------------------------
+Documentation/sparse.txt 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+中文版维护者： 李阳  Li Yang 
+中文版翻译者： 李阳  Li Yang 
+
+
+以下为正文
+---------------------------------------------------------------------
+
+Copyright 2004 Linus Torvalds
+Copyright 2004 Pavel Machek 
+Copyright 2006 Bob Copeland 
+
+使用 sparse 工具做类型检查
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+"__bitwise" 是一种类型属性，所以你应该这样使用它：
+
+        typedef int __bitwise pm_request_t;
+
+        enum pm_request {
+                PM_SUSPEND = (__force pm_request_t) 1,
+                PM_RESUME = (__force pm_request_t) 2
+        };
+
+这样会使 PM_SUSPEND 和 PM_RESUME 成为位方式(bitwise)整数（使用"__force"
+是因为 sparse 会抱怨改变位方式的类型转换，但是这里我们确实需要强制进行转
+换）。而且因为所有枚举值都使用了相同的类型，这里的"enum pm_request"也将
+会使用那个类型做为底层实现。
+
+而且使用 gcc 编译的时候，所有的 __bitwise/__force 都会消失，最后在 gcc
+看来它们只不过是普通的整数。
+
+坦白来说，你并不需要使用枚举类型。上面那些实际都可以浓缩成一个特殊的"int
+__bitwise"类型。
+
+所以更简单的办法只要这样做：
+
+	typedef int __bitwise pm_request_t;
+
+	#define PM_SUSPEND ((__force pm_request_t) 1)
+	#define PM_RESUME ((__force pm_request_t) 2)
+
+现在你就有了严格的类型检查所需要的所有基础架构。
+
+一个小提醒：常数整数"0"是特殊的。你可以直接把常数零当作位方式整数使用而
+不用担心 sparse 会抱怨。这是因为"bitwise"（恰如其名）是用来确保不同位方
+式类型不会被弄混（小尾模式，大尾模式，cpu尾模式，或者其他），对他们来说
+常数"0"确实是特殊的。
+
+获取 sparse 工具
+~~~~~~~~~~~~~~~~
+
+你可以从 Sparse 的主页获取最新的发布版本：
+
+	http://www.kernel.org/pub/linux/kernel/people/josh/sparse/
+
+或者，你也可以使用 git 克隆最新的 sparse 开发版本：
+
+	git://git.kernel.org/pub/scm/linux/kernel/git/josh/sparse.git
+
+DaveJ 把每小时自动生成的 git 源码树 tar 包放在以下地址：
+
+	http://www.codemonkey.org.uk/projects/git-snapshots/sparse/
+
+一旦你下载了源码，只要以普通用户身份运行：
+
+	make
+	make install
+
+它将会被自动安装到你的 ~/bin 目录下。
+
+使用 sparse 工具
+~~~~~~~~~~~~~~~~
+
+用"make C=1"命令来编译内核，会对所有重新编译的 C 文件使用 sparse 工具。
+或者使用"make C=2"命令，无论文件是否被重新编译都会对其使用 sparse 工具。
+如果你已经编译了内核，用后一种方式可以很快地检查整个源码树。
+
+make 的可选变量 CHECKFLAGS 可以用来向 sparse 工具传递参数。编译系统会自
+动向 sparse 工具传递 -Wbitwise 参数。你可以定义 __CHECK_ENDIAN__ 来进行
+大小尾检查。
+
+	make C=2 CHECKFLAGS="-D__CHECK_ENDIAN__"
+
+这些检查默认都是被关闭的，因为他们通常会产生大量的警告。
diff --git a/Documentation/translations/zh_CN/stable_api_nonsense.txt b/Documentation/translations/zh_CN/stable_api_nonsense.txt
new file mode 100644
index 000000000000..a2b27fab382c
--- /dev/null
+++ b/Documentation/translations/zh_CN/stable_api_nonsense.txt
@@ -0,0 +1,157 @@
+Chinese translated version of Documentation/process/stable-api-nonsense.rst
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have problem
+communicating in English you can also ask the Chinese maintainer for help.
+Contact the Chinese maintainer, if this translation is outdated or there
+is problem with translation.
+
+Maintainer: Greg Kroah-Hartman 
+Chinese maintainer: TripleX Chung 
+---------------------------------------------------------------------
+Documentation/process/stable-api-nonsense.rst 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+英文版维护者： Greg Kroah-Hartman 
+中文版维护者： 钟宇  TripleX Chung 
+中文版翻译者： 钟宇  TripleX Chung 
+中文版校译者： 李阳  Li Yang 
+以下为正文
+---------------------------------------------------------------------
+
+写作本文档的目的，是为了解释为什么Linux既没有二进制内核接口，也没有稳定
+的内核接口。这里所说的内核接口，是指内核里的接口，而不是内核和用户空间
+的接口。内核到用户空间的接口，是提供给应用程序使用的系统调用，系统调用
+在历史上几乎没有过变化，将来也不会有变化。我有一些老应用程序是在0.9版本
+或者更早版本的内核上编译的，在使用2.6版本内核的Linux发布上依然用得很好
+。用户和应用程序作者可以将这个接口看成是稳定的。
+
+
+执行纲要
+--------
+
+你也许以为自己想要稳定的内核接口，但是你不清楚你要的实际上不是它。你需
+要的其实是稳定的驱动程序，而你只有将驱动程序放到公版内核的源代码树里，
+才有可能达到这个目的。而且这样做还有很多其它好处，正是因为这些好处使得
+Linux能成为强壮，稳定，成熟的操作系统，这也是你最开始选择Linux的原因。
+
+
+入门
+-----
+
+只有那些写驱动程序的“怪人”才会担心内核接口的改变，对广大用户来说，既
+看不到内核接口，也不需要去关心它。
+
+首先，我不打算讨论关于任何非GPL许可的内核驱动的法律问题，这些非GPL许可
+的驱动程序包括不公开源代码，隐藏源代码，二进制或者是用源代码包装，或者
+是其它任何形式的不能以GPL许可公开源代码的驱动程序。如果有法律问题，请咨
+询律师，我只是一个程序员，所以我只打算探讨技术问题（不是小看法律问题，
+法律问题很实际，并且需要一直关注）。
+
+既然只谈技术问题，我们就有了下面两个主题：二进制内核接口和稳定的内核源
+代码接口。这两个问题是互相关联的，让我们先解决掉二进制接口的问题。
+
+
+二进制内核接口
+--------------
+假如我们有一个稳定的内核源代码接口，那么自然而然的，我们就拥有了稳定的
+二进制接口，是这样的吗？错。让我们看看关于Linux内核的几点事实：
+    - 取决于所用的C编译器的版本，不同的内核数据结构里的结构体的对齐方
+式会有差别，代码中不同函数的表现形式也不一样（函数是不是被inline编译取
+决于编译器行为）。不同的函数的表现形式并不重要，但是数据结构内部的对齐
+方式很关键。
+    - 取决于内核的配置选项，不同的选项会让内核的很多东西发生改变：
+      - 同一个结构体可能包含不同的成员变量
+      - 有的函数可能根本不会被实现（比如编译的时候没有选择SMP支持
+，一些锁函数就会被定义成空函数）。
+      - 内核使用的内存会以不同的方式对齐，这取决于不同的内核配置选
+项。
+    - Linux可以在很多的不同体系结构的处理器上运行。在某个体系结构上编
+译好的二进制驱动程序，不可能在另外一个体系结构上正确的运行。
+
+对于一个特定的内核，满足这些条件并不难，使用同一个C编译器和同样的内核配
+置选项来编译驱动程序模块就可以了。这对于给一个特定Linux发布的特定版本提
+供驱动程序，是完全可以满足需求的。但是如果你要给不同发布的不同版本都发
+布一个驱动程序，就需要在每个发布上用不同的内核设置参数都编译一次内核，
+这简直跟噩梦一样。而且还要注意到，每个Linux发布还提供不同的Linux内核，
+这些内核都针对不同的硬件类型进行了优化（有很多种不同的处理器，还有不同
+的内核设置选项）。所以每发布一次驱动程序，都需要提供很多不同版本的内核
+模块。
+
+相信我，如果你真的要采取这种发布方式，一定会慢慢疯掉，我很久以前就有过
+深刻的教训...
+
+
+稳定的内核源代码接口
+--------------------
+
+如果有人不将他的内核驱动程序，放入公版内核的源代码树，而又想让驱动程序
+一直保持在最新的内核中可用，那么这个话题将会变得没完没了。
+ 内核开发是持续而且快节奏的，从来都不会慢下来。内核开发人员在当前接口中
+找到bug，或者找到更好的实现方式。一旦发现这些，他们就很快会去修改当前的
+接口。修改接口意味着，函数名可能会改变，结构体可能被扩充或者删减，函数
+的参数也可能发生改变。一旦接口被修改，内核中使用这些接口的地方需要同时
+修正，这样才能保证所有的东西继续工作。
+
+举一个例子，内核的USB驱动程序接口在USB子系统的整个生命周期中，至少经历
+了三次重写。这些重写解决以下问题：
+    - 把数据流从同步模式改成非同步模式，这个改动减少了一些驱动程序的
+复杂度，提高了所有USB驱动程序的吞吐率，这样几乎所有的USB设备都能以最大
+速率工作了。
+    - 修改了USB核心代码中为USB驱动分配数据包内存的方式，所有的驱动都
+需要提供更多的参数给USB核心，以修正了很多已经被记录在案的死锁。
+
+这和一些封闭源代码的操作系统形成鲜明的对比，在那些操作系统上，不得不额
+外的维护旧的USB接口。这导致了一个可能性，新的开发者依然会不小心使用旧的
+接口，以不恰当的方式编写代码，进而影响到操作系统的稳定性。
+ 在上面的例子中，所有的开发者都同意这些重要的改动，在这样的情况下修改代
+价很低。如果Linux保持一个稳定的内核源代码接口，那么就得创建一个新的接口
+；旧的，有问题的接口必须一直维护，给Linux USB开发者带来额外的工作。既然
+所有的Linux USB驱动的作者都是利用自己的时间工作，那么要求他们去做毫无意
+义的免费额外工作，是不可能的。
+ 安全问题对Linux来说十分重要。一个安全问题被发现，就会在短时间内得到修
+正。在很多情况下，这将导致Linux内核中的一些接口被重写，以从根本上避免安
+全问题。一旦接口被重写，所有使用这些接口的驱动程序，必须同时得到修正，
+以确定安全问题已经得到修复并且不可能在未来还有同样的安全问题。如果内核
+内部接口不允许改变，那么就不可能修复这样的安全问题，也不可能确认这样的
+安全问题以后不会发生。
+开发者一直在清理内核接口。如果一个接口没有人在使用了，它就会被删除。这
+样可以确保内核尽可能的小，而且所有潜在的接口都会得到尽可能完整的测试
+（没有人使用的接口是不可能得到良好的测试的）。
+
+
+要做什么
+-------
+
+如果你写了一个Linux内核驱动，但是它还不在Linux源代码树里，作为一个开发
+者，你应该怎么做？为每个发布的每个版本提供一个二进制驱动，那简直是一个
+噩梦，要跟上永远处于变化之中的内核接口，也是一件辛苦活。
+很简单，让你的驱动进入内核源代码树（要记得我们在谈论的是以GPL许可发行
+的驱动，如果你的代码不符合GPL，那么祝你好运，你只能自己解决这个问题了，
+你这个吸血鬼<把Andrew和Linus对吸血鬼的定义链接到这里>）。当你的代码加入
+公版内核源代码树之后，如果一个内核接口改变，你的驱动会直接被修改接口的
+那个人修改。保证你的驱动永远都可以编译通过，并且一直工作，你几乎不需要
+做什么事情。
+
+把驱动放到内核源代码树里会有很多的好处：
+    - 驱动的质量会提升，而维护成本（对原始作者来说）会下降。
+    - 其他人会给驱动添加新特性。
+    - 其他人会找到驱动中的bug并修复。
+    - 其他人会在驱动中找到性能优化的机会。
+    - 当外部的接口的改变需要修改驱动程序的时候，其他人会修改驱动程序
+。
+    - 不需要联系任何发行商，这个驱动会自动的随着所有的Linux发布一起发
+布。
+
+和别的操作系统相比，Linux为更多不同的设备提供现成的驱动，而且能在更多不
+同体系结构的处理器上支持这些设备。这个经过考验的开发模式，必然是错不了
+的 :)
+
+-------------
+感谢 Randy Dunlap, Andrew Morton, David Brownell, Hanna Linder,
+Robert Love, and Nishanth Aravamudan 对于本文档早期版本的评审和建议。
+
+英文版维护者： Greg Kroah-Hartman 
diff --git a/Documentation/translations/zh_CN/stable_kernel_rules.txt b/Documentation/translations/zh_CN/stable_kernel_rules.txt
new file mode 100644
index 000000000000..db4ba5a0c39a
--- /dev/null
+++ b/Documentation/translations/zh_CN/stable_kernel_rules.txt
@@ -0,0 +1,66 @@
+Chinese translated version of Documentation/process/stable-kernel-rules.rst
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Chinese maintainer: TripleX Chung 
+---------------------------------------------------------------------
+Documentation/process/stable-kernel-rules.rst 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+
+中文版维护者： 钟宇  TripleX Chung 
+中文版翻译者： 钟宇  TripleX Chung 
+中文版校译者： 李阳  Li Yang 
+               Kangkai Yin 
+
+以下为正文
+---------------------------------------------------------------------
+
+关于Linux 2.6稳定版发布，所有你想知道的事情。
+
+关于哪些类型的补丁可以被接收进入稳定版代码树，哪些不可以的规则：
+
+  - 必须是显而易见的正确，并且经过测试的。
+  - 连同上下文，不能大于100行。
+  - 必须只修正一件事情。
+  - 必须修正了一个给大家带来麻烦的真正的bug（不是“这也许是一个问题...”
+    那样的东西）。
+  - 必须修正带来如下后果的问题：编译错误（对被标记为CONFIG_BROKEN的例外），
+    内核崩溃，挂起，数据损坏，真正的安全问题，或者一些类似“哦，这不
+    好”的问题。简短的说，就是一些致命的问题。
+  - 没有“理论上的竞争条件”，除非能给出竞争条件如何被利用的解释。
+  - 不能存在任何的“琐碎的”修正（拼写修正，去掉多余空格之类的）。
+  - 必须被相关子系统的维护者接受。
+  - 必须遵循Documentation/process/submitting-patches.rst里的规则。
+
+向稳定版代码树提交补丁的过程：
+
+  - 在确认了补丁符合以上的规则后，将补丁发送到stable@vger.kernel.org。
+  - 如果补丁被接受到队列里，发送者会收到一个ACK回复，如果没有被接受，收
+    到的是NAK回复。回复需要几天的时间，这取决于开发者的时间安排。
+  - 被接受的补丁会被加到稳定版本队列里，等待其他开发者的审查。
+  - 安全方面的补丁不要发到这个列表，应该发送到security@kernel.org。
+
+审查周期：
+
+  - 当稳定版的维护者决定开始一个审查周期，补丁将被发送到审查委员会，以
+    及被补丁影响的领域的维护者（除非提交者就是该领域的维护者）并且抄送
+    到linux-kernel邮件列表。
+  - 审查委员会有48小时的时间，用来决定给该补丁回复ACK还是NAK。
+  - 如果委员会中有成员拒绝这个补丁，或者linux-kernel列表上有人反对这个
+    补丁，并提出维护者和审查委员会之前没有意识到的问题，补丁会从队列中
+    丢弃。
+  - 在审查周期结束的时候，那些得到ACK回应的补丁将会被加入到最新的稳定版
+    发布中，一个新的稳定版发布就此产生。
+  - 安全性补丁将从内核安全小组那里直接接收到稳定版代码树中，而不是通过
+    通常的审查周期。请联系内核安全小组以获得关于这个过程的更多细节。
+
+审查委员会：
+  - 由一些自愿承担这项任务的内核开发者，和几个非志愿的组成。
diff --git a/Documentation/translations/zh_CN/video4linux/omap3isp.txt b/Documentation/translations/zh_CN/video4linux/omap3isp.txt
new file mode 100644
index 000000000000..67ffbf352ae0
--- /dev/null
+++ b/Documentation/translations/zh_CN/video4linux/omap3isp.txt
@@ -0,0 +1,277 @@
+Chinese translated version of Documentation/video4linux/omap3isp.txt
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Maintainer: Laurent Pinchart 
+	  Sakari Ailus 
+	  David Cohen 
+Chinese maintainer: Fu Wei 
+---------------------------------------------------------------------
+Documentation/video4linux/omap3isp.txt 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+英文版维护者： Laurent Pinchart 
+	  Sakari Ailus 
+	  David Cohen 
+中文版维护者： 傅炜 Fu Wei 
+中文版翻译者： 傅炜 Fu Wei 
+中文版校译者： 傅炜 Fu Wei 
+
+
+以下为正文
+---------------------------------------------------------------------
+OMAP 3 图像信号处理器 (ISP) 驱动
+
+Copyright (C) 2010 Nokia Corporation
+Copyright (C) 2009 Texas Instruments, Inc.
+
+联系人: Laurent Pinchart 
+	  Sakari Ailus 
+	  David Cohen 
+
+
+介绍
+===
+
+本文档介绍了由 drivers/media/video/omap3isp 加载的德州仪器
+（TI）OMAP 3 图像信号处理器 (ISP) 驱动。原始驱动由德州仪器（TI）
+编写，但此后由诺基亚重写了两次。
+
+驱动已在以下 OMAP 3 系列的芯片中成功使用：
+
+	3430
+	3530
+	3630
+
+驱动实现了 V4L2、媒体控制器和 v4l2_subdev 接口。支持内核中使用
+v4l2_subdev 接口的传感器、镜头和闪光灯驱动。
+
+
+拆分为子设备
+==========
+
+OMAP 3 ISP 被拆分为 V4L2 子设备，ISP中的每个模块都由一个子设备
+来表示。每个子设备向用户空间提供一个 V4L2 子设备接口。
+
+	OMAP3 ISP CCP2
+	OMAP3 ISP CSI2a
+	OMAP3 ISP CCDC
+	OMAP3 ISP preview
+	OMAP3 ISP resizer
+	OMAP3 ISP AEWB
+	OMAP3 ISP AF
+	OMAP3 ISP histogram
+
+ISP 中每个可能的连接都通过一个链接嵌入到媒体控制器接口中。详见例程 [2]。
+
+
+控制 OMAP 3 ISP
+==============
+
+通常，对 OMAP 3 ISP 的配置会在下一帧起始时生效。在传感器垂直消隐期间，
+模块变为空闲时完成配置。在内存到内存的操作中，视频管道一次处理一帧。
+应用配置应在帧间完成。
+
+ISP 中的所有模块，除 CSI-2 和 （可能存在的）CCP2 接收器外，都必须
+接收完整的帧数据。因此，传感器必须保证从不发送部分帧数据给ISP。
+
+Autoidle（自动空闲）功能至少在 3430 的 ISP 模块中确实存在一些问题。
+当 omap3isp 模块参数 autoidle 非零时，autoidle（自动空闲）功能
+仅在 3630 中启用了。
+
+
+事件机制
+======
+
+OMAP 3 ISP 驱动在 CCDC 和统计（AEWB、AF 和 直方图）子设备中支持
+V4L2 事件机制接口。
+
+CCDC 子设备通过 HS_VS 中断，处理 V4L2_EVENT_FRAME_SYNC 类型
+事件，用于告知帧起始。早期版本的驱动则使用 V4L2_EVENT_OMAP3ISP_HS_VS。
+当在 CCDC 模块中接收到起始帧的第一行时，会准确地触发事件。这个事件
+可以在 CCDC 子设备中“订阅”。
+
+（当使用并行接口时，必须注意正确地配置 VS 信号极性。而当使用串行接收时
+这个会自动校正。）
+
+每个统计子设备都可以产生事件。每当一个统计缓冲区可由用户空间应用程序
+通过 VIDIOC_OMAP3ISP_STAT_REQ IOCTL 操作获取时，就会产生一个
+事件。当前存在以下事件：
+
+	V4L2_EVENT_OMAP3ISP_AEWB
+	V4L2_EVENT_OMAP3ISP_AF
+	V4L2_EVENT_OMAP3ISP_HIST
+
+这些 ioctl 的事件数据类型为 struct omap3isp_stat_event_status
+结构体。如果出现计算错误的统计，也同样会产生一个事件，但没有相关的统计
+数据缓冲区。这种情况下 omap3isp_stat_event_status.buf_err 会被
+设置为非零值。
+
+
+私有 IOCTL
+==========
+
+OMAP 3 ISP 驱动支持标准的 V4L2 IOCTL 以及可能存在且实用的控制。但
+ISP 提供的许多功能都不在标准 IOCTL 之列，例如 gamma（伽马）表和统计
+数据采集配置等。
+
+通常，会有一个私有 ioctl 用于配置每个包含硬件依赖功能的模块。
+
+支持以下私有 IOCTL：
+
+	VIDIOC_OMAP3ISP_CCDC_CFG
+	VIDIOC_OMAP3ISP_PRV_CFG
+	VIDIOC_OMAP3ISP_AEWB_CFG
+	VIDIOC_OMAP3ISP_HIST_CFG
+	VIDIOC_OMAP3ISP_AF_CFG
+	VIDIOC_OMAP3ISP_STAT_REQ
+	VIDIOC_OMAP3ISP_STAT_EN
+
+在 include/linux/omap3isp.h 中描述了这些 ioctl 使用的参数结构体。
+与特定 ISP 模块相关的 ISP 自身的详细功能在技术参考手册 (TRMs)中有
+描述，详见文档结尾。
+
+虽然在不使用任何私有 IOCTL 的情况下使用 ISP 驱动是可能的，但这样无法
+获得最佳的图像质量。AEWB、AF 和 直方图（译者注：一般用于自动曝光和增益
+控制，以及图像均衡等）模块无法在未使用适当的私有 IOCTL 配置的情况下使用。
+
+
+CCDC 和 preview（预览）模块 IOCTL
+===============================
+
+VIDIOC_OMAP3ISP_CCDC_CFG 和 VIDIOC_OMAP3ISP_PRV_CFG IOCTL
+被分别用于配置、启用和禁用 CCDC 和 preview（预览）模块的功能。在它们
+所控制的模块中，两个 IOCTL 控制多种功能。VIDIOC_OMAP3ISP_CCDC_CFG IOCTL
+接受一个指向 omap3isp_ccdc_update_config 结构体的指针作为它的参数。
+同样的，VIDIOC_OMAP3ISP_PRV_CFG 接受一个指向 omap3isp_prev_update_config
+结构体的指针。以上两个结构体定义位于 [1]。
+
+这些结构体中的 update 域标识是否针对指定的功能更新配置，而 flag 域
+则标识是启用还是禁用此功能。
+
+update 和 flag 位接受以下掩码值。CCDC 和 preview（预览）模块的
+每个单独功能都与一个 flag 关联（禁用或启用；在结构体中 flag 域的
+一部分）和一个指向功能配置数据的指针。
+
+对于 VIDIOC_OMAP3ISP_CCDC_CFG，下面列出了 update 和 flag 域
+中的有效值。 这些值可能会在同一个 IOCTL 调用中配置多个功能。
+
+        OMAP3ISP_CCDC_ALAW
+        OMAP3ISP_CCDC_LPF
+        OMAP3ISP_CCDC_BLCLAMP
+        OMAP3ISP_CCDC_BCOMP
+        OMAP3ISP_CCDC_FPC
+        OMAP3ISP_CCDC_CULL
+        OMAP3ISP_CCDC_CONFIG_LSC
+        OMAP3ISP_CCDC_TBL_LSC
+
+针对 VIDIOC_OMAP3ISP_PRV_CFG 的相应值如下：
+
+        OMAP3ISP_PREV_LUMAENH
+        OMAP3ISP_PREV_INVALAW
+        OMAP3ISP_PREV_HRZ_MED
+        OMAP3ISP_PREV_CFA
+        OMAP3ISP_PREV_CHROMA_SUPP
+        OMAP3ISP_PREV_WB
+        OMAP3ISP_PREV_BLKADJ
+        OMAP3ISP_PREV_RGB2RGB
+        OMAP3ISP_PREV_COLOR_CONV
+        OMAP3ISP_PREV_YC_LIMIT
+        OMAP3ISP_PREV_DEFECT_COR
+        OMAP3ISP_PREV_GAMMABYPASS
+        OMAP3ISP_PREV_DRK_FRM_CAPTURE
+        OMAP3ISP_PREV_DRK_FRM_SUBTRACT
+        OMAP3ISP_PREV_LENS_SHADING
+        OMAP3ISP_PREV_NF
+        OMAP3ISP_PREV_GAMMA
+
+在启用某个功能的时候，相关的配置数据指针不可为 NULL。在禁用某个功能时，
+配置数据指针会被忽略。
+
+
+统计模块 IOCTL
+=============
+
+统计子设备相较于其他子设备提供了更多动态配置选项。在图像处理流水线处于
+工作状态时，它们可以被启用、禁用和重配。
+
+统计模块总是从 CCDC 中获取输入的图像数据（由于直方图内存读取未实现）。
+统计数据可由用户通过统计子设备节点使用私有 IOCTL 获取。
+
+AEWB、AF 和 直方图子设备提供的私有 IOCTL 极大程度上反应了 ISP 硬件
+提供的寄存器级接口。有些方面纯粹和驱动程序的实现相关，这些将在下面讨论。
+
+VIDIOC_OMAP3ISP_STAT_EN
+-----------------------
+
+这个私有 IOCTL 启用/禁用 一个统计模块。如果这个申请在视频流启动前完成，
+它将在视频流水线开始工作时生效。如果视频流水线已经处于工作状态了，它将在
+CCDC 变为空闲时生效。
+
+VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG
+-----------------------------------------------------------------------------
+
+这些 IOCTL 用于配置模块。它们要求用户应用程序对硬件有深入的认识。对
+大多数域的解释可以在 OMAP 的 TRM 中找到。以下两个域对于以上所有的
+私有 IOCTL 配置都很常见，由于他们没有在 TRM 中提及，故需要对其有
+更好的认识。
+
+omap3isp_[h3a_af/h3a_aewb/hist]_config.buf_size:
+
+模块在内部处理自身缓冲。对模块数据输出所必需的缓存大小依赖于已申请的配置。
+虽然驱动支持在视频流工作时重新配置，但对于所需缓存量大于模块启用时内部
+所分配数量的情况，则不支持重新配置。在这种情况下将返回 -EBUSY。为了避免
+此类状况，无论是禁用/重配/启用模块，还是第一次配置时申请必须的缓存大小，
+都应在模块禁用的情况下进行。
+
+内部缓冲分配的大小需综合考虑所申请配置的最小缓存量以及 buf_size 域中
+所设的值。如果 buf_size 域在[minimum（最小值）, maximum（最大值）]
+缓冲大小范围之外，则应该将其调整到其范围中。驱动则会选择最大值。正确的
+buf_size 值将回写到用户应用程序中。
+
+omap3isp_[h3a_af/h3a_aewb/hist]_config.config_counter:
+
+由于配置并未在申请之后同步生效，驱动必须提供一个跟踪这类信息的方法，
+以提供更准确的数据。在一个配置被申请之后，返回到用户空间应用程序的
+config_counter 是一个与其配置相关的唯一值。当用户应用程序接收到
+一个缓冲可用或一个新的缓冲申请事件时，这个 config_counter 用于
+一个缓冲数据和一个配置的匹配。
+
+VIDIOC_OMAP3ISP_STAT_REQ
+------------------------
+
+将内部缓冲队列中最早的数据发送到用户空间，然后丢弃此缓冲区。
+omap3isp_stat_data.frame_number 域与视频缓冲的 field_count
+域相匹配。
+
+
+技术参考手册 (TRMs) 和其他文档
+==========================
+
+OMAP 3430 TRM:
+
+参考于 2011-03-05.
+
+OMAP 35xx TRM:
+ 参考于 2011-03-05.
+
+OMAP 3630 TRM:
+
+参考于 2011-03-05.
+
+DM 3730 TRM:
+ 参考于 2011-03-06.
+
+
+参考资料
+=======
+
+[1] include/linux/omap3isp.h
+
+[2] http://git.ideasonboard.org/?p=media-ctl.git;a=summary
diff --git a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
new file mode 100644
index 000000000000..698660b7f21f
--- /dev/null
+++ b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
@@ -0,0 +1,976 @@
+Chinese translated version of Documentation/video4linux/v4l2-framework.txt
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Maintainer: Mauro Carvalho Chehab 
+Chinese maintainer: Fu Wei 
+---------------------------------------------------------------------
+Documentation/video4linux/v4l2-framework.txt 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+英文版维护者： Mauro Carvalho Chehab 
+中文版维护者： 傅炜 Fu Wei 
+中文版翻译者： 傅炜 Fu Wei 
+中文版校译者： 傅炜 Fu Wei 
+
+
+以下为正文
+---------------------------------------------------------------------
+V4L2 驱动框架概览
+==============
+
+本文档描述 V4L2 框架所提供的各种结构和它们之间的关系。
+
+
+介绍
+----
+
+大部分现代 V4L2 设备由多个 IC 组成，在 /dev 下导出多个设备节点，
+并同时创建非 V4L2 设备（如 DVB、ALSA、FB、I2C 和红外输入设备）。
+由于这种硬件的复杂性，V4L2 驱动也变得非常复杂。
+
+尤其是 V4L2 必须支持 IC 实现音视频的多路复用和编解码，这就更增加了其
+复杂性。通常这些 IC 通过一个或多个 I2C 总线连接到主桥驱动器，但也可
+使用其他总线。这些设备称为“子设备”。
+
+长期以来，这个框架仅限于通过 video_device 结构体创建 V4L 设备节点，
+并使用 video_buf 处理视频缓冲（注：本文不讨论 video_buf 框架）。
+
+这意味着所有驱动必须自己设置设备实例并连接到子设备。其中一部分要正确地
+完成是比较复杂的，使得许多驱动都没有正确地实现。
+
+由于框架的缺失，有很多通用代码都不可重复利用。
+
+因此，这个框架构建所有驱动都需要的基本结构块，而统一的框架将使通用代码
+创建成实用函数并在所有驱动中共享变得更加容易。
+
+
+驱动结构
+-------
+
+所有 V4L2 驱动都有如下结构：
+
+1) 每个设备实例的结构体--包含其设备状态。
+
+2) 初始化和控制子设备的方法（如果有）。
+
+3) 创建 V4L2 设备节点 (/dev/videoX、/dev/vbiX 和 /dev/radioX)
+   并跟踪设备节点的特定数据。
+
+4) 特定文件句柄结构体--包含每个文件句柄的数据。
+
+5) 视频缓冲处理。
+
+以下是它们的初略关系图：
+
+    device instances（设备实例）
+      |
+      +-sub-device instances（子设备实例）
+      |
+      \-V4L2 device nodes（V4L2 设备节点）
+	  |
+	  \-filehandle instances（文件句柄实例）
+
+
+框架结构
+-------
+
+该框架非常类似驱动结构：它有一个 v4l2_device 结构用于保存设备
+实例的数据；一个 v4l2_subdev 结构体代表子设备实例；video_device
+结构体保存 V4L2 设备节点的数据；将来 v4l2_fh 结构体将跟踪文件句柄
+实例（暂未尚未实现）。
+
+V4L2 框架也可与媒体框架整合（可选的）。如果驱动设置了 v4l2_device
+结构体的 mdev 域，子设备和视频节点的入口将自动出现在媒体框架中。
+
+
+v4l2_device 结构体
+----------------
+
+每个设备实例都通过 v4l2_device (v4l2-device.h)结构体来表示。
+简单设备可以仅分配这个结构体，但在大多数情况下，都会将这个结构体
+嵌入到一个更大的结构体中。
+
+你必须注册这个设备实例：
+
+	v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev);
+
+注册操作将会初始化 v4l2_device 结构体。如果 dev->driver_data 域
+为 NULL，就将其指向 v4l2_dev。
+
+需要与媒体框架整合的驱动必须手动设置 dev->driver_data，指向包含
+v4l2_device 结构体实例的驱动特定设备结构体。这可以在注册 V4L2 设备
+实例前通过 dev_set_drvdata() 函数完成。同时必须设置 v4l2_device
+结构体的 mdev 域，指向适当的初始化并注册过的 media_device 实例。
+
+如果 v4l2_dev->name 为空，则它将被设置为从 dev 中衍生出的值（为了
+更加精确，形式为驱动名后跟 bus_id）。如果你在调用 v4l2_device_register
+前已经设置好了，则不会被修改。如果 dev 为 NULL，则你*必须*在调用
+v4l2_device_register 前设置 v4l2_dev->name。
+
+你可以基于驱动名和驱动的全局 atomic_t 类型的实例编号，通过
+v4l2_device_set_name() 设置 name。这样会生成类似 ivtv0、ivtv1 等
+名字。若驱动名以数字结尾，则会在编号和驱动名间插入一个破折号，如：
+cx18-0、cx18-1 等。此函数返回实例编号。
+
+第一个 “dev” 参数通常是一个指向 pci_dev、usb_interface 或
+platform_device 的指针。很少使其为 NULL，除非是一个ISA设备或者
+当一个设备创建了多个 PCI 设备，使得 v4l2_dev 无法与一个特定的父设备
+关联。
+
+你也可以提供一个 notify() 回调，使子设备可以调用它实现事件通知。
+但这个设置与子设备相关。子设备支持的任何通知必须在
+include/media/.h 中定义一个消息头。
+
+注销 v4l2_device 使用如下函数：
+
+	v4l2_device_unregister(struct v4l2_device *v4l2_dev);
+
+如果 dev->driver_data 域指向 v4l2_dev，将会被重置为 NULL。注销同时
+会自动从设备中注销所有子设备。
+
+如果你有一个热插拔设备（如USB设备），则当断开发生时，父设备将无效。
+由于 v4l2_device 有一个指向父设备的指针必须被清除，同时标志父设备
+已消失，所以必须调用以下函数：
+
+	v4l2_device_disconnect(struct v4l2_device *v4l2_dev);
+
+这个函数并*不*注销子设备，因此你依然要调用 v4l2_device_unregister()
+函数。如果你的驱动器并非热插拔的，就没有必要调用 v4l2_device_disconnect()。
+
+有时你需要遍历所有被特定驱动注册的设备。这通常发生在多个设备驱动使用
+同一个硬件的情况下。如：ivtvfb 驱动是一个使用 ivtv 硬件的帧缓冲驱动，
+同时 alsa 驱动也使用此硬件。
+
+你可以使用如下例程遍历所有注册的设备：
+
+static int callback(struct device *dev, void *p)
+{
+	struct v4l2_device *v4l2_dev = dev_get_drvdata(dev);
+
+	/* 测试这个设备是否已经初始化 */
+	if (v4l2_dev == NULL)
+		return 0;
+	...
+	return 0;
+}
+
+int iterate(void *p)
+{
+	struct device_driver *drv;
+	int err;
+
+	/* 在PCI 总线上查找ivtv驱动。
+	   pci_bus_type是全局的. 对于USB总线使用usb_bus_type。 */
+	drv = driver_find("ivtv", &pci_bus_type);
+	/* 遍历所有的ivtv设备实例 */
+	err = driver_for_each_device(drv, NULL, p, callback);
+	put_driver(drv);
+	return err;
+}
+
+有时你需要一个设备实例的运行计数。这个通常用于映射一个设备实例到一个
+模块选择数组的索引。
+
+推荐方法如下：
+
+static atomic_t drv_instance = ATOMIC_INIT(0);
+
+static int drv_probe(struct pci_dev *pdev, const struct pci_device_id *pci_id)
+{
+	...
+	state->instance = atomic_inc_return(&drv_instance) - 1;
+}
+
+如果你有多个设备节点，对于热插拔设备，知道何时注销 v4l2_device 结构体
+就比较困难。为此 v4l2_device 有引用计数支持。当调用 video_register_device
+时增加引用计数，而设备节点释放时减小引用计数。当引用计数为零，则
+v4l2_device 的release() 回调将被执行。你就可以在此时做最后的清理工作。
+
+如果创建了其他设备节点（比如 ALSA），则你可以通过以下函数手动增减
+引用计数：
+
+void v4l2_device_get(struct v4l2_device *v4l2_dev);
+
+或:
+
+int v4l2_device_put(struct v4l2_device *v4l2_dev);
+
+由于引用技术初始化为 1 ，你也需要在 disconnect() 回调（对于 USB 设备）中
+调用 v4l2_device_put，或者 remove() 回调（例如对于 PCI 设备），否则
+引用计数将永远不会为 0 。
+
+v4l2_subdev结构体
+------------------
+
+许多驱动需要与子设备通信。这些设备可以完成各种任务，但通常他们负责
+音视频复用和编解码。如网络摄像头的子设备通常是传感器和摄像头控制器。
+
+这些一般为 I2C 接口设备，但并不一定都是。为了给驱动提供调用子设备的
+统一接口，v4l2_subdev 结构体（v4l2-subdev.h）产生了。
+
+每个子设备驱动都必须有一个 v4l2_subdev 结构体。这个结构体可以单独
+代表一个简单的子设备，也可以嵌入到一个更大的结构体中，与更多设备状态
+信息保存在一起。通常有一个下级设备结构体（比如：i2c_client）包含了
+内核创建的设备数据。建议使用 v4l2_set_subdevdata() 将这个结构体的
+指针保存在 v4l2_subdev 的私有数据域(dev_priv)中。这使得通过 v4l2_subdev
+找到实际的低层总线特定设备数据变得容易。
+
+你同时需要一个从低层结构体获取 v4l2_subdev 指针的方法。对于常用的
+i2c_client 结构体，i2c_set_clientdata() 函数可用于保存一个 v4l2_subdev
+指针；对于其他总线你可能需要使用其他相关函数。
+
+桥驱动中也应保存每个子设备的私有数据，比如一个指向特定桥的各设备私有
+数据的指针。为此 v4l2_subdev 结构体提供主机私有数据域(host_priv)，
+并可通过 v4l2_get_subdev_hostdata() 和 v4l2_set_subdev_hostdata()
+访问。
+
+从总线桥驱动的视角，驱动加载子设备模块并以某种方式获得 v4l2_subdev
+结构体指针。对于 i2c 总线设备相对简单：调用 i2c_get_clientdata()。
+对于其他总线也需要做类似的操作。针对 I2C 总线上的子设备辅助函数帮你
+完成了大部分复杂的工作。
+
+每个 v4l2_subdev 都包含子设备驱动需要实现的函数指针（如果对此设备
+不适用，可为NULL）。由于子设备可完成许多不同的工作，而在一个庞大的
+函数指针结构体中通常仅有少数有用的函数实现其功能肯定不合适。所以，
+函数指针根据其实现的功能被分类，每一类都有自己的函数指针结构体。
+
+顶层函数指针结构体包含了指向各类函数指针结构体的指针，如果子设备驱动
+不支持该类函数中的任何一个功能，则指向该类结构体的指针为NULL。
+
+这些结构体定义如下：
+
+struct v4l2_subdev_core_ops {
+	int (*log_status)(struct v4l2_subdev *sd);
+	int (*init)(struct v4l2_subdev *sd, u32 val);
+	...
+};
+
+struct v4l2_subdev_tuner_ops {
+	...
+};
+
+struct v4l2_subdev_audio_ops {
+	...
+};
+
+struct v4l2_subdev_video_ops {
+	...
+};
+
+struct v4l2_subdev_pad_ops {
+	...
+};
+
+struct v4l2_subdev_ops {
+	const struct v4l2_subdev_core_ops  *core;
+	const struct v4l2_subdev_tuner_ops *tuner;
+	const struct v4l2_subdev_audio_ops *audio;
+	const struct v4l2_subdev_video_ops *video;
+	const struct v4l2_subdev_pad_ops *video;
+};
+
+其中 core（核心）函数集通常可用于所有子设备，其他类别的实现依赖于
+子设备。如视频设备可能不支持音频操作函数，反之亦然。
+
+这样的设置在限制了函数指针数量的同时，还使增加新的操作函数和分类
+变得较为容易。
+
+子设备驱动可使用如下函数初始化 v4l2_subdev 结构体：
+
+	v4l2_subdev_init(sd, &ops);
+
+然后，你必须用一个唯一的名字初始化 subdev->name，并初始化模块的
+owner 域。若使用 i2c 辅助函数，这些都会帮你处理好。
+
+若需同媒体框架整合，你必须调用 media_entity_pads_init() 初始化 v4l2_subdev
+结构体中的 media_entity 结构体（entity 域）：
+
+	struct media_pad *pads = &my_sd->pads;
+	int err;
+
+	err = media_entity_pads_init(&sd->entity, npads, pads);
+
+pads 数组必须预先初始化。无须手动设置 media_entity 的 type 和
+name 域，但如有必要，revision 域必须初始化。
+
+当（任何）子设备节点被打开/关闭，对 entity 的引用将被自动获取/释放。
+
+在子设备被注销之后，不要忘记清理 media_entity 结构体：
+
+	media_entity_cleanup(&sd->entity);
+
+如果子设备驱动趋向于处理视频并整合进了媒体框架，必须使用 v4l2_subdev_pad_ops
+替代 v4l2_subdev_video_ops 实现格式相关的功能。
+
+这种情况下，子设备驱动应该设置 link_validate 域，以提供它自身的链接
+验证函数。链接验证函数应对管道（两端链接的都是 V4L2 子设备）中的每个
+链接调用。驱动还要负责验证子设备和视频节点间格式配置的正确性。
+
+如果 link_validate 操作没有设置，默认的 v4l2_subdev_link_validate_default()
+函数将会被调用。这个函数保证宽、高和媒体总线像素格式在链接的收发两端
+都一致。子设备驱动除了它们自己的检测外，也可以自由使用这个函数以执行
+上面提到的检查。
+
+设备（桥）驱动程序必须向 v4l2_device 注册 v4l2_subdev：
+
+	int err = v4l2_device_register_subdev(v4l2_dev, sd);
+
+如果子设备模块在它注册前消失，这个操作可能失败。在这个函数成功返回后，
+subdev->dev 域就指向了 v4l2_device。
+
+如果 v4l2_device 父设备的 mdev 域为非 NULL 值，则子设备实体将被自动
+注册为媒体设备。
+
+注销子设备则可用如下函数：
+
+	v4l2_device_unregister_subdev(sd);
+
+此后，子设备模块就可卸载，且 sd->dev == NULL。
+
+注册之设备后，可通过以下方式直接调用其操作函数：
+
+	err = sd->ops->core->g_std(sd, &norm);
+
+但使用如下宏会比较容易且合适：
+
+	err = v4l2_subdev_call(sd, core, g_std, &norm);
+
+这个宏将会做 NULL 指针检查，如果 subdev 为 NULL，则返回-ENODEV；如果
+subdev->core 或 subdev->core->g_std 为 NULL，则返回 -ENOIOCTLCMD；
+否则将返回 subdev->ops->core->g_std ops 调用的实际结果。
+
+有时也可能同时调用所有或一系列子设备的某个操作函数：
+
+	v4l2_device_call_all(v4l2_dev, 0, core, g_std, &norm);
+
+任何不支持此操作的子设备都会被跳过，并忽略错误返回值。但如果你需要
+检查出错码，则可使用如下函数：
+
+	err = v4l2_device_call_until_err(v4l2_dev, 0, core, g_std, &norm);
+
+除 -ENOIOCTLCMD 外的任何错误都会跳出循环并返回错误值。如果（除 -ENOIOCTLCMD
+外）没有错误发生，则返回 0。
+
+对于以上两个函数的第二个参数为组 ID。如果为 0，则所有子设备都会执行
+这个操作。如果为非 0 值，则只有那些组 ID 匹配的子设备才会执行此操作。
+在桥驱动注册一个子设备前，可以设置 sd->grp_id 为任何期望值（默认值为
+0）。这个值属于桥驱动，且子设备驱动将不会修改和使用它。
+
+组 ID 赋予了桥驱动更多对于如何调用回调的控制。例如，电路板上有多个
+音频芯片，每个都有改变音量的能力。但当用户想要改变音量的时候，通常
+只有一个会被实际使用。你可以对这样的子设备设置组 ID 为（例如 AUDIO_CONTROLLER）
+并在调用 v4l2_device_call_all() 时指定它为组 ID 值。这就保证了只有
+需要的子设备才会执行这个回调。
+
+如果子设备需要通知它的 v4l2_device 父设备一个事件，可以调用
+v4l2_subdev_notify(sd, notification, arg)。这个宏检查是否有一个
+notify() 回调被注册，如果没有，返回 -ENODEV。否则返回 notify() 调用
+结果。
+
+使用 v4l2_subdev 的好处在于它是一个通用结构体，且不包含任何底层硬件
+信息。所有驱动可以包含多个 I2C 总线的子设备，但也有子设备是通过 GPIO
+控制。这个区别仅在配置设备时有关系，一旦子设备注册完成，对于 v4l2
+子系统来说就完全透明了。
+
+
+V4L2 子设备用户空间API
+--------------------
+
+除了通过 v4l2_subdev_ops 结构导出的内核 API，V4L2 子设备也可以直接
+通过用户空间应用程序来控制。
+
+可以在 /dev 中创建名为 v4l-subdevX 设备节点，以通过其直接访问子设备。
+如果子设备支持用户空间直接配置，必须在注册前设置 V4L2_SUBDEV_FL_HAS_DEVNODE
+标志。
+
+注册子设备之后， v4l2_device 驱动会通过调用 v4l2_device_register_subdev_nodes()
+函数为所有已注册并设置了 V4L2_SUBDEV_FL_HAS_DEVNODE 的子设备创建
+设备节点。这些设备节点会在子设备注销时自动删除。
+
+这些设备节点处理 V4L2 API 的一个子集。
+
+VIDIOC_QUERYCTRL
+VIDIOC_QUERYMENU
+VIDIOC_G_CTRL
+VIDIOC_S_CTRL
+VIDIOC_G_EXT_CTRLS
+VIDIOC_S_EXT_CTRLS
+VIDIOC_TRY_EXT_CTRLS
+
+	这些 ioctls 控制与 V4L2 中定义的一致。他们行为相同，唯一的
+	不同是他们只处理子设备的控制实现。根据驱动程序，这些控制也
+	可以通过一个（或多个） V4L2 设备节点访问。
+
+VIDIOC_DQEVENT
+VIDIOC_SUBSCRIBE_EVENT
+VIDIOC_UNSUBSCRIBE_EVENT
+
+	这些  ioctls 事件与 V4L2 中定义的一致。他们行为相同，唯一的
+	不同是他们只处理子设备产生的事件。根据驱动程序，这些事件也
+	可以通过一个（或多个） V4L2 设备节点上报。
+
+	要使用事件通知的子设备驱动，在注册子设备前必须在 v4l2_subdev::flags
+	中设置 V4L2_SUBDEV_USES_EVENTS 并在 v4l2_subdev::nevents
+	中初始化事件队列深度。注册完成后，事件会在 v4l2_subdev::devnode
+	设备节点中像通常一样被排队。
+
+	为正确支持事件机制，poll() 文件操作也应被实现。
+
+私有 ioctls
+
+	不在以上列表中的所有 ioctls 会通过 core::ioctl 操作直接传递
+	给子设备驱动。
+
+
+I2C 子设备驱动
+-------------
+
+由于这些驱动很常见，所以内特提供了特定的辅助函数(v4l2-common.h)让这些
+设备的使用更加容易。
+
+添加 v4l2_subdev 支持的推荐方法是让 I2C 驱动将 v4l2_subdev 结构体
+嵌入到为每个 I2C 设备实例创建的状态结构体中。而最简单的设备没有状态
+结构体，此时可以直接创建一个 v4l2_subdev 结构体。
+
+一个典型的状态结构体如下所示（‘chipname’用芯片名代替）：
+
+struct chipname_state {
+	struct v4l2_subdev sd;
+	...  /* 附加的状态域*/
+};
+
+初始化 v4l2_subdev 结构体的方法如下：
+
+	v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
+
+这个函数将填充 v4l2_subdev 结构体中的所有域，并保证 v4l2_subdev 和
+i2c_client 都指向彼此。
+
+同时，你也应该为从 v4l2_subdev 指针找到 chipname_state 结构体指针
+添加一个辅助内联函数。
+
+static inline struct chipname_state *to_state(struct v4l2_subdev *sd)
+{
+	return container_of(sd, struct chipname_state, sd);
+}
+
+使用以下函数可以通过 v4l2_subdev 结构体指针获得 i2c_client 结构体
+指针：
+
+	struct i2c_client *client = v4l2_get_subdevdata(sd);
+
+而以下函数则相反，通过 i2c_client 结构体指针获得 v4l2_subdev 结构体
+指针：
+
+	struct v4l2_subdev *sd = i2c_get_clientdata(client);
+
+当 remove()函数被调用前，必须保证先调用 v4l2_device_unregister_subdev(sd)。
+此操作将会从桥驱动中注销子设备。即使子设备没有注册，调用此函数也是
+安全的。
+
+必须这样做的原因是：当桥驱动注销 i2c 适配器时，remove()回调函数
+会被那个适配器上的 i2c 设备调用。此后，相应的 v4l2_subdev 结构体
+就不存在了，所有它们必须先被注销。在 remove()回调函数中调用
+v4l2_device_unregister_subdev(sd)，可以保证执行总是正确的。
+
+
+桥驱动也有一些辅组函数可用：
+
+struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter,
+	       "module_foo", "chipid", 0x36, NULL);
+
+这个函数会加载给定的模块（如果没有模块需要加载，可以为 NULL），
+并用给定的 i2c 适配器结构体指针（i2c_adapter）和 器件地址（chip/address）
+作为参数调用 i2c_new_device()。如果一切顺利，则就在 v4l2_device
+中注册了子设备。
+
+你也可以利用 v4l2_i2c_new_subdev()的最后一个参数，传递一个可能的
+I2C 地址数组，让函数自动探测。这些探测地址只有在前一个参数为 0 的
+情况下使用。非零参数意味着你知道准确的 i2c 地址，所以此时无须进行
+探测。
+
+如果出错，两个函数都返回 NULL。
+
+注意：传递给 v4l2_i2c_new_subdev()的 chipid 通常与模块名一致。
+它允许你指定一个芯片的变体，比如“saa7114”或“saa7115”。一般通过
+i2c 驱动自动探测。chipid 的使用是在今后需要深入了解的事情。这个与
+i2c 驱动不同，较容易混淆。要知道支持哪些芯片变体，你可以查阅 i2c
+驱动代码的 i2c_device_id 表，上面列出了所有可能支持的芯片。
+
+还有两个辅助函数：
+
+v4l2_i2c_new_subdev_cfg：这个函数添加新的 irq 和 platform_data
+参数，并有‘addr’和‘probed_addrs’参数：如果 addr 非零，则被使用
+（不探测变体），否则 probed_addrs 中的地址将用于自动探测。
+
+例如：以下代码将会探测地址（0x10）：
+
+struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter,
+	       "module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10));
+
+v4l2_i2c_new_subdev_board 使用一个 i2c_board_info 结构体，将其
+替代 irq、platform_data 和 add r参数传递给 i2c 驱动。
+
+如果子设备支持 s_config 核心操作，这个操作会在子设备配置好之后以 irq 和
+platform_data 为参数调用。早期的 v4l2_i2c_new_(probed_)subdev 函数
+同样也会调用 s_config，但仅在 irq 为 0 且 platform_data 为 NULL 时。
+
+video_device结构体
+-----------------
+
+在 /dev 目录下的实际设备节点根据 video_device 结构体(v4l2-dev.h)
+创建。此结构体既可以动态分配也可以嵌入到一个更大的结构体中。
+
+动态分配方法如下：
+
+	struct video_device *vdev = video_device_alloc();
+
+	if (vdev == NULL)
+		return -ENOMEM;
+
+	vdev->release = video_device_release;
+
+如果将其嵌入到一个大结构体中，则必须自己实现 release()回调。
+
+	struct video_device *vdev = &my_vdev->vdev;
+
+	vdev->release = my_vdev_release;
+
+release()回调必须被设置，且在最后一个 video_device 用户退出之后
+被调用。
+
+默认的 video_device_release()回调只是调用 kfree 来释放之前分配的
+内存。
+
+你应该设置这些域：
+
+- v4l2_dev: 设置为 v4l2_device 父设备。
+
+- name: 设置为唯一的描述性设备名。
+
+- fops: 设置为已有的 v4l2_file_operations 结构体。
+
+- ioctl_ops: 如果你使用v4l2_ioctl_ops 来简化 ioctl 的维护
+  (强烈建议使用，且将来可能变为强制性的!)，然后设置你自己的
+  v4l2_ioctl_ops 结构体.
+
+- lock: 如果你要在驱动中实现所有的锁操作，则设为 NULL 。否则
+  就要设置一个指向 struct mutex_lock 结构体的指针，这个锁将
+  在 unlocked_ioctl 文件操作被调用前由内核获得，并在调用返回后
+  释放。详见下一节。
+
+- prio: 保持对优先级的跟踪。用于实现 VIDIOC_G/S_PRIORITY。如果
+  设置为 NULL，则会使用 v4l2_device 中的 v4l2_prio_state 结构体。
+  如果要对每个设备节点（组）实现独立的优先级，可以将其指向自己
+  实现的 v4l2_prio_state 结构体。
+
+- parent: 仅在使用 NULL 作为父设备结构体参数注册 v4l2_device 时
+  设置此参数。只有在一个硬件设备包含多一个 PCI 设备，共享同一个
+  v4l2_device 核心时才会发生。
+
+  cx88 驱动就是一个例子：一个 v4l2_device 结构体核心，被一个裸的
+  视频 PCI 设备(cx8800)和一个 MPEG PCI 设备(cx8802)共用。由于
+  v4l2_device 无法与特定的 PCI 设备关联，所有没有设置父设备。但当
+  video_device 配置后，就知道使用哪个父 PCI 设备了。
+
+如果你使用 v4l2_ioctl_ops，则应该在 v4l2_file_operations 结构体中
+设置 .unlocked_ioctl 指向 video_ioctl2。
+
+请勿使用 .ioctl！它已被废弃，今后将消失。
+
+某些情况下你要告诉核心：你在 v4l2_ioctl_ops 指定的某个函数应被忽略。
+你可以在 video_device_register 被调用前通过以下函数标记这个 ioctls。
+
+void v4l2_disable_ioctl(struct video_device *vdev, unsigned int cmd);
+
+基于外部因素（例如某个板卡已被使用），在不创建新结构体的情况下，你想
+要关闭 v4l2_ioctl_ops 中某个特性往往需要这个机制。
+
+v4l2_file_operations 结构体是 file_operations 的一个子集。其主要
+区别在于：因 inode 参数从未被使用，它将被忽略。
+
+如果需要与媒体框架整合，你必须通过调用 media_entity_pads_init() 初始化
+嵌入在 video_device 结构体中的 media_entity（entity 域）结构体：
+
+	struct media_pad *pad = &my_vdev->pad;
+	int err;
+
+	err = media_entity_pads_init(&vdev->entity, 1, pad);
+
+pads 数组必须预先初始化。没有必要手动设置 media_entity 的 type 和
+name 域。
+
+当（任何）子设备节点被打开/关闭，对 entity 的引用将被自动获取/释放。
+
+v4l2_file_operations 与锁
+--------------------------
+
+你可以在 video_device 结构体中设置一个指向 mutex_lock 的指针。通常
+这既可是一个顶层互斥锁也可为设备节点自身的互斥锁。默认情况下，此锁
+用于 unlocked_ioctl，但为了使用 ioctls 你通过以下函数可禁用锁定：
+
+	void v4l2_disable_ioctl_locking(struct video_device *vdev, unsigned int cmd);
+
+例如: v4l2_disable_ioctl_locking(vdev, VIDIOC_DQBUF);
+
+你必须在注册 video_device 前调用这个函数。
+
+特别是对于 USB 驱动程序，某些命令（如设置控制）需要很长的时间，可能
+需要自行为缓冲区队列的 ioctls 实现锁定。
+
+如果你需要更细粒度的锁，你必须设置 mutex_lock 为 NULL，并完全自己实现
+锁机制。
+
+这完全由驱动开发者决定使用何种方法。然而，如果你的驱动存在长延时操作
+（例如，改变 USB 摄像头的曝光时间可能需要较长时间），而你又想让用户
+在等待长延时操作完成期间做其他的事，则你最好自己实现锁机制。
+
+如果指定一个锁，则所有 ioctl 操作将在这个锁的作用下串行执行。如果你
+使用 videobuf，则必须将同一个锁传递给 videobuf 队列初始化函数；如
+videobuf 必须等待一帧的到达，则可临时解锁并在这之后重新上锁。如果驱动
+也在代码执行期间等待，则可做同样的工作（临时解锁，再上锁）让其他进程
+可以在第一个进程阻塞时访问设备节点。
+
+在使用 videobuf2 的情况下，必须实现 wait_prepare 和 wait_finish 回调
+在适当的时候解锁/加锁。进一步来说，如果你在 video_device 结构体中使用
+锁，则必须在 wait_prepare 和 wait_finish 中对这个互斥锁进行解锁/加锁。
+
+热插拔的断开实现也必须在调用 v4l2_device_disconnect 前获得锁。
+
+video_device注册
+---------------
+
+接下来你需要注册视频设备：这会为你创建一个字符设备。
+
+	err = video_register_device(vdev, VFL_TYPE_GRABBER, -1);
+	if (err) {
+		video_device_release(vdev); /* or kfree(my_vdev); */
+		return err;
+	}
+
+如果 v4l2_device 父设备的 mdev 域为非 NULL 值，视频设备实体将自动
+注册为媒体设备。
+
+注册哪种设备是根据类型（type）参数。存在以下类型：
+
+VFL_TYPE_GRABBER: 用于视频输入/输出设备的 videoX
+VFL_TYPE_VBI: 用于垂直消隐数据的 vbiX (例如，隐藏式字幕，图文电视)
+VFL_TYPE_RADIO: 用于广播调谐器的 radioX
+
+最后一个参数让你确定一个所控制设备的设备节点号数量(例如 videoX 中的 X)。
+通常你可以传入-1，让 v4l2 框架自己选择第一个空闲的编号。但是有时用户
+需要选择一个特定的节点号。驱动允许用户通过驱动模块参数选择一个特定的
+设备节点号是很普遍的。这个编号将会传递给这个函数，且 video_register_device
+将会试图选择这个设备节点号。如果这个编号被占用，下一个空闲的设备节点
+编号将被选中，并向内核日志中发送一个警告信息。
+
+另一个使用场景是当驱动创建多个设备时。这种情况下，对不同的视频设备在
+编号上使用不同的范围是很有用的。例如，视频捕获设备从 0 开始，视频
+输出设备从 16 开始。所以你可以使用最后一个参数来指定设备节点号最小值，
+而 v4l2 框架会试图选择第一个的空闲编号（等于或大于你提供的编号）。
+如果失败，则它会就选择第一个空闲的编号。
+
+由于这种情况下，你会忽略无法选择特定设备节点号的警告，则可调用
+video_register_device_no_warn() 函数避免警告信息的产生。
+
+只要设备节点被创建，一些属性也会同时创建。在 /sys/class/video4linux
+目录中你会找到这些设备。例如进入其中的 video0 目录，你会看到‘name’和
+‘index’属性。‘name’属性值就是 video_device 结构体中的‘name’域。
+
+‘index’属性值就是设备节点的索引值：每次调用 video_register_device()，
+索引值都递增 1 。第一个视频设备节点总是从索引值 0 开始。
+
+用户可以设置 udev 规则，利用索引属性生成花哨的设备名（例如：用‘mpegX’
+代表 MPEG 视频捕获设备节点）。
+
+在设备成功注册后，就可以使用这些域：
+
+- vfl_type: 传递给 video_register_device 的设备类型。
+- minor: 已指派的次设备号。
+- num: 设备节点编号 (例如 videoX 中的 X)。
+- index: 设备索引号。
+
+如果注册失败，你必须调用 video_device_release() 来释放已分配的
+video_device 结构体；如果 video_device 是嵌入在自己创建的结构体中，
+你也必须释放它。vdev->release() 回调不会在注册失败之后被调用，
+你也不应试图在注册失败后注销设备。
+
+
+video_device 注销
+----------------
+
+当视频设备节点已被移除，不论是卸载驱动还是USB设备断开，你都应注销
+它们：
+
+	video_unregister_device(vdev);
+
+这个操作将从 sysfs 中移除设备节点（导致 udev 将其从 /dev 中移除）。
+
+video_unregister_device() 返回之后，就无法完成打开操作。尽管如此，
+USB 设备的情况则不同，某些应用程序可能依然打开着其中一个已注销设备
+节点。所以在注销之后，所有文件操作（当然除了 release ）也应返回错误值。
+
+当最后一个视频设备节点的用户退出，则 vdev->release() 回调会被调用，
+并且你可以做最后的清理操作。
+
+不要忘记清理与视频设备相关的媒体入口（如果被初始化过）：
+
+	media_entity_cleanup(&vdev->entity);
+
+这可以在 release 回调中完成。
+
+
+video_device 辅助函数
+---------------------
+
+一些有用的辅助函数如下：
+
+- file/video_device 私有数据
+
+你可以用以下函数在 video_device 结构体中设置/获取驱动私有数据：
+
+void *video_get_drvdata(struct video_device *vdev);
+void video_set_drvdata(struct video_device *vdev, void *data);
+
+注意：在调用 video_register_device() 前执行 video_set_drvdata()
+是安全的。
+
+而以下函数：
+
+struct video_device *video_devdata(struct file *file);
+
+返回 file 结构体中拥有的的 video_device 指针。
+
+video_drvdata 辅助函数结合了 video_get_drvdata 和 video_devdata
+的功能：
+
+void *video_drvdata(struct file *file);
+
+你可以使用如下代码从 video_device 结构体中获取 v4l2_device 结构体
+指针：
+
+struct v4l2_device *v4l2_dev = vdev->v4l2_dev;
+
+- 设备节点名
+
+video_device 设备节点在内核中的名称可以通过以下函数获得
+
+const char *video_device_node_name(struct video_device *vdev);
+
+这个名字被用户空间工具（例如 udev）作为提示信息使用。应尽可能使用
+此功能，而非访问 video_device::num 和 video_device::minor 域。
+
+
+视频缓冲辅助函数
+---------------
+
+v4l2 核心 API 提供了一个处理视频缓冲的标准方法(称为“videobuf”)。
+这些方法使驱动可以通过统一的方式实现 read()、mmap() 和 overlay()。
+目前在设备上支持视频缓冲的方法有分散/聚集 DMA(videobuf-dma-sg)、
+线性 DMA(videobuf-dma-contig)以及大多用于 USB 设备的用 vmalloc
+分配的缓冲(videobuf-vmalloc)。
+
+请参阅 Documentation/video4linux/videobuf，以获得更多关于 videobuf
+层的使用信息。
+
+v4l2_fh 结构体
+-------------
+
+v4l2_fh 结构体提供一个保存用于 V4L2 框架的文件句柄特定数据的简单方法。
+如果 video_device 标志，新驱动
+必须使用 v4l2_fh 结构体，因为它也用于实现优先级处理（VIDIOC_G/S_PRIORITY）。
+
+v4l2_fh 的用户（位于 V4l2 框架中，并非驱动）可通过测试
+video_device->flags 中的 V4L2_FL_USES_V4L2_FH 位得知驱动是否使用
+v4l2_fh 作为他的 file->private_data 指针。这个位会在调用 v4l2_fh_init()
+时被设置。
+
+v4l2_fh 结构体作为驱动自身文件句柄结构体的一部分被分配，且驱动在
+其打开函数中将 file->private_data 指向它。
+
+在许多情况下，v4l2_fh 结构体会嵌入到一个更大的结构体中。这钟情况下，
+应该在 open() 中调用 v4l2_fh_init+v4l2_fh_add，并在 release() 中
+调用 v4l2_fh_del+v4l2_fh_exit。
+
+驱动可以通过使用 container_of 宏提取他们自己的文件句柄结构体。例如：
+
+struct my_fh {
+	int blah;
+	struct v4l2_fh fh;
+};
+
+...
+
+int my_open(struct file *file)
+{
+	struct my_fh *my_fh;
+	struct video_device *vfd;
+	int ret;
+
+	...
+
+	my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
+
+	...
+
+	v4l2_fh_init(&my_fh->fh, vfd);
+
+	...
+
+	file->private_data = &my_fh->fh;
+	v4l2_fh_add(&my_fh->fh);
+	return 0;
+}
+
+int my_release(struct file *file)
+{
+	struct v4l2_fh *fh = file->private_data;
+	struct my_fh *my_fh = container_of(fh, struct my_fh, fh);
+
+	...
+	v4l2_fh_del(&my_fh->fh);
+	v4l2_fh_exit(&my_fh->fh);
+	kfree(my_fh);
+	return 0;
+}
+
+以下是 v4l2_fh 函数使用的简介：
+
+void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev)
+
+  初始化文件句柄。这*必须*在驱动的 v4l2_file_operations->open()
+  函数中执行。
+
+void v4l2_fh_add(struct v4l2_fh *fh)
+
+  添加一个 v4l2_fh 到 video_device 文件句柄列表。一旦文件句柄
+  初始化完成就必须调用。
+
+void v4l2_fh_del(struct v4l2_fh *fh)
+
+  从 video_device() 中解除文件句柄的关联。文件句柄的退出函数也
+  将被调用。
+
+void v4l2_fh_exit(struct v4l2_fh *fh)
+
+  清理文件句柄。在清理完 v4l2_fh 后，相关内存会被释放。
+
+
+如果 v4l2_fh 不是嵌入在其他结构体中的，则可以用这些辅助函数：
+
+int v4l2_fh_open(struct file *filp)
+
+  分配一个 v4l2_fh 结构体空间，初始化并将其添加到 file 结构体相关的
+  video_device 结构体中。
+
+int v4l2_fh_release(struct file *filp)
+
+  从 file 结构体相关的 video_device 结构体中删除 v4l2_fh ，清理
+  v4l2_fh 并释放空间。
+
+这两个函数可以插入到 v4l2_file_operation 的 open() 和 release()
+操作中。
+
+
+某些驱动需要在第一个文件句柄打开和最后一个文件句柄关闭的时候做些
+工作。所以加入了两个辅助函数以检查 v4l2_fh 结构体是否是相关设备
+节点打开的唯一文件句柄。
+
+int v4l2_fh_is_singular(struct v4l2_fh *fh)
+
+  如果此文件句柄是唯一打开的文件句柄，则返回 1 ，否则返回 0 。
+
+int v4l2_fh_is_singular_file(struct file *filp)
+
+  功能相同，但通过 filp->private_data 调用 v4l2_fh_is_singular。
+
+
+V4L2 事件机制
+-----------
+
+V4L2 事件机制提供了一个通用的方法将事件传递到用户空间。驱动必须使用
+v4l2_fh 才能支持 V4L2 事件机制。
+
+
+事件通过一个类型和选择 ID 来定义。ID 对应一个 V4L2 对象，例如
+一个控制 ID。如果未使用，则 ID 为 0。
+
+当用户订阅一个事件，驱动会为此分配一些 kevent 结构体。所以每个
+事件组（类型、ID）都会有自己的一套 kevent 结构体。这保证了如果
+一个驱动短时间内产生了许多同类事件，不会覆盖其他类型的事件。
+
+但如果你收到的事件数量大于同类事件 kevent 的保存数量，则最早的
+事件将被丢弃，并加入新事件。
+
+此外，v4l2_subscribed_event 结构体内部有可供驱动设置的 merge() 和
+replace() 回调，这些回调会在新事件产生且没有多余空间的时候被调用。
+replace() 回调让你可以将早期事件的净荷替换为新事件的净荷，将早期
+净荷的相关数据合并到替换进来的新净荷中。当该类型的事件仅分配了一个
+kevent 结构体时，它将被调用。merge() 回调让你可以合并最早的事件净荷
+到在它之后的那个事件净荷中。当该类型的事件分配了两个或更多 kevent
+结构体时，它将被调用。
+
+这种方法不会有状态信息丢失，只会导致中间步骤信息丢失。
+
+
+关于 replace/merge 回调的一个不错的例子在 v4l2-event.c 中：用于
+控制事件的 ctrls_replace() 和 ctrls_merge() 回调。
+
+注意：这些回调可以在中断上下文中调用，所以它们必须尽快完成并退出。
+
+有用的函数：
+
+void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev)
+
+  将事件加入视频设备的队列。驱动仅负责填充 type 和 data 域。
+  其他域由 V4L2 填充。
+
+int v4l2_event_subscribe(struct v4l2_fh *fh,
+			 struct v4l2_event_subscription *sub, unsigned elems,
+			 const struct v4l2_subscribed_event_ops *ops)
+
+  video_device->ioctl_ops->vidioc_subscribe_event 必须检测驱动能
+  产生特定 id 的事件。然后调用 v4l2_event_subscribe() 来订阅该事件。
+
+  elems 参数是该事件的队列大小。若为 0，V4L2 框架将会（根据事件类型）
+  填充默认值。
+
+  ops 参数允许驱动指定一系列回调：
+  * add:     当添加一个新监听者时调用（重复订阅同一个事件，此回调
+             仅被执行一次）。
+  * del:     当一个监听者停止监听时调用。
+  * replace: 用‘新’事件替换‘早期‘事件。
+  * merge:   将‘早期‘事件合并到‘新’事件中。
+  这四个调用都是可选的，如果不想指定任何回调，则 ops 可为 NULL。
+
+int v4l2_event_unsubscribe(struct v4l2_fh *fh,
+			   struct v4l2_event_subscription *sub)
+
+  v4l2_ioctl_ops 结构体中的 vidioc_unsubscribe_event 回调函数。
+  驱动程序可以直接使用 v4l2_event_unsubscribe() 实现退订事件过程。
+
+  特殊的 V4L2_EVENT_ALL 类型，可用于退订所有事件。驱动可能在特殊
+  情况下需要做此操作。
+
+int v4l2_event_pending(struct v4l2_fh *fh)
+
+  返回未决事件的数量。有助于实现轮询（poll）操作。
+
+事件通过 poll 系统调用传递到用户空间。驱动可用
+v4l2_fh->wait (wait_queue_head_t 类型)作为参数调用 poll_wait()。
+
+事件分为标准事件和私有事件。新的标准事件必须使用可用的最小事件类型
+编号。驱动必须从他们本类型的编号起始处分配事件。类型的编号起始为
+V4L2_EVENT_PRIVATE_START + n * 1000 ，其中 n 为可用最小编号。每个
+类型中的第一个事件类型编号是为以后的使用保留的，所以第一个可用事件
+类型编号是‘class base + 1’。
+
+V4L2 事件机制的使用实例可以在 OMAP3 ISP 的驱动
+(drivers/media/video/omap3isp)中找到。
diff --git a/Documentation/translations/zh_CN/volatile-considered-harmful.txt b/Documentation/translations/zh_CN/volatile-considered-harmful.txt
new file mode 100644
index 000000000000..475125967197
--- /dev/null
+++ b/Documentation/translations/zh_CN/volatile-considered-harmful.txt
@@ -0,0 +1,113 @@
+Chinese translated version of Documentation/process/volatile-considered-harmful.rst
+
+If you have any comment or update to the content, please contact the
+original document maintainer directly.  However, if you have a problem
+communicating in English you can also ask the Chinese maintainer for
+help.  Contact the Chinese maintainer if this translation is outdated
+or if there is a problem with the translation.
+
+Maintainer: Jonathan Corbet 
+Chinese maintainer: Bryan Wu 
+---------------------------------------------------------------------
+Documentation/process/volatile-considered-harmful.rst 的中文翻译
+
+如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
+交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
+译存在问题，请联系中文版维护者。
+
+英文版维护者： Jonathan Corbet 
+中文版维护者： 伍鹏  Bryan Wu 
+中文版翻译者： 伍鹏  Bryan Wu 
+中文版校译者： 张汉辉  Eugene Teo 
+               杨瑞  Dave Young 
+以下为正文
+---------------------------------------------------------------------
+
+为什么不应该使用“volatile”类型
+------------------------------
+
+C程序员通常认为volatile表示某个变量可以在当前执行的线程之外被改变；因此，在内核
+中用到共享数据结构时，常常会有C程序员喜欢使用volatile这类变量。换句话说，他们经
+常会把volatile类型看成某种简易的原子变量，当然它们不是。在内核中使用volatile几
+乎总是错误的；本文档将解释为什么这样。
+
+理解volatile的关键是知道它的目的是用来消除优化，实际上很少有人真正需要这样的应
+用。在内核中，程序员必须防止意外的并发访问破坏共享的数据结构，这其实是一个完全
+不同的任务。用来防止意外并发访问的保护措施，可以更加高效的避免大多数优化相关的
+问题。
+
+像volatile一样，内核提供了很多原语来保证并发访问时的数据安全（自旋锁, 互斥量,内
+存屏障等等），同样可以防止意外的优化。如果可以正确使用这些内核原语，那么就没有
+必要再使用volatile。如果仍然必须使用volatile，那么几乎可以肯定在代码的某处有一
+个bug。在正确设计的内核代码中，volatile能带来的仅仅是使事情变慢。
+
+思考一下这段典型的内核代码：
+
+    spin_lock(&the_lock);
+    do_something_on(&shared_data);
+    do_something_else_with(&shared_data);
+    spin_unlock(&the_lock);
+
+如果所有的代码都遵循加锁规则，当持有the_lock的时候，不可能意外的改变shared_data的
+值。任何可能访问该数据的其他代码都会在这个锁上等待。自旋锁原语跟内存屏障一样—— 它
+们显式的用来书写成这样 —— 意味着数据访问不会跨越它们而被优化。所以本来编译器认为
+它知道在shared_data里面将有什么，但是因为spin_lock()调用跟内存屏障一样，会强制编
+译器忘记它所知道的一切。那么在访问这些数据时不会有优化的问题。
+
+如果shared_data被声名为volatile，锁操作将仍然是必须的。就算我们知道没有其他人正在
+使用它，编译器也将被阻止优化对临界区内shared_data的访问。在锁有效的同时，
+shared_data不是volatile的。在处理共享数据的时候，适当的锁操作可以不再需要
+volatile —— 并且是有潜在危害的。
+
+volatile的存储类型最初是为那些内存映射的I/O寄存器而定义。在内核里，寄存器访问也应
+该被锁保护，但是人们也不希望编译器“优化”临界区内的寄存器访问。内核里I/O的内存访问
+是通过访问函数完成的；不赞成通过指针对I/O内存的直接访问，并且不是在所有体系架构上
+都能工作。那些访问函数正是为了防止意外优化而写的，因此，再说一次，volatile类型不
+是必需的。
+
+另一种引起用户可能使用volatile的情况是当处理器正忙着等待一个变量的值。正确执行一
+个忙等待的方法是：
+
+    while (my_variable != what_i_want)
+        cpu_relax();
+
+cpu_relax()调用会降低CPU的能量消耗或者让位于超线程双处理器；它也作为内存屏障一样出
+现，所以，再一次，volatile不是必需的。当然，忙等待一开始就是一种反常规的做法。
+
+在内核中，一些稀少的情况下volatile仍然是有意义的：
+
+  - 在一些体系架构的系统上，允许直接的I/0内存访问，那么前面提到的访问函数可以使用
+    volatile。基本上，每一个访问函数调用它自己都是一个小的临界区域并且保证了按照
+    程序员期望的那样发生访问操作。
+
+  - 某些会改变内存的内联汇编代码虽然没有什么其他明显的附作用，但是有被GCC删除的可
+    能性。在汇编声明中加上volatile关键字可以防止这种删除操作。
+
+  - Jiffies变量是一种特殊情况，虽然每次引用它的时候都可以有不同的值，但读jiffies
+    变量时不需要任何特殊的加锁保护。所以jiffies变量可以使用volatile，但是不赞成
+    其他跟jiffies相同类型变量使用volatile。Jiffies被认为是一种“愚蠢的遗留物"
+    （Linus的话）因为解决这个问题比保持现状要麻烦的多。
+
+  - 由于某些I/0设备可能会修改连续一致的内存,所以有时,指向连续一致内存的数据结构
+    的指针需要正确的使用volatile。网络适配器使用的环状缓存区正是这类情形的一个例
+    子，其中适配器用改变指针来表示哪些描述符已经处理过了。
+
+对于大多代码，上述几种可以使用volatile的情况都不适用。所以，使用volatile是一种
+bug并且需要对这样的代码额外仔细检查。那些试图使用volatile的开发人员需要退一步想想
+他们真正想实现的是什么。
+
+非常欢迎删除volatile变量的补丁 － 只要证明这些补丁完整的考虑了并发问题。
+
+注释
+----
+
+[1] http://lwn.net/Articles/233481/
+[2] http://lwn.net/Articles/233482/
+
+致谢
+----
+
+最初由Randy Dunlap推动并作初步研究
+由Jonathan Corbet撰写
+参考Satyam Sharma，Johannes Stezenbach，Jesper Juhl，Heikki Orsila，
+H. Peter Anvin，Philipp Hahn和Stefan Richter的意见改善了本档。
diff --git a/Documentation/zh_CN/CodingStyle b/Documentation/zh_CN/CodingStyle
deleted file mode 100644
index b02738042799..000000000000
--- a/Documentation/zh_CN/CodingStyle
+++ /dev/null
@@ -1,813 +0,0 @@
-Chinese translated version of Documentation/process/coding-style.rst
-
-If you have any comment or update to the content, please post to LKML directly.
-However, if you have problem communicating in English you can also ask the
-Chinese maintainer for help.  Contact the Chinese maintainer, if this
-translation is outdated or there is problem with translation.
-
-Chinese maintainer: Zhang Le 
----------------------------------------------------------------------
-Documentation/process/coding-style.rst的中文翻译
-
-如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可
-以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。
-
-中文版维护者： 张乐 Zhang Le 
-中文版翻译者： 张乐 Zhang Le 
-中文版校译者： 王聪 Wang Cong 
-               wheelz 
-               管旭东 Xudong Guan 
-               Li Zefan 
-               Wang Chen 
-以下为正文
----------------------------------------------------------------------
-
-		Linux内核代码风格
-
-这是一个简短的文档，描述了 linux 内核的首选代码风格。代码风格是因人而异的，而且我
-不愿意把自己的观点强加给任何人，但这就像我去做任何事情都必须遵循的原则那样，我也
-希望在绝大多数事上保持这种的态度。请（在写代码时）至少考虑一下这里的代码风格。
-
-首先，我建议你打印一份 GNU 代码规范，然后不要读。烧了它，这是一个具有重大象征性意义
-的动作。
-
-不管怎样，现在我们开始：
-
-
-		第一章：缩进
-
-制表符是 8 个字符，所以缩进也是 8 个字符。有些异端运动试图将缩进变为 4（甚至 2！）
-个字符深，这几乎相当于尝试将圆周率的值定义为 3。
-
-理由：缩进的全部意义就在于清楚的定义一个控制块起止于何处。尤其是当你盯着你的屏幕
-连续看了 20 小时之后，你将会发现大一点的缩进会使你更容易分辨缩进。
-
-现在，有些人会抱怨 8 个字符的缩进会使代码向右边移动的太远，在 80 个字符的终端屏幕上
-就很难读这样的代码。这个问题的答案是，如果你需要 3 级以上的缩进，不管用何种方式你
-的代码已经有问题了，应该修正你的程序。
-
-简而言之，8 个字符的缩进可以让代码更容易阅读，还有一个好处是当你的函数嵌套太深的
-时候可以给你警告。留心这个警告。
-
-在 switch 语句中消除多级缩进的首选的方式是让 “switch” 和从属于它的 “case” 标签
-对齐于同一列，而不要 “两次缩进” “case” 标签。比如：
-
-	switch (suffix) {
-	case 'G':
-	case 'g':
-		mem <<= 30;
-		break;
-	case 'M':
-	case 'm':
-		mem <<= 20;
-		break;
-	case 'K':
-	case 'k':
-		mem <<= 10;
-		/* fall through */
-	default:
-		break;
-	}
-
-不要把多个语句放在一行里，除非你有什么东西要隐藏：
-
-	if (condition) do_this;
-	  do_something_everytime;
-
-也不要在一行里放多个赋值语句。内核代码风格超级简单。就是避免可能导致别人误读的表
-达式。
-
-除了注释、文档和 Kconfig 之外，不要使用空格来缩进，前面的例子是例外，是有意为之。
-
-选用一个好的编辑器，不要在行尾留空格。
-
-
-		第二章：把长的行和字符串打散
-
-代码风格的意义就在于使用平常使用的工具来维持代码的可读性和可维护性。
-
-每一行的长度的限制是 80 列，我们强烈建议您遵守这个惯例。
-
-长于 80 列的语句要打散成有意义的片段。除非超过 80 列能显著增加可读性，并且不会隐藏
-信息。子片段要明显短于母片段，并明显靠右。这同样适用于有着很长参数列表的函数头。
-然而，绝对不要打散对用户可见的字符串，例如 printk 信息，因为这将导致无法 grep 这些
-信息。
-
-		第三章：大括号和空格的放置
-
-C语言风格中另外一个常见问题是大括号的放置。和缩进大小不同，选择或弃用某种放置策
-略并没有多少技术上的原因，不过首选的方式，就像 Kernighan 和 Ritchie 展示给我们的，
-是把起始大括号放在行尾，而把结束大括号放在行首，所以：
-
-	if (x is true) {
-		we do y
-	}
-
-这适用于所有的非函数语句块（if、switch、for、while、do）。比如：
-
-	switch (action) {
-	case KOBJ_ADD:
-		return "add";
-	case KOBJ_REMOVE:
-		return "remove";
-	case KOBJ_CHANGE:
-		return "change";
-	default:
-		return NULL;
-	}
-
-不过，有一个例外，那就是函数：函数的起始大括号放置于下一行的开头，所以：
-
-	int function(int x)
-	{
-		body of function
-	}
-
-全世界的异端可能会抱怨这个不一致性是……呃……不一致的，不过所有思维健全的人都知道
-(a) K&R 是 _正确的_，并且 (b) K&R 是正确的。此外，不管怎样函数都是特殊的（C
-函数是不能嵌套的）。
-
-注意结束大括号独自占据一行，除非它后面跟着同一个语句的剩余部分，也就是 do 语句中的
-“while” 或者 if 语句中的 “else”，像这样：
-
-	do {
-		body of do-loop
-	} while (condition);
-
-和
-
-	if (x == y) {
-		..
-	} else if (x > y) {
-		...
-	} else {
-		....
-	}
-
-理由：K&R。
-
-也请注意这种大括号的放置方式也能使空（或者差不多空的）行的数量最小化，同时不失可
-读性。因此，由于你的屏幕上的新行是不可再生资源（想想 25 行的终端屏幕），你将会有更
-多的空行来放置注释。
-
-当只有一个单独的语句的时候，不用加不必要的大括号。
-
-	if (condition)
-		action();
-
-和
-
-	if (condition)
-		do_this();
-	else
-		do_that();
-
-这并不适用于只有一个条件分支是单语句的情况；这时所有分支都要使用大括号：
-
-	if (condition) {
-		do_this();
-		do_that();
-	} else {
-		otherwise();
-	}
-
-		3.1：空格
-
-Linux 内核的空格使用方式（主要）取决于它是用于函数还是关键字。（大多数）关键字后
-要加一个空格。值得注意的例外是 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);
-
-不要在小括号里的表达式两侧加空格。这是一个反例：
-
-	s = sizeof( struct file );
-
-当声明指针类型或者返回指针类型的函数时，“*” 的首选使用方式是使之靠近变量名或者函
-数名，而不是靠近类型名。例子：
-
-	char *linux_banner;
-	unsigned long long memparse(char *ptr, char **retptr);
-	char *match_strdup(substring_t *s);
-
-在大多数二元和三元操作符两侧使用一个空格，例如下面所有这些操作符：
-
-	=  +  -  <  >  *  /  %  |  &  ^  <=  >=  ==  !=  ?  :
-
-但是一元操作符后不要加空格：
-
-	&  *  +  -  ~  !  sizeof  typeof  alignof  __attribute__  defined
-
-后缀自加和自减一元操作符前不加空格：
-
-	++  --
-
-前缀自加和自减一元操作符后不加空格：
-
-	++  --
-
-‘.’ 和 “->” 结构体成员操作符前后不加空格。
-
-不要在行尾留空白。有些可以自动缩进的编辑器会在新行的行首加入适量的空白，然后你
-就可以直接在那一行输入代码。不过假如你最后没有在那一行输入代码，有些编辑器就不
-会移除已经加入的空白，就像你故意留下一个只有空白的行。包含行尾空白的行就这样产
-生了。
-
-当git发现补丁包含了行尾空白的时候会警告你，并且可以应你的要求去掉行尾空白；不过
-如果你是正在打一系列补丁，这样做会导致后面的补丁失败，因为你改变了补丁的上下文。
-
-
-		第四章：命名
-
-C是一个简朴的语言，你的命名也应该这样。和 Modula-2 和 Pascal 程序员不同，C 程序员
-不使用类似 ThisVariableIsATemporaryCounter 这样华丽的名字。C 程序员会称那个变量
-为 “tmp”，这样写起来会更容易，而且至少不会令其难于理解。
-
-不过，虽然混用大小写的名字是不提倡使用的，但是全局变量还是需要一个具描述性的名字
-。称一个全局函数为 “foo” 是一个难以饶恕的错误。
-
-全局变量（只有当你真正需要它们的时候再用它）需要有一个具描述性的名字，就像全局函
-数。如果你有一个可以计算活动用户数量的函数，你应该叫它 “count_active_users()”
-或者类似的名字，你不应该叫它 “cntuser()”。
-
-在函数名中包含函数类型（所谓的匈牙利命名法）是脑子出了问题——编译器知道那些类型而
-且能够检查那些类型，这样做只能把程序员弄糊涂了。难怪微软总是制造出有问题的程序。
-
-本地变量名应该简短，而且能够表达相关的含义。如果你有一些随机的整数型的循环计数器
-，它应该被称为 “i”。叫它 “loop_counter” 并无益处，如果它没有被误解的可能的话。
-类似的，“tmp” 可以用来称呼任意类型的临时变量。
-
-如果你怕混淆了你的本地变量名，你就遇到另一个问题了，叫做函数增长荷尔蒙失衡综合症
-。请看第六章（函数）。
-
-
-		第五章：Typedef
-
-不要使用类似 “vps_t” 之类的东西。
-
-对结构体和指针使用 typedef 是一个错误。当你在代码里看到：
-
-	vps_t a;
-
-这代表什么意思呢？
-
-相反，如果是这样
-
-	struct virtual_container *a;
-
-你就知道 “a” 是什么了。
-
-很多人认为 typedef “能提高可读性”。实际不是这样的。它们只在下列情况下有用：
-
- (a) 完全不透明的对象（这种情况下要主动使用 typedef 来隐藏这个对象实际上是什么）。
-
-     例如：“pte_t” 等不透明对象，你只能用合适的访问函数来访问它们。
-
-     注意！不透明性和“访问函数”本身是不好的。我们使用 pte_t 等类型的原因在于真的是
-     完全没有任何共用的可访问信息。
-
- (b) 清楚的整数类型，如此，这层抽象就可以帮助消除到底是 “int” 还是 “long” 的混淆。
-
-     u8/u16/u32 是完全没有问题的 typedef，不过它们更符合类别 (d) 而不是这里。
-
-     再次注意！要这样做，必须事出有因。如果某个变量是 “unsigned long“，那么没有必要
-
-	typedef unsigned long myflags_t;
-
-     不过如果有一个明确的原因，比如它在某种情况下可能会是一个 “unsigned int” 而在
-     其他情况下可能为 “unsigned long”，那么就不要犹豫，请务必使用 typedef。
-
- (c) 当你使用sparse按字面的创建一个新类型来做类型检查的时候。
-
- (d) 和标准C99类型相同的类型，在某些例外的情况下。
-
-     虽然让眼睛和脑筋来适应新的标准类型比如 “uint32_t” 不需要花很多时间，可是有些
-     人仍然拒绝使用它们。
-
-     因此，Linux 特有的等同于标准类型的 “u8/u16/u32/u64” 类型和它们的有符号类型是被
-     允许的——尽管在你自己的新代码中，它们不是强制要求要使用的。
-
-     当编辑已经使用了某个类型集的已有代码时，你应该遵循那些代码中已经做出的选择。
-
- (e) 可以在用户空间安全使用的类型。
-
-     在某些用户空间可见的结构体里，我们不能要求C99类型而且不能用上面提到的 “u32”
-     类型。因此，我们在与用户空间共享的所有结构体中使用 __u32 和类似的类型。
-
-可能还有其他的情况，不过基本的规则是永远不要使用 typedef，除非你可以明确的应用上
-述某个规则中的一个。
-
-总的来说，如果一个指针或者一个结构体里的元素可以合理的被直接访问到，那么它们就不
-应该是一个 typedef。
-
-
-		第六章：函数
-
-函数应该简短而漂亮，并且只完成一件事情。函数应该可以一屏或者两屏显示完（我们都知
-道 ISO/ANSI 屏幕大小是 80x24），只做一件事情，而且把它做好。
-
-一个函数的最大长度是和该函数的复杂度和缩进级数成反比的。所以，如果你有一个理论上
-很简单的只有一个很长（但是简单）的 case 语句的函数，而且你需要在每个 case 里做
-很多很小的事情，这样的函数尽管很长，但也是可以的。
-
-不过，如果你有一个复杂的函数，而且你怀疑一个天分不是很高的高中一年级学生可能甚至
-搞不清楚这个函数的目的，你应该严格的遵守前面提到的长度限制。使用辅助函数，并为之
-取个具描述性的名字（如果你觉得它们的性能很重要的话，可以让编译器内联它们，这样的
-效果往往会比你写一个复杂函数的效果要好。）
-
-函数的另外一个衡量标准是本地变量的数量。此数量不应超过 5－10 个，否则你的函数就有
-问题了。重新考虑一下你的函数，把它分拆成更小的函数。人的大脑一般可以轻松的同时跟
-踪 7 个不同的事物，如果再增多的话，就会糊涂了。即便你聪颖过人，你也可能会记不清你
-2 个星期前做过的事情。
-
-在源文件里，使用空行隔开不同的函数。如果该函数需要被导出，它的 EXPORT* 宏应该紧贴
-在它的结束大括号之下。比如：
-
-	int system_is_up(void)
-	{
-		return system_state == SYSTEM_RUNNING;
-	}
-	EXPORT_SYMBOL(system_is_up);
-
-在函数原型中，包含函数名和它们的数据类型。虽然C语言里没有这样的要求，在 Linux 里这
-是提倡的做法，因为这样可以很简单的给读者提供更多的有价值的信息。
-
-
-		第七章：集中的函数退出途径
-
-虽然被某些人声称已经过时，但是 goto 语句的等价物还是经常被编译器所使用，具体形式是
-无条件跳转指令。
-
-当一个函数从多个位置退出，并且需要做一些类似清理的常见操作时，goto 语句就很方便了。
-如果并不需要清理操作，那么直接 return 即可。
-
-理由是：
-
-- 无条件语句容易理解和跟踪
-- 嵌套程度减小
-- 可以避免由于修改时忘记更新某个单独的退出点而导致的错误
-- 减轻了编译器的工作，无需删除冗余代码;)
-
-	int fun(int a)
-	{
-		int result = 0;
-		char *buffer;
-
-		buffer = kmalloc(SIZE, GFP_KERNEL);
-		if (!buffer)
-			return -ENOMEM;
-
-		if (condition1) {
-			while (loop1) {
-				...
-			}
-			result = 1;
-			goto out_buffer;
-		}
-		...
-	out_buffer:
-		kfree(buffer);
-		return result;
-	}
-
-一个需要注意的常见错误是“一个 err 错误”，就像这样：
-
-	err:
-		kfree(foo->bar);
-		kfree(foo);
-		return ret;
-
-这段代码的错误是，在某些退出路径上 “foo” 是 NULL。通常情况下，通过把它分离成两个
-错误标签 “err_bar:” 和 “err_foo:” 来修复这个错误。
-
-		第八章：注释
-
-注释是好的，不过有过度注释的危险。永远不要在注释里解释你的代码是如何运作的：更好
-的做法是让别人一看你的代码就可以明白，解释写的很差的代码是浪费时间。
-
-一般的，你想要你的注释告诉别人你的代码做了什么，而不是怎么做的。也请你不要把注释
-放在一个函数体内部：如果函数复杂到你需要独立的注释其中的一部分，你很可能需要回到
-第六章看一看。你可以做一些小注释来注明或警告某些很聪明（或者槽糕）的做法，但不要
-加太多。你应该做的，是把注释放在函数的头部，告诉人们它做了什么，也可以加上它做这
-些事情的原因。
-
-当注释内核API函数时，请使用 kernel-doc 格式。请看
-Documentation/kernel-documentation.rst和scripts/kernel-doc 以获得详细信息。
-
-Linux的注释风格是 C89 “/* ... */” 风格。不要使用 C99 风格 “// ...” 注释。
-
-长（多行）的首选注释风格是：
-
-	/*
-	 * This is the preferred style for multi-line
-	 * comments in the Linux kernel source code.
-	 * Please use it consistently.
-	 *
-	 * Description:  A column of asterisks on the left side,
-	 * 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.
-	 */
-
-注释数据也是很重要的，不管是基本类型还是衍生类型。为了方便实现这一点，每一行应只
-声明一个数据（不要使用逗号来一次声明多个数据）。这样你就有空间来为每个数据写一段
-小注释来解释它们的用途了。
-
-
-		第九章：你已经把事情弄糟了
-
-这没什么，我们都是这样。可能你的使用了很长时间 Unix 的朋友已经告诉你 “GNU emacs” 能
-自动帮你格式化 C 源代码，而且你也注意到了，确实是这样，不过它所使用的默认值和我们
-想要的相去甚远（实际上，甚至比随机打的还要差——无数个猴子在 GNU emacs 里打字永远不
-会创造出一个好程序）（译注：请参考 Infinite Monkey Theorem）
-
-所以你要么放弃 GNU emacs，要么改变它让它使用更合理的设定。要采用后一个方案，你可
-以把下面这段粘贴到你的 .emacs 文件里。
-
-(defun c-lineup-arglist-tabs-only (ignored)
-  "Line up argument lists by tabs, not spaces"
-  (let* ((anchor (c-langelem-pos c-syntactic-element))
-         (column (c-langelem-2nd-pos c-syntactic-element))
-         (offset (- (1+ column) anchor))
-         (steps (floor offset c-basic-offset)))
-    (* (max steps 1)
-       c-basic-offset)))
-
-(add-hook 'c-mode-common-hook
-          (lambda ()
-            ;; Add kernel style
-            (c-add-style
-             "linux-tabs-only"
-             '("linux" (c-offsets-alist
-                        (arglist-cont-nonempty
-                         c-lineup-gcc-asm-reg
-                         c-lineup-arglist-tabs-only))))))
-
-(add-hook 'c-mode-hook
-          (lambda ()
-            (let ((filename (buffer-file-name)))
-              ;; Enable kernel mode for the appropriate files
-              (when (and filename
-                         (string-match (expand-file-name "~/src/linux-trees")
-                                       filename))
-                (setq indent-tabs-mode t)
-                (setq show-trailing-whitespace t)
-                (c-set-style "linux-tabs-only")))))
-
-这会让 emacs 在 ~/src/linux-trees 目录下的 C 源文件获得更好的内核代码风格。
-
-不过就算你尝试让 emacs 正确的格式化代码失败了，也并不意味着你失去了一切：还可以用
-“indent”。
-
-不过，GNU indent 也有和 GNU emacs 一样有问题的设定，所以你需要给它一些命令选项。不
-过，这还不算太糟糕，因为就算是 GNU indent 的作者也认同 K&R 的权威性（GNU 的人并不是
-坏人，他们只是在这个问题上被严重的误导了），所以你只要给 indent 指定选项 “-kr -i8”
-（代表 “K&R，8 个字符缩进”），或者使用 “scripts/Lindent”，这样就可以以最时髦的方式
-缩进源代码。
-
-“indent” 有很多选项，特别是重新格式化注释的时候，你可能需要看一下它的手册页。不过
-记住：“indent” 不能修正坏的编程习惯。
-
-
-		第十章：Kconfig 配置文件
-
-对于遍布源码树的所有 Kconfig* 配置文件来说，它们缩进方式与 C 代码相比有所不同。紧挨
-在 “config” 定义下面的行缩进一个制表符，帮助信息则再多缩进 2 个空格。比如：
-
-config AUDIT
-	bool "Auditing support"
-	depends on NET
-	help
-	  Enable auditing infrastructure that can be used with another
-	  kernel subsystem, such as SELinux (which requires this for
-	  logging of avc messages output).  Does not do system-call
-	  auditing without CONFIG_AUDITSYSCALL.
-
-而那些危险的功能（比如某些文件系统的写支持）应该在它们的提示字符串里显著的声明这
-一点：
-
-config ADFS_FS_RW
-	bool "ADFS write support (DANGEROUS)"
-	depends on ADFS_FS
-	...
-
-要查看配置文件的完整文档，请看 Documentation/kbuild/kconfig-language.txt。
-
-
-		第十一章：数据结构
-
-如果一个数据结构，在创建和销毁它的单线执行环境之外可见，那么它必须要有一个引用计
-数器。内核里没有垃圾收集（并且内核之外的垃圾收集慢且效率低下），这意味着你绝对需
-要记录你对这种数据结构的使用情况。
-
-引用计数意味着你能够避免上锁，并且允许多个用户并行访问这个数据结构——而不需要担心
-这个数据结构仅仅因为暂时不被使用就消失了，那些用户可能不过是沉睡了一阵或者做了一
-些其他事情而已。
-
-注意上锁不能取代引用计数。上锁是为了保持数据结构的一致性，而引用计数是一个内存管
-理技巧。通常二者都需要，不要把两个搞混了。
-
-很多数据结构实际上有2级引用计数，它们通常有不同“类”的用户。子类计数器统计子类用
-户的数量，每当子类计数器减至零时，全局计数器减一。
-
-这种“多级引用计数”的例子可以在内存管理（“struct mm_struct”：mm_users 和 mm_count）
-和文件系统（“struct super_block”：s_count和s_active）中找到。
-
-记住：如果另一个执行线索可以找到你的数据结构，但是这个数据结构没有引用计数器，这
-里几乎肯定是一个 bug。
-
-
-		第十二章：宏，枚举和RTL
-
-用于定义常量的宏的名字及枚举里的标签需要大写。
-
-#define CONSTANT 0x12345
-
-在定义几个相关的常量时，最好用枚举。
-
-宏的名字请用大写字母，不过形如函数的宏的名字可以用小写字母。
-
-一般的，如果能写成内联函数就不要写成像函数的宏。
-
-含有多个语句的宏应该被包含在一个 do-while 代码块里：
-
-	#define macrofun(a, b, c)			\
-		do {					\
-			if (a == 5)			\
-				do_this(b, c);		\
-		} while (0)
-
-使用宏的时候应避免的事情：
-
-1) 影响控制流程的宏：
-
-	#define FOO(x)					\
-		do {					\
-			if (blah(x) < 0)		\
-				return -EBUGGERED;	\
-		} while (0)
-
-非常不好。它看起来像一个函数，不过却能导致“调用”它的函数退出；不要打乱读者大脑里
-的语法分析器。
-
-2) 依赖于一个固定名字的本地变量的宏：
-
-	#define FOO(val) bar(index, val)
-
-可能看起来像是个不错的东西，不过它非常容易把读代码的人搞糊涂，而且容易导致看起来
-不相关的改动带来错误。
-
-3) 作为左值的带参数的宏： FOO(x) = y；如果有人把 FOO 变成一个内联函数的话，这种用
-法就会出错了。
-
-4) 忘记了优先级：使用表达式定义常量的宏必须将表达式置于一对小括号之内。带参数的
-宏也要注意此类问题。
-
-	#define CONSTANT 0x4000
-	#define CONSTEXP (CONSTANT | 3)
-
-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”。保证这些信息简单、明了、
-无歧义。
-
-内核信息不必以句号（译注：英文句号，即点）结束。
-
-在小括号里打印数字 (%d) 没有任何价值，应该避免这样做。
-
- 里有一些驱动模型诊断宏，你应该使用它们，以确保信息对应于正确的
-设备和驱动，并且被标记了正确的消息级别。这些宏有：dev_err()，dev_warn()，
-dev_info() 等等。对于那些不和某个特定设备相关连的信息， 定义了
-pr_notice()，pr_info()，pr_warn()，pr_err() 和其他。
-
-写出好的调试信息可以是一个很大的挑战；一旦你写出后，这些信息在远程除错时能提供极大
-的帮助。然而打印调试信息的处理方式同打印非调试信息不同。其他 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()，kmalloc_array()，kcalloc()，vmalloc() 和 vzalloc()。
-请参考 API 文档以获取有关它们的详细信息。
-
-传递结构体大小的首选形式是这样的：
-
-	p = kmalloc(sizeof(*p), ...);
-
-另外一种传递方式中，sizeof 的操作数是结构体的名字，这样会降低可读性，并且可能会引
-入 bug。有可能指针变量类型被改变时，而对应的传递给内存分配函数的 sizeof 的结果不变。
-
-强制转换一个 void 指针返回值是多余的。C 语言本身保证了从 void 指针到其他任何指针类型
-的转换是没有问题的。
-
-分配一个数组的首选形式是这样的：
-
-	p = kmalloc_array(n, sizeof(...), ...);
-
-分配一个零长数组的首选形式是这样的：
-
-	p = kcalloc(n, sizeof(...), ...);
-
-两种形式检查分配大小 n * sizeof(...) 的溢出，如果溢出返回 NULL。
-
-
-		第十五章：内联弊病
-
-有一个常见的误解是内联函数是 gcc 提供的可以让代码运行更快的一个选项。虽然使用内联
-函数有时候是恰当的（比如作为一种替代宏的方式，请看第十二章），不过很多情况下不是
-这样。inline 关键字的过度使用会使内核变大，从而使整个系统运行速度变慢。因为大内核
-会占用更多的指令高速缓存（译注：一级缓存通常是指令缓存和数据缓存分开的）而且会导
-致 pagecache 的可用内存减少。想象一下，一次pagecache未命中就会导致一次磁盘寻址，
-将耗时 5 毫秒。5 毫秒的时间内 CPU 能执行很多很多指令。
-
-一个基本的原则是如果一个函数有 3 行以上，就不要把它变成内联函数。这个原则的一个例
-外是，如果你知道某个参数是一个编译时常量，而且因为这个常量你确定编译器在编译时能
-优化掉你的函数的大部分代码，那仍然可以给它加上 inline 关键字。kmalloc() 内联函数就
-是一个很好的例子。
-
-人们经常主张给 static 的而且只用了一次的函数加上 inline，如此不会有任何损失，因为没
-有什么好权衡的。虽然从技术上说这是正确的，但是实际上这种情况下即使不加 inline gcc
-也可以自动使其内联。而且其他用户可能会要求移除 inline，由此而来的争论会抵消 inline
-自身的潜在价值，得不偿失。
-
-
-		第十六章：函数返回值及命名
-
-函数可以返回很多种不同类型的值，最常见的一种是表明函数执行成功或者失败的值。这样
-的一个值可以表示为一个错误代码整数（-Exxx＝失败，0＝成功）或者一个“成功”布尔值（
-0＝失败，非0＝成功）。
-
-混合使用这两种表达方式是难于发现的 bug 的来源。如果 C 语言本身严格区分整形和布尔型变
-量，那么编译器就能够帮我们发现这些错误……不过 C 语言不区分。为了避免产生这种 bug，请
-遵循下面的惯例：
-
-	如果函数的名字是一个动作或者强制性的命令，那么这个函数应该返回错误代码整
-	数。如果是一个判断，那么函数应该返回一个“成功”布尔值。
-
-比如，“add work” 是一个命令，所以 add_work() 函数在成功时返回 0，在失败时返回 -EBUSY。
-类似的，因为 “PCI device present” 是一个判断，所以 pci_dev_present() 函数在成功找到
-一个匹配的设备时应该返回 1，如果找不到时应该返回 0。
-
-所有导出（译注：EXPORT）的函数都必须遵守这个惯例，所有的公共函数也都应该如此。私
-有（static）函数不需要如此，但是我们也推荐这样做。
-
-返回值是实际计算结果而不是计算是否成功的标志的函数不受此惯例的限制。一般的，他们
-通过返回一些正常值范围之外的结果来表示出错。典型的例子是返回指针的函数，他们使用
-NULL 或者 ERR_PTR 机制来报告错误。
-
-
-		第十七章：不要重新发明内核宏
-
-头文件 include/linux/kernel.h 包含了一些宏，你应该使用它们，而不要自己写一些它们的
-变种。比如，如果你需要计算一个数组的长度，使用这个宏
-
-	#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
-
-类似的，如果你要计算某结构体成员的大小，使用
-
-	#define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
-
-还有可以做严格的类型检查的 min() 和 max() 宏，如果你需要可以使用它们。你可以自己看看
-那个头文件里还定义了什么你可以拿来用的东西，如果有定义的话，你就不应在你的代码里
-自己重新定义。
-
-
-		第十八章：编辑器模式行和其他需要罗嗦的事情
-
-有一些编辑器可以解释嵌入在源文件里的由一些特殊标记标明的配置信息。比如，emacs
-能够解释被标记成这样的行：
-
-	-*- mode: c -*-
-
-或者这样的：
-
-	/*
-	Local Variables:
-	compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
-	End:
-	*/
-
-Vim 能够解释这样的标记：
-
-	/* vim:set sw=8 noet */
-
-不要在源代码中包含任何这样的内容。每个人都有他自己的编辑器配置，你的源文件不应
-该覆盖别人的配置。这包括有关缩进和模式配置的标记。人们可以使用他们自己定制的模
-式，或者使用其他可以产生正确的缩进的巧妙方法。
-
-
-		第十九章：内联汇编
-
-在特定架构的代码中，你也许需要内联汇编来使用 CPU 接口和平台相关功能。在需要
-这么做时，不要犹豫。然而，当 C 可以完成工作时，不要无端地使用内联汇编。如果
-可能，你可以并且应该用 C 和硬件交互。
-
-考虑去写通用一点的内联汇编作为简明的辅助函数，而不是重复写下它们的细节。记住
-内联汇编可以使用 C 参数。
-
-大而特殊的汇编函数应该放在 .S 文件中，对应 C 的原型定义在 C 头文件中。汇编
-函数的 C 原型应该使用 “asmlinkage”。
-
-你可能需要将你的汇编语句标记为 volatile，来阻止 GCC 在没发现任何副作用后就
-移除了它。你不必总是这样做，虽然，这样可以限制不必要的优化。
-
-在写一个包含多条指令的单个内联汇编语句时，把每条指令用引号字符串分离，并写在
-单独一行，在每个字符串结尾，除了 \n\t 结尾之外，在汇编输出中适当地缩进下
-一条指令：
-
-	asm ("magic %reg1, #42\n\t"
-	     "more_magic %reg2, %reg3"
-	     : /* outputs */ : /* inputs */ : /* clobbers */);
-
-
-		第二十章：条件编译
-
-只要可能，就不要在 .c 文件里面使用预处理条件；这样做让代码更难阅读并且逻辑难以
-跟踪。替代方案是，在头文件定义函数在这些 .c 文件中使用这类的条件表达式，提供空
-操作的桩版本（译注：桩程序，是指用来替换一部分功能的程序段）在 #else 情况下，
-再从 .c 文件中无条件地调用这些函数。编译器会避免生成任何桩调用的代码，产生一致
-的结果，但逻辑将更加清晰。
-
-宁可编译整个函数，而不是部分函数或部分表达式。而不是在一个表达式添加 ifdef，
-解析部分或全部表达式到一个单独的辅助函数，并应用条件到该函数内。
-
-如果你有一个在特定配置中可能是未使用的函数或变量，编译器将警告它定义了但未使用，
-标记这个定义为 __maybe_unused 而不是将它包含在一个预处理条件中。（然而，如果
-一个函数或变量总是未使用的，就直接删除它。）
-
-在代码中，可能的情况下，使用 IS_ENABLED 宏来转化某个 Kconfig 标记为 C 的布尔
-表达式，并在正常的 C 条件中使用它：
-
-	if (IS_ENABLED(CONFIG_SOMETHING)) {
-		...
-	}
-
-编译器会无条件地做常数合并，就像使用 #ifdef 那样，包含或排除代码块，所以这不会
-带来任何运行时开销。然而，这种方法依旧允许 C 编译器查看块内的代码，并检查它的正确
-性（语法，类型，符号引用，等等）。因此，如果条件不满足，代码块内的引用符号将不存在，
-你必须继续使用 #ifdef。
-
-在任何有意义的 #if 或 #ifdef 块的末尾（超过几行），在 #endif 同一行的后面写下
-注释，指出该条件表达式被使用。例如：
-
-	#ifdef CONFIG_SOMETHING
-	...
-	#endif /* CONFIG_SOMETHING */
-
-
-		附录 I：参考
-
-The C Programming Language, 第二版
-作者：Brian W. Kernighan 和 Denni M. Ritchie.
-Prentice Hall, Inc., 1988.
-ISBN 0-13-110362-8 (软皮), 0-13-110370-9 (硬皮).
-
-The Practice of Programming
-作者：Brian W. Kernighan 和 Rob Pike.
-Addison-Wesley, Inc., 1999.
-ISBN 0-201-61586-X.
-
-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 process/coding-style.rst，作者 greg@kroah.com 发表于OLS 2002：
-http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
diff --git a/Documentation/zh_CN/HOWTO b/Documentation/zh_CN/HOWTO
deleted file mode 100644
index 11be075ba5fa..000000000000
--- a/Documentation/zh_CN/HOWTO
+++ /dev/null
@@ -1,536 +0,0 @@
-Chinese translated version of Documentation/process/howto.rst
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Maintainer: Greg Kroah-Hartman 
-Chinese maintainer: Li Yang 
----------------------------------------------------------------------
-Documentation/process/howto.rst 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-
-英文版维护者： Greg Kroah-Hartman 
-中文版维护者： 李阳  Li Yang 
-中文版翻译者： 李阳  Li Yang 
-中文版校译者： 钟宇  TripleX Chung 
-               陈琦  Maggie Chen 
-               王聪  Wang Cong 
-
-以下为正文
----------------------------------------------------------------------
-
-如何参与Linux内核开发
----------------------
-
-这是一篇将如何参与Linux内核开发的相关问题一网打尽的终极秘笈。它将指导你
-成为一名Linux内核开发者，并且学会如何同Linux内核开发社区合作。它尽可能不
-包括任何关于内核编程的技术细节，但会给你指引一条获得这些知识的正确途径。
-
-如果这篇文章中的任何内容不再适用，请给文末列出的文件维护者发送补丁。
-
-
-入门
-----
-
-你想了解如何成为一名Linux内核开发者？或者老板吩咐你“给这个设备写个Linux
-驱动程序”？这篇文章的目的就是教会你达成这些目标的全部诀窍，它将描述你需
-要经过的流程以及给出如何同内核社区合作的一些提示。它还将试图解释内核社区
-为何这样运作。
-
-Linux内核大部分是由C语言写成的，一些体系结构相关的代码用到了汇编语言。要
-参与内核开发，你必须精通C语言。除非你想为某个架构开发底层代码，否则你并
-不需要了解（任何体系结构的）汇编语言。下面列举的书籍虽然不能替代扎实的C
-语言教育和多年的开发经验，但如果需要的话，做为参考还是不错的：
- - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
-   《C程序设计语言（第2版·新版）》（徐宝文 李志 译）[机械工业出版社]
- - "Practical C Programming" by Steve Oualline [O'Reilly]
-   《实用C语言编程（第三版）》（郭大海 译）[中国电力出版社]
- - "C:  A Reference Manual" by Harbison and Steele [Prentice Hall]
-   《C语言参考手册（原书第5版）》（邱仲潘 等译）[机械工业出版社]
-
-Linux内核使用GNU C和GNU工具链开发。虽然它遵循ISO C89标准，但也用到了一些
-标准中没有定义的扩展。内核是自给自足的C环境，不依赖于标准C库的支持，所以
-并不支持C标准中的部分定义。比如long long类型的大数除法和浮点运算就不允许
-使用。有时候确实很难弄清楚内核对工具链的要求和它所使用的扩展，不幸的是目
-前还没有明确的参考资料可以解释它们。请查阅gcc信息页（使用“info gcc”命令
-显示）获得一些这方面信息。
-
-请记住你是在学习怎么和已经存在的开发社区打交道。它由一群形形色色的人组成，
-他们对代码、风格和过程有着很高的标准。这些标准是在长期实践中总结出来的，
-适应于地理上分散的大型开发团队。它们已经被很好得整理成档，建议你在开发
-之前尽可能多的学习这些标准，而不要期望别人来适应你或者你公司的行为方式。
-
-
-法律问题
---------
-
-Linux内核源代码都是在GPL（通用公共许可证）的保护下发布的。要了解这种许可
-的细节请查看源代码主目录下的COPYING文件。如果你对它还有更深入问题请联系
-律师，而不要在Linux内核邮件组上提问。因为邮件组里的人并不是律师，不要期
-望他们的话有法律效力。
-
-对于GPL的常见问题和解答，请访问以下链接：
-	http://www.gnu.org/licenses/gpl-faq.html
-
-
-文档
-----
-
-Linux内核代码中包含有大量的文档。这些文档对于学习如何与内核社区互动有着
-不可估量的价值。当一个新的功能被加入内核，最好把解释如何使用这个功能的文
-档也放进内核。当内核的改动导致面向用户空间的接口发生变化时，最好将相关信
-息或手册页(manpages)的补丁发到mtk.manpages@gmail.com，以向手册页(manpages)
-的维护者解释这些变化。
-
-以下是内核代码中需要阅读的文档：
-  README
-    文件简要介绍了Linux内核的背景，并且描述了如何配置和编译内核。内核的
-    新用户应该从这里开始。
-
-  Documentation/process/changes.rst
-    文件给出了用来编译和使用内核所需要的最小软件包列表。
-
-  Documentation/process/coding-style.rst
-    描述Linux内核的代码风格和理由。所有新代码需要遵守这篇文档中定义的规
-    范。大多数维护者只会接收符合规定的补丁，很多人也只会帮忙检查符合风格
-    的代码。
-
-  Documentation/process/submitting-patches.rst
-  Documentation/process/submitting-drivers.rst
-    这两份文档明确描述如何创建和发送补丁，其中包括（但不仅限于)：
-       - 邮件内容
-       - 邮件格式
-       - 选择收件人
-    遵守这些规定并不能保证提交成功（因为所有补丁需要通过严格的内容和风格
-    审查），但是忽视他们几乎就意味着失败。
-
-    其他关于如何正确地生成补丁的优秀文档包括：
-    "The Perfect Patch"
-        http://www.ozlabs.org/~akpm/stuff/tpp.txt
-    "Linux kernel patch submission format"
-        http://linux.yyz.us/patch-format.html
-
-  Documentation/process/stable-api-nonsense.rst
-    论证内核为什么特意不包括稳定的内核内部API，也就是说不包括像这样的特
-    性：
-       - 子系统中间层（为了兼容性？）
-       - 在不同操作系统间易于移植的驱动程序
-       - 减缓（甚至阻止）内核代码的快速变化
-    这篇文档对于理解Linux的开发哲学至关重要。对于将开发平台从其他操作系
-    统转移到Linux的人来说也很重要。
-
-  Documentation/admin-guide/security-bugs.rst
-    如果你认为自己发现了Linux内核的安全性问题，请根据这篇文档中的步骤来
-    提醒其他内核开发者并帮助解决这个问题。
-
-  Documentation/process/management-style.rst
-    描述内核维护者的工作方法及其共有特点。这对于刚刚接触内核开发（或者对
-    它感到好奇）的人来说很重要，因为它解释了很多对于内核维护者独特行为的
-    普遍误解与迷惑。
-
-  Documentation/process/stable-kernel-rules.rst
-    解释了稳定版内核发布的规则，以及如何将改动放入这些版本的步骤。
-
-  Documentation/process/kernel-docs.rst
-    有助于内核开发的外部文档列表。如果你在内核自带的文档中没有找到你想找
-    的内容，可以查看这些文档。
-
-  Documentation/process/applying-patches.rst
-    关于补丁是什么以及如何将它打在不同内核开发分支上的好介绍
-
-内核还拥有大量从代码自动生成的文档。它包含内核内部API的全面介绍以及如何
-妥善处理加锁的规则。生成的文档会放在 Documentation/DocBook/目录下。在内
-核源码的主目录中使用以下不同命令将会分别生成PDF、Postscript、HTML和手册
-页等不同格式的文档：
-    make pdfdocs
-    make psdocs
-    make htmldocs
-    make mandocs
-
-
-如何成为内核开发者
-------------------
-如果你对Linux内核开发一无所知，你应该访问“Linux内核新手”计划：
-	http://kernelnewbies.org
-它拥有一个可以问各种最基本的内核开发问题的邮件列表（在提问之前一定要记得
-查找已往的邮件，确认是否有人已经回答过相同的问题）。它还拥有一个可以获得
-实时反馈的IRC聊天频道，以及大量对于学习Linux内核开发相当有帮助的文档。
-
-网站简要介绍了源代码组织结构、子系统划分以及目前正在进行的项目（包括内核
-中的和单独维护的）。它还提供了一些基本的帮助信息，比如如何编译内核和打补
-丁。
-
-如果你想加入内核开发社区并协助完成一些任务，却找不到从哪里开始，可以访问
-“Linux内核房管员”计划：
-	http://kernelnewbies.org/KernelJanitors
-这是极佳的起点。它提供一个相对简单的任务列表，列出内核代码中需要被重新
-整理或者改正的地方。通过和负责这个计划的开发者们一同工作，你会学到将补丁
-集成进内核的基本原理。如果还没有决定下一步要做什么的话，你还可能会得到方
-向性的指点。
-
-如果你已经有一些现成的代码想要放到内核中，但是需要一些帮助来使它们拥有正
-确的格式。请访问“内核导师”计划。这个计划就是用来帮助你完成这个目标的。它
-是一个邮件列表，地址如下：
-	http://selenic.com/mailman/listinfo/kernel-mentors
-
-在真正动手修改内核代码之前，理解要修改的代码如何运作是必需的。要达到这个
-目的，没什么办法比直接读代码更有效了（大多数花招都会有相应的注释），而且
-一些特制的工具还可以提供帮助。例如，“Linux代码交叉引用”项目就是一个值得
-特别推荐的帮助工具，它将源代码显示在有编目和索引的网页上。其中一个更新及
-时的内核源码库，可以通过以下地址访问：
-	http://sosdg.org/~coywolf/lxr/
-
-
-开发流程
---------
-
-目前Linux内核开发流程包括几个“主内核分支”和很多子系统相关的内核分支。这
-些分支包括：
-  - 2.6.x主内核源码树
-  - 2.6.x.y -stable内核源码树
-  - 2.6.x -git内核补丁集
-  - 2.6.x -mm内核补丁集
-  - 子系统相关的内核源码树和补丁集
-
-
-2.6.x内核主源码树
------------------
-2.6.x内核是由Linus Torvalds（Linux的创造者）亲自维护的。你可以在
-kernel.org网站的pub/linux/kernel/v2.6/目录下找到它。它的开发遵循以下步
-骤：
-  - 每当一个新版本的内核被发布，为期两周的集成窗口将被打开。在这段时间里
-    维护者可以向Linus提交大段的修改，通常这些修改已经被放到-mm内核中几个
-    星期了。提交大量修改的首选方式是使用git工具（内核的代码版本管理工具
-    ，更多的信息可以在http://git-scm.com/获取），不过使用普通补丁也是可以
-    的。
-  - 两个星期以后-rc1版本内核发布。之后只有不包含可能影响整个内核稳定性的
-    新功能的补丁才可能被接受。请注意一个全新的驱动程序（或者文件系统）有
-    可能在-rc1后被接受是因为这样的修改完全独立，不会影响其他的代码，所以
-    没有造成内核退步的风险。在-rc1以后也可以用git向Linus提交补丁，不过所
-    有的补丁需要同时被发送到相应的公众邮件列表以征询意见。
-  - 当Linus认为当前的git源码树已经达到一个合理健全的状态足以发布供人测试
-    时，一个新的-rc版本就会被发布。计划是每周都发布新的-rc版本。
-  - 这个过程一直持续下去直到内核被认为达到足够稳定的状态，持续时间大概是
-    6个星期。
-
-关于内核发布，值得一提的是Andrew Morton在linux-kernel邮件列表中如是说：
-	“没有人知道新内核何时会被发布，因为发布是根据已知bug的情况来决定
-	的，而不是根据一个事先制定好的时间表。”
-
-
-2.6.x.y -stable（稳定版）内核源码树
------------------------------------
-由4个数字组成的内核版本号说明此内核是-stable版本。它们包含基于2.6.x版本
-内核的相对较小且至关重要的修补，这些修补针对安全性问题或者严重的内核退步。
-
-这种版本的内核适用于那些期望获得最新的稳定版内核并且不想参与测试开发版或
-者实验版的用户。
-
-如果没有2.6.x.y版本内核存在，那么最新的2.6.x版本内核就相当于是当前的稳定
-版内核。
-
-2.6.x.y版本由“稳定版”小组（邮件地址）维护，一般隔周发
-布新版本。
-
-内核源码中的Documentation/process/stable-kernel-rules.rst文件具体描述了可被稳定
-版内核接受的修改类型以及发布的流程。
-
-
-2.6.x -git补丁集
-----------------
-Linus的内核源码树的每日快照，这个源码树是由git工具管理的（由此得名）。这
-些补丁通常每天更新以反映Linus的源码树的最新状态。它们比-rc版本的内核源码
-树更具试验性质，因为这个补丁集是全自动生成的，没有任何人来确认其是否真正
-健全。
-
-
-2.6.x -mm补丁集
----------------
-这是由Andrew Morton维护的试验性内核补丁集。Andrew将所有子系统的内核源码
-和补丁拼凑到一起，并且加入了大量从linux-kernel邮件列表中采集的补丁。这个
-源码树是新功能和补丁的试炼场。当补丁在-mm补丁集里证明了其价值以后Andrew
-或者相应子系统的维护者会将补丁发给Linus以便集成进主内核源码树。
-
-在将所有新补丁发给Linus以集成到主内核源码树之前，我们非常鼓励先把这些补
-丁放在-mm版内核源码树中进行测试。
-
-这些内核版本不适合在需要稳定运行的系统上运行，因为运行它们比运行任何其他
-内核分支都更具有风险。
-
-如果你想为内核开发进程提供帮助，请尝试并使用这些内核版本，并在
-linux-kernel邮件列表中提供反馈，告诉大家你遇到了问题还是一切正常。
-
-通常-mm版补丁集不光包括这些额外的试验性补丁，还包括发布时-git版主源码树
-中的改动。
-
--mm版内核没有固定的发布周期，但是通常在每两个-rc版内核发布之间都会有若干
-个-mm版内核发布（一般是1至3个）。
-
-
-子系统相关内核源码树和补丁集
-----------------------------
-相当一部分内核子系统开发者会公开他们自己的开发源码树，以便其他人能了解内
-核的不同领域正在发生的事情。如上所述，这些源码树会被集成到-mm版本内核中。
-
-下面是目前可用的一些内核源码树的列表：
-  通过git管理的源码树：
-    - Kbuild开发源码树， Sam Ravnborg 
-	git.kernel.org:/pub/scm/linux/kernel/git/sam/kbuild.git
-
-    - ACPI开发源码树, Len Brown 
-	git.kernel.org:/pub/scm/linux/kernel/git/lenb/linux-acpi-2.6.git
-
-    - 块设备开发源码树, Jens Axboe 
-	git.kernel.org:/pub/scm/linux/kernel/git/axboe/linux-2.6-block.git
-
-    - DRM开发源码树, Dave Airlie 
-	git.kernel.org:/pub/scm/linux/kernel/git/airlied/drm-2.6.git
-
-    - ia64开发源码树, Tony Luck 
-	git.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git
-
-    - ieee1394开发源码树, Jody McIntyre 
-	git.kernel.org:/pub/scm/linux/kernel/git/scjody/ieee1394.git
-
-    - infiniband开发源码树, Roland Dreier 
-	git.kernel.org:/pub/scm/linux/kernel/git/roland/infiniband.git
-
-    - libata开发源码树, Jeff Garzik 
-	git.kernel.org:/pub/scm/linux/kernel/git/jgarzik/libata-dev.git
-
-    - 网络驱动程序开发源码树, Jeff Garzik 
-	git.kernel.org:/pub/scm/linux/kernel/git/jgarzik/netdev-2.6.git
-
-    - pcmcia开发源码树, Dominik Brodowski 
-	git.kernel.org:/pub/scm/linux/kernel/git/brodo/pcmcia-2.6.git
-
-    - SCSI开发源码树, James Bottomley 
-	git.kernel.org:/pub/scm/linux/kernel/git/jejb/scsi-misc-2.6.git
-
-  使用quilt管理的补丁集：
-    - USB, PCI, 驱动程序核心和I2C, Greg Kroah-Hartman 
-	kernel.org/pub/linux/kernel/people/gregkh/gregkh-2.6/
-    - x86-64, 部分i386, Andi Kleen 
-	ftp.firstfloor.org:/pub/ak/x86_64/quilt/
-
-  其他内核源码树可以在http://git.kernel.org的列表中和MAINTAINERS文件里
-  找到。
-
-报告bug
--------
-
-bugzilla.kernel.org是Linux内核开发者们用来跟踪内核Bug的网站。我们鼓励用
-户在这个工具中报告找到的所有bug。如何使用内核bugzilla的细节请访问：
-	http://test.kernel.org/bugzilla/faq.html
-
-内核源码主目录中的admin-guide/reporting-bugs.rst文件里有一个很好的模板。它指导用户如何报
-告可能的内核bug以及需要提供哪些信息来帮助内核开发者们找到问题的根源。
-
-
-利用bug报告
------------
-
-练习内核开发技能的最好办法就是修改其他人报告的bug。你不光可以帮助内核变
-得更加稳定，还可以学会如何解决实际问题从而提高自己的技能，并且让其他开发
-者感受到你的存在。修改bug是赢得其他开发者赞誉的最好办法，因为并不是很多
-人都喜欢浪费时间去修改别人报告的bug。
-
-要尝试修改已知的bug，请访问http://bugzilla.kernel.org网址。如果你想获得
-最新bug的通知，可以订阅bugme-new邮件列表（只有新的bug报告会被寄到这里）
-或者订阅bugme-janitor邮件列表（所有bugzilla的变动都会被寄到这里）。
-
-	https://lists.linux-foundation.org/mailman/listinfo/bugme-new
-	https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
-
-
-邮件列表
---------
-
-正如上面的文档所描述，大多数的骨干内核开发者都加入了Linux Kernel邮件列
-表。如何订阅和退订列表的细节可以在这里找到：
-	http://vger.kernel.org/vger-lists.html#linux-kernel
-网上很多地方都有这个邮件列表的存档(archive)。可以使用搜索引擎来找到这些
-存档。比如：
-	http://dir.gmane.org/gmane.linux.kernel
-在发信之前，我们强烈建议你先在存档中搜索你想要讨论的问题。很多已经被详细
-讨论过的问题只在邮件列表的存档中可以找到。
-
-大多数内核子系统也有自己独立的邮件列表来协调各自的开发工作。从
-MAINTAINERS文件中可以找到不同话题对应的邮件列表。
-
-很多邮件列表架设在kernel.org服务器上。这些列表的信息可以在这里找到：
-	http://vger.kernel.org/vger-lists.html
-
-在使用这些邮件列表时，请记住保持良好的行为习惯。下面的链接提供了与这些列
-表（或任何其它邮件列表）交流的一些简单规则，虽然内容有点滥竽充数。
-	http://www.albion.com/netiquette/
-
-当有很多人回复你的邮件时，邮件的抄送列表会变得很长。请不要将任何人从抄送
-列表中删除，除非你有足够的理由这么做。也不要只回复到邮件列表。请习惯于同
-一封邮件接收两次（一封来自发送者一封来自邮件列表），而不要试图通过添加一
-些奇特的邮件头来解决这个问题，人们不会喜欢的。
-
-记住保留你所回复内容的上下文和源头。在你回复邮件的顶部保留“某某某说到……”
-这几行。将你的评论加在被引用的段落之间而不要放在邮件的顶部。
-
-如果你在邮件中附带补丁，请确认它们是可以直接阅读的纯文本（如
-Documentation/process/submitting-patches.rst文档中所述）。内核开发者们不希望遇到附件
-或者被压缩了的补丁。只有这样才能保证他们可以直接评论你的每行代码。请确保
-你使用的邮件发送程序不会修改空格和制表符。一个防范性的测试方法是先将邮件
-发送给自己，然后自己尝试是否可以顺利地打上收到的补丁。如果测试不成功，请
-调整或者更换你的邮件发送程序直到它正确工作为止。
-
-总而言之，请尊重其他的邮件列表订阅者。
-
-
-同内核社区合作
-----------------
-
-内核社区的目标就是提供尽善尽美的内核。所以当你提交补丁期望被接受进内核的
-时候，它的技术价值以及其他方面都将被评审。那么你可能会得到什么呢？
-  - 批评
-  - 评论
-  - 要求修改
-  - 要求证明修改的必要性
-  - 沉默
-
-要记住，这些是把补丁放进内核的正常情况。你必须学会听取对补丁的批评和评论，
-从技术层面评估它们，然后要么重写你的补丁要么简明扼要地论证修改是不必要
-的。如果你发的邮件没有得到任何回应，请过几天后再试一次，因为有时信件会湮
-没在茫茫信海中。
-
-你不应该做的事情：
-  - 期望自己的补丁不受任何质疑就直接被接受
-  - 翻脸
-  - 忽略别人的评论
-  - 没有按照别人的要求做任何修改就重新提交
-
-在一个努力追寻最好技术方案的社区里，对于一个补丁有多少好处总会有不同的见
-解。你必须要抱着合作的态度，愿意改变自己的观点来适应内核的风格。或者至少
-愿意去证明你的想法是有价值的。记住，犯错误是允许的，只要你愿意朝着正确的
-方案去努力。
-
-如果你的第一个补丁换来的是一堆修改建议，这是很正常的。这并不代表你的补丁
-不会被接受，也不意味着有人和你作对。你只需要改正所有提出的问题然后重新发
-送你的补丁。
-
-内核社区和公司文化的差异
-------------------------
-
-内核社区的工作模式同大多数传统公司开发队伍的工作模式并不相同。下面这些例
-子，可以帮助你避免某些可能发生问题：
-  用这些话介绍你的修改提案会有好处：
-    - 它同时解决了多个问题
-    - 它删除了2000行代码
-    - 这是补丁，它已经解释了我想要说明的
-    - 我在5种不同的体系结构上测试过它……
-    - 这是一系列小补丁用来……
-    - 这个修改提高了普通机器的性能……
-
-  应该避免如下的说法：
-    - 我们在AIX/ptx/Solaris就是这么做的，所以这么做肯定是好的……
-    - 我做这行已经20年了，所以……
-    - 为了我们公司赚钱考虑必须这么做
-    - 这是我们的企业产品线所需要的
-    - 这里是描述我观点的1000页设计文档
-    - 这是一个5000行的补丁用来……
-    - 我重写了现在乱七八糟的代码，这就是……
-    - 我被规定了最后期限，所以这个补丁需要立刻被接受
-
-另外一个内核社区与大部分传统公司的软件开发队伍不同的地方是无法面对面地交
-流。使用电子邮件和IRC聊天工具做为主要沟通工具的一个好处是性别和种族歧视
-将会更少。Linux内核的工作环境更能接受妇女和少数族群，因为每个人在别人眼
-里只是一个邮件地址。国际化也帮助了公平的实现，因为你无法通过姓名来判断人
-的性别。男人有可能叫李丽，女人也有可能叫王刚。大多数在Linux内核上工作过
-并表达过看法的女性对在linux上工作的经历都给出了正面的评价。
-
-对于一些不习惯使用英语的人来说，语言可能是一个引起问题的障碍。在邮件列表
-中要正确地表达想法必需良好地掌握语言，所以建议你在发送邮件之前最好检查一
-下英文写得是否正确。
-
-
-拆分修改
---------
-
-Linux内核社区并不喜欢一下接收大段的代码。修改需要被恰当地介绍、讨论并且
-拆分成独立的小段。这几乎完全和公司中的习惯背道而驰。你的想法应该在开发最
-开始的阶段就让大家知道，这样你就可以及时获得对你正在进行的开发的反馈。这
-样也会让社区觉得你是在和他们协作，而不是仅仅把他们当作倾销新功能的对象。
-无论如何，你不要一次性地向邮件列表发送50封信，你的补丁序列应该永远用不到
-这么多。
-
-将补丁拆开的原因如下：
-
-1) 小的补丁更有可能被接受，因为它们不需要太多的时间和精力去验证其正确性。
-   一个5行的补丁，可能在维护者看了一眼以后就会被接受。而500行的补丁则
-   需要数个小时来审查其正确性（所需时间随补丁大小增加大约呈指数级增长）。
-
-   当出了问题的时候，小的补丁也会让调试变得非常容易。一个一个补丁地回溯
-   将会比仔细剖析一个被打上的大补丁（这个补丁破坏了其他东西）容易得多。
-
-2）不光发送小的补丁很重要，在提交之前重新编排、化简（或者仅仅重新排列）
-   补丁也是很重要的。
-
-这里有内核开发者Al Viro打的一个比方：
-	“想象一个老师正在给学生批改数学作业。老师并不希望看到学生为了得
-	到正确解法所进行的尝试和产生的错误。他希望看到的是最干净最优雅的
-	解答。好学生了解这点，绝不会把最终解决之前的中间方案提交上去。”
-
-	内核开发也是这样。维护者和评审者不希望看到一个人在解决问题时的思
-	考过程。他们只希望看到简单和优雅的解决方案。
-
-直接给出一流的解决方案，和社区一起协作讨论尚未完成的工作，这两者之间似乎
-很难找到一个平衡点。所以最好尽早开始收集有利于你进行改进的反馈；同时也要
-保证修改分成很多小块，这样在整个项目都准备好被包含进内核之前，其中的一部
-分可能会先被接收。
-
-必须了解这样做是不可接受的：试图将未完成的工作提交进内核，然后再找时间修
-复。
-
-
-证明修改的必要性
-----------------
-除了将补丁拆成小块，很重要的一点是让Linux社区了解他们为什么需要这样修改。
-你必须证明新功能是有人需要的并且是有用的。
-
-
-记录修改
---------
-
-当你发送补丁的时候，需要特别留意邮件正文的内容。因为这里的信息将会做为补
-丁的修改记录(ChangeLog)，会被一直保留以备大家查阅。它需要完全地描述补丁，
-包括：
-  - 为什么需要这个修改
-  - 补丁的总体设计
-  - 实现细节
-  - 测试结果
-
-想了解它具体应该看起来像什么，请查阅以下文档中的“ChangeLog”章节：
-  “The Perfect Patch”
-  	 http://www.ozlabs.org/~akpm/stuff/tpp.txt
-
-
-这些事情有时候做起来很难。要在任何方面都做到完美可能需要好几年时间。这是
-一个持续提高的过程，它需要大量的耐心和决心。只要不放弃，你一定可以做到。
-很多人已经做到了，而他们都曾经和现在的你站在同样的起点上。
-
-
----------------
-感谢Paolo Ciarrocchi允许“开发流程”部分基于他所写的文章
-(http://www.kerneltravel.net/newbie/2.6-development_process)，感谢Randy
-Dunlap和Gerrit Huizenga完善了应该说和不该说的列表。感谢Pat Mochel, Hanna
-Linder, Randy Dunlap, Kay Sievers, Vojtech Pavlik, Jan Kara, Josh Boyer,
-Kees Cook, Andrew Morton, Andi Kleen, Vadim Lobanov, Jesper Juhl, Adrian
-Bunk, Keri Harris, Frans Pop, David A. Wheeler, Junio Hamano, Michael
-Kerrisk和Alex Shepard的评审、建议和贡献。没有他们的帮助，这篇文档是不可
-能完成的。
-
-
-
-英文版维护者： Greg Kroah-Hartman 
diff --git a/Documentation/zh_CN/IRQ.txt b/Documentation/zh_CN/IRQ.txt
deleted file mode 100644
index 956026d5cf82..000000000000
--- a/Documentation/zh_CN/IRQ.txt
+++ /dev/null
@@ -1,39 +0,0 @@
-Chinese translated version of Documentation/IRQ.txt
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Maintainer: Eric W. Biederman 
-Chinese maintainer: Fu Wei 
----------------------------------------------------------------------
-Documentation/IRQ.txt 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-英文版维护者： Eric W. Biederman 
-中文版维护者： 傅炜 Fu Wei 
-中文版翻译者： 傅炜 Fu Wei 
-中文版校译者： 傅炜 Fu Wei 
-
-
-以下为正文
----------------------------------------------------------------------
-何为 IRQ?
-
-一个 IRQ 是来自某个设备的一个中断请求。目前，它们可以来自一个硬件引脚，
-或来自一个数据包。多个设备可能连接到同个硬件引脚，从而共享一个 IRQ。
-
-一个 IRQ 编号是用于告知硬件中断源的内核标识。通常情况下，这是一个
-全局 irq_desc 数组的索引，但是除了在 linux/interrupt.h 中的实现，
-具体的细节是体系结构特定的。
-
-一个 IRQ 编号是设备上某个可能的中断源的枚举。通常情况下，枚举的编号是
-该引脚在系统内中断控制器的所有输入引脚中的编号。对于 ISA 总线中的情况，
-枚举的是在两个 i8259 中断控制器中 16 个输入引脚。
-
-架构可以对 IRQ 编号指定额外的含义，在硬件涉及任何手工配置的情况下，
-是被提倡的。ISA 的 IRQ 是一个分配这类额外含义的典型例子。
diff --git a/Documentation/zh_CN/SecurityBugs b/Documentation/zh_CN/SecurityBugs
deleted file mode 100644
index 2d0fffd122ce..000000000000
--- a/Documentation/zh_CN/SecurityBugs
+++ /dev/null
@@ -1,50 +0,0 @@
-Chinese translated version of Documentation/admin-guide/security-bugs.rst
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Chinese maintainer: Harry Wei 
----------------------------------------------------------------------
-Documentation/admin-guide/security-bugs.rst 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-
-中文版维护者： 贾威威 Harry Wei 
-中文版翻译者： 贾威威 Harry Wei 
-中文版校译者： 贾威威 Harry Wei 
-
-
-以下为正文
----------------------------------------------------------------------
-Linux内核开发者认为安全非常重要。因此，我们想要知道当一个有关于
-安全的漏洞被发现的时候，并且它可能会被尽快的修复或者公开。请把这个安全
-漏洞报告给Linux内核安全团队。
-
-1) 联系
-
-linux内核安全团队可以通过email来联系。这是
-一组独立的安全工作人员，可以帮助改善漏洞报告并且公布和取消一个修复。安
-全团队有可能会从部分的维护者那里引进额外的帮助来了解并且修复安全漏洞。
-当遇到任何漏洞，所能提供的信息越多就越能诊断和修复。如果你不清楚什么
-是有帮助的信息，那就请重温一下admin-guide/reporting-bugs.rst文件中的概述过程。任
-何攻击性的代码都是非常有用的，未经报告者的同意不会被取消，除非它已经
-被公布于众。
-
-2) 公开
-
-Linux内核安全团队的宗旨就是和漏洞提交者一起处理漏洞的解决方案直
-到公开。我们喜欢尽快地完全公开漏洞。当一个漏洞或者修复还没有被完全地理
-解，解决方案没有通过测试或者供应商协调，可以合理地延迟公开。然而，我们
-期望这些延迟尽可能的短些，是可数的几天，而不是几个星期或者几个月。公开
-日期是通过安全团队和漏洞提供者以及供应商洽谈后的结果。公开时间表是从很
-短（特殊的，它已经被公众所知道）到几个星期。作为一个基本的默认政策，我
-们所期望通知公众的日期是7天的安排。
-
-3) 保密协议
-
-Linux内核安全团队不是一个正式的团体，因此不能加入任何的保密协议。
diff --git a/Documentation/zh_CN/SubmittingDrivers b/Documentation/zh_CN/SubmittingDrivers
deleted file mode 100644
index 929385e4b194..000000000000
--- a/Documentation/zh_CN/SubmittingDrivers
+++ /dev/null
@@ -1,164 +0,0 @@
-Chinese translated version of Documentation/process/submitting-drivers.rst
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Chinese maintainer: Li Yang 
----------------------------------------------------------------------
-Documentation/process/submitting-drivers.rst 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-
-中文版维护者： 李阳  Li Yang 
-中文版翻译者： 李阳  Li Yang 
-中文版校译者： 陈琦 Maggie Chen 
-               王聪 Wang Cong 
-               张巍 Zhang Wei 
-
-以下为正文
----------------------------------------------------------------------
-
-如何向 Linux 内核提交驱动程序
------------------------------
-
-这篇文档将会解释如何向不同的内核源码树提交设备驱动程序。请注意，如果你感
-兴趣的是显卡驱动程序，你也许应该访问 XFree86 项目(http://www.xfree86.org/)
-和／或 X.org 项目 (http://x.org)。
-
-另请参阅 Documentation/process/submitting-patches.rst 文档。
-
-
-分配设备号
-----------
-
-块设备和字符设备的主设备号与从设备号是由 Linux 命名编号分配权威 LANANA（
-现在是 Torben Mathiasen）负责分配。申请的网址是 http://www.lanana.org/。
-即使不准备提交到主流内核的设备驱动也需要在这里分配设备号。有关详细信息，
-请参阅 Documentation/admin-guide/devices.rst。
-
-如果你使用的不是已经分配的设备号，那么当你提交设备驱动的时候，它将会被强
-制分配一个新的设备号，即便这个设备号和你之前发给客户的截然不同。
-
-设备驱动的提交对象
-------------------
-
-Linux 2.0:
-	此内核源码树不接受新的驱动程序。
-
-Linux 2.2:
-	此内核源码树不接受新的驱动程序。
-
-Linux 2.4:
-	如果所属的代码领域在内核的 MAINTAINERS 文件中列有一个总维护者，
-	那么请将驱动程序提交给他。如果此维护者没有回应或者你找不到恰当的
-	维护者，那么请联系 Willy Tarreau 。
-
-Linux 2.6:
-	除了遵循和 2.4 版内核同样的规则外，你还需要在 linux-kernel 邮件
-	列表上跟踪最新的 API 变化。向 Linux 2.6 内核提交驱动的顶级联系人
-	是 Andrew Morton 。
-
-决定设备驱动能否被接受的条件
-----------------------------
-
-许可：		代码必须使用 GNU 通用公开许可证 (GPL) 提交给 Linux，但是
-		我们并不要求 GPL 是唯一的许可。你或许会希望同时使用多种
-		许可证发布，如果希望驱动程序可以被其他开源社区（比如BSD）
-		使用。请参考 include/linux/module.h 文件中所列出的可被
-		接受共存的许可。
-
-版权：		版权所有者必须同意使用 GPL 许可。最好提交者和版权所有者
-		是相同个人或实体。否则，必需列出授权使用 GPL 的版权所有
-		人或实体，以备验证之需。
-
-接口：		如果你的驱动程序使用现成的接口并且和其他同类的驱动程序行
-		为相似，而不是去发明无谓的新接口，那么它将会更容易被接受。
-		如果你需要一个 Linux 和 NT 的通用驱动接口，那么请在用
-		户空间实现它。
-
-代码：		请使用 Documentation/process/coding-style.rst 中所描述的 Linux 代码风
-		格。如果你的某些代码段（例如那些与 Windows 驱动程序包共
-		享的代码段）需要使用其他格式，而你却只希望维护一份代码，
-		那么请将它们很好地区分出来，并且注明原因。
-
-可移植性：	请注意，指针并不永远是 32 位的，不是所有的计算机都使用小
-		尾模式 (little endian) 存储数据，不是所有的人都拥有浮点
-		单元，不要随便在你的驱动程序里嵌入 x86 汇编指令。只能在
-		x86 上运行的驱动程序一般是不受欢迎的。虽然你可能只有 x86
-		硬件，很难测试驱动程序在其他平台上是否可用，但是确保代码
-		可以被轻松地移植却是很简单的。
-
-清晰度：	做到所有人都能修补这个驱动程序将会很有好处，因为这样你将
-		会直接收到修复的补丁而不是 bug 报告。如果你提交一个试图
-		隐藏硬件工作机理的驱动程序，那么它将会被扔进废纸篓。
-
-电源管理：	因为 Linux 正在被很多移动设备和桌面系统使用，所以你的驱
-		动程序也很有可能被使用在这些设备上。它应该支持最基本的电
-		源管理，即在需要的情况下实现系统级休眠和唤醒要用到的
-		.suspend 和 .resume 函数。你应该检查你的驱动程序是否能正
-		确地处理休眠与唤醒，如果实在无法确认，请至少把 .suspend
-		函数定义成返回 -ENOSYS（功能未实现）错误。你还应该尝试确
-		保你的驱动在什么都不干的情况下将耗电降到最低。要获得驱动
-		程序测试的指导，请参阅
-		Documentation/power/drivers-testing.txt。有关驱动程序电
-		源管理问题相对全面的概述，请参阅
-		Documentation/power/admin-guide/devices.rst。
-
-管理：		如果一个驱动程序的作者还在进行有效的维护，那么通常除了那
-		些明显正确且不需要任何检查的补丁以外，其他所有的补丁都会
-		被转发给作者。如果你希望成为驱动程序的联系人和更新者，最
-		好在代码注释中写明并且在 MAINTAINERS 文件中加入这个驱动
-		程序的条目。
-
-不影响设备驱动能否被接受的条件
-------------------------------
-
-供应商：	由硬件供应商来维护驱动程序通常是一件好事。不过，如果源码
-		树里已经有其他人提供了可稳定工作的驱动程序，那么请不要期
-		望“我是供应商”会成为内核改用你的驱动程序的理由。理想的情
-		况是：供应商与现有驱动程序的作者合作，构建一个统一完美的
-		驱动程序。
-
-作者：		驱动程序是由大的 Linux 公司研发还是由你个人编写，并不影
-		响其是否能被内核接受。没有人对内核源码树享有特权。只要你
-		充分了解内核社区，你就会发现这一点。
-
-
-资源列表
---------
-
-Linux 内核主源码树：
-	ftp.??.kernel.org:/pub/linux/kernel/...
-	?? == 你的国家代码，例如 "cn"、"us"、"uk"、"fr" 等等
-
-Linux 内核邮件列表：
-	linux-kernel@vger.kernel.org
-	[可通过向majordomo@vger.kernel.org发邮件来订阅]
-
-Linux 设备驱动程序，第三版（探讨 2.6.10 版内核）：
-	http://lwn.net/Kernel/LDD3/ （免费版）
-
-LWN.net:
-	每周内核开发活动摘要 - http://lwn.net/
-	2.6 版中 API 的变更：
-		http://lwn.net/Articles/2.6-kernel-api/
-	将旧版内核的驱动程序移植到 2.6 版：
-		http://lwn.net/Articles/driver-porting/
-
-内核新手(KernelNewbies):
-	为新的内核开发者提供文档和帮助
-	http://kernelnewbies.org/
-
-Linux USB项目：
-	http://www.linux-usb.org/
-
-写内核驱动的“不要”（Arjan van de Ven著）:
-	http://www.fenrus.org/how-to-not-write-a-device-driver-paper.pdf
-
-内核清洁工 (Kernel Janitor):
-	http://kernelnewbies.org/KernelJanitors
diff --git a/Documentation/zh_CN/SubmittingPatches b/Documentation/zh_CN/SubmittingPatches
deleted file mode 100644
index e9098da8f1a4..000000000000
--- a/Documentation/zh_CN/SubmittingPatches
+++ /dev/null
@@ -1,412 +0,0 @@
-Chinese translated version of Documentation/process/submitting-patches.rst
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Chinese maintainer: TripleX Chung 
----------------------------------------------------------------------
-Documentation/process/submitting-patches.rst 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-
-中文版维护者： 钟宇 TripleX Chung 
-中文版翻译者： 钟宇 TripleX Chung 
-中文版校译者： 李阳 Li Yang 
-               王聪 Wang Cong 
-
-以下为正文
----------------------------------------------------------------------
-
-   如何让你的改动进入内核
-     或者
-  获得亲爱的 Linus Torvalds 的关注和处理
-----------------------------------
-
-对于想要将改动提交到 Linux 内核的个人或者公司来说，如果不熟悉“规矩”，
-提交的流程会让人畏惧。本文档收集了一系列建议，这些建议可以大大的提高你
-的改动被接受的机会。
-阅读 Documentation/process/submit-checklist.rst 来获得在提交代码前需要检查的项目的列
-表。如果你在提交一个驱动程序，那么同时阅读一下
-Documentation/process/submitting-drivers.rst 。
-
-
---------------------------
-第一节 - 创建并发送你的改动
---------------------------
-
-1) "diff -up"
------------
-
-使用 "diff -up" 或者 "diff -uprN" 来创建补丁。
-
-所有内核的改动，都是以补丁的形式呈现的，补丁由 diff(1) 生成。创建补丁的
-时候，要确认它是以 "unified diff" 格式创建的，这种格式由 diff(1) 的 '-u'
-参数生成。而且，请使用 '-p' 参数，那样会显示每个改动所在的C函数，使得
-产生的补丁容易读得多。补丁应该基于内核源代码树的根目录，而不是里边的任
-何子目录。
-为一个单独的文件创建补丁，一般来说这样做就够了：
-
-        SRCTREE= linux-2.6
-        MYFILE=  drivers/net/mydriver.c
-
-        cd $SRCTREE
-        cp $MYFILE $MYFILE.orig
-        vi $MYFILE      # make your change
-        cd ..
-        diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
-
-为多个文件创建补丁，你可以解开一个没有修改过的内核源代码树，然后和你自
-己的代码树之间做 diff 。例如：
-
-        MYSRC= /devel/linux-2.6
-
-        tar xvfz linux-2.6.12.tar.gz
-        mv linux-2.6.12 linux-2.6.12-vanilla
-        diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \
-                linux-2.6.12-vanilla $MYSRC > /tmp/patch
-
-"dontdiff" 是内核在编译的时候产生的文件的列表，列表中的文件在 diff(1)
-产生的补丁里会被跳过。"dontdiff" 文件被包含在2.6.12和之后版本的内核源代
-码树中。对于更早的内核版本，你可以从
- 获取它。
-确定你的补丁里没有包含任何不属于这次补丁提交的额外文件。记得在用diff(1)
-生成补丁之后，审阅一次补丁，以确保准确。
-如果你的改动很散乱，你应该研究一下如何将补丁分割成独立的部分，将改动分
-割成一系列合乎逻辑的步骤。这样更容易让其他内核开发者审核，如果你想你的
-补丁被接受，这是很重要的。下面这些脚本能够帮助你做这件事情：
-Quilt:
-http://savannah.nongnu.org/projects/quilt
-
-2)描述你的改动。
-描述你的改动包含的技术细节。
-
-要多具体就写多具体。最糟糕的描述可能是像下面这些语句：“更新了某驱动程
-序”，“修正了某驱动程序的bug”，或者“这个补丁包含了某子系统的修改，请
-使用。”
-
-如果你的描述开始变长，这表示你也许需要拆分你的补丁了，请看第3小节，
-继续。
-
-3)拆分你的改动
-
-将改动拆分，逻辑类似的放到同一个补丁文件里。
-
-例如，如果你的改动里同时有bug修正和性能优化，那么把这些改动拆分到两个或
-者更多的补丁文件中。如果你的改动包含对API的修改，并且修改了驱动程序来适
-应这些新的API，那么把这些修改分成两个补丁。
-
-另一方面，如果你将一个单独的改动做成多个补丁文件，那么将它们合并成一个
-单独的补丁文件。这样一个逻辑上单独的改动只被包含在一个补丁文件里。
-
-如果有一个补丁依赖另外一个补丁来完成它的改动，那没问题。简单的在你的补
-丁描述里指出“这个补丁依赖某补丁”就好了。
-
-如果你不能将补丁浓缩成更少的文件，那么每次大约发送出15个，然后等待审查
-和整合。
-
-4)选择 e-mail 的收件人
-
-看一遍 MAINTAINERS 文件和源代码，看看你所的改动所在的内核子系统有没有指
-定的维护者。如果有，给他们发e-mail。
-
-如果没有找到维护者，或者维护者没有反馈，将你的补丁发送到内核开发者主邮
-件列表 linux-kernel@vger.kernel.org。大部分的内核开发者都跟踪这个邮件列
-表，可以评价你的改动。
-
-每次不要发送超过15个补丁到 vger 邮件列表！！！
-
-Linus Torvalds 是决定改动能否进入 Linux 内核的最终裁决者。他的 e-mail
-地址是  。他收到的 e-mail 很多，所以一般
-的说，最好别给他发 e-mail。
-
-那些修正bug，“显而易见”的修改或者是类似的只需要很少讨论的补丁可以直接
-发送或者CC给Linus。那些需要讨论或者没有很清楚的好处的补丁，一般先发送到
-linux-kernel邮件列表。只有当补丁被讨论得差不多了，才提交给Linus。
-
-5)选择CC( e-mail 抄送)列表
-
-除非你有理由不这样做，否则CC linux-kernel@vger.kernel.org。
-
-除了 Linus 之外，其他内核开发者也需要注意到你的改动，这样他们才能评论你
-的改动并提供代码审查和建议。linux-kernel 是 Linux 内核开发者主邮件列表
-。其它的邮件列表为特定的子系统提供服务，比如 USB，framebuffer 设备，虚
-拟文件系统，SCSI 子系统，等等。查看 MAINTAINERS 文件来获得和你的改动有
-关的邮件列表。
-
-Majordomo lists of VGER.KERNEL.ORG at:
-        
-
-如果改动影响了用户空间和内核之间的接口，请给 MAN-PAGES 的维护者（列在
-MAINTAINERS 文件里的）发送一个手册页（man-pages）补丁，或者至少通知一下改
-变，让一些信息有途径进入手册页。
-
-即使在第四步的时候，维护者没有作出回应，也要确认在修改他们的代码的时候
-，一直将维护者拷贝到CC列表中。
-
-对于小的补丁，你也许会CC到 Adrian Bunk 管理的搜集琐碎补丁的邮件列表
-(Trivial Patch Monkey)trivial@kernel.org，那里专门收集琐碎的补丁。下面这样
-的补丁会被看作“琐碎的”补丁：
-  文档的拼写修正。
-  修正会影响到 grep(1) 的拼写。
-  警告信息修正(频繁的打印无用的警告是不好的。)
-  编译错误修正（代码逻辑的确是对的，只是编译有问题。）
-  运行时修正（只要真的修正了错误。）
-  移除使用了被废弃的函数/宏的代码(例如 check_region。)
-  联系方式和文档修正。
-  用可移植的代码替换不可移植的代码（即使在体系结构相关的代码中，既然有
-  人拷贝，只要它是琐碎的）
-  任何文件的作者/维护者对该文件的改动（例如 patch monkey 在重传模式下）
-
-EMAIL: trivial@kernel.org
-
-(译注，关于“琐碎补丁”的一些说明：因为原文的这一部分写得比较简单，所以不得不
-违例写一下译注。"trivial"这个英文单词的本意是“琐碎的，不重要的。”但是在这里
-有稍微有一些变化，例如对一些明显的NULL指针的修正，属于运行时修正，会被归类
-到琐碎补丁里。虽然NULL指针的修正很重要，但是这样的修正往往很小而且很容易得到
-检验，所以也被归入琐碎补丁。琐碎补丁更精确的归类应该是
-“simple, localized & easy to verify”，也就是说简单的，局部的和易于检验的。
-trivial@kernel.org邮件列表的目的是针对这样的补丁，为提交者提供一个中心，来
-降低提交的门槛。)
-
-6)没有 MIME 编码，没有链接，没有压缩，没有附件，只有纯文本。
-
-Linus 和其他的内核开发者需要阅读和评论你提交的改动。对于内核开发者来说
-，可以“引用”你的改动很重要，使用一般的 e-mail 工具，他们就可以在你的
-代码的任何位置添加评论。
-
-因为这个原因，所有的提交的补丁都是 e-mail 中“内嵌”的。
-警告：如果你使用剪切-粘贴你的补丁，小心你的编辑器的自动换行功能破坏你的
-补丁。
-
-不要将补丁作为 MIME 编码的附件，不管是否压缩。很多流行的 e-mail 软件不
-是任何时候都将 MIME 编码的附件当作纯文本发送的，这会使得别人无法在你的
-代码中加评论。另外，MIME 编码的附件会让 Linus 多花一点时间来处理，这就
-降低了你的改动被接受的可能性。
-
-警告：一些邮件软件，比如 Mozilla 会将你的信息以如下格式发送：
----- 邮件头 ----
-Content-Type: text/plain; charset=us-ascii; format=flowed
----- 邮件头 ----
-问题在于 “format=flowed” 会让接收端的某些邮件软件将邮件中的制表符替换
-成空格以及做一些类似的替换。这样，你发送的时候看起来没问题的补丁就被破
-坏了。
-
-要修正这个问题，只需要将你的 mozilla 的 defaults/pref/mailnews.js 文件
-里的
-pref("mailnews.send_plaintext_flowed", false); // RFC 2646=======
-修改成
-pref("mailnews.display.disable_format_flowed_support", true);
-就可以了。
-
-7) e-mail 的大小
-
-给 Linus 发送补丁的时候，永远按照第6小节说的做。
-
-大的改动对邮件列表不合适，对某些维护者也不合适。如果你的补丁，在不压缩
-的情况下，超过了40kB，那么你最好将补丁放在一个能通过 internet 访问的服
-务器上，然后用指向你的补丁的 URL 替代。
-
-8) 指出你的内核版本
-
-在标题和在补丁的描述中，指出补丁对应的内核的版本，是很重要的。
-
-如果补丁不能干净的在最新版本的内核上打上，Linus 是不会接受它的。
-
-9) 不要气馁，继续提交。
-
-当你提交了改动以后，耐心地等待。如果 Linus 喜欢你的改动并且同意它，那么
-它将在下一个内核发布版本中出现。
-
-然而，如果你的改动没有出现在下一个版本的内核中，可能有若干原因。减少那
-些原因，修正错误，重新提交更新后的改动，是你自己的工作。
-
-Linus不给出任何评论就“丢弃”你的补丁是常见的事情。在系统中这样的事情很
-平常。如果他没有接受你的补丁，也许是由于以下原因：
-* 你的补丁不能在最新版本的内核上干净的打上。
-* 你的补丁在 linux-kernel 邮件列表中没有得到充分的讨论。
-* 风格问题（参照第2小节）
-* 邮件格式问题（重读本节）
-* 你的改动有技术问题。
-* 他收到了成吨的 e-mail，而你的在混乱中丢失了。
-* 你让人为难。
-
-有疑问的时候，在 linux-kernel 邮件列表上请求评论。
-
-10) 在标题上加上 PATCH 的字样
-
-Linus 和 linux-kernel 邮件列表的 e-mail 流量都很高，一个通常的约定是标
-题行以 [PATCH] 开头。这样可以让 Linus 和其他内核开发人员可以从 e-mail
-的讨论中很轻易的将补丁分辨出来。
-
-11）为你的工作签名
-
-为了加强对谁做了何事的追踪，尤其是对那些透过好几层的维护者的补丁，我们
-建议在发送出去的补丁上加一个 “sign-off” 的过程。
-
-"sign-off" 是在补丁的注释的最后的简单的一行文字，认证你编写了它或者其他
-人有权力将它作为开放源代码的补丁传递。规则很简单：如果你能认证如下信息
-：
-      开发者来源证书 1.1
-      对于本项目的贡献，我认证如下信息：
-      （a）这些贡献是完全或者部分的由我创建，我有权利以文件中指出
-       的开放源代码许可证提交它；或者
-      （b）这些贡献基于以前的工作，据我所知，这些以前的工作受恰当的开放
-       源代码许可证保护，而且，根据许可证，我有权提交修改后的贡献，
-       无论是完全还是部分由我创造，这些贡献都使用同一个开放源代码许可证
-       （除非我被允许用其它的许可证），正如文件中指出的；或者
-      （c）这些贡献由认证（a），（b）或者（c）的人直接提供给我，而
-       且我没有修改它。
-      （d）我理解并同意这个项目和贡献是公开的，贡献的记录（包括我
-       一起提交的个人记录，包括 sign-off ）被永久维护并且可以和这个项目
-       或者开放源代码的许可证同步地再发行。
-       那么加入这样一行：
-       Signed-off-by: Random J Developer 
-
-使用你的真名（抱歉，不能使用假名或者匿名。）
-
-有人在最后加上标签。现在这些东西会被忽略，但是你可以这样做，来标记公司
-内部的过程，或者只是指出关于 sign-off 的一些特殊细节。
-
-12）标准补丁格式
-
-标准的补丁，标题行是：
-    Subject: [PATCH 001/123] 子系统:一句话概述
-
-标准补丁的信体存在如下部分：
-
-  - 一个 "from" 行指出补丁作者。
-
-  - 一个空行
-
-  - 说明的主体，这些说明文字会被拷贝到描述该补丁的永久改动记录里。
-
-  - 一个由"---"构成的标记行
-
-  - 不合适放到改动记录里的额外的注解。
-
-  - 补丁本身（diff 输出）
-
-标题行的格式，使得对标题行按字母序排序非常的容易 - 很多 e-mail 客户端都
-可以支持 - 因为序列号是用零填充的，所以按数字排序和按字母排序是一样的。
-
-e-mail 标题中的“子系统”标识哪个内核子系统将被打补丁。
-
-e-mail 标题中的“一句话概述”扼要的描述 e-mail 中的补丁。“一句话概述”
-不应该是一个文件名。对于一个补丁系列（“补丁系列”指一系列的多个相关补
-丁），不要对每个补丁都使用同样的“一句话概述”。
-
-记住 e-mail 的“一句话概述”会成为该补丁的全局唯一标识。它会蔓延到 git
-的改动记录里。然后“一句话概述”会被用在开发者的讨论里，用来指代这个补
-丁。用户将希望通过 google 来搜索"一句话概述"来找到那些讨论这个补丁的文
-章。
-
-一些标题的例子：
-
-    Subject: [patch 2/5] ext2: improve scalability of bitmap searching
-    Subject: [PATCHv2 001/207] x86: fix eflags tracking
-
-"from" 行是信体里的最上面一行，具有如下格式：
-        From: Original Author 
-
-"from" 行指明在永久改动日志里，谁会被确认为作者。如果没有 "from" 行，那
-么邮件头里的 "From: " 行会被用来决定改动日志中的作者。
-
-说明的主题将会被提交到永久的源代码改动日志里，因此对那些早已经不记得和
-这个补丁相关的讨论细节的有能力的读者来说，是有意义的。
-
-"---" 标记行对于补丁处理工具要找到哪里是改动日志信息的结束，是不可缺少
-的。
-
-对于 "---" 标记之后的额外注解，一个好的用途就是用来写 diffstat，用来显
-示修改了什么文件和每个文件都增加和删除了多少行。diffstat 对于比较大的补
-丁特别有用。其余那些只是和时刻或者开发者相关的注解，不合适放到永久的改
-动日志里的，也应该放这里。
-使用 diffstat的选项 "-p 1 -w 70" 这样文件名就会从内核源代码树的目录开始
-，不会占用太宽的空间（很容易适合80列的宽度，也许会有一些缩进。）
-
-在后面的参考资料中能看到适当的补丁格式的更多细节。
-
--------------------------------
-第二节 提示，建议和诀窍
--------------------------------
-
-本节包含很多和提交到内核的代码有关的通常的"规则"。事情永远有例外...但是
-你必须真的有好的理由这样做。你可以把本节叫做Linus的计算机科学入门课。
-
-1) 读 Document/process/coding-style.rst
-
-Nuff 说过，如果你的代码和这个偏离太多，那么它有可能会被拒绝，没有更多的
-审查，没有更多的评价。
-
-2) #ifdef 是丑陋的
-混杂了 ifdef 的代码难以阅读和维护。别这样做。作为替代，将你的 ifdef 放
-在头文件里，有条件地定义 "static inline" 函数，或者宏，在代码里用这些东
-西。让编译器把那些"空操作"优化掉。
-
-一个简单的例子，不好的代码：
-
-    dev = alloc_etherdev (sizeof(struct funky_private));
-    if (!dev)
-        return -ENODEV;
-    #ifdef CONFIG_NET_FUNKINESS
-    init_funky_net(dev);
-    #endif
-
-清理后的例子:
-
-(头文件里)
-    #ifndef CONFIG_NET_FUNKINESS
-    static inline void init_funky_net (struct net_device *d) {}
-    #endif
-
-(代码文件里)
-    dev = alloc_etherdev (sizeof(struct funky_private));
-    if (!dev)
-        return -ENODEV;
-    init_funky_net(dev);
-
-3) 'static inline' 比宏好
-
-Static inline 函数相比宏来说，是好得多的选择。Static inline 函数提供了
-类型安全，没有长度限制，没有格式限制，在 gcc 下开销和宏一样小。
-
-宏只在 static inline 函数不是最优的时候[在 fast paths 里有很少的独立的
-案例]，或者不可能用 static inline 函数的时候[例如字符串分配]。
-应该用 'static inline' 而不是 'static __inline__', 'extern inline' 和
-'extern __inline__' 。
-
-4) 不要过度设计
-
-不要试图预计模糊的未来事情，这些事情也许有用也许没有用："让事情尽可能的
-简单，而不是更简单"。
-
-----------------
-第三节 参考文献
-----------------
-
-Andrew Morton, "The perfect patch" (tpp).
-  
-
-Jeff Garzik, "Linux kernel patch submission format".
-  
-
-Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
-  
-  
-  
-  
-
-NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
-  
-
-Kernel Documentation/process/coding-style.rst:
-  
-
-Linus Torvalds's mail on the canonical patch format:
-  
---
diff --git a/Documentation/zh_CN/arm/Booting b/Documentation/zh_CN/arm/Booting
deleted file mode 100644
index 1fe866f8218f..000000000000
--- a/Documentation/zh_CN/arm/Booting
+++ /dev/null
@@ -1,175 +0,0 @@
-Chinese translated version of Documentation/arm/Booting
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Maintainer: Russell King 
-Chinese maintainer: Fu Wei 
----------------------------------------------------------------------
-Documentation/arm/Booting 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-
-英文版维护者： Russell King 
-中文版维护者： 傅炜  Fu Wei 
-中文版翻译者： 傅炜  Fu Wei 
-中文版校译者： 傅炜  Fu Wei 
-
-以下为正文
----------------------------------------------------------------------
-
-			启动 ARM Linux
-			==============
-
-作者：Russell King
-日期：2002年5月18日
-
-以下文档适用于 2.4.18-rmk6 及以上版本。
-
-为了启动 ARM Linux，你需要一个引导装载程序（boot loader），
-它是一个在主内核启动前运行的一个小程序。引导装载程序需要初始化各种
-设备，并最终调用 Linux 内核，将信息传递给内核。
-
-从本质上讲，引导装载程序应提供（至少）以下功能：
-
-1、设置和初始化 RAM。
-2、初始化一个串口。
-3、检测机器的类型（machine type）。
-4、设置内核标签列表（tagged list）。
-5、调用内核映像。
-
-
-1、设置和初始化 RAM
--------------------
-
-现有的引导加载程序:		强制
-新开发的引导加载程序:		强制
-
-引导装载程序应该找到并初始化系统中所有内核用于保持系统变量数据的 RAM。
-这个操作的执行是设备依赖的。（它可能使用内部算法来自动定位和计算所有
-RAM，或可能使用对这个设备已知的 RAM 信息，还可能使用任何引导装载程序
-设计者想到的匹配方法。）
-
-
-2、初始化一个串口
------------------------------
-
-现有的引导加载程序:		可选、建议
-新开发的引导加载程序:		可选、建议
-
-引导加载程序应该初始化并使能一个目标板上的串口。这允许内核串口驱动
-自动检测哪个串口用于内核控制台。(一般用于调试或与目标板通信。)
-
-作为替代方案，引导加载程序也可以通过标签列表传递相关的'console='
-选项给内核以指定某个串口，而串口数据格式的选项在以下文档中描述：
-
-       Documentation/admin-guide/kernel-parameters.rst。
-
-
-3、检测机器类型
---------------------------
-
-现有的引导加载程序:		可选
-新开发的引导加载程序:		强制
-
-引导加载程序应该通过某些方式检测自身所处的机器类型。这是一个硬件
-代码或通过查看所连接的硬件用某些算法得到，这些超出了本文档的范围。
-引导加载程序最终必须能提供一个 MACH_TYPE_xxx 值给内核。
-(详见 linux/arch/arm/tools/mach-types )。
-
-4、设置启动数据
-------------------
-
-现有的引导加载程序:		可选、强烈建议
-新开发的引导加载程序:		强制
-
-引导加载程序必须提供标签列表或者 dtb 映像以传递配置数据给内核。启动
-数据的物理地址通过寄存器 r2 传递给内核。
-
-4a、设置内核标签列表
---------------------------------
-
-bootloader 必须创建和初始化内核标签列表。一个有效的标签列表以
-ATAG_CORE 标签开始，并以 ATAG_NONE 标签结束。ATAG_CORE 标签可以是
-空的，也可以是非空。一个空 ATAG_CORE 标签其 size 域设置为
-‘2’(0x00000002)。ATAG_NONE 标签的 size 域必须设置为零。
-
-在列表中可以保存任意数量的标签。对于一个重复的标签是追加到之前标签
-所携带的信息之后，还是会覆盖原来的信息，是未定义的。某些标签的行为
-是前者，其他是后者。
-
-bootloader 必须传递一个系统内存的位置和最小值，以及根文件系统位置。
-因此，最小的标签列表如下所示：
-
-		+-----------+
-基地址 ->	| ATAG_CORE |  |
-		+-----------+  |
-		| ATAG_MEM  |  | 地址增长方向
-		+-----------+  |
-		| ATAG_NONE |  |
-		+-----------+  v
-
-标签列表应该保存在系统的 RAM 中。
-
-标签列表必须置于内核自解压和 initrd'bootp' 程序都不会覆盖的内存区。
-建议放在 RAM 的头 16KiB 中。
-
-4b、设置设备树
--------------------------
-
-bootloader 必须以 64bit 地址对齐的形式加载一个设备树映像(dtb)到系统
-RAM 中，并用启动数据初始化它。dtb 格式在文档
-Documentation/devicetree/booting-without-of.txt 中。内核将会在
-dtb 物理地址处查找 dtb 魔数值（0xd00dfeed），以确定 dtb 是否已经代替
-标签列表被传递进来。
-
-bootloader 必须传递一个系统内存的位置和最小值，以及根文件系统位置。
-dtb 必须置于内核自解压不会覆盖的内存区。建议将其放置于 RAM 的头 16KiB
-中。但是不可将其放置于“0”物理地址处，因为内核认为：r2 中为 0，意味着
-没有标签列表和 dtb 传递过来。
-
-5、调用内核映像
----------------------------
-
-现有的引导加载程序:		强制
-新开发的引导加载程序:		强制
-
-调用内核映像 zImage 有两个选择。如果 zImge 保存在 flash 中，且是为了
-在 flash 中直接运行而被正确链接的。这样引导加载程序就可以在 flash 中
-直接调用 zImage。
-
-zImage 也可以被放在系统 RAM（任意位置）中被调用。注意：内核使用映像
-基地址的前 16KB RAM 空间来保存页表。建议将映像置于 RAM 的 32KB 处。
-
-对于以上任意一种情况，都必须符合以下启动状态：
-
-- 停止所有 DMA 设备，这样内存数据就不会因为虚假网络包或磁盘数据而被破坏。
-  这可能可以节省你许多的调试时间。
-
-- CPU 寄存器配置
-  r0 = 0，
-  r1 = （在上面 3 中获取的）机器类型码。
-  r2 = 标签列表在系统 RAM 中的物理地址，或
-       设备树块(dtb)在系统 RAM 中的物理地址
-
-- CPU 模式
-  所有形式的中断必须被禁止 (IRQs 和 FIQs)
-  CPU 必须处于 SVC 模式。(对于 Angel 调试有特例存在)
-
-- 缓存，MMUs
-  MMU 必须关闭。
-  指令缓存开启或关闭都可以。
-  数据缓存必须关闭。
-
-- 引导加载程序应该通过直接跳转到内核映像的第一条指令来调用内核映像。
-
-  对于支持 ARM 指令集的 CPU，跳入内核入口时必须处在 ARM 状态，即使
-  对于 Thumb-2 内核也是如此。
-
-  对于仅支持 Thumb 指令集的 CPU，比如 Cortex-M 系列的 CPU，跳入
-  内核入口时必须处于 Thumb 状态。
diff --git a/Documentation/zh_CN/arm/kernel_user_helpers.txt b/Documentation/zh_CN/arm/kernel_user_helpers.txt
deleted file mode 100644
index cd7fc8f34cf9..000000000000
--- a/Documentation/zh_CN/arm/kernel_user_helpers.txt
+++ /dev/null
@@ -1,284 +0,0 @@
-Chinese translated version of Documentation/arm/kernel_user_helpers.txt
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Maintainer: Nicolas Pitre 
-		Dave Martin 
-Chinese maintainer: Fu Wei 
----------------------------------------------------------------------
-Documentation/arm/kernel_user_helpers.txt 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-英文版维护者： Nicolas Pitre 
-		Dave Martin 
-中文版维护者： 傅炜 Fu Wei 
-中文版翻译者： 傅炜 Fu Wei 
-中文版校译者： 宋冬生 Dongsheng Song 
-		傅炜 Fu Wei 
-
-
-以下为正文
----------------------------------------------------------------------
-内核提供的用户空间辅助代码
-=========================
-
-在内核内存空间的固定地址处，有一个由内核提供并可从用户空间访问的代码
-段。它用于向用户空间提供因在许多 ARM CPU 中未实现的特性和/或指令而需
-内核提供帮助的某些操作。这些代码直接在用户模式下执行的想法是为了获得
-最佳效率，但那些与内核计数器联系过于紧密的部分，则被留给了用户库实现。
-事实上，此代码甚至可能因不同的 CPU 而异，这取决于其可用的指令集或它
-是否为 SMP 系统。换句话说，内核保留在不作出警告的情况下根据需要更改
-这些代码的权利。只有本文档描述的入口及其结果是保证稳定的。
-
-这与完全成熟的 VDSO 实现不同（但两者并不冲突），尽管如此，VDSO 可阻止
-某些通过常量高效跳转到那些代码段的汇编技巧。且由于那些代码段在返回用户
-代码前仅使用少量的代码周期，则一个 VDSO 间接远程调用将会在这些简单的
-操作上增加一个可测量的开销。
-
-在对那些拥有原生支持的新型处理器进行代码优化时，仅在已为其他操作使用
-了类似的新增指令，而导致二进制结果已与早期 ARM 处理器不兼容的情况下，
-用户空间才应绕过这些辅助代码，并在内联函数中实现这些操作（无论是通过
-编译器在代码中直接放置，还是作为库函数调用实现的一部分）。也就是说，
-如果你编译的代码不会为了其他目的使用新指令，则不要仅为了避免使用这些
-内核辅助代码，导致二进制程序无法在早期处理器上运行。
-
-新的辅助代码可能随着时间的推移而增加，所以新内核中的某些辅助代码在旧
-内核中可能不存在。因此，程序必须在对任何辅助代码调用假设是安全之前，
-检测 __kuser_helper_version 的值（见下文）。理想情况下，这种检测应该
-只在进程启动时执行一次；如果内核版本不支持所需辅助代码，则该进程可尽早
-中止执行。
-
-kuser_helper_version
---------------------
-
-位置:	0xffff0ffc
-
-参考声明:
-
-  extern int32_t __kuser_helper_version;
-
-定义:
-
-  这个区域包含了当前运行内核实现的辅助代码版本号。用户空间可以通过读
-  取此版本号以确定特定的辅助代码是否存在。
-
-使用范例:
-
-#define __kuser_helper_version (*(int32_t *)0xffff0ffc)
-
-void check_kuser_version(void)
-{
-	if (__kuser_helper_version < 2) {
-		fprintf(stderr, "can't do atomic operations, kernel too old\n");
-		abort();
-	}
-}
-
-注意:
-
-  用户空间可以假设这个域的值不会在任何单个进程的生存期内改变。也就
-  是说，这个域可以仅在库的初始化阶段或进程启动阶段读取一次。
-
-kuser_get_tls
--------------
-
-位置:	0xffff0fe0
-
-参考原型:
-
-  void * __kuser_get_tls(void);
-
-输入:
-
-  lr = 返回地址
-
-输出:
-
-  r0 = TLS 值
-
-被篡改的寄存器:
-
-  无
-
-定义:
-
-  获取之前通过 __ARM_NR_set_tls 系统调用设置的 TLS 值。
-
-使用范例:
-
-typedef void * (__kuser_get_tls_t)(void);
-#define __kuser_get_tls (*(__kuser_get_tls_t *)0xffff0fe0)
-
-void foo()
-{
-	void *tls = __kuser_get_tls();
-	printf("TLS = %p\n", tls);
-}
-
-注意:
-
-  - 仅在 __kuser_helper_version >= 1 时，此辅助代码存在
-    （从内核版本 2.6.12 开始）。
-
-kuser_cmpxchg
--------------
-
-位置:	0xffff0fc0
-
-参考原型:
-
-  int __kuser_cmpxchg(int32_t oldval, int32_t newval, volatile int32_t *ptr);
-
-输入:
-
-  r0 = oldval
-  r1 = newval
-  r2 = ptr
-  lr = 返回地址
-
-输出:
-
-  r0 = 成功代码 (零或非零)
-  C flag = 如果 r0 == 0 则置 1，如果 r0 != 0 则清零。
-
-被篡改的寄存器:
-
-  r3, ip, flags
-
-定义:
-
-  仅在 *ptr 为 oldval 时原子保存 newval 于 *ptr 中。
-  如果 *ptr 被改变，则返回值为零，否则为非零值。
-  如果 *ptr 被改变，则 C flag 也会被置 1，以实现调用代码中的汇编
-  优化。
-
-使用范例:
-
-typedef int (__kuser_cmpxchg_t)(int oldval, int newval, volatile int *ptr);
-#define __kuser_cmpxchg (*(__kuser_cmpxchg_t *)0xffff0fc0)
-
-int atomic_add(volatile int *ptr, int val)
-{
-	int old, new;
-
-	do {
-		old = *ptr;
-		new = old + val;
-	} while(__kuser_cmpxchg(old, new, ptr));
-
-	return new;
-}
-
-注意:
-
-  - 这个例程已根据需要包含了内存屏障。
-
-  - 仅在 __kuser_helper_version >= 2 时，此辅助代码存在
-    （从内核版本 2.6.12 开始）。
-
-kuser_memory_barrier
---------------------
-
-位置:	0xffff0fa0
-
-参考原型:
-
-  void __kuser_memory_barrier(void);
-
-输入:
-
-  lr = 返回地址
-
-输出:
-
-  无
-
-被篡改的寄存器:
-
-  无
-
-定义:
-
-  应用于任何需要内存屏障以防止手动数据修改带来的一致性问题，以及
-  __kuser_cmpxchg 中。
-
-使用范例:
-
-typedef void (__kuser_dmb_t)(void);
-#define __kuser_dmb (*(__kuser_dmb_t *)0xffff0fa0)
-
-注意:
-
-  - 仅在 __kuser_helper_version >= 3 时，此辅助代码存在
-    （从内核版本 2.6.15 开始）。
-
-kuser_cmpxchg64
----------------
-
-位置:	0xffff0f60
-
-参考原型:
-
-  int __kuser_cmpxchg64(const int64_t *oldval,
-                        const int64_t *newval,
-                        volatile int64_t *ptr);
-
-输入:
-
-  r0 = 指向 oldval
-  r1 = 指向 newval
-  r2 = 指向目标值
-  lr = 返回地址
-
-输出:
-
-  r0 = 成功代码 (零或非零)
-  C flag = 如果 r0 == 0 则置 1，如果 r0 != 0 则清零。
-
-被篡改的寄存器:
-
-  r3, lr, flags
-
-定义:
-
-  仅在 *ptr 等于 *oldval 指向的 64 位值时，原子保存 *newval
-  指向的 64 位值于 *ptr 中。如果 *ptr 被改变，则返回值为零，
-  否则为非零值。
-
-  如果 *ptr 被改变，则 C flag 也会被置 1，以实现调用代码中的汇编
-  优化。
-
-使用范例:
-
-typedef int (__kuser_cmpxchg64_t)(const int64_t *oldval,
-                                  const int64_t *newval,
-                                  volatile int64_t *ptr);
-#define __kuser_cmpxchg64 (*(__kuser_cmpxchg64_t *)0xffff0f60)
-
-int64_t atomic_add64(volatile int64_t *ptr, int64_t val)
-{
-	int64_t old, new;
-
-	do {
-		old = *ptr;
-		new = old + val;
-	} while(__kuser_cmpxchg64(&old, &new, ptr));
-
-	return new;
-}
-
-注意:
-
-  - 这个例程已根据需要包含了内存屏障。
-
-  - 由于这个过程的代码长度（此辅助代码跨越 2 个常规的 kuser “槽”），
-    因此 0xffff0f80 不被作为有效的入口点。
-
-  - 仅在 __kuser_helper_version >= 5 时，此辅助代码存在
-    （从内核版本 3.1 开始）。
diff --git a/Documentation/zh_CN/arm64/booting.txt b/Documentation/zh_CN/arm64/booting.txt
deleted file mode 100644
index c1dd968c5ee9..000000000000
--- a/Documentation/zh_CN/arm64/booting.txt
+++ /dev/null
@@ -1,246 +0,0 @@
-Chinese translated version of Documentation/arm64/booting.txt
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-M:	Will Deacon 
-zh_CN:	Fu Wei 
-C:	55f058e7574c3615dea4615573a19bdb258696c6
----------------------------------------------------------------------
-Documentation/arm64/booting.txt 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-
-英文版维护者： Will Deacon 
-中文版维护者： 傅炜  Fu Wei 
-中文版翻译者： 傅炜  Fu Wei 
-中文版校译者： 傅炜  Fu Wei 
-本文翻译提交时的 Git 检出点为： 55f058e7574c3615dea4615573a19bdb258696c6
-
-以下为正文
----------------------------------------------------------------------
-			启动 AArch64 Linux
-			==================
-
-作者: Will Deacon 
-日期: 2012 年 09 月 07 日
-
-本文档基于 Russell King 的 ARM 启动文档，且适用于所有公开发布的
-AArch64 Linux 内核代码。
-
-AArch64 异常模型由多个异常级（EL0 - EL3）组成，对于 EL0 和 EL1 异常级
-有对应的安全和非安全模式。EL2 是系统管理级，且仅存在于非安全模式下。
-EL3 是最高特权级，且仅存在于安全模式下。
-
-基于本文档的目的，我们将简单地使用‘引导装载程序’（‘boot loader’）
-这个术语来定义在将控制权交给 Linux 内核前 CPU 上执行的所有软件。
-这可能包含安全监控和系统管理代码，或者它可能只是一些用于准备最小启动
-环境的指令。
-
-基本上，引导装载程序（至少）应实现以下操作：
-
-1、设置和初始化 RAM
-2、设置设备树数据
-3、解压内核映像
-4、调用内核映像
-
-
-1、设置和初始化 RAM
------------------
-
-必要性: 强制
-
-引导装载程序应该找到并初始化系统中所有内核用于保持系统变量数据的 RAM。
-这个操作的执行方式因设备而异。（它可能使用内部算法来自动定位和计算所有
-RAM，或可能使用对这个设备已知的 RAM 信息，还可能是引导装载程序设计者
-想到的任何合适的方法。）
-
-
-2、设置设备树数据
----------------
-
-必要性: 强制
-
-设备树数据块（dtb）必须 8 字节对齐，且大小不能超过 2MB。由于设备树
-数据块将在使能缓存的情况下以 2MB 粒度被映射，故其不能被置于带任意
-特定属性被映射的 2MB 区域内。
-
-注： v4.2 之前的版本同时要求设备树数据块被置于从内核映像以下
-text_offset 字节处算起第一个 512MB 内。
-
-3、解压内核映像
--------------
-
-必要性: 可选
-
-AArch64 内核当前没有提供自解压代码，因此如果使用了压缩内核映像文件
-（比如 Image.gz），则需要通过引导装载程序（使用 gzip 等）来进行解压。
-若引导装载程序没有实现这个功能，就要使用非压缩内核映像文件。
-
-
-4、调用内核映像
--------------
-
-必要性: 强制
-
-已解压的内核映像包含一个 64 字节的头，内容如下：
-
-  u32 code0;			/* 可执行代码 */
-  u32 code1;			/* 可执行代码 */
-  u64 text_offset;		/* 映像装载偏移，小端模式 */
-  u64 image_size;		/* 映像实际大小, 小端模式 */
-  u64 flags;			/* 内核旗标, 小端模式 *
-  u64 res2	= 0;		/* 保留 */
-  u64 res3	= 0;		/* 保留 */
-  u64 res4	= 0;		/* 保留 */
-  u32 magic	= 0x644d5241;	/* 魔数, 小端, "ARM\x64" */
-  u32 res5;			/* 保留 （用于 PE COFF 偏移） */
-
-
-映像头注释：
-
-- 自 v3.17 起，除非另有说明，所有域都是小端模式。
-
-- code0/code1 负责跳转到 stext.
-
-- 当通过 EFI 启动时， 最初 code0/code1 被跳过。
-  res5 是到 PE 文件头的偏移，而 PE 文件头含有 EFI 的启动入口点
-  （efi_stub_entry）。当 stub 代码完成了它的使命，它会跳转到 code0
-  继续正常的启动流程。
-
-- v3.17 之前，未明确指定 text_offset 的字节序。此时，image_size 为零，
-  且 text_offset 依照内核字节序为 0x80000。
-  当 image_size 非零，text_offset 为小端模式且是有效值，应被引导加载
-  程序使用。当 image_size 为零，text_offset 可假定为 0x80000。
-
-- flags 域 (v3.17 引入) 为 64 位小端模式，其编码如下：
-  位 0: 	内核字节序。 1 表示大端模式，0 表示小端模式。
-  位 1-2:	内核页大小。
-			0 - 未指定。
-			1 - 4K
-			2 - 16K
-			3 - 64K
-  位 3:		内核物理位置
-			0 - 2MB 对齐基址应尽量靠近内存起始处，因为
-			    其基址以下的内存无法通过线性映射访问
-			1 - 2MB 对齐基址可以在物理内存的任意位置
-  位 4-63:	保留。
-
-- 当 image_size 为零时，引导装载程序应试图在内核映像末尾之后尽可能
-  多地保留空闲内存供内核直接使用。对内存空间的需求量因所选定的内核
-  特性而异, 并无实际限制。
-
-内核映像必须被放置在任意一个可用系统内存 2MB 对齐基址的 text_offset
-字节处，并从该处被调用。2MB 对齐基址和内核映像起始地址之间的区域对于
-内核来说没有特殊意义，且可能被用于其他目的。
-从映像起始地址算起，最少必须准备 image_size 字节的空闲内存供内核使用。
-注： v4.6 之前的版本无法使用内核映像物理偏移以下的内存，所以当时建议
-将映像尽量放置在靠近系统内存起始的地方。
-
-任何提供给内核的内存（甚至在映像起始地址之前），若未从内核中标记为保留
-(如在设备树（dtb）的 memreserve 区域），都将被认为对内核是可用。
-
-在跳转入内核前，必须符合以下状态：
-
-- 停止所有 DMA 设备，这样内存数据就不会因为虚假网络包或磁盘数据而
-  被破坏。这可能可以节省你许多的调试时间。
-
-- 主 CPU 通用寄存器设置
-  x0 = 系统 RAM 中设备树数据块（dtb）的物理地址。
-  x1 = 0 (保留，将来可能使用)
-  x2 = 0 (保留，将来可能使用)
-  x3 = 0 (保留，将来可能使用)
-
-- CPU 模式
-  所有形式的中断必须在 PSTATE.DAIF 中被屏蔽（Debug、SError、IRQ
-  和 FIQ）。
-  CPU 必须处于 EL2（推荐，可访问虚拟化扩展）或非安全 EL1 模式下。
-
-- 高速缓存、MMU
-  MMU 必须关闭。
-  指令缓存开启或关闭皆可。
-  已载入的内核映像的相应内存区必须被清理，以达到缓存一致性点（PoC）。
-  当存在系统缓存或其他使能缓存的一致性主控器时，通常需使用虚拟地址
-  维护其缓存，而非 set/way 操作。
-  遵从通过虚拟地址操作维护构架缓存的系统缓存必须被配置，并可以被使能。
-  而不通过虚拟地址操作维护构架缓存的系统缓存（不推荐），必须被配置且
-  禁用。
-
-  *译者注：对于 PoC 以及缓存相关内容，请参考 ARMv8 构架参考手册
-   ARM DDI 0487A
-
-- 架构计时器
-  CNTFRQ 必须设定为计时器的频率，且 CNTVOFF 必须设定为对所有 CPU
-  都一致的值。如果在 EL1 模式下进入内核，则 CNTHCTL_EL2 中的
-  EL1PCTEN (bit 0) 必须置位。
-
-- 一致性
-  通过内核启动的所有 CPU 在内核入口地址上必须处于相同的一致性域中。
-  这可能要根据具体实现来定义初始化过程，以使能每个CPU上对维护操作的
-  接收。
-
-- 系统寄存器
-  在进入内核映像的异常级中，所有构架中可写的系统寄存器必须通过软件
-  在一个更高的异常级别下初始化，以防止在 未知 状态下运行。
-
-  对于拥有 GICv3 中断控制器并以 v3 模式运行的系统：
-  - 如果 EL3 存在：
-    ICC_SRE_EL3.Enable (位 3) 必须初始化为 0b1。
-    ICC_SRE_EL3.SRE (位 0) 必须初始化为 0b1。
-  - 若内核运行在 EL1：
-    ICC_SRE_EL2.Enable (位 3) 必须初始化为 0b1。
-    ICC_SRE_EL2.SRE (位 0) 必须初始化为 0b1。
-  - 设备树（DT）或 ACPI 表必须描述一个 GICv3 中断控制器。
-
-  对于拥有 GICv3 中断控制器并以兼容（v2）模式运行的系统：
-  - 如果 EL3 存在：
-    ICC_SRE_EL3.SRE (位 0) 必须初始化为 0b0。
-  - 若内核运行在 EL1：
-    ICC_SRE_EL2.SRE (位 0) 必须初始化为 0b0。
-  - 设备树（DT）或 ACPI 表必须描述一个 GICv2 中断控制器。
-
-以上对于 CPU 模式、高速缓存、MMU、架构计时器、一致性、系统寄存器的
-必要条件描述适用于所有 CPU。所有 CPU 必须在同一异常级别跳入内核。
-
-引导装载程序必须在每个 CPU 处于以下状态时跳入内核入口：
-
-- 主 CPU 必须直接跳入内核映像的第一条指令。通过此 CPU 传递的设备树
-  数据块必须在每个 CPU 节点中包含一个 ‘enable-method’ 属性，所
-  支持的 enable-method 请见下文。
-
-  引导装载程序必须生成这些设备树属性，并在跳入内核入口之前将其插入
-  数据块。
-
-- enable-method 为 “spin-table” 的 CPU 必须在它们的 CPU
-  节点中包含一个 ‘cpu-release-addr’ 属性。这个属性标识了一个
-  64 位自然对齐且初始化为零的内存位置。
-
-  这些 CPU 必须在内存保留区（通过设备树中的 /memreserve/ 域传递
-  给内核）中自旋于内核之外，轮询它们的 cpu-release-addr 位置（必须
-  包含在保留区中）。可通过插入 wfe 指令来降低忙循环开销，而主 CPU 将
-  发出 sev 指令。当对 cpu-release-addr 所指位置的读取操作返回非零值
-  时，CPU 必须跳入此值所指向的地址。此值为一个单独的 64 位小端值，
-  因此 CPU 须在跳转前将所读取的值转换为其本身的端模式。
-
-- enable-method 为 “psci” 的 CPU 保持在内核外（比如，在
-  memory 节点中描述为内核空间的内存区外，或在通过设备树 /memreserve/
-  域中描述为内核保留区的空间中）。内核将会发起在 ARM 文档（编号
-  ARM DEN 0022A：用于 ARM 上的电源状态协调接口系统软件）中描述的
-  CPU_ON 调用来将 CPU 带入内核。
-
-  *译者注: ARM DEN 0022A 已更新到 ARM DEN 0022C。
-
-  设备树必须包含一个 ‘psci’ 节点，请参考以下文档：
-  Documentation/devicetree/bindings/arm/psci.txt
-
-
-- 辅助 CPU 通用寄存器设置
-  x0 = 0 (保留，将来可能使用)
-  x1 = 0 (保留，将来可能使用)
-  x2 = 0 (保留，将来可能使用)
-  x3 = 0 (保留，将来可能使用)
diff --git a/Documentation/zh_CN/arm64/legacy_instructions.txt b/Documentation/zh_CN/arm64/legacy_instructions.txt
deleted file mode 100644
index 68362a1ab717..000000000000
--- a/Documentation/zh_CN/arm64/legacy_instructions.txt
+++ /dev/null
@@ -1,72 +0,0 @@
-Chinese translated version of Documentation/arm64/legacy_instructions.txt
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Maintainer: Punit Agrawal 
-            Suzuki K. Poulose 
-Chinese maintainer: Fu Wei 
----------------------------------------------------------------------
-Documentation/arm64/legacy_instructions.txt 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-
-本文翻译提交时的 Git 检出点为： bc465aa9d045feb0e13b4a8f32cc33c1943f62d6
-
-英文版维护者： Punit Agrawal 
-            Suzuki K. Poulose 
-中文版维护者： 傅炜  Fu Wei 
-中文版翻译者： 傅炜  Fu Wei 
-中文版校译者： 傅炜  Fu Wei 
-
-以下为正文
----------------------------------------------------------------------
-Linux 内核在 arm64 上的移植提供了一个基础框架，以支持构架中正在被淘汰或已废弃指令的模拟执行。
-这个基础框架的代码使用未定义指令钩子（hooks）来支持模拟。如果指令存在，它也允许在硬件中启用该指令。
-
-模拟模式可通过写 sysctl 节点（/proc/sys/abi）来控制。
-不同的执行方式及 sysctl 节点的相应值，解释如下：
-
-* Undef（未定义）
-  值： 0
-  产生未定义指令终止异常。它是那些构架中已废弃的指令，如 SWP，的默认处理方式。
-
-* Emulate（模拟）
-  值： 1
-  使用软件模拟方式。为解决软件迁移问题，这种模拟指令模式的使用是被跟踪的，并会发出速率限制警告。
-  它是那些构架中正在被淘汰的指令，如 CP15 barriers（隔离指令），的默认处理方式。
-
-* Hardware Execution（硬件执行）
-  值： 2
-  虽然标记为正在被淘汰，但一些实现可能提供硬件执行这些指令的使能/禁用操作。
-  使用硬件执行一般会有更好的性能，但将无法收集运行时对正被淘汰指令的使用统计数据。
-
-默认执行模式依赖于指令在构架中状态。正在被淘汰的指令应该以模拟（Emulate）作为默认模式，
-而已废弃的指令必须默认使用未定义（Undef）模式
-
-注意：指令模拟可能无法应对所有情况。更多详情请参考单独的指令注释。
-
-受支持的遗留指令
--------------
-* SWP{B}
-节点: /proc/sys/abi/swp
-状态: 已废弃
-默认执行方式: Undef (0)
-
-* CP15 Barriers
-节点: /proc/sys/abi/cp15_barrier
-状态: 正被淘汰，不推荐使用
-默认执行方式: Emulate (1)
-
-* SETEND
-节点: /proc/sys/abi/setend
-状态: 正被淘汰，不推荐使用
-默认执行方式: Emulate (1)*
-注：为了使能这个特性，系统中的所有 CPU 必须在 EL0 支持混合字节序。
-如果一个新的 CPU （不支持混合字节序） 在使能这个特性后被热插入系统，
-在应用中可能会出现不可预期的结果。
diff --git a/Documentation/zh_CN/arm64/memory.txt b/Documentation/zh_CN/arm64/memory.txt
deleted file mode 100644
index 19b3a52d5d94..000000000000
--- a/Documentation/zh_CN/arm64/memory.txt
+++ /dev/null
@@ -1,114 +0,0 @@
-Chinese translated version of Documentation/arm64/memory.txt
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Maintainer: Catalin Marinas 
-Chinese maintainer: Fu Wei 
----------------------------------------------------------------------
-Documentation/arm64/memory.txt 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-
-本文翻译提交时的 Git 检出点为： bc465aa9d045feb0e13b4a8f32cc33c1943f62d6
-
-英文版维护者： Catalin Marinas 
-中文版维护者： 傅炜  Fu Wei 
-中文版翻译者： 傅炜  Fu Wei 
-中文版校译者： 傅炜  Fu Wei 
-
-以下为正文
----------------------------------------------------------------------
-		     Linux 在 AArch64 中的内存布局
-		     ===========================
-
-作者: Catalin Marinas 
-
-本文档描述 AArch64 Linux 内核所使用的虚拟内存布局。此构架可以实现
-页大小为 4KB 的 4 级转换表和页大小为 64KB 的 3 级转换表。
-
-AArch64 Linux 使用 3 级或 4 级转换表，其页大小配置为 4KB，对于用户和内核
-分别都有 39-bit (512GB) 或 48-bit (256TB) 的虚拟地址空间。
-对于页大小为 64KB的配置，仅使用 2 级转换表，有 42-bit (4TB) 的虚拟地址空间，但内存布局相同。
-
-用户地址空间的 63:48 位为 0，而内核地址空间的相应位为 1。TTBRx 的
-选择由虚拟地址的 63 位给出。swapper_pg_dir 仅包含内核（全局）映射，
-而用户 pgd 仅包含用户（非全局）映射。swapper_pg_dir 地址被写入
-TTBR1 中，且从不写入 TTBR0。
-
-
-AArch64 Linux 在页大小为 4KB，并使用 3 级转换表时的内存布局：
-
-起始地址			结束地址			大小		用途
------------------------------------------------------------------------
-0000000000000000	0000007fffffffff	 512GB		用户空间
-ffffff8000000000	ffffffffffffffff	 512GB		内核空间
-
-
-AArch64 Linux 在页大小为 4KB，并使用 4 级转换表时的内存布局：
-
-起始地址			结束地址			大小		用途
------------------------------------------------------------------------
-0000000000000000	0000ffffffffffff	 256TB		用户空间
-ffff000000000000	ffffffffffffffff	 256TB		内核空间
-
-
-AArch64 Linux 在页大小为 64KB，并使用 2 级转换表时的内存布局：
-
-起始地址			结束地址			大小		用途
------------------------------------------------------------------------
-0000000000000000	000003ffffffffff	   4TB		用户空间
-fffffc0000000000	ffffffffffffffff	   4TB		内核空间
-
-
-AArch64 Linux 在页大小为 64KB，并使用 3 级转换表时的内存布局：
-
-起始地址			结束地址			大小		用途
------------------------------------------------------------------------
-0000000000000000	0000ffffffffffff	 256TB		用户空间
-ffff000000000000	ffffffffffffffff	 256TB		内核空间
-
-
-更详细的内核虚拟内存布局，请参阅内核启动信息。
-
-
-4KB 页大小的转换表查找：
-
-+--------+--------+--------+--------+--------+--------+--------+--------+
-|63    56|55    48|47    40|39    32|31    24|23    16|15     8|7      0|
-+--------+--------+--------+--------+--------+--------+--------+--------+
- |                 |         |         |         |         |
- |                 |         |         |         |         v
- |                 |         |         |         |   [11:0]  页内偏移
- |                 |         |         |         +-> [20:12] L3 索引
- |                 |         |         +-----------> [29:21] L2 索引
- |                 |         +---------------------> [38:30] L1 索引
- |                 +-------------------------------> [47:39] L0 索引
- +-------------------------------------------------> [63] TTBR0/1
-
-
-64KB 页大小的转换表查找：
-
-+--------+--------+--------+--------+--------+--------+--------+--------+
-|63    56|55    48|47    40|39    32|31    24|23    16|15     8|7      0|
-+--------+--------+--------+--------+--------+--------+--------+--------+
- |                 |    |               |              |
- |                 |    |               |              v
- |                 |    |               |            [15:0]  页内偏移
- |                 |    |               +----------> [28:16] L3 索引
- |                 |    +--------------------------> [41:29] L2 索引
- |                 +-------------------------------> [47:42] L1 索引
- +-------------------------------------------------> [63] TTBR0/1
-
-
-当使用 KVM 时, 管理程序（hypervisor）在 EL2 中通过相对内核虚拟地址的
-一个固定偏移来映射内核页（内核虚拟地址的高 24 位设为零）:
-
-起始地址			结束地址			大小		用途
------------------------------------------------------------------------
-0000004000000000	0000007fffffffff	 256GB		在 HYP 中映射的内核对象
diff --git a/Documentation/zh_CN/arm64/silicon-errata.txt b/Documentation/zh_CN/arm64/silicon-errata.txt
deleted file mode 100644
index 39477c75c4a4..000000000000
--- a/Documentation/zh_CN/arm64/silicon-errata.txt
+++ /dev/null
@@ -1,74 +0,0 @@
-Chinese translated version of Documentation/arm64/silicon-errata.txt
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-M:	Will Deacon 
-zh_CN:	Fu Wei 
-C:	1926e54f115725a9248d0c4c65c22acaf94de4c4
----------------------------------------------------------------------
-Documentation/arm64/silicon-errata.txt 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-
-英文版维护者： Will Deacon 
-中文版维护者： 傅炜  Fu Wei 
-中文版翻译者： 傅炜  Fu Wei 
-中文版校译者： 傅炜  Fu Wei 
-本文翻译提交时的 Git 检出点为： 1926e54f115725a9248d0c4c65c22acaf94de4c4
-
-以下为正文
----------------------------------------------------------------------
-                芯片勘误和软件补救措施
-                ==================
-
-作者: Will Deacon 
-日期: 2015年11月27日
-
-一个不幸的现实：硬件经常带有一些所谓的“瑕疵（errata）”，导致其在
-某些特定情况下会违背构架定义的行为。就基于 ARM 的硬件而言，这些瑕疵
-大体可分为以下几类：
-
-  A 类：无可行补救措施的严重缺陷。
-  B 类：有可接受的补救措施的重大或严重缺陷。
-  C 类：在正常操作中不会显现的小瑕疵。
-
-更多资讯，请在 infocenter.arm.com （需注册）中查阅“软件开发者勘误
-笔记”（“Software Developers Errata Notice”）文档。
-
-对于 Linux 而言，B 类缺陷可能需要操作系统的某些特别处理。例如，避免
-一个特殊的代码序列，或是以一种特定的方式配置处理器。在某种不太常见的
-情况下，为将 A 类缺陷当作 C 类处理，可能需要用类似的手段。这些手段被
-统称为“软件补救措施”，且仅在少数情况需要（例如，那些需要一个运行在
-非安全异常级的补救措施 *并且* 能被 Linux 触发的情况）。
-
-对于尚在讨论中的可能对未受瑕疵影响的系统产生干扰的软件补救措施，有一个
-相应的内核配置（Kconfig）选项被加在 “内核特性（Kernel Features）”->
-“基于可选方法框架的 ARM 瑕疵补救措施（ARM errata workarounds via
-the alternatives framework）"。这些选项被默认开启，若探测到受影响的CPU，
-补丁将在运行时被使用。至于对系统运行影响较小的补救措施，内核配置选项
-并不存在，且代码以某种规避瑕疵的方式被构造（带注释为宜）。
-
-这种做法对于在任意内核源代码树中准确地判断出哪个瑕疵已被软件方法所补救
-稍微有点麻烦，所以在 Linux 内核中此文件作为软件补救措施的注册表，
-并将在新的软件补救措施被提交和向后移植（backported）到稳定内核时被更新。
-
-| 实现者         | 受影响的组件    | 勘误编号        | 内核配置                |
-+----------------+-----------------+-----------------+-------------------------+
-| ARM            | Cortex-A53      | #826319         | ARM64_ERRATUM_826319    |
-| ARM            | Cortex-A53      | #827319         | ARM64_ERRATUM_827319    |
-| ARM            | Cortex-A53      | #824069         | ARM64_ERRATUM_824069    |
-| ARM            | Cortex-A53      | #819472         | ARM64_ERRATUM_819472    |
-| ARM            | Cortex-A53      | #845719         | ARM64_ERRATUM_845719    |
-| ARM            | Cortex-A53      | #843419         | ARM64_ERRATUM_843419    |
-| ARM            | Cortex-A57      | #832075         | ARM64_ERRATUM_832075    |
-| ARM            | Cortex-A57      | #852523         | N/A                     |
-| ARM            | Cortex-A57      | #834220         | ARM64_ERRATUM_834220    |
-|                |                 |                 |                         |
-| Cavium         | ThunderX ITS    | #22375, #24313  | CAVIUM_ERRATUM_22375    |
-| Cavium         | ThunderX GICv3  | #23154          | CAVIUM_ERRATUM_23154    |
diff --git a/Documentation/zh_CN/arm64/tagged-pointers.txt b/Documentation/zh_CN/arm64/tagged-pointers.txt
deleted file mode 100644
index 2664d1bd5a1c..000000000000
--- a/Documentation/zh_CN/arm64/tagged-pointers.txt
+++ /dev/null
@@ -1,52 +0,0 @@
-Chinese translated version of Documentation/arm64/tagged-pointers.txt
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Maintainer: Will Deacon 
-Chinese maintainer: Fu Wei 
----------------------------------------------------------------------
-Documentation/arm64/tagged-pointers.txt 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-
-英文版维护者： Will Deacon 
-中文版维护者： 傅炜  Fu Wei 
-中文版翻译者： 傅炜  Fu Wei 
-中文版校译者： 傅炜  Fu Wei 
-
-以下为正文
----------------------------------------------------------------------
-		Linux 在 AArch64 中带标记的虚拟地址
-		=================================
-
-作者: Will Deacon 
-日期: 2013 年 06 月 12 日
-
-本文档简述了在 AArch64 地址转换系统中提供的带标记的虚拟地址及其在
-AArch64 Linux 中的潜在用途。
-
-内核提供的地址转换表配置使通过 TTBR0 完成的虚拟地址转换（即用户空间
-映射），其虚拟地址的最高 8 位（63:56）会被转换硬件所忽略。这种机制
-让这些位可供应用程序自由使用，其注意事项如下：
-
-	(1) 内核要求所有传递到 EL1 的用户空间地址带有 0x00 标记。
-	    这意味着任何携带用户空间虚拟地址的系统调用（syscall）
-	    参数 *必须* 在陷入内核前使它们的最高字节被清零。
-
-	(2) 非零标记在传递信号时不被保存。这意味着在应用程序中利用了
-	    标记的信号处理函数无法依赖 siginfo_t 的用户空间虚拟
-	    地址所携带的包含其内部域信息的标记。此规则的一个例外是
-	    当信号是在调试观察点的异常处理程序中产生的，此时标记的
-	    信息将被保存。
-
-	(3) 当使用带标记的指针时需特别留心，因为仅对两个虚拟地址
-	    的高字节，C 编译器很可能无法判断它们是不同的。
-
-此构架会阻止对带标记的 PC 指针的利用，因此在异常返回时，其高字节
-将被设置成一个为 “55” 的扩展符。
diff --git a/Documentation/zh_CN/basic_profiling.txt b/Documentation/zh_CN/basic_profiling.txt
deleted file mode 100644
index 1e6bf0bdf8f5..000000000000
--- a/Documentation/zh_CN/basic_profiling.txt
+++ /dev/null
@@ -1,71 +0,0 @@
-Chinese translated version of Documentation/basic_profiling
-
-If you have any comment or update to the content, please post to LKML directly.
-However, if you have problem communicating in English you can also ask the
-Chinese maintainer for help.  Contact the Chinese maintainer, if this
-translation is outdated or there is problem with translation.
-
-Chinese maintainer: Liang Xie 
----------------------------------------------------------------------
-Documentation/basic_profiling的中文翻译
-
-如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可
-以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。
-
-中文版维护者： 谢良 Liang Xie 
-中文版翻译者： 谢良 Liang Xie 
-中文版校译者：
-以下为正文
----------------------------------------------------------------------
-
-下面这些说明指令都是非常基础的，如果你想进一步了解请阅读相关专业文档：）
-请不要再在本文档增加新的内容，但可以修复文档中的错误：）(mbligh@aracnet.com)
-感谢John Levon，Dave Hansen等在撰写时的帮助
-
- 用于表示要测量的目标
-请先确保您已经有正确的System.map / vmlinux配置！
-
-对于linux系统来说，配置vmlinuz最容易的方法可能就是使用“make install”，然后修改
-/sbin/installkernel将vmlinux拷贝到/boot目录，而System.map通常是默认安装好的
-
-Readprofile
------------
-2.6系列内核需要版本相对较新的readprofile，比如util-linux 2.12a中包含的，可以从:
-
-http://www.kernel.org/pub/linux/utils/util-linux/ 下载
-
-大部分linux发行版已经包含了.
-
-启用readprofile需要在kernel启动命令行增加”profile=2“
-
-clear		readprofile -r
-		
-dump output	readprofile -m /boot/System.map > captured_profile
-
-Oprofile
---------
-
-从http://oprofile.sourceforge.net/获取源代码（请参考Changes以获取匹配的版本）
-在kernel启动命令行增加“idle=poll”
-
-配置CONFIG_PROFILING=y和CONFIG_OPROFILE=y然后重启进入新kernel
-
-./configure --with-kernel-support
-make install
-
-想得到好的测量结果，请确保启用了本地APIC特性。如果opreport显示有0Hz CPU，
-说明APIC特性没有开启。另外注意idle=poll选项可能有损性能。
-
-One time setup:
-		opcontrol --setup --vmlinux=/boot/vmlinux
-
-clear		opcontrol --reset
-start		opcontrol --start
-		
-stop		opcontrol --stop
-dump output	opreport >  output_file
-
-如果只看kernel相关的报告结果，请运行命令 opreport -l /boot/vmlinux > output_file
-
-通过reset选项可以清理过期统计数据，相当于重启的效果。
-
diff --git a/Documentation/zh_CN/email-clients.txt b/Documentation/zh_CN/email-clients.txt
deleted file mode 100644
index ec31d97e8d0e..000000000000
--- a/Documentation/zh_CN/email-clients.txt
+++ /dev/null
@@ -1,210 +0,0 @@
-Chinese translated version of Documentation/process/email-clients.rst
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Chinese maintainer: Harry Wei 
----------------------------------------------------------------------
-Documentation/process/email-clients.rst 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-
-中文版维护者： 贾威威  Harry Wei 
-中文版翻译者： 贾威威  Harry Wei 
-中文版校译者： Yinglin Luan 
-		Xiaochen Wang 
-		yaxinsn 
-
-以下为正文
----------------------------------------------------------------------
-
-Linux邮件客户端配置信息
-======================================================================
-
-普通配置
-----------------------------------------------------------------------
-Linux内核补丁是通过邮件被提交的，最好把补丁作为邮件体的内嵌文本。有些维护者
-接收附件，但是附件的内容格式应该是"text/plain"。然而，附件一般是不赞成的，
-因为这会使补丁的引用部分在评论过程中变的很困难。
-
-用来发送Linux内核补丁的邮件客户端在发送补丁时应该处于文本的原始状态。例如，
-他们不能改变或者删除制表符或者空格，甚至是在每一行的开头或者结尾。
-
-不要通过"format=flowed"模式发送补丁。这样会引起不可预期以及有害的断行。
-
-不要让你的邮件客户端进行自动换行。这样也会破坏你的补丁。
-
-邮件客户端不能改变文本的字符集编码方式。要发送的补丁只能是ASCII或者UTF-8编码方式，
-如果你使用UTF-8编码方式发送邮件，那么你将会避免一些可能发生的字符集问题。
-
-邮件客户端应该形成并且保持 References: 或者 In-Reply-To: 标题，那么
-邮件话题就不会中断。
-
-复制粘帖(或者剪贴粘帖)通常不能用于补丁，因为制表符会转换为空格。使用xclipboard, xclip
-或者xcutsel也许可以，但是最好测试一下或者避免使用复制粘帖。
-
-不要在使用PGP/GPG署名的邮件中包含补丁。这样会使得很多脚本不能读取和适用于你的补丁。
-（这个问题应该是可以修复的）
-
-在给内核邮件列表发送补丁之前，给自己发送一个补丁是个不错的主意，保存接收到的
-邮件，将补丁用'patch'命令打上，如果成功了，再给内核邮件列表发送。
-
-
-一些邮件客户端提示
-----------------------------------------------------------------------
-这里给出一些详细的MUA配置提示，可以用于给Linux内核发送补丁。这些并不意味是
-所有的软件包配置总结。
-
-说明：
-TUI = 以文本为基础的用户接口
-GUI = 图形界面用户接口
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Alpine (TUI)
-
-配置选项：
-在"Sending Preferences"部分：
-
-- "Do Not Send Flowed Text"必须开启
-- "Strip Whitespace Before Sending"必须关闭
-
-当写邮件时，光标应该放在补丁会出现的地方，然后按下CTRL-R组合键，使指定的
-补丁文件嵌入到邮件中。
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Evolution (GUI)
-
-一些开发者成功的使用它发送补丁
-
-当选择邮件选项：Preformat
-  从Format->Heading->Preformatted (Ctrl-7)或者工具栏
-
-然后使用：
-  Insert->Text File... (Alt-n x)插入补丁文件。
-
-你还可以"diff -Nru old.c new.c | xclip"，选择Preformat，然后使用中间键进行粘帖。
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Kmail (GUI)
-
-一些开发者成功的使用它发送补丁。
-
-默认设置不为HTML格式是合适的；不要启用它。
-
-当书写一封邮件的时候，在选项下面不要选择自动换行。唯一的缺点就是你在邮件中输入的任何文本
-都不会被自动换行，因此你必须在发送补丁之前手动换行。最简单的方法就是启用自动换行来书写邮件，
-然后把它保存为草稿。一旦你在草稿中再次打开它，它已经全部自动换行了，那么你的邮件虽然没有
-选择自动换行，但是还不会失去已有的自动换行。
-
-在邮件的底部，插入补丁之前，放上常用的补丁定界符：三个连字号(---)。
-
-然后在"Message"菜单条目，选择插入文件，接着选取你的补丁文件。还有一个额外的选项，你可以
-通过它配置你的邮件建立工具栏菜单，还可以带上"insert file"图标。
-
-你可以安全地通过GPG标记附件，但是内嵌补丁最好不要使用GPG标记它们。作为内嵌文本的签发补丁，
-当从GPG中提取7位编码时会使他们变的更加复杂。
-
-如果你非要以附件的形式发送补丁，那么就右键点击附件，然后选中属性，突出"Suggest automatic
-display"，这样内嵌附件更容易让读者看到。
-
-当你要保存将要发送的内嵌文本补丁，你可以从消息列表窗格选择包含补丁的邮件，然后右击选择
-"save as"。你可以使用一个没有更改的包含补丁的邮件，如果它是以正确的形式组成。当你正真在它
-自己的窗口之下察看，那时没有选项可以保存邮件--已经有一个这样的bug被汇报到了kmail的bugzilla
-并且希望这将会被处理。邮件是以只针对某个用户可读写的权限被保存的，所以如果你想把邮件复制到其他地方，
-你不得不把他们的权限改为组或者整体可读。
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Lotus Notes (GUI)
-
-不要使用它。
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Mutt (TUI)
-
-很多Linux开发人员使用mutt客户端，所以证明它肯定工作的非常漂亮。
-
-Mutt不自带编辑器，所以不管你使用什么编辑器都不应该带有自动断行。大多数编辑器都带有
-一个"insert file"选项，它可以通过不改变文件内容的方式插入文件。
-
-'vim'作为mutt的编辑器：
-  set editor="vi"
-
-  如果使用xclip，敲入以下命令
-  :set paste
-  按中键之前或者shift-insert或者使用
-  :r filename
-
-如果想要把补丁作为内嵌文本。
-(a)ttach工作的很好，不带有"set paste"。
-
-配置选项：
-它应该以默认设置的形式工作。
-然而，把"send_charset"设置为"us-ascii::utf-8"也是一个不错的主意。
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Pine (TUI)
-
-Pine过去有一些空格删减问题，但是这些现在应该都被修复了。
-
-如果可以，请使用alpine(pine的继承者)
-
-配置选项：
-- 最近的版本需要消除流程文本
-- "no-strip-whitespace-before-send"选项也是需要的。
-
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Sylpheed (GUI)
-
-- 内嵌文本可以很好的工作（或者使用附件）。
-- 允许使用外部的编辑器。
-- 对于目录较多时非常慢。
-- 如果通过non-SSL连接，无法使用TLS SMTP授权。
-- 在组成窗口中有一个很有用的ruler bar。
-- 给地址本中添加地址就不会正确的了解显示名。
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Thunderbird (GUI)
-
-默认情况下，thunderbird很容易损坏文本，但是还有一些方法可以强制它变得更好。
-
-- 在用户帐号设置里，组成和寻址，不要选择"Compose messages in HTML format"。
-
-- 编辑你的Thunderbird配置设置来使它不要拆行使用：user_pref("mailnews.wraplength", 0);
-
-- 编辑你的Thunderbird配置设置，使它不要使用"format=flowed"格式：user_pref("mailnews.
-  send_plaintext_flowed", false);
-
-- 你需要使Thunderbird变为预先格式方式：
-  如果默认情况下你书写的是HTML格式，那不是很难。仅仅从标题栏的下拉框中选择"Preformat"格式。
-  如果默认情况下你书写的是文本格式，你不得把它改为HTML格式（仅仅作为一次性的）来书写新的消息，
-  然后强制使它回到文本格式，否则它就会拆行。要实现它，在写信的图标上使用shift键来使它变为HTML
-  格式，然后标题栏的下拉框中选择"Preformat"格式。
-
-- 允许使用外部的编辑器：
-  针对Thunderbird打补丁最简单的方法就是使用一个"external editor"扩展，然后使用你最喜欢的
-  $EDITOR来读取或者合并补丁到文本中。要实现它，可以下载并且安装这个扩展，然后添加一个使用它的
-  按键View->Toolbars->Customize...最后当你书写信息的时候仅仅点击它就可以了。
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-TkRat (GUI)
-
-可以使用它。使用"Insert file..."或者外部的编辑器。
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Gmail (Web GUI)
-
-不要使用它发送补丁。
-
-Gmail网页客户端自动地把制表符转换为空格。
-
-虽然制表符转换为空格问题可以被外部编辑器解决，同时它还会使用回车换行把每行拆分为78个字符。
-
-另一个问题是Gmail还会把任何不是ASCII的字符的信息改为base64编码。它把东西变的像欧洲人的名字。
-
-                                ###
diff --git a/Documentation/zh_CN/filesystems/sysfs.txt b/Documentation/zh_CN/filesystems/sysfs.txt
deleted file mode 100644
index 7d3b05edb8ce..000000000000
--- a/Documentation/zh_CN/filesystems/sysfs.txt
+++ /dev/null
@@ -1,372 +0,0 @@
-Chinese translated version of Documentation/filesystems/sysfs.txt
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Maintainer: Patrick Mochel	
-		Mike Murphy 
-Chinese maintainer: Fu Wei 
----------------------------------------------------------------------
-Documentation/filesystems/sysfs.txt 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-英文版维护者： Patrick Mochel	
-		Mike Murphy 
-中文版维护者： 傅炜 Fu Wei 
-中文版翻译者： 傅炜 Fu Wei 
-中文版校译者： 傅炜 Fu Wei 
-
-
-以下为正文
----------------------------------------------------------------------
-sysfs - 用于导出内核对象(kobject)的文件系统
-
-Patrick Mochel	
-Mike Murphy 
-
-修订:    16 August 2011
-原始版本:   10 January 2003
-
-
-sysfs 简介:
-~~~~~~~~~~
-
-sysfs 是一个最初基于 ramfs 且位于内存的文件系统。它提供导出内核
-数据结构及其属性，以及它们之间的关联到用户空间的方法。
-
-sysfs 始终与 kobject 的底层结构紧密相关。请阅读
-Documentation/kobject.txt 文档以获得更多关于 kobject 接口的
-信息。
-
-
-使用 sysfs
-~~~~~~~~~~~
-
-只要内核配置中定义了 CONFIG_SYSFS ，sysfs 总是被编译进内核。你可
-通过以下命令挂载它:
-
-    mount -t sysfs sysfs /sys
-
-
-创建目录
-~~~~~~~~
-
-任何 kobject 在系统中注册，就会有一个目录在 sysfs 中被创建。这个
-目录是作为该 kobject 的父对象所在目录的子目录创建的，以准确地传递
-内核的对象层次到用户空间。sysfs 中的顶层目录代表着内核对象层次的
-共同祖先；例如：某些对象属于某个子系统。
-
-Sysfs 在与其目录关联的 kernfs_node 对象中内部保存一个指向实现
-目录的 kobject 的指针。以前，这个 kobject 指针被 sysfs 直接用于
-kobject 文件打开和关闭的引用计数。而现在的 sysfs 实现中，kobject
-引用计数只能通过 sysfs_schedule_callback() 函数直接修改。
-
-
-属性
-~~~~
-
-kobject 的属性可在文件系统中以普通文件的形式导出。Sysfs 为属性定义
-了面向文件 I/O 操作的方法，以提供对内核属性的读写。
-
-
-属性应为 ASCII 码文本文件。以一个文件只存储一个属性值为宜。但一个
-文件只包含一个属性值可能影响效率，所以一个包含相同数据类型的属性值
-数组也被广泛地接受。
-
-混合类型、表达多行数据以及一些怪异的数据格式会遭到强烈反对。这样做是
-很丢脸的,而且其代码会在未通知作者的情况下被重写。
-
-
-一个简单的属性结构定义如下:
-
-struct attribute {
-        char                    * name;
-        struct module		*owner;
-        umode_t                 mode;
-};
-
-
-int sysfs_create_file(struct kobject * kobj, const struct attribute * attr);
-void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr);
-
-
-一个单独的属性结构并不包含读写其属性值的方法。子系统最好为增删特定
-对象类型的属性定义自己的属性结构体和封装函数。
-
-例如:驱动程序模型定义的 device_attribute 结构体如下:
-
-struct device_attribute {
-	struct attribute	attr;
-	ssize_t (*show)(struct device *dev, struct device_attribute *attr,
-			char *buf);
-	ssize_t (*store)(struct device *dev, struct device_attribute *attr,
-			 const char *buf, size_t count);
-};
-
-int device_create_file(struct device *, const struct device_attribute *);
-void device_remove_file(struct device *, const struct device_attribute *);
-
-为了定义设备属性，同时定义了一下辅助宏:
-
-#define DEVICE_ATTR(_name, _mode, _show, _store) \
-struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)
-
-例如:声明
-
-static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo);
-
-等同于如下代码：
-
-static struct device_attribute dev_attr_foo = {
-       .attr	= {
-		.name = "foo",
-		.mode = S_IWUSR | S_IRUGO,
-		.show = show_foo,
-		.store = store_foo,
-	},
-};
-
-
-子系统特有的回调函数
-~~~~~~~~~~~~~~~~~~~
-
-当一个子系统定义一个新的属性类型时，必须实现一系列的 sysfs 操作，
-以帮助读写调用实现属性所有者的显示和储存方法。
-
-struct sysfs_ops {
-        ssize_t (*show)(struct kobject *, struct attribute *, char *);
-        ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t);
-};
-
-[子系统应已经定义了一个 struct kobj_type 结构体作为这个类型的
-描述符，并在此保存 sysfs_ops 的指针。更多的信息参见 kobject 的
-文档]
-
-sysfs 会为这个类型调用适当的方法。当一个文件被读写时，这个方法会
-将一般的kobject 和 attribute 结构体指针转换为适当的指针类型后
-调用相关联的函数。
-
-
-示例:
-
-#define to_dev(obj) container_of(obj, struct device, kobj)
-#define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr)
-
-static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr,
-                             char *buf)
-{
-        struct device_attribute *dev_attr = to_dev_attr(attr);
-        struct device *dev = to_dev(kobj);
-        ssize_t ret = -EIO;
-
-        if (dev_attr->show)
-                ret = dev_attr->show(dev, dev_attr, buf);
-        if (ret >= (ssize_t)PAGE_SIZE) {
-                print_symbol("dev_attr_show: %s returned bad count\n",
-                                (unsigned long)dev_attr->show);
-        }
-        return ret;
-}
-
-
-
-读写属性数据
-~~~~~~~~~~~~
-
-在声明属性时，必须指定 show() 或 store() 方法，以实现属性的
-读或写。这些方法的类型应该和以下的设备属性定义一样简单。
-
-ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf);
-ssize_t (*store)(struct device *dev, struct device_attribute *attr,
-                 const char *buf, size_t count);
-
-也就是说,他们应只以一个处理对象、一个属性和一个缓冲指针作为参数。
-
-sysfs 会分配一个大小为 (PAGE_SIZE) 的缓冲区并传递给这个方法。
-Sysfs 将会为每次读写操作调用一次这个方法。这使得这些方法在执行时
-会出现以下的行为:
-
-- 在读方面（read(2)），show() 方法应该填充整个缓冲区。回想属性
-  应只导出了一个属性值或是一个同类型属性值的数组，所以这个代价将
-  不会不太高。
-
-  这使得用户空间可以局部地读和任意的向前搜索整个文件。如果用户空间
-  向后搜索到零或使用‘0’偏移执行一个pread(2)操作，show()方法将
-  再次被调用，以重新填充缓存。
-
-- 在写方面（write(2)），sysfs 希望在第一次写操作时得到整个缓冲区。
-  之后 Sysfs 传递整个缓冲区给 store() 方法。
-
-  当要写 sysfs 文件时，用户空间进程应首先读取整个文件，修该想要
-  改变的值，然后回写整个缓冲区。
-
-  在读写属性值时，属性方法的执行应操作相同的缓冲区。
-
-注记:
-
-- 写操作导致的 show() 方法重载，会忽略当前文件位置。
-
-- 缓冲区应总是 PAGE_SIZE 大小。对于i386，这个值为4096。
-
-- show() 方法应该返回写入缓冲区的字节数，也就是 snprintf()的
-  返回值。
-
-- show() 应始终使用 snprintf()。
-
-- store() 应返回缓冲区的已用字节数。如果整个缓存都已填满，只需返回
-  count 参数。
-
-- show() 或 store() 可以返回错误值。当得到一个非法值，必须返回一个
-  错误值。
-
-- 一个传递给方法的对象将会通过 sysfs 调用对象内嵌的引用计数固定在
-  内存中。尽管如此，对象代表的物理实体(如设备)可能已不存在。如有必要，
-  应该实现一个检测机制。
-
-一个简单的(未经实验证实的)设备属性实现如下：
-
-static ssize_t show_name(struct device *dev, struct device_attribute *attr,
-                         char *buf)
-{
-	return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name);
-}
-
-static ssize_t store_name(struct device *dev, struct device_attribute *attr,
-                          const char *buf, size_t count)
-{
-        snprintf(dev->name, sizeof(dev->name), "%.*s",
-                 (int)min(count, sizeof(dev->name) - 1), buf);
-	return count;
-}
-
-static DEVICE_ATTR(name, S_IRUGO, show_name, store_name);
-
-
-（注意：真正的实现不允许用户空间设置设备名。）
-
-顶层目录布局
-~~~~~~~~~~~~
-
-sysfs 目录的安排显示了内核数据结构之间的关系。
-
-顶层 sysfs 目录如下:
-
-block/
-bus/
-class/
-dev/
-devices/
-firmware/
-net/
-fs/
-
-devices/ 包含了一个设备树的文件系统表示。他直接映射了内部的内核
-设备树，反映了设备的层次结构。
-
-bus/ 包含了内核中各种总线类型的平面目录布局。每个总线目录包含两个
-子目录:
-
-	devices/
-	drivers/
-
-devices/ 包含了系统中出现的每个设备的符号链接，他们指向 root/ 下的
-设备目录。
-
-drivers/ 包含了每个已为特定总线上的设备而挂载的驱动程序的目录(这里
-假定驱动没有跨越多个总线类型)。
-
-fs/ 包含了一个为文件系统设立的目录。现在每个想要导出属性的文件系统必须
-在 fs/ 下创建自己的层次结构(参见Documentation/filesystems/fuse.txt)。
-
-dev/ 包含两个子目录： char/ 和 block/。在这两个子目录中，有以
-: 格式命名的符号链接。这些符号链接指向 sysfs 目录
-中相应的设备。/sys/dev 提供一个通过一个 stat(2) 操作结果，查找
-设备 sysfs 接口快捷的方法。
-
-更多有关 driver-model 的特性信息可以在 Documentation/driver-model/
-中找到。
-
-
-TODO: 完成这一节。
-
-
-当前接口
-~~~~~~~~
-
-以下的接口层普遍存在于当前的sysfs中:
-
-- 设备 (include/linux/device.h)
-----------------------------------
-结构体:
-
-struct device_attribute {
-	struct attribute	attr;
-	ssize_t (*show)(struct device *dev, struct device_attribute *attr,
-			char *buf);
-	ssize_t (*store)(struct device *dev, struct device_attribute *attr,
-			 const char *buf, size_t count);
-};
-
-声明:
-
-DEVICE_ATTR(_name, _mode, _show, _store);
-
-增/删属性:
-
-int device_create_file(struct device *dev, const struct device_attribute * attr);
-void device_remove_file(struct device *dev, const struct device_attribute * attr);
-
-
-- 总线驱动程序 (include/linux/device.h)
---------------------------------------
-结构体:
-
-struct bus_attribute {
-        struct attribute        attr;
-        ssize_t (*show)(struct bus_type *, char * buf);
-        ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
-};
-
-声明:
-
-BUS_ATTR(_name, _mode, _show, _store)
-
-增/删属性:
-
-int bus_create_file(struct bus_type *, struct bus_attribute *);
-void bus_remove_file(struct bus_type *, struct bus_attribute *);
-
-
-- 设备驱动程序 (include/linux/device.h)
------------------------------------------
-
-结构体:
-
-struct driver_attribute {
-        struct attribute        attr;
-        ssize_t (*show)(struct device_driver *, char * buf);
-        ssize_t (*store)(struct device_driver *, const char * buf,
-                         size_t count);
-};
-
-声明:
-
-DRIVER_ATTR(_name, _mode, _show, _store)
-
-增/删属性：
-
-int driver_create_file(struct device_driver *, const struct driver_attribute *);
-void driver_remove_file(struct device_driver *, const struct driver_attribute *);
-
-
-文档
-~~~~
-
-sysfs 目录结构以及其中包含的属性定义了一个内核与用户空间之间的 ABI。
-对于任何 ABI，其自身的稳定和适当的文档是非常重要的。所有新的 sysfs
-属性必须在 Documentation/ABI 中有文档。详见 Documentation/ABI/README。
diff --git a/Documentation/zh_CN/gpio.txt b/Documentation/zh_CN/gpio.txt
deleted file mode 100644
index bce972521065..000000000000
--- a/Documentation/zh_CN/gpio.txt
+++ /dev/null
@@ -1,650 +0,0 @@
-Chinese translated version of Documentation/gpio.txt
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Maintainer: Grant Likely 
-		Linus Walleij 
-Chinese maintainer: Fu Wei 
----------------------------------------------------------------------
-Documentation/gpio.txt 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-英文版维护者： Grant Likely 
-		Linus Walleij 
-中文版维护者： 傅炜 Fu Wei 
-中文版翻译者： 傅炜 Fu Wei 
-中文版校译者： 傅炜 Fu Wei 
-
-
-以下为正文
----------------------------------------------------------------------
-GPIO 接口
-
-本文档提供了一个在Linux下访问GPIO的公约概述。
-
-这些函数以 gpio_* 作为前缀。其他的函数不允许使用这样的前缀或相关的
-__gpio_* 前缀。
-
-
-什么是GPIO?
-==========
-"通用输入/输出口"(GPIO)是一个灵活的由软件控制的数字信号。他们可
-由多种芯片提供,且对于从事嵌入式和定制硬件的 Linux 开发者来说是
-比较熟悉。每个GPIO 都代表一个连接到特定引脚或球栅阵列(BGA)封装中
-“球珠”的一个位。电路板原理图显示了 GPIO 与外部硬件的连接关系。
-驱动可以编写成通用代码，以使板级启动代码可传递引脚配置数据给驱动。
-
-片上系统 (SOC) 处理器对 GPIO 有很大的依赖。在某些情况下,每个
-非专用引脚都可配置为 GPIO,且大多数芯片都最少有一些 GPIO。
-可编程逻辑器件(类似 FPGA) 可以方便地提供 GPIO。像电源管理和
-音频编解码器这样的多功能芯片经常留有一些这样的引脚来帮助那些引脚
-匮乏的 SOC。同时还有通过 I2C 或 SPI 串行总线连接的“GPIO扩展器”
-芯片。大多数 PC 的南桥有一些拥有 GPIO 能力的引脚 (只有BIOS
-固件才知道如何使用他们)。
-
-GPIO 的实际功能因系统而异。通常用法有:
-
-  - 输出值可写 (高电平=1，低电平=0)。一些芯片也有如何驱动这些值的选项,
-    例如只允许输出一个值、支持“线与”及其他取值类似的模式(值得注意的是
-    “开漏”信号)
-
-  - 输入值可读(1、0)。一些芯片支持引脚在配置为“输出”时回读，这对于类似
-    “线与”的情况(以支持双向信号)是非常有用的。GPIO 控制器可能有输入
-    去毛刺/消抖逻辑,这有时需要软件控制。
-
-  - 输入通常可作为 IRQ 信号,一般是沿触发,但有时是电平触发。这样的 IRQ
-    可能配置为系统唤醒事件,以将系统从低功耗状态下唤醒。
-
-  - 通常一个 GPIO 根据不同产品电路板的需求,可以配置为输入或输出,也有仅
-    支持单向的。
-
-  - 大部分 GPIO 可以在持有自旋锁时访问,但是通常由串行总线扩展的 GPIO
-    不允许持有自旋锁。但某些系统也支持这种类型。
-
-对于给定的电路板,每个 GPIO 都用于某个特定的目的,如监控 MMC/SD 卡的
-插入/移除、检测卡的写保护状态、驱动 LED、配置收发器、模拟串行总线、
-复位硬件看门狗、感知开关状态等等。
-
-
-GPIO 公约
-=========
-注意,这个叫做“公约”，因为这不是强制性的，不遵循这个公约是无伤大雅的，
-因为此时可移植性并不重要。GPIO 常用于板级特定的电路逻辑,甚至可能
-随着电路板的版本而改变，且不可能在不同走线的电路板上使用。仅有在少数
-功能上才具有可移植性，其他功能是平台特定。这也是由于“胶合”的逻辑造成的。
-
-此外，这不需要任何的执行框架，只是一个接口。某个平台可能通过一个简单地
-访问芯片寄存器的内联函数来实现它，其他平台可能通过委托一系列不同的GPIO
-控制器的抽象函数来实现它。(有一些可选的代码能支持这种策略的实现,本文档
-后面会介绍，但作为 GPIO 接口的客户端驱动程序必须与它的实现无关。)
-
-也就是说,如果在他们的平台上支持这个公约，驱动应尽可能的使用它。同时，平台
-必须在 Kconfig 中选择 ARCH_REQUIRE_GPIOLIB 或者 ARCH_WANT_OPTIONAL_GPIOLIB
-选项。那些调用标准 GPIO 函数的驱动应该在 Kconfig 入口中声明依赖GENERIC_GPIO。
-当驱动包含文件:
-
-	#include 
-
-则 GPIO 函数是可用,无论是“真实代码”还是经优化过的语句。如果你遵守
-这个公约，当你的代码完成后，对其他的开发者来说会更容易看懂和维护。
-
-注意，这些操作包含所用平台的 I/O 屏障代码，驱动无须显式地调用他们。
-
-
-标识 GPIO
----------
-GPIO 是通过无符号整型来标识的,范围是 0 到 MAX_INT。保留“负”数
-用于其他目的,例如标识信号“在这个板子上不可用”或指示错误。未接触底层
-硬件的代码会忽略这些整数。
-
-平台会定义这些整数的用法,且通常使用 #define 来定义 GPIO，这样
-板级特定的启动代码可以直接关联相应的原理图。相对来说，驱动应该仅使用
-启动代码传递过来的 GPIO 编号，使用 platform_data 保存板级特定
-引脚配置数据 (同时还有其他须要的板级特定数据)，避免可能出现的问题。
-
-例如一个平台使用编号 32-159 来标识 GPIO,而在另一个平台使用编号0-63
-标识一组 GPIO 控制器,64-79标识另一类 GPIO 控制器,且在一个含有
-FPGA 的特定板子上使用 80-95。编号不一定要连续,那些平台中，也可以
-使用编号2000-2063来标识一个 I2C 接口的 GPIO 扩展器中的 GPIO。
-
-如果你要初始化一个带有无效 GPIO 编号的结构体,可以使用一些负编码
-(如"-EINVAL")，那将使其永远不会是有效。来测试这样一个结构体中的编号
-是否关联一个 GPIO，你可使用以下断言:
-
-	int gpio_is_valid(int number);
-
-如果编号不存在，则请求和释放 GPIO 的函数将拒绝执行相关操作(见下文)。
-其他编号也可能被拒绝,比如一个编号可能存在，但暂时在给定的电路上不可用。
-
-一个平台是否支持多个 GPIO 控制器为平台特定的实现问题，就像是否可以
-在 GPIO 编号空间中有“空洞”和是否可以在运行时添加新的控制器一样。
-这些问题会影响其他事情，包括相邻的 GPIO 编号是否存在等。
-
-使用 GPIO
----------
-对于一个 GPIO，系统应该做的第一件事情就是通过 gpio_request()
-函数分配它，见下文。
-
-接下来是设置I/O方向，这通常是在板级启动代码中为所使用的 GPIO 设置
-platform_device 时完成。
-
-	/* 设置为输入或输出, 返回 0 或负的错误代码 */
-	int gpio_direction_input(unsigned gpio);
-	int gpio_direction_output(unsigned gpio, int value);
-
-返回值为零代表成功，否则返回一个负的错误代码。这个返回值需要检查，因为
-get/set(获取/设置)函数调用没法返回错误,且有可能是配置错误。通常，
-你应该在进程上下文中调用这些函数。然而,对于自旋锁安全的 GPIO，在板子
-启动的早期、进程启动前使用他们也是可以的。
-
-对于作为输出的 GPIO，为其提供初始输出值，对于避免在系统启动期间出现
-信号毛刺是很有帮助的。
-
-为了与传统的 GPIO 接口兼容, 在设置一个 GPIO 方向时，如果它还未被申请，
-则隐含了申请那个 GPIO 的操作(见下文)。这种兼容性正在从可选的 gpiolib
-框架中移除。
-
-如果这个 GPIO 编码不存在，或者特定的 GPIO 不能用于那种模式，则方向
-设置可能失败。依赖启动固件来正确地设置方向通常是一个坏主意，因为它可能
-除了启动Linux，并没有做更多的验证工作。(同理, 板子的启动代码可能需要
-将这个复用的引脚设置为 GPIO，并正确地配置上拉/下拉电阻。)
-
-
-访问自旋锁安全的 GPIO
--------------------
-大多数 GPIO 控制器可以通过内存读/写指令来访问。这些指令不会休眠,可以
-安全地在硬(非线程)中断例程和类似的上下文中完成。
-
-对于那些用 gpio_cansleep()测试总是返回失败的 GPIO(见下文)，使用
-以下的函数访问:
-
-	/* GPIO 输入:返回零或非零 */
-	int gpio_get_value(unsigned gpio);
-
-	/* GPIO 输出 */
-	void gpio_set_value(unsigned gpio, int value);
-
-GPIO值是布尔值，零表示低电平，非零表示高电平。当读取一个输出引脚的值时，
-返回值应该是引脚上的值。这个值不总是和输出值相符，因为存在开漏输出信号和
-输出延迟问题。
-
-以上的 get/set 函数无错误返回值，因为之前 gpio_direction_*()应已检查过
-其是否为“无效GPIO”。此外，还需要注意的是并不是所有平台都可以从输出引脚
-中读取数据，对于不能读取的引脚应总返回零。另外，对那些在原子上下文中无法
-安全访问的 GPIO (译者注：因为访问可能导致休眠)使用这些函数是不合适的
-(见下文)。
-
-在 GPIO 编号(还有输出、值)为常数的情况下,鼓励通过平台特定的实现来优化
-这两个函数来访问 GPIO 值。这种情况(读写一个硬件寄存器)下只需要几条指令
-是很正常的,且无须自旋锁。这种优化函数比起那些在子程序上花费许多指令的
-函数可以使得模拟接口(译者注:例如 GPIO 模拟 I2C、1-wire 或 SPI)的
-应用(在空间和时间上都)更具效率。
-
-
-访问可能休眠的 GPIO
------------------
-某些 GPIO 控制器必须通过基于总线(如 I2C 或 SPI)的消息访问。读或写这些
-GPIO 值的命令需要等待其信息排到队首才发送命令，再获得其反馈。期间需要
-休眠，这不能在 IRQ 例程(中断上下文)中执行。
-
-支持此类 GPIO 的平台通过以下函数返回非零值来区分出这种 GPIO。(此函数需要
-一个之前通过 gpio_request 分配到的有效 GPIO 编号):
-
-	int gpio_cansleep(unsigned gpio);
-
-为了访问这种 GPIO,内核定义了一套不同的函数:
-
-	/* GPIO 输入:返回零或非零 ,可能会休眠 */
-	int gpio_get_value_cansleep(unsigned gpio);
-
-	/* GPIO 输出,可能会休眠 */
-	void gpio_set_value_cansleep(unsigned gpio, int value);
-
-
-访问这样的 GPIO 需要一个允许休眠的上下文，例如线程 IRQ 处理例程，并用以上的
-访问函数替换那些没有 cansleep()后缀的自旋锁安全访问函数。
-
-除了这些访问函数可能休眠，且它们操作的 GPIO 不能在硬件 IRQ 处理例程中访问的
-事实，这些处理例程实际上和自旋锁安全的函数是一样的。
-
-** 除此之外 ** 调用设置和配置此类 GPIO 的函数也必须在允许休眠的上下文中，
-因为它们可能也需要访问 GPIO 控制器芯片: (这些设置函数通常在板级启动代码或者
-驱动探测/断开代码中，所以这是一个容易满足的约束条件。)
-
-	gpio_direction_input()
-	gpio_direction_output()
-	gpio_request()
-
-## 	gpio_request_one()
-##	gpio_request_array()
-## 	gpio_free_array()
-
-	gpio_free()
-	gpio_set_debounce()
-
-
-
-声明和释放 GPIO
-----------------------------
-为了有助于捕获系统配置错误,定义了两个函数。
-
-	/* 申请 GPIO, 返回 0 或负的错误代码.
-	 * 非空标签可能有助于诊断.
-	 */
-	int gpio_request(unsigned gpio, const char *label);
-
-	/* 释放之前声明的 GPIO */
-	void gpio_free(unsigned gpio);
-
-将无效的 GPIO 编码传递给 gpio_request()会导致失败，申请一个已使用这个
-函数声明过的 GPIO 也会失败。gpio_request()的返回值必须检查。你应该在
-进程上下文中调用这些函数。然而,对于自旋锁安全的 GPIO,在板子启动的早期、
-进入进程之前是可以申请的。
-
-这个函数完成两个基本的目标。一是标识那些实际上已作为 GPIO 使用的信号线，
-这样便于更好地诊断;系统可能需要服务几百个可用的 GPIO，但是对于任何一个
-给定的电路板通常只有一些被使用。另一个目的是捕获冲突，查明错误:如两个或
-更多驱动错误地认为他们已经独占了某个信号线,或是错误地认为移除一个管理着
-某个已激活信号的驱动是安全的。也就是说，申请 GPIO 的作用类似一种锁机制。
-
-某些平台可能也使用 GPIO 作为电源管理激活信号(例如通过关闭未使用芯片区和
-简单地关闭未使用时钟)。
-
-对于 GPIO 使用 pinctrl 子系统已知的引脚，子系统应该被告知其使用情况；
-一个 gpiolib 驱动的 .request()操作应调用 pinctrl_request_gpio()，
-而 gpiolib 驱动的 .free()操作应调用 pinctrl_free_gpio()。pinctrl
-子系统允许 pinctrl_request_gpio()在某个引脚或引脚组以复用形式“属于”
-一个设备时都成功返回。
-
-任何须将 GPIO 信号导向适当引脚的引脚复用硬件的编程应该发生在 GPIO
-驱动的 .direction_input()或 .direction_output()函数中，以及
-任何输出 GPIO 值的设置之后。这样可使从引脚特殊功能到 GPIO 的转换
-不会在引脚产生毛刺波形。有时当用一个 GPIO 实现其信号驱动一个非 GPIO
-硬件模块的解决方案时，就需要这种机制。
-
-某些平台允许部分或所有 GPIO 信号使用不同的引脚。类似的，GPIO 或引脚的
-其他方面也需要配置，如上拉/下拉。平台软件应该在对这些 GPIO 调用
-gpio_request()前将这类细节配置好，例如使用 pinctrl 子系统的映射表，
-使得 GPIO 的用户无须关注这些细节。
-
-还有一个值得注意的是在释放 GPIO 前，你必须停止使用它。
-
-
-注意:申请一个 GPIO 并没有以任何方式配置它，只不过标识那个 GPIO 处于使用
-状态。必须有另外的代码来处理引脚配置(如控制 GPIO 使用的引脚、上拉/下拉)。
-考虑到大多数情况下声明 GPIO 之后就会立即配置它们,所以定义了以下三个辅助函数:
-
-	/* 申请一个 GPIO 信号, 同时通过特定的'flags'初始化配置,
-	 * 其他和 gpio_request()的参数和返回值相同
-	 *
-	 */
-	int gpio_request_one(unsigned gpio, unsigned long flags, const char *label);
-
-	/* 在单个函数中申请多个 GPIO
-	 */
-	int gpio_request_array(struct gpio *array, size_t num);
-
-	/* 在单个函数中释放多个 GPIO
-	 */
-	void gpio_free_array(struct gpio *array, size_t num);
-
-这里 'flags' 当前定义可指定以下属性:
-
-	* GPIOF_DIR_IN		- 配置方向为输入
-	* GPIOF_DIR_OUT		- 配置方向为输出
-
-	* GPIOF_INIT_LOW	- 在作为输出时,初始值为低电平
-	* GPIOF_INIT_HIGH	- 在作为输出时,初始值为高电平
-	* GPIOF_OPEN_DRAIN	- gpio引脚为开漏信号
-	* GPIOF_OPEN_SOURCE	- gpio引脚为源极开路信号
-
-	* GPIOF_EXPORT_DIR_FIXED	- 将 gpio 导出到 sysfs，并保持方向
-	* GPIOF_EXPORT_DIR_CHANGEABLE	- 同样是导出, 但允许改变方向
-
-因为 GPIOF_INIT_* 仅有在配置为输出的时候才存在,所以有效的组合为:
-
-	* GPIOF_IN		- 配置为输入
-	* GPIOF_OUT_INIT_LOW	- 配置为输出,并初始化为低电平
-	* GPIOF_OUT_INIT_HIGH	- 配置为输出,并初始化为高电平
-
-当设置 flag 为 GPIOF_OPEN_DRAIN 时，则假设引脚是开漏信号。这样的引脚
-将不会在输出模式下置1。这样的引脚需要连接上拉电阻。通过使能这个标志，gpio库
-将会在被要求输出模式下置1时将引脚变为输入状态来使引脚置高。引脚在输出模式下
-通过置0使其输出低电平。
-
-当设置 flag 为 GPIOF_OPEN_SOURCE 时，则假设引脚为源极开路信号。这样的引脚
-将不会在输出模式下置0。这样的引脚需要连接下拉电阻。通过使能这个标志，gpio库
-将会在被要求输出模式下置0时将引脚变为输入状态来使引脚置低。引脚在输出模式下
-通过置1使其输出高电平。
-
-将来这些标志可能扩展到支持更多的属性。
-
-更进一步,为了更简单地声明/释放多个 GPIO,'struct gpio'被引进来封装所有
-这三个领域:
-
-	struct gpio {
-		unsigned	gpio;
-		unsigned long	flags;
-		const char	*label;
-	};
-
-一个典型的用例:
-
-	static struct gpio leds_gpios[] = {
-		{ 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* 默认开启 */
-		{ 33, GPIOF_OUT_INIT_LOW,  "Green LED" }, /* 默认关闭 */
-		{ 34, GPIOF_OUT_INIT_LOW,  "Red LED"   }, /* 默认关闭 */
-		{ 35, GPIOF_OUT_INIT_LOW,  "Blue LED"  }, /* 默认关闭 */
-		{ ... },
-	};
-
-	err = gpio_request_one(31, GPIOF_IN, "Reset Button");
-	if (err)
-		...
-
-	err = gpio_request_array(leds_gpios, ARRAY_SIZE(leds_gpios));
-	if (err)
-		...
-
-	gpio_free_array(leds_gpios, ARRAY_SIZE(leds_gpios));
-
-
-GPIO 映射到 IRQ
---------------------
-GPIO 编号是无符号整数;IRQ 编号也是。这些构成了两个逻辑上不同的命名空间
-(GPIO 0 不一定使用 IRQ 0)。你可以通过以下函数在它们之间实现映射:
-
-	/* 映射 GPIO 编号到 IRQ 编号 */
-	int gpio_to_irq(unsigned gpio);
-
-	/* 映射 IRQ 编号到 GPIO 编号 (尽量避免使用) */
-	int irq_to_gpio(unsigned irq);
-
-它们的返回值为对应命名空间的相关编号，或是负的错误代码(如果无法映射)。
-(例如,某些 GPIO 无法做为 IRQ 使用。)以下的编号错误是未经检测的:使用一个
-未通过 gpio_direction_input()配置为输入的 GPIO 编号，或者使用一个
-并非来源于gpio_to_irq()的 IRQ 编号。
-
-这两个映射函数可能会在信号编号的加减计算过程上花些时间。它们不可休眠。
-
-gpio_to_irq()返回的非错误值可以传递给 request_irq()或者 free_irq()。
-它们通常通过板级特定的初始化代码存放到平台设备的 IRQ 资源中。注意:IRQ
-触发选项是 IRQ 接口的一部分，如 IRQF_TRIGGER_FALLING，系统唤醒能力
-也是如此。
-
-irq_to_gpio()返回的非错误值大多数通常可以被 gpio_get_value()所使用，
-比如在 IRQ 是沿触发时初始化或更新驱动状态。注意某些平台不支持反映射,所以
-你应该尽量避免使用它。
-
-
-模拟开漏信号
-----------------------------
-有时在只有低电平信号作为实际驱动结果(译者注:多个输出连接于一点，逻辑电平
-结果为所有输出的逻辑与)的时候,共享的信号线需要使用“开漏”信号。(该术语
-适用于 CMOS 管；而 TTL 用“集电极开路”。)一个上拉电阻使信号为高电平。这
-有时被称为“线与”。实际上，从负逻辑(低电平为真)的角度来看，这是一个“线或”。
-
-一个开漏信号的常见例子是共享的低电平使能 IRQ 信号线。此外,有时双向数据总线
-信号也使用漏极开路信号。
-
-某些 GPIO 控制器直接支持开漏输出，还有许多不支持。当你需要开漏信号，但
-硬件又不直接支持的时候，一个常用的方法是用任何即可作输入也可作输出的 GPIO
-引脚来模拟:
-
- LOW:	gpio_direction_output(gpio, 0) ... 这代码驱动信号并覆盖
-	上拉配置。
-
- HIGH:	gpio_direction_input(gpio) ... 这代码关闭输出,所以上拉电阻
-	(或其他的一些器件)控制了信号。
-
-如果你将信号线“驱动”为高电平，但是 gpio_get_value(gpio)报告了一个
-低电平(在适当的上升时间后)，你就可以知道是其他的一些组件将共享信号线拉低了。
-这不一定是错误的。一个常见的例子就是 I2C 时钟的延长：一个需要较慢时钟的
-从设备延迟 SCK 的上升沿，而 I2C 主设备相应地调整其信号传输速率。
-
-
-这些公约忽略了什么?
-================
-这些公约忽略的最大一件事就是引脚复用，因为这属于高度芯片特定的属性且
-没有可移植性。某个平台可能不需要明确的复用信息；有的对于任意给定的引脚
-可能只有两个功能选项；有的可能每个引脚有八个功能选项；有的可能可以将
-几个引脚中的任何一个作为给定的 GPIO。(是的，这些例子都来自于当前运行
-Linux 的系统。)
-
-在某些系统中,与引脚复用相关的是配置和使能集成的上、下拉模式。并不是所有
-平台都支持这种模式,或者不会以相同的方式来支持这种模式；且任何给定的电路板
-可能使用外置的上拉(或下拉)电阻,这时芯片上的就不应该使用。(当一个电路需要
-5kOhm 的拉动电阻,芯片上的 100 kOhm 电阻就不能做到。)同样的，驱动能力
-(2 mA vs 20 mA)和电压(1.8V vs 3.3V)是平台特定问题,就像模型一样在
-可配置引脚和 GPIO 之间(没)有一一对应的关系。
-
-还有其他一些系统特定的机制没有在这里指出，例如上述的输入去毛刺和线与输出
-选项。硬件可能支持批量读或写 GPIO，但是那一般是配置相关的：对于处于同一
-块区(bank)的GPIO。(GPIO 通常以 16 或 32 个组成一个区块，一个给定的
-片上系统一般有几个这样的区块。)某些系统可以通过输出 GPIO 触发 IRQ，
-或者从并非以 GPIO 管理的引脚取值。这些机制的相关代码没有必要具有可移植性。
-
-当前，动态定义 GPIO 并不是标准的，例如作为配置一个带有某些 GPIO 扩展器的
-附加电路板的副作用。
-
-GPIO 实现者的框架 (可选)
-=====================
-前面提到了，有一个可选的实现框架，让平台使用相同的编程接口，更加简单地支持
-不同种类的 GPIO 控制器。这个框架称为"gpiolib"。
-
-作为一个辅助调试功能，如果 debugfs 可用，就会有一个 /sys/kernel/debug/gpio
-文件。通过这个框架，它可以列出所有注册的控制器,以及当前正在使用中的 GPIO
-的状态。
-
-
-控制器驱动: gpio_chip
--------------------
-在框架中每个 GPIO 控制器都包装为一个 "struct gpio_chip"，他包含了
-该类型的每个控制器的常用信息:
-
- - 设置 GPIO 方向的方法
- - 用于访问 GPIO 值的方法
- - 告知调用其方法是否可能休眠的标志
- - 可选的 debugfs 信息导出方法 (显示类似上拉配置一样的额外状态)
- - 诊断标签
-
-也包含了来自 device.platform_data 的每个实例的数据：它第一个 GPIO 的
-编号和它可用的 GPIO 的数量。
-
-实现 gpio_chip 的代码应支持多控制器实例，这可能使用驱动模型。那些代码要
-配置每个 gpio_chip，并发起gpiochip_add()。卸载一个 GPIO 控制器很少见，
-但在必要的时候可以使用 gpiochip_remove()。
-
-大部分 gpio_chip 是一个实例特定结构体的一部分，而并不将 GPIO 接口单独
-暴露出来,比如编址、电源管理等。类似编解码器这样的芯片会有复杂的非 GPIO
-状态。
-
-任何一个 debugfs 信息导出方法通常应该忽略还未申请作为 GPIO 的信号线。
-他们可以使用 gpiochip_is_requested()测试，当这个 GPIO 已经申请过了
-就返回相关的标签，否则返回 NULL。
-
-
-平台支持
--------
-为了支持这个框架，一个平台的 Kconfig 文件将会 "select"(选择)
-ARCH_REQUIRE_GPIOLIB 或 ARCH_WANT_OPTIONAL_GPIOLIB，并让它的
- 包含 ，同时定义三个方法:
-gpio_get_value()、gpio_set_value()和 gpio_cansleep()。
-
-它也应提供一个 ARCH_NR_GPIOS 的定义值，这样可以更好地反映该平台 GPIO
-的实际数量,节省静态表的空间。(这个定义值应该包含片上系统内建 GPIO 和
-GPIO 扩展器中的数据。)
-
-ARCH_REQUIRE_GPIOLIB 意味着 gpiolib 核心在这个构架中将总是编译进内核。
-
-ARCH_WANT_OPTIONAL_GPIOLIB 意味着 gpiolib 核心默认关闭,且用户可以
-使能它,并将其编译进内核(可选)。
-
-如果这些选项都没被选择,该平台就不通过 GPIO-lib 支持 GPIO,且代码不可以
-被用户使能。
-
-以下这些方法的实现可以直接使用框架代码,并总是通过 gpio_chip 调度:
-
-  #define gpio_get_value	__gpio_get_value
-  #define gpio_set_value	__gpio_set_value
-  #define gpio_cansleep		__gpio_cansleep
-
-这些定义可以用更理想的实现方法替代，那就是使用经过逻辑优化的内联函数来访问
-基于特定片上系统的 GPIO。例如,若引用的 GPIO (寄存器位偏移)是常量“12”，
-读取或设置它可能只需少则两或三个指令，且不会休眠。当这样的优化无法实现时，
-那些函数必须使用框架提供的代码，那就至少要几十条指令才可以实现。对于用 GPIO
-模拟的 I/O 接口, 如此精简指令是很有意义的。
-
-对于片上系统，平台特定代码为片上 GPIO 每个区(bank)定义并注册 gpio_chip
-实例。那些 GPIO 应该根据芯片厂商的文档进行编码/标签,并直接和电路板原理图
-对应。他们应该开始于零并终止于平台特定的限制。这些 GPIO(代码)通常从
-arch_initcall()或者更早的地方集成进平台初始化代码，使这些 GPIO 总是可用，
-且他们通常可以作为 IRQ 使用。
-
-板级支持
--------
-对于外部 GPIO 控制器(例如 I2C 或 SPI 扩展器、专用芯片、多功能器件、FPGA
-或 CPLD)，大多数常用板级特定代码都可以注册控制器设备，并保证他们的驱动知道
-gpiochip_add()所使用的 GPIO 编号。他们的起始编号通常跟在平台特定的 GPIO
-编号之后。
-
-例如板级启动代码应该创建结构体指明芯片公开的 GPIO 范围，并使用 platform_data
-将其传递给每个 GPIO 扩展器芯片。然后芯片驱动中的 probe()例程可以将这个
-数据传递给 gpiochip_add()。
-
-初始化顺序很重要。例如，如果一个设备依赖基于 I2C 的(扩展)GPIO，那么它的
-probe()例程就应该在那个 GPIO 有效以后才可以被调用。这意味着设备应该在
-GPIO 可以工作之后才可被注册。解决这类依赖的的一种方法是让这种 gpio_chip
-控制器向板级特定代码提供 setup()和 teardown()回调函数。一旦所有必须的
-资源可用之后，这些板级特定的回调函数将会注册设备，并可以在这些 GPIO 控制器
-设备变成无效时移除它们。
-
-
-用户空间的 Sysfs 接口(可选)
-========================
-使用“gpiolib”实现框架的平台可以选择配置一个 GPIO 的 sysfs 用户接口。
-这不同于 debugfs 接口，因为它提供的是对 GPIO方向和值的控制，而不只显示
-一个GPIO 的状态摘要。此外,它可以出现在没有调试支持的产品级系统中。
-
-例如，通过适当的系统硬件文档，用户空间可以知道 GIOP #23 控制 Flash
-存储器的写保护(用于保护其中 Bootloader 分区)。产品的系统升级可能需要
-临时解除这个保护：首先导入一个 GPIO，改变其输出状态，然后在重新使能写保护
-前升级代码。通常情况下,GPIO #23 是不会被触及的，并且内核也不需要知道他。
-
-根据适当的硬件文档，某些系统的用户空间 GPIO 可以用于确定系统配置数据，
-这些数据是标准内核不知道的。在某些任务中，简单的用户空间 GPIO 驱动可能是
-系统真正需要的。
-
-注意：标准内核驱动中已经存在通用的“LED 和按键”GPIO 任务，分别是:
-"leds-gpio" 和 "gpio_keys"。请使用这些来替代直接访问 GPIO，因为集成在
-内核框架中的这类驱动比你在用户空间的代码更好。
-
-
-Sysfs 中的路径
---------------
-在/sys/class/gpio 中有 3 类入口:
-
-   -	用于在用户空间控制 GPIO 的控制接口;
-
-   -	GPIOs 本身;以及
-
-   -	GPIO 控制器 ("gpio_chip" 实例)。
-
-除了这些标准的文件,还包含“device”符号链接。
-
-控制接口是只写的:
-
-    /sys/class/gpio/
-
-    	"export" ... 用户空间可以通过写其编号到这个文件，要求内核导出
-		一个 GPIO 的控制到用户空间。
-
-		例如: 如果内核代码没有申请 GPIO #19,"echo 19 > export"
-		将会为 GPIO #19 创建一个 "gpio19" 节点。
-
-    	"unexport" ... 导出到用户空间的逆操作。
-
-		例如: "echo 19 > unexport" 将会移除使用"export"文件导出的
-		"gpio19" 节点。
-
-GPIO 信号的路径类似 /sys/class/gpio/gpio42/ (对于 GPIO #42 来说)，
-并有如下的读/写属性:
-
-    /sys/class/gpio/gpioN/
-
-	"direction" ... 读取得到 "in" 或 "out"。这个值通常运行写入。
-		写入"out" 时,其引脚的默认输出为低电平。为了确保无故障运行，
-		"low" 或 "high" 的电平值应该写入 GPIO 的配置，作为初始输出值。
-
-		注意:如果内核不支持改变 GPIO 的方向，或者在导出时内核代码没有
-		明确允许用户空间可以重新配置 GPIO 方向，那么这个属性将不存在。
-
-	"value" ... 读取得到 0 (低电平) 或 1 (高电平)。如果 GPIO 配置为
-		输出,这个值允许写操作。任何非零值都以高电平看待。
-
-		如果引脚可以配置为中断信号，且如果已经配置了产生中断的模式
-		（见"edge"的描述），你可以对这个文件使用轮询操作(poll(2))，
-		且轮询操作会在任何中断触发时返回。如果你使用轮询操作(poll(2))，
-		请在 events 中设置 POLLPRI 和 POLLERR。如果你使用轮询操作
-		(select(2))，请在 exceptfds 设置你期望的文件描述符。在
-		轮询操作(poll(2))返回之后，既可以通过 lseek(2)操作读取
-		sysfs 文件的开始部分，也可以关闭这个文件并重新打开它来读取数据。
-
-	"edge" ... 读取得到“none”、“rising”、“falling”或者“both”。
-		将这些字符串写入这个文件可以选择沿触发模式，会使得轮询操作
-		(select(2))在"value"文件中返回。
-
-		这个文件仅有在这个引脚可以配置为可产生中断输入引脚时，才存在。
-
-	"active_low" ... 读取得到 0 (假) 或 1 (真)。写入任何非零值可以
-		翻转这个属性的(读写)值。已存在或之后通过"edge"属性设置了"rising"
-		和 "falling" 沿触发模式的轮询操作(poll(2))将会遵循这个设置。
-
-GPIO 控制器的路径类似 /sys/class/gpio/gpiochip42/ (对于从#42 GPIO
-开始实现控制的控制器),并有着以下只读属性:
-
-    /sys/class/gpio/gpiochipN/
-
-    	"base" ... 与以上的 N 相同,代表此芯片管理的第一个 GPIO 的编号
-
-    	"label" ... 用于诊断 (并不总是只有唯一值)
-
-    	"ngpio" ... 此控制器所管理的 GPIO 数量(而 GPIO 编号从 N 到
-    		N + ngpio - 1)
-
-大多数情况下,电路板的文档应当标明每个 GPIO 的使用目的。但是那些编号并不总是
-固定的,例如在扩展卡上的 GPIO会根据所使用的主板或所在堆叠架构中其他的板子而
-有所不同。在这种情况下,你可能需要使用 gpiochip 节点(尽可能地结合电路图)来
-确定给定信号所用的 GPIO 编号。
-
-
-从内核代码中导出
--------------
-内核代码可以明确地管理那些已通过 gpio_request()申请的 GPIO 的导出:
-
-	/* 导出 GPIO 到用户空间 */
-	int gpio_export(unsigned gpio, bool direction_may_change);
-
-	/* gpio_export()的逆操作 */
-	void gpio_unexport();
-
-	/* 创建一个 sysfs 连接到已导出的 GPIO 节点 */
-	int gpio_export_link(struct device *dev, const char *name,
-		unsigned gpio)
-
-在一个内核驱动申请一个 GPIO 之后，它可以通过 gpio_export()使其在 sysfs
-接口中可见。该驱动可以控制信号方向是否可修改。这有助于防止用户空间代码无意间
-破坏重要的系统状态。
-
-这个明确的导出有助于(通过使某些实验更容易来)调试，也可以提供一个始终存在的接口，
-与文档配合作为板级支持包的一部分。
-
-在 GPIO 被导出之后，gpio_export_link()允许在 sysfs 文件系统的任何地方
-创建一个到这个 GPIO sysfs 节点的符号链接。这样驱动就可以通过一个描述性的
-名字，在 sysfs 中他们所拥有的设备下提供一个(到这个 GPIO sysfs 节点的)接口。
diff --git a/Documentation/zh_CN/io_ordering.txt b/Documentation/zh_CN/io_ordering.txt
deleted file mode 100644
index e592daf4e014..000000000000
--- a/Documentation/zh_CN/io_ordering.txt
+++ /dev/null
@@ -1,67 +0,0 @@
-Chinese translated version of Documentation/io_orderings.txt
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Chinese maintainer: Lin Yongting 
----------------------------------------------------------------------
-Documentation/io_ordering.txt 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-
-中文版维护者： 林永听 Lin Yongting 
-中文版翻译者： 林永听 Lin Yongting 
-中文版校译者： 林永听 Lin Yongting 
-
-
-以下为正文
----------------------------------------------------------------------
-
-在某些平台上，所谓的内存映射I/O是弱顺序。在这些平台上，驱动开发者有责任
-保证I/O内存映射地址的写操作按程序图意的顺序达到设备。通常读取一个“安全”
-设备寄存器或桥寄存器，触发IO芯片清刷未处理的写操作到达设备后才处理读操作，
-而达到保证目的。驱动程序通常在spinlock保护的临界区退出之前使用这种技术。
-这也可以保证后面的写操作只在前面的写操作之后到达设备（这非常类似于内存
-屏障操作，mb()，不过仅适用于I/O）。
-
-假设一个设备驱动程的具体例子：
-
-        ...
-CPU A:  spin_lock_irqsave(&dev_lock, flags)
-CPU A:  val = readl(my_status);
-CPU A:  ...
-CPU A:  writel(newval, ring_ptr);
-CPU A:  spin_unlock_irqrestore(&dev_lock, flags)
-        ...
-CPU B:  spin_lock_irqsave(&dev_lock, flags)
-CPU B:  val = readl(my_status);
-CPU B:  ...
-CPU B:  writel(newval2, ring_ptr);
-CPU B:  spin_unlock_irqrestore(&dev_lock, flags)
-        ...
-
-上述例子中，设备可能会先接收到newval2的值，然后接收到newval的值，问题就
-发生了。不过很容易通过下面方法来修复：
-
-        ...
-CPU A:  spin_lock_irqsave(&dev_lock, flags)
-CPU A:  val = readl(my_status);
-CPU A:  ...
-CPU A:  writel(newval, ring_ptr);
-CPU A:  (void)readl(safe_register); /* 配置寄存器？*/
-CPU A:  spin_unlock_irqrestore(&dev_lock, flags)
-        ...
-CPU B:  spin_lock_irqsave(&dev_lock, flags)
-CPU B:  val = readl(my_status);
-CPU B:  ...
-CPU B:  writel(newval2, ring_ptr);
-CPU B:  (void)readl(safe_register); /* 配置寄存器？*/
-CPU B:  spin_unlock_irqrestore(&dev_lock, flags)
-
-在解决方案中，读取safe_register寄存器，触发IO芯片清刷未处理的写操作，
-再处理后面的读操作，防止引发数据不一致问题。
diff --git a/Documentation/zh_CN/magic-number.txt b/Documentation/zh_CN/magic-number.txt
deleted file mode 100644
index e9db693c0a23..000000000000
--- a/Documentation/zh_CN/magic-number.txt
+++ /dev/null
@@ -1,153 +0,0 @@
-Chinese translated version of Documentation/magic-number.txt
-
-If you have any comment or update to the content, please post to LKML directly.
-However, if you have problem communicating in English you can also ask the
-Chinese maintainer for help.  Contact the Chinese maintainer, if this
-translation is outdated or there is problem with translation.
-
-Chinese maintainer: Jia Wei Wei 
----------------------------------------------------------------------
-Documentation/magic-number.txt的中文翻译
-
-如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可
-以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。
-
-中文版维护者： 贾威威 Jia Wei Wei 
-中文版翻译者： 贾威威 Jia Wei Wei 
-中文版校译者： 贾威威 Jia Wei Wei 
-
-以下为正文
----------------------------------------------------------------------
-这个文件是有关当前使用的魔术值注册表。当你给一个结构添加了一个魔术值，你也应该把这个魔术值添加到这个文件，因为我们最好把用于各种结构的魔术值统一起来。
-
-使用魔术值来保护内核数据结构是一个非常好的主意。这就允许你在运行期检查(a)一个结构是否已经被攻击，或者(b)你已经给一个例行程序通过了一个错误的结构。后一种情况特别地有用---特别是当你通过一个空指针指向结构体的时候。tty源码，例如，经常通过特定驱动使用这种方法并且反复地排列特定方面的结构。
-
-使用魔术值的方法是在结构的开始处声明的，如下：
-
-struct tty_ldisc {
-	int	magic;
-	...
-};
-
-当你以后给内核添加增强功能的时候，请遵守这条规则！这样就会节省数不清的调试时间，特别是一些古怪的情况，例如，数组超出范围并且重新写了超出部分。遵守这个规则，‪这些情况可以被快速地，安全地避免。
-
-		Theodore Ts'o
-		  31 Mar 94
-
-给当前的Linux 2.1.55添加魔术表。
-
-		Michael Chastain
-		
-		22 Sep 1997
-
-现在应该最新的Linux 2.1.112.因为在特性冻结期间，不能在2.2.x前改变任何东西。这些条目被数域所排序。
-
-		Krzysztof G.Baranowski
-	        
-		29 Jul 1998
-
-更新魔术表到Linux 2.5.45。刚好越过特性冻结，但是有可能还会有一些新的魔术值在2.6.x之前融入到内核中。
-
-		Petr Baudis
-		
-		03 Nov 2002
-
-更新魔术表到Linux 2.5.74。
-
-		Fabian Frederick
-                
-		09 Jul 2003
-
-魔术名                 地址         结构               所在文件
-===========================================================================
-PG_MAGIC              'P'         pg_{read,write}_hdr include/linux/pg.h
-CMAGIC                0x0111      user              include/linux/a.out.h
-MKISS_DRIVER_MAGIC    0x04bf      mkiss_channel     drivers/net/mkiss.h
-HDLC_MAGIC            0x239e      n_hdlc            drivers/char/n_hdlc.c
-APM_BIOS_MAGIC        0x4101      apm_user          arch/x86/kernel/apm_32.c
-CYCLADES_MAGIC        0x4359      cyclades_port     include/linux/cyclades.h
-DB_MAGIC              0x4442      fc_info           drivers/net/iph5526_novram.c
-DL_MAGIC              0x444d      fc_info           drivers/net/iph5526_novram.c
-FASYNC_MAGIC          0x4601      fasync_struct     include/linux/fs.h
-FF_MAGIC              0x4646      fc_info           drivers/net/iph5526_novram.c
-ISICOM_MAGIC          0x4d54      isi_port          include/linux/isicom.h
-PTY_MAGIC             0x5001                        drivers/char/pty.c
-PPP_MAGIC             0x5002      ppp               include/linux/if_pppvar.h
-SERIAL_MAGIC          0x5301      async_struct      include/linux/serial.h
-SSTATE_MAGIC          0x5302      serial_state      include/linux/serial.h
-SLIP_MAGIC            0x5302      slip              drivers/net/slip.h
-STRIP_MAGIC           0x5303      strip             drivers/net/strip.c
-X25_ASY_MAGIC         0x5303      x25_asy           drivers/net/x25_asy.h
-SIXPACK_MAGIC         0x5304      sixpack           drivers/net/hamradio/6pack.h
-AX25_MAGIC            0x5316      ax_disp           drivers/net/mkiss.h
-TTY_MAGIC             0x5401      tty_struct        include/linux/tty.h
-MGSL_MAGIC            0x5401      mgsl_info         drivers/char/synclink.c
-TTY_DRIVER_MAGIC      0x5402      tty_driver        include/linux/tty_driver.h
-MGSLPC_MAGIC          0x5402      mgslpc_info       drivers/char/pcmcia/synclink_cs.c
-TTY_LDISC_MAGIC       0x5403      tty_ldisc         include/linux/tty_ldisc.h
-USB_SERIAL_MAGIC      0x6702      usb_serial        drivers/usb/serial/usb-serial.h
-FULL_DUPLEX_MAGIC     0x6969                        drivers/net/ethernet/dec/tulip/de2104x.c
-USB_BLUETOOTH_MAGIC   0x6d02      usb_bluetooth     drivers/usb/class/bluetty.c
-RFCOMM_TTY_MAGIC      0x6d02                        net/bluetooth/rfcomm/tty.c
-USB_SERIAL_PORT_MAGIC 0x7301      usb_serial_port   drivers/usb/serial/usb-serial.h
-CG_MAGIC              0x00090255  ufs_cylinder_group include/linux/ufs_fs.h
-RPORT_MAGIC           0x00525001  r_port            drivers/char/rocket_int.h
-LSEMAGIC              0x05091998  lse               drivers/fc4/fc.c
-GDTIOCTL_MAGIC        0x06030f07  gdth_iowr_str     drivers/scsi/gdth_ioctl.h
-RIEBL_MAGIC           0x09051990                    drivers/net/atarilance.c
-NBD_REQUEST_MAGIC     0x12560953  nbd_request       include/linux/nbd.h
-RED_MAGIC2            0x170fc2a5  (any)             mm/slab.c
-BAYCOM_MAGIC          0x19730510  baycom_state      drivers/net/baycom_epp.c
-ISDN_X25IFACE_MAGIC   0x1e75a2b9  isdn_x25iface_proto_data
-                                                    drivers/isdn/isdn_x25iface.h
-ECP_MAGIC             0x21504345  cdkecpsig         include/linux/cdk.h
-LSOMAGIC              0x27091997  lso               drivers/fc4/fc.c
-LSMAGIC               0x2a3b4d2a  ls                drivers/fc4/fc.c
-WANPIPE_MAGIC         0x414C4453  sdla_{dump,exec}  include/linux/wanpipe.h
-CS_CARD_MAGIC         0x43525553  cs_card           sound/oss/cs46xx.c
-LABELCL_MAGIC         0x4857434c  labelcl_info_s    include/asm/ia64/sn/labelcl.h
-ISDN_ASYNC_MAGIC      0x49344C01  modem_info        include/linux/isdn.h
-CTC_ASYNC_MAGIC       0x49344C01  ctc_tty_info      drivers/s390/net/ctctty.c
-ISDN_NET_MAGIC        0x49344C02  isdn_net_local_s  drivers/isdn/i4l/isdn_net_lib.h
-SAVEKMSG_MAGIC2       0x4B4D5347  savekmsg          arch/*/amiga/config.c
-CS_STATE_MAGIC        0x4c4f4749  cs_state          sound/oss/cs46xx.c
-SLAB_C_MAGIC          0x4f17a36d  kmem_cache        mm/slab.c
-COW_MAGIC             0x4f4f4f4d  cow_header_v1     arch/um/drivers/ubd_user.c
-I810_CARD_MAGIC       0x5072696E  i810_card         sound/oss/i810_audio.c
-TRIDENT_CARD_MAGIC    0x5072696E  trident_card      sound/oss/trident.c
-ROUTER_MAGIC          0x524d4157  wan_device        [in wanrouter.h pre 3.9]
-SAVEKMSG_MAGIC1       0x53415645  savekmsg          arch/*/amiga/config.c
-GDA_MAGIC             0x58464552  gda               arch/mips/include/asm/sn/gda.h
-RED_MAGIC1            0x5a2cf071  (any)             mm/slab.c
-EEPROM_MAGIC_VALUE    0x5ab478d2  lanai_dev         drivers/atm/lanai.c
-HDLCDRV_MAGIC         0x5ac6e778  hdlcdrv_state     include/linux/hdlcdrv.h
-PCXX_MAGIC            0x5c6df104  channel           drivers/char/pcxx.h
-KV_MAGIC              0x5f4b565f  kernel_vars_s     arch/mips/include/asm/sn/klkernvars.h
-I810_STATE_MAGIC      0x63657373  i810_state        sound/oss/i810_audio.c
-TRIDENT_STATE_MAGIC   0x63657373  trient_state      sound/oss/trident.c
-M3_CARD_MAGIC         0x646e6f50  m3_card           sound/oss/maestro3.c
-FW_HEADER_MAGIC       0x65726F66  fw_header         drivers/atm/fore200e.h
-SLOT_MAGIC            0x67267321  slot              drivers/hotplug/cpqphp.h
-SLOT_MAGIC            0x67267322  slot              drivers/hotplug/acpiphp.h
-LO_MAGIC              0x68797548  nbd_device        include/linux/nbd.h
-OPROFILE_MAGIC        0x6f70726f  super_block       drivers/oprofile/oprofilefs.h
-M3_STATE_MAGIC        0x734d724d  m3_state          sound/oss/maestro3.c
-VMALLOC_MAGIC         0x87654320  snd_alloc_track   sound/core/memory.c
-KMALLOC_MAGIC         0x87654321  snd_alloc_track   sound/core/memory.c
-PWC_MAGIC             0x89DC10AB  pwc_device        drivers/usb/media/pwc.h
-NBD_REPLY_MAGIC       0x96744668  nbd_reply         include/linux/nbd.h
-ENI155_MAGIC          0xa54b872d  midway_eprom	    drivers/atm/eni.h
-CODA_MAGIC            0xC0DAC0DA  coda_file_info    include/linux/coda_fs_i.h
-DPMEM_MAGIC           0xc0ffee11  gdt_pci_sram      drivers/scsi/gdth.h
-YAM_MAGIC             0xF10A7654  yam_port          drivers/net/hamradio/yam.c
-CCB_MAGIC             0xf2691ad2  ccb               drivers/scsi/ncr53c8xx.c
-QUEUE_MAGIC_FREE      0xf7e1c9a3  queue_entry       drivers/scsi/arm/queue.c
-QUEUE_MAGIC_USED      0xf7e1cc33  queue_entry       drivers/scsi/arm/queue.c
-HTB_CMAGIC            0xFEFAFEF1  htb_class         net/sched/sch_htb.c
-NMI_MAGIC             0x48414d4d455201 nmi_s        arch/mips/include/asm/sn/nmi.h
-
-请注意，在声音记忆管理中仍然有一些特殊的为每个驱动定义的魔术值。查看include/sound/sndmagic.h来获取他们完整的列表信息。很多OSS声音驱动拥有自己从声卡PCI ID构建的魔术值-他们也没有被列在这里。
-
-IrDA子系统也使用了大量的自己的魔术值，查看include/net/irda/irda.h来获取他们完整的信息。
-
-HFS是另外一个比较大的使用魔术值的文件系统-你可以在fs/hfs/hfs.h中找到他们。
diff --git a/Documentation/zh_CN/oops-tracing.txt b/Documentation/zh_CN/oops-tracing.txt
deleted file mode 100644
index 41ab53cc0e83..000000000000
--- a/Documentation/zh_CN/oops-tracing.txt
+++ /dev/null
@@ -1,212 +0,0 @@
-Chinese translated version of Documentation/admin-guide/oops-tracing.rst
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Chinese maintainer: Dave Young 
----------------------------------------------------------------------
-Documentation/admin-guide/oops-tracing.rst 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-
-中文版维护者： 杨瑞 Dave Young 
-中文版翻译者： 杨瑞 Dave Young 
-中文版校译者： 李阳 Li Yang 
-               王聪 Wang Cong 
-
-以下为正文
----------------------------------------------------------------------
-
-注意： ksymoops 在2.6中是没有用的。 请以原有格式使用Oops(来自dmesg，等等)。
-忽略任何这样那样关于“解码Oops”或者“通过ksymoops运行”的文档。 如果你贴出运行过
-ksymoops的来自2.6的Oops，人们只会让你重贴一次。
-
-快速总结
--------------
-
-发现Oops并发送给看似相关的内核领域的维护者。别太担心对不上号。如果你不确定就发给
-和你所做的事情相关的代码的负责人。 如果可重现试着描述怎样重构。 那甚至比oops更有
-价值。
-
-如果你对于发送给谁一无所知， 发给linux-kernel@vger.kernel.org。感谢你帮助Linux
-尽可能地稳定。
-
-Oops在哪里?
-----------------------
-
-通常Oops文本由klogd从内核缓冲区里读取并传给syslogd，由syslogd写到syslog文件中，
-典型地是/var/log/messages(依赖于/etc/syslog.conf)。有时klogd崩溃了,这种情况下你
-能够运行dmesg > file来从内核缓冲区中读取数据并保存下来。 否则你可以
-cat /proc/kmsg > file， 然而你必须介入中止传输， kmsg是一个“永不结束的文件”。如
-果机器崩溃坏到你不能输入命令或者磁盘不可用那么你有三种选择:-
-
-（1） 手抄屏幕上的文本待机器重启后再输入计算机。 麻烦但如果没有针对崩溃的准备，
-这是仅有的选择。 另外，你可以用数码相机把屏幕拍下来-不太好，但比没有强。 如果信
-息滚动到了终端的上面，你会发现以高分辩率启动（比如，vga=791）会让你读到更多的文
-本。（注意：这需要vesafb，所以对‘早期’的oops没有帮助）
-
-（2）用串口终端启动（请参看Documentation/admin-guide/serial-console.rst），运行一个null
-modem到另一台机器并用你喜欢的通讯工具获取输出。Minicom工作地很好。
-
-（3）使用Kdump（请参看Documentation/kdump/kdump.txt），
-使用在Documentation/kdump/gdbmacros.txt中定义的dmesg gdb宏，从旧的内存中提取内核
-环形缓冲区。
-
-完整信息
-----------------
-
-注意：以下来自于Linus的邮件适用于2.4内核。 我因为历史原因保留了它，并且因为其中
-一些信息仍然适用。 特别注意的是，请忽略任何ksymoops的引用。
-
-From: Linus Torvalds 
-
-怎样跟踪Oops.. [原发到linux-kernel的一封邮件]
-
-主要的窍门是有五年和这些烦人的oops消息打交道的经验;-)
-
-实际上，你有办法使它更简单。我有两个不同的方法：
-
-	gdb /usr/src/linux/vmlinux
-	gdb> disassemble 
-
-那是发现问题的简单办法，至少如果bug报告做的好的情况下（象这个一样-运行ksymoops
-得到oops发生的函数及函数内的偏移）。
-
-哦，如果报告发生的内核以相同的编译器和相似的配置编译它会有帮助的。
-
-另一件要做的事是反汇编bug报告的“Code”部分：ksymoops也会用正确的工具来做这件事，
-但如果没有那些工具你可以写一个傻程序：
-
-	char str[] = "\xXX\xXX\xXX...";
-	main(){}
-
-并用gcc -g编译它然后执行“disassemble str”（XX部分是由Oops报告的值-你可以仅剪切
-粘贴并用“\x”替换空格-我就是这么做的，因为我懒得写程序自动做这一切）。
-
-另外，你可以用scripts/decodecode这个shell脚本。它的使用方法是：
-decodecode < oops.txt
-
-“Code”之后的十六进制字节可能（在某些架构上）有一些当前指令之前的指令字节以及
-当前和之后的指令字节
-
-Code: f9 0f 8d f9 00 00 00 8d 42 0c e8 dd 26 11 c7 a1 60 ea 2b f9 8b 50 08 a1
-64 ea 2b f9 8d 34 82 8b 1e 85 db 74 6d 8b 15 60 ea 2b f9 <8b> 43 04 39 42 54
-7e 04 40 89 42 54 8b 43 04 3b 05 00 f6 52 c0
-
-最后，如果你想知道代码来自哪里，你可以：
-
-	cd /usr/src/linux
-	make fs/buffer.s 	# 或任何产生BUG的文件
-
-然后你会比gdb反汇编更清楚的知道发生了什么。
-
-现在，问题是把你所拥有的所有数据结合起来：C源码（关于它应该怎样的一般知识），
-汇编代码及其反汇编得到的代码（另外还有从“oops”消息得到的寄存器状态-对了解毁坏的
-指针有用，而且当你有了汇编代码你也能拿其它的寄存器和任何它们对应的C表达式做匹配
-）。
-
-实际上，你仅需看看哪里不匹配（这个例子是“Code”反汇编和编译器生成的代码不匹配）。
-然后你须要找出为什么不匹配。通常很简单-你看到代码使用了空指针然后你看代码想知道
-空指针是怎么出现的，还有检查它是否合法..
-
-现在，如果明白这是一项耗时的工作而且需要一丁点儿的专心，没错。这就是我为什么大多
-只是忽略那些没有符号表信息的崩溃报告的原因：简单的说太难查找了（我有一些
-程序用于在内核代码段中搜索特定的模式，而且有时我也已经能找出那些崩溃的地方，但是
-仅仅是找出正确的序列也确实需要相当扎实的内核知识）
-
-_有时_会发生这种情况，我仅看到崩溃中的反汇编代码序列， 然后我马上就明白问题出在
-哪里。这时我才意识到自己干这个工作已经太长时间了;-)
-
-		Linus
-
-
----------------------------------------------------------------------------
-关于Oops跟踪的注解：
-
-为了帮助Linus和其它内核开发者，klogd纳入了大量的支持来处理保护错误。为了拥有对
-地址解析的完整支持至少应该使用1.3-pl3的sysklogd包。
-
-当保护错误发生时，klogd守护进程自动把内核日志信息中的重要地址翻译成它们相应的符
-号。
-
-klogd执行两种类型的地址解析。首先是静态翻译其次是动态翻译。静态翻译和ksymoops
-一样使用System.map文件。为了做静态翻译klogd守护进程必须在初始化时能找到system
-map文件。关于klogd怎样搜索map文件请参看klogd手册页。
-
-动态地址翻译在使用内核可装载模块时很重要。 因为内核模块的内存是从内核动态内存池
-里分配的，所以不管是模块开始位置还是模块中函数和符号的位置都不是固定的。
-
-内核支持允许程序决定装载哪些模块和它们在内存中位置的系统调用。使用这些系统调用
-klogd守护进程生成一张符号表用于调试发生在可装载模块中的保护错误。
-
-至少klogd会提供产生保护错误的模块名。还可有额外的符号信息供可装载模块开发者选择
-以从模块中输出符号信息。
-
-因为内核模块环境可能是动态的，所以必须有一种机制当模块环境发生改变时来通知klogd
-守护进程。 有一些可用的命令行选项允许klogd向当前执行中的守护进程发送信号，告知符
-号信息应该被刷新了。 更多信息请参看klogd手册页。
-
-sysklogd发布时包含一个补丁修改了modules-2.0.0包，无论何时一个模块装载或者卸载都
-会自动向klogd发送信号。打上这个补丁提供了必要的对调试发生于内核可装载模块的保护
-错误的无缝支持。
-
-以下是被klogd处理过的发生在可装载模块中的一个保护错误例子：
----------------------------------------------------------------------------
-Aug 29 09:51:01 blizard kernel: Unable to handle kernel paging request at virtual address f15e97cc
-Aug 29 09:51:01 blizard kernel: current->tss.cr3 = 0062d000, %cr3 = 0062d000
-Aug 29 09:51:01 blizard kernel: *pde = 00000000
-Aug 29 09:51:01 blizard kernel: Oops: 0002
-Aug 29 09:51:01 blizard kernel: CPU:    0
-Aug 29 09:51:01 blizard kernel: EIP:    0010:[oops:_oops+16/3868]
-Aug 29 09:51:01 blizard kernel: EFLAGS: 00010212
-Aug 29 09:51:01 blizard kernel: eax: 315e97cc   ebx: 003a6f80   ecx: 001be77b   edx: 00237c0c
-Aug 29 09:51:01 blizard kernel: esi: 00000000   edi: bffffdb3   ebp: 00589f90   esp: 00589f8c
-Aug 29 09:51:01 blizard kernel: ds: 0018   es: 0018   fs: 002b   gs: 002b   ss: 0018
-Aug 29 09:51:01 blizard kernel: Process oops_test (pid: 3374, process nr: 21, stackpage=00589000)
-Aug 29 09:51:01 blizard kernel: Stack: 315e97cc 00589f98 0100b0b4 bffffed4 0012e38e 00240c64 003a6f80 00000001
-Aug 29 09:51:01 blizard kernel:        00000000 00237810 bfffff00 0010a7fa 00000003 00000001 00000000 bfffff00
-Aug 29 09:51:01 blizard kernel:        bffffdb3 bffffed4 ffffffda 0000002b 0007002b 0000002b 0000002b 00000036
-Aug 29 09:51:01 blizard kernel: Call Trace: [oops:_oops_ioctl+48/80] [_sys_ioctl+254/272] [_system_call+82/128]
-Aug 29 09:51:01 blizard kernel: Code: c7 00 05 00 00 00 eb 08 90 90 90 90 90 90 90 90 89 ec 5d c3
----------------------------------------------------------------------------
-
-Dr. G.W. Wettstein           Oncology Research Div. Computing Facility
-Roger Maris Cancer Center    INTERNET: greg@wind.rmcc.com
-820 4th St. N.
-Fargo, ND  58122
-Phone: 701-234-7556
-
-
----------------------------------------------------------------------------
-受污染的内核
-
-一些oops报告在程序记数器之后包含字符串'Tainted: '。这表明内核已经被一些东西给污
-染了。 该字符串之后紧跟着一系列的位置敏感的字符，每个代表一个特定的污染值。
-
-  1：'G'如果所有装载的模块都有GPL或相容的许可证，'P'如果装载了任何的专有模块。
-没有模块MODULE_LICENSE或者带有insmod认为是与GPL不相容的的MODULE_LICENSE的模块被
-认定是专有的。
-
-  2：'F'如果有任何通过“insmod -f”被强制装载的模块，' '如果所有模块都被正常装载。
-
-  3：'S'如果oops发生在SMP内核中，运行于没有证明安全运行多处理器的硬件。 当前这种
-情况仅限于几种不支持SMP的速龙处理器。
-
-  4：'R'如果模块通过“insmod -f”被强制装载，' '如果所有模块都被正常装载。
-
-  5：'M'如果任何处理器报告了机器检查异常，' '如果没有发生机器检查异常。
-
-  6：'B'如果页释放函数发现了一个错误的页引用或者一些非预期的页标志。
-
-  7：'U'如果用户或者用户应用程序特别请求设置污染标志，否则' '。
-
-  8：'D'如果内核刚刚死掉，比如有OOPS或者BUG。
-
-使用'Tainted: '字符串的主要原因是要告诉内核调试者，这是否是一个干净的内核亦或发
-生了任何的不正常的事。污染是永久的：即使出错的模块已经被卸载了，污染值仍然存在，
-以表明内核不再值得信任。
diff --git a/Documentation/zh_CN/sparse.txt b/Documentation/zh_CN/sparse.txt
deleted file mode 100644
index cc144e581515..000000000000
--- a/Documentation/zh_CN/sparse.txt
+++ /dev/null
@@ -1,100 +0,0 @@
-Chinese translated version of Documentation/sparse.txt
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Chinese maintainer: Li Yang 
----------------------------------------------------------------------
-Documentation/sparse.txt 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-
-中文版维护者： 李阳  Li Yang 
-中文版翻译者： 李阳  Li Yang 
-
-
-以下为正文
----------------------------------------------------------------------
-
-Copyright 2004 Linus Torvalds
-Copyright 2004 Pavel Machek 
-Copyright 2006 Bob Copeland 
-
-使用 sparse 工具做类型检查
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-"__bitwise" 是一种类型属性，所以你应该这样使用它：
-
-        typedef int __bitwise pm_request_t;
-
-        enum pm_request {
-                PM_SUSPEND = (__force pm_request_t) 1,
-                PM_RESUME = (__force pm_request_t) 2
-        };
-
-这样会使 PM_SUSPEND 和 PM_RESUME 成为位方式(bitwise)整数（使用"__force"
-是因为 sparse 会抱怨改变位方式的类型转换，但是这里我们确实需要强制进行转
-换）。而且因为所有枚举值都使用了相同的类型，这里的"enum pm_request"也将
-会使用那个类型做为底层实现。
-
-而且使用 gcc 编译的时候，所有的 __bitwise/__force 都会消失，最后在 gcc
-看来它们只不过是普通的整数。
-
-坦白来说，你并不需要使用枚举类型。上面那些实际都可以浓缩成一个特殊的"int
-__bitwise"类型。
-
-所以更简单的办法只要这样做：
-
-	typedef int __bitwise pm_request_t;
-
-	#define PM_SUSPEND ((__force pm_request_t) 1)
-	#define PM_RESUME ((__force pm_request_t) 2)
-
-现在你就有了严格的类型检查所需要的所有基础架构。
-
-一个小提醒：常数整数"0"是特殊的。你可以直接把常数零当作位方式整数使用而
-不用担心 sparse 会抱怨。这是因为"bitwise"（恰如其名）是用来确保不同位方
-式类型不会被弄混（小尾模式，大尾模式，cpu尾模式，或者其他），对他们来说
-常数"0"确实是特殊的。
-
-获取 sparse 工具
-~~~~~~~~~~~~~~~~
-
-你可以从 Sparse 的主页获取最新的发布版本：
-
-	http://www.kernel.org/pub/linux/kernel/people/josh/sparse/
-
-或者，你也可以使用 git 克隆最新的 sparse 开发版本：
-
-	git://git.kernel.org/pub/scm/linux/kernel/git/josh/sparse.git
-
-DaveJ 把每小时自动生成的 git 源码树 tar 包放在以下地址：
-
-	http://www.codemonkey.org.uk/projects/git-snapshots/sparse/
-
-一旦你下载了源码，只要以普通用户身份运行：
-
-	make
-	make install
-
-它将会被自动安装到你的 ~/bin 目录下。
-
-使用 sparse 工具
-~~~~~~~~~~~~~~~~
-
-用"make C=1"命令来编译内核，会对所有重新编译的 C 文件使用 sparse 工具。
-或者使用"make C=2"命令，无论文件是否被重新编译都会对其使用 sparse 工具。
-如果你已经编译了内核，用后一种方式可以很快地检查整个源码树。
-
-make 的可选变量 CHECKFLAGS 可以用来向 sparse 工具传递参数。编译系统会自
-动向 sparse 工具传递 -Wbitwise 参数。你可以定义 __CHECK_ENDIAN__ 来进行
-大小尾检查。
-
-	make C=2 CHECKFLAGS="-D__CHECK_ENDIAN__"
-
-这些检查默认都是被关闭的，因为他们通常会产生大量的警告。
diff --git a/Documentation/zh_CN/stable_api_nonsense.txt b/Documentation/zh_CN/stable_api_nonsense.txt
deleted file mode 100644
index a2b27fab382c..000000000000
--- a/Documentation/zh_CN/stable_api_nonsense.txt
+++ /dev/null
@@ -1,157 +0,0 @@
-Chinese translated version of Documentation/process/stable-api-nonsense.rst
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have problem
-communicating in English you can also ask the Chinese maintainer for help.
-Contact the Chinese maintainer, if this translation is outdated or there
-is problem with translation.
-
-Maintainer: Greg Kroah-Hartman 
-Chinese maintainer: TripleX Chung 
----------------------------------------------------------------------
-Documentation/process/stable-api-nonsense.rst 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-
-英文版维护者： Greg Kroah-Hartman 
-中文版维护者： 钟宇  TripleX Chung 
-中文版翻译者： 钟宇  TripleX Chung 
-中文版校译者： 李阳  Li Yang 
-以下为正文
----------------------------------------------------------------------
-
-写作本文档的目的，是为了解释为什么Linux既没有二进制内核接口，也没有稳定
-的内核接口。这里所说的内核接口，是指内核里的接口，而不是内核和用户空间
-的接口。内核到用户空间的接口，是提供给应用程序使用的系统调用，系统调用
-在历史上几乎没有过变化，将来也不会有变化。我有一些老应用程序是在0.9版本
-或者更早版本的内核上编译的，在使用2.6版本内核的Linux发布上依然用得很好
-。用户和应用程序作者可以将这个接口看成是稳定的。
-
-
-执行纲要
---------
-
-你也许以为自己想要稳定的内核接口，但是你不清楚你要的实际上不是它。你需
-要的其实是稳定的驱动程序，而你只有将驱动程序放到公版内核的源代码树里，
-才有可能达到这个目的。而且这样做还有很多其它好处，正是因为这些好处使得
-Linux能成为强壮，稳定，成熟的操作系统，这也是你最开始选择Linux的原因。
-
-
-入门
------
-
-只有那些写驱动程序的“怪人”才会担心内核接口的改变，对广大用户来说，既
-看不到内核接口，也不需要去关心它。
-
-首先，我不打算讨论关于任何非GPL许可的内核驱动的法律问题，这些非GPL许可
-的驱动程序包括不公开源代码，隐藏源代码，二进制或者是用源代码包装，或者
-是其它任何形式的不能以GPL许可公开源代码的驱动程序。如果有法律问题，请咨
-询律师，我只是一个程序员，所以我只打算探讨技术问题（不是小看法律问题，
-法律问题很实际，并且需要一直关注）。
-
-既然只谈技术问题，我们就有了下面两个主题：二进制内核接口和稳定的内核源
-代码接口。这两个问题是互相关联的，让我们先解决掉二进制接口的问题。
-
-
-二进制内核接口
---------------
-假如我们有一个稳定的内核源代码接口，那么自然而然的，我们就拥有了稳定的
-二进制接口，是这样的吗？错。让我们看看关于Linux内核的几点事实：
-    - 取决于所用的C编译器的版本，不同的内核数据结构里的结构体的对齐方
-式会有差别，代码中不同函数的表现形式也不一样（函数是不是被inline编译取
-决于编译器行为）。不同的函数的表现形式并不重要，但是数据结构内部的对齐
-方式很关键。
-    - 取决于内核的配置选项，不同的选项会让内核的很多东西发生改变：
-      - 同一个结构体可能包含不同的成员变量
-      - 有的函数可能根本不会被实现（比如编译的时候没有选择SMP支持
-，一些锁函数就会被定义成空函数）。
-      - 内核使用的内存会以不同的方式对齐，这取决于不同的内核配置选
-项。
-    - Linux可以在很多的不同体系结构的处理器上运行。在某个体系结构上编
-译好的二进制驱动程序，不可能在另外一个体系结构上正确的运行。
-
-对于一个特定的内核，满足这些条件并不难，使用同一个C编译器和同样的内核配
-置选项来编译驱动程序模块就可以了。这对于给一个特定Linux发布的特定版本提
-供驱动程序，是完全可以满足需求的。但是如果你要给不同发布的不同版本都发
-布一个驱动程序，就需要在每个发布上用不同的内核设置参数都编译一次内核，
-这简直跟噩梦一样。而且还要注意到，每个Linux发布还提供不同的Linux内核，
-这些内核都针对不同的硬件类型进行了优化（有很多种不同的处理器，还有不同
-的内核设置选项）。所以每发布一次驱动程序，都需要提供很多不同版本的内核
-模块。
-
-相信我，如果你真的要采取这种发布方式，一定会慢慢疯掉，我很久以前就有过
-深刻的教训...
-
-
-稳定的内核源代码接口
---------------------
-
-如果有人不将他的内核驱动程序，放入公版内核的源代码树，而又想让驱动程序
-一直保持在最新的内核中可用，那么这个话题将会变得没完没了。
- 内核开发是持续而且快节奏的，从来都不会慢下来。内核开发人员在当前接口中
-找到bug，或者找到更好的实现方式。一旦发现这些，他们就很快会去修改当前的
-接口。修改接口意味着，函数名可能会改变，结构体可能被扩充或者删减，函数
-的参数也可能发生改变。一旦接口被修改，内核中使用这些接口的地方需要同时
-修正，这样才能保证所有的东西继续工作。
-
-举一个例子，内核的USB驱动程序接口在USB子系统的整个生命周期中，至少经历
-了三次重写。这些重写解决以下问题：
-    - 把数据流从同步模式改成非同步模式，这个改动减少了一些驱动程序的
-复杂度，提高了所有USB驱动程序的吞吐率，这样几乎所有的USB设备都能以最大
-速率工作了。
-    - 修改了USB核心代码中为USB驱动分配数据包内存的方式，所有的驱动都
-需要提供更多的参数给USB核心，以修正了很多已经被记录在案的死锁。
-
-这和一些封闭源代码的操作系统形成鲜明的对比，在那些操作系统上，不得不额
-外的维护旧的USB接口。这导致了一个可能性，新的开发者依然会不小心使用旧的
-接口，以不恰当的方式编写代码，进而影响到操作系统的稳定性。
- 在上面的例子中，所有的开发者都同意这些重要的改动，在这样的情况下修改代
-价很低。如果Linux保持一个稳定的内核源代码接口，那么就得创建一个新的接口
-；旧的，有问题的接口必须一直维护，给Linux USB开发者带来额外的工作。既然
-所有的Linux USB驱动的作者都是利用自己的时间工作，那么要求他们去做毫无意
-义的免费额外工作，是不可能的。
- 安全问题对Linux来说十分重要。一个安全问题被发现，就会在短时间内得到修
-正。在很多情况下，这将导致Linux内核中的一些接口被重写，以从根本上避免安
-全问题。一旦接口被重写，所有使用这些接口的驱动程序，必须同时得到修正，
-以确定安全问题已经得到修复并且不可能在未来还有同样的安全问题。如果内核
-内部接口不允许改变，那么就不可能修复这样的安全问题，也不可能确认这样的
-安全问题以后不会发生。
-开发者一直在清理内核接口。如果一个接口没有人在使用了，它就会被删除。这
-样可以确保内核尽可能的小，而且所有潜在的接口都会得到尽可能完整的测试
-（没有人使用的接口是不可能得到良好的测试的）。
-
-
-要做什么
--------
-
-如果你写了一个Linux内核驱动，但是它还不在Linux源代码树里，作为一个开发
-者，你应该怎么做？为每个发布的每个版本提供一个二进制驱动，那简直是一个
-噩梦，要跟上永远处于变化之中的内核接口，也是一件辛苦活。
-很简单，让你的驱动进入内核源代码树（要记得我们在谈论的是以GPL许可发行
-的驱动，如果你的代码不符合GPL，那么祝你好运，你只能自己解决这个问题了，
-你这个吸血鬼<把Andrew和Linus对吸血鬼的定义链接到这里>）。当你的代码加入
-公版内核源代码树之后，如果一个内核接口改变，你的驱动会直接被修改接口的
-那个人修改。保证你的驱动永远都可以编译通过，并且一直工作，你几乎不需要
-做什么事情。
-
-把驱动放到内核源代码树里会有很多的好处：
-    - 驱动的质量会提升，而维护成本（对原始作者来说）会下降。
-    - 其他人会给驱动添加新特性。
-    - 其他人会找到驱动中的bug并修复。
-    - 其他人会在驱动中找到性能优化的机会。
-    - 当外部的接口的改变需要修改驱动程序的时候，其他人会修改驱动程序
-。
-    - 不需要联系任何发行商，这个驱动会自动的随着所有的Linux发布一起发
-布。
-
-和别的操作系统相比，Linux为更多不同的设备提供现成的驱动，而且能在更多不
-同体系结构的处理器上支持这些设备。这个经过考验的开发模式，必然是错不了
-的 :)
-
--------------
-感谢 Randy Dunlap, Andrew Morton, David Brownell, Hanna Linder,
-Robert Love, and Nishanth Aravamudan 对于本文档早期版本的评审和建议。
-
-英文版维护者： Greg Kroah-Hartman 
diff --git a/Documentation/zh_CN/stable_kernel_rules.txt b/Documentation/zh_CN/stable_kernel_rules.txt
deleted file mode 100644
index db4ba5a0c39a..000000000000
--- a/Documentation/zh_CN/stable_kernel_rules.txt
+++ /dev/null
@@ -1,66 +0,0 @@
-Chinese translated version of Documentation/process/stable-kernel-rules.rst
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Chinese maintainer: TripleX Chung 
----------------------------------------------------------------------
-Documentation/process/stable-kernel-rules.rst 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-
-
-中文版维护者： 钟宇  TripleX Chung 
-中文版翻译者： 钟宇  TripleX Chung 
-中文版校译者： 李阳  Li Yang 
-               Kangkai Yin 
-
-以下为正文
----------------------------------------------------------------------
-
-关于Linux 2.6稳定版发布，所有你想知道的事情。
-
-关于哪些类型的补丁可以被接收进入稳定版代码树，哪些不可以的规则：
-
-  - 必须是显而易见的正确，并且经过测试的。
-  - 连同上下文，不能大于100行。
-  - 必须只修正一件事情。
-  - 必须修正了一个给大家带来麻烦的真正的bug（不是“这也许是一个问题...”
-    那样的东西）。
-  - 必须修正带来如下后果的问题：编译错误（对被标记为CONFIG_BROKEN的例外），
-    内核崩溃，挂起，数据损坏，真正的安全问题，或者一些类似“哦，这不
-    好”的问题。简短的说，就是一些致命的问题。
-  - 没有“理论上的竞争条件”，除非能给出竞争条件如何被利用的解释。
-  - 不能存在任何的“琐碎的”修正（拼写修正，去掉多余空格之类的）。
-  - 必须被相关子系统的维护者接受。
-  - 必须遵循Documentation/process/submitting-patches.rst里的规则。
-
-向稳定版代码树提交补丁的过程：
-
-  - 在确认了补丁符合以上的规则后，将补丁发送到stable@vger.kernel.org。
-  - 如果补丁被接受到队列里，发送者会收到一个ACK回复，如果没有被接受，收
-    到的是NAK回复。回复需要几天的时间，这取决于开发者的时间安排。
-  - 被接受的补丁会被加到稳定版本队列里，等待其他开发者的审查。
-  - 安全方面的补丁不要发到这个列表，应该发送到security@kernel.org。
-
-审查周期：
-
-  - 当稳定版的维护者决定开始一个审查周期，补丁将被发送到审查委员会，以
-    及被补丁影响的领域的维护者（除非提交者就是该领域的维护者）并且抄送
-    到linux-kernel邮件列表。
-  - 审查委员会有48小时的时间，用来决定给该补丁回复ACK还是NAK。
-  - 如果委员会中有成员拒绝这个补丁，或者linux-kernel列表上有人反对这个
-    补丁，并提出维护者和审查委员会之前没有意识到的问题，补丁会从队列中
-    丢弃。
-  - 在审查周期结束的时候，那些得到ACK回应的补丁将会被加入到最新的稳定版
-    发布中，一个新的稳定版发布就此产生。
-  - 安全性补丁将从内核安全小组那里直接接收到稳定版代码树中，而不是通过
-    通常的审查周期。请联系内核安全小组以获得关于这个过程的更多细节。
-
-审查委员会：
-  - 由一些自愿承担这项任务的内核开发者，和几个非志愿的组成。
diff --git a/Documentation/zh_CN/video4linux/omap3isp.txt b/Documentation/zh_CN/video4linux/omap3isp.txt
deleted file mode 100644
index 67ffbf352ae0..000000000000
--- a/Documentation/zh_CN/video4linux/omap3isp.txt
+++ /dev/null
@@ -1,277 +0,0 @@
-Chinese translated version of Documentation/video4linux/omap3isp.txt
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Maintainer: Laurent Pinchart 
-	  Sakari Ailus 
-	  David Cohen 
-Chinese maintainer: Fu Wei 
----------------------------------------------------------------------
-Documentation/video4linux/omap3isp.txt 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-英文版维护者： Laurent Pinchart 
-	  Sakari Ailus 
-	  David Cohen 
-中文版维护者： 傅炜 Fu Wei 
-中文版翻译者： 傅炜 Fu Wei 
-中文版校译者： 傅炜 Fu Wei 
-
-
-以下为正文
----------------------------------------------------------------------
-OMAP 3 图像信号处理器 (ISP) 驱动
-
-Copyright (C) 2010 Nokia Corporation
-Copyright (C) 2009 Texas Instruments, Inc.
-
-联系人: Laurent Pinchart 
-	  Sakari Ailus 
-	  David Cohen 
-
-
-介绍
-===
-
-本文档介绍了由 drivers/media/video/omap3isp 加载的德州仪器
-（TI）OMAP 3 图像信号处理器 (ISP) 驱动。原始驱动由德州仪器（TI）
-编写，但此后由诺基亚重写了两次。
-
-驱动已在以下 OMAP 3 系列的芯片中成功使用：
-
-	3430
-	3530
-	3630
-
-驱动实现了 V4L2、媒体控制器和 v4l2_subdev 接口。支持内核中使用
-v4l2_subdev 接口的传感器、镜头和闪光灯驱动。
-
-
-拆分为子设备
-==========
-
-OMAP 3 ISP 被拆分为 V4L2 子设备，ISP中的每个模块都由一个子设备
-来表示。每个子设备向用户空间提供一个 V4L2 子设备接口。
-
-	OMAP3 ISP CCP2
-	OMAP3 ISP CSI2a
-	OMAP3 ISP CCDC
-	OMAP3 ISP preview
-	OMAP3 ISP resizer
-	OMAP3 ISP AEWB
-	OMAP3 ISP AF
-	OMAP3 ISP histogram
-
-ISP 中每个可能的连接都通过一个链接嵌入到媒体控制器接口中。详见例程 [2]。
-
-
-控制 OMAP 3 ISP
-==============
-
-通常，对 OMAP 3 ISP 的配置会在下一帧起始时生效。在传感器垂直消隐期间，
-模块变为空闲时完成配置。在内存到内存的操作中，视频管道一次处理一帧。
-应用配置应在帧间完成。
-
-ISP 中的所有模块，除 CSI-2 和 （可能存在的）CCP2 接收器外，都必须
-接收完整的帧数据。因此，传感器必须保证从不发送部分帧数据给ISP。
-
-Autoidle（自动空闲）功能至少在 3430 的 ISP 模块中确实存在一些问题。
-当 omap3isp 模块参数 autoidle 非零时，autoidle（自动空闲）功能
-仅在 3630 中启用了。
-
-
-事件机制
-======
-
-OMAP 3 ISP 驱动在 CCDC 和统计（AEWB、AF 和 直方图）子设备中支持
-V4L2 事件机制接口。
-
-CCDC 子设备通过 HS_VS 中断，处理 V4L2_EVENT_FRAME_SYNC 类型
-事件，用于告知帧起始。早期版本的驱动则使用 V4L2_EVENT_OMAP3ISP_HS_VS。
-当在 CCDC 模块中接收到起始帧的第一行时，会准确地触发事件。这个事件
-可以在 CCDC 子设备中“订阅”。
-
-（当使用并行接口时，必须注意正确地配置 VS 信号极性。而当使用串行接收时
-这个会自动校正。）
-
-每个统计子设备都可以产生事件。每当一个统计缓冲区可由用户空间应用程序
-通过 VIDIOC_OMAP3ISP_STAT_REQ IOCTL 操作获取时，就会产生一个
-事件。当前存在以下事件：
-
-	V4L2_EVENT_OMAP3ISP_AEWB
-	V4L2_EVENT_OMAP3ISP_AF
-	V4L2_EVENT_OMAP3ISP_HIST
-
-这些 ioctl 的事件数据类型为 struct omap3isp_stat_event_status
-结构体。如果出现计算错误的统计，也同样会产生一个事件，但没有相关的统计
-数据缓冲区。这种情况下 omap3isp_stat_event_status.buf_err 会被
-设置为非零值。
-
-
-私有 IOCTL
-==========
-
-OMAP 3 ISP 驱动支持标准的 V4L2 IOCTL 以及可能存在且实用的控制。但
-ISP 提供的许多功能都不在标准 IOCTL 之列，例如 gamma（伽马）表和统计
-数据采集配置等。
-
-通常，会有一个私有 ioctl 用于配置每个包含硬件依赖功能的模块。
-
-支持以下私有 IOCTL：
-
-	VIDIOC_OMAP3ISP_CCDC_CFG
-	VIDIOC_OMAP3ISP_PRV_CFG
-	VIDIOC_OMAP3ISP_AEWB_CFG
-	VIDIOC_OMAP3ISP_HIST_CFG
-	VIDIOC_OMAP3ISP_AF_CFG
-	VIDIOC_OMAP3ISP_STAT_REQ
-	VIDIOC_OMAP3ISP_STAT_EN
-
-在 include/linux/omap3isp.h 中描述了这些 ioctl 使用的参数结构体。
-与特定 ISP 模块相关的 ISP 自身的详细功能在技术参考手册 (TRMs)中有
-描述，详见文档结尾。
-
-虽然在不使用任何私有 IOCTL 的情况下使用 ISP 驱动是可能的，但这样无法
-获得最佳的图像质量。AEWB、AF 和 直方图（译者注：一般用于自动曝光和增益
-控制，以及图像均衡等）模块无法在未使用适当的私有 IOCTL 配置的情况下使用。
-
-
-CCDC 和 preview（预览）模块 IOCTL
-===============================
-
-VIDIOC_OMAP3ISP_CCDC_CFG 和 VIDIOC_OMAP3ISP_PRV_CFG IOCTL
-被分别用于配置、启用和禁用 CCDC 和 preview（预览）模块的功能。在它们
-所控制的模块中，两个 IOCTL 控制多种功能。VIDIOC_OMAP3ISP_CCDC_CFG IOCTL
-接受一个指向 omap3isp_ccdc_update_config 结构体的指针作为它的参数。
-同样的，VIDIOC_OMAP3ISP_PRV_CFG 接受一个指向 omap3isp_prev_update_config
-结构体的指针。以上两个结构体定义位于 [1]。
-
-这些结构体中的 update 域标识是否针对指定的功能更新配置，而 flag 域
-则标识是启用还是禁用此功能。
-
-update 和 flag 位接受以下掩码值。CCDC 和 preview（预览）模块的
-每个单独功能都与一个 flag 关联（禁用或启用；在结构体中 flag 域的
-一部分）和一个指向功能配置数据的指针。
-
-对于 VIDIOC_OMAP3ISP_CCDC_CFG，下面列出了 update 和 flag 域
-中的有效值。 这些值可能会在同一个 IOCTL 调用中配置多个功能。
-
-        OMAP3ISP_CCDC_ALAW
-        OMAP3ISP_CCDC_LPF
-        OMAP3ISP_CCDC_BLCLAMP
-        OMAP3ISP_CCDC_BCOMP
-        OMAP3ISP_CCDC_FPC
-        OMAP3ISP_CCDC_CULL
-        OMAP3ISP_CCDC_CONFIG_LSC
-        OMAP3ISP_CCDC_TBL_LSC
-
-针对 VIDIOC_OMAP3ISP_PRV_CFG 的相应值如下：
-
-        OMAP3ISP_PREV_LUMAENH
-        OMAP3ISP_PREV_INVALAW
-        OMAP3ISP_PREV_HRZ_MED
-        OMAP3ISP_PREV_CFA
-        OMAP3ISP_PREV_CHROMA_SUPP
-        OMAP3ISP_PREV_WB
-        OMAP3ISP_PREV_BLKADJ
-        OMAP3ISP_PREV_RGB2RGB
-        OMAP3ISP_PREV_COLOR_CONV
-        OMAP3ISP_PREV_YC_LIMIT
-        OMAP3ISP_PREV_DEFECT_COR
-        OMAP3ISP_PREV_GAMMABYPASS
-        OMAP3ISP_PREV_DRK_FRM_CAPTURE
-        OMAP3ISP_PREV_DRK_FRM_SUBTRACT
-        OMAP3ISP_PREV_LENS_SHADING
-        OMAP3ISP_PREV_NF
-        OMAP3ISP_PREV_GAMMA
-
-在启用某个功能的时候，相关的配置数据指针不可为 NULL。在禁用某个功能时，
-配置数据指针会被忽略。
-
-
-统计模块 IOCTL
-=============
-
-统计子设备相较于其他子设备提供了更多动态配置选项。在图像处理流水线处于
-工作状态时，它们可以被启用、禁用和重配。
-
-统计模块总是从 CCDC 中获取输入的图像数据（由于直方图内存读取未实现）。
-统计数据可由用户通过统计子设备节点使用私有 IOCTL 获取。
-
-AEWB、AF 和 直方图子设备提供的私有 IOCTL 极大程度上反应了 ISP 硬件
-提供的寄存器级接口。有些方面纯粹和驱动程序的实现相关，这些将在下面讨论。
-
-VIDIOC_OMAP3ISP_STAT_EN
------------------------
-
-这个私有 IOCTL 启用/禁用 一个统计模块。如果这个申请在视频流启动前完成，
-它将在视频流水线开始工作时生效。如果视频流水线已经处于工作状态了，它将在
-CCDC 变为空闲时生效。
-
-VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG
------------------------------------------------------------------------------
-
-这些 IOCTL 用于配置模块。它们要求用户应用程序对硬件有深入的认识。对
-大多数域的解释可以在 OMAP 的 TRM 中找到。以下两个域对于以上所有的
-私有 IOCTL 配置都很常见，由于他们没有在 TRM 中提及，故需要对其有
-更好的认识。
-
-omap3isp_[h3a_af/h3a_aewb/hist]_config.buf_size:
-
-模块在内部处理自身缓冲。对模块数据输出所必需的缓存大小依赖于已申请的配置。
-虽然驱动支持在视频流工作时重新配置，但对于所需缓存量大于模块启用时内部
-所分配数量的情况，则不支持重新配置。在这种情况下将返回 -EBUSY。为了避免
-此类状况，无论是禁用/重配/启用模块，还是第一次配置时申请必须的缓存大小，
-都应在模块禁用的情况下进行。
-
-内部缓冲分配的大小需综合考虑所申请配置的最小缓存量以及 buf_size 域中
-所设的值。如果 buf_size 域在[minimum（最小值）, maximum（最大值）]
-缓冲大小范围之外，则应该将其调整到其范围中。驱动则会选择最大值。正确的
-buf_size 值将回写到用户应用程序中。
-
-omap3isp_[h3a_af/h3a_aewb/hist]_config.config_counter:
-
-由于配置并未在申请之后同步生效，驱动必须提供一个跟踪这类信息的方法，
-以提供更准确的数据。在一个配置被申请之后，返回到用户空间应用程序的
-config_counter 是一个与其配置相关的唯一值。当用户应用程序接收到
-一个缓冲可用或一个新的缓冲申请事件时，这个 config_counter 用于
-一个缓冲数据和一个配置的匹配。
-
-VIDIOC_OMAP3ISP_STAT_REQ
-------------------------
-
-将内部缓冲队列中最早的数据发送到用户空间，然后丢弃此缓冲区。
-omap3isp_stat_data.frame_number 域与视频缓冲的 field_count
-域相匹配。
-
-
-技术参考手册 (TRMs) 和其他文档
-==========================
-
-OMAP 3430 TRM:
-
-参考于 2011-03-05.
-
-OMAP 35xx TRM:
- 参考于 2011-03-05.
-
-OMAP 3630 TRM:
-
-参考于 2011-03-05.
-
-DM 3730 TRM:
- 参考于 2011-03-06.
-
-
-参考资料
-=======
-
-[1] include/linux/omap3isp.h
-
-[2] http://git.ideasonboard.org/?p=media-ctl.git;a=summary
diff --git a/Documentation/zh_CN/video4linux/v4l2-framework.txt b/Documentation/zh_CN/video4linux/v4l2-framework.txt
deleted file mode 100644
index 698660b7f21f..000000000000
--- a/Documentation/zh_CN/video4linux/v4l2-framework.txt
+++ /dev/null
@@ -1,976 +0,0 @@
-Chinese translated version of Documentation/video4linux/v4l2-framework.txt
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Maintainer: Mauro Carvalho Chehab 
-Chinese maintainer: Fu Wei 
----------------------------------------------------------------------
-Documentation/video4linux/v4l2-framework.txt 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-英文版维护者： Mauro Carvalho Chehab 
-中文版维护者： 傅炜 Fu Wei 
-中文版翻译者： 傅炜 Fu Wei 
-中文版校译者： 傅炜 Fu Wei 
-
-
-以下为正文
----------------------------------------------------------------------
-V4L2 驱动框架概览
-==============
-
-本文档描述 V4L2 框架所提供的各种结构和它们之间的关系。
-
-
-介绍
-----
-
-大部分现代 V4L2 设备由多个 IC 组成，在 /dev 下导出多个设备节点，
-并同时创建非 V4L2 设备（如 DVB、ALSA、FB、I2C 和红外输入设备）。
-由于这种硬件的复杂性，V4L2 驱动也变得非常复杂。
-
-尤其是 V4L2 必须支持 IC 实现音视频的多路复用和编解码，这就更增加了其
-复杂性。通常这些 IC 通过一个或多个 I2C 总线连接到主桥驱动器，但也可
-使用其他总线。这些设备称为“子设备”。
-
-长期以来，这个框架仅限于通过 video_device 结构体创建 V4L 设备节点，
-并使用 video_buf 处理视频缓冲（注：本文不讨论 video_buf 框架）。
-
-这意味着所有驱动必须自己设置设备实例并连接到子设备。其中一部分要正确地
-完成是比较复杂的，使得许多驱动都没有正确地实现。
-
-由于框架的缺失，有很多通用代码都不可重复利用。
-
-因此，这个框架构建所有驱动都需要的基本结构块，而统一的框架将使通用代码
-创建成实用函数并在所有驱动中共享变得更加容易。
-
-
-驱动结构
--------
-
-所有 V4L2 驱动都有如下结构：
-
-1) 每个设备实例的结构体--包含其设备状态。
-
-2) 初始化和控制子设备的方法（如果有）。
-
-3) 创建 V4L2 设备节点 (/dev/videoX、/dev/vbiX 和 /dev/radioX)
-   并跟踪设备节点的特定数据。
-
-4) 特定文件句柄结构体--包含每个文件句柄的数据。
-
-5) 视频缓冲处理。
-
-以下是它们的初略关系图：
-
-    device instances（设备实例）
-      |
-      +-sub-device instances（子设备实例）
-      |
-      \-V4L2 device nodes（V4L2 设备节点）
-	  |
-	  \-filehandle instances（文件句柄实例）
-
-
-框架结构
--------
-
-该框架非常类似驱动结构：它有一个 v4l2_device 结构用于保存设备
-实例的数据；一个 v4l2_subdev 结构体代表子设备实例；video_device
-结构体保存 V4L2 设备节点的数据；将来 v4l2_fh 结构体将跟踪文件句柄
-实例（暂未尚未实现）。
-
-V4L2 框架也可与媒体框架整合（可选的）。如果驱动设置了 v4l2_device
-结构体的 mdev 域，子设备和视频节点的入口将自动出现在媒体框架中。
-
-
-v4l2_device 结构体
-----------------
-
-每个设备实例都通过 v4l2_device (v4l2-device.h)结构体来表示。
-简单设备可以仅分配这个结构体，但在大多数情况下，都会将这个结构体
-嵌入到一个更大的结构体中。
-
-你必须注册这个设备实例：
-
-	v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev);
-
-注册操作将会初始化 v4l2_device 结构体。如果 dev->driver_data 域
-为 NULL，就将其指向 v4l2_dev。
-
-需要与媒体框架整合的驱动必须手动设置 dev->driver_data，指向包含
-v4l2_device 结构体实例的驱动特定设备结构体。这可以在注册 V4L2 设备
-实例前通过 dev_set_drvdata() 函数完成。同时必须设置 v4l2_device
-结构体的 mdev 域，指向适当的初始化并注册过的 media_device 实例。
-
-如果 v4l2_dev->name 为空，则它将被设置为从 dev 中衍生出的值（为了
-更加精确，形式为驱动名后跟 bus_id）。如果你在调用 v4l2_device_register
-前已经设置好了，则不会被修改。如果 dev 为 NULL，则你*必须*在调用
-v4l2_device_register 前设置 v4l2_dev->name。
-
-你可以基于驱动名和驱动的全局 atomic_t 类型的实例编号，通过
-v4l2_device_set_name() 设置 name。这样会生成类似 ivtv0、ivtv1 等
-名字。若驱动名以数字结尾，则会在编号和驱动名间插入一个破折号，如：
-cx18-0、cx18-1 等。此函数返回实例编号。
-
-第一个 “dev” 参数通常是一个指向 pci_dev、usb_interface 或
-platform_device 的指针。很少使其为 NULL，除非是一个ISA设备或者
-当一个设备创建了多个 PCI 设备，使得 v4l2_dev 无法与一个特定的父设备
-关联。
-
-你也可以提供一个 notify() 回调，使子设备可以调用它实现事件通知。
-但这个设置与子设备相关。子设备支持的任何通知必须在
-include/media/.h 中定义一个消息头。
-
-注销 v4l2_device 使用如下函数：
-
-	v4l2_device_unregister(struct v4l2_device *v4l2_dev);
-
-如果 dev->driver_data 域指向 v4l2_dev，将会被重置为 NULL。注销同时
-会自动从设备中注销所有子设备。
-
-如果你有一个热插拔设备（如USB设备），则当断开发生时，父设备将无效。
-由于 v4l2_device 有一个指向父设备的指针必须被清除，同时标志父设备
-已消失，所以必须调用以下函数：
-
-	v4l2_device_disconnect(struct v4l2_device *v4l2_dev);
-
-这个函数并*不*注销子设备，因此你依然要调用 v4l2_device_unregister()
-函数。如果你的驱动器并非热插拔的，就没有必要调用 v4l2_device_disconnect()。
-
-有时你需要遍历所有被特定驱动注册的设备。这通常发生在多个设备驱动使用
-同一个硬件的情况下。如：ivtvfb 驱动是一个使用 ivtv 硬件的帧缓冲驱动，
-同时 alsa 驱动也使用此硬件。
-
-你可以使用如下例程遍历所有注册的设备：
-
-static int callback(struct device *dev, void *p)
-{
-	struct v4l2_device *v4l2_dev = dev_get_drvdata(dev);
-
-	/* 测试这个设备是否已经初始化 */
-	if (v4l2_dev == NULL)
-		return 0;
-	...
-	return 0;
-}
-
-int iterate(void *p)
-{
-	struct device_driver *drv;
-	int err;
-
-	/* 在PCI 总线上查找ivtv驱动。
-	   pci_bus_type是全局的. 对于USB总线使用usb_bus_type。 */
-	drv = driver_find("ivtv", &pci_bus_type);
-	/* 遍历所有的ivtv设备实例 */
-	err = driver_for_each_device(drv, NULL, p, callback);
-	put_driver(drv);
-	return err;
-}
-
-有时你需要一个设备实例的运行计数。这个通常用于映射一个设备实例到一个
-模块选择数组的索引。
-
-推荐方法如下：
-
-static atomic_t drv_instance = ATOMIC_INIT(0);
-
-static int drv_probe(struct pci_dev *pdev, const struct pci_device_id *pci_id)
-{
-	...
-	state->instance = atomic_inc_return(&drv_instance) - 1;
-}
-
-如果你有多个设备节点，对于热插拔设备，知道何时注销 v4l2_device 结构体
-就比较困难。为此 v4l2_device 有引用计数支持。当调用 video_register_device
-时增加引用计数，而设备节点释放时减小引用计数。当引用计数为零，则
-v4l2_device 的release() 回调将被执行。你就可以在此时做最后的清理工作。
-
-如果创建了其他设备节点（比如 ALSA），则你可以通过以下函数手动增减
-引用计数：
-
-void v4l2_device_get(struct v4l2_device *v4l2_dev);
-
-或:
-
-int v4l2_device_put(struct v4l2_device *v4l2_dev);
-
-由于引用技术初始化为 1 ，你也需要在 disconnect() 回调（对于 USB 设备）中
-调用 v4l2_device_put，或者 remove() 回调（例如对于 PCI 设备），否则
-引用计数将永远不会为 0 。
-
-v4l2_subdev结构体
-------------------
-
-许多驱动需要与子设备通信。这些设备可以完成各种任务，但通常他们负责
-音视频复用和编解码。如网络摄像头的子设备通常是传感器和摄像头控制器。
-
-这些一般为 I2C 接口设备，但并不一定都是。为了给驱动提供调用子设备的
-统一接口，v4l2_subdev 结构体（v4l2-subdev.h）产生了。
-
-每个子设备驱动都必须有一个 v4l2_subdev 结构体。这个结构体可以单独
-代表一个简单的子设备，也可以嵌入到一个更大的结构体中，与更多设备状态
-信息保存在一起。通常有一个下级设备结构体（比如：i2c_client）包含了
-内核创建的设备数据。建议使用 v4l2_set_subdevdata() 将这个结构体的
-指针保存在 v4l2_subdev 的私有数据域(dev_priv)中。这使得通过 v4l2_subdev
-找到实际的低层总线特定设备数据变得容易。
-
-你同时需要一个从低层结构体获取 v4l2_subdev 指针的方法。对于常用的
-i2c_client 结构体，i2c_set_clientdata() 函数可用于保存一个 v4l2_subdev
-指针；对于其他总线你可能需要使用其他相关函数。
-
-桥驱动中也应保存每个子设备的私有数据，比如一个指向特定桥的各设备私有
-数据的指针。为此 v4l2_subdev 结构体提供主机私有数据域(host_priv)，
-并可通过 v4l2_get_subdev_hostdata() 和 v4l2_set_subdev_hostdata()
-访问。
-
-从总线桥驱动的视角，驱动加载子设备模块并以某种方式获得 v4l2_subdev
-结构体指针。对于 i2c 总线设备相对简单：调用 i2c_get_clientdata()。
-对于其他总线也需要做类似的操作。针对 I2C 总线上的子设备辅助函数帮你
-完成了大部分复杂的工作。
-
-每个 v4l2_subdev 都包含子设备驱动需要实现的函数指针（如果对此设备
-不适用，可为NULL）。由于子设备可完成许多不同的工作，而在一个庞大的
-函数指针结构体中通常仅有少数有用的函数实现其功能肯定不合适。所以，
-函数指针根据其实现的功能被分类，每一类都有自己的函数指针结构体。
-
-顶层函数指针结构体包含了指向各类函数指针结构体的指针，如果子设备驱动
-不支持该类函数中的任何一个功能，则指向该类结构体的指针为NULL。
-
-这些结构体定义如下：
-
-struct v4l2_subdev_core_ops {
-	int (*log_status)(struct v4l2_subdev *sd);
-	int (*init)(struct v4l2_subdev *sd, u32 val);
-	...
-};
-
-struct v4l2_subdev_tuner_ops {
-	...
-};
-
-struct v4l2_subdev_audio_ops {
-	...
-};
-
-struct v4l2_subdev_video_ops {
-	...
-};
-
-struct v4l2_subdev_pad_ops {
-	...
-};
-
-struct v4l2_subdev_ops {
-	const struct v4l2_subdev_core_ops  *core;
-	const struct v4l2_subdev_tuner_ops *tuner;
-	const struct v4l2_subdev_audio_ops *audio;
-	const struct v4l2_subdev_video_ops *video;
-	const struct v4l2_subdev_pad_ops *video;
-};
-
-其中 core（核心）函数集通常可用于所有子设备，其他类别的实现依赖于
-子设备。如视频设备可能不支持音频操作函数，反之亦然。
-
-这样的设置在限制了函数指针数量的同时，还使增加新的操作函数和分类
-变得较为容易。
-
-子设备驱动可使用如下函数初始化 v4l2_subdev 结构体：
-
-	v4l2_subdev_init(sd, &ops);
-
-然后，你必须用一个唯一的名字初始化 subdev->name，并初始化模块的
-owner 域。若使用 i2c 辅助函数，这些都会帮你处理好。
-
-若需同媒体框架整合，你必须调用 media_entity_pads_init() 初始化 v4l2_subdev
-结构体中的 media_entity 结构体（entity 域）：
-
-	struct media_pad *pads = &my_sd->pads;
-	int err;
-
-	err = media_entity_pads_init(&sd->entity, npads, pads);
-
-pads 数组必须预先初始化。无须手动设置 media_entity 的 type 和
-name 域，但如有必要，revision 域必须初始化。
-
-当（任何）子设备节点被打开/关闭，对 entity 的引用将被自动获取/释放。
-
-在子设备被注销之后，不要忘记清理 media_entity 结构体：
-
-	media_entity_cleanup(&sd->entity);
-
-如果子设备驱动趋向于处理视频并整合进了媒体框架，必须使用 v4l2_subdev_pad_ops
-替代 v4l2_subdev_video_ops 实现格式相关的功能。
-
-这种情况下，子设备驱动应该设置 link_validate 域，以提供它自身的链接
-验证函数。链接验证函数应对管道（两端链接的都是 V4L2 子设备）中的每个
-链接调用。驱动还要负责验证子设备和视频节点间格式配置的正确性。
-
-如果 link_validate 操作没有设置，默认的 v4l2_subdev_link_validate_default()
-函数将会被调用。这个函数保证宽、高和媒体总线像素格式在链接的收发两端
-都一致。子设备驱动除了它们自己的检测外，也可以自由使用这个函数以执行
-上面提到的检查。
-
-设备（桥）驱动程序必须向 v4l2_device 注册 v4l2_subdev：
-
-	int err = v4l2_device_register_subdev(v4l2_dev, sd);
-
-如果子设备模块在它注册前消失，这个操作可能失败。在这个函数成功返回后，
-subdev->dev 域就指向了 v4l2_device。
-
-如果 v4l2_device 父设备的 mdev 域为非 NULL 值，则子设备实体将被自动
-注册为媒体设备。
-
-注销子设备则可用如下函数：
-
-	v4l2_device_unregister_subdev(sd);
-
-此后，子设备模块就可卸载，且 sd->dev == NULL。
-
-注册之设备后，可通过以下方式直接调用其操作函数：
-
-	err = sd->ops->core->g_std(sd, &norm);
-
-但使用如下宏会比较容易且合适：
-
-	err = v4l2_subdev_call(sd, core, g_std, &norm);
-
-这个宏将会做 NULL 指针检查，如果 subdev 为 NULL，则返回-ENODEV；如果
-subdev->core 或 subdev->core->g_std 为 NULL，则返回 -ENOIOCTLCMD；
-否则将返回 subdev->ops->core->g_std ops 调用的实际结果。
-
-有时也可能同时调用所有或一系列子设备的某个操作函数：
-
-	v4l2_device_call_all(v4l2_dev, 0, core, g_std, &norm);
-
-任何不支持此操作的子设备都会被跳过，并忽略错误返回值。但如果你需要
-检查出错码，则可使用如下函数：
-
-	err = v4l2_device_call_until_err(v4l2_dev, 0, core, g_std, &norm);
-
-除 -ENOIOCTLCMD 外的任何错误都会跳出循环并返回错误值。如果（除 -ENOIOCTLCMD
-外）没有错误发生，则返回 0。
-
-对于以上两个函数的第二个参数为组 ID。如果为 0，则所有子设备都会执行
-这个操作。如果为非 0 值，则只有那些组 ID 匹配的子设备才会执行此操作。
-在桥驱动注册一个子设备前，可以设置 sd->grp_id 为任何期望值（默认值为
-0）。这个值属于桥驱动，且子设备驱动将不会修改和使用它。
-
-组 ID 赋予了桥驱动更多对于如何调用回调的控制。例如，电路板上有多个
-音频芯片，每个都有改变音量的能力。但当用户想要改变音量的时候，通常
-只有一个会被实际使用。你可以对这样的子设备设置组 ID 为（例如 AUDIO_CONTROLLER）
-并在调用 v4l2_device_call_all() 时指定它为组 ID 值。这就保证了只有
-需要的子设备才会执行这个回调。
-
-如果子设备需要通知它的 v4l2_device 父设备一个事件，可以调用
-v4l2_subdev_notify(sd, notification, arg)。这个宏检查是否有一个
-notify() 回调被注册，如果没有，返回 -ENODEV。否则返回 notify() 调用
-结果。
-
-使用 v4l2_subdev 的好处在于它是一个通用结构体，且不包含任何底层硬件
-信息。所有驱动可以包含多个 I2C 总线的子设备，但也有子设备是通过 GPIO
-控制。这个区别仅在配置设备时有关系，一旦子设备注册完成，对于 v4l2
-子系统来说就完全透明了。
-
-
-V4L2 子设备用户空间API
---------------------
-
-除了通过 v4l2_subdev_ops 结构导出的内核 API，V4L2 子设备也可以直接
-通过用户空间应用程序来控制。
-
-可以在 /dev 中创建名为 v4l-subdevX 设备节点，以通过其直接访问子设备。
-如果子设备支持用户空间直接配置，必须在注册前设置 V4L2_SUBDEV_FL_HAS_DEVNODE
-标志。
-
-注册子设备之后， v4l2_device 驱动会通过调用 v4l2_device_register_subdev_nodes()
-函数为所有已注册并设置了 V4L2_SUBDEV_FL_HAS_DEVNODE 的子设备创建
-设备节点。这些设备节点会在子设备注销时自动删除。
-
-这些设备节点处理 V4L2 API 的一个子集。
-
-VIDIOC_QUERYCTRL
-VIDIOC_QUERYMENU
-VIDIOC_G_CTRL
-VIDIOC_S_CTRL
-VIDIOC_G_EXT_CTRLS
-VIDIOC_S_EXT_CTRLS
-VIDIOC_TRY_EXT_CTRLS
-
-	这些 ioctls 控制与 V4L2 中定义的一致。他们行为相同，唯一的
-	不同是他们只处理子设备的控制实现。根据驱动程序，这些控制也
-	可以通过一个（或多个） V4L2 设备节点访问。
-
-VIDIOC_DQEVENT
-VIDIOC_SUBSCRIBE_EVENT
-VIDIOC_UNSUBSCRIBE_EVENT
-
-	这些  ioctls 事件与 V4L2 中定义的一致。他们行为相同，唯一的
-	不同是他们只处理子设备产生的事件。根据驱动程序，这些事件也
-	可以通过一个（或多个） V4L2 设备节点上报。
-
-	要使用事件通知的子设备驱动，在注册子设备前必须在 v4l2_subdev::flags
-	中设置 V4L2_SUBDEV_USES_EVENTS 并在 v4l2_subdev::nevents
-	中初始化事件队列深度。注册完成后，事件会在 v4l2_subdev::devnode
-	设备节点中像通常一样被排队。
-
-	为正确支持事件机制，poll() 文件操作也应被实现。
-
-私有 ioctls
-
-	不在以上列表中的所有 ioctls 会通过 core::ioctl 操作直接传递
-	给子设备驱动。
-
-
-I2C 子设备驱动
--------------
-
-由于这些驱动很常见，所以内特提供了特定的辅助函数(v4l2-common.h)让这些
-设备的使用更加容易。
-
-添加 v4l2_subdev 支持的推荐方法是让 I2C 驱动将 v4l2_subdev 结构体
-嵌入到为每个 I2C 设备实例创建的状态结构体中。而最简单的设备没有状态
-结构体，此时可以直接创建一个 v4l2_subdev 结构体。
-
-一个典型的状态结构体如下所示（‘chipname’用芯片名代替）：
-
-struct chipname_state {
-	struct v4l2_subdev sd;
-	...  /* 附加的状态域*/
-};
-
-初始化 v4l2_subdev 结构体的方法如下：
-
-	v4l2_i2c_subdev_init(&state->sd, client, subdev_ops);
-
-这个函数将填充 v4l2_subdev 结构体中的所有域，并保证 v4l2_subdev 和
-i2c_client 都指向彼此。
-
-同时，你也应该为从 v4l2_subdev 指针找到 chipname_state 结构体指针
-添加一个辅助内联函数。
-
-static inline struct chipname_state *to_state(struct v4l2_subdev *sd)
-{
-	return container_of(sd, struct chipname_state, sd);
-}
-
-使用以下函数可以通过 v4l2_subdev 结构体指针获得 i2c_client 结构体
-指针：
-
-	struct i2c_client *client = v4l2_get_subdevdata(sd);
-
-而以下函数则相反，通过 i2c_client 结构体指针获得 v4l2_subdev 结构体
-指针：
-
-	struct v4l2_subdev *sd = i2c_get_clientdata(client);
-
-当 remove()函数被调用前，必须保证先调用 v4l2_device_unregister_subdev(sd)。
-此操作将会从桥驱动中注销子设备。即使子设备没有注册，调用此函数也是
-安全的。
-
-必须这样做的原因是：当桥驱动注销 i2c 适配器时，remove()回调函数
-会被那个适配器上的 i2c 设备调用。此后，相应的 v4l2_subdev 结构体
-就不存在了，所有它们必须先被注销。在 remove()回调函数中调用
-v4l2_device_unregister_subdev(sd)，可以保证执行总是正确的。
-
-
-桥驱动也有一些辅组函数可用：
-
-struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter,
-	       "module_foo", "chipid", 0x36, NULL);
-
-这个函数会加载给定的模块（如果没有模块需要加载，可以为 NULL），
-并用给定的 i2c 适配器结构体指针（i2c_adapter）和 器件地址（chip/address）
-作为参数调用 i2c_new_device()。如果一切顺利，则就在 v4l2_device
-中注册了子设备。
-
-你也可以利用 v4l2_i2c_new_subdev()的最后一个参数，传递一个可能的
-I2C 地址数组，让函数自动探测。这些探测地址只有在前一个参数为 0 的
-情况下使用。非零参数意味着你知道准确的 i2c 地址，所以此时无须进行
-探测。
-
-如果出错，两个函数都返回 NULL。
-
-注意：传递给 v4l2_i2c_new_subdev()的 chipid 通常与模块名一致。
-它允许你指定一个芯片的变体，比如“saa7114”或“saa7115”。一般通过
-i2c 驱动自动探测。chipid 的使用是在今后需要深入了解的事情。这个与
-i2c 驱动不同，较容易混淆。要知道支持哪些芯片变体，你可以查阅 i2c
-驱动代码的 i2c_device_id 表，上面列出了所有可能支持的芯片。
-
-还有两个辅助函数：
-
-v4l2_i2c_new_subdev_cfg：这个函数添加新的 irq 和 platform_data
-参数，并有‘addr’和‘probed_addrs’参数：如果 addr 非零，则被使用
-（不探测变体），否则 probed_addrs 中的地址将用于自动探测。
-
-例如：以下代码将会探测地址（0x10）：
-
-struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter,
-	       "module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10));
-
-v4l2_i2c_new_subdev_board 使用一个 i2c_board_info 结构体，将其
-替代 irq、platform_data 和 add r参数传递给 i2c 驱动。
-
-如果子设备支持 s_config 核心操作，这个操作会在子设备配置好之后以 irq 和
-platform_data 为参数调用。早期的 v4l2_i2c_new_(probed_)subdev 函数
-同样也会调用 s_config，但仅在 irq 为 0 且 platform_data 为 NULL 时。
-
-video_device结构体
------------------
-
-在 /dev 目录下的实际设备节点根据 video_device 结构体(v4l2-dev.h)
-创建。此结构体既可以动态分配也可以嵌入到一个更大的结构体中。
-
-动态分配方法如下：
-
-	struct video_device *vdev = video_device_alloc();
-
-	if (vdev == NULL)
-		return -ENOMEM;
-
-	vdev->release = video_device_release;
-
-如果将其嵌入到一个大结构体中，则必须自己实现 release()回调。
-
-	struct video_device *vdev = &my_vdev->vdev;
-
-	vdev->release = my_vdev_release;
-
-release()回调必须被设置，且在最后一个 video_device 用户退出之后
-被调用。
-
-默认的 video_device_release()回调只是调用 kfree 来释放之前分配的
-内存。
-
-你应该设置这些域：
-
-- v4l2_dev: 设置为 v4l2_device 父设备。
-
-- name: 设置为唯一的描述性设备名。
-
-- fops: 设置为已有的 v4l2_file_operations 结构体。
-
-- ioctl_ops: 如果你使用v4l2_ioctl_ops 来简化 ioctl 的维护
-  (强烈建议使用，且将来可能变为强制性的!)，然后设置你自己的
-  v4l2_ioctl_ops 结构体.
-
-- lock: 如果你要在驱动中实现所有的锁操作，则设为 NULL 。否则
-  就要设置一个指向 struct mutex_lock 结构体的指针，这个锁将
-  在 unlocked_ioctl 文件操作被调用前由内核获得，并在调用返回后
-  释放。详见下一节。
-
-- prio: 保持对优先级的跟踪。用于实现 VIDIOC_G/S_PRIORITY。如果
-  设置为 NULL，则会使用 v4l2_device 中的 v4l2_prio_state 结构体。
-  如果要对每个设备节点（组）实现独立的优先级，可以将其指向自己
-  实现的 v4l2_prio_state 结构体。
-
-- parent: 仅在使用 NULL 作为父设备结构体参数注册 v4l2_device 时
-  设置此参数。只有在一个硬件设备包含多一个 PCI 设备，共享同一个
-  v4l2_device 核心时才会发生。
-
-  cx88 驱动就是一个例子：一个 v4l2_device 结构体核心，被一个裸的
-  视频 PCI 设备(cx8800)和一个 MPEG PCI 设备(cx8802)共用。由于
-  v4l2_device 无法与特定的 PCI 设备关联，所有没有设置父设备。但当
-  video_device 配置后，就知道使用哪个父 PCI 设备了。
-
-如果你使用 v4l2_ioctl_ops，则应该在 v4l2_file_operations 结构体中
-设置 .unlocked_ioctl 指向 video_ioctl2。
-
-请勿使用 .ioctl！它已被废弃，今后将消失。
-
-某些情况下你要告诉核心：你在 v4l2_ioctl_ops 指定的某个函数应被忽略。
-你可以在 video_device_register 被调用前通过以下函数标记这个 ioctls。
-
-void v4l2_disable_ioctl(struct video_device *vdev, unsigned int cmd);
-
-基于外部因素（例如某个板卡已被使用），在不创建新结构体的情况下，你想
-要关闭 v4l2_ioctl_ops 中某个特性往往需要这个机制。
-
-v4l2_file_operations 结构体是 file_operations 的一个子集。其主要
-区别在于：因 inode 参数从未被使用，它将被忽略。
-
-如果需要与媒体框架整合，你必须通过调用 media_entity_pads_init() 初始化
-嵌入在 video_device 结构体中的 media_entity（entity 域）结构体：
-
-	struct media_pad *pad = &my_vdev->pad;
-	int err;
-
-	err = media_entity_pads_init(&vdev->entity, 1, pad);
-
-pads 数组必须预先初始化。没有必要手动设置 media_entity 的 type 和
-name 域。
-
-当（任何）子设备节点被打开/关闭，对 entity 的引用将被自动获取/释放。
-
-v4l2_file_operations 与锁
---------------------------
-
-你可以在 video_device 结构体中设置一个指向 mutex_lock 的指针。通常
-这既可是一个顶层互斥锁也可为设备节点自身的互斥锁。默认情况下，此锁
-用于 unlocked_ioctl，但为了使用 ioctls 你通过以下函数可禁用锁定：
-
-	void v4l2_disable_ioctl_locking(struct video_device *vdev, unsigned int cmd);
-
-例如: v4l2_disable_ioctl_locking(vdev, VIDIOC_DQBUF);
-
-你必须在注册 video_device 前调用这个函数。
-
-特别是对于 USB 驱动程序，某些命令（如设置控制）需要很长的时间，可能
-需要自行为缓冲区队列的 ioctls 实现锁定。
-
-如果你需要更细粒度的锁，你必须设置 mutex_lock 为 NULL，并完全自己实现
-锁机制。
-
-这完全由驱动开发者决定使用何种方法。然而，如果你的驱动存在长延时操作
-（例如，改变 USB 摄像头的曝光时间可能需要较长时间），而你又想让用户
-在等待长延时操作完成期间做其他的事，则你最好自己实现锁机制。
-
-如果指定一个锁，则所有 ioctl 操作将在这个锁的作用下串行执行。如果你
-使用 videobuf，则必须将同一个锁传递给 videobuf 队列初始化函数；如
-videobuf 必须等待一帧的到达，则可临时解锁并在这之后重新上锁。如果驱动
-也在代码执行期间等待，则可做同样的工作（临时解锁，再上锁）让其他进程
-可以在第一个进程阻塞时访问设备节点。
-
-在使用 videobuf2 的情况下，必须实现 wait_prepare 和 wait_finish 回调
-在适当的时候解锁/加锁。进一步来说，如果你在 video_device 结构体中使用
-锁，则必须在 wait_prepare 和 wait_finish 中对这个互斥锁进行解锁/加锁。
-
-热插拔的断开实现也必须在调用 v4l2_device_disconnect 前获得锁。
-
-video_device注册
----------------
-
-接下来你需要注册视频设备：这会为你创建一个字符设备。
-
-	err = video_register_device(vdev, VFL_TYPE_GRABBER, -1);
-	if (err) {
-		video_device_release(vdev); /* or kfree(my_vdev); */
-		return err;
-	}
-
-如果 v4l2_device 父设备的 mdev 域为非 NULL 值，视频设备实体将自动
-注册为媒体设备。
-
-注册哪种设备是根据类型（type）参数。存在以下类型：
-
-VFL_TYPE_GRABBER: 用于视频输入/输出设备的 videoX
-VFL_TYPE_VBI: 用于垂直消隐数据的 vbiX (例如，隐藏式字幕，图文电视)
-VFL_TYPE_RADIO: 用于广播调谐器的 radioX
-
-最后一个参数让你确定一个所控制设备的设备节点号数量(例如 videoX 中的 X)。
-通常你可以传入-1，让 v4l2 框架自己选择第一个空闲的编号。但是有时用户
-需要选择一个特定的节点号。驱动允许用户通过驱动模块参数选择一个特定的
-设备节点号是很普遍的。这个编号将会传递给这个函数，且 video_register_device
-将会试图选择这个设备节点号。如果这个编号被占用，下一个空闲的设备节点
-编号将被选中，并向内核日志中发送一个警告信息。
-
-另一个使用场景是当驱动创建多个设备时。这种情况下，对不同的视频设备在
-编号上使用不同的范围是很有用的。例如，视频捕获设备从 0 开始，视频
-输出设备从 16 开始。所以你可以使用最后一个参数来指定设备节点号最小值，
-而 v4l2 框架会试图选择第一个的空闲编号（等于或大于你提供的编号）。
-如果失败，则它会就选择第一个空闲的编号。
-
-由于这种情况下，你会忽略无法选择特定设备节点号的警告，则可调用
-video_register_device_no_warn() 函数避免警告信息的产生。
-
-只要设备节点被创建，一些属性也会同时创建。在 /sys/class/video4linux
-目录中你会找到这些设备。例如进入其中的 video0 目录，你会看到‘name’和
-‘index’属性。‘name’属性值就是 video_device 结构体中的‘name’域。
-
-‘index’属性值就是设备节点的索引值：每次调用 video_register_device()，
-索引值都递增 1 。第一个视频设备节点总是从索引值 0 开始。
-
-用户可以设置 udev 规则，利用索引属性生成花哨的设备名（例如：用‘mpegX’
-代表 MPEG 视频捕获设备节点）。
-
-在设备成功注册后，就可以使用这些域：
-
-- vfl_type: 传递给 video_register_device 的设备类型。
-- minor: 已指派的次设备号。
-- num: 设备节点编号 (例如 videoX 中的 X)。
-- index: 设备索引号。
-
-如果注册失败，你必须调用 video_device_release() 来释放已分配的
-video_device 结构体；如果 video_device 是嵌入在自己创建的结构体中，
-你也必须释放它。vdev->release() 回调不会在注册失败之后被调用，
-你也不应试图在注册失败后注销设备。
-
-
-video_device 注销
-----------------
-
-当视频设备节点已被移除，不论是卸载驱动还是USB设备断开，你都应注销
-它们：
-
-	video_unregister_device(vdev);
-
-这个操作将从 sysfs 中移除设备节点（导致 udev 将其从 /dev 中移除）。
-
-video_unregister_device() 返回之后，就无法完成打开操作。尽管如此，
-USB 设备的情况则不同，某些应用程序可能依然打开着其中一个已注销设备
-节点。所以在注销之后，所有文件操作（当然除了 release ）也应返回错误值。
-
-当最后一个视频设备节点的用户退出，则 vdev->release() 回调会被调用，
-并且你可以做最后的清理操作。
-
-不要忘记清理与视频设备相关的媒体入口（如果被初始化过）：
-
-	media_entity_cleanup(&vdev->entity);
-
-这可以在 release 回调中完成。
-
-
-video_device 辅助函数
----------------------
-
-一些有用的辅助函数如下：
-
-- file/video_device 私有数据
-
-你可以用以下函数在 video_device 结构体中设置/获取驱动私有数据：
-
-void *video_get_drvdata(struct video_device *vdev);
-void video_set_drvdata(struct video_device *vdev, void *data);
-
-注意：在调用 video_register_device() 前执行 video_set_drvdata()
-是安全的。
-
-而以下函数：
-
-struct video_device *video_devdata(struct file *file);
-
-返回 file 结构体中拥有的的 video_device 指针。
-
-video_drvdata 辅助函数结合了 video_get_drvdata 和 video_devdata
-的功能：
-
-void *video_drvdata(struct file *file);
-
-你可以使用如下代码从 video_device 结构体中获取 v4l2_device 结构体
-指针：
-
-struct v4l2_device *v4l2_dev = vdev->v4l2_dev;
-
-- 设备节点名
-
-video_device 设备节点在内核中的名称可以通过以下函数获得
-
-const char *video_device_node_name(struct video_device *vdev);
-
-这个名字被用户空间工具（例如 udev）作为提示信息使用。应尽可能使用
-此功能，而非访问 video_device::num 和 video_device::minor 域。
-
-
-视频缓冲辅助函数
----------------
-
-v4l2 核心 API 提供了一个处理视频缓冲的标准方法(称为“videobuf”)。
-这些方法使驱动可以通过统一的方式实现 read()、mmap() 和 overlay()。
-目前在设备上支持视频缓冲的方法有分散/聚集 DMA(videobuf-dma-sg)、
-线性 DMA(videobuf-dma-contig)以及大多用于 USB 设备的用 vmalloc
-分配的缓冲(videobuf-vmalloc)。
-
-请参阅 Documentation/video4linux/videobuf，以获得更多关于 videobuf
-层的使用信息。
-
-v4l2_fh 结构体
--------------
-
-v4l2_fh 结构体提供一个保存用于 V4L2 框架的文件句柄特定数据的简单方法。
-如果 video_device 标志，新驱动
-必须使用 v4l2_fh 结构体，因为它也用于实现优先级处理（VIDIOC_G/S_PRIORITY）。
-
-v4l2_fh 的用户（位于 V4l2 框架中，并非驱动）可通过测试
-video_device->flags 中的 V4L2_FL_USES_V4L2_FH 位得知驱动是否使用
-v4l2_fh 作为他的 file->private_data 指针。这个位会在调用 v4l2_fh_init()
-时被设置。
-
-v4l2_fh 结构体作为驱动自身文件句柄结构体的一部分被分配，且驱动在
-其打开函数中将 file->private_data 指向它。
-
-在许多情况下，v4l2_fh 结构体会嵌入到一个更大的结构体中。这钟情况下，
-应该在 open() 中调用 v4l2_fh_init+v4l2_fh_add，并在 release() 中
-调用 v4l2_fh_del+v4l2_fh_exit。
-
-驱动可以通过使用 container_of 宏提取他们自己的文件句柄结构体。例如：
-
-struct my_fh {
-	int blah;
-	struct v4l2_fh fh;
-};
-
-...
-
-int my_open(struct file *file)
-{
-	struct my_fh *my_fh;
-	struct video_device *vfd;
-	int ret;
-
-	...
-
-	my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
-
-	...
-
-	v4l2_fh_init(&my_fh->fh, vfd);
-
-	...
-
-	file->private_data = &my_fh->fh;
-	v4l2_fh_add(&my_fh->fh);
-	return 0;
-}
-
-int my_release(struct file *file)
-{
-	struct v4l2_fh *fh = file->private_data;
-	struct my_fh *my_fh = container_of(fh, struct my_fh, fh);
-
-	...
-	v4l2_fh_del(&my_fh->fh);
-	v4l2_fh_exit(&my_fh->fh);
-	kfree(my_fh);
-	return 0;
-}
-
-以下是 v4l2_fh 函数使用的简介：
-
-void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev)
-
-  初始化文件句柄。这*必须*在驱动的 v4l2_file_operations->open()
-  函数中执行。
-
-void v4l2_fh_add(struct v4l2_fh *fh)
-
-  添加一个 v4l2_fh 到 video_device 文件句柄列表。一旦文件句柄
-  初始化完成就必须调用。
-
-void v4l2_fh_del(struct v4l2_fh *fh)
-
-  从 video_device() 中解除文件句柄的关联。文件句柄的退出函数也
-  将被调用。
-
-void v4l2_fh_exit(struct v4l2_fh *fh)
-
-  清理文件句柄。在清理完 v4l2_fh 后，相关内存会被释放。
-
-
-如果 v4l2_fh 不是嵌入在其他结构体中的，则可以用这些辅助函数：
-
-int v4l2_fh_open(struct file *filp)
-
-  分配一个 v4l2_fh 结构体空间，初始化并将其添加到 file 结构体相关的
-  video_device 结构体中。
-
-int v4l2_fh_release(struct file *filp)
-
-  从 file 结构体相关的 video_device 结构体中删除 v4l2_fh ，清理
-  v4l2_fh 并释放空间。
-
-这两个函数可以插入到 v4l2_file_operation 的 open() 和 release()
-操作中。
-
-
-某些驱动需要在第一个文件句柄打开和最后一个文件句柄关闭的时候做些
-工作。所以加入了两个辅助函数以检查 v4l2_fh 结构体是否是相关设备
-节点打开的唯一文件句柄。
-
-int v4l2_fh_is_singular(struct v4l2_fh *fh)
-
-  如果此文件句柄是唯一打开的文件句柄，则返回 1 ，否则返回 0 。
-
-int v4l2_fh_is_singular_file(struct file *filp)
-
-  功能相同，但通过 filp->private_data 调用 v4l2_fh_is_singular。
-
-
-V4L2 事件机制
------------
-
-V4L2 事件机制提供了一个通用的方法将事件传递到用户空间。驱动必须使用
-v4l2_fh 才能支持 V4L2 事件机制。
-
-
-事件通过一个类型和选择 ID 来定义。ID 对应一个 V4L2 对象，例如
-一个控制 ID。如果未使用，则 ID 为 0。
-
-当用户订阅一个事件，驱动会为此分配一些 kevent 结构体。所以每个
-事件组（类型、ID）都会有自己的一套 kevent 结构体。这保证了如果
-一个驱动短时间内产生了许多同类事件，不会覆盖其他类型的事件。
-
-但如果你收到的事件数量大于同类事件 kevent 的保存数量，则最早的
-事件将被丢弃，并加入新事件。
-
-此外，v4l2_subscribed_event 结构体内部有可供驱动设置的 merge() 和
-replace() 回调，这些回调会在新事件产生且没有多余空间的时候被调用。
-replace() 回调让你可以将早期事件的净荷替换为新事件的净荷，将早期
-净荷的相关数据合并到替换进来的新净荷中。当该类型的事件仅分配了一个
-kevent 结构体时，它将被调用。merge() 回调让你可以合并最早的事件净荷
-到在它之后的那个事件净荷中。当该类型的事件分配了两个或更多 kevent
-结构体时，它将被调用。
-
-这种方法不会有状态信息丢失，只会导致中间步骤信息丢失。
-
-
-关于 replace/merge 回调的一个不错的例子在 v4l2-event.c 中：用于
-控制事件的 ctrls_replace() 和 ctrls_merge() 回调。
-
-注意：这些回调可以在中断上下文中调用，所以它们必须尽快完成并退出。
-
-有用的函数：
-
-void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev)
-
-  将事件加入视频设备的队列。驱动仅负责填充 type 和 data 域。
-  其他域由 V4L2 填充。
-
-int v4l2_event_subscribe(struct v4l2_fh *fh,
-			 struct v4l2_event_subscription *sub, unsigned elems,
-			 const struct v4l2_subscribed_event_ops *ops)
-
-  video_device->ioctl_ops->vidioc_subscribe_event 必须检测驱动能
-  产生特定 id 的事件。然后调用 v4l2_event_subscribe() 来订阅该事件。
-
-  elems 参数是该事件的队列大小。若为 0，V4L2 框架将会（根据事件类型）
-  填充默认值。
-
-  ops 参数允许驱动指定一系列回调：
-  * add:     当添加一个新监听者时调用（重复订阅同一个事件，此回调
-             仅被执行一次）。
-  * del:     当一个监听者停止监听时调用。
-  * replace: 用‘新’事件替换‘早期‘事件。
-  * merge:   将‘早期‘事件合并到‘新’事件中。
-  这四个调用都是可选的，如果不想指定任何回调，则 ops 可为 NULL。
-
-int v4l2_event_unsubscribe(struct v4l2_fh *fh,
-			   struct v4l2_event_subscription *sub)
-
-  v4l2_ioctl_ops 结构体中的 vidioc_unsubscribe_event 回调函数。
-  驱动程序可以直接使用 v4l2_event_unsubscribe() 实现退订事件过程。
-
-  特殊的 V4L2_EVENT_ALL 类型，可用于退订所有事件。驱动可能在特殊
-  情况下需要做此操作。
-
-int v4l2_event_pending(struct v4l2_fh *fh)
-
-  返回未决事件的数量。有助于实现轮询（poll）操作。
-
-事件通过 poll 系统调用传递到用户空间。驱动可用
-v4l2_fh->wait (wait_queue_head_t 类型)作为参数调用 poll_wait()。
-
-事件分为标准事件和私有事件。新的标准事件必须使用可用的最小事件类型
-编号。驱动必须从他们本类型的编号起始处分配事件。类型的编号起始为
-V4L2_EVENT_PRIVATE_START + n * 1000 ，其中 n 为可用最小编号。每个
-类型中的第一个事件类型编号是为以后的使用保留的，所以第一个可用事件
-类型编号是‘class base + 1’。
-
-V4L2 事件机制的使用实例可以在 OMAP3 ISP 的驱动
-(drivers/media/video/omap3isp)中找到。
diff --git a/Documentation/zh_CN/volatile-considered-harmful.txt b/Documentation/zh_CN/volatile-considered-harmful.txt
deleted file mode 100644
index 475125967197..000000000000
--- a/Documentation/zh_CN/volatile-considered-harmful.txt
+++ /dev/null
@@ -1,113 +0,0 @@
-Chinese translated version of Documentation/process/volatile-considered-harmful.rst
-
-If you have any comment or update to the content, please contact the
-original document maintainer directly.  However, if you have a problem
-communicating in English you can also ask the Chinese maintainer for
-help.  Contact the Chinese maintainer if this translation is outdated
-or if there is a problem with the translation.
-
-Maintainer: Jonathan Corbet 
-Chinese maintainer: Bryan Wu 
----------------------------------------------------------------------
-Documentation/process/volatile-considered-harmful.rst 的中文翻译
-
-如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
-交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
-译存在问题，请联系中文版维护者。
-
-英文版维护者： Jonathan Corbet 
-中文版维护者： 伍鹏  Bryan Wu 
-中文版翻译者： 伍鹏  Bryan Wu 
-中文版校译者： 张汉辉  Eugene Teo 
-               杨瑞  Dave Young 
-以下为正文
----------------------------------------------------------------------
-
-为什么不应该使用“volatile”类型
-------------------------------
-
-C程序员通常认为volatile表示某个变量可以在当前执行的线程之外被改变；因此，在内核
-中用到共享数据结构时，常常会有C程序员喜欢使用volatile这类变量。换句话说，他们经
-常会把volatile类型看成某种简易的原子变量，当然它们不是。在内核中使用volatile几
-乎总是错误的；本文档将解释为什么这样。
-
-理解volatile的关键是知道它的目的是用来消除优化，实际上很少有人真正需要这样的应
-用。在内核中，程序员必须防止意外的并发访问破坏共享的数据结构，这其实是一个完全
-不同的任务。用来防止意外并发访问的保护措施，可以更加高效的避免大多数优化相关的
-问题。
-
-像volatile一样，内核提供了很多原语来保证并发访问时的数据安全（自旋锁, 互斥量,内
-存屏障等等），同样可以防止意外的优化。如果可以正确使用这些内核原语，那么就没有
-必要再使用volatile。如果仍然必须使用volatile，那么几乎可以肯定在代码的某处有一
-个bug。在正确设计的内核代码中，volatile能带来的仅仅是使事情变慢。
-
-思考一下这段典型的内核代码：
-
-    spin_lock(&the_lock);
-    do_something_on(&shared_data);
-    do_something_else_with(&shared_data);
-    spin_unlock(&the_lock);
-
-如果所有的代码都遵循加锁规则，当持有the_lock的时候，不可能意外的改变shared_data的
-值。任何可能访问该数据的其他代码都会在这个锁上等待。自旋锁原语跟内存屏障一样—— 它
-们显式的用来书写成这样 —— 意味着数据访问不会跨越它们而被优化。所以本来编译器认为
-它知道在shared_data里面将有什么，但是因为spin_lock()调用跟内存屏障一样，会强制编
-译器忘记它所知道的一切。那么在访问这些数据时不会有优化的问题。
-
-如果shared_data被声名为volatile，锁操作将仍然是必须的。就算我们知道没有其他人正在
-使用它，编译器也将被阻止优化对临界区内shared_data的访问。在锁有效的同时，
-shared_data不是volatile的。在处理共享数据的时候，适当的锁操作可以不再需要
-volatile —— 并且是有潜在危害的。
-
-volatile的存储类型最初是为那些内存映射的I/O寄存器而定义。在内核里，寄存器访问也应
-该被锁保护，但是人们也不希望编译器“优化”临界区内的寄存器访问。内核里I/O的内存访问
-是通过访问函数完成的；不赞成通过指针对I/O内存的直接访问，并且不是在所有体系架构上
-都能工作。那些访问函数正是为了防止意外优化而写的，因此，再说一次，volatile类型不
-是必需的。
-
-另一种引起用户可能使用volatile的情况是当处理器正忙着等待一个变量的值。正确执行一
-个忙等待的方法是：
-
-    while (my_variable != what_i_want)
-        cpu_relax();
-
-cpu_relax()调用会降低CPU的能量消耗或者让位于超线程双处理器；它也作为内存屏障一样出
-现，所以，再一次，volatile不是必需的。当然，忙等待一开始就是一种反常规的做法。
-
-在内核中，一些稀少的情况下volatile仍然是有意义的：
-
-  - 在一些体系架构的系统上，允许直接的I/0内存访问，那么前面提到的访问函数可以使用
-    volatile。基本上，每一个访问函数调用它自己都是一个小的临界区域并且保证了按照
-    程序员期望的那样发生访问操作。
-
-  - 某些会改变内存的内联汇编代码虽然没有什么其他明显的附作用，但是有被GCC删除的可
-    能性。在汇编声明中加上volatile关键字可以防止这种删除操作。
-
-  - Jiffies变量是一种特殊情况，虽然每次引用它的时候都可以有不同的值，但读jiffies
-    变量时不需要任何特殊的加锁保护。所以jiffies变量可以使用volatile，但是不赞成
-    其他跟jiffies相同类型变量使用volatile。Jiffies被认为是一种“愚蠢的遗留物"
-    （Linus的话）因为解决这个问题比保持现状要麻烦的多。
-
-  - 由于某些I/0设备可能会修改连续一致的内存,所以有时,指向连续一致内存的数据结构
-    的指针需要正确的使用volatile。网络适配器使用的环状缓存区正是这类情形的一个例
-    子，其中适配器用改变指针来表示哪些描述符已经处理过了。
-
-对于大多代码，上述几种可以使用volatile的情况都不适用。所以，使用volatile是一种
-bug并且需要对这样的代码额外仔细检查。那些试图使用volatile的开发人员需要退一步想想
-他们真正想实现的是什么。
-
-非常欢迎删除volatile变量的补丁 － 只要证明这些补丁完整的考虑了并发问题。
-
-注释
-----
-
-[1] http://lwn.net/Articles/233481/
-[2] http://lwn.net/Articles/233482/
-
-致谢
-----
-
-最初由Randy Dunlap推动并作初步研究
-由Jonathan Corbet撰写
-参考Satyam Sharma，Johannes Stezenbach，Jesper Juhl，Heikki Orsila，
-H. Peter Anvin，Philipp Hahn和Stefan Richter的意见改善了本档。
-- 
cgit v1.2.3


From ba42c574fc8b803ec206785b7b91325c05810422 Mon Sep 17 00:00:00 2001
From: SeongJae Park 
Date: Tue, 8 Nov 2016 21:26:09 +0900
Subject: Documentation: Add HOWTO Korean translation into rst based build
 system

This commit adds Korean translation of HOWTO document into rst based
documentation build system.

Signed-off-by: SeongJae Park 
Signed-off-by: Jonathan Corbet 
---
 Documentation/index.rst                    |   8 +
 Documentation/translations/ko_KR/HOWTO     | 637 -----------------------------
 Documentation/translations/ko_KR/howto.rst | 637 +++++++++++++++++++++++++++++
 Documentation/translations/ko_KR/index.rst |  12 +
 4 files changed, 657 insertions(+), 637 deletions(-)
 delete mode 100644 Documentation/translations/ko_KR/HOWTO
 create mode 100644 Documentation/translations/ko_KR/howto.rst
 create mode 100644 Documentation/translations/ko_KR/index.rst

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 1dff9fa106bd..733bd9013541 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -59,6 +59,14 @@ needed).
    80211/index
    security/index
 
+Korean translations
+-------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   translations/ko_KR/index
+
 Indices and tables
 ==================
 
diff --git a/Documentation/translations/ko_KR/HOWTO b/Documentation/translations/ko_KR/HOWTO
deleted file mode 100644
index 3b0c15b277e0..000000000000
--- a/Documentation/translations/ko_KR/HOWTO
+++ /dev/null
@@ -1,637 +0,0 @@
-NOTE:
-This is a version of Documentation/process/howto.rst translated into korean
-This document is maintained by Minchan Kim 
-If you find any difference between this document and the original file or
-a problem with the translation, please contact the maintainer of this file.
-
-Please also note that the purpose of this file is to be easier to
-read for non English (read: korean) speakers and is not intended as
-a fork. So if you have any comments or updates for this file please
-try to update the original English file first.
-
-----------------------------------
-
-이 문서는
-Documentation/process/howto.rst
-의 한글 번역입니다.
-
-역자： 김민찬 
-감수： 이제이미 
-
-----------------------------------
-
-
-어떻게 리눅스 커널 개발을 하는가
-================================
-
-이 문서는 커널 개발에 있어 가장 중요한 문서이다. 이 문서는
-리눅스 커널 개발자가 되는 법과 리눅스 커널 개발 커뮤니티와 일하는
-법을 담고있다. 커널 프로그래밍의 기술적인 측면과 관련된 내용들은
-포함하지 않으려고 하였지만 올바른 길로 여러분을 안내하는 데는 도움이
-될 것이다.
-
-이 문서에서 오래된 것을 발견하면 문서의 아래쪽에 나열된 메인테이너에게
-패치를 보내달라.
-
-
-소개
-----
-
-자, 여러분은 리눅스 커널 개발자가 되는 법을 배우고 싶은가? 아니면
-상사로부터"이 장치를 위한 리눅스 드라이버를 작성하시오"라는 말을
-들었는가? 이 문서의 목적은 여러분이 겪게 될 과정과 커뮤니티와 협력하는
-법을 조언하여 여러분의 목적을 달성하기 위해 필요한 것 모두를 알려주기
-위함이다.
-
-커널은 대부분은 C로 작성되어 있고 몇몇 아키텍쳐의 의존적인 부분은
-어셈블리로 작성되어 있다. 커널 개발을 위해 C를 잘 이해하고 있어야 한다.
-여러분이 특정 아키텍쳐의 low-level 개발을 할 것이 아니라면
-어셈블리(특정 아키텍쳐)는 잘 알아야 할 필요는 없다.
-다음의 참고서적들은 기본에 충실한 C 교육이나 수년간의 경험에 견주지는
-못하지만 적어도 참고 용도로는 좋을 것이다
-
- - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
- - "Practical C Programming" by Steve Oualline [O'Reilly]
- - "C:  A Reference Manual" by Harbison and Steele [Prentice Hall]
-
-커널은 GNU C와 GNU 툴체인을 사용하여 작성되었다. 이 툴들은 ISO C89 표준을
-따르는 반면 표준에 있지 않은 많은 확장기능도 가지고 있다. 커널은 표준 C
-라이브러리와는 관계없이 freestanding C 환경이어서 C 표준의 일부는
-지원되지 않는다. 임의의 long long 나누기나 floating point는 지원되지 않는다.
-때론 이런 이유로 커널이 그런 확장 기능을 가진 툴체인을 가지고 만들어졌다는
-것이 이해하기 어려울 수도 있고 게다가 불행하게도 그런 것을 정확하게 설명하는
-어떤 참고문서도 있지 않다. 정보를 얻기 위해서는 gcc info (`info gcc`)페이지를
-살펴보라.
-
-여러분은 기존의 개발 커뮤니티와 협력하는 법을 배우려고 하고 있다는 것을
-기억하라. 코딩, 스타일, 함수에 관한 훌륭한 표준을 가진 사람들이 모인
-다양한 그룹이 있다. 이 표준들은 오랜동안 크고 지역적으로 분산된 팀들에
-의해 가장 좋은 방법으로 일하기 위하여 찾은 것을 기초로 만들어져 왔다.
-그 표준들은 문서화가 잘 되어있기 때문에 가능한한 미리 많은 표준들에
-관하여 배우려고 시도하라. 다른 사람들은 여러분이나 여러분의 회사가
-일하는 방식에 적응하는 것을 원하지는 않는다.
-
-
-법적 문제
----------
-
-리눅스 커널 소스 코드는 GPL로 배포(release)되었다. 소스트리의 메인
-디렉토리에 있는 라이센스에 관하여 상세하게 쓰여 있는 COPYING이라는
-파일을 봐라. 여러분이 라이센스에 관한 더 깊은 문제를 가지고 있다면
-리눅스 커널 메일링 리스트에 묻지말고 변호사와 연락하라. 메일링
-리스트들에 있는 사람들은 변호사가 아니기 때문에 법적 문제에 관하여
-그들의 말에 의지해서는 안된다.
-
-GPL에 관한 잦은 질문들과 답변들은 다음을 참조하라.
-
-    https://www.gnu.org/licenses/gpl-faq.html
-
-
-문서
-----
-
-리눅스 커널 소스 트리는 커널 커뮤니티와 협력하는 법을 배우기위해 훌륭한
-다양한 문서들을 가지고 있다. 새로운 기능들이 커널에 들어가게 될 때,
-그 기능을 어떻게 사용하는지에 관한 설명을 위하여 새로운 문서 파일을
-추가하는 것을 권장한다. 커널이 유저스페이스로 노출하는 인터페이스를
-변경하게 되면 변경을 설명하는 메뉴얼 페이지들에 대한 패치나 정보를
-mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다.
-
-다음은 커널 소스 트리에 있는 읽어야 할 파일들의 리스트이다.
-
-  README
-    이 파일은 리눅스 커널에 관하여 간단한 배경 설명과 커널을 설정하고
-    빌드하기 위해 필요한 것을 설명한다. 커널에 입문하는 사람들은 여기서
-    시작해야 한다.
-
-  :ref:`Documentation/process/changes.rst `
-    이 파일은 커널을 성공적으로 빌드하고 실행시키기 위해 필요한 다양한
-    소프트웨어 패키지들의 최소 버젼을 나열한다.
-
-  :ref:`Documentation/process/coding-style.rst `
-    이 문서는 리눅스 커널 코딩 스타일과 그렇게 한 몇몇 이유를 설명한다.
-    모든 새로운 코드는 이 문서에 가이드라인들을 따라야 한다. 대부분의
-    메인테이너들은 이 규칙을 따르는 패치들만을 받아들일 것이고 많은 사람들이
-    그 패치가 올바른 스타일일 경우만 코드를 검토할 것이다.
-
-  :ref:`Documentation/process/submitting-patches.rst ` 와 :ref:`Documentation/process/submitting-drivers.rst `
-    이 파일들은 성공적으로 패치를 만들고 보내는 법을 다음의 내용들로
-    굉장히 상세히 설명하고 있다(그러나 다음으로 한정되진 않는다).
-
-       - Email 내용들
-       - Email 양식
-       - 그것을 누구에게 보낼지
-
-    이러한 규칙들을 따르는 것이 성공(역자주: 패치가 받아들여 지는 것)을
-    보장하진 않는다(왜냐하면 모든 패치들은 내용과 스타일에 관하여
-    면밀히 검토되기 때문이다). 그러나 규칙을 따르지 않는다면 거의
-    성공하지도 못할 것이다.
-
-    올바른 패치들을 만드는 법에 관한 훌륭한 다른 문서들이 있다.
-
-    "The Perfect Patch"
-        https://www.ozlabs.org/~akpm/stuff/tpp.txt
-
-    "Linux kernel patch submission format"
-        http://linux.yyz.us/patch-format.html
-
-   :ref:`Documentation/process/stable-api-nonsense.rst `
-    이 문서는 의도적으로 커널이 불변하는 API를 갖지 않도록 결정한
-    이유를 설명하며 다음과 같은 것들을 포함한다.
-
-       - 서브시스템 shim-layer(호환성을 위해?)
-       - 운영체제들간의 드라이버 이식성
-       - 커널 소스 트리내에 빠른 변화를 늦추는 것(또는 빠른 변화를 막는 것)
-
-    이 문서는 리눅스 개발 철학을 이해하는데 필수적이며 다른 운영체제에서
-    리눅스로 전향하는 사람들에게는 매우 중요하다.
-
-
-  :ref:`Documentation/admin-guide/security-bugs.rst `
-    여러분들이 리눅스 커널의 보안 문제를 발견했다고 생각한다면 이 문서에
-    나온 단계에 따라서 커널 개발자들에게 알리고 그 문제를 해결할 수 있도록
-    도와 달라.
-
-  :ref:`Documentation/process/management-style.rst `
-    이 문서는 리눅스 커널 메인테이너들이 그들의 방법론에 녹아 있는
-    정신을 어떻게 공유하고 운영하는지를 설명한다. 이것은 커널 개발에 입문하는
-    모든 사람들(또는 커널 개발에 작은 호기심이라도 있는 사람들)이
-    읽어야 할 중요한 문서이다. 왜냐하면 이 문서는 커널 메인테이너들의
-    독특한 행동에 관하여 흔히 있는 오해들과 혼란들을 해소하고 있기
-    때문이다.
-
-  :ref:`Documentation/process/stable_kernel_rules.rst `
-    이 문서는 안정적인 커널 배포가 이루어지는 규칙을 설명하고 있으며
-    여러분들이 이러한 배포들 중 하나에 변경을 하길 원한다면
-    무엇을 해야 하는지를 설명한다.
-
-  :ref:`Documentation/process/kernel-docs.rst `
-    커널 개발에 관계된 외부 문서의 리스트이다. 커널 내의 포함된 문서들
-    중에 여러분이 찾고 싶은 문서를 발견하지 못할 경우 이 리스트를
-    살펴보라.
-
-  :ref:`Documentation/process/applying-patches.rst `
-    패치가 무엇이며 그것을 커널의 다른 개발 브랜치들에 어떻게
-    적용하는지에 관하여 자세히 설명하고 있는 좋은 입문서이다.
-
-커널은 소스 코드 그 자체에서 또는 이것과 같은 ReStructuredText 마크업 (ReST) 을
-통해 자동적으로 만들어질 수 있는 많은 문서들을 가지고 있다. 이것은 커널 내의
-API에 대한 모든 설명, 그리고 락킹을 올바르게 처리하는 법에 관한 규칙을 포함하고
-있다.
-
-모든 그런 문서들은 커널 소스 디렉토리에서 다음 커맨드를 실행하는 것을 통해 PDF
-나 HTML 의 형태로 만들어질 수 있다::
-
-         make pdfdocs
-         make htmldocs
-
-ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된다.  해당
-문서들은 다음의 커맨드를 사용하면 LaTeX 이나 ePub 로도 만들어질 수 있다::
-
-         make latexdocs
-         make epubdocs
-
-현재, ReST 로의 변환이 진행중인, DocBook 으로 쓰인 문서들이 존재한다. 그런
-문서들은 Documentation/DocBook/ 디렉토리 안에 생성될 것이고 다음 커맨드를 통해
-Postscript 나 man page 로도 만들어질 수 있다::
-
-         make psdocs
-         make mandocs
-
-커널 개발자가 되는 것
----------------------
-
-여러분이 리눅스 커널 개발에 관하여 아무것도 모른다면 Linux KernelNewbies
-프로젝트를 봐야 한다.
-
-    https://kernelnewbies.org
-
-그곳은 거의 모든 종류의 기본적인 커널 개발 질문들(질문하기 전에 먼저
-아카이브를 찾아봐라. 과거에 이미 답변되었을 수도 있다)을 할 수 있는 도움이
-될만한 메일링 리스트가 있다. 또한 실시간으로 질문 할 수 있는 IRC 채널도
-가지고 있으며 리눅스 커널 개발을 배우는 데 유용한 문서들을 보유하고 있다.
-
-웹사이트는 코드구성, 서브시스템들, 그리고 현재 프로젝트들
-(트리 내, 외부에 존재하는)에 관한 기본적인 정보들을 가지고 있다. 또한
-그곳은 커널 컴파일이나 패치를 하는 법과 같은 기본적인 것들을  설명한다.
-
-여러분이 어디서 시작해야 할진 모르지만 커널 개발 커뮤니티에 참여할 수
-있는 일들을 찾길 원한다면 리눅스 커널 Janitor 프로젝트를 살펴봐라.
-
-	https://kernelnewbies.org/KernelJanitors
-
-그곳은 시작하기에 훌륭한 장소이다. 그곳은 리눅스 커널 소스 트리내에
-간단히 정리되고 수정될 수 있는 문제들에 관하여 설명한다. 여러분은 이
-프로젝트를 대표하는 개발자들과 일하면서 자신의 패치를 리눅스 커널 트리에
-반영하기 위한 기본적인 것들을 배우게 될것이며 여러분이 아직 아이디어를
-가지고 있지 않다면 다음에 무엇을 해야할지에 관한 방향을 배울 수 있을
-것이다.
-
-여러분들이 이미 커널 트리에 반영하길 원하는 코드 묶음을 가지고 있지만
-올바른 포맷으로 포장하는데 도움이 필요하다면 그러한 문제를 돕기 위해
-만들어진 kernel-mentors 프로젝트가 있다. 그곳은 메일링 리스트이며
-다음에서 참조할 수 있다.
-
-         https://selenic.com/mailman/listinfo/kernel-mentors
-
-리눅스 커널 코드에 실제 변경을 하기 전에 반드시 그 코드가 어떻게
-동작하는지 이해하고 있어야 한다. 코드를 분석하기 위하여 특정한 툴의
-도움을 빌려서라도 코드를 직접 읽는 것보다 좋은 것은 없다(대부분의
-자잘한 부분들은 잘 코멘트되어 있다). 그런 툴들 중에 특히 추천할만한
-것은 Linux Cross-Reference project이며 그것은 자기 참조 방식이며
-소스코드를 인덱스된 웹 페이지들의 형태로 보여준다. 최신의 멋진 커널
-코드 저장소는 다음을 통하여 참조할 수 있다.
-
-      http://lxr.free-electrons.com/
-
-
-개발 프로세스
--------------
-
-리눅스 커널 개발 프로세스는 현재 몇몇 다른 메인 커널 "브랜치들"과
-서브시스템에 특화된 커널 브랜치들로 구성된다. 몇몇 다른 메인
-브랜치들은 다음과 같다.
-
-  - main 4.x 커널 트리
-  - 4.x.y - 안정된 커널 트리
-  - 4.x -git 커널 패치들
-  - 서브시스템을 위한 커널 트리들과 패치들
-  - 4.x - 통합 테스트를 위한 next 커널 트리
-
-4.x 커널 트리
-~~~~~~~~~~~~~
-
-4.x 커널들은 Linus Torvalds가 관리하며 https://kernel.org 의
-pub/linux/kernel/v4.x/ 디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다.
-
-  - 새로운 커널이 배포되자마자 2주의 시간이 주어진다. 이 기간동은
-    메인테이너들은 큰 diff들을 Linus에게 제출할 수 있다. 대개 이 패치들은
-    몇 주 동안 -next 커널내에 이미 있었던 것들이다. 큰 변경들을 제출하는 데
-    선호되는 방법은  git(커널의 소스 관리 툴, 더 많은 정보들은
-    https://git-scm.com/ 에서 참조할 수 있다)를 사용하는 것이지만 순수한
-    패치파일의 형식으로 보내는 것도 무관하다.
-  - 2주 후에 -rc1 커널이 배포되며 지금부터는 전체 커널의 안정성에 영향을
-    미칠수 있는 새로운 기능들을 포함하지 않는 패치들만이 추가될 수 있다.
-    완전히 새로운 드라이버(혹은 파일시스템)는 -rc1 이후에만 받아들여진다는
-    것을 기억해라. 왜냐하면 변경이 자체내에서만 발생하고 추가된 코드가
-    드라이버 외부의 다른 부분에는 영향을 주지 않으므로 그런 변경은
-    회귀(역자주: 이전에는 존재하지 않았지만 새로운 기능추가나 변경으로 인해
-    생겨난 버그)를 일으킬 만한 위험을 가지고 있지 않기 때문이다. -rc1이
-    배포된 이후에 git를 사용하여 패치들을 Linus에게 보낼수 있지만 패치들은
-    공식적인 메일링 리스트로 보내서 검토를 받을 필요가 있다.
-  - 새로운 -rc는 Linus가 현재 git tree가 테스트 하기에 충분히 안정된 상태에
-    있다고 판단될 때마다 배포된다. 목표는 새로운 -rc 커널을 매주 배포하는
-    것이다.
-  - 이러한 프로세스는 커널이 "준비(ready)"되었다고 여겨질때까지 계속된다.
-    프로세스는 대체로 6주간 지속된다.
-
-커널 배포에 있어서 언급할만한 가치가 있는 리눅스 커널 메일링 리스트의
-Andrew Morton의 글이 있다.
-
-        *"커널이 언제 배포될지는 아무도 모른다. 왜냐하면 배포는 알려진
-         버그의 상황에 따라 배포되는 것이지 미리정해 놓은 시간에 따라
-         배포되는 것은 아니기 때문이다."*
-
-4.x.y - 안정 커널 트리
-~~~~~~~~~~~~~~~~~~~~~~
-
-3 자리 숫자로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 4.x
-커널에서 발견된 큰 회귀들이나 보안 문제들 중 비교적 작고 중요한 수정들을
-포함한다.
-
-이것은 가장 최근의 안정적인 커널을 원하는 사용자에게 추천되는 브랜치이며,
-개발/실험적 버젼을 테스트하는 것을 돕고자 하는 사용자들과는 별로 관련이 없다.
-
-어떤 4.x.y 커널도 사용할 수 없다면 그때는 가장 높은 숫자의 4.x
-커널이 현재의 안정 커널이다.
-
-4.x.y는 "stable" 팀에 의해 관리되며 거의 매번 격주로
-배포된다.
-
-커널 트리 문서들 내에 Documentation/process/stable-kernel-rules.rst 파일은 어떤
-종류의 변경들이 -stable 트리로 들어왔는지와 배포 프로세스가 어떻게
-진행되는지를 설명한다.
-
-4.x -git 패치들
-~~~~~~~~~~~~~~~
-
-git 저장소(그러므로 -git이라는 이름이 붙음)에는 날마다 관리되는 Linus의
-커널 트리의 snapshot 들이 있다. 이 패치들은 일반적으로 날마다 배포되며
-Linus의 트리의 현재 상태를 나타낸다. 이 패치들은 정상적인지 조금도
-살펴보지 않고 자동적으로 생성된 것이므로 -rc 커널들 보다도 더 실험적이다.
-
-서브시스템 커널 트리들과 패치들
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-다양한 커널 서브시스템의 메인테이너들 --- 그리고 많은 커널 서브시스템 개발자들
---- 은 그들의 현재 개발 상태를 소스 저장소로 노출한다. 이를 통해 다른 사람들도
-커널의 다른 영역에 어떤 변화가 이루어지고 있는지 알 수 있다. 급속히 개발이
-진행되는 영역이 있고 그렇지 않은 영역이 있으므로, 개발자는 다른 개발자가 제출한
-수정 사항과 자신의 수정사항의 충돌이나 동일한 일을 동시에 두사람이 따로
-진행하는 사태를 방지하기 위해 급속히 개발이 진행되고 있는 영역에 작업의
-베이스를 맞춰줄 것이 요구된다.
-
-대부분의 이러한 저장소는 git 트리지만, git이 아닌 SCM으로 관리되거나, quilt
-시리즈로 제공되는 패치들도 존재한다. 이러한 서브시스템 저장소들은 MAINTAINERS
-파일에 나열되어 있다. 대부분은 https://git.kernel.org 에서 볼 수 있다.
-
-제안된 패치는 서브시스템 트리에 커밋되기 전에 메일링 리스트를 통해
-리뷰된다(아래의 관련 섹션을 참고하기 바란다). 일부 커널 서브시스템의 경우, 이
-리뷰 프로세스는 patchwork라는 도구를 통해 추적된다. patchwork은 등록된 패치와
-패치에 대한 코멘트, 패치의 버전을 볼 수 있는 웹 인터페이스를 제공하고,
-메인테이너는 패치를 리뷰 중, 리뷰 통과, 또는 반려됨으로 표시할 수 있다.
-대부분의 이러한 patchwork 사이트는 https://patchwork.kernel.org/ 또는
-http://patchwork.ozlabs.org/ 에 나열되어 있다.
-
-4.x - 통합 테스트를 위한 next 커널 트리
----------------------------------------
-서브시스템 트리들의 변경사항들은 mainline 4.x 트리로 들어오기 전에 통합
-테스트를 거쳐야 한다. 이런 목적으로, 모든 서브시스템 트리의 변경사항을 거의
-매일 받아가는 특수한 테스트 저장소가 존재한다:
-
-       https://git.kernel.org/?p=linux/kernel/git/sfr/linux-next.git
-
-이런 식으로, -next 커널을 통해 다음 머지 기간에 메인라인 커널에 어떤 변경이
-가해질 것인지 간략히 알 수 있다. 모험심 강한 테스터라면 -next 커널에서 테스트를
-수행하는 것도 좋을 것이다.
-
-
-버그 보고
----------
-
-https://bugzilla.kernel.org는 리눅스 커널 개발자들이 커널의 버그를 추적하는
-곳이다. 사용자들은 발견한 모든 버그들을 보고하기 위하여 이 툴을 사용할 것을
-권장한다.  kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라.
-
-    https://bugzilla.kernel.org/page.cgi?id=faq.html
-
-메인 커널 소스 디렉토리에 있는 admin-guide/reporting-bugs.rst 파일은 커널 버그라고 생각되는
-것을 보고하는 방법에 관한 좋은 템플릿이며 문제를 추적하기 위해서 커널
-개발자들이 필요로 하는 정보가 무엇들인지를 상세히 설명하고 있다.
-
-
-버그 리포트들의 관리
---------------------
-
-여러분의 해킹 기술을 연습하는 가장 좋은 방법 중의 하는 다른 사람들이
-보고한 버그들을 수정하는 것이다. 여러분은 커널을 더욱 안정화시키는데
-도움을 줄 뿐만이 아니라 실제있는 문제들을 수정하는 법을 배우게 되고
-그와 함께 여러분들의 기술은 향상될 것이며 다른 개발자들이 여러분의
-존재에 대해 알게 될 것이다. 버그를 수정하는 것은 개발자들  사이에서
-점수를 얻을 수 있는 가장 좋은 방법중의 하나이다. 왜냐하면 많은 사람들은
-다른 사람들의 버그들을 수정하기 위하여 시간을 낭비하지 않기 때문이다.
-
-이미 보고된 버그 리포트들을 가지고 작업하기 위해서 https://bugzilla.kernel.org
-를 참조하라. 여러분이 앞으로 생겨날 버그 리포트들의 조언자가 되길 원한다면
-bugme-new 메일링 리스트나(새로운 버그 리포트들만이 이곳에서 메일로 전해진다)
-bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메일로 전해진다)
-에 등록하면 된다.
-
-      https://lists.linux-foundation.org/mailman/listinfo/bugme-new
-
-      https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
-
-
-
-메일링 리스트들
----------------
-
-위의 몇몇 문서들이 설명하였지만 핵심 커널 개발자들의 대다수는
-리눅스 커널 메일링 리스트에 참여하고 있다. 리스트에 등록하고 해지하는
-방법에 관한 자세한 사항은 다음에서 참조할 수 있다.
-
-    http://vger.kernel.org/vger-lists.html#linux-kernel
-
-웹상의 많은 다른 곳에도 메일링 리스트의 아카이브들이 있다.
-이러한 아카이브들을 찾으려면 검색 엔진을 사용하라. 예를 들어:
-
-      http://dir.gmane.org/gmane.linux.kernel
-
-여러분이 새로운 문제에 관해 리스트에 올리기 전에 말하고 싶은 주제에 관한
-것을 아카이브에서 먼저 찾아보기를 강력히 권장한다. 이미 상세하게 토론된 많은
-것들이 메일링 리스트의 아카이브에 기록되어 있다.
-
-각각의 커널 서브시스템들의 대부분은 자신들의 개발에 관한 노력들로 이루어진
-분리된 메일링 리스트를 따로 가지고 있다. 다른 그룹들이 무슨 리스트를 가지고
-있는지는 MAINTAINERS 파일을 참조하라.
-
-많은 리스트들은 kernel.org에서 호스트되고 있다. 그 정보들은 다음에서 참조될 수 있다.
-
-         http://vger.kernel.org/vger-lists.html
-
-리스트들을 사용할 때는 올바른 예절을 따를 것을 유념해라.
-대단하진 않지만 다음 URL은 리스트(혹은 모든 리스트)와 대화하는 몇몇 간단한
-가이드라인을 가지고 있다.
-
-         http://www.albion.com/netiquette/
-
-여러 사람들이 여러분의 메일에 응답한다면 CC: 즉 수신 리스트는 꽤 커지게
-될 것이다. 아무 이유없이 CC에서 어떤 사람도 제거하거나 리스트 주소로만
-회신하지 마라. 메일을 보낸 사람으로서 하나를 받고 리스트로부터 또
-하나를 받아 두번 받는 것에 익숙하여 있으니 mail-header를 조작하려고 하지
-말아라. 사람들은 그런 것을 좋아하지 않을 것이다.
-
-여러분의 회신의 문맥을 원래대로 유지해야 한다. 여러분들의 회신의 윗부분에
-"John 커널해커는 작성했다...."를 유지하며 여러분들의 의견을 그 메일의 윗부분에
-작성하지 말고 각 인용한 단락들 사이에 넣어라.
-
-여러분들이 패치들을 메일에 넣는다면 그것들은 Documentation/process/submitting-patches.rst에
-나와있는데로 명백히(plain) 읽을 수 있는 텍스트여야 한다. 커널 개발자들은
-첨부파일이나 압축된 패치들을 원하지 않는다. 그들은 여러분들의 패치의
-각 라인 단위로 코멘트를 하길 원하며 압축하거나 첨부하지 않고 보내는 것이
-그렇게 할 수 있는 유일한 방법이다. 여러분들이 사용하는 메일 프로그램이
-스페이스나 탭 문자들을 조작하지 않는지 확인하라. 가장 좋은 첫 테스트는
-메일을 자신에게 보내보고 스스로 그 패치를 적용해보라. 그것이 동작하지
-않는다면 여러분의 메일 프로그램을 고치던가 제대로 동작하는 프로그램으로
-바꾸어라.
-
-무엇보다도 메일링 리스트의 다른 구독자들에게 보여주려 한다는 것을 기억하라.
-
-
-커뮤니티와 협력하는 법
-----------------------
-
-커널 커뮤니티의 목적은 가능한한 가장 좋은 커널을 제공하는 것이다. 여러분이
-받아들여질 패치를 제출하게 되면 그 패치의 기술적인 이점으로 검토될 것이다.
-그럼 여러분들은 무엇을 기대하고 있어야 하는가?
-
- - 비판
- - 의견
- - 변경을 위한 요구
- - 당위성을 위한 요구
- - 침묵
-
-기억하라. 이것들은 여러분의 패치가 커널로 들어가기 위한 과정이다. 여러분의
-패치들은 비판과 다른 의견을 받을 수 있고 그것들을 기술적인 레벨로 평가하고
-재작업하거나 또는 왜 수정하면 안되는지에 관하여 명료하고 간결한 이유를
-말할 수 있어야 한다. 여러분이 제출한 것에 어떤 응답도 있지 않다면 몇 일을
-기다려보고 다시 시도해라. 때론 너무 많은 메일들 속에 묻혀버리기도 한다.
-
-여러분은 무엇을 해서는 안되는가?
-
- - 여러분의 패치가 아무 질문 없이 받아들여지기를 기대하는 것
- - 방어적이 되는 것
- - 의견을 무시하는 것
- - 요청된 변경을 하지 않고 패치를 다시 제출하는 것
-
-가능한한 가장 좋은 기술적인 해답을 찾고 있는 커뮤니티에서는 항상
-어떤 패치가 얼마나 좋은지에 관하여 다른 의견들이 있을 수 있다. 여러분은
-협조적이어야 하고 기꺼이 여러분의 생각을 커널 내에 맞추어야 한다. 아니면
-적어도 여러분의 것이 가치있다는 것을 증명하여야 한다. 잘못된 것도 여러분이
-올바른 방향의 해결책으로 이끌어갈 의지가 있다면 받아들여질 것이라는 점을
-기억하라.
-
-여러분의 첫 패치에 여러분이 수정해야하는 십여개 정도의 회신이 오는
-경우도 흔하다. 이것은 여러분의 패치가 받아들여지지 않을 것이라는 것을
-의미하는 것이 아니고 개인적으로 여러분에게 감정이 있어서 그러는 것도
-아니다. 간단히 여러분의 패치에 제기된 문제들을 수정하고 그것을 다시
-보내라.
-
-
-커널 커뮤니티와 기업 조직간의 차이점
-------------------------------------
-커널 커뮤니티는 가장 전통적인 회사의 개발 환경과는 다르다. 여기에 여러분들의
-문제를 피하기 위한 목록이 있다.
-
-  여러분들이 제안한 변경들에 관하여 말할 때 좋은 것들 :
-
-    - "이것은 여러 문제들을 해결합니다."
-    - "이것은 2000 라인의 코드를 줄입니다."
-    - "이것은 내가 말하려는 것에 관해 설명하는 패치입니다."
-    - "나는 5개의 다른 아키텍쳐에서 그것을 테스트 했으므로..."
-    - "여기에 일련의 작은 패치들이 있으므로..."
-    - "이것은 일반적인 머신에서 성능을 향상함으로..."
-
-  여러분들이 말할 때 피해야 할 좋지 않은 것들 :
-
-    - "우리는 그것을 AIX/ptx/Solaris에서 이러한 방법으로 했다. 그러므로 그것은 좋은 것임에 틀림없다..."
-    - "나는 20년동안 이것을 해왔다. 그러므로..."
-    - "이것은 돈을 벌기위해 나의 회사가 필요로 하는 것이다."
-    - "이것은 우리의 엔터프라이즈 상품 라인을 위한 것이다."
-    - "여기에 나의 생각을 말하고 있는 1000 페이지 설계 문서가 있다."
-    - "나는 6달동안 이것을 했으니..."
-    - "여기에 5000 라인 짜리 패치가 있으니..."
-    - "나는 현재 뒤죽박죽인 것을 재작성했다. 그리고 여기에..."
-    - "나는 마감시한을 가지고 있으므로 이 패치는 지금 적용될 필요가 있다."
-
-커널 커뮤니티가 전통적인 소프트웨어 엔지니어링 개발 환경들과
-또 다른 점은 얼굴을 보지 않고 일한다는 점이다. 이메일과 irc를 대화의
-주요수단으로 사용하는 것의 한가지 장점은 성별이나 인종의 차별이
-없다는 것이다. 리눅스 커널의 작업 환경에서는 단지 이메일 주소만
-알수 있기 때문에 여성과 소수 민족들도 모두 받아들여진다. 국제적으로
-일하게 되는 측면은 사람의 이름에 근거하여 성별을 추측할 수 없게
-하기때문에 차별을 없애는 데 도움을 준다. Andrea라는 이름을 가진 남자와
-Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅스 커널에서
-작업하며 생각을 표현해왔던 대부분의 여성들은 긍정적인 경험을 가지고
-있다.
-
-언어 장벽은 영어에 익숙하지 않은 몇몇 사람들에게 문제가 될 수도 있다.
-언어의 훌륭한 구사는 메일링 리스트에서 올바르게 자신의 생각을
-표현하기 위하여 필요하다. 그래서 여러분은 이메일을 보내기 전에
-영어를 올바르게 사용하고 있는지를 체크하는 것이 바람직하다.
-
-
-여러분의 변경을 나누어라
-------------------------
-
-리눅스 커널 커뮤니티는 한꺼번에 굉장히 큰 코드의 묶음(chunk)을 쉽게
-받아들이지 않는다. 변경은 적절하게 소개되고, 검토되고, 각각의
-부분으로 작게 나누어져야 한다. 이것은 회사에서 하는 것과는 정확히
-반대되는 것이다. 여러분들의 제안은 개발 초기에 일찍이 소개되야 한다.
-그래서 여러분들은 자신이 하고 있는 것에 관하여 피드백을 받을 수 있게
-된다. 커뮤니티가 여러분들이 커뮤니티와 함께 일하고 있다는 것을
-느끼도록 만들고 커뮤니티가 여러분의 기능을 위한 쓰레기 장으로써
-사용되지 않고 있다는 것을 느끼게 하자. 그러나 메일링 리스트에 한번에
-50개의 이메일을 보내지는 말아라. 여러분들의 일련의 패치들은 항상
-더 작아야 한다.
-
-패치를 나누는 이유는 다음과 같다.
-
-1) 작은 패치들은 여러분의 패치들이 적용될 수 있는 확률을 높여준다.
-   왜냐하면 다른 사람들은 정확성을 검증하기 위하여 많은 시간과 노력을
-   들이기를 원하지 않는다. 5줄의 패치는 메인테이너가 거의 몇 초간 힐끗
-   보면 적용될 수 있다. 그러나 500 줄의 패치는 정확성을 검토하기 위하여
-   몇시간이 걸릴 수도 있다(걸리는 시간은 패치의 크기 혹은 다른 것에
-   비례하여 기하급수적으로 늘어난다).
-
-   패치를 작게 만드는 것은 무엇인가 잘못되었을 때 디버그하는 것을
-   쉽게 만든다. 즉, 그렇게 만드는 것은 매우 큰 패치를 적용한 후에
-   조사하는 것 보다 작은 패치를 적용한 후에 (그리고 몇몇의 것이
-   깨졌을 때) 하나씩 패치들을 제거해가며 디버그 하기 쉽도록 만들어 준다.
-
-2) 작은 패치들을 보내는 것뿐만 아니라 패치들을 제출하기전에 재작성하고
-   간단하게(혹은 간단한게 재배치하여) 하는 것도 중요하다.
-
-여기에 커널 개발자 Al Viro의 이야기가 있다.
-
-    *"학생의 수학 숙제를 채점하는 선생님을 생각해보라. 선생님은 학생들이
-    답을 얻을때까지 겪은 시행착오를 보길 원하지 않는다. 선생님들은
-    간결하고 가장 뛰어난 답을 보길 원한다. 훌륭한 학생은 이것을 알고
-    마지막으로 답을 얻기 전 중간 과정들을 제출하진 않는다.*
-
-    *커널 개발도 마찬가지이다. 메인테이너들과 검토하는 사람들은 문제를
-    풀어나가는 과정속에 숨겨진 과정을 보길 원하진 않는다. 그들은
-    간결하고 멋진 답을 보길 원한다."*
-
-커뮤니티와 협력하며 뛰어난 답을 찾는 것과 여러분들의 끝마치지 못한 작업들
-사이에 균형을 유지해야 하는 것은 어려울지도 모른다. 그러므로 프로세스의
-초반에 여러분의 작업을 향상시키기위한 피드백을 얻는 것 뿐만 아니라
-여러분들의 변경들을 작은 묶음으로 유지해서 심지어는 여러분의 작업의
-모든 부분이 지금은 포함될 준비가 되어있지 않지만 작은 부분은 벌써
-받아들여질 수 있도록 유지하는 것이 바람직하다.
-
-또한 완성되지 않았고 "나중에 수정될 것이다." 와 같은 것들을 포함하는
-패치들은 받아들여지지 않을 것이라는 점을 유념하라.
-
-
-변경을 정당화해라
------------------
-
-여러분들의 나누어진 패치들을 리눅스 커뮤니티가 왜 반영해야 하는지를
-알도록 하는 것은 매우 중요하다. 새로운 기능들이 필요하고 유용하다는
-것은 반드시 그에 합당한 이유가 있어야 한다.
-
-
-변경을 문서화해라
------------------
-
-여러분이 패치를 보내려 할때는 여러분이 무엇을 말하려고 하는지를 충분히
-생각하여 이메일을 작성해야 한다. 이 정보는 패치를 위한 ChangeLog가 될
-것이다. 그리고 항상 그 내용을 보길 원하는 모든 사람들을 위해 보존될
-것이다. 패치는 완벽하게 다음과 같은 내용들을 포함하여 설명해야 한다.
-
-  - 변경이 왜 필요한지
-  - 패치에 관한 전체 설계 접근(approach)
-  - 구현 상세들
-  - 테스트 결과들
-
-이것이 무엇인지 더 자세한 것을 알고 싶다면 다음 문서의 ChageLog 항을 봐라.
-
-   "The Perfect Patch"
-
-    http://www.ozlabs.org/~akpm/stuff/tpp.txt
-
-
-이 모든 것을 하는 것은 매우 어려운 일이다. 완벽히 소화하는 데는 적어도 몇년이
-걸릴 수도 있다. 많은 인내와 결심이 필요한 계속되는 개선의 과정이다. 그러나
-가능한한 포기하지 말라. 많은 사람들은 이전부터 해왔던 것이고 그 사람들도
-정확하게 여러분들이 지금 서 있는 그 곳부터  시작했었다.
-
-
-
-
-----------
-
-"개발 프로세스"(https://lwn.net/Articles/94386/) 섹션을
-작성하는데 있어 참고할 문서를 사용하도록 허락해준 Paolo Ciarrocchi에게
-감사한다. 여러분들이 말해야 할 것과 말해서는 안되는 것의 목록 중 일부를 제공해준
-Randy Dunlap과 Gerrit Huizenga에게 감사한다. 또한 검토와 의견 그리고
-공헌을 아끼지 않은 Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers,
-Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi Kleen,
-Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop,
-David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard에게도 감사를 전한다.
-그들의 도움이 없었다면 이 문서는 존재하지 않았을 것이다.
-
-
-
-메인테이너: Greg Kroah-Hartman 
diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst
new file mode 100644
index 000000000000..3b0c15b277e0
--- /dev/null
+++ b/Documentation/translations/ko_KR/howto.rst
@@ -0,0 +1,637 @@
+NOTE:
+This is a version of Documentation/process/howto.rst translated into korean
+This document is maintained by Minchan Kim 
+If you find any difference between this document and the original file or
+a problem with the translation, please contact the maintainer of this file.
+
+Please also note that the purpose of this file is to be easier to
+read for non English (read: korean) speakers and is not intended as
+a fork. So if you have any comments or updates for this file please
+try to update the original English file first.
+
+----------------------------------
+
+이 문서는
+Documentation/process/howto.rst
+의 한글 번역입니다.
+
+역자： 김민찬 
+감수： 이제이미 
+
+----------------------------------
+
+
+어떻게 리눅스 커널 개발을 하는가
+================================
+
+이 문서는 커널 개발에 있어 가장 중요한 문서이다. 이 문서는
+리눅스 커널 개발자가 되는 법과 리눅스 커널 개발 커뮤니티와 일하는
+법을 담고있다. 커널 프로그래밍의 기술적인 측면과 관련된 내용들은
+포함하지 않으려고 하였지만 올바른 길로 여러분을 안내하는 데는 도움이
+될 것이다.
+
+이 문서에서 오래된 것을 발견하면 문서의 아래쪽에 나열된 메인테이너에게
+패치를 보내달라.
+
+
+소개
+----
+
+자, 여러분은 리눅스 커널 개발자가 되는 법을 배우고 싶은가? 아니면
+상사로부터"이 장치를 위한 리눅스 드라이버를 작성하시오"라는 말을
+들었는가? 이 문서의 목적은 여러분이 겪게 될 과정과 커뮤니티와 협력하는
+법을 조언하여 여러분의 목적을 달성하기 위해 필요한 것 모두를 알려주기
+위함이다.
+
+커널은 대부분은 C로 작성되어 있고 몇몇 아키텍쳐의 의존적인 부분은
+어셈블리로 작성되어 있다. 커널 개발을 위해 C를 잘 이해하고 있어야 한다.
+여러분이 특정 아키텍쳐의 low-level 개발을 할 것이 아니라면
+어셈블리(특정 아키텍쳐)는 잘 알아야 할 필요는 없다.
+다음의 참고서적들은 기본에 충실한 C 교육이나 수년간의 경험에 견주지는
+못하지만 적어도 참고 용도로는 좋을 것이다
+
+ - "The C Programming Language" by Kernighan and Ritchie [Prentice Hall]
+ - "Practical C Programming" by Steve Oualline [O'Reilly]
+ - "C:  A Reference Manual" by Harbison and Steele [Prentice Hall]
+
+커널은 GNU C와 GNU 툴체인을 사용하여 작성되었다. 이 툴들은 ISO C89 표준을
+따르는 반면 표준에 있지 않은 많은 확장기능도 가지고 있다. 커널은 표준 C
+라이브러리와는 관계없이 freestanding C 환경이어서 C 표준의 일부는
+지원되지 않는다. 임의의 long long 나누기나 floating point는 지원되지 않는다.
+때론 이런 이유로 커널이 그런 확장 기능을 가진 툴체인을 가지고 만들어졌다는
+것이 이해하기 어려울 수도 있고 게다가 불행하게도 그런 것을 정확하게 설명하는
+어떤 참고문서도 있지 않다. 정보를 얻기 위해서는 gcc info (`info gcc`)페이지를
+살펴보라.
+
+여러분은 기존의 개발 커뮤니티와 협력하는 법을 배우려고 하고 있다는 것을
+기억하라. 코딩, 스타일, 함수에 관한 훌륭한 표준을 가진 사람들이 모인
+다양한 그룹이 있다. 이 표준들은 오랜동안 크고 지역적으로 분산된 팀들에
+의해 가장 좋은 방법으로 일하기 위하여 찾은 것을 기초로 만들어져 왔다.
+그 표준들은 문서화가 잘 되어있기 때문에 가능한한 미리 많은 표준들에
+관하여 배우려고 시도하라. 다른 사람들은 여러분이나 여러분의 회사가
+일하는 방식에 적응하는 것을 원하지는 않는다.
+
+
+법적 문제
+---------
+
+리눅스 커널 소스 코드는 GPL로 배포(release)되었다. 소스트리의 메인
+디렉토리에 있는 라이센스에 관하여 상세하게 쓰여 있는 COPYING이라는
+파일을 봐라. 여러분이 라이센스에 관한 더 깊은 문제를 가지고 있다면
+리눅스 커널 메일링 리스트에 묻지말고 변호사와 연락하라. 메일링
+리스트들에 있는 사람들은 변호사가 아니기 때문에 법적 문제에 관하여
+그들의 말에 의지해서는 안된다.
+
+GPL에 관한 잦은 질문들과 답변들은 다음을 참조하라.
+
+    https://www.gnu.org/licenses/gpl-faq.html
+
+
+문서
+----
+
+리눅스 커널 소스 트리는 커널 커뮤니티와 협력하는 법을 배우기위해 훌륭한
+다양한 문서들을 가지고 있다. 새로운 기능들이 커널에 들어가게 될 때,
+그 기능을 어떻게 사용하는지에 관한 설명을 위하여 새로운 문서 파일을
+추가하는 것을 권장한다. 커널이 유저스페이스로 노출하는 인터페이스를
+변경하게 되면 변경을 설명하는 메뉴얼 페이지들에 대한 패치나 정보를
+mtk.manpages@gmail.com의 메인테이너에게 보낼 것을 권장한다.
+
+다음은 커널 소스 트리에 있는 읽어야 할 파일들의 리스트이다.
+
+  README
+    이 파일은 리눅스 커널에 관하여 간단한 배경 설명과 커널을 설정하고
+    빌드하기 위해 필요한 것을 설명한다. 커널에 입문하는 사람들은 여기서
+    시작해야 한다.
+
+  :ref:`Documentation/process/changes.rst `
+    이 파일은 커널을 성공적으로 빌드하고 실행시키기 위해 필요한 다양한
+    소프트웨어 패키지들의 최소 버젼을 나열한다.
+
+  :ref:`Documentation/process/coding-style.rst `
+    이 문서는 리눅스 커널 코딩 스타일과 그렇게 한 몇몇 이유를 설명한다.
+    모든 새로운 코드는 이 문서에 가이드라인들을 따라야 한다. 대부분의
+    메인테이너들은 이 규칙을 따르는 패치들만을 받아들일 것이고 많은 사람들이
+    그 패치가 올바른 스타일일 경우만 코드를 검토할 것이다.
+
+  :ref:`Documentation/process/submitting-patches.rst ` 와 :ref:`Documentation/process/submitting-drivers.rst `
+    이 파일들은 성공적으로 패치를 만들고 보내는 법을 다음의 내용들로
+    굉장히 상세히 설명하고 있다(그러나 다음으로 한정되진 않는다).
+
+       - Email 내용들
+       - Email 양식
+       - 그것을 누구에게 보낼지
+
+    이러한 규칙들을 따르는 것이 성공(역자주: 패치가 받아들여 지는 것)을
+    보장하진 않는다(왜냐하면 모든 패치들은 내용과 스타일에 관하여
+    면밀히 검토되기 때문이다). 그러나 규칙을 따르지 않는다면 거의
+    성공하지도 못할 것이다.
+
+    올바른 패치들을 만드는 법에 관한 훌륭한 다른 문서들이 있다.
+
+    "The Perfect Patch"
+        https://www.ozlabs.org/~akpm/stuff/tpp.txt
+
+    "Linux kernel patch submission format"
+        http://linux.yyz.us/patch-format.html
+
+   :ref:`Documentation/process/stable-api-nonsense.rst `
+    이 문서는 의도적으로 커널이 불변하는 API를 갖지 않도록 결정한
+    이유를 설명하며 다음과 같은 것들을 포함한다.
+
+       - 서브시스템 shim-layer(호환성을 위해?)
+       - 운영체제들간의 드라이버 이식성
+       - 커널 소스 트리내에 빠른 변화를 늦추는 것(또는 빠른 변화를 막는 것)
+
+    이 문서는 리눅스 개발 철학을 이해하는데 필수적이며 다른 운영체제에서
+    리눅스로 전향하는 사람들에게는 매우 중요하다.
+
+
+  :ref:`Documentation/admin-guide/security-bugs.rst `
+    여러분들이 리눅스 커널의 보안 문제를 발견했다고 생각한다면 이 문서에
+    나온 단계에 따라서 커널 개발자들에게 알리고 그 문제를 해결할 수 있도록
+    도와 달라.
+
+  :ref:`Documentation/process/management-style.rst `
+    이 문서는 리눅스 커널 메인테이너들이 그들의 방법론에 녹아 있는
+    정신을 어떻게 공유하고 운영하는지를 설명한다. 이것은 커널 개발에 입문하는
+    모든 사람들(또는 커널 개발에 작은 호기심이라도 있는 사람들)이
+    읽어야 할 중요한 문서이다. 왜냐하면 이 문서는 커널 메인테이너들의
+    독특한 행동에 관하여 흔히 있는 오해들과 혼란들을 해소하고 있기
+    때문이다.
+
+  :ref:`Documentation/process/stable_kernel_rules.rst `
+    이 문서는 안정적인 커널 배포가 이루어지는 규칙을 설명하고 있으며
+    여러분들이 이러한 배포들 중 하나에 변경을 하길 원한다면
+    무엇을 해야 하는지를 설명한다.
+
+  :ref:`Documentation/process/kernel-docs.rst `
+    커널 개발에 관계된 외부 문서의 리스트이다. 커널 내의 포함된 문서들
+    중에 여러분이 찾고 싶은 문서를 발견하지 못할 경우 이 리스트를
+    살펴보라.
+
+  :ref:`Documentation/process/applying-patches.rst `
+    패치가 무엇이며 그것을 커널의 다른 개발 브랜치들에 어떻게
+    적용하는지에 관하여 자세히 설명하고 있는 좋은 입문서이다.
+
+커널은 소스 코드 그 자체에서 또는 이것과 같은 ReStructuredText 마크업 (ReST) 을
+통해 자동적으로 만들어질 수 있는 많은 문서들을 가지고 있다. 이것은 커널 내의
+API에 대한 모든 설명, 그리고 락킹을 올바르게 처리하는 법에 관한 규칙을 포함하고
+있다.
+
+모든 그런 문서들은 커널 소스 디렉토리에서 다음 커맨드를 실행하는 것을 통해 PDF
+나 HTML 의 형태로 만들어질 수 있다::
+
+         make pdfdocs
+         make htmldocs
+
+ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된다.  해당
+문서들은 다음의 커맨드를 사용하면 LaTeX 이나 ePub 로도 만들어질 수 있다::
+
+         make latexdocs
+         make epubdocs
+
+현재, ReST 로의 변환이 진행중인, DocBook 으로 쓰인 문서들이 존재한다. 그런
+문서들은 Documentation/DocBook/ 디렉토리 안에 생성될 것이고 다음 커맨드를 통해
+Postscript 나 man page 로도 만들어질 수 있다::
+
+         make psdocs
+         make mandocs
+
+커널 개발자가 되는 것
+---------------------
+
+여러분이 리눅스 커널 개발에 관하여 아무것도 모른다면 Linux KernelNewbies
+프로젝트를 봐야 한다.
+
+    https://kernelnewbies.org
+
+그곳은 거의 모든 종류의 기본적인 커널 개발 질문들(질문하기 전에 먼저
+아카이브를 찾아봐라. 과거에 이미 답변되었을 수도 있다)을 할 수 있는 도움이
+될만한 메일링 리스트가 있다. 또한 실시간으로 질문 할 수 있는 IRC 채널도
+가지고 있으며 리눅스 커널 개발을 배우는 데 유용한 문서들을 보유하고 있다.
+
+웹사이트는 코드구성, 서브시스템들, 그리고 현재 프로젝트들
+(트리 내, 외부에 존재하는)에 관한 기본적인 정보들을 가지고 있다. 또한
+그곳은 커널 컴파일이나 패치를 하는 법과 같은 기본적인 것들을  설명한다.
+
+여러분이 어디서 시작해야 할진 모르지만 커널 개발 커뮤니티에 참여할 수
+있는 일들을 찾길 원한다면 리눅스 커널 Janitor 프로젝트를 살펴봐라.
+
+	https://kernelnewbies.org/KernelJanitors
+
+그곳은 시작하기에 훌륭한 장소이다. 그곳은 리눅스 커널 소스 트리내에
+간단히 정리되고 수정될 수 있는 문제들에 관하여 설명한다. 여러분은 이
+프로젝트를 대표하는 개발자들과 일하면서 자신의 패치를 리눅스 커널 트리에
+반영하기 위한 기본적인 것들을 배우게 될것이며 여러분이 아직 아이디어를
+가지고 있지 않다면 다음에 무엇을 해야할지에 관한 방향을 배울 수 있을
+것이다.
+
+여러분들이 이미 커널 트리에 반영하길 원하는 코드 묶음을 가지고 있지만
+올바른 포맷으로 포장하는데 도움이 필요하다면 그러한 문제를 돕기 위해
+만들어진 kernel-mentors 프로젝트가 있다. 그곳은 메일링 리스트이며
+다음에서 참조할 수 있다.
+
+         https://selenic.com/mailman/listinfo/kernel-mentors
+
+리눅스 커널 코드에 실제 변경을 하기 전에 반드시 그 코드가 어떻게
+동작하는지 이해하고 있어야 한다. 코드를 분석하기 위하여 특정한 툴의
+도움을 빌려서라도 코드를 직접 읽는 것보다 좋은 것은 없다(대부분의
+자잘한 부분들은 잘 코멘트되어 있다). 그런 툴들 중에 특히 추천할만한
+것은 Linux Cross-Reference project이며 그것은 자기 참조 방식이며
+소스코드를 인덱스된 웹 페이지들의 형태로 보여준다. 최신의 멋진 커널
+코드 저장소는 다음을 통하여 참조할 수 있다.
+
+      http://lxr.free-electrons.com/
+
+
+개발 프로세스
+-------------
+
+리눅스 커널 개발 프로세스는 현재 몇몇 다른 메인 커널 "브랜치들"과
+서브시스템에 특화된 커널 브랜치들로 구성된다. 몇몇 다른 메인
+브랜치들은 다음과 같다.
+
+  - main 4.x 커널 트리
+  - 4.x.y - 안정된 커널 트리
+  - 4.x -git 커널 패치들
+  - 서브시스템을 위한 커널 트리들과 패치들
+  - 4.x - 통합 테스트를 위한 next 커널 트리
+
+4.x 커널 트리
+~~~~~~~~~~~~~
+
+4.x 커널들은 Linus Torvalds가 관리하며 https://kernel.org 의
+pub/linux/kernel/v4.x/ 디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다.
+
+  - 새로운 커널이 배포되자마자 2주의 시간이 주어진다. 이 기간동은
+    메인테이너들은 큰 diff들을 Linus에게 제출할 수 있다. 대개 이 패치들은
+    몇 주 동안 -next 커널내에 이미 있었던 것들이다. 큰 변경들을 제출하는 데
+    선호되는 방법은  git(커널의 소스 관리 툴, 더 많은 정보들은
+    https://git-scm.com/ 에서 참조할 수 있다)를 사용하는 것이지만 순수한
+    패치파일의 형식으로 보내는 것도 무관하다.
+  - 2주 후에 -rc1 커널이 배포되며 지금부터는 전체 커널의 안정성에 영향을
+    미칠수 있는 새로운 기능들을 포함하지 않는 패치들만이 추가될 수 있다.
+    완전히 새로운 드라이버(혹은 파일시스템)는 -rc1 이후에만 받아들여진다는
+    것을 기억해라. 왜냐하면 변경이 자체내에서만 발생하고 추가된 코드가
+    드라이버 외부의 다른 부분에는 영향을 주지 않으므로 그런 변경은
+    회귀(역자주: 이전에는 존재하지 않았지만 새로운 기능추가나 변경으로 인해
+    생겨난 버그)를 일으킬 만한 위험을 가지고 있지 않기 때문이다. -rc1이
+    배포된 이후에 git를 사용하여 패치들을 Linus에게 보낼수 있지만 패치들은
+    공식적인 메일링 리스트로 보내서 검토를 받을 필요가 있다.
+  - 새로운 -rc는 Linus가 현재 git tree가 테스트 하기에 충분히 안정된 상태에
+    있다고 판단될 때마다 배포된다. 목표는 새로운 -rc 커널을 매주 배포하는
+    것이다.
+  - 이러한 프로세스는 커널이 "준비(ready)"되었다고 여겨질때까지 계속된다.
+    프로세스는 대체로 6주간 지속된다.
+
+커널 배포에 있어서 언급할만한 가치가 있는 리눅스 커널 메일링 리스트의
+Andrew Morton의 글이 있다.
+
+        *"커널이 언제 배포될지는 아무도 모른다. 왜냐하면 배포는 알려진
+         버그의 상황에 따라 배포되는 것이지 미리정해 놓은 시간에 따라
+         배포되는 것은 아니기 때문이다."*
+
+4.x.y - 안정 커널 트리
+~~~~~~~~~~~~~~~~~~~~~~
+
+3 자리 숫자로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 4.x
+커널에서 발견된 큰 회귀들이나 보안 문제들 중 비교적 작고 중요한 수정들을
+포함한다.
+
+이것은 가장 최근의 안정적인 커널을 원하는 사용자에게 추천되는 브랜치이며,
+개발/실험적 버젼을 테스트하는 것을 돕고자 하는 사용자들과는 별로 관련이 없다.
+
+어떤 4.x.y 커널도 사용할 수 없다면 그때는 가장 높은 숫자의 4.x
+커널이 현재의 안정 커널이다.
+
+4.x.y는 "stable" 팀에 의해 관리되며 거의 매번 격주로
+배포된다.
+
+커널 트리 문서들 내에 Documentation/process/stable-kernel-rules.rst 파일은 어떤
+종류의 변경들이 -stable 트리로 들어왔는지와 배포 프로세스가 어떻게
+진행되는지를 설명한다.
+
+4.x -git 패치들
+~~~~~~~~~~~~~~~
+
+git 저장소(그러므로 -git이라는 이름이 붙음)에는 날마다 관리되는 Linus의
+커널 트리의 snapshot 들이 있다. 이 패치들은 일반적으로 날마다 배포되며
+Linus의 트리의 현재 상태를 나타낸다. 이 패치들은 정상적인지 조금도
+살펴보지 않고 자동적으로 생성된 것이므로 -rc 커널들 보다도 더 실험적이다.
+
+서브시스템 커널 트리들과 패치들
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+다양한 커널 서브시스템의 메인테이너들 --- 그리고 많은 커널 서브시스템 개발자들
+--- 은 그들의 현재 개발 상태를 소스 저장소로 노출한다. 이를 통해 다른 사람들도
+커널의 다른 영역에 어떤 변화가 이루어지고 있는지 알 수 있다. 급속히 개발이
+진행되는 영역이 있고 그렇지 않은 영역이 있으므로, 개발자는 다른 개발자가 제출한
+수정 사항과 자신의 수정사항의 충돌이나 동일한 일을 동시에 두사람이 따로
+진행하는 사태를 방지하기 위해 급속히 개발이 진행되고 있는 영역에 작업의
+베이스를 맞춰줄 것이 요구된다.
+
+대부분의 이러한 저장소는 git 트리지만, git이 아닌 SCM으로 관리되거나, quilt
+시리즈로 제공되는 패치들도 존재한다. 이러한 서브시스템 저장소들은 MAINTAINERS
+파일에 나열되어 있다. 대부분은 https://git.kernel.org 에서 볼 수 있다.
+
+제안된 패치는 서브시스템 트리에 커밋되기 전에 메일링 리스트를 통해
+리뷰된다(아래의 관련 섹션을 참고하기 바란다). 일부 커널 서브시스템의 경우, 이
+리뷰 프로세스는 patchwork라는 도구를 통해 추적된다. patchwork은 등록된 패치와
+패치에 대한 코멘트, 패치의 버전을 볼 수 있는 웹 인터페이스를 제공하고,
+메인테이너는 패치를 리뷰 중, 리뷰 통과, 또는 반려됨으로 표시할 수 있다.
+대부분의 이러한 patchwork 사이트는 https://patchwork.kernel.org/ 또는
+http://patchwork.ozlabs.org/ 에 나열되어 있다.
+
+4.x - 통합 테스트를 위한 next 커널 트리
+---------------------------------------
+서브시스템 트리들의 변경사항들은 mainline 4.x 트리로 들어오기 전에 통합
+테스트를 거쳐야 한다. 이런 목적으로, 모든 서브시스템 트리의 변경사항을 거의
+매일 받아가는 특수한 테스트 저장소가 존재한다:
+
+       https://git.kernel.org/?p=linux/kernel/git/sfr/linux-next.git
+
+이런 식으로, -next 커널을 통해 다음 머지 기간에 메인라인 커널에 어떤 변경이
+가해질 것인지 간략히 알 수 있다. 모험심 강한 테스터라면 -next 커널에서 테스트를
+수행하는 것도 좋을 것이다.
+
+
+버그 보고
+---------
+
+https://bugzilla.kernel.org는 리눅스 커널 개발자들이 커널의 버그를 추적하는
+곳이다. 사용자들은 발견한 모든 버그들을 보고하기 위하여 이 툴을 사용할 것을
+권장한다.  kernel bugzilla를 사용하는 자세한 방법은 다음을 참조하라.
+
+    https://bugzilla.kernel.org/page.cgi?id=faq.html
+
+메인 커널 소스 디렉토리에 있는 admin-guide/reporting-bugs.rst 파일은 커널 버그라고 생각되는
+것을 보고하는 방법에 관한 좋은 템플릿이며 문제를 추적하기 위해서 커널
+개발자들이 필요로 하는 정보가 무엇들인지를 상세히 설명하고 있다.
+
+
+버그 리포트들의 관리
+--------------------
+
+여러분의 해킹 기술을 연습하는 가장 좋은 방법 중의 하는 다른 사람들이
+보고한 버그들을 수정하는 것이다. 여러분은 커널을 더욱 안정화시키는데
+도움을 줄 뿐만이 아니라 실제있는 문제들을 수정하는 법을 배우게 되고
+그와 함께 여러분들의 기술은 향상될 것이며 다른 개발자들이 여러분의
+존재에 대해 알게 될 것이다. 버그를 수정하는 것은 개발자들  사이에서
+점수를 얻을 수 있는 가장 좋은 방법중의 하나이다. 왜냐하면 많은 사람들은
+다른 사람들의 버그들을 수정하기 위하여 시간을 낭비하지 않기 때문이다.
+
+이미 보고된 버그 리포트들을 가지고 작업하기 위해서 https://bugzilla.kernel.org
+를 참조하라. 여러분이 앞으로 생겨날 버그 리포트들의 조언자가 되길 원한다면
+bugme-new 메일링 리스트나(새로운 버그 리포트들만이 이곳에서 메일로 전해진다)
+bugme-janitor 메일링 리스트(bugzilla에 모든 변화들이 여기서 메일로 전해진다)
+에 등록하면 된다.
+
+      https://lists.linux-foundation.org/mailman/listinfo/bugme-new
+
+      https://lists.linux-foundation.org/mailman/listinfo/bugme-janitors
+
+
+
+메일링 리스트들
+---------------
+
+위의 몇몇 문서들이 설명하였지만 핵심 커널 개발자들의 대다수는
+리눅스 커널 메일링 리스트에 참여하고 있다. 리스트에 등록하고 해지하는
+방법에 관한 자세한 사항은 다음에서 참조할 수 있다.
+
+    http://vger.kernel.org/vger-lists.html#linux-kernel
+
+웹상의 많은 다른 곳에도 메일링 리스트의 아카이브들이 있다.
+이러한 아카이브들을 찾으려면 검색 엔진을 사용하라. 예를 들어:
+
+      http://dir.gmane.org/gmane.linux.kernel
+
+여러분이 새로운 문제에 관해 리스트에 올리기 전에 말하고 싶은 주제에 관한
+것을 아카이브에서 먼저 찾아보기를 강력히 권장한다. 이미 상세하게 토론된 많은
+것들이 메일링 리스트의 아카이브에 기록되어 있다.
+
+각각의 커널 서브시스템들의 대부분은 자신들의 개발에 관한 노력들로 이루어진
+분리된 메일링 리스트를 따로 가지고 있다. 다른 그룹들이 무슨 리스트를 가지고
+있는지는 MAINTAINERS 파일을 참조하라.
+
+많은 리스트들은 kernel.org에서 호스트되고 있다. 그 정보들은 다음에서 참조될 수 있다.
+
+         http://vger.kernel.org/vger-lists.html
+
+리스트들을 사용할 때는 올바른 예절을 따를 것을 유념해라.
+대단하진 않지만 다음 URL은 리스트(혹은 모든 리스트)와 대화하는 몇몇 간단한
+가이드라인을 가지고 있다.
+
+         http://www.albion.com/netiquette/
+
+여러 사람들이 여러분의 메일에 응답한다면 CC: 즉 수신 리스트는 꽤 커지게
+될 것이다. 아무 이유없이 CC에서 어떤 사람도 제거하거나 리스트 주소로만
+회신하지 마라. 메일을 보낸 사람으로서 하나를 받고 리스트로부터 또
+하나를 받아 두번 받는 것에 익숙하여 있으니 mail-header를 조작하려고 하지
+말아라. 사람들은 그런 것을 좋아하지 않을 것이다.
+
+여러분의 회신의 문맥을 원래대로 유지해야 한다. 여러분들의 회신의 윗부분에
+"John 커널해커는 작성했다...."를 유지하며 여러분들의 의견을 그 메일의 윗부분에
+작성하지 말고 각 인용한 단락들 사이에 넣어라.
+
+여러분들이 패치들을 메일에 넣는다면 그것들은 Documentation/process/submitting-patches.rst에
+나와있는데로 명백히(plain) 읽을 수 있는 텍스트여야 한다. 커널 개발자들은
+첨부파일이나 압축된 패치들을 원하지 않는다. 그들은 여러분들의 패치의
+각 라인 단위로 코멘트를 하길 원하며 압축하거나 첨부하지 않고 보내는 것이
+그렇게 할 수 있는 유일한 방법이다. 여러분들이 사용하는 메일 프로그램이
+스페이스나 탭 문자들을 조작하지 않는지 확인하라. 가장 좋은 첫 테스트는
+메일을 자신에게 보내보고 스스로 그 패치를 적용해보라. 그것이 동작하지
+않는다면 여러분의 메일 프로그램을 고치던가 제대로 동작하는 프로그램으로
+바꾸어라.
+
+무엇보다도 메일링 리스트의 다른 구독자들에게 보여주려 한다는 것을 기억하라.
+
+
+커뮤니티와 협력하는 법
+----------------------
+
+커널 커뮤니티의 목적은 가능한한 가장 좋은 커널을 제공하는 것이다. 여러분이
+받아들여질 패치를 제출하게 되면 그 패치의 기술적인 이점으로 검토될 것이다.
+그럼 여러분들은 무엇을 기대하고 있어야 하는가?
+
+ - 비판
+ - 의견
+ - 변경을 위한 요구
+ - 당위성을 위한 요구
+ - 침묵
+
+기억하라. 이것들은 여러분의 패치가 커널로 들어가기 위한 과정이다. 여러분의
+패치들은 비판과 다른 의견을 받을 수 있고 그것들을 기술적인 레벨로 평가하고
+재작업하거나 또는 왜 수정하면 안되는지에 관하여 명료하고 간결한 이유를
+말할 수 있어야 한다. 여러분이 제출한 것에 어떤 응답도 있지 않다면 몇 일을
+기다려보고 다시 시도해라. 때론 너무 많은 메일들 속에 묻혀버리기도 한다.
+
+여러분은 무엇을 해서는 안되는가?
+
+ - 여러분의 패치가 아무 질문 없이 받아들여지기를 기대하는 것
+ - 방어적이 되는 것
+ - 의견을 무시하는 것
+ - 요청된 변경을 하지 않고 패치를 다시 제출하는 것
+
+가능한한 가장 좋은 기술적인 해답을 찾고 있는 커뮤니티에서는 항상
+어떤 패치가 얼마나 좋은지에 관하여 다른 의견들이 있을 수 있다. 여러분은
+협조적이어야 하고 기꺼이 여러분의 생각을 커널 내에 맞추어야 한다. 아니면
+적어도 여러분의 것이 가치있다는 것을 증명하여야 한다. 잘못된 것도 여러분이
+올바른 방향의 해결책으로 이끌어갈 의지가 있다면 받아들여질 것이라는 점을
+기억하라.
+
+여러분의 첫 패치에 여러분이 수정해야하는 십여개 정도의 회신이 오는
+경우도 흔하다. 이것은 여러분의 패치가 받아들여지지 않을 것이라는 것을
+의미하는 것이 아니고 개인적으로 여러분에게 감정이 있어서 그러는 것도
+아니다. 간단히 여러분의 패치에 제기된 문제들을 수정하고 그것을 다시
+보내라.
+
+
+커널 커뮤니티와 기업 조직간의 차이점
+------------------------------------
+커널 커뮤니티는 가장 전통적인 회사의 개발 환경과는 다르다. 여기에 여러분들의
+문제를 피하기 위한 목록이 있다.
+
+  여러분들이 제안한 변경들에 관하여 말할 때 좋은 것들 :
+
+    - "이것은 여러 문제들을 해결합니다."
+    - "이것은 2000 라인의 코드를 줄입니다."
+    - "이것은 내가 말하려는 것에 관해 설명하는 패치입니다."
+    - "나는 5개의 다른 아키텍쳐에서 그것을 테스트 했으므로..."
+    - "여기에 일련의 작은 패치들이 있으므로..."
+    - "이것은 일반적인 머신에서 성능을 향상함으로..."
+
+  여러분들이 말할 때 피해야 할 좋지 않은 것들 :
+
+    - "우리는 그것을 AIX/ptx/Solaris에서 이러한 방법으로 했다. 그러므로 그것은 좋은 것임에 틀림없다..."
+    - "나는 20년동안 이것을 해왔다. 그러므로..."
+    - "이것은 돈을 벌기위해 나의 회사가 필요로 하는 것이다."
+    - "이것은 우리의 엔터프라이즈 상품 라인을 위한 것이다."
+    - "여기에 나의 생각을 말하고 있는 1000 페이지 설계 문서가 있다."
+    - "나는 6달동안 이것을 했으니..."
+    - "여기에 5000 라인 짜리 패치가 있으니..."
+    - "나는 현재 뒤죽박죽인 것을 재작성했다. 그리고 여기에..."
+    - "나는 마감시한을 가지고 있으므로 이 패치는 지금 적용될 필요가 있다."
+
+커널 커뮤니티가 전통적인 소프트웨어 엔지니어링 개발 환경들과
+또 다른 점은 얼굴을 보지 않고 일한다는 점이다. 이메일과 irc를 대화의
+주요수단으로 사용하는 것의 한가지 장점은 성별이나 인종의 차별이
+없다는 것이다. 리눅스 커널의 작업 환경에서는 단지 이메일 주소만
+알수 있기 때문에 여성과 소수 민족들도 모두 받아들여진다. 국제적으로
+일하게 되는 측면은 사람의 이름에 근거하여 성별을 추측할 수 없게
+하기때문에 차별을 없애는 데 도움을 준다. Andrea라는 이름을 가진 남자와
+Pat이라는 이름을 가진 여자가 있을 수도 있는 것이다. 리눅스 커널에서
+작업하며 생각을 표현해왔던 대부분의 여성들은 긍정적인 경험을 가지고
+있다.
+
+언어 장벽은 영어에 익숙하지 않은 몇몇 사람들에게 문제가 될 수도 있다.
+언어의 훌륭한 구사는 메일링 리스트에서 올바르게 자신의 생각을
+표현하기 위하여 필요하다. 그래서 여러분은 이메일을 보내기 전에
+영어를 올바르게 사용하고 있는지를 체크하는 것이 바람직하다.
+
+
+여러분의 변경을 나누어라
+------------------------
+
+리눅스 커널 커뮤니티는 한꺼번에 굉장히 큰 코드의 묶음(chunk)을 쉽게
+받아들이지 않는다. 변경은 적절하게 소개되고, 검토되고, 각각의
+부분으로 작게 나누어져야 한다. 이것은 회사에서 하는 것과는 정확히
+반대되는 것이다. 여러분들의 제안은 개발 초기에 일찍이 소개되야 한다.
+그래서 여러분들은 자신이 하고 있는 것에 관하여 피드백을 받을 수 있게
+된다. 커뮤니티가 여러분들이 커뮤니티와 함께 일하고 있다는 것을
+느끼도록 만들고 커뮤니티가 여러분의 기능을 위한 쓰레기 장으로써
+사용되지 않고 있다는 것을 느끼게 하자. 그러나 메일링 리스트에 한번에
+50개의 이메일을 보내지는 말아라. 여러분들의 일련의 패치들은 항상
+더 작아야 한다.
+
+패치를 나누는 이유는 다음과 같다.
+
+1) 작은 패치들은 여러분의 패치들이 적용될 수 있는 확률을 높여준다.
+   왜냐하면 다른 사람들은 정확성을 검증하기 위하여 많은 시간과 노력을
+   들이기를 원하지 않는다. 5줄의 패치는 메인테이너가 거의 몇 초간 힐끗
+   보면 적용될 수 있다. 그러나 500 줄의 패치는 정확성을 검토하기 위하여
+   몇시간이 걸릴 수도 있다(걸리는 시간은 패치의 크기 혹은 다른 것에
+   비례하여 기하급수적으로 늘어난다).
+
+   패치를 작게 만드는 것은 무엇인가 잘못되었을 때 디버그하는 것을
+   쉽게 만든다. 즉, 그렇게 만드는 것은 매우 큰 패치를 적용한 후에
+   조사하는 것 보다 작은 패치를 적용한 후에 (그리고 몇몇의 것이
+   깨졌을 때) 하나씩 패치들을 제거해가며 디버그 하기 쉽도록 만들어 준다.
+
+2) 작은 패치들을 보내는 것뿐만 아니라 패치들을 제출하기전에 재작성하고
+   간단하게(혹은 간단한게 재배치하여) 하는 것도 중요하다.
+
+여기에 커널 개발자 Al Viro의 이야기가 있다.
+
+    *"학생의 수학 숙제를 채점하는 선생님을 생각해보라. 선생님은 학생들이
+    답을 얻을때까지 겪은 시행착오를 보길 원하지 않는다. 선생님들은
+    간결하고 가장 뛰어난 답을 보길 원한다. 훌륭한 학생은 이것을 알고
+    마지막으로 답을 얻기 전 중간 과정들을 제출하진 않는다.*
+
+    *커널 개발도 마찬가지이다. 메인테이너들과 검토하는 사람들은 문제를
+    풀어나가는 과정속에 숨겨진 과정을 보길 원하진 않는다. 그들은
+    간결하고 멋진 답을 보길 원한다."*
+
+커뮤니티와 협력하며 뛰어난 답을 찾는 것과 여러분들의 끝마치지 못한 작업들
+사이에 균형을 유지해야 하는 것은 어려울지도 모른다. 그러므로 프로세스의
+초반에 여러분의 작업을 향상시키기위한 피드백을 얻는 것 뿐만 아니라
+여러분들의 변경들을 작은 묶음으로 유지해서 심지어는 여러분의 작업의
+모든 부분이 지금은 포함될 준비가 되어있지 않지만 작은 부분은 벌써
+받아들여질 수 있도록 유지하는 것이 바람직하다.
+
+또한 완성되지 않았고 "나중에 수정될 것이다." 와 같은 것들을 포함하는
+패치들은 받아들여지지 않을 것이라는 점을 유념하라.
+
+
+변경을 정당화해라
+-----------------
+
+여러분들의 나누어진 패치들을 리눅스 커뮤니티가 왜 반영해야 하는지를
+알도록 하는 것은 매우 중요하다. 새로운 기능들이 필요하고 유용하다는
+것은 반드시 그에 합당한 이유가 있어야 한다.
+
+
+변경을 문서화해라
+-----------------
+
+여러분이 패치를 보내려 할때는 여러분이 무엇을 말하려고 하는지를 충분히
+생각하여 이메일을 작성해야 한다. 이 정보는 패치를 위한 ChangeLog가 될
+것이다. 그리고 항상 그 내용을 보길 원하는 모든 사람들을 위해 보존될
+것이다. 패치는 완벽하게 다음과 같은 내용들을 포함하여 설명해야 한다.
+
+  - 변경이 왜 필요한지
+  - 패치에 관한 전체 설계 접근(approach)
+  - 구현 상세들
+  - 테스트 결과들
+
+이것이 무엇인지 더 자세한 것을 알고 싶다면 다음 문서의 ChageLog 항을 봐라.
+
+   "The Perfect Patch"
+
+    http://www.ozlabs.org/~akpm/stuff/tpp.txt
+
+
+이 모든 것을 하는 것은 매우 어려운 일이다. 완벽히 소화하는 데는 적어도 몇년이
+걸릴 수도 있다. 많은 인내와 결심이 필요한 계속되는 개선의 과정이다. 그러나
+가능한한 포기하지 말라. 많은 사람들은 이전부터 해왔던 것이고 그 사람들도
+정확하게 여러분들이 지금 서 있는 그 곳부터  시작했었다.
+
+
+
+
+----------
+
+"개발 프로세스"(https://lwn.net/Articles/94386/) 섹션을
+작성하는데 있어 참고할 문서를 사용하도록 허락해준 Paolo Ciarrocchi에게
+감사한다. 여러분들이 말해야 할 것과 말해서는 안되는 것의 목록 중 일부를 제공해준
+Randy Dunlap과 Gerrit Huizenga에게 감사한다. 또한 검토와 의견 그리고
+공헌을 아끼지 않은 Pat Mochel, Hanna Linder, Randy Dunlap, Kay Sievers,
+Vojtech Pavlik, Jan Kara, Josh Boyer, Kees Cook, Andrew Morton, Andi Kleen,
+Vadim Lobanov, Jesper Juhl, Adrian Bunk, Keri Harris, Frans Pop,
+David A. Wheeler, Junio Hamano, Michael Kerrisk, and Alex Shepard에게도 감사를 전한다.
+그들의 도움이 없었다면 이 문서는 존재하지 않았을 것이다.
+
+
+
+메인테이너: Greg Kroah-Hartman 
diff --git a/Documentation/translations/ko_KR/index.rst b/Documentation/translations/ko_KR/index.rst
new file mode 100644
index 000000000000..0b695345abc7
--- /dev/null
+++ b/Documentation/translations/ko_KR/index.rst
@@ -0,0 +1,12 @@
+.. raw:: latex
+
+        \renewcommand\thesection*
+        \renewcommand\thesubsection*
+
+Korean translations
+===================
+
+.. toctree::
+   :maxdepth: 1
+
+   howto
-- 
cgit v1.2.3


From f5ff9b63d494ed6fbfc96e8b4f5c2c32ad291b12 Mon Sep 17 00:00:00 2001
From: Jonathan Corbet 
Date: Sun, 13 Nov 2016 12:24:59 -0700
Subject: MAINTAINERS: The Chinese documentation moved

Update the F: line accordingly.

Signed-off-by: Jonathan Corbet 
---
 MAINTAINERS | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/MAINTAINERS b/MAINTAINERS
index 489a913a0bd4..690cfb6a53d9 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -3072,7 +3072,7 @@ M:	Harry Wei 
 L:	xiyoulinuxkernelgroup@googlegroups.com (subscribers-only)
 L:	linux-kernel@zh-kernel.org (moderated for non-subscribers)
 S:	Maintained
-F:	Documentation/zh_CN/
+F:	Documentation/translations/zh_CN/
 
 CHIPIDEA USB HIGH SPEED DUAL ROLE CONTROLLER
 M:	Peter Chen 
-- 
cgit v1.2.3


From e2a91f4f42018994d7424d405900d17eba6555d0 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 14 Nov 2016 14:32:27 -0200
Subject: docs-rst: fix LaTeX \DURole renewcommand with Sphinx 1.3+

PDF build on Kernel 4.9-rc? returns an error with Sphinx 1.3.x
and Sphinx 1.4.x, when trying to solve some cross-references.

The solution is to redefine the \DURole macro.

However, this is redefined too late. Move such redefinition to
LaTeX preamble and bind it to just the Sphinx versions where the
error is known to be present.

Tested by building the documentation on interactive mode:
	make PDFLATEX=xelatex -C Documentation/output/./latex

Fixes: e61a39baf74d ("[media] index.rst: Fix LaTeX error in interactive mode on Sphinx 1.4.x")
Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/conf.py         | 6 +++++-
 Documentation/media/index.rst | 5 -----
 2 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index bcb1af786e78..db78974aad26 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -37,7 +37,7 @@ from load_config import loadConfig
 extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain']
 
 # The name of the math extension changed on Sphinx 1.4
-if minor > 3:
+if major == 1 and minor > 3:
     extensions.append("sphinx.ext.imgmath")
 else:
     extensions.append("sphinx.ext.pngmath")
@@ -332,6 +332,10 @@ latex_elements = {
      '''
 }
 
+# Fix reference escape troubles with Sphinx 1.4.x
+if major == 1 and minor > 3:
+    latex_elements['preamble']  += '\\renewcommand*{\\DUrole}[2]{ #2 }\n'
+
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
diff --git a/Documentation/media/index.rst b/Documentation/media/index.rst
index e347a3e7bdef..7f8f0af620ce 100644
--- a/Documentation/media/index.rst
+++ b/Documentation/media/index.rst
@@ -1,11 +1,6 @@
 Linux Media Subsystem Documentation
 ===================================
 
-.. Sphinx 1.4.x has a definition for DUrole that doesn't work on alltt blocks
-.. raw:: latex
-
-	\renewcommand*{\DUrole}[2]{ #2 }
-
 Contents:
 
 .. toctree::
-- 
cgit v1.2.3


From ce998e6fbaf77a0cc9ce5070db64db56c1d4b69a Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 14 Nov 2016 14:32:28 -0200
Subject: subdev-formats.rst: don't use adjustbox on a longtable

adjustbox doesn't work on longtables. Also, this
causes an error on LaTeX in interactive mode.

So, use, instead, a tiny font.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/media/uapi/v4l/subdev-formats.rst | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst
index e144370f62a0..282a7467a812 100644
--- a/Documentation/media/uapi/v4l/subdev-formats.rst
+++ b/Documentation/media/uapi/v4l/subdev-formats.rst
@@ -1526,9 +1526,16 @@ The following table lists existing packed Bayer formats. The data
 organization is given as an example for the first pixel only.
 
 
+.. HACK: ideally, we would be using adjustbox here. However, Sphinx
+.. is a very bad behaviored guy: if the table has more than 30 cols,
+.. it switches to long table, and there's no way to override it.
+
+
 .. raw:: latex
 
-    \newline\newline\begin{adjustbox}{width=\columnwidth}
+    \begingroup
+    \tiny
+    \setlength{\tabcolsep}{2pt}
 
 .. tabularcolumns:: |p{7.6cm}|p{1.6cm}|p{0.7cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|
 
@@ -2314,7 +2321,7 @@ organization is given as an example for the first pixel only.
 
 .. raw:: latex
 
-    \end{adjustbox}\newline\newline
+    \endgroup
 
 
 Packed YUV Formats
-- 
cgit v1.2.3


From 346dabfee054e5ca6cee4ab605640098e6555b6c Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 14 Nov 2016 14:32:29 -0200
Subject: subdev-formats.rst: add missing columns to tabularcolumns

There are several missing columns on the size specification,
causing LaTeX to complain on interactive mode.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/media/uapi/v4l/subdev-formats.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst
index 282a7467a812..65105609374b 100644
--- a/Documentation/media/uapi/v4l/subdev-formats.rst
+++ b/Documentation/media/uapi/v4l/subdev-formats.rst
@@ -1537,7 +1537,7 @@ organization is given as an example for the first pixel only.
     \tiny
     \setlength{\tabcolsep}{2pt}
 
-.. tabularcolumns:: |p{7.6cm}|p{1.6cm}|p{0.7cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|p{0.5cm}|
+.. tabularcolumns:: |p{4.0cm}|p{0.7cm}|p{0.3cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|p{0.22cm}|
 
 .. _v4l2-mbus-pixelcode-bayer:
 
-- 
cgit v1.2.3


From 00e99ed2c84536055761fa5962ae4e6eb95b4090 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 14 Nov 2016 14:32:30 -0200
Subject: convert some images from png to svg

SVG images are nicer, as they can easily be scaled. Also, they're
written in text, with makes easier to work.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/media/uapi/dvb/intro.rst             |   2 +-
 .../media/uapi/dvb/intro_files/dvbstb.png          | Bin 22655 -> 0 bytes
 .../media/uapi/dvb/intro_files/dvbstb.svg          | 651 +++++++++++++++++++++
 .../media/uapi/v4l/vidioc-g-selection.rst          |   2 +-
 .../v4l/vidioc-g-selection_files/constraints.png   | Bin 3313 -> 0 bytes
 .../v4l/vidioc-g-selection_files/constraints.svg   | 346 +++++++++++
 6 files changed, 999 insertions(+), 2 deletions(-)
 delete mode 100644 Documentation/media/uapi/dvb/intro_files/dvbstb.png
 create mode 100644 Documentation/media/uapi/dvb/intro_files/dvbstb.svg
 delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.png
 create mode 100644 Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.svg

diff --git a/Documentation/media/uapi/dvb/intro.rst b/Documentation/media/uapi/dvb/intro.rst
index b61081d00a9f..11b96a19a9ab 100644
--- a/Documentation/media/uapi/dvb/intro.rst
+++ b/Documentation/media/uapi/dvb/intro.rst
@@ -56,7 +56,7 @@ Overview
 .. _stb_components:
 
 .. figure::  intro_files/dvbstb.*
-    :alt:    dvbstb.pdf / dvbstb.png
+    :alt:    dvbstb.pdf / dvbstb.svg
     :align:  center
 
     Components of a DVB card/STB
diff --git a/Documentation/media/uapi/dvb/intro_files/dvbstb.png b/Documentation/media/uapi/dvb/intro_files/dvbstb.png
deleted file mode 100644
index 9b8f372e7afd..000000000000
Binary files a/Documentation/media/uapi/dvb/intro_files/dvbstb.png and /dev/null differ
diff --git a/Documentation/media/uapi/dvb/intro_files/dvbstb.svg b/Documentation/media/uapi/dvb/intro_files/dvbstb.svg
new file mode 100644
index 000000000000..c4140fb518af
--- /dev/null
+++ b/Documentation/media/uapi/dvb/intro_files/dvbstb.svg
@@ -0,0 +1,651 @@
+
+image/svg+xmlAntena
+Frontend
+CA
+Demux
+SEC
+Audio
+Video
+TV
+
\ No newline at end of file
diff --git a/Documentation/media/uapi/v4l/vidioc-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-g-selection.rst
index 3145a9166bad..6da359e50668 100644
--- a/Documentation/media/uapi/v4l/vidioc-g-selection.rst
+++ b/Documentation/media/uapi/v4l/vidioc-g-selection.rst
@@ -130,7 +130,7 @@ Selection targets and flags are documented in
 .. _sel-const-adjust:
 
 .. figure::  vidioc-g-selection_files/constraints.*
-    :alt:    constraints.png
+    :alt:    constraints.svg
     :align:  center
 
     Size adjustments with constraint flags.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.png b/Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.png
deleted file mode 100644
index 20228d2c5504..000000000000
Binary files a/Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.svg b/Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.svg
new file mode 100644
index 000000000000..f710ee46b1f8
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.svg
@@ -0,0 +1,346 @@
+
+image/svg+xmlV4L2_SEL_FLAG_GE
+ORIGINAL
+V4L2_SEL_FLAG_LE
+
\ No newline at end of file
-- 
cgit v1.2.3


From f3902934797b0b00ba8f10bfc377c1bb2789046c Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 14 Nov 2016 14:32:31 -0200
Subject: docs-rst: convert gif files to png

Right now, media is using two different formats for bitmap
images: GIF and PNG. Let's use just one, to make it simpler when
building with Sphinx.

As PNG is usually better than GIF, let's use it.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/media/uapi/v4l/crop_files/crop.gif        | Bin 5967 -> 0 bytes
 Documentation/media/uapi/v4l/crop_files/crop.png        | Bin 0 -> 3334 bytes
 .../media/uapi/v4l/dev-raw-vbi_files/vbi_525.gif        | Bin 4741 -> 0 bytes
 .../media/uapi/v4l/dev-raw-vbi_files/vbi_525.png        | Bin 0 -> 2053 bytes
 .../media/uapi/v4l/dev-raw-vbi_files/vbi_625.gif        | Bin 5095 -> 0 bytes
 .../media/uapi/v4l/dev-raw-vbi_files/vbi_625.png        | Bin 0 -> 2352 bytes
 .../media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.gif      | Bin 2400 -> 0 bytes
 .../media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.png      | Bin 0 -> 906 bytes
 .../media/uapi/v4l/field-order_files/fieldseq_bt.gif    | Bin 25430 -> 0 bytes
 .../media/uapi/v4l/field-order_files/fieldseq_bt.png    | Bin 0 -> 12306 bytes
 .../media/uapi/v4l/field-order_files/fieldseq_tb.gif    | Bin 25323 -> 0 bytes
 .../media/uapi/v4l/field-order_files/fieldseq_tb.png    | Bin 0 -> 12247 bytes
 12 files changed, 0 insertions(+), 0 deletions(-)
 delete mode 100644 Documentation/media/uapi/v4l/crop_files/crop.gif
 create mode 100644 Documentation/media/uapi/v4l/crop_files/crop.png
 delete mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.gif
 create mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.png
 delete mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.gif
 create mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.png
 delete mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.gif
 create mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.png
 delete mode 100644 Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.gif
 create mode 100644 Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.png
 delete mode 100644 Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.gif
 create mode 100644 Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.png

diff --git a/Documentation/media/uapi/v4l/crop_files/crop.gif b/Documentation/media/uapi/v4l/crop_files/crop.gif
deleted file mode 100644
index 3b9e7d836d4b..000000000000
Binary files a/Documentation/media/uapi/v4l/crop_files/crop.gif and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/crop_files/crop.png b/Documentation/media/uapi/v4l/crop_files/crop.png
new file mode 100644
index 000000000000..225998c395df
Binary files /dev/null and b/Documentation/media/uapi/v4l/crop_files/crop.png differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.gif b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.gif
deleted file mode 100644
index 5580b690d504..000000000000
Binary files a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.gif and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.png b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.png
new file mode 100644
index 000000000000..24937dbec337
Binary files /dev/null and b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.png differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.gif b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.gif
deleted file mode 100644
index 34e3251983c4..000000000000
Binary files a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.gif and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.png b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.png
new file mode 100644
index 000000000000..25c671af41ad
Binary files /dev/null and b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.png differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.gif b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.gif
deleted file mode 100644
index b02434d3b356..000000000000
Binary files a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.gif and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.png b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.png
new file mode 100644
index 000000000000..b04ae50385a7
Binary files /dev/null and b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.png differ
diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.gif b/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.gif
deleted file mode 100644
index 60e8569a76c9..000000000000
Binary files a/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.gif and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.png b/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.png
new file mode 100644
index 000000000000..888ce6fed817
Binary files /dev/null and b/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.png differ
diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.gif b/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.gif
deleted file mode 100644
index 718492f1cfc7..000000000000
Binary files a/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.gif and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.png b/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.png
new file mode 100644
index 000000000000..b69426270b10
Binary files /dev/null and b/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.png differ
-- 
cgit v1.2.3


From 15a04d4e76bd7ba755591f2369c574d8a0a7dc5d Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 14 Nov 2016 14:32:32 -0200
Subject: docs-rst: auto-generate PDF image files

The PDF files that contain media images were actually generated
offline from their SVG or PNG source files.

Sphinx can handle PNG sources automatially. So, let's just
drop their PDF counterparts.

For SVG, however, Sphinx doesn't produce the right tags to
use the TexLive SVG support. Also, the SVG support is done via
shell execution, with is not nice.

So, while we don't have any support for SVG inside Sphinx
core or as an extension, move the logic to build them to Makefile,
producing the PDF images on runtime.

NOTE: due to the way Sphinx works, the PDF images should be
generated inside the Kernel source tree, as otherwise Sphinx
won't find it, not obeying what's specified by "O=" makefile
parameter.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/Makefile.sphinx                      |   3 +-
 Documentation/media/.gitignore                     |   1 +
 Documentation/media/Makefile                       |  29 +-
 Documentation/media/intro.rst                      |   4 +-
 .../media/media_api_files/typical_media_device.pdf | Bin 52895 -> 0 bytes
 .../media/media_api_files/typical_media_device.svg |  28 -
 Documentation/media/typical_media_device.svg       |  28 +
 Documentation/media/uapi/dvb/dvbstb.svg            | 651 +++++++++++++++++++++
 Documentation/media/uapi/dvb/intro.rst             |   2 +-
 .../media/uapi/dvb/intro_files/dvbstb.pdf          | Bin 1881 -> 0 bytes
 .../media/uapi/dvb/intro_files/dvbstb.svg          | 651 ---------------------
 Documentation/media/uapi/v4l/bayer.png             | Bin 0 -> 9725 bytes
 Documentation/media/uapi/v4l/constraints.svg       | 346 +++++++++++
 Documentation/media/uapi/v4l/crop.png              | Bin 0 -> 3334 bytes
 Documentation/media/uapi/v4l/crop.rst              |   4 +-
 Documentation/media/uapi/v4l/crop_files/crop.pdf   | Bin 5846 -> 0 bytes
 Documentation/media/uapi/v4l/crop_files/crop.png   | Bin 3334 -> 0 bytes
 Documentation/media/uapi/v4l/dev-raw-vbi.rst       |  12 +-
 .../media/uapi/v4l/dev-raw-vbi_files/vbi_525.pdf   | Bin 3706 -> 0 bytes
 .../media/uapi/v4l/dev-raw-vbi_files/vbi_525.png   | Bin 2053 -> 0 bytes
 .../media/uapi/v4l/dev-raw-vbi_files/vbi_625.pdf   | Bin 3996 -> 0 bytes
 .../media/uapi/v4l/dev-raw-vbi_files/vbi_625.png   | Bin 2352 -> 0 bytes
 .../media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdf | Bin 7405 -> 0 bytes
 .../media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.png | Bin 906 -> 0 bytes
 Documentation/media/uapi/v4l/dev-subdev.rst        |  16 +-
 .../media/uapi/v4l/dev-subdev_files/pipeline.pdf   | Bin 20276 -> 0 bytes
 .../media/uapi/v4l/dev-subdev_files/pipeline.png   | Bin 12130 -> 0 bytes
 .../subdev-image-processing-crop.pdf               | Bin 20729 -> 0 bytes
 .../subdev-image-processing-crop.svg               |  63 --
 .../subdev-image-processing-full.pdf               | Bin 46311 -> 0 bytes
 .../subdev-image-processing-full.svg               | 163 ------
 ...ubdev-image-processing-scaling-multi-source.pdf | Bin 36714 -> 0 bytes
 ...ubdev-image-processing-scaling-multi-source.svg | 116 ----
 Documentation/media/uapi/v4l/field-order.rst       |   8 +-
 .../uapi/v4l/field-order_files/fieldseq_bt.pdf     | Bin 9185 -> 0 bytes
 .../uapi/v4l/field-order_files/fieldseq_bt.png     | Bin 12306 -> 0 bytes
 .../uapi/v4l/field-order_files/fieldseq_tb.pdf     | Bin 9173 -> 0 bytes
 .../uapi/v4l/field-order_files/fieldseq_tb.png     | Bin 12247 -> 0 bytes
 Documentation/media/uapi/v4l/fieldseq_bt.png       | Bin 0 -> 12306 bytes
 Documentation/media/uapi/v4l/fieldseq_tb.png       | Bin 0 -> 12247 bytes
 Documentation/media/uapi/v4l/nv12mt.png            | Bin 0 -> 1920 bytes
 Documentation/media/uapi/v4l/nv12mt_example.png    | Bin 0 -> 5261 bytes
 Documentation/media/uapi/v4l/pipeline.png          | Bin 0 -> 12130 bytes
 Documentation/media/uapi/v4l/pixfmt-nv12mt.rst     |   4 +-
 .../media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.png  | Bin 1920 -> 0 bytes
 .../v4l/pixfmt-nv12mt_files/nv12mt_example.png     | Bin 5261 -> 0 bytes
 Documentation/media/uapi/v4l/selection-api-003.rst |   2 +-
 .../uapi/v4l/selection-api-003_files/selection.png | Bin 11716 -> 0 bytes
 Documentation/media/uapi/v4l/selection.png         | Bin 0 -> 11716 bytes
 Documentation/media/uapi/v4l/subdev-formats.rst    |   4 +-
 .../media/uapi/v4l/subdev-formats_files/bayer.png  | Bin 9725 -> 0 bytes
 .../uapi/v4l/subdev-image-processing-crop.svg      |  63 ++
 .../uapi/v4l/subdev-image-processing-full.svg      | 163 ++++++
 ...ubdev-image-processing-scaling-multi-source.svg | 116 ++++
 Documentation/media/uapi/v4l/vbi_525.png           | Bin 0 -> 2053 bytes
 Documentation/media/uapi/v4l/vbi_625.png           | Bin 0 -> 2352 bytes
 Documentation/media/uapi/v4l/vbi_hsync.png         | Bin 0 -> 906 bytes
 .../media/uapi/v4l/vidioc-g-selection.rst          |   4 +-
 .../v4l/vidioc-g-selection_files/constraints.svg   | 346 -----------
 59 files changed, 1427 insertions(+), 1400 deletions(-)
 create mode 100644 Documentation/media/.gitignore
 delete mode 100644 Documentation/media/media_api_files/typical_media_device.pdf
 delete mode 100644 Documentation/media/media_api_files/typical_media_device.svg
 create mode 100644 Documentation/media/typical_media_device.svg
 create mode 100644 Documentation/media/uapi/dvb/dvbstb.svg
 delete mode 100644 Documentation/media/uapi/dvb/intro_files/dvbstb.pdf
 delete mode 100644 Documentation/media/uapi/dvb/intro_files/dvbstb.svg
 create mode 100644 Documentation/media/uapi/v4l/bayer.png
 create mode 100644 Documentation/media/uapi/v4l/constraints.svg
 create mode 100644 Documentation/media/uapi/v4l/crop.png
 delete mode 100644 Documentation/media/uapi/v4l/crop_files/crop.pdf
 delete mode 100644 Documentation/media/uapi/v4l/crop_files/crop.png
 delete mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.pdf
 delete mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.png
 delete mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.pdf
 delete mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.png
 delete mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdf
 delete mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.png
 delete mode 100644 Documentation/media/uapi/v4l/dev-subdev_files/pipeline.pdf
 delete mode 100644 Documentation/media/uapi/v4l/dev-subdev_files/pipeline.png
 delete mode 100644 Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.pdf
 delete mode 100644 Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.svg
 delete mode 100644 Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.pdf
 delete mode 100644 Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.svg
 delete mode 100644 Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.pdf
 delete mode 100644 Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.svg
 delete mode 100644 Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.pdf
 delete mode 100644 Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.png
 delete mode 100644 Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.pdf
 delete mode 100644 Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.png
 create mode 100644 Documentation/media/uapi/v4l/fieldseq_bt.png
 create mode 100644 Documentation/media/uapi/v4l/fieldseq_tb.png
 create mode 100644 Documentation/media/uapi/v4l/nv12mt.png
 create mode 100644 Documentation/media/uapi/v4l/nv12mt_example.png
 create mode 100644 Documentation/media/uapi/v4l/pipeline.png
 delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.png
 delete mode 100644 Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.png
 delete mode 100644 Documentation/media/uapi/v4l/selection-api-003_files/selection.png
 create mode 100644 Documentation/media/uapi/v4l/selection.png
 delete mode 100644 Documentation/media/uapi/v4l/subdev-formats_files/bayer.png
 create mode 100644 Documentation/media/uapi/v4l/subdev-image-processing-crop.svg
 create mode 100644 Documentation/media/uapi/v4l/subdev-image-processing-full.svg
 create mode 100644 Documentation/media/uapi/v4l/subdev-image-processing-scaling-multi-source.svg
 create mode 100644 Documentation/media/uapi/v4l/vbi_525.png
 create mode 100644 Documentation/media/uapi/v4l/vbi_625.png
 create mode 100644 Documentation/media/uapi/v4l/vbi_hsync.png
 delete mode 100644 Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.svg

diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
index ec0c77d028db..a23d3c8b4848 100644
--- a/Documentation/Makefile.sphinx
+++ b/Documentation/Makefile.sphinx
@@ -54,7 +54,7 @@ loop_cmd = $(echo-cmd) $(cmd_$(1))
 #    e.g. "media" for the linux-tv book-set at ./Documentation/media
 
 quiet_cmd_sphinx = SPHINX  $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
-      cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media all;\
+      cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2;\
 	BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
 	$(SPHINXBUILD) \
 	-b $2 \
@@ -98,6 +98,7 @@ installmandocs:
 
 cleandocs:
 	$(Q)rm -rf $(BUILDDIR)
+	$(Q)$(MAKE) -C Documentation/media clean
 
 endif # HAVE_SPHINX
 
diff --git a/Documentation/media/.gitignore b/Documentation/media/.gitignore
new file mode 100644
index 000000000000..a1363379944a
--- /dev/null
+++ b/Documentation/media/.gitignore
@@ -0,0 +1 @@
+*.pdf
diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index a7fb35291f6c..297b85c37ab9 100644
--- a/Documentation/media/Makefile
+++ b/Documentation/media/Makefile
@@ -10,8 +10,35 @@ FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst net.h.rst video.h.rst \
 
 TARGETS := $(addprefix $(BUILDDIR)/, $(FILES))
 
-.PHONY: all
+IMAGES = \
+	typical_media_device.svg \
+	uapi/dvb/dvbstb.svg \
+	uapi/v4l/constraints.svg \
+	uapi/v4l/subdev-image-processing-full.svg \
+	uapi/v4l/subdev-image-processing-scaling-multi-source.svg \
+	uapi/v4l/subdev-image-processing-crop.svg \
+
+IMGTGT := $(patsubst %.png,%.pdf,$(patsubst %.svg,%.pdf,$(IMAGES)))
+IMGPDF := $(patsubst %,$(SRC_DIR)/%,$(IMGTGT))
+
+cmd = $(echo-cmd) $(cmd_$(1))
+
+quiet_cmd_genpdf = GENPDF  $2
+      cmd_genpdf = convert $2 $3
+
+%.pdf: %.svg
+	@$(call cmd,genpdf,$<,$@)
+
+.PHONY: all html epub xml latex
+
 all: $(BUILDDIR) ${TARGETS}
+html: all
+epub: all
+xml: all
+latex: $(IMGPDF) all
+
+clean:
+	-rm $(IMGTGT) 2>/dev/null
 
 $(BUILDDIR):
 	$(Q)mkdir -p $@
diff --git a/Documentation/media/intro.rst b/Documentation/media/intro.rst
index f6086c159772..8f7490c9a8ef 100644
--- a/Documentation/media/intro.rst
+++ b/Documentation/media/intro.rst
@@ -13,8 +13,8 @@ A typical media device hardware is shown at :ref:`typical_media_device`.
 
 .. _typical_media_device:
 
-.. figure::  media_api_files/typical_media_device.*
-    :alt:    typical_media_device.svg
+.. figure::  typical_media_device.*
+    :alt:    typical_media_device.pdf / typical_media_device.svg
     :align:  center
 
     Typical Media Device
diff --git a/Documentation/media/media_api_files/typical_media_device.pdf b/Documentation/media/media_api_files/typical_media_device.pdf
deleted file mode 100644
index d000d802b20f..000000000000
Binary files a/Documentation/media/media_api_files/typical_media_device.pdf and /dev/null differ
diff --git a/Documentation/media/media_api_files/typical_media_device.svg b/Documentation/media/media_api_files/typical_media_device.svg
deleted file mode 100644
index f0c82f72c4b6..000000000000
--- a/Documentation/media/media_api_files/typical_media_device.svg
+++ /dev/null
@@ -1,28 +0,0 @@
-
-Audio decoder
-Video decoder
-Audio encoder
-Button Key/IR input logic
-EEPROM
-Sensor
-System Bus
-Demux
-Conditional Access Module
-Video encoder
-Radio / Analog TV
-Digital TV
-PS.: picture is not complete: other blocks may be present
-Webcam
-Processing blocks
-Smartcard
-TunerFM/TV
-Satellite Equipment Control (SEC)
-Demod
-I2C Bus (control bus)
-Digital TV Frontend
-
-CPU
-PCI, USB, SPI, I2C, ...
-Bridge
- DMA
-
diff --git a/Documentation/media/typical_media_device.svg b/Documentation/media/typical_media_device.svg
new file mode 100644
index 000000000000..f0c82f72c4b6
--- /dev/null
+++ b/Documentation/media/typical_media_device.svg
@@ -0,0 +1,28 @@
+
+Audio decoder
+Video decoder
+Audio encoder
+Button Key/IR input logic
+EEPROM
+Sensor
+System Bus
+Demux
+Conditional Access Module
+Video encoder
+Radio / Analog TV
+Digital TV
+PS.: picture is not complete: other blocks may be present
+Webcam
+Processing blocks
+Smartcard
+TunerFM/TV
+Satellite Equipment Control (SEC)
+Demod
+I2C Bus (control bus)
+Digital TV Frontend
+
+CPU
+PCI, USB, SPI, I2C, ...
+Bridge
+ DMA
+
diff --git a/Documentation/media/uapi/dvb/dvbstb.svg b/Documentation/media/uapi/dvb/dvbstb.svg
new file mode 100644
index 000000000000..c4140fb518af
--- /dev/null
+++ b/Documentation/media/uapi/dvb/dvbstb.svg
@@ -0,0 +1,651 @@
+
+image/svg+xmlAntena
+Frontend
+CA
+Demux
+SEC
+Audio
+Video
+TV
+
\ No newline at end of file
diff --git a/Documentation/media/uapi/dvb/intro.rst b/Documentation/media/uapi/dvb/intro.rst
index 11b96a19a9ab..2ed5c23102b4 100644
--- a/Documentation/media/uapi/dvb/intro.rst
+++ b/Documentation/media/uapi/dvb/intro.rst
@@ -55,7 +55,7 @@ Overview
 
 .. _stb_components:
 
-.. figure::  intro_files/dvbstb.*
+.. figure::  dvbstb.*
     :alt:    dvbstb.pdf / dvbstb.svg
     :align:  center
 
diff --git a/Documentation/media/uapi/dvb/intro_files/dvbstb.pdf b/Documentation/media/uapi/dvb/intro_files/dvbstb.pdf
deleted file mode 100644
index 0fa75d90c3eb..000000000000
Binary files a/Documentation/media/uapi/dvb/intro_files/dvbstb.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/dvb/intro_files/dvbstb.svg b/Documentation/media/uapi/dvb/intro_files/dvbstb.svg
deleted file mode 100644
index c4140fb518af..000000000000
--- a/Documentation/media/uapi/dvb/intro_files/dvbstb.svg
+++ /dev/null
@@ -1,651 +0,0 @@
-
-image/svg+xmlAntena
-Frontend
-CA
-Demux
-SEC
-Audio
-Video
-TV
-
\ No newline at end of file
diff --git a/Documentation/media/uapi/v4l/bayer.png b/Documentation/media/uapi/v4l/bayer.png
new file mode 100644
index 000000000000..9b15fb22e817
Binary files /dev/null and b/Documentation/media/uapi/v4l/bayer.png differ
diff --git a/Documentation/media/uapi/v4l/constraints.svg b/Documentation/media/uapi/v4l/constraints.svg
new file mode 100644
index 000000000000..f710ee46b1f8
--- /dev/null
+++ b/Documentation/media/uapi/v4l/constraints.svg
@@ -0,0 +1,346 @@
+
+image/svg+xmlV4L2_SEL_FLAG_GE
+ORIGINAL
+V4L2_SEL_FLAG_LE
+
\ No newline at end of file
diff --git a/Documentation/media/uapi/v4l/crop.png b/Documentation/media/uapi/v4l/crop.png
new file mode 100644
index 000000000000..225998c395df
Binary files /dev/null and b/Documentation/media/uapi/v4l/crop.png differ
diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst
index 3ea733a8eef8..578c6f3d20f3 100644
--- a/Documentation/media/uapi/v4l/crop.rst
+++ b/Documentation/media/uapi/v4l/crop.rst
@@ -53,8 +53,8 @@ Cropping Structures
 
 .. _crop-scale:
 
-.. figure::  crop_files/crop.*
-    :alt:    crop.pdf / crop.gif
+.. figure::  crop.png
+    :alt:    crop.png
     :align:  center
 
     Image Cropping, Insertion and Scaling
diff --git a/Documentation/media/uapi/v4l/crop_files/crop.pdf b/Documentation/media/uapi/v4l/crop_files/crop.pdf
deleted file mode 100644
index c9fb81cd32f3..000000000000
Binary files a/Documentation/media/uapi/v4l/crop_files/crop.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/crop_files/crop.png b/Documentation/media/uapi/v4l/crop_files/crop.png
deleted file mode 100644
index 225998c395df..000000000000
Binary files a/Documentation/media/uapi/v4l/crop_files/crop.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi.rst b/Documentation/media/uapi/v4l/dev-raw-vbi.rst
index b82d837e4ff1..f81d906137ee 100644
--- a/Documentation/media/uapi/v4l/dev-raw-vbi.rst
+++ b/Documentation/media/uapi/v4l/dev-raw-vbi.rst
@@ -221,8 +221,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT ` does
 
 .. _vbi-hsync:
 
-.. figure::  dev-raw-vbi_files/vbi_hsync.*
-    :alt:    vbi_hsync.pdf / vbi_hsync.gif
+.. figure::  vbi_hsync.png
+    :alt:    vbi_hsync.png
     :align:  center
 
     **Figure 4.1. Line synchronization**
@@ -230,8 +230,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT ` does
 
 .. _vbi-525:
 
-.. figure::  dev-raw-vbi_files/vbi_525.*
-    :alt:    vbi_525.pdf / vbi_525.gif
+.. figure::  vbi_525.png
+    :alt:    vbi_525.png
     :align:  center
 
     **Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)**
@@ -240,8 +240,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT ` does
 
 .. _vbi-625:
 
-.. figure::  dev-raw-vbi_files/vbi_625.*
-    :alt:    vbi_625.pdf / vbi_625.gif
+.. figure::  vbi_625.png
+    :alt:    vbi_625.png
     :align:  center
 
     **Figure 4.3. ITU-R 625 line numbering**
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.pdf b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.pdf
deleted file mode 100644
index 0bae28385dfa..000000000000
Binary files a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.png b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.png
deleted file mode 100644
index 24937dbec337..000000000000
Binary files a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_525.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.pdf b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.pdf
deleted file mode 100644
index bf29b95dcd08..000000000000
Binary files a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.png b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.png
deleted file mode 100644
index 25c671af41ad..000000000000
Binary files a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_625.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdf b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdf
deleted file mode 100644
index 200b668189bf..000000000000
Binary files a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.png b/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.png
deleted file mode 100644
index b04ae50385a7..000000000000
Binary files a/Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst
index fb4d0d45b216..c18e9c5427ee 100644
--- a/Documentation/media/uapi/v4l/dev-subdev.rst
+++ b/Documentation/media/uapi/v4l/dev-subdev.rst
@@ -99,8 +99,8 @@ the video sensor and the host image processing hardware.
 
 .. _pipeline-scaling:
 
-.. figure::  dev-subdev_files/pipeline.*
-    :alt:    pipeline.pdf / pipeline.png
+.. figure::  pipeline.png
+    :alt:    pipeline.png
     :align:  center
 
     Image Format Negotiation on Pipelines
@@ -404,8 +404,8 @@ selection will refer to the sink pad format dimensions instead.
 
 .. _subdev-image-processing-crop:
 
-.. figure::  dev-subdev_files/subdev-image-processing-crop.*
-    :alt:    subdev-image-processing-crop.svg
+.. figure::  subdev-image-processing-crop.*
+    :alt:    subdev-image-processing-crop.pdf / subdev-image-processing-crop.svg
     :align:  center
 
     **Figure 4.5. Image processing in subdevs: simple crop example**
@@ -421,8 +421,8 @@ pad.
 
 .. _subdev-image-processing-scaling-multi-source:
 
-.. figure::  dev-subdev_files/subdev-image-processing-scaling-multi-source.*
-    :alt:    subdev-image-processing-scaling-multi-source.svg
+.. figure::  subdev-image-processing-scaling-multi-source.*
+    :alt:    subdev-image-processing-scaling-multi-source.pdf / subdev-image-processing-scaling-multi-source.svg
     :align:  center
 
     **Figure 4.6. Image processing in subdevs: scaling with multiple sources**
@@ -437,8 +437,8 @@ an area at location specified by the source crop rectangle from it.
 
 .. _subdev-image-processing-full:
 
-.. figure::  dev-subdev_files/subdev-image-processing-full.*
-    :alt:    subdev-image-processing-full.svg
+.. figure::  subdev-image-processing-full.*
+    :alt:    subdev-image-processing-full.pdf / subdev-image-processing-full.svg
     :align:  center
 
     **Figure 4.7. Image processing in subdevs: scaling and composition with multiple sinks and sources**
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.pdf b/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.pdf
deleted file mode 100644
index ee3e37f04b6a..000000000000
Binary files a/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.png b/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.png
deleted file mode 100644
index f19b86c2c24d..000000000000
Binary files a/Documentation/media/uapi/v4l/dev-subdev_files/pipeline.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.pdf b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.pdf
deleted file mode 100644
index 29a806f839b4..000000000000
Binary files a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.svg b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.svg
deleted file mode 100644
index 18b0f5de9ed2..000000000000
--- a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-crop.svg
+++ /dev/null
@@ -1,63 +0,0 @@
-
-
-
-  
-  
-    
-    
-  
-  
-    
-    
-  
-  
-    sink
-    crop
-    selection
-  
-  
-    
-  
-  
-    sink media
-    bus format
-  
-  
-    source media
-    bus format
-  
-  
-    
-    
-  
-  
-  
-  
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    pad 1 (source)
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    pad 0 (sink)
-  
-
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.pdf b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.pdf
deleted file mode 100644
index b78a8e8f6b35..000000000000
Binary files a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.svg b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.svg
deleted file mode 100644
index 3322cf4c0093..000000000000
--- a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-full.svg
+++ /dev/null
@@ -1,163 +0,0 @@
-
-
-
-  
-    
-    
-  
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    pad 0 (sink)
-  
-  
-    pad 2 (source)
-  
-  
-    
-    
-  
-  
-    
-    
-  
-  
-    
-  
-  
-    sink media
-    bus format
-  
-  
-    
-    
-  
-  
-  
-  
-  
-  
-    sink compose
-    selection (scaling)
-  
-  
-    
-    
-  
-  
-    source media
-    bus format
-  
-  
-    
-    
-  
-  
-  
-  
-  
-  
-    sink compose
-    bounds selection
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    pad 1 (sink)
-  
-  
-    
-    
-  
-  
-    
-    
-  
-  
-    
-  
-  
-  
-  
-  
-  
-  
-  
-    
-    
-  
-  
-  
-  
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    pad 3 (source)
-  
-  
-    sink
-    crop
-    selection
-  
-  
-    source
-    crop
-    selection
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.pdf b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.pdf
deleted file mode 100644
index 8f7a95b6eb4d..000000000000
Binary files a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.svg b/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.svg
deleted file mode 100644
index 2340c0f8bc92..000000000000
--- a/Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.svg
+++ /dev/null
@@ -1,116 +0,0 @@
-
-
-
-  
-  
-    
-    
-  
-  
-    
-    
-  
-  
-    sink
-    crop
-    selection
-  
-  
-    
-  
-  
-    sink media
-    bus format
-  
-  
-    
-    
-  
-  
-  
-  
-  
-  
-    sink compose
-    selection (scaling)
-  
-  
-    
-    
-  
-  
-    source
-    crop
-    selection
-  
-  
-    source media
-    bus format
-  
-  
-    
-    
-  
-  
-  
-  
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    pad 1 (source)
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    pad 0 (sink)
-  
-  
-  
-    
-    
-  
-  
-  
-  
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    pad 2 (source)
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-
diff --git a/Documentation/media/uapi/v4l/field-order.rst b/Documentation/media/uapi/v4l/field-order.rst
index 50779a67c3fd..a7e1b4dae343 100644
--- a/Documentation/media/uapi/v4l/field-order.rst
+++ b/Documentation/media/uapi/v4l/field-order.rst
@@ -141,8 +141,8 @@ enum v4l2_field
 Field Order, Top Field First Transmitted
 ========================================
 
-.. figure::  field-order_files/fieldseq_tb.*
-    :alt:    fieldseq_tb.pdf / fieldseq_tb.gif
+.. figure::  fieldseq_tb.png
+    :alt:    fieldseq_tb.png
     :align:  center
 
 
@@ -151,7 +151,7 @@ Field Order, Top Field First Transmitted
 Field Order, Bottom Field First Transmitted
 ===========================================
 
-.. figure::  field-order_files/fieldseq_bt.*
-    :alt:    fieldseq_bt.pdf / fieldseq_bt.gif
+.. figure::  fieldseq_bt.png
+    :alt:    fieldseq_bt.png
     :align:  center
 
diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.pdf b/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.pdf
deleted file mode 100644
index 26598b23f80d..000000000000
Binary files a/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.png b/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.png
deleted file mode 100644
index 888ce6fed817..000000000000
Binary files a/Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.pdf b/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.pdf
deleted file mode 100644
index 4965b22ddb3a..000000000000
Binary files a/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.pdf and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.png b/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.png
deleted file mode 100644
index b69426270b10..000000000000
Binary files a/Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/fieldseq_bt.png b/Documentation/media/uapi/v4l/fieldseq_bt.png
new file mode 100644
index 000000000000..888ce6fed817
Binary files /dev/null and b/Documentation/media/uapi/v4l/fieldseq_bt.png differ
diff --git a/Documentation/media/uapi/v4l/fieldseq_tb.png b/Documentation/media/uapi/v4l/fieldseq_tb.png
new file mode 100644
index 000000000000..b69426270b10
Binary files /dev/null and b/Documentation/media/uapi/v4l/fieldseq_tb.png differ
diff --git a/Documentation/media/uapi/v4l/nv12mt.png b/Documentation/media/uapi/v4l/nv12mt.png
new file mode 100644
index 000000000000..41401860fb73
Binary files /dev/null and b/Documentation/media/uapi/v4l/nv12mt.png differ
diff --git a/Documentation/media/uapi/v4l/nv12mt_example.png b/Documentation/media/uapi/v4l/nv12mt_example.png
new file mode 100644
index 000000000000..7775f5d7cc46
Binary files /dev/null and b/Documentation/media/uapi/v4l/nv12mt_example.png differ
diff --git a/Documentation/media/uapi/v4l/pipeline.png b/Documentation/media/uapi/v4l/pipeline.png
new file mode 100644
index 000000000000..f19b86c2c24d
Binary files /dev/null and b/Documentation/media/uapi/v4l/pipeline.png differ
diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst b/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst
index 9f250a1df2f6..c8a77bc79f2f 100644
--- a/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst
@@ -33,7 +33,7 @@ Layout of macroblocks in memory is presented in the following figure.
 
 .. _nv12mt:
 
-.. figure::  pixfmt-nv12mt_files/nv12mt.*
+.. figure::  nv12mt.png
     :alt:    nv12mt.png
     :align:  center
 
@@ -50,7 +50,7 @@ interleaved. Height of the buffer is aligned to 32.
 
 .. _nv12mt_ex:
 
-.. figure::  pixfmt-nv12mt_files/nv12mt_example.*
+.. figure::  nv12mt_example.png
     :alt:    nv12mt_example.png
     :align:  center
 
diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.png b/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.png
deleted file mode 100644
index 41401860fb73..000000000000
Binary files a/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.png b/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.png
deleted file mode 100644
index 7775f5d7cc46..000000000000
Binary files a/Documentation/media/uapi/v4l/pixfmt-nv12mt_files/nv12mt_example.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/selection-api-003.rst b/Documentation/media/uapi/v4l/selection-api-003.rst
index 15cb3b79f12c..207349c17ead 100644
--- a/Documentation/media/uapi/v4l/selection-api-003.rst
+++ b/Documentation/media/uapi/v4l/selection-api-003.rst
@@ -7,7 +7,7 @@ Selection targets
 
 .. _sel-targets-capture:
 
-.. figure::  selection-api-003_files/selection.*
+.. figure::  selection.png
     :alt:    selection.png
     :align:  center
 
diff --git a/Documentation/media/uapi/v4l/selection-api-003_files/selection.png b/Documentation/media/uapi/v4l/selection-api-003_files/selection.png
deleted file mode 100644
index bfc523eae570..000000000000
Binary files a/Documentation/media/uapi/v4l/selection-api-003_files/selection.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/selection.png b/Documentation/media/uapi/v4l/selection.png
new file mode 100644
index 000000000000..bfc523eae570
Binary files /dev/null and b/Documentation/media/uapi/v4l/selection.png differ
diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst
index 65105609374b..2f9c135dfadd 100644
--- a/Documentation/media/uapi/v4l/subdev-formats.rst
+++ b/Documentation/media/uapi/v4l/subdev-formats.rst
@@ -1514,14 +1514,12 @@ be named ``MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE``.
 
 .. _bayer-patterns:
 
-.. figure::  subdev-formats_files/bayer.*
+.. figure::  bayer.png
     :alt:    bayer.png
     :align:  center
 
     **Figure 4.8 Bayer Patterns**
 
-
-
 The following table lists existing packed Bayer formats. The data
 organization is given as an example for the first pixel only.
 
diff --git a/Documentation/media/uapi/v4l/subdev-formats_files/bayer.png b/Documentation/media/uapi/v4l/subdev-formats_files/bayer.png
deleted file mode 100644
index 9b15fb22e817..000000000000
Binary files a/Documentation/media/uapi/v4l/subdev-formats_files/bayer.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/subdev-image-processing-crop.svg b/Documentation/media/uapi/v4l/subdev-image-processing-crop.svg
new file mode 100644
index 000000000000..18b0f5de9ed2
--- /dev/null
+++ b/Documentation/media/uapi/v4l/subdev-image-processing-crop.svg
@@ -0,0 +1,63 @@
+
+
+
+  
+  
+    
+    
+  
+  
+    
+    
+  
+  
+    sink
+    crop
+    selection
+  
+  
+    
+  
+  
+    sink media
+    bus format
+  
+  
+    source media
+    bus format
+  
+  
+    
+    
+  
+  
+  
+  
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    pad 1 (source)
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    pad 0 (sink)
+  
+
diff --git a/Documentation/media/uapi/v4l/subdev-image-processing-full.svg b/Documentation/media/uapi/v4l/subdev-image-processing-full.svg
new file mode 100644
index 000000000000..3322cf4c0093
--- /dev/null
+++ b/Documentation/media/uapi/v4l/subdev-image-processing-full.svg
@@ -0,0 +1,163 @@
+
+
+
+  
+    
+    
+  
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    pad 0 (sink)
+  
+  
+    pad 2 (source)
+  
+  
+    
+    
+  
+  
+    
+    
+  
+  
+    
+  
+  
+    sink media
+    bus format
+  
+  
+    
+    
+  
+  
+  
+  
+  
+  
+    sink compose
+    selection (scaling)
+  
+  
+    
+    
+  
+  
+    source media
+    bus format
+  
+  
+    
+    
+  
+  
+  
+  
+  
+  
+    sink compose
+    bounds selection
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    pad 1 (sink)
+  
+  
+    
+    
+  
+  
+    
+    
+  
+  
+    
+  
+  
+  
+  
+  
+  
+  
+  
+    
+    
+  
+  
+  
+  
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    pad 3 (source)
+  
+  
+    sink
+    crop
+    selection
+  
+  
+    source
+    crop
+    selection
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+
diff --git a/Documentation/media/uapi/v4l/subdev-image-processing-scaling-multi-source.svg b/Documentation/media/uapi/v4l/subdev-image-processing-scaling-multi-source.svg
new file mode 100644
index 000000000000..2340c0f8bc92
--- /dev/null
+++ b/Documentation/media/uapi/v4l/subdev-image-processing-scaling-multi-source.svg
@@ -0,0 +1,116 @@
+
+
+
+  
+  
+    
+    
+  
+  
+    
+    
+  
+  
+    sink
+    crop
+    selection
+  
+  
+    
+  
+  
+    sink media
+    bus format
+  
+  
+    
+    
+  
+  
+  
+  
+  
+  
+    sink compose
+    selection (scaling)
+  
+  
+    
+    
+  
+  
+    source
+    crop
+    selection
+  
+  
+    source media
+    bus format
+  
+  
+    
+    
+  
+  
+  
+  
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    pad 1 (source)
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    pad 0 (sink)
+  
+  
+  
+    
+    
+  
+  
+  
+  
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    pad 2 (source)
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+
diff --git a/Documentation/media/uapi/v4l/vbi_525.png b/Documentation/media/uapi/v4l/vbi_525.png
new file mode 100644
index 000000000000..24937dbec337
Binary files /dev/null and b/Documentation/media/uapi/v4l/vbi_525.png differ
diff --git a/Documentation/media/uapi/v4l/vbi_625.png b/Documentation/media/uapi/v4l/vbi_625.png
new file mode 100644
index 000000000000..25c671af41ad
Binary files /dev/null and b/Documentation/media/uapi/v4l/vbi_625.png differ
diff --git a/Documentation/media/uapi/v4l/vbi_hsync.png b/Documentation/media/uapi/v4l/vbi_hsync.png
new file mode 100644
index 000000000000..b04ae50385a7
Binary files /dev/null and b/Documentation/media/uapi/v4l/vbi_hsync.png differ
diff --git a/Documentation/media/uapi/v4l/vidioc-g-selection.rst b/Documentation/media/uapi/v4l/vidioc-g-selection.rst
index 6da359e50668..deb1f6fb473b 100644
--- a/Documentation/media/uapi/v4l/vidioc-g-selection.rst
+++ b/Documentation/media/uapi/v4l/vidioc-g-selection.rst
@@ -129,8 +129,8 @@ Selection targets and flags are documented in
 
 .. _sel-const-adjust:
 
-.. figure::  vidioc-g-selection_files/constraints.*
-    :alt:    constraints.svg
+.. figure::  constraints.*
+    :alt:    constraints.pdf / constraints.svg
     :align:  center
 
     Size adjustments with constraint flags.
diff --git a/Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.svg b/Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.svg
deleted file mode 100644
index f710ee46b1f8..000000000000
--- a/Documentation/media/uapi/v4l/vidioc-g-selection_files/constraints.svg
+++ /dev/null
@@ -1,346 +0,0 @@
-
-image/svg+xmlV4L2_SEL_FLAG_GE
-ORIGINAL
-V4L2_SEL_FLAG_LE
-
\ No newline at end of file
-- 
cgit v1.2.3


From c54b6b37796edbe7eb48756d4be151479ea430ab Mon Sep 17 00:00:00 2001
From: Jonathan Corbet 
Date: Wed, 16 Nov 2016 15:38:03 -0700
Subject: docs: Avoid warning on cleandocs

Recent Makefile changes added an rm command without the requisite "-f",
leading to warnings if the files do not exist.  Make it be quiet again.

Signed-off-by: Jonathan Corbet 
---
 Documentation/media/Makefile | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index 297b85c37ab9..c22a30b07821 100644
--- a/Documentation/media/Makefile
+++ b/Documentation/media/Makefile
@@ -38,7 +38,7 @@ xml: all
 latex: $(IMGPDF) all
 
 clean:
-	-rm $(IMGTGT) 2>/dev/null
+	-rm -f $(IMGTGT) 2>/dev/null
 
 $(BUILDDIR):
 	$(Q)mkdir -p $@
@@ -85,4 +85,4 @@ $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exception
 	@$($(quiet)gen_rst)
 
 cleandocs:
-	-rm ${TARGETS}
+	-rm -f ${TARGETS}
-- 
cgit v1.2.3


From 22917b992d3713157e759f23a5a090687d004331 Mon Sep 17 00:00:00 2001
From: Jonathan Corbet 
Date: Wed, 16 Nov 2016 16:07:02 -0700
Subject: docs: Add more manuals to the PDF build

There were a few manuals that weren't being built in PDF format, but
there's no reason not to...

Signed-off-by: Jonathan Corbet 
---
 Documentation/conf.py          | 6 ++++++
 Documentation/core-api/conf.py | 5 +++++
 Documentation/security/conf.py | 8 ++++++++
 3 files changed, 19 insertions(+)
 create mode 100644 Documentation/security/conf.py

diff --git a/Documentation/conf.py b/Documentation/conf.py
index db78974aad26..ba38bcf485a9 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -342,6 +342,10 @@ if major == 1 and minor > 3:
 latex_documents = [
     ('admin-guide/index', 'linux-user.tex', 'Linux Kernel User Documentation',
      'The kernel development community', 'manual'),
+    ('core-api/index', 'core-api.tex', 'The kernel core API manual',
+     'The kernel development community', 'manual'),
+    ('driver-api/index', 'driver-api.tex', 'The kernel driver API manual',
+     'The kernel development community', 'manual'),
     ('kernel-documentation', 'kernel-documentation.tex', 'The Linux Kernel Documentation',
      'The kernel development community', 'manual'),
     ('process/index', 'development-process.tex', 'Linux Kernel Development Documentation',
@@ -350,6 +354,8 @@ latex_documents = [
      'The kernel development community', 'manual'),
     ('media/index', 'media.tex', 'Linux Media Subsystem Documentation',
      'The kernel development community', 'manual'),
+    ('security/index', 'security.tex', 'The kernel security subsystem manual',
+     'The kernel development community', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
diff --git a/Documentation/core-api/conf.py b/Documentation/core-api/conf.py
index fed87ab7f486..db1f7659f3da 100644
--- a/Documentation/core-api/conf.py
+++ b/Documentation/core-api/conf.py
@@ -3,3 +3,8 @@
 project = "Core-API Documentation"
 
 tags.add("subproject")
+
+latex_documents = [
+    ('index', 'core-api.tex', project,
+     'The kernel development community', 'manual'),
+]
diff --git a/Documentation/security/conf.py b/Documentation/security/conf.py
new file mode 100644
index 000000000000..472fc9a8eb67
--- /dev/null
+++ b/Documentation/security/conf.py
@@ -0,0 +1,8 @@
+project = "The kernel security subsystem manual"
+
+tags.add("subproject")
+
+latex_documents = [
+    ('index', 'security.tex', project,
+     'The kernel development community', 'manual'),
+]
-- 
cgit v1.2.3


From 47f421221029e8515b71e7e2379eba8406b7f458 Mon Sep 17 00:00:00 2001
From: Mark Rutland 
Date: Wed, 16 Nov 2016 11:13:59 +0000
Subject: Documentation: atomic_ops: use {READ,WRITE}_ONCE()

While the {READ,WRITE}_ONCE() macros should be used in preference to
ACCESS_ONCE(), the atomic documentation uses the latter exclusively.

To point people in the right direction, and as a step towards the
eventual removal of ACCESS_ONCE(), update the documentation to use the
{READ,WRITE}_ONCE() macros as appropriate.

Signed-off-by: Mark Rutland 
Cc: Boqun Feng 
Cc: Peter Zijlstra 
Cc: Will Deacon 
Acked-by: Paul E. McKenney 
Signed-off-by: Jonathan Corbet 
---
 Documentation/atomic_ops.txt | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/atomic_ops.txt b/Documentation/atomic_ops.txt
index 7281bf939779..6c5e8a9d2c6e 100644
--- a/Documentation/atomic_ops.txt
+++ b/Documentation/atomic_ops.txt
@@ -90,10 +90,10 @@ compiler optimizes the section accessing atomic_t variables.
 
 Properly aligned pointers, longs, ints, and chars (and unsigned
 equivalents) may be atomically loaded from and stored to in the same
-sense as described for atomic_read() and atomic_set().  The ACCESS_ONCE()
-macro should be used to prevent the compiler from using optimizations
-that might otherwise optimize accesses out of existence on the one hand,
-or that might create unsolicited accesses on the other.
+sense as described for atomic_read() and atomic_set().  The READ_ONCE()
+and WRITE_ONCE() macros should be used to prevent the compiler from using
+optimizations that might otherwise optimize accesses out of existence on
+the one hand, or that might create unsolicited accesses on the other.
 
 For example consider the following code:
 
@@ -112,7 +112,7 @@ the following:
 If you don't want the compiler to do this (and you probably don't), then
 you should use something like the following:
 
-	while (ACCESS_ONCE(a) < 0)
+	while (READ_ONCE(a) < 0)
 		do_something();
 
 Alternatively, you could place a barrier() call in the loop.
@@ -141,7 +141,7 @@ of registers: reloading from variable a could save a flush to the
 stack and later reload.  To prevent the compiler from attacking your
 code in this manner, write the following:
 
-	tmp_a = ACCESS_ONCE(a);
+	tmp_a = READ_ONCE(a);
 	do_something_with(tmp_a);
 	do_something_else_with(tmp_a);
 
@@ -166,14 +166,14 @@ that expected b to never have the value 42 if a was zero.  To prevent
 the compiler from doing this, write something like:
 
 	if (a)
-		ACCESS_ONCE(b) = 9;
+		WRITE_ONCE(b, 9);
 	else
-		ACCESS_ONCE(b) = 42;
+		WRITE_ONCE(b, 42);
 
 Don't even -think- about doing this without proper use of memory barriers,
 locks, or atomic operations if variable a can change at runtime!
 
-*** WARNING: ACCESS_ONCE() DOES NOT IMPLY A BARRIER! ***
+*** WARNING: READ_ONCE() OR WRITE_ONCE() DO NOT IMPLY A BARRIER! ***
 
 Now, we move onto the atomic operation interfaces typically implemented with
 the help of assembly code.
-- 
cgit v1.2.3


From 01e4644203b01fba5023784598f4d033e3bd3e28 Mon Sep 17 00:00:00 2001
From: Mark Rutland 
Date: Wed, 16 Nov 2016 11:12:49 +0000
Subject: Documentation: circular-buffers: use READ_ONCE()

While the {READ,WRITE}_ONCE() macros should be used in preference to
ACCESS_ONCE(), the circular buffer documentation uses the latter
exclusively.

To point people in the right direction, and as a step towards the
eventual removal of ACCESS_ONCE(), update the documentation to use
READ_ONCE(), as ACCESS_ONCE() is only used in a reader context in the
circular buffer documentation.

Signed-off-by: Mark Rutland 
Acked-by: David Howells 
Acked-by: Paul E. McKenney 
Signed-off-by: Jonathan Corbet 
---
 Documentation/circular-buffers.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/circular-buffers.txt b/Documentation/circular-buffers.txt
index 88951b179262..4a824d232472 100644
--- a/Documentation/circular-buffers.txt
+++ b/Documentation/circular-buffers.txt
@@ -161,7 +161,7 @@ The producer will look something like this:
 
 	unsigned long head = buffer->head;
 	/* The spin_unlock() and next spin_lock() provide needed ordering. */
-	unsigned long tail = ACCESS_ONCE(buffer->tail);
+	unsigned long tail = READ_ONCE(buffer->tail);
 
 	if (CIRC_SPACE(head, tail, buffer->size) >= 1) {
 		/* insert one item into the buffer */
@@ -222,7 +222,7 @@ This will instruct the CPU to make sure the index is up to date before reading
 the new item, and then it shall make sure the CPU has finished reading the item
 before it writes the new tail pointer, which will erase the item.
 
-Note the use of ACCESS_ONCE() and smp_load_acquire() to read the
+Note the use of READ_ONCE() and smp_load_acquire() to read the
 opposition index.  This prevents the compiler from discarding and
 reloading its cached value - which some compilers will do across
 smp_read_barrier_depends().  This isn't strictly needed if you can
-- 
cgit v1.2.3


From dd0b38d8eef86308dbbba7557400e4894e55e3c8 Mon Sep 17 00:00:00 2001
From: Oliver Neukum 
Date: Mon, 14 Nov 2016 15:52:43 +0100
Subject: Documentation: convert USB to new format

This is a conversion of the USB documentation to the Sphinx format.
No content was altered or reformatted.

Signed-off-by: Oliver 
Signed-off-by: Jonathan Corbet 
---
 Documentation/DocBook/Makefile     |   2 +-
 Documentation/DocBook/usb.tmpl     | 984 -------------------------------------
 Documentation/driver-api/index.rst |   1 +
 Documentation/driver-api/usb.rst   | 748 ++++++++++++++++++++++++++++
 4 files changed, 750 insertions(+), 985 deletions(-)
 delete mode 100644 Documentation/DocBook/usb.tmpl
 create mode 100644 Documentation/driver-api/usb.rst

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index 263e6577de66..857b772e9da1 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -9,7 +9,7 @@
 DOCBOOKS := z8530book.xml  \
 	    kernel-hacking.xml kernel-locking.xml deviceiobook.xml \
 	    writing_usb_driver.xml networking.xml \
-	    kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \
+	    kernel-api.xml filesystems.xml lsm.xml kgdb.xml \
 	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
 	    genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
 	    debugobjects.xml sh.xml regulator.xml \
diff --git a/Documentation/DocBook/usb.tmpl b/Documentation/DocBook/usb.tmpl
deleted file mode 100644
index e322691be67e..000000000000
--- a/Documentation/DocBook/usb.tmpl
+++ /dev/null
@@ -1,984 +0,0 @@
-
-
-
-
- 
-  The Linux-USB Host Side API
-  
-  
-   
-     This documentation is free software; you can redistribute
-     it and/or modify it under the terms of the GNU General Public
-     License as published by the Free Software Foundation; either
-     version 2 of the License, or (at your option) any later
-     version.
-   
-      
-   
-     This program is distributed in the hope that it will be
-     useful, but WITHOUT ANY WARRANTY; without even the implied
-     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-     See the GNU General Public License for more details.
-   
-      
-   
-     You should have received a copy of the GNU General Public
-     License along with this program; if not, write to the Free
-     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
-     MA 02111-1307 USA
-   
-      
-   
-     For more details see the file COPYING in the source
-     distribution of Linux.
-   
-  
- 
-
-
-
-
-    Introduction to USB on Linux
-
-    A Universal Serial Bus (USB) is used to connect a host,
-    such as a PC or workstation, to a number of peripheral
-    devices.  USB uses a tree structure, with the host as the
-    root (the system's master), hubs as interior nodes, and
-    peripherals as leaves (and slaves).
-    Modern PCs support several such trees of USB devices, usually
-    a few USB 3.0 (5 GBit/s) or USB 3.1 (10 GBit/s) and some legacy
-    USB 2.0 (480 MBit/s) busses just in case.
-    
-
-    That master/slave asymmetry was designed-in for a number of
-    reasons, one being ease of use.  It is not physically possible to
-    mistake upstream and downstream or it does not matter with a type C
-    plug
-    (or they are built into the peripheral).
-    Also, the host software doesn't need to deal with distributed
-    auto-configuration since the pre-designated master node manages all that.
-    
-
-    Kernel developers added USB support to Linux early in the 2.2 kernel
-    series and have been developing it further since then. Besides support
-    for each new generation of USB, various host controllers gained support,
-    new drivers for peripherals have been added and advanced features for latency
-    measurement and improved power management introduced.
-    
-
-    Linux can run inside USB devices as well as on
-    the hosts that control the devices.
-    But USB device drivers running inside those peripherals
-    don't do the same things as the ones running inside hosts,
-    so they've been given a different name:
-    gadget drivers.
-    This document does not cover gadget drivers.
-    
-
-    
-
-
-    USB Host-Side API Model
-
-    Host-side drivers for USB devices talk to the "usbcore" APIs.
-    There are two.  One is intended for
-    general-purpose drivers (exposed through
-    driver frameworks), and the other is for drivers that are
-    part of the core.
-    Such core drivers include the hub driver
-    (which manages trees of USB devices) and several different kinds
-    of host controller drivers,
-    which control individual busses.
-    
-
-    The device model seen by USB drivers is relatively complex.
-    
-     
-    
-
-	USB supports four kinds of data transfers
-	(control, bulk, interrupt, and isochronous).  Two of them (control
-	and bulk) use bandwidth as it's available,
-	while the other two (interrupt and isochronous)
-	are scheduled to provide guaranteed bandwidth.
-	
-
-	The device description model includes one or more
-	"configurations" per device, only one of which is active at a time.
-	Devices are supposed to be capable of operating at lower than their top
-	speeds and may provide a BOS descriptor showing the lowest speed they
-	remain fully operational at.
-	
-
-	From USB 3.0 on configurations have one or more "functions", which
-	provide a common functionality and are grouped together for purposes
-	of power management.
-	
-
-	Configurations or functions have one or more "interfaces", each
-	of which may have "alternate settings".  Interfaces may be
-	standardized by USB "Class" specifications, or may be specific to
-	a vendor or device.
-
-	USB device drivers actually bind to interfaces, not devices.
-	Think of them as "interface drivers", though you
-	may not see many devices where the distinction is important.
-	Most USB devices are simple, with only one configuration,
-	one function, one interface, and one alternate setting.
-	
-
-	Interfaces have one or more "endpoints", each of
-	which supports one type and direction of data transfer such as
-	"bulk out" or "interrupt in".  The entire configuration may have
-	up to sixteen endpoints in each direction, allocated as needed
-	among all the interfaces.
-	
-
-	Data transfer on USB is packetized; each endpoint
-	has a maximum packet size.
-	Drivers must often be aware of conventions such as flagging the end
-	of bulk transfers using "short" (including zero length) packets.
-	
-
-	The Linux USB API supports synchronous calls for
-	control and bulk messages.
-	It also supports asynchronous calls for all kinds of data transfer,
-	using request structures called "URBs" (USB Request Blocks).
-	
-
-    
-
-    Accordingly, the USB Core API exposed to device drivers
-    covers quite a lot of territory.  You'll probably need to consult
-    the USB 3.0 specification, available online from www.usb.org at
-    no cost, as well as class or device specifications.
-    
-
-    The only host-side drivers that actually touch hardware
-    (reading/writing registers, handling IRQs, and so on) are the HCDs.
-    In theory, all HCDs provide the same functionality through the same
-    API.  In practice, that's becoming mostly true,
-    but there are still differences that crop up especially with
-    fault handling on the less common controllers.
-    Different controllers don't necessarily report
-    the same aspects of failures, and recovery from faults (including
-    software-induced ones like unlinking an URB) isn't yet fully
-    consistent.
-    Device driver authors should make a point of doing disconnect
-    testing (while the device is active) with each different host
-    controller driver, to make sure drivers don't have bugs of
-    their own as well as to make sure they aren't relying on some
-    HCD-specific behavior.
-    
-
-    
-
-USB-Standard Types
-
-    In <linux/usb/ch9.h> you will find
-    the USB data types defined in chapter 9 of the USB specification.
-    These data types are used throughout USB, and in APIs including
-    this host side API, gadget APIs, and usbfs.
-    
-
-!Iinclude/linux/usb/ch9.h
-
-    
-
-Host-Side Data Types and Macros
-
-    The host side API exposes several layers to drivers, some of
-    which are more necessary than others.
-    These support lifecycle models for host side drivers
-    and devices, and support passing buffers through usbcore to
-    some HCD that performs the I/O for the device driver.
-    
-
-
-!Iinclude/linux/usb.h
-
-    
-
-    USB Core APIs
-
-    There are two basic I/O models in the USB API.
-    The most elemental one is asynchronous:  drivers submit requests
-    in the form of an URB, and the URB's completion callback
-    handles the next step.
-    All USB transfer types support that model, although there
-    are special cases for control URBs (which always have setup
-    and status stages, but may not have a data stage) and
-    isochronous URBs (which allow large packets and include
-    per-packet fault reports).
-    Built on top of that is synchronous API support, where a
-    driver calls a routine that allocates one or more URBs,
-    submits them, and waits until they complete.
-    There are synchronous wrappers for single-buffer control
-    and bulk transfers (which are awkward to use in some
-    driver disconnect scenarios), and for scatterlist based
-    streaming i/o (bulk or interrupt).
-    
-
-    USB drivers need to provide buffers that can be
-    used for DMA, although they don't necessarily need to
-    provide the DMA mapping themselves.
-    There are APIs to use used when allocating DMA buffers,
-    which can prevent use of bounce buffers on some systems.
-    In some cases, drivers may be able to rely on 64bit DMA
-    to eliminate another kind of bounce buffer.
-    
-
-!Edrivers/usb/core/urb.c
-!Edrivers/usb/core/message.c
-!Edrivers/usb/core/file.c
-!Edrivers/usb/core/driver.c
-!Edrivers/usb/core/usb.c
-!Edrivers/usb/core/hub.c
-    
-
-    Host Controller APIs
-
-    These APIs are only for use by host controller drivers,
-    most of which implement standard register interfaces such as
-    XHCI, EHCI, OHCI, or UHCI.
-    UHCI was one of the first interfaces, designed by Intel and
-    also used by VIA; it doesn't do much in hardware.
-    OHCI was designed later, to have the hardware do more work
-    (bigger transfers, tracking protocol state, and so on).
-    EHCI was designed with USB 2.0; its design has features that
-    resemble OHCI (hardware does much more work) as well as
-    UHCI (some parts of ISO support, TD list processing).
-    XHCI was designed with USB 3.0. It continues to shift support
-    for functionality into hardware.
-    
-
-    There are host controllers other than the "big three",
-    although most PCI based controllers (and a few non-PCI based
-    ones) use one of those interfaces.
-    Not all host controllers use DMA; some use PIO, and there
-    is also a simulator and a virtual host controller to pipe
-    USB over the network.
-    
-
-    The same basic APIs are available to drivers for all
-    those controllers.  
-    For historical reasons they are in two layers:
-    struct usb_bus is a rather thin
-    layer that became available in the 2.2 kernels, while
-    struct usb_hcd is a more featureful
-    layer that
-    lets HCDs share common code, to shrink driver size
-    and significantly reduce hcd-specific behaviors.
-    
-
-!Edrivers/usb/core/hcd.c
-!Edrivers/usb/core/hcd-pci.c
-!Idrivers/usb/core/buffer.c
-    
-
-    
-	The USB Filesystem (usbfs)
-
-	This chapter presents the Linux usbfs.
-	You may prefer to avoid writing new kernel code for your
-	USB driver; that's the problem that usbfs set out to solve.
-	User mode device drivers are usually packaged as applications
-	or libraries, and may use usbfs through some programming library
-	that wraps it.  Such libraries include
-	libusb
-	for C/C++, and
-	jUSB for Java.
-	
-
-	Unfinished
-	    This particular documentation is incomplete,
-	    especially with respect to the asynchronous mode.
-	    As of kernel 2.5.66 the code and this (new) documentation
-	    need to be cross-reviewed.
-	    
-	    
-
-	Configure usbfs into Linux kernels by enabling the
-	USB filesystem option (CONFIG_USB_DEVICEFS),
-	and you get basic support for user mode USB device drivers.
-	Until relatively recently it was often (confusingly) called
-	usbdevfs although it wasn't solving what
-	devfs was.
-	Every USB device will appear in usbfs, regardless of whether or
-	not it has a kernel driver.
-	
-
-	
-	    What files are in "usbfs"?
-
-	    Conventionally mounted at
-	    /proc/bus/usb, usbfs 
-	    features include:
-	    
-		/proc/bus/usb/devices
-		    ... a text file
-		    showing each of the USB devices on known to the kernel,
-		    and their configuration descriptors.
-		    You can also poll() this to learn about new devices.
-		    
-		/proc/bus/usb/BBB/DDD
-		    ... magic files
-		    exposing the each device's configuration descriptors, and
-		    supporting a series of ioctls for making device requests,
-		    including I/O to devices.  (Purely for access by programs.)
-		    
-	    
-	    
-
-	     Each bus is given a number (BBB) based on when it was
-	    enumerated; within each bus, each device is given a similar
-	    number (DDD).
-	    Those BBB/DDD paths are not "stable" identifiers;
-	    expect them to change even if you always leave the devices
-	    plugged in to the same hub port.
-	    Don't even think of saving these in application
-	    configuration files.
-	    Stable identifiers are available, for user mode applications
-	    that want to use them.  HID and networking devices expose
-	    these stable IDs, so that for example you can be sure that
-	    you told the right UPS to power down its second server.
-	    "usbfs" doesn't (yet) expose those IDs.
-	    
-
-	
-
-	
-	    Mounting and Access Control
-
-	    There are a number of mount options for usbfs, which will
-	    be of most interest to you if you need to override the default
-	    access control policy.
-	    That policy is that only root may read or write device files
-	    (/proc/bus/BBB/DDD) although anyone may read
-	    the devices
-	    or drivers files.
-	    I/O requests to the device also need the CAP_SYS_RAWIO capability,
-	    
-
-	    The significance of that is that by default, all user mode
-	    device drivers need super-user privileges.
-	    You can change modes or ownership in a driver setup
-	    when the device hotplugs, or maye just start the
-	    driver right then, as a privileged server (or some activity
-	    within one).
-	    That's the most secure approach for multi-user systems,
-	    but for single user systems ("trusted" by that user)
-	    it's more convenient just to grant everyone all access
-	    (using the devmode=0666 option)
-	    so the driver can start whenever it's needed.
-	    
-
-	    The mount options for usbfs, usable in /etc/fstab or
-	    in command line invocations of mount, are:
-
-	    
-		
-		    busgid=NNNNN
-		    Controls the GID used for the
-		    /proc/bus/usb/BBB
-		    directories.  (Default: 0)
-		busmode=MMM
-		    Controls the file mode used for the
-		    /proc/bus/usb/BBB
-		    directories.  (Default: 0555)
-		    
-		busuid=NNNNN
-		    Controls the UID used for the
-		    /proc/bus/usb/BBB
-		    directories.  (Default: 0)
-
-		devgid=NNNNN
-		    Controls the GID used for the
-		    /proc/bus/usb/BBB/DDD
-		    files.  (Default: 0)
-		devmode=MMM
-		    Controls the file mode used for the
-		    /proc/bus/usb/BBB/DDD
-		    files.  (Default: 0644)
-		devuid=NNNNN
-		    Controls the UID used for the
-		    /proc/bus/usb/BBB/DDD
-		    files.  (Default: 0)
-
-		listgid=NNNNN
-		    Controls the GID used for the
-		    /proc/bus/usb/devices and drivers files.
-		    (Default: 0)
-		listmode=MMM
-		    Controls the file mode used for the
-		    /proc/bus/usb/devices and drivers files.
-		    (Default: 0444)
-		listuid=NNNNN
-		    Controls the UID used for the
-		    /proc/bus/usb/devices and drivers files.
-		    (Default: 0)
-	    
-
-	    
-
-	    Note that many Linux distributions hard-wire the mount options
-	    for usbfs in their init scripts, such as
-	    /etc/rc.d/rc.sysinit,
-	    rather than making it easy to set this per-system
-	    policy in /etc/fstab.
-	    
-
-	
-
-	
-	    /proc/bus/usb/devices
-
-	    This file is handy for status viewing tools in user
-	    mode, which can scan the text format and ignore most of it.
-	    More detailed device status (including class and vendor
-	    status) is available from device-specific files.
-	    For information about the current format of this file,
-	    see the
-	    Documentation/usb/proc_usb_info.txt
-	    file in your Linux kernel sources.
-	    
-
-	    This file, in combination with the poll() system call, can
-	    also be used to detect when devices are added or removed:
-int fd;
-struct pollfd pfd;
-
-fd = open("/proc/bus/usb/devices", O_RDONLY);
-pfd = { fd, POLLIN, 0 };
-for (;;) {
-	/* The first time through, this call will return immediately. */
-	poll(&pfd, 1, -1);
-
-	/* To see what's changed, compare the file's previous and current
-	   contents or scan the filesystem.  (Scanning is more precise.) */
-}
-	    Note that this behavior is intended to be used for informational
-	    and debug purposes.  It would be more appropriate to use programs
-	    such as udev or HAL to initialize a device or start a user-mode
-	    helper program, for instance.
-	    
-	
-
-	
-	    /proc/bus/usb/BBB/DDD
-
-	    Use these files in one of these basic ways:
-	    
-
-	    They can be read,
-	    producing first the device descriptor
-	    (18 bytes) and then the descriptors for the current configuration.
-	    See the USB 2.0 spec for details about those binary data formats.
-	    You'll need to convert most multibyte values from little endian
-	    format to your native host byte order, although a few of the
-	    fields in the device descriptor (both of the BCD-encoded fields,
-	    and the vendor and product IDs) will be byteswapped for you.
-	    Note that configuration descriptors include descriptors for
-	    interfaces, altsettings, endpoints, and maybe additional
-	    class descriptors.
-	    
-
-	    Perform USB operations using 
-	    ioctl() requests to make endpoint I/O
-	    requests (synchronously or asynchronously) or manage
-	    the device.
-	    These requests need the CAP_SYS_RAWIO capability,
-	    as well as filesystem access permissions.
-	    Only one ioctl request can be made on one of these
-	    device files at a time.
-	    This means that if you are synchronously reading an endpoint
-	    from one thread, you won't be able to write to a different
-	    endpoint from another thread until the read completes.
-	    This works for half duplex protocols,
-	    but otherwise you'd use asynchronous i/o requests. 
-	    
-
-	    
-
-
-	
-	    Life Cycle of User Mode Drivers
-
-	    Such a driver first needs to find a device file
-	    for a device it knows how to handle.
-	    Maybe it was told about it because a
-	    /sbin/hotplug event handling agent
-	    chose that driver to handle the new device.
-	    Or maybe it's an application that scans all the
-	    /proc/bus/usb device files, and ignores most devices.
-	    In either case, it should read() all
-	    the descriptors from the device file,
-	    and check them against what it knows how to handle.
-	    It might just reject everything except a particular
-	    vendor and product ID, or need a more complex policy.
-	    
-
-	    Never assume there will only be one such device
-	    on the system at a time!
-	    If your code can't handle more than one device at
-	    a time, at least detect when there's more than one, and
-	    have your users choose which device to use.
-	    
-
-	    Once your user mode driver knows what device to use,
-	    it interacts with it in either of two styles.
-	    The simple style is to make only control requests; some
-	    devices don't need more complex interactions than those.
-	    (An example might be software using vendor-specific control
-	    requests for some initialization or configuration tasks,
-	    with a kernel driver for the rest.)
-	    
-
-	    More likely, you need a more complex style driver:
-	    one using non-control endpoints, reading or writing data
-	    and claiming exclusive use of an interface.
-	    Bulk transfers are easiest to use,
-	    but only their sibling interrupt transfers 
-	    work with low speed devices.
-	    Both interrupt and isochronous transfers
-	    offer service guarantees because their bandwidth is reserved.
-	    Such "periodic" transfers are awkward to use through usbfs,
-	    unless you're using the asynchronous calls.  However, interrupt
-	    transfers can also be used in a synchronous "one shot" style.
-	    
-
-	    Your user-mode driver should never need to worry
-	    about cleaning up request state when the device is
-	    disconnected, although it should close its open file
-	    descriptors as soon as it starts seeing the ENODEV
-	    errors.
-	    
-
-	    
-
-	The ioctl() Requests
-
-	    To use these ioctls, you need to include the following
-	    headers in your userspace program:
-#include <linux/usb.h>
-#include <linux/usbdevice_fs.h>
-#include <asm/byteorder.h>
-	    The standard USB device model requests, from "Chapter 9" of
-	    the USB 2.0 specification, are automatically included from
-	    the <linux/usb/ch9.h> header.
-	    
-
-	    Unless noted otherwise, the ioctl requests
-	    described here will
-	    update the modification time on the usbfs file to which
-	    they are applied (unless they fail).
-	    A return of zero indicates success; otherwise, a
-	    standard USB error code is returned.  (These are
-	    documented in
-	    Documentation/usb/error-codes.txt
-	    in your kernel sources.)
-	    
-
-	    Each of these files multiplexes access to several
-	    I/O streams, one per endpoint.
-	    Each device has one control endpoint (endpoint zero)
-	    which supports a limited RPC style RPC access.
-	    Devices are configured
-	    by hub_wq (in the kernel) setting a device-wide
-	    configuration that affects things
-	    like power consumption and basic functionality.
-	    The endpoints are part of USB interfaces,
-	    which may have altsettings
-	    affecting things like which endpoints are available.
-	    Many devices only have a single configuration and interface,
-	    so drivers for them will ignore configurations and altsettings.
-	    
-
-
-	    
-		Management/Status Requests
-
-		A number of usbfs requests don't deal very directly
-		with device I/O.
-		They mostly relate to device management and status.
-		These are all synchronous requests.
-		
-
-		
-
-		USBDEVFS_CLAIMINTERFACE
-		    This is used to force usbfs to
-		    claim a specific interface,
-		    which has not previously been claimed by usbfs or any other
-		    kernel driver.
-		    The ioctl parameter is an integer holding the number of
-		    the interface (bInterfaceNumber from descriptor).
-		    
-		    Note that if your driver doesn't claim an interface
-		    before trying to use one of its endpoints, and no
-		    other driver has bound to it, then the interface is
-		    automatically claimed by usbfs.
-		    
-		    This claim will be released by a RELEASEINTERFACE ioctl,
-		    or by closing the file descriptor.
-		    File modification time is not updated by this request.
-		    
-
-		USBDEVFS_CONNECTINFO
-		    Says whether the device is lowspeed.
-		    The ioctl parameter points to a structure like this:
-struct usbdevfs_connectinfo {
-        unsigned int   devnum;
-        unsigned char  slow;
-}; 
-		    File modification time is not updated by this request.
-		    
-		    You can't tell whether a "not slow"
-		    device is connected at high speed (480 MBit/sec)
-		    or just full speed (12 MBit/sec).
-		    You should know the devnum value already,
-		    it's the DDD value of the device file name.
-		    
-
-		USBDEVFS_GETDRIVER
-		    Returns the name of the kernel driver
-		    bound to a given interface (a string).  Parameter
-		    is a pointer to this structure, which is modified:
-struct usbdevfs_getdriver {
-        unsigned int  interface;
-        char          driver[USBDEVFS_MAXDRIVERNAME + 1];
-};
-		    File modification time is not updated by this request.
-		    
-
-		USBDEVFS_IOCTL
-		    Passes a request from userspace through
-		    to a kernel driver that has an ioctl entry in the
-		    struct usb_driver it registered.
-struct usbdevfs_ioctl {
-        int     ifno;
-        int     ioctl_code;
-        void    *data;
-};
-
-/* user mode call looks like this.
- * 'request' becomes the driver->ioctl() 'code' parameter.
- * the size of 'param' is encoded in 'request', and that data
- * is copied to or from the driver->ioctl() 'buf' parameter.
- */
-static int
-usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
-{
-        struct usbdevfs_ioctl	wrapper;
-
-        wrapper.ifno = ifno;
-        wrapper.ioctl_code = request;
-        wrapper.data = param;
-
-        return ioctl (fd, USBDEVFS_IOCTL, &wrapper);
-} 
-		    File modification time is not updated by this request.
-		    
-		    This request lets kernel drivers talk to user mode code
-		    through filesystem operations even when they don't create
-		    a character or block special device.
-		    It's also been used to do things like ask devices what
-		    device special file should be used.
-		    Two pre-defined ioctls are used
-		    to disconnect and reconnect kernel drivers, so
-		    that user mode code can completely manage binding
-		    and configuration of devices.
-		    
-
-		USBDEVFS_RELEASEINTERFACE
-		    This is used to release the claim usbfs
-		    made on interface, either implicitly or because of a
-		    USBDEVFS_CLAIMINTERFACE call, before the file
-		    descriptor is closed.
-		    The ioctl parameter is an integer holding the number of
-		    the interface (bInterfaceNumber from descriptor);
-		    File modification time is not updated by this request.
-		    
-		    No security check is made to ensure
-		    that the task which made the claim is the one
-		    which is releasing it.
-		    This means that user mode driver may interfere
-		    other ones.  
-		    
-
-		USBDEVFS_RESETEP
-		    Resets the data toggle value for an endpoint
-		    (bulk or interrupt) to DATA0.
-		    The ioctl parameter is an integer endpoint number
-		    (1 to 15, as identified in the endpoint descriptor),
-		    with USB_DIR_IN added if the device's endpoint sends
-		    data to the host.
-		    
-		    Avoid using this request.
-		    It should probably be removed.
-		    Using it typically means the device and driver will lose
-		    toggle synchronization.  If you really lost synchronization,
-		    you likely need to completely handshake with the device,
-		    using a request like CLEAR_HALT
-		    or SET_INTERFACE.
-		    
-
-		USBDEVFS_DROP_PRIVILEGES
-		    This is used to relinquish the ability
-		    to do certain operations which are considered to be
-		    privileged on a usbfs file descriptor.
-		    This includes claiming arbitrary interfaces, resetting
-		    a device on which there are currently claimed interfaces
-		    from other users, and issuing USBDEVFS_IOCTL calls.
-		    The ioctl parameter is a 32 bit mask of interfaces
-		    the user is allowed to claim on this file descriptor.
-		    You may issue this ioctl more than one time to narrow
-		    said mask.
-		    
-		
-
-		
-
-	    
-		Synchronous I/O Support
-
-		Synchronous requests involve the kernel blocking
-		until the user mode request completes, either by
-		finishing successfully or by reporting an error.
-		In most cases this is the simplest way to use usbfs,
-		although as noted above it does prevent performing I/O
-		to more than one endpoint at a time.
-		
-
-		
-
-		USBDEVFS_BULK
-		    Issues a bulk read or write request to the
-		    device.
-		    The ioctl parameter is a pointer to this structure:
-struct usbdevfs_bulktransfer {
-        unsigned int  ep;
-        unsigned int  len;
-        unsigned int  timeout; /* in milliseconds */
-        void          *data;
-};
-		    The "ep" value identifies a
-		    bulk endpoint number (1 to 15, as identified in an endpoint
-		    descriptor),
-		    masked with USB_DIR_IN when referring to an endpoint which
-		    sends data to the host from the device.
-		    The length of the data buffer is identified by "len";
-		    Recent kernels support requests up to about 128KBytes.
-		    FIXME say how read length is returned,
-		    and how short reads are handled..
-		    
-
-		USBDEVFS_CLEAR_HALT
-		    Clears endpoint halt (stall) and
-		    resets the endpoint toggle.  This is only
-		    meaningful for bulk or interrupt endpoints.
-		    The ioctl parameter is an integer endpoint number
-		    (1 to 15, as identified in an endpoint descriptor),
-		    masked with USB_DIR_IN when referring to an endpoint which
-		    sends data to the host from the device.
-		    
-		    Use this on bulk or interrupt endpoints which have
-		    stalled, returning -EPIPE status
-		    to a data transfer request.
-		    Do not issue the control request directly, since
-		    that could invalidate the host's record of the
-		    data toggle.
-		    
-
-		USBDEVFS_CONTROL
-		    Issues a control request to the device.
-		    The ioctl parameter points to a structure like this:
-struct usbdevfs_ctrltransfer {
-        __u8   bRequestType;
-        __u8   bRequest;
-        __u16  wValue;
-        __u16  wIndex;
-        __u16  wLength;
-        __u32  timeout;  /* in milliseconds */
-        void   *data;
-};
-		    
-		    The first eight bytes of this structure are the contents
-		    of the SETUP packet to be sent to the device; see the
-		    USB 2.0 specification for details.
-		    The bRequestType value is composed by combining a
-		    USB_TYPE_* value, a USB_DIR_* value, and a
-		    USB_RECIP_* value (from
-		    <linux/usb.h>).
-		    If wLength is nonzero, it describes the length of the data
-		    buffer, which is either written to the device
-		    (USB_DIR_OUT) or read from the device (USB_DIR_IN).
-		    
-		    At this writing, you can't transfer more than 4 KBytes
-		    of data to or from a device; usbfs has a limit, and
-		    some host controller drivers have a limit.
-		    (That's not usually a problem.)
-		    Also there's no way to say it's
-		    not OK to get a short read back from the device.
-		    
-
-		USBDEVFS_RESET
-		    Does a USB level device reset.
-		    The ioctl parameter is ignored.
-		    After the reset, this rebinds all device interfaces.
-		    File modification time is not updated by this request.
-		    
-		    Avoid using this call
-		    until some usbcore bugs get fixed,
-		    since it does not fully synchronize device, interface,
-		    and driver (not just usbfs) state.
-		    
-	    
-		USBDEVFS_SETINTERFACE
-		    Sets the alternate setting for an
-		    interface.  The ioctl parameter is a pointer to a
-		    structure like this:
-struct usbdevfs_setinterface {
-        unsigned int  interface;
-        unsigned int  altsetting;
-}; 
-		    File modification time is not updated by this request.
-		    
-		    Those struct members are from some interface descriptor
-		    applying to the current configuration.
-		    The interface number is the bInterfaceNumber value, and
-		    the altsetting number is the bAlternateSetting value.
-		    (This resets each endpoint in the interface.)
-		    
-
-		USBDEVFS_SETCONFIGURATION
-		    Issues the
-		    usb_set_configuration call
-		    for the device.
-		    The parameter is an integer holding the number of
-		    a configuration (bConfigurationValue from descriptor).
-		    File modification time is not updated by this request.
-		    
-		    Avoid using this call
-		    until some usbcore bugs get fixed,
-		    since it does not fully synchronize device, interface,
-		    and driver (not just usbfs) state.
-		    
-
-		
-	    
-
-	    
-		Asynchronous I/O Support
-
-		As mentioned above, there are situations where it may be
-		important to initiate concurrent operations from user mode code.
-		This is particularly important for periodic transfers
-		(interrupt and isochronous), but it can be used for other
-		kinds of USB requests too.
-		In such cases, the asynchronous requests described here
-		are essential.  Rather than submitting one request and having
-		the kernel block until it completes, the blocking is separate.
-		
-
-		These requests are packaged into a structure that
-		resembles the URB used by kernel device drivers.
-		(No POSIX Async I/O support here, sorry.)
-		It identifies the endpoint type (USBDEVFS_URB_TYPE_*),
-		endpoint (number, masked with USB_DIR_IN as appropriate),
-		buffer and length, and a user "context" value serving to
-		uniquely identify each request.
-		(It's usually a pointer to per-request data.)
-		Flags can modify requests (not as many as supported for
-		kernel drivers).
-		
-
-		Each request can specify a realtime signal number
-		(between SIGRTMIN and SIGRTMAX, inclusive) to request a
-		signal be sent when the request completes.
-		
-
-		When usbfs returns these urbs, the status value
-		is updated, and the buffer may have been modified.
-		Except for isochronous transfers, the actual_length is
-		updated to say how many bytes were transferred; if the
-		USBDEVFS_URB_DISABLE_SPD flag is set
-		("short packets are not OK"), if fewer bytes were read
-		than were requested then you get an error report.
-		
-
-struct usbdevfs_iso_packet_desc {
-        unsigned int                     length;
-        unsigned int                     actual_length;
-        unsigned int                     status;
-};
-
-struct usbdevfs_urb {
-        unsigned char                    type;
-        unsigned char                    endpoint;
-        int                              status;
-        unsigned int                     flags;
-        void                             *buffer;
-        int                              buffer_length;
-        int                              actual_length;
-        int                              start_frame;
-        int                              number_of_packets;
-        int                              error_count;
-        unsigned int                     signr;
-        void                             *usercontext;
-        struct usbdevfs_iso_packet_desc  iso_frame_desc[];
-};
-
-		 For these asynchronous requests, the file modification
-		time reflects when the request was initiated.
-		This contrasts with their use with the synchronous requests,
-		where it reflects when requests complete.
-		
-
-		
-
-		USBDEVFS_DISCARDURB
-		    
-		    TBS
-		    File modification time is not updated by this request.
-		    
-		    
-
-		USBDEVFS_DISCSIGNAL
-		    
-		    TBS
-		    File modification time is not updated by this request.
-		    
-		    
-
-		USBDEVFS_REAPURB
-		    
-		    TBS
-		    File modification time is not updated by this request.
-		    
-		    
-
-		USBDEVFS_REAPURBNDELAY
-		    
-		    TBS
-		    File modification time is not updated by this request.
-		    
-		    
-
-		USBDEVFS_SUBMITURB
-		    
-		    TBS
-		    
-		    
-
-		
-	    
-
-	
-
-    
-
-
-
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index e18135b513e2..743828ead665 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -20,6 +20,7 @@ available subsections can be seen below.
    sound
    frame-buffer
    input
+   usb
    spi
    i2c
    hsi
diff --git a/Documentation/driver-api/usb.rst b/Documentation/driver-api/usb.rst
new file mode 100644
index 000000000000..851cc40b66b5
--- /dev/null
+++ b/Documentation/driver-api/usb.rst
@@ -0,0 +1,748 @@
+===========================
+The Linux-USB Host Side API
+===========================
+
+Introduction to USB on Linux
+============================
+
+A Universal Serial Bus (USB) is used to connect a host, such as a PC or
+workstation, to a number of peripheral devices. USB uses a tree
+structure, with the host as the root (the system's master), hubs as
+interior nodes, and peripherals as leaves (and slaves). Modern PCs
+support several such trees of USB devices, usually
+a few USB 3.0 (5 GBit/s) or USB 3.1 (10 GBit/s) and some legacy
+USB 2.0 (480 MBit/s) busses just in case.
+
+That master/slave asymmetry was designed-in for a number of reasons, one
+being ease of use. It is not physically possible to mistake upstream and
+downstream or it does not matter with a type C plug (or they are built into the
+peripheral). Also, the host software doesn't need to deal with
+distributed auto-configuration since the pre-designated master node
+manages all that.
+
+Kernel developers added USB support to Linux early in the 2.2 kernel
+series and have been developing it further since then. Besides support
+for each new generation of USB, various host controllers gained support,
+new drivers for peripherals have been added and advanced features for latency
+measurement and improved power management introduced.
+
+Linux can run inside USB devices as well as on the hosts that control
+the devices. But USB device drivers running inside those peripherals
+don't do the same things as the ones running inside hosts, so they've
+been given a different name: *gadget drivers*. This document does not
+cover gadget drivers.
+
+USB Host-Side API Model
+=======================
+
+Host-side drivers for USB devices talk to the "usbcore" APIs. There are
+two. One is intended for *general-purpose* drivers (exposed through
+driver frameworks), and the other is for drivers that are *part of the
+core*. Such core drivers include the *hub* driver (which manages trees
+of USB devices) and several different kinds of *host controller
+drivers*, which control individual busses.
+
+The device model seen by USB drivers is relatively complex.
+
+-  USB supports four kinds of data transfers (control, bulk, interrupt,
+   and isochronous). Two of them (control and bulk) use bandwidth as
+   it's available, while the other two (interrupt and isochronous) are
+   scheduled to provide guaranteed bandwidth.
+
+-  The device description model includes one or more "configurations"
+   per device, only one of which is active at a time. Devices are supposed
+   to be capable of operating at lower than their top
+   speeds and may provide a BOS descriptor showing the lowest speed they
+   remain fully operational at.
+
+-  From USB 3.0 on configurations have one or more "functions", which
+   provide a common functionality and are grouped together for purposes
+   of power management.
+
+-  Configurations or functions have one or more "interfaces", each of which may have
+   "alternate settings". Interfaces may be standardized by USB "Class"
+   specifications, or may be specific to a vendor or device.
+
+   USB device drivers actually bind to interfaces, not devices. Think of
+   them as "interface drivers", though you may not see many devices
+   where the distinction is important. *Most USB devices are simple,
+   with only one function, one configuration, one interface, and one alternate
+   setting.*
+
+-  Interfaces have one or more "endpoints", each of which supports one
+   type and direction of data transfer such as "bulk out" or "interrupt
+   in". The entire configuration may have up to sixteen endpoints in
+   each direction, allocated as needed among all the interfaces.
+
+-  Data transfer on USB is packetized; each endpoint has a maximum
+   packet size. Drivers must often be aware of conventions such as
+   flagging the end of bulk transfers using "short" (including zero
+   length) packets.
+
+-  The Linux USB API supports synchronous calls for control and bulk
+   messages. It also supports asynchronous calls for all kinds of data
+   transfer, using request structures called "URBs" (USB Request
+   Blocks).
+
+Accordingly, the USB Core API exposed to device drivers covers quite a
+lot of territory. You'll probably need to consult the USB 3.0
+specification, available online from www.usb.org at no cost, as well as
+class or device specifications.
+
+The only host-side drivers that actually touch hardware (reading/writing
+registers, handling IRQs, and so on) are the HCDs. In theory, all HCDs
+provide the same functionality through the same API. In practice, that's
+becoming more true, but there are still differences
+that crop up especially with fault handling on the less common controllers.
+Different controllers don't
+necessarily report the same aspects of failures, and recovery from
+faults (including software-induced ones like unlinking an URB) isn't yet
+fully consistent. Device driver authors should make a point of doing
+disconnect testing (while the device is active) with each different host
+controller driver, to make sure drivers don't have bugs of their own as
+well as to make sure they aren't relying on some HCD-specific behavior.
+
+USB-Standard Types
+==================
+
+In ```` you will find the USB data types defined in
+chapter 9 of the USB specification. These data types are used throughout
+USB, and in APIs including this host side API, gadget APIs, and usbfs.
+
+.. kernel-doc:: include/linux/usb/ch9.h
+   :internal:
+
+Host-Side Data Types and Macros
+===============================
+
+The host side API exposes several layers to drivers, some of which are
+more necessary than others. These support lifecycle models for host side
+drivers and devices, and support passing buffers through usbcore to some
+HCD that performs the I/O for the device driver.
+
+.. kernel-doc:: include/linux/usb.h
+   :internal:
+
+USB Core APIs
+=============
+
+There are two basic I/O models in the USB API. The most elemental one is
+asynchronous: drivers submit requests in the form of an URB, and the
+URB's completion callback handles the next step. All USB transfer types
+support that model, although there are special cases for control URBs
+(which always have setup and status stages, but may not have a data
+stage) and isochronous URBs (which allow large packets and include
+per-packet fault reports). Built on top of that is synchronous API
+support, where a driver calls a routine that allocates one or more URBs,
+submits them, and waits until they complete. There are synchronous
+wrappers for single-buffer control and bulk transfers (which are awkward
+to use in some driver disconnect scenarios), and for scatterlist based
+streaming i/o (bulk or interrupt).
+
+USB drivers need to provide buffers that can be used for DMA, although
+they don't necessarily need to provide the DMA mapping themselves. There
+are APIs to use used when allocating DMA buffers, which can prevent use
+of bounce buffers on some systems. In some cases, drivers may be able to
+rely on 64bit DMA to eliminate another kind of bounce buffer.
+
+.. kernel-doc:: drivers/usb/core/urb.c
+   :export:
+
+.. kernel-doc:: drivers/usb/core/message.c
+   :export:
+
+.. kernel-doc:: drivers/usb/core/file.c
+   :export:
+
+.. kernel-doc:: drivers/usb/core/driver.c
+   :export:
+
+.. kernel-doc:: drivers/usb/core/usb.c
+   :export:
+
+.. kernel-doc:: drivers/usb/core/hub.c
+   :export:
+
+Host Controller APIs
+====================
+
+These APIs are only for use by host controller drivers, most of which
+implement standard register interfaces such as XHCI, EHCI, OHCI, or UHCI. UHCI
+was one of the first interfaces, designed by Intel and also used by VIA;
+it doesn't do much in hardware. OHCI was designed later, to have the
+hardware do more work (bigger transfers, tracking protocol state, and so
+on). EHCI was designed with USB 2.0; its design has features that
+resemble OHCI (hardware does much more work) as well as UHCI (some parts
+of ISO support, TD list processing). XHCI was designed with USB 3.0. It
+continues to shift support for functionality into hardware.
+
+There are host controllers other than the "big three", although most PCI
+based controllers (and a few non-PCI based ones) use one of those
+interfaces. Not all host controllers use DMA; some use PIO, and there is
+also a simulator and a virtual host controller to pipe USB over the network.
+
+The same basic APIs are available to drivers for all those controllers.
+For historical reasons they are in two layers: :c:type:`struct
+usb_bus ` is a rather thin layer that became available
+in the 2.2 kernels, while :c:type:`struct usb_hcd `
+is a more featureful layer
+that lets HCDs share common code, to shrink driver size and
+significantly reduce hcd-specific behaviors.
+
+.. kernel-doc:: drivers/usb/core/hcd.c
+   :export:
+
+.. kernel-doc:: drivers/usb/core/hcd-pci.c
+   :export:
+
+.. kernel-doc:: drivers/usb/core/buffer.c
+   :internal:
+
+The USB Filesystem (usbfs)
+==========================
+
+This chapter presents the Linux *usbfs*. You may prefer to avoid writing
+new kernel code for your USB driver; that's the problem that usbfs set
+out to solve. User mode device drivers are usually packaged as
+applications or libraries, and may use usbfs through some programming
+library that wraps it. Such libraries include
+`libusb `__ for C/C++, and
+`jUSB `__ for Java.
+
+    **Note**
+
+    This particular documentation is incomplete, especially with respect
+    to the asynchronous mode. As of kernel 2.5.66 the code and this
+    (new) documentation need to be cross-reviewed.
+
+Configure usbfs into Linux kernels by enabling the *USB filesystem*
+option (CONFIG_USB_DEVICEFS), and you get basic support for user mode
+USB device drivers. Until relatively recently it was often (confusingly)
+called *usbdevfs* although it wasn't solving what *devfs* was. Every USB
+device will appear in usbfs, regardless of whether or not it has a
+kernel driver.
+
+What files are in "usbfs"?
+--------------------------
+
+Conventionally mounted at ``/proc/bus/usb``, usbfs features include:
+
+-  ``/proc/bus/usb/devices`` ... a text file showing each of the USB
+   devices on known to the kernel, and their configuration descriptors.
+   You can also poll() this to learn about new devices.
+
+-  ``/proc/bus/usb/BBB/DDD`` ... magic files exposing the each device's
+   configuration descriptors, and supporting a series of ioctls for
+   making device requests, including I/O to devices. (Purely for access
+   by programs.)
+
+Each bus is given a number (BBB) based on when it was enumerated; within
+each bus, each device is given a similar number (DDD). Those BBB/DDD
+paths are not "stable" identifiers; expect them to change even if you
+always leave the devices plugged in to the same hub port. *Don't even
+think of saving these in application configuration files.* Stable
+identifiers are available, for user mode applications that want to use
+them. HID and networking devices expose these stable IDs, so that for
+example you can be sure that you told the right UPS to power down its
+second server. "usbfs" doesn't (yet) expose those IDs.
+
+Mounting and Access Control
+---------------------------
+
+There are a number of mount options for usbfs, which will be of most
+interest to you if you need to override the default access control
+policy. That policy is that only root may read or write device files
+(``/proc/bus/BBB/DDD``) although anyone may read the ``devices`` or
+``drivers`` files. I/O requests to the device also need the
+CAP_SYS_RAWIO capability,
+
+The significance of that is that by default, all user mode device
+drivers need super-user privileges. You can change modes or ownership in
+a driver setup when the device hotplugs, or maye just start the driver
+right then, as a privileged server (or some activity within one). That's
+the most secure approach for multi-user systems, but for single user
+systems ("trusted" by that user) it's more convenient just to grant
+everyone all access (using the *devmode=0666* option) so the driver can
+start whenever it's needed.
+
+The mount options for usbfs, usable in /etc/fstab or in command line
+invocations of *mount*, are:
+
+*busgid*\ =NNNNN
+    Controls the GID used for the /proc/bus/usb/BBB directories.
+    (Default: 0)
+
+*busmode*\ =MMM
+    Controls the file mode used for the /proc/bus/usb/BBB directories.
+    (Default: 0555)
+
+*busuid*\ =NNNNN
+    Controls the UID used for the /proc/bus/usb/BBB directories.
+    (Default: 0)
+
+*devgid*\ =NNNNN
+    Controls the GID used for the /proc/bus/usb/BBB/DDD files. (Default:
+    0)
+
+*devmode*\ =MMM
+    Controls the file mode used for the /proc/bus/usb/BBB/DDD files.
+    (Default: 0644)
+
+*devuid*\ =NNNNN
+    Controls the UID used for the /proc/bus/usb/BBB/DDD files. (Default:
+    0)
+
+*listgid*\ =NNNNN
+    Controls the GID used for the /proc/bus/usb/devices and drivers
+    files. (Default: 0)
+
+*listmode*\ =MMM
+    Controls the file mode used for the /proc/bus/usb/devices and
+    drivers files. (Default: 0444)
+
+*listuid*\ =NNNNN
+    Controls the UID used for the /proc/bus/usb/devices and drivers
+    files. (Default: 0)
+
+Note that many Linux distributions hard-wire the mount options for usbfs
+in their init scripts, such as ``/etc/rc.d/rc.sysinit``, rather than
+making it easy to set this per-system policy in ``/etc/fstab``.
+
+/proc/bus/usb/devices
+---------------------
+
+This file is handy for status viewing tools in user mode, which can scan
+the text format and ignore most of it. More detailed device status
+(including class and vendor status) is available from device-specific
+files. For information about the current format of this file, see the
+``Documentation/usb/proc_usb_info.txt`` file in your Linux kernel
+sources.
+
+This file, in combination with the poll() system call, can also be used
+to detect when devices are added or removed:
+
+::
+
+    int fd;
+    struct pollfd pfd;
+
+    fd = open("/proc/bus/usb/devices", O_RDONLY);
+    pfd = { fd, POLLIN, 0 };
+    for (;;) {
+        /* The first time through, this call will return immediately. */
+        poll(&pfd, 1, -1);
+
+        /* To see what's changed, compare the file's previous and current
+           contents or scan the filesystem.  (Scanning is more precise.) */
+    }
+
+Note that this behavior is intended to be used for informational and
+debug purposes. It would be more appropriate to use programs such as
+udev or HAL to initialize a device or start a user-mode helper program,
+for instance.
+
+/proc/bus/usb/BBB/DDD
+---------------------
+
+Use these files in one of these basic ways:
+
+*They can be read,* producing first the device descriptor (18 bytes) and
+then the descriptors for the current configuration. See the USB 2.0 spec
+for details about those binary data formats. You'll need to convert most
+multibyte values from little endian format to your native host byte
+order, although a few of the fields in the device descriptor (both of
+the BCD-encoded fields, and the vendor and product IDs) will be
+byteswapped for you. Note that configuration descriptors include
+descriptors for interfaces, altsettings, endpoints, and maybe additional
+class descriptors.
+
+*Perform USB operations* using *ioctl()* requests to make endpoint I/O
+requests (synchronously or asynchronously) or manage the device. These
+requests need the CAP_SYS_RAWIO capability, as well as filesystem
+access permissions. Only one ioctl request can be made on one of these
+device files at a time. This means that if you are synchronously reading
+an endpoint from one thread, you won't be able to write to a different
+endpoint from another thread until the read completes. This works for
+*half duplex* protocols, but otherwise you'd use asynchronous i/o
+requests.
+
+Life Cycle of User Mode Drivers
+-------------------------------
+
+Such a driver first needs to find a device file for a device it knows
+how to handle. Maybe it was told about it because a ``/sbin/hotplug``
+event handling agent chose that driver to handle the new device. Or
+maybe it's an application that scans all the /proc/bus/usb device files,
+and ignores most devices. In either case, it should :c:func:`read()`
+all the descriptors from the device file, and check them against what it
+knows how to handle. It might just reject everything except a particular
+vendor and product ID, or need a more complex policy.
+
+Never assume there will only be one such device on the system at a time!
+If your code can't handle more than one device at a time, at least
+detect when there's more than one, and have your users choose which
+device to use.
+
+Once your user mode driver knows what device to use, it interacts with
+it in either of two styles. The simple style is to make only control
+requests; some devices don't need more complex interactions than those.
+(An example might be software using vendor-specific control requests for
+some initialization or configuration tasks, with a kernel driver for the
+rest.)
+
+More likely, you need a more complex style driver: one using non-control
+endpoints, reading or writing data and claiming exclusive use of an
+interface. *Bulk* transfers are easiest to use, but only their sibling
+*interrupt* transfers work with low speed devices. Both interrupt and
+*isochronous* transfers offer service guarantees because their bandwidth
+is reserved. Such "periodic" transfers are awkward to use through usbfs,
+unless you're using the asynchronous calls. However, interrupt transfers
+can also be used in a synchronous "one shot" style.
+
+Your user-mode driver should never need to worry about cleaning up
+request state when the device is disconnected, although it should close
+its open file descriptors as soon as it starts seeing the ENODEV errors.
+
+The ioctl() Requests
+--------------------
+
+To use these ioctls, you need to include the following headers in your
+userspace program:
+
+::
+
+    #include 
+    #include 
+    #include 
+
+The standard USB device model requests, from "Chapter 9" of the USB 2.0
+specification, are automatically included from the ````
+header.
+
+Unless noted otherwise, the ioctl requests described here will update
+the modification time on the usbfs file to which they are applied
+(unless they fail). A return of zero indicates success; otherwise, a
+standard USB error code is returned. (These are documented in
+``Documentation/usb/error-codes.txt`` in your kernel sources.)
+
+Each of these files multiplexes access to several I/O streams, one per
+endpoint. Each device has one control endpoint (endpoint zero) which
+supports a limited RPC style RPC access. Devices are configured by
+hub_wq (in the kernel) setting a device-wide *configuration* that
+affects things like power consumption and basic functionality. The
+endpoints are part of USB *interfaces*, which may have *altsettings*
+affecting things like which endpoints are available. Many devices only
+have a single configuration and interface, so drivers for them will
+ignore configurations and altsettings.
+
+Management/Status Requests
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A number of usbfs requests don't deal very directly with device I/O.
+They mostly relate to device management and status. These are all
+synchronous requests.
+
+USBDEVFS_CLAIMINTERFACE
+    This is used to force usbfs to claim a specific interface, which has
+    not previously been claimed by usbfs or any other kernel driver. The
+    ioctl parameter is an integer holding the number of the interface
+    (bInterfaceNumber from descriptor).
+
+    Note that if your driver doesn't claim an interface before trying to
+    use one of its endpoints, and no other driver has bound to it, then
+    the interface is automatically claimed by usbfs.
+
+    This claim will be released by a RELEASEINTERFACE ioctl, or by
+    closing the file descriptor. File modification time is not updated
+    by this request.
+
+USBDEVFS_CONNECTINFO
+    Says whether the device is lowspeed. The ioctl parameter points to a
+    structure like this:
+
+    ::
+
+        struct usbdevfs_connectinfo {
+                unsigned int   devnum;
+                unsigned char  slow;
+        };
+
+    File modification time is not updated by this request.
+
+    *You can't tell whether a "not slow" device is connected at high
+    speed (480 MBit/sec) or just full speed (12 MBit/sec).* You should
+    know the devnum value already, it's the DDD value of the device file
+    name.
+
+USBDEVFS_GETDRIVER
+    Returns the name of the kernel driver bound to a given interface (a
+    string). Parameter is a pointer to this structure, which is
+    modified:
+
+    ::
+
+        struct usbdevfs_getdriver {
+                unsigned int  interface;
+                char          driver[USBDEVFS_MAXDRIVERNAME + 1];
+        };
+
+    File modification time is not updated by this request.
+
+USBDEVFS_IOCTL
+    Passes a request from userspace through to a kernel driver that has
+    an ioctl entry in the *struct usb_driver* it registered.
+
+    ::
+
+        struct usbdevfs_ioctl {
+                int     ifno;
+                int     ioctl_code;
+                void    *data;
+        };
+
+        /* user mode call looks like this.
+         * 'request' becomes the driver->ioctl() 'code' parameter.
+         * the size of 'param' is encoded in 'request', and that data
+         * is copied to or from the driver->ioctl() 'buf' parameter.
+         */
+        static int
+        usbdev_ioctl (int fd, int ifno, unsigned request, void *param)
+        {
+                struct usbdevfs_ioctl   wrapper;
+
+                wrapper.ifno = ifno;
+                wrapper.ioctl_code = request;
+                wrapper.data = param;
+
+                return ioctl (fd, USBDEVFS_IOCTL, &wrapper);
+        }
+
+    File modification time is not updated by this request.
+
+    This request lets kernel drivers talk to user mode code through
+    filesystem operations even when they don't create a character or
+    block special device. It's also been used to do things like ask
+    devices what device special file should be used. Two pre-defined
+    ioctls are used to disconnect and reconnect kernel drivers, so that
+    user mode code can completely manage binding and configuration of
+    devices.
+
+USBDEVFS_RELEASEINTERFACE
+    This is used to release the claim usbfs made on interface, either
+    implicitly or because of a USBDEVFS_CLAIMINTERFACE call, before the
+    file descriptor is closed. The ioctl parameter is an integer holding
+    the number of the interface (bInterfaceNumber from descriptor); File
+    modification time is not updated by this request.
+
+        **Warning**
+
+        *No security check is made to ensure that the task which made
+        the claim is the one which is releasing it. This means that user
+        mode driver may interfere other ones.*
+
+USBDEVFS_RESETEP
+    Resets the data toggle value for an endpoint (bulk or interrupt) to
+    DATA0. The ioctl parameter is an integer endpoint number (1 to 15,
+    as identified in the endpoint descriptor), with USB_DIR_IN added
+    if the device's endpoint sends data to the host.
+
+        **Warning**
+
+        *Avoid using this request. It should probably be removed.* Using
+        it typically means the device and driver will lose toggle
+        synchronization. If you really lost synchronization, you likely
+        need to completely handshake with the device, using a request
+        like CLEAR_HALT or SET_INTERFACE.
+
+USBDEVFS_DROP_PRIVILEGES
+    This is used to relinquish the ability to do certain operations
+    which are considered to be privileged on a usbfs file descriptor.
+    This includes claiming arbitrary interfaces, resetting a device on
+    which there are currently claimed interfaces from other users, and
+    issuing USBDEVFS_IOCTL calls. The ioctl parameter is a 32 bit mask
+    of interfaces the user is allowed to claim on this file descriptor.
+    You may issue this ioctl more than one time to narrow said mask.
+
+Synchronous I/O Support
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Synchronous requests involve the kernel blocking until the user mode
+request completes, either by finishing successfully or by reporting an
+error. In most cases this is the simplest way to use usbfs, although as
+noted above it does prevent performing I/O to more than one endpoint at
+a time.
+
+USBDEVFS_BULK
+    Issues a bulk read or write request to the device. The ioctl
+    parameter is a pointer to this structure:
+
+    ::
+
+        struct usbdevfs_bulktransfer {
+                unsigned int  ep;
+                unsigned int  len;
+                unsigned int  timeout; /* in milliseconds */
+                void          *data;
+        };
+
+    The "ep" value identifies a bulk endpoint number (1 to 15, as
+    identified in an endpoint descriptor), masked with USB_DIR_IN when
+    referring to an endpoint which sends data to the host from the
+    device. The length of the data buffer is identified by "len"; Recent
+    kernels support requests up to about 128KBytes. *FIXME say how read
+    length is returned, and how short reads are handled.*.
+
+USBDEVFS_CLEAR_HALT
+    Clears endpoint halt (stall) and resets the endpoint toggle. This is
+    only meaningful for bulk or interrupt endpoints. The ioctl parameter
+    is an integer endpoint number (1 to 15, as identified in an endpoint
+    descriptor), masked with USB_DIR_IN when referring to an endpoint
+    which sends data to the host from the device.
+
+    Use this on bulk or interrupt endpoints which have stalled,
+    returning *-EPIPE* status to a data transfer request. Do not issue
+    the control request directly, since that could invalidate the host's
+    record of the data toggle.
+
+USBDEVFS_CONTROL
+    Issues a control request to the device. The ioctl parameter points
+    to a structure like this:
+
+    ::
+
+        struct usbdevfs_ctrltransfer {
+                __u8   bRequestType;
+                __u8   bRequest;
+                __u16  wValue;
+                __u16  wIndex;
+                __u16  wLength;
+                __u32  timeout;  /* in milliseconds */
+                void   *data;
+        };
+
+    The first eight bytes of this structure are the contents of the
+    SETUP packet to be sent to the device; see the USB 2.0 specification
+    for details. The bRequestType value is composed by combining a
+    USB_TYPE_\* value, a USB_DIR_\* value, and a USB_RECIP_\*
+    value (from **). If wLength is nonzero, it describes
+    the length of the data buffer, which is either written to the device
+    (USB_DIR_OUT) or read from the device (USB_DIR_IN).
+
+    At this writing, you can't transfer more than 4 KBytes of data to or
+    from a device; usbfs has a limit, and some host controller drivers
+    have a limit. (That's not usually a problem.) *Also* there's no way
+    to say it's not OK to get a short read back from the device.
+
+USBDEVFS_RESET
+    Does a USB level device reset. The ioctl parameter is ignored. After
+    the reset, this rebinds all device interfaces. File modification
+    time is not updated by this request.
+
+        **Warning**
+
+        *Avoid using this call* until some usbcore bugs get fixed, since
+        it does not fully synchronize device, interface, and driver (not
+        just usbfs) state.
+
+USBDEVFS_SETINTERFACE
+    Sets the alternate setting for an interface. The ioctl parameter is
+    a pointer to a structure like this:
+
+    ::
+
+        struct usbdevfs_setinterface {
+                unsigned int  interface;
+                unsigned int  altsetting;
+        };
+
+    File modification time is not updated by this request.
+
+    Those struct members are from some interface descriptor applying to
+    the current configuration. The interface number is the
+    bInterfaceNumber value, and the altsetting number is the
+    bAlternateSetting value. (This resets each endpoint in the
+    interface.)
+
+USBDEVFS_SETCONFIGURATION
+    Issues the :c:func:`usb_set_configuration()` call for the
+    device. The parameter is an integer holding the number of a
+    configuration (bConfigurationValue from descriptor). File
+    modification time is not updated by this request.
+
+        **Warning**
+
+        *Avoid using this call* until some usbcore bugs get fixed, since
+        it does not fully synchronize device, interface, and driver (not
+        just usbfs) state.
+
+Asynchronous I/O Support
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+As mentioned above, there are situations where it may be important to
+initiate concurrent operations from user mode code. This is particularly
+important for periodic transfers (interrupt and isochronous), but it can
+be used for other kinds of USB requests too. In such cases, the
+asynchronous requests described here are essential. Rather than
+submitting one request and having the kernel block until it completes,
+the blocking is separate.
+
+These requests are packaged into a structure that resembles the URB used
+by kernel device drivers. (No POSIX Async I/O support here, sorry.) It
+identifies the endpoint type (USBDEVFS_URB_TYPE_\*), endpoint
+(number, masked with USB_DIR_IN as appropriate), buffer and length,
+and a user "context" value serving to uniquely identify each request.
+(It's usually a pointer to per-request data.) Flags can modify requests
+(not as many as supported for kernel drivers).
+
+Each request can specify a realtime signal number (between SIGRTMIN and
+SIGRTMAX, inclusive) to request a signal be sent when the request
+completes.
+
+When usbfs returns these urbs, the status value is updated, and the
+buffer may have been modified. Except for isochronous transfers, the
+actual_length is updated to say how many bytes were transferred; if the
+USBDEVFS_URB_DISABLE_SPD flag is set ("short packets are not OK"), if
+fewer bytes were read than were requested then you get an error report.
+
+::
+
+    struct usbdevfs_iso_packet_desc {
+            unsigned int                     length;
+            unsigned int                     actual_length;
+            unsigned int                     status;
+    };
+
+    struct usbdevfs_urb {
+            unsigned char                    type;
+            unsigned char                    endpoint;
+            int                              status;
+            unsigned int                     flags;
+            void                             *buffer;
+            int                              buffer_length;
+            int                              actual_length;
+            int                              start_frame;
+            int                              number_of_packets;
+            int                              error_count;
+            unsigned int                     signr;
+            void                             *usercontext;
+            struct usbdevfs_iso_packet_desc  iso_frame_desc[];
+    };
+
+For these asynchronous requests, the file modification time reflects
+when the request was initiated. This contrasts with their use with the
+synchronous requests, where it reflects when requests complete.
+
+USBDEVFS_DISCARDURB
+    *TBS* File modification time is not updated by this request.
+
+USBDEVFS_DISCSIGNAL
+    *TBS* File modification time is not updated by this request.
+
+USBDEVFS_REAPURB
+    *TBS* File modification time is not updated by this request.
+
+USBDEVFS_REAPURBNDELAY
+    *TBS* File modification time is not updated by this request.
+
+USBDEVFS_SUBMITURB
+    *TBS*
-- 
cgit v1.2.3


From dc92726e7f8d9e400ae4fa42fde4c3a5020fcbb8 Mon Sep 17 00:00:00 2001
From: Brian Norris 
Date: Tue, 15 Nov 2016 14:42:14 -0800
Subject: docs/completion.txt: drop dangling reference to
 completions-design.txt

Per the original author, the proposed document was never deemed
necessary, and the important bits got merged into completion.txt. Let's
just stop confusing readers by pointing at a nonexistent doc.

Signed-off-by: Brian Norris 
Signed-off-by: Jonathan Corbet 
---
 Documentation/scheduler/completion.txt | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/Documentation/scheduler/completion.txt b/Documentation/scheduler/completion.txt
index 2622bc7a188b..656cf803c006 100644
--- a/Documentation/scheduler/completion.txt
+++ b/Documentation/scheduler/completion.txt
@@ -25,8 +25,7 @@ struct completion that tells the waiting threads of execution if they
 can continue safely.
 
 As completions are scheduling related, the code is found in
-kernel/sched/completion.c - for details on completion design and
-implementation see completions-design.txt
+kernel/sched/completion.c.
 
 
 Usage:
-- 
cgit v1.2.3


From 0c9aa209579d41c9b8bf1fc39ce042bea2ec422d Mon Sep 17 00:00:00 2001
From: Jani Nikula 
Date: Wed, 16 Nov 2016 17:26:16 +0200
Subject: kernel-doc: add support for one line inline struct member doc
 comments

kernel-doc supports documenting struct members "inline" since
a4c6ebede2f9 ("scripts/kernel-doc Allow struct arguments documentation
in struct body"). This requires the inline kernel-doc comments to have
the opening and closing comment markers (/** and */ respectively) on
lines of their own, even for short comments. For example:

	/**
	 * struct foo - struct documentation
	 */
	struct foo {
		/**
		 * @bar: member documentation
		 */
		int bar;
	};

Add support for one line inline comments:

	/**
	 * struct foo - struct documentation
	 */
	struct foo {
		/** @bar: member documentation */
		int bar;
	};

Note that mixing of the two in one doc comment is not allowed; either
both comment markers must be on lines of their own, or both must be on
the one line. This limitation keeps both the comments more uniform, and
kernel-doc less complicated.

Cc: Daniel Vetter 
Signed-off-by: Jani Nikula 
Signed-off-by: Jonathan Corbet 
---
 scripts/kernel-doc | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index e10378f769f9..030fc633acd4 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -421,6 +421,7 @@ my $doc_block = $doc_com . 'DOC:\s*(.*)?';
 my $doc_inline_start = '^\s*/\*\*\s*$';
 my $doc_inline_sect = '\s*\*\s*(@[\w\s]+):(.*)';
 my $doc_inline_end = '^\s*\*/\s*$';
+my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';
 my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*\(\s*(\w+)\s*\)\s*;';
 
 my %parameterdescs;
@@ -3024,7 +3025,16 @@ sub process_file($) {
 		}
 	    }
 	} elsif ($state == STATE_PROTO) {	# scanning for function '{' (end of prototype)
-	    if (/$doc_inline_start/) {
+	    if (/$doc_inline_oneline/) {
+		$section = $1;
+		$contents = $2;
+		if ($contents ne "") {
+		    $contents .= "\n";
+		    dump_section($file, $section, xml_escape($contents));
+		    $section = $section_default;
+		    $contents = "";
+		}
+	    } elsif (/$doc_inline_start/) {
 		$state = STATE_INLINE;
 		$inline_doc_state = STATE_INLINE_NAME;
 	    } elsif ($decl_type eq 'function') {
-- 
cgit v1.2.3


From 38f985e3c9bb33d5422103807eb0a54f4ad39a0d Mon Sep 17 00:00:00 2001
From: Daniel Vetter 
Date: Thu, 17 Nov 2016 11:19:43 +0100
Subject: doc: Document the new inline struct member kernel-doc style

We don't just need better doc toolchains, we also need better docs for
our doc toolchain!

v2: Make sure we don't have foo twice (Jani).

Cc: Daniel Vetter 
Cc: Jani Nikula 
Cc: Jonathan Corbet 
Cc: linux-doc@vger.kernel.org
Signed-off-by: Daniel Vetter 
Signed-off-by: Jonathan Corbet 
---
 Documentation/kernel-documentation.rst | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
index c66ab937c2ca..3fcf0ad6e5f0 100644
--- a/Documentation/kernel-documentation.rst
+++ b/Documentation/kernel-documentation.rst
@@ -484,7 +484,10 @@ 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::
+The structure members may also be documented in-line within the definition.
+There are two styles, single-line comments where both the opening ``/**`` and
+closing ``*/`` are on the same line, and multi-line comments where they are each
+on a line of their own, like all other kernel-doc comments::
 
   /**
    * struct foo - Brief description.
@@ -502,6 +505,8 @@ The structure members may also be documented in-line within the definition::
          * Here, the member description may contain several paragraphs.
          */
         int baz;
+        /** @foobar: Single line description. */
+        int foobar;
   }
 
 Private members
-- 
cgit v1.2.3


From 1dc4bbf0b268246f6202c761016735933b6f0b99 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Thu, 17 Nov 2016 08:32:33 -0200
Subject: docs-rst: doc-guide: split the kernel-documentation.rst contents

Having the kernel-documentation at the topmost level doesn't
allow generating a separate PDF file for it. Also, makes harder
to add extra contents. So, place it on a sub-dir.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/00-INDEX                       |   2 +-
 Documentation/conf.py                        |   2 +
 Documentation/doc-guide/conf.py              |  10 +
 Documentation/doc-guide/docbook.rst          |  90 ++++
 Documentation/doc-guide/index.rst            |  19 +
 Documentation/doc-guide/kernel-doc.rst       | 363 ++++++++++++++
 Documentation/doc-guide/sphinx.rst           | 219 +++++++++
 Documentation/index.rst                      |   2 +-
 Documentation/kernel-doc-nano-HOWTO.txt      |   2 +-
 Documentation/kernel-documentation.rst       | 679 ---------------------------
 Documentation/process/4.Coding.rst           |   4 +-
 Documentation/process/coding-style.rst       |   4 +-
 Documentation/translations/zh_CN/CodingStyle |   2 +-
 13 files changed, 711 insertions(+), 687 deletions(-)
 create mode 100644 Documentation/doc-guide/conf.py
 create mode 100644 Documentation/doc-guide/docbook.rst
 create mode 100644 Documentation/doc-guide/index.rst
 create mode 100644 Documentation/doc-guide/kernel-doc.rst
 create mode 100644 Documentation/doc-guide/sphinx.rst
 delete mode 100644 Documentation/kernel-documentation.rst

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index e2e74448d425..c08de5574d48 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -258,7 +258,7 @@ kdump/
 	- directory with mini HowTo on getting the crash dump code to work.
 process/kernel-docs.rst
 	- listing of various WWW + books that document kernel internals.
-kernel-documentation.rst
+doc-guide/
 	- how to write and format reStructuredText kernel documentation
 admin-guide/kernel-parameters.rst
 	- summary listing of command line / boot prompt args for the kernel.
diff --git a/Documentation/conf.py b/Documentation/conf.py
index ba38bcf485a9..1ac958c0333d 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -340,6 +340,8 @@ if major == 1 and minor > 3:
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
+    ('doc-guide/index', 'kernel-doc-guide.tex', 'Linux Kernel Documentation Guide',
+     'The kernel development community', 'manual'),
     ('admin-guide/index', 'linux-user.tex', 'Linux Kernel User Documentation',
      'The kernel development community', 'manual'),
     ('core-api/index', 'core-api.tex', 'The kernel core API manual',
diff --git a/Documentation/doc-guide/conf.py b/Documentation/doc-guide/conf.py
new file mode 100644
index 000000000000..fd3731182d5a
--- /dev/null
+++ b/Documentation/doc-guide/conf.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = 'Linux Kernel Documentation Guide'
+
+tags.add("subproject")
+
+latex_documents = [
+    ('index', 'kernel-doc-guide.tex', 'Linux Kernel Documentation Guide',
+     'The kernel development community', 'manual'),
+]
diff --git a/Documentation/doc-guide/docbook.rst b/Documentation/doc-guide/docbook.rst
new file mode 100644
index 000000000000..d8bf04308b43
--- /dev/null
+++ b/Documentation/doc-guide/docbook.rst
@@ -0,0 +1,90 @@
+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
+----------------------------
+
+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`` is replaced by the documentation, in ````, for
+functions that are exported using ``EXPORT_SYMBOL``: the function list is
+collected from files listed in ``Documentation/DocBook/Makefile``.
+
+``!I`` is replaced by the documentation for functions that are **not**
+exported using ``EXPORT_SYMBOL``.
+
+``!D`` is used to name additional files to search for functions
+exported using ``EXPORT_SYMBOL``.
+
+``!F `` is replaced by the documentation, in
+````, for the functions listed.
+
+``!P 
`` is replaced by the contents of the ``DOC:``
+section titled ``
`` from ````. Spaces are allowed in
+``
``; do not quote the ``
``.
+
+``!C`` 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.
diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst
new file mode 100644
index 000000000000..695b7b6cf6ed
--- /dev/null
+++ b/Documentation/doc-guide/index.rst
@@ -0,0 +1,19 @@
+.. _doc_guide:
+
+=================================
+How to write kernel documentation
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   sphinx.rst
+   kernel-doc.rst
+   docbook.rst
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst
new file mode 100644
index 000000000000..afc95c9e9626
--- /dev/null
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -0,0 +1,363 @@
+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.
+
+.. _kernel_doc:
+
+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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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 `.
+  See :c:type:`union bar `.
+  See :c:type:`enum baz `.
+  See :c:type:`typedef 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
+----------------------
+
+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.
diff --git a/Documentation/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
new file mode 100644
index 000000000000..96fe7ccb2c67
--- /dev/null
+++ b/Documentation/doc-guide/sphinx.rst
@@ -0,0 +1,219 @@
+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.
+
+
+the C domain
+------------
+
+The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. a
+function prototype:
+
+.. code-block:: rst
+
+    .. c:function:: int ioctl( int fd, int request )
+
+The C domain of the kernel-doc has some additional features. E.g. you can
+*rename* the reference name of a function with a common name like ``open`` or
+``ioctl``:
+
+.. code-block:: rst
+
+     .. c:function:: int ioctl( int fd, int request )
+        :name: VIDIOC_LOG_STATUS
+
+The func-name (e.g. ioctl) remains in the output but the ref-name changed from
+``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also
+changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by:
+
+.. code-block:: rst
+
+     :c:func:`VIDIOC_LOG_STATUS`
+
+
+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 ``` / :ref:`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
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 286d92bad208..bf3eb3ad6ad5 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -38,7 +38,7 @@ merged much easier.
 
    process/index
    dev-tools/index
-   kernel-documentation
+   doc-guide/index
 
 Kernel API documentation
 ------------------------
diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt
index 062e3af271b7..104740ea0041 100644
--- a/Documentation/kernel-doc-nano-HOWTO.txt
+++ b/Documentation/kernel-doc-nano-HOWTO.txt
@@ -1,5 +1,5 @@
 NOTE: this document is outdated and will eventually be removed.  See
-Documentation/kernel-documentation.rst for current information.
+Documentation/doc-guide/ for current information.
 
 kernel-doc nano-HOWTO
 =====================
diff --git a/Documentation/kernel-documentation.rst b/Documentation/kernel-documentation.rst
deleted file mode 100644
index c66ab937c2ca..000000000000
--- a/Documentation/kernel-documentation.rst
+++ /dev/null
@@ -1,679 +0,0 @@
-=================================
-How to write 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.
-
-
-the C domain
-------------
-
-The `Sphinx C Domain`_ (name c) is suited for documentation of C API. E.g. a
-function prototype:
-
-.. code-block:: rst
-
-    .. c:function:: int ioctl( int fd, int request )
-
-The C domain of the kernel-doc has some additional features. E.g. you can
-*rename* the reference name of a function with a common name like ``open`` or
-``ioctl``:
-
-.. code-block:: rst
-
-     .. c:function:: int ioctl( int fd, int request )
-        :name: VIDIOC_LOG_STATUS
-
-The func-name (e.g. ioctl) remains in the output but the ref-name changed from
-``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for this function is also
-changed to ``VIDIOC_LOG_STATUS`` and the function can now referenced by:
-
-.. code-block:: rst
-
-     :c:func:`VIDIOC_LOG_STATUS`
-
-
-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 ``` / :ref:`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.
-
-.. _kernel_doc:
-
-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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-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 `.
-  See :c:type:`union bar `.
-  See :c:type:`enum baz `.
-  See :c:type:`typedef 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
-----------------------
-
-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
-----------------------------
-
-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`` is replaced by the documentation, in ````, for
-functions that are exported using ``EXPORT_SYMBOL``: the function list is
-collected from files listed in ``Documentation/DocBook/Makefile``.
-
-``!I`` is replaced by the documentation for functions that are **not**
-exported using ``EXPORT_SYMBOL``.
-
-``!D`` is used to name additional files to search for functions
-exported using ``EXPORT_SYMBOL``.
-
-``!F `` is replaced by the documentation, in
-````, for the functions listed.
-
-``!P 
`` is replaced by the contents of the ``DOC:``
-section titled ``
`` from ````. Spaces are allowed in
-``
``; do not quote the ``
``.
-
-``!C`` 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.
diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.Coding.rst
index 983d628c1112..2a728d898fc5 100644
--- a/Documentation/process/4.Coding.rst
+++ b/Documentation/process/4.Coding.rst
@@ -358,8 +358,8 @@ them, as appropriate, for externally-available functions.  Even in areas
 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-documentation.rst.
+information on how to create kerneldoc templates can be found at
+:ref:`Documentation/doc-guide/ `.
 
 Anybody who reads through a significant amount of existing kernel code will
 note that, often, comments are most notable by their absence.  Once again,
diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 3e7905172000..d20d52a4d812 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -525,8 +525,8 @@ 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-documentation.rst and scripts/kernel-doc
-for details.
+See the files at :ref:`Documentation/doc-guide/ ` and
+``scripts/kernel-doc`` for details.
 
 The preferred style for long (multi-line) comments is:
 
diff --git a/Documentation/translations/zh_CN/CodingStyle b/Documentation/translations/zh_CN/CodingStyle
index b02738042799..dc101f48e713 100644
--- a/Documentation/translations/zh_CN/CodingStyle
+++ b/Documentation/translations/zh_CN/CodingStyle
@@ -399,7 +399,7 @@ C是一个简朴的语言，你的命名也应该这样。和 Modula-2 和 Pasca
 些事情的原因。
 
 当注释内核API函数时，请使用 kernel-doc 格式。请看
-Documentation/kernel-documentation.rst和scripts/kernel-doc 以获得详细信息。
+Documentation/doc-guide/和scripts/kernel-doc 以获得详细信息。
 
 Linux的注释风格是 C89 “/* ... */” 风格。不要使用 C99 风格 “// ...” 注释。
 
-- 
cgit v1.2.3


From 327f5a754ab14aa9dc20e9c31cf776680b1d9a4d Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Thu, 17 Nov 2016 08:32:34 -0200
Subject: parse-headers.pl: add documentation for this script

Provide a man page for parse-headers.pl, describing
how to use it.

The documentation on ReST format was generated via pod2rst:
	http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/doc-guide/index.rst         |   1 +
 Documentation/doc-guide/parse-headers.rst | 186 ++++++++++++++++++++++++++++
 Documentation/sphinx/parse-headers.pl     | 193 ++++++++++++++++++++++++++++--
 3 files changed, 367 insertions(+), 13 deletions(-)
 create mode 100644 Documentation/doc-guide/parse-headers.rst

diff --git a/Documentation/doc-guide/index.rst b/Documentation/doc-guide/index.rst
index 695b7b6cf6ed..6fff4024606e 100644
--- a/Documentation/doc-guide/index.rst
+++ b/Documentation/doc-guide/index.rst
@@ -9,6 +9,7 @@ How to write kernel documentation
 
    sphinx.rst
    kernel-doc.rst
+   parse-headers.rst
    docbook.rst
 
 .. only::  subproject and html
diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst
new file mode 100644
index 000000000000..a1867d757ff4
--- /dev/null
+++ b/Documentation/doc-guide/parse-headers.rst
@@ -0,0 +1,186 @@
+================
+parse_headers.pl
+================
+
+****
+NAME
+****
+
+
+parse_headers.pl - parse a C file, in order to identify functions, structs,
+enums and defines and create cross-references to a Sphinx book.
+
+
+********
+SYNOPSIS
+********
+
+
+\ **parse_headers.pl**\  []   []
+
+Where  can be: --debug, --help or --man.
+
+
+*******
+OPTIONS
+*******
+
+
+
+\ **--debug**\
+
+ Put the script in verbose mode, useful for debugging.
+
+
+
+\ **--help**\
+
+ Prints a brief help message and exits.
+
+
+
+\ **--man**\
+
+ Prints the manual page and exits.
+
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+Convert a C header or source file (C_FILE), into a ReStructured Text
+included via ..parsed-literal block with cross-references for the
+documentation files that describe the API. It accepts an optional
+EXCEPTIONS_FILE with describes what elements will be either ignored or
+be pointed to a non-default reference.
+
+The output is written at the (OUT_FILE).
+
+It is capable of identifying defines, functions, structs, typedefs,
+enums and enum symbols and create cross-references for all of them.
+It is also capable of distinguish #define used for specifying a Linux
+ioctl.
+
+The EXCEPTIONS_FILE contain two types of statements: \ **ignore**\  or \ **replace**\ .
+
+The syntax for the ignore tag is:
+
+
+ignore \ **type**\  \ **name**\
+
+The \ **ignore**\  means that it won't generate cross references for a
+\ **name**\  symbol of type \ **type**\ .
+
+The syntax for the replace tag is:
+
+
+replace \ **type**\  \ **name**\  \ **new_value**\
+
+The \ **replace**\  means that it will generate cross references for a
+\ **name**\  symbol of type \ **type**\ , but, instead of using the default
+replacement rule, it will use \ **new_value**\ .
+
+For both statements, \ **type**\  can be either one of the following:
+
+
+\ **ioctl**\
+
+ The ignore or replace statement will apply to ioctl definitions like:
+
+ #define	VIDIOC_DBG_S_REGISTER 	 _IOW('V', 79, struct v4l2_dbg_register)
+
+
+
+\ **define**\
+
+ The ignore or replace statement will apply to any other #define found
+ at C_FILE.
+
+
+
+\ **typedef**\
+
+ The ignore or replace statement will apply to typedef statements at C_FILE.
+
+
+
+\ **struct**\
+
+ The ignore or replace statement will apply to the name of struct statements
+ at C_FILE.
+
+
+
+\ **enum**\
+
+ The ignore or replace statement will apply to the name of enum statements
+ at C_FILE.
+
+
+
+\ **symbol**\
+
+ The ignore or replace statement will apply to the name of enum statements
+ at C_FILE.
+
+ For replace statements, \ **new_value**\  will automatically use :c:type:
+ references for \ **typedef**\ , \ **enum**\  and \ **struct**\  types. It will use :ref:
+ for \ **ioctl**\ , \ **define**\  and \ **symbol**\  types. The type of reference can
+ also be explicitly defined at the replace statement.
+
+
+
+
+********
+EXAMPLES
+********
+
+
+ignore define _VIDEODEV2_H
+
+
+Ignore a #define _VIDEODEV2_H at the C_FILE.
+
+ignore symbol PRIVATE
+
+
+On a struct like:
+
+enum foo { BAR1, BAR2, PRIVATE };
+
+It won't generate cross-references for \ **PRIVATE**\ .
+
+replace symbol BAR1 :c:type:\`foo\`
+replace symbol BAR2 :c:type:\`foo\`
+
+
+On a struct like:
+
+enum foo { BAR1, BAR2, PRIVATE };
+
+It will make the BAR1 and BAR2 enum symbols to cross reference the foo
+symbol at the C domain.
+
+
+****
+BUGS
+****
+
+
+Report bugs to Mauro Carvalho Chehab 
+
+
+*********
+COPYRIGHT
+*********
+
+
+Copyright (c) 2016 by Mauro Carvalho Chehab .
+
+License GPLv2: GNU GPL version 2 .
+
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl
index db0186a7618f..20dbdf55c71e 100755
--- a/Documentation/sphinx/parse-headers.pl
+++ b/Documentation/sphinx/parse-headers.pl
@@ -1,22 +1,22 @@
 #!/usr/bin/perl
 use strict;
 use Text::Tabs;
+use Getopt::Long;
+use Pod::Usage;
 
-my $debug = 0;
+my $debug;
+my $help;
+my $man;
 
-while ($ARGV[0] =~ m/^-(.*)/) {
-	my $cmd = shift @ARGV;
-	if ($cmd eq "--debug") {
-		require Data::Dumper;
-		$debug = 1;
-		next;
-	}
-	die "argument $cmd unknown";
-}
+GetOptions(
+	"debug" => \$debug,
+	'help|?' => \$help,
+	man => \$man
+) or pod2usage(2);
 
-if (scalar @ARGV < 2 || scalar @ARGV > 3) {
-	die "Usage:\n\t$0   []\n";
-}
+pod2usage(1) if $help;
+pod2usage(-exitstatus => 0, -verbose => 2) if $man;
+pod2usage(2) if (scalar @ARGV < 2 || scalar @ARGV > 3);
 
 my ($file_in, $file_out, $file_exceptions) = @ARGV;
 
@@ -28,6 +28,8 @@ my %enums;
 my %enum_symbols;
 my %structs;
 
+require Data::Dumper if ($debug);
+
 #
 # read the file and get identifiers
 #
@@ -330,3 +332,168 @@ print OUT "=" x length($title);
 print OUT "\n\n.. parsed-literal::\n\n";
 print OUT $data;
 close OUT;
+
+__END__
+
+=head1 NAME
+
+parse_headers.pl - parse a C file, in order to identify functions, structs,
+enums and defines and create cross-references to a Sphinx book.
+
+=head1 SYNOPSIS
+
+B []   []
+
+Where  can be: --debug, --help or --man.
+
+=head1 OPTIONS
+
+=over 8
+
+=item B<--debug>
+
+Put the script in verbose mode, useful for debugging.
+
+=item B<--help>
+
+Prints a brief help message and exits.
+
+=item B<--man>
+
+Prints the manual page and exits.
+
+=back
+
+=head1 DESCRIPTION
+
+Convert a C header or source file (C_FILE), into a ReStructured Text
+included via ..parsed-literal block with cross-references for the
+documentation files that describe the API. It accepts an optional
+EXCEPTIONS_FILE with describes what elements will be either ignored or
+be pointed to a non-default reference.
+
+The output is written at the (OUT_FILE).
+
+It is capable of identifying defines, functions, structs, typedefs,
+enums and enum symbols and create cross-references for all of them.
+It is also capable of distinguish #define used for specifying a Linux
+ioctl.
+
+The EXCEPTIONS_FILE contain two types of statements: B or B.
+
+The syntax for the ignore tag is:
+
+=over 8
+
+ignore B B
+
+=back
+
+The B means that it won't generate cross references for a
+B symbol of type B.
+
+The syntax for the replace tag is:
+
+=over 8
+
+replace B B B
+
+=back
+
+The B means that it will generate cross references for a
+B symbol of type B, but, instead of using the default
+replacement rule, it will use B.
+
+For both statements, B can be either one of the following:
+
+=over 8
+
+=item B
+
+The ignore or replace statement will apply to ioctl definitions like:
+
+#define	VIDIOC_DBG_S_REGISTER 	 _IOW('V', 79, struct v4l2_dbg_register)
+
+=item B
+
+The ignore or replace statement will apply to any other #define found
+at C_FILE.
+
+=item B
+
+The ignore or replace statement will apply to typedef statements at C_FILE.
+
+=item B
+
+The ignore or replace statement will apply to the name of struct statements
+at C_FILE.
+
+=item B
+
+The ignore or replace statement will apply to the name of enum statements
+at C_FILE.
+
+=item B
+
+The ignore or replace statement will apply to the name of enum statements
+at C_FILE.
+
+
+For replace statements, B will automatically use :c:type:
+references for B, B and B types. It will use :ref:
+for B, B and B types. The type of reference can
+also be explicitly defined at the replace statement.
+
+=back
+
+=head1 EXAMPLES
+
+ignore define _VIDEODEV2_H
+
+=over 8
+
+
+Ignore a #define _VIDEODEV2_H at the C_FILE.
+
+=back
+
+ignore symbol PRIVATE
+
+=over 8
+
+On a struct like:
+
+enum foo { BAR1, BAR2, PRIVATE };
+
+It won't generate cross-references for B.
+
+=back
+
+replace symbol BAR1 :c:type:`foo`
+replace symbol BAR2 :c:type:`foo`
+
+=over 8
+
+On a struct like:
+
+enum foo { BAR1, BAR2, PRIVATE };
+
+It will make the BAR1 and BAR2 enum symbols to cross reference the foo
+symbol at the C domain.
+
+=back
+
+=head1 BUGS
+
+Report bugs to Mauro Carvalho Chehab 
+
+=head1 COPYRIGHT
+
+Copyright (c) 2016 by Mauro Carvalho Chehab .
+
+License GPLv2: GNU GPL version 2 .
+
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+
+=cut
-- 
cgit v1.2.3


From 2dde123b23ceba4b6d0d780b4e9fdcfb94621747 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Thu, 17 Nov 2016 08:32:35 -0200
Subject: parse-headers.rst: add an introduction to the man page

The pod2rst tool generated a man page for parse-headers.pl
script, but it is better to put it into some context.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/doc-guide/parse-headers.rst | 26 ++++++++++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst
index a1867d757ff4..615e25ec64bb 100644
--- a/Documentation/doc-guide/parse-headers.rst
+++ b/Documentation/doc-guide/parse-headers.rst
@@ -1,6 +1,28 @@
-================
+===========================
+Including uAPI header files
+===========================
+
+Sometimes, it is useful to include header files and C example codes in
+order to describe the userspace API and to generate cross-references
+between the code and the documentation. Adding cross-references for
+userspace API files has an additional vantage: Sphinx will generate warnings
+if a symbol is not found at the documentation. That helps to keep the
+uAPI documentation in sync with the Kernel changes.
+The :ref:`parse_headers.pl ` provide a way to generate such
+cross-references. It has to be called via Makefile, while building the
+documentation. Please see ``Documentation/media/Makefile`` for an example
+about how to use it inside the Kernel tree.
+
+.. _parse_headers:
+
 parse_headers.pl
-================
+^^^^^^^^^^^^^^^^
+
+.. NOTE: the man pages below were generated using pod2rst tool:
+.. http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst
+.. If you need to change anything below this point, please do the changes
+.. at parse-headers.pl directly, re-run the script and paste the output of
+.. the script here.
 
 ****
 NAME
-- 
cgit v1.2.3


From 9c240d757658a3ae9968dd309e674c61f07c7f48 Mon Sep 17 00:00:00 2001
From: Chao Fan 
Date: Wed, 26 Oct 2016 10:41:28 +0800
Subject: Change the document about iowait

The iowait is not reliable by reading from /proc/stat, so this
method to get iowait is not suggested. And we mark it in the
document.

Signed-off-by: Cao Jin 
Signed-off-by: Chao Fan 
Signed-off-by: Jonathan Corbet 
---
 Documentation/filesystems/proc.txt | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt
index 74329fd0add2..71f5096694b4 100644
--- a/Documentation/filesystems/proc.txt
+++ b/Documentation/filesystems/proc.txt
@@ -1305,7 +1305,16 @@ second).  The meanings of the columns are as follows, from left to right:
 - nice: niced processes executing in user mode
 - system: processes executing in kernel mode
 - idle: twiddling thumbs
-- iowait: waiting for I/O to complete
+- iowait: In a word, iowait stands for waiting for I/O to complete. But there
+  are several problems:
+  1. Cpu will not wait for I/O to complete, iowait is the time that a task is
+     waiting for I/O to complete. When cpu goes into idle state for
+     outstanding task io, another task will be scheduled on this CPU.
+  2. In a multi-core CPU, the task waiting for I/O to complete is not running
+     on any CPU, so the iowait of each CPU is difficult to calculate.
+  3. The value of iowait field in /proc/stat will decrease in certain
+     conditions.
+  So, the iowait is not reliable by reading from /proc/stat.
 - irq: servicing interrupts
 - softirq: servicing softirqs
 - steal: involuntary wait
-- 
cgit v1.2.3


From 388f9b20f98d4792f72091acac5031a99370827d Mon Sep 17 00:00:00 2001
From: Dan Carpenter 
Date: Mon, 28 Nov 2016 17:43:15 +0300
Subject: Documentation/process/howto: Only send regression fixes after -rc1

The original text was not clear if white space or other harmless patches
should be merged in -rc kernels.  The discussion at Kernel Summit said
that we should be more strict about sending regression fixes only.

Signed-off-by: Dan Carpenter 
Acked-by: Greg Kroah-Hartman 
Signed-off-by: Jonathan Corbet 
---
 Documentation/process/howto.rst | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst
index 449ca1f199f4..1260f60d4cb9 100644
--- a/Documentation/process/howto.rst
+++ b/Documentation/process/howto.rst
@@ -267,15 +267,16 @@ process is as follows:
     is using git (the kernel's source management tool, more information
     can be found at https://git-scm.com/) but plain patches are also just
     fine.
-  - After two weeks a -rc1 kernel is released it is now possible to push
-    only patches that do not include new features that could affect the
-    stability of the whole kernel.  Please note that a whole new driver
-    (or filesystem) might be accepted after -rc1 because there is no
-    risk of causing regressions with such a change as long as the change
-    is self-contained and does not affect areas outside of the code that
-    is being added.  git can be used to send patches to Linus after -rc1
-    is released, but the patches need to also be sent to a public
-    mailing list for review.
+  - After two weeks a -rc1 kernel is released and the focus is on making the
+    new kernel as rock solid as possible.  Most of the patches at this point
+    should fix a regression.  Bugs that have always existed are not
+    regressions, so only push these kinds of fixes if they are important.
+    Please note that a whole new driver (or filesystem) might be accepted
+    after -rc1 because there is no risk of causing regressions with such a
+    change as long as the change is self-contained and does not affect areas
+    outside of the code that is being added.  git can be used to send
+    patches to Linus after -rc1 is released, but the patches need to also be
+    sent to a public mailing list for review.
   - A new -rc is released whenever Linus deems the current git tree to
     be in a reasonably sane state adequate for testing.  The goal is to
     release a new -rc kernel every week.
-- 
cgit v1.2.3


From 0bb33e25e5c91f69304f3799609a52354dca1af4 Mon Sep 17 00:00:00 2001
From: Jonathan Corbet 
Date: Fri, 18 Nov 2016 16:04:48 -0700
Subject: docs: Move the 802.11 guide into the driver-api manual

Put this documentation with the other driver docs and try to keep the top
level reasonably clean.

Cc: Johannes Berg 
Signed-off-by: Jonathan Corbet 
---
 Documentation/80211/cfg80211.rst                   | 345 ---------------------
 Documentation/80211/conf.py                        |  10 -
 Documentation/80211/index.rst                      |  17 -
 Documentation/80211/introduction.rst               |  17 -
 Documentation/80211/mac80211-advanced.rst          | 295 ------------------
 Documentation/80211/mac80211.rst                   | 216 -------------
 Documentation/driver-api/80211/cfg80211.rst        | 345 +++++++++++++++++++++
 Documentation/driver-api/80211/conf.py             |  10 +
 Documentation/driver-api/80211/index.rst           |  17 +
 Documentation/driver-api/80211/introduction.rst    |  17 +
 .../driver-api/80211/mac80211-advanced.rst         | 295 ++++++++++++++++++
 Documentation/driver-api/80211/mac80211.rst        | 216 +++++++++++++
 Documentation/driver-api/index.rst                 |   2 +-
 Documentation/index.rst                            |   1 -
 14 files changed, 901 insertions(+), 902 deletions(-)
 delete mode 100644 Documentation/80211/cfg80211.rst
 delete mode 100644 Documentation/80211/conf.py
 delete mode 100644 Documentation/80211/index.rst
 delete mode 100644 Documentation/80211/introduction.rst
 delete mode 100644 Documentation/80211/mac80211-advanced.rst
 delete mode 100644 Documentation/80211/mac80211.rst
 create mode 100644 Documentation/driver-api/80211/cfg80211.rst
 create mode 100644 Documentation/driver-api/80211/conf.py
 create mode 100644 Documentation/driver-api/80211/index.rst
 create mode 100644 Documentation/driver-api/80211/introduction.rst
 create mode 100644 Documentation/driver-api/80211/mac80211-advanced.rst
 create mode 100644 Documentation/driver-api/80211/mac80211.rst

diff --git a/Documentation/80211/cfg80211.rst b/Documentation/80211/cfg80211.rst
deleted file mode 100644
index b1e149ea6fee..000000000000
--- a/Documentation/80211/cfg80211.rst
+++ /dev/null
@@ -1,345 +0,0 @@
-==================
-cfg80211 subsystem
-==================
-
-Device registration
-===================
-
-.. kernel-doc:: include/net/cfg80211.h
-   :doc: Device registration
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_channel_flags
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_channel
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_rate_flags
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_rate
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_sta_ht_cap
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_supported_band
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_signal_type
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: wiphy_params_flags
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: wiphy_flags
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: wiphy
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: wireless_dev
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: wiphy_new
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: wiphy_register
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: wiphy_unregister
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: wiphy_free
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: wiphy_name
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: wiphy_dev
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: wiphy_priv
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: priv_to_wiphy
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: set_wiphy_dev
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: wdev_priv
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_iface_limit
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_iface_combination
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_check_combinations
-
-Actions and configuration
-=========================
-
-.. kernel-doc:: include/net/cfg80211.h
-   :doc: Actions and configuration
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_ops
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: vif_params
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: key_params
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: survey_info_flags
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: survey_info
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_beacon_data
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_ap_settings
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: station_parameters
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: rate_info_flags
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: rate_info
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: station_info
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: monitor_flags
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: mpath_info_flags
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: mpath_info
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: bss_parameters
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_txq_params
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_crypto_settings
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_auth_request
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_assoc_request
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_deauth_request
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_disassoc_request
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_ibss_params
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_connect_params
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_pmksa
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_rx_mlme_mgmt
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_auth_timeout
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_rx_assoc_resp
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_assoc_timeout
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_tx_mlme_mgmt
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_ibss_joined
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_connect_result
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_connect_bss
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_connect_timeout
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_roamed
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_disconnected
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_ready_on_channel
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_remain_on_channel_expired
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_new_sta
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_rx_mgmt
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_mgmt_tx_status
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_cqm_rssi_notify
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_cqm_pktloss_notify
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_michael_mic_failure
-
-Scanning and BSS list handling
-==============================
-
-.. kernel-doc:: include/net/cfg80211.h
-   :doc: Scanning and BSS list handling
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_ssid
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_scan_request
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_scan_done
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_bss
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_inform_bss
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_inform_bss_frame_data
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_inform_bss_data
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_unlink_bss
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_find_ie
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_bss_get_ie
-
-Utility functions
-=================
-
-.. kernel-doc:: include/net/cfg80211.h
-   :doc: Utility functions
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_channel_to_frequency
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_frequency_to_channel
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_get_channel
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_get_response_rate
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_hdrlen
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_get_hdrlen_from_skb
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_radiotap_iterator
-
-Data path helpers
-=================
-
-.. kernel-doc:: include/net/cfg80211.h
-   :doc: Data path helpers
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_data_to_8023
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_data_from_8023
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: ieee80211_amsdu_to_8023s
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_classify8021d
-
-Regulatory enforcement infrastructure
-=====================================
-
-.. kernel-doc:: include/net/cfg80211.h
-   :doc: Regulatory enforcement infrastructure
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: regulatory_hint
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: wiphy_apply_custom_regulatory
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: freq_reg_info
-
-RFkill integration
-==================
-
-.. kernel-doc:: include/net/cfg80211.h
-   :doc: RFkill integration
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: wiphy_rfkill_set_hw_state
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: wiphy_rfkill_start_polling
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: wiphy_rfkill_stop_polling
-
-Test mode
-=========
-
-.. kernel-doc:: include/net/cfg80211.h
-   :doc: Test mode
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_testmode_alloc_reply_skb
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_testmode_reply
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_testmode_alloc_event_skb
-
-.. kernel-doc:: include/net/cfg80211.h
-   :functions: cfg80211_testmode_event
diff --git a/Documentation/80211/conf.py b/Documentation/80211/conf.py
deleted file mode 100644
index 4424b4b0b9c3..000000000000
--- a/Documentation/80211/conf.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# -*- coding: utf-8; mode: python -*-
-
-project = "Linux 802.11 Driver Developer's Guide"
-
-tags.add("subproject")
-
-latex_documents = [
-    ('index', '80211.tex', project,
-     'The kernel development community', 'manual'),
-]
diff --git a/Documentation/80211/index.rst b/Documentation/80211/index.rst
deleted file mode 100644
index af210859d3e1..000000000000
--- a/Documentation/80211/index.rst
+++ /dev/null
@@ -1,17 +0,0 @@
-=====================================
-Linux 802.11 Driver Developer's Guide
-=====================================
-
-.. toctree::
-
-   introduction
-   cfg80211
-   mac80211
-   mac80211-advanced
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
diff --git a/Documentation/80211/introduction.rst b/Documentation/80211/introduction.rst
deleted file mode 100644
index 4938fa87691c..000000000000
--- a/Documentation/80211/introduction.rst
+++ /dev/null
@@ -1,17 +0,0 @@
-============
-Introduction
-============
-
-Explaining wireless 802.11 networking in the Linux kernel
-
-Copyright 2007-2009 Johannes Berg
-
-These books attempt to give a description of the various subsystems
-that play a role in 802.11 wireless networking in Linux. Since these
-books are for kernel developers they attempts to document the
-structures and functions used in the kernel as well as giving a
-higher-level overview.
-
-The reader is expected to be familiar with the 802.11 standard as
-published by the IEEE in 802.11-2007 (or possibly later versions).
-References to this standard will be given as "802.11-2007 8.1.5".
diff --git a/Documentation/80211/mac80211-advanced.rst b/Documentation/80211/mac80211-advanced.rst
deleted file mode 100644
index 70a89b2163c2..000000000000
--- a/Documentation/80211/mac80211-advanced.rst
+++ /dev/null
@@ -1,295 +0,0 @@
-=============================
-mac80211 subsystem (advanced)
-=============================
-
-Information contained within this part of the book is of interest only
-for advanced interaction of mac80211 with drivers to exploit more
-hardware capabilities and improve performance.
-
-LED support
-===========
-
-Mac80211 supports various ways of blinking LEDs. Wherever possible,
-device LEDs should be exposed as LED class devices and hooked up to the
-appropriate trigger, which will then be triggered appropriately by
-mac80211.
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_get_tx_led_name
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_get_rx_led_name
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_get_assoc_led_name
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_get_radio_led_name
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_tpt_blink
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_tpt_led_trigger_flags
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_create_tpt_led_trigger
-
-Hardware crypto acceleration
-============================
-
-.. kernel-doc:: include/net/mac80211.h
-   :doc: Hardware crypto acceleration
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: set_key_cmd
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_key_conf
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_key_flags
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_get_tkip_p1k
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_get_tkip_p1k_iv
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_get_tkip_p2k
-
-Powersave support
-=================
-
-.. kernel-doc:: include/net/mac80211.h
-   :doc: Powersave support
-
-Beacon filter support
-=====================
-
-.. kernel-doc:: include/net/mac80211.h
-   :doc: Beacon filter support
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_beacon_loss
-
-Multiple queues and QoS support
-===============================
-
-TBD
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_tx_queue_params
-
-Access point mode support
-=========================
-
-TBD
-
-Some parts of the if_conf should be discussed here instead
-
-Insert notes about VLAN interfaces with hw crypto here or in the hw
-crypto chapter.
-
-support for powersaving clients
--------------------------------
-
-.. kernel-doc:: include/net/mac80211.h
-   :doc: AP support for powersaving clients
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_get_buffered_bc
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_beacon_get
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_sta_eosp
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_frame_release_type
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_sta_ps_transition
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_sta_ps_transition_ni
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_sta_set_buffered
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_sta_block_awake
-
-Supporting multiple virtual interfaces
-======================================
-
-TBD
-
-Note: WDS with identical MAC address should almost always be OK
-
-Insert notes about having multiple virtual interfaces with different MAC
-addresses here, note which configurations are supported by mac80211, add
-notes about supporting hw crypto with it.
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_iterate_active_interfaces
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_iterate_active_interfaces_atomic
-
-Station handling
-================
-
-TODO
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_sta
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: sta_notify_cmd
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_find_sta
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_find_sta_by_ifaddr
-
-Hardware scan offload
-=====================
-
-TBD
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_scan_completed
-
-Aggregation
-===========
-
-TX A-MPDU aggregation
----------------------
-
-.. kernel-doc:: net/mac80211/agg-tx.c
-   :doc: TX A-MPDU aggregation
-
-.. WARNING: DOCPROC directive not supported: !Cnet/mac80211/agg-tx.c
-
-RX A-MPDU aggregation
----------------------
-
-.. kernel-doc:: net/mac80211/agg-rx.c
-   :doc: RX A-MPDU aggregation
-
-.. WARNING: DOCPROC directive not supported: !Cnet/mac80211/agg-rx.c
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_ampdu_mlme_action
-
-Spatial Multiplexing Powersave (SMPS)
-=====================================
-
-.. kernel-doc:: include/net/mac80211.h
-   :doc: Spatial multiplexing power save
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_request_smps
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_smps_mode
-
-TBD
-
-This part of the book describes the rate control algorithm interface and
-how it relates to mac80211 and drivers.
-
-Rate Control API
-================
-
-TBD
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_start_tx_ba_session
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_start_tx_ba_cb_irqsafe
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_stop_tx_ba_session
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_stop_tx_ba_cb_irqsafe
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_rate_control_changed
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_tx_rate_control
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: rate_control_send_low
-
-TBD
-
-This part of the book describes mac80211 internals.
-
-Key handling
-============
-
-Key handling basics
--------------------
-
-.. kernel-doc:: net/mac80211/key.c
-   :doc: Key handling basics
-
-MORE TBD
---------
-
-TBD
-
-Receive processing
-==================
-
-TBD
-
-Transmit processing
-===================
-
-TBD
-
-Station info handling
-=====================
-
-Programming information
------------------------
-
-.. kernel-doc:: net/mac80211/sta_info.h
-   :functions: sta_info
-
-.. kernel-doc:: net/mac80211/sta_info.h
-   :functions: ieee80211_sta_info_flags
-
-STA information lifetime rules
-------------------------------
-
-.. kernel-doc:: net/mac80211/sta_info.c
-   :doc: STA information lifetime rules
-
-Aggregation
-===========
-
-.. kernel-doc:: net/mac80211/sta_info.h
-   :functions: sta_ampdu_mlme
-
-.. kernel-doc:: net/mac80211/sta_info.h
-   :functions: tid_ampdu_tx
-
-.. kernel-doc:: net/mac80211/sta_info.h
-   :functions: tid_ampdu_rx
-
-Synchronisation
-===============
-
-TBD
-
-Locking, lots of RCU
diff --git a/Documentation/80211/mac80211.rst b/Documentation/80211/mac80211.rst
deleted file mode 100644
index 85a8335e80b6..000000000000
--- a/Documentation/80211/mac80211.rst
+++ /dev/null
@@ -1,216 +0,0 @@
-===========================
-mac80211 subsystem (basics)
-===========================
-
-You should read and understand the information contained within this
-part of the book while implementing a mac80211 driver. In some chapters,
-advanced usage is noted, those may be skipped if this isn't needed.
-
-This part of the book only covers station and monitor mode
-functionality, additional information required to implement the other
-modes is covered in the second part of the book.
-
-Basic hardware handling
-=======================
-
-TBD
-
-This chapter shall contain information on getting a hw struct allocated
-and registered with mac80211.
-
-Since it is required to allocate rates/modes before registering a hw
-struct, this chapter shall also contain information on setting up the
-rate/mode structs.
-
-Additionally, some discussion about the callbacks and the general
-programming model should be in here, including the definition of
-ieee80211_ops which will be referred to a lot.
-
-Finally, a discussion of hardware capabilities should be done with
-references to other parts of the book.
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_hw
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_hw_flags
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: SET_IEEE80211_DEV
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: SET_IEEE80211_PERM_ADDR
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_ops
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_alloc_hw
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_register_hw
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_unregister_hw
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_free_hw
-
-PHY configuration
-=================
-
-TBD
-
-This chapter should describe PHY handling including start/stop callbacks
-and the various structures used.
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_conf
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_conf_flags
-
-Virtual interfaces
-==================
-
-TBD
-
-This chapter should describe virtual interface basics that are relevant
-to the driver (VLANs, MGMT etc are not.) It should explain the use of
-the add_iface/remove_iface callbacks as well as the interface
-configuration callbacks.
-
-Things related to AP mode should be discussed there.
-
-Things related to supporting multiple interfaces should be in the
-appropriate chapter, a BIG FAT note should be here about this though and
-the recommendation to allow only a single interface in STA mode at
-first!
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_vif
-
-Receive and transmit processing
-===============================
-
-what should be here
--------------------
-
-TBD
-
-This should describe the receive and transmit paths in mac80211/the
-drivers as well as transmit status handling.
-
-Frame format
-------------
-
-.. kernel-doc:: include/net/mac80211.h
-   :doc: Frame format
-
-Packet alignment
-----------------
-
-.. kernel-doc:: net/mac80211/rx.c
-   :doc: Packet alignment
-
-Calling into mac80211 from interrupts
--------------------------------------
-
-.. kernel-doc:: include/net/mac80211.h
-   :doc: Calling mac80211 from interrupts
-
-functions/definitions
----------------------
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_rx_status
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: mac80211_rx_flags
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: mac80211_tx_info_flags
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: mac80211_tx_control_flags
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: mac80211_rate_control_flags
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_tx_rate
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_tx_info
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_tx_info_clear_status
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_rx
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_rx_ni
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_rx_irqsafe
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_tx_status
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_tx_status_ni
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_tx_status_irqsafe
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_rts_get
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_rts_duration
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_ctstoself_get
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_ctstoself_duration
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_generic_frame_duration
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_wake_queue
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_stop_queue
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_wake_queues
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_stop_queues
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_queue_stopped
-
-Frame filtering
-===============
-
-.. kernel-doc:: include/net/mac80211.h
-   :doc: Frame filtering
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_filter_flags
-
-The mac80211 workqueue
-======================
-
-.. kernel-doc:: include/net/mac80211.h
-   :doc: mac80211 workqueue
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_queue_work
-
-.. kernel-doc:: include/net/mac80211.h
-   :functions: ieee80211_queue_delayed_work
diff --git a/Documentation/driver-api/80211/cfg80211.rst b/Documentation/driver-api/80211/cfg80211.rst
new file mode 100644
index 000000000000..b1e149ea6fee
--- /dev/null
+++ b/Documentation/driver-api/80211/cfg80211.rst
@@ -0,0 +1,345 @@
+==================
+cfg80211 subsystem
+==================
+
+Device registration
+===================
+
+.. kernel-doc:: include/net/cfg80211.h
+   :doc: Device registration
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_channel_flags
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_channel
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_rate_flags
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_rate
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_sta_ht_cap
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_supported_band
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_signal_type
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: wiphy_params_flags
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: wiphy_flags
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: wiphy
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: wireless_dev
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: wiphy_new
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: wiphy_register
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: wiphy_unregister
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: wiphy_free
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: wiphy_name
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: wiphy_dev
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: wiphy_priv
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: priv_to_wiphy
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: set_wiphy_dev
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: wdev_priv
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_iface_limit
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_iface_combination
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_check_combinations
+
+Actions and configuration
+=========================
+
+.. kernel-doc:: include/net/cfg80211.h
+   :doc: Actions and configuration
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_ops
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: vif_params
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: key_params
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: survey_info_flags
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: survey_info
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_beacon_data
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_ap_settings
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: station_parameters
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: rate_info_flags
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: rate_info
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: station_info
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: monitor_flags
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: mpath_info_flags
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: mpath_info
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: bss_parameters
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_txq_params
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_crypto_settings
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_auth_request
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_assoc_request
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_deauth_request
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_disassoc_request
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_ibss_params
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_connect_params
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_pmksa
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_rx_mlme_mgmt
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_auth_timeout
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_rx_assoc_resp
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_assoc_timeout
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_tx_mlme_mgmt
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_ibss_joined
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_connect_result
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_connect_bss
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_connect_timeout
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_roamed
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_disconnected
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_ready_on_channel
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_remain_on_channel_expired
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_new_sta
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_rx_mgmt
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_mgmt_tx_status
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_cqm_rssi_notify
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_cqm_pktloss_notify
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_michael_mic_failure
+
+Scanning and BSS list handling
+==============================
+
+.. kernel-doc:: include/net/cfg80211.h
+   :doc: Scanning and BSS list handling
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_ssid
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_scan_request
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_scan_done
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_bss
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_inform_bss
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_inform_bss_frame_data
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_inform_bss_data
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_unlink_bss
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_find_ie
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_bss_get_ie
+
+Utility functions
+=================
+
+.. kernel-doc:: include/net/cfg80211.h
+   :doc: Utility functions
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_channel_to_frequency
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_frequency_to_channel
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_get_channel
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_get_response_rate
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_hdrlen
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_get_hdrlen_from_skb
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_radiotap_iterator
+
+Data path helpers
+=================
+
+.. kernel-doc:: include/net/cfg80211.h
+   :doc: Data path helpers
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_data_to_8023
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_data_from_8023
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: ieee80211_amsdu_to_8023s
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_classify8021d
+
+Regulatory enforcement infrastructure
+=====================================
+
+.. kernel-doc:: include/net/cfg80211.h
+   :doc: Regulatory enforcement infrastructure
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: regulatory_hint
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: wiphy_apply_custom_regulatory
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: freq_reg_info
+
+RFkill integration
+==================
+
+.. kernel-doc:: include/net/cfg80211.h
+   :doc: RFkill integration
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: wiphy_rfkill_set_hw_state
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: wiphy_rfkill_start_polling
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: wiphy_rfkill_stop_polling
+
+Test mode
+=========
+
+.. kernel-doc:: include/net/cfg80211.h
+   :doc: Test mode
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_testmode_alloc_reply_skb
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_testmode_reply
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_testmode_alloc_event_skb
+
+.. kernel-doc:: include/net/cfg80211.h
+   :functions: cfg80211_testmode_event
diff --git a/Documentation/driver-api/80211/conf.py b/Documentation/driver-api/80211/conf.py
new file mode 100644
index 000000000000..4424b4b0b9c3
--- /dev/null
+++ b/Documentation/driver-api/80211/conf.py
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = "Linux 802.11 Driver Developer's Guide"
+
+tags.add("subproject")
+
+latex_documents = [
+    ('index', '80211.tex', project,
+     'The kernel development community', 'manual'),
+]
diff --git a/Documentation/driver-api/80211/index.rst b/Documentation/driver-api/80211/index.rst
new file mode 100644
index 000000000000..af210859d3e1
--- /dev/null
+++ b/Documentation/driver-api/80211/index.rst
@@ -0,0 +1,17 @@
+=====================================
+Linux 802.11 Driver Developer's Guide
+=====================================
+
+.. toctree::
+
+   introduction
+   cfg80211
+   mac80211
+   mac80211-advanced
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/driver-api/80211/introduction.rst b/Documentation/driver-api/80211/introduction.rst
new file mode 100644
index 000000000000..4938fa87691c
--- /dev/null
+++ b/Documentation/driver-api/80211/introduction.rst
@@ -0,0 +1,17 @@
+============
+Introduction
+============
+
+Explaining wireless 802.11 networking in the Linux kernel
+
+Copyright 2007-2009 Johannes Berg
+
+These books attempt to give a description of the various subsystems
+that play a role in 802.11 wireless networking in Linux. Since these
+books are for kernel developers they attempts to document the
+structures and functions used in the kernel as well as giving a
+higher-level overview.
+
+The reader is expected to be familiar with the 802.11 standard as
+published by the IEEE in 802.11-2007 (or possibly later versions).
+References to this standard will be given as "802.11-2007 8.1.5".
diff --git a/Documentation/driver-api/80211/mac80211-advanced.rst b/Documentation/driver-api/80211/mac80211-advanced.rst
new file mode 100644
index 000000000000..70a89b2163c2
--- /dev/null
+++ b/Documentation/driver-api/80211/mac80211-advanced.rst
@@ -0,0 +1,295 @@
+=============================
+mac80211 subsystem (advanced)
+=============================
+
+Information contained within this part of the book is of interest only
+for advanced interaction of mac80211 with drivers to exploit more
+hardware capabilities and improve performance.
+
+LED support
+===========
+
+Mac80211 supports various ways of blinking LEDs. Wherever possible,
+device LEDs should be exposed as LED class devices and hooked up to the
+appropriate trigger, which will then be triggered appropriately by
+mac80211.
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_get_tx_led_name
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_get_rx_led_name
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_get_assoc_led_name
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_get_radio_led_name
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_tpt_blink
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_tpt_led_trigger_flags
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_create_tpt_led_trigger
+
+Hardware crypto acceleration
+============================
+
+.. kernel-doc:: include/net/mac80211.h
+   :doc: Hardware crypto acceleration
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: set_key_cmd
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_key_conf
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_key_flags
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_get_tkip_p1k
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_get_tkip_p1k_iv
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_get_tkip_p2k
+
+Powersave support
+=================
+
+.. kernel-doc:: include/net/mac80211.h
+   :doc: Powersave support
+
+Beacon filter support
+=====================
+
+.. kernel-doc:: include/net/mac80211.h
+   :doc: Beacon filter support
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_beacon_loss
+
+Multiple queues and QoS support
+===============================
+
+TBD
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_tx_queue_params
+
+Access point mode support
+=========================
+
+TBD
+
+Some parts of the if_conf should be discussed here instead
+
+Insert notes about VLAN interfaces with hw crypto here or in the hw
+crypto chapter.
+
+support for powersaving clients
+-------------------------------
+
+.. kernel-doc:: include/net/mac80211.h
+   :doc: AP support for powersaving clients
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_get_buffered_bc
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_beacon_get
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_sta_eosp
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_frame_release_type
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_sta_ps_transition
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_sta_ps_transition_ni
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_sta_set_buffered
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_sta_block_awake
+
+Supporting multiple virtual interfaces
+======================================
+
+TBD
+
+Note: WDS with identical MAC address should almost always be OK
+
+Insert notes about having multiple virtual interfaces with different MAC
+addresses here, note which configurations are supported by mac80211, add
+notes about supporting hw crypto with it.
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_iterate_active_interfaces
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_iterate_active_interfaces_atomic
+
+Station handling
+================
+
+TODO
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_sta
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: sta_notify_cmd
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_find_sta
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_find_sta_by_ifaddr
+
+Hardware scan offload
+=====================
+
+TBD
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_scan_completed
+
+Aggregation
+===========
+
+TX A-MPDU aggregation
+---------------------
+
+.. kernel-doc:: net/mac80211/agg-tx.c
+   :doc: TX A-MPDU aggregation
+
+.. WARNING: DOCPROC directive not supported: !Cnet/mac80211/agg-tx.c
+
+RX A-MPDU aggregation
+---------------------
+
+.. kernel-doc:: net/mac80211/agg-rx.c
+   :doc: RX A-MPDU aggregation
+
+.. WARNING: DOCPROC directive not supported: !Cnet/mac80211/agg-rx.c
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_ampdu_mlme_action
+
+Spatial Multiplexing Powersave (SMPS)
+=====================================
+
+.. kernel-doc:: include/net/mac80211.h
+   :doc: Spatial multiplexing power save
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_request_smps
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_smps_mode
+
+TBD
+
+This part of the book describes the rate control algorithm interface and
+how it relates to mac80211 and drivers.
+
+Rate Control API
+================
+
+TBD
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_start_tx_ba_session
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_start_tx_ba_cb_irqsafe
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_stop_tx_ba_session
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_stop_tx_ba_cb_irqsafe
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_rate_control_changed
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_tx_rate_control
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: rate_control_send_low
+
+TBD
+
+This part of the book describes mac80211 internals.
+
+Key handling
+============
+
+Key handling basics
+-------------------
+
+.. kernel-doc:: net/mac80211/key.c
+   :doc: Key handling basics
+
+MORE TBD
+--------
+
+TBD
+
+Receive processing
+==================
+
+TBD
+
+Transmit processing
+===================
+
+TBD
+
+Station info handling
+=====================
+
+Programming information
+-----------------------
+
+.. kernel-doc:: net/mac80211/sta_info.h
+   :functions: sta_info
+
+.. kernel-doc:: net/mac80211/sta_info.h
+   :functions: ieee80211_sta_info_flags
+
+STA information lifetime rules
+------------------------------
+
+.. kernel-doc:: net/mac80211/sta_info.c
+   :doc: STA information lifetime rules
+
+Aggregation
+===========
+
+.. kernel-doc:: net/mac80211/sta_info.h
+   :functions: sta_ampdu_mlme
+
+.. kernel-doc:: net/mac80211/sta_info.h
+   :functions: tid_ampdu_tx
+
+.. kernel-doc:: net/mac80211/sta_info.h
+   :functions: tid_ampdu_rx
+
+Synchronisation
+===============
+
+TBD
+
+Locking, lots of RCU
diff --git a/Documentation/driver-api/80211/mac80211.rst b/Documentation/driver-api/80211/mac80211.rst
new file mode 100644
index 000000000000..85a8335e80b6
--- /dev/null
+++ b/Documentation/driver-api/80211/mac80211.rst
@@ -0,0 +1,216 @@
+===========================
+mac80211 subsystem (basics)
+===========================
+
+You should read and understand the information contained within this
+part of the book while implementing a mac80211 driver. In some chapters,
+advanced usage is noted, those may be skipped if this isn't needed.
+
+This part of the book only covers station and monitor mode
+functionality, additional information required to implement the other
+modes is covered in the second part of the book.
+
+Basic hardware handling
+=======================
+
+TBD
+
+This chapter shall contain information on getting a hw struct allocated
+and registered with mac80211.
+
+Since it is required to allocate rates/modes before registering a hw
+struct, this chapter shall also contain information on setting up the
+rate/mode structs.
+
+Additionally, some discussion about the callbacks and the general
+programming model should be in here, including the definition of
+ieee80211_ops which will be referred to a lot.
+
+Finally, a discussion of hardware capabilities should be done with
+references to other parts of the book.
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_hw
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_hw_flags
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: SET_IEEE80211_DEV
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: SET_IEEE80211_PERM_ADDR
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_ops
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_alloc_hw
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_register_hw
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_unregister_hw
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_free_hw
+
+PHY configuration
+=================
+
+TBD
+
+This chapter should describe PHY handling including start/stop callbacks
+and the various structures used.
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_conf
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_conf_flags
+
+Virtual interfaces
+==================
+
+TBD
+
+This chapter should describe virtual interface basics that are relevant
+to the driver (VLANs, MGMT etc are not.) It should explain the use of
+the add_iface/remove_iface callbacks as well as the interface
+configuration callbacks.
+
+Things related to AP mode should be discussed there.
+
+Things related to supporting multiple interfaces should be in the
+appropriate chapter, a BIG FAT note should be here about this though and
+the recommendation to allow only a single interface in STA mode at
+first!
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_vif
+
+Receive and transmit processing
+===============================
+
+what should be here
+-------------------
+
+TBD
+
+This should describe the receive and transmit paths in mac80211/the
+drivers as well as transmit status handling.
+
+Frame format
+------------
+
+.. kernel-doc:: include/net/mac80211.h
+   :doc: Frame format
+
+Packet alignment
+----------------
+
+.. kernel-doc:: net/mac80211/rx.c
+   :doc: Packet alignment
+
+Calling into mac80211 from interrupts
+-------------------------------------
+
+.. kernel-doc:: include/net/mac80211.h
+   :doc: Calling mac80211 from interrupts
+
+functions/definitions
+---------------------
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_rx_status
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: mac80211_rx_flags
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: mac80211_tx_info_flags
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: mac80211_tx_control_flags
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: mac80211_rate_control_flags
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_tx_rate
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_tx_info
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_tx_info_clear_status
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_rx
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_rx_ni
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_rx_irqsafe
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_tx_status
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_tx_status_ni
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_tx_status_irqsafe
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_rts_get
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_rts_duration
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_ctstoself_get
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_ctstoself_duration
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_generic_frame_duration
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_wake_queue
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_stop_queue
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_wake_queues
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_stop_queues
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_queue_stopped
+
+Frame filtering
+===============
+
+.. kernel-doc:: include/net/mac80211.h
+   :doc: Frame filtering
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_filter_flags
+
+The mac80211 workqueue
+======================
+
+.. kernel-doc:: include/net/mac80211.h
+   :doc: mac80211 workqueue
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_queue_work
+
+.. kernel-doc:: include/net/mac80211.h
+   :functions: ieee80211_queue_delayed_work
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 743828ead665..0dec394b9038 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -26,7 +26,7 @@ available subsections can be seen below.
    hsi
    miscellaneous
    vme
-
+   80211/index
 
 .. only::  subproject and html
 
diff --git a/Documentation/index.rst b/Documentation/index.rst
index bf3eb3ad6ad5..2bd8fdc9207c 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -56,7 +56,6 @@ needed).
    core-api/index
    media/index
    gpu/index
-   80211/index
    security/index
    sound/index
 
-- 
cgit v1.2.3


From 93dc3a112bf8e5f97e3d9744595934ff31708764 Mon Sep 17 00:00:00 2001
From: Jonathan Corbet 
Date: Fri, 18 Nov 2016 17:06:13 -0700
Subject: doc: Convert the debugobjects DocBook template to sphinx

A couple of the most minor heading tweaks, otherwise no changes to the text
itself beyond the mechanical conversion.

Note that the inclusion of the kerneldoc comments from the source has never
worked, since exported symbols were asked for and none of those functions
are exported to modules.  It doesn't work here either :)

Cc: Thomas Gleixner 
Signed-off-by: Jonathan Corbet 
---
 Documentation/DocBook/Makefile           |   2 +-
 Documentation/DocBook/debugobjects.tmpl  | 443 -------------------------------
 Documentation/core-api/debug-objects.rst | 314 ++++++++++++++++++++++
 Documentation/core-api/index.rst         |  16 +-
 4 files changed, 329 insertions(+), 446 deletions(-)
 delete mode 100644 Documentation/DocBook/debugobjects.tmpl
 create mode 100644 Documentation/core-api/debug-objects.rst

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index c8bd257660eb..bc6278d18090 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -12,7 +12,7 @@ DOCBOOKS := z8530book.xml  \
 	    kernel-api.xml filesystems.xml lsm.xml kgdb.xml \
 	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
 	    genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
-	    80211.xml debugobjects.xml sh.xml regulator.xml \
+	    80211.xml sh.xml regulator.xml \
 	    tracepoint.xml w1.xml \
 	    writing_musb_glue_layer.xml crypto-API.xml iio.xml
 
diff --git a/Documentation/DocBook/debugobjects.tmpl b/Documentation/DocBook/debugobjects.tmpl
deleted file mode 100644
index 7e4f34fde697..000000000000
--- a/Documentation/DocBook/debugobjects.tmpl
+++ /dev/null
@@ -1,443 +0,0 @@
-
-
-
-
- 
-  Debug objects life time
-
-  
-   
-    Thomas
-    Gleixner
-    
-     

-      tglx@linutronix.de
-     

-    
-   
-  
-
-  
-   2008
-   Thomas Gleixner
-  
-
-  
-   
-     This documentation is free software; you can redistribute
-     it and/or modify it under the terms of the GNU General Public
-     License version 2 as published by the Free Software Foundation.
-   
-
-   
-     This program is distributed in the hope that it will be
-     useful, but WITHOUT ANY WARRANTY; without even the implied
-     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-     See the GNU General Public License for more details.
-   
-
-   
-     You should have received a copy of the GNU General Public
-     License along with this program; if not, write to the Free
-     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
-     MA 02111-1307 USA
-   
-
-   
-     For more details see the file COPYING in the source
-     distribution of Linux.
-   
-  
- 
-
-
-
-  
-    Introduction
-    
-      debugobjects is a generic infrastructure to track the life time
-      of kernel objects and validate the operations on those.
-    
-    
-      debugobjects is useful to check for the following error patterns:
-	
-	  Activation of uninitialized objects
-	  Initialization of active objects
-	  Usage of freed/destroyed objects
-	
-    
-    
-      debugobjects is not changing the data structure of the real
-      object so it can be compiled in with a minimal runtime impact
-      and enabled on demand with a kernel command line option.
-    
-  
-
-  
-    Howto use debugobjects
-    
-      A kernel subsystem needs to provide a data structure which
-      describes the object type and add calls into the debug code at
-      appropriate places. The data structure to describe the object
-      type needs at minimum the name of the object type. Optional
-      functions can and should be provided to fixup detected problems
-      so the kernel can continue to work and the debug information can
-      be retrieved from a live system instead of hard core debugging
-      with serial consoles and stack trace transcripts from the
-      monitor.
-    
-    
-      The debug calls provided by debugobjects are:
-      
-	debug_object_init
-	debug_object_init_on_stack
-	debug_object_activate
-	debug_object_deactivate
-	debug_object_destroy
-	debug_object_free
-	debug_object_assert_init
-      
-      Each of these functions takes the address of the real object and
-      a pointer to the object type specific debug description
-      structure.
-    
-    
-      Each detected error is reported in the statistics and a limited
-      number of errors are printk'ed including a full stack trace.
-    
-    
-      The statistics are available via /sys/kernel/debug/debug_objects/stats.
-      They provide information about the number of warnings and the
-      number of successful fixups along with information about the
-      usage of the internal tracking objects and the state of the
-      internal tracking objects pool.
-    
-  
-  
-    Debug functions
-    
-      Debug object function reference
-!Elib/debugobjects.c
-    
-    
-      debug_object_init
-      
-	This function is called whenever the initialization function
-	of a real object is called.
-      
-      
-	When the real object is already tracked by debugobjects it is
-	checked, whether the object can be initialized.  Initializing
-	is not allowed for active and destroyed objects. When
-	debugobjects detects an error, then it calls the fixup_init
-	function of the object type description structure if provided
-	by the caller. The fixup function can correct the problem
-	before the real initialization of the object happens. E.g. it
-	can deactivate an active object in order to prevent damage to
-	the subsystem.
-      
-      
-	When the real object is not yet tracked by debugobjects,
-	debugobjects allocates a tracker object for the real object
-	and sets the tracker object state to ODEBUG_STATE_INIT. It
-	verifies that the object is not on the callers stack. If it is
-	on the callers stack then a limited number of warnings
-	including a full stack trace is printk'ed. The calling code
-	must use debug_object_init_on_stack() and remove the object
-	before leaving the function which allocated it. See next
-	section.
-      
-    
-
-    
-      debug_object_init_on_stack
-      
-	This function is called whenever the initialization function
-	of a real object which resides on the stack is called.
-      
-      
-	When the real object is already tracked by debugobjects it is
-	checked, whether the object can be initialized. Initializing
-	is not allowed for active and destroyed objects. When
-	debugobjects detects an error, then it calls the fixup_init
-	function of the object type description structure if provided
-	by the caller. The fixup function can correct the problem
-	before the real initialization of the object happens. E.g. it
-	can deactivate an active object in order to prevent damage to
-	the subsystem.
-      
-      
-	When the real object is not yet tracked by debugobjects
-	debugobjects allocates a tracker object for the real object
-	and sets the tracker object state to ODEBUG_STATE_INIT. It
-	verifies that the object is on the callers stack.
-      
-      
-	An object which is on the stack must be removed from the
-	tracker by calling debug_object_free() before the function
-	which allocates the object returns. Otherwise we keep track of
-	stale objects.
-      
-    
-
-    
-      debug_object_activate
-      
-	This function is called whenever the activation function of a
-	real object is called.
-      
-      
-	When the real object is already tracked by debugobjects it is
-	checked, whether the object can be activated.  Activating is
-	not allowed for active and destroyed objects. When
-	debugobjects detects an error, then it calls the
-	fixup_activate function of the object type description
-	structure if provided by the caller. The fixup function can
-	correct the problem before the real activation of the object
-	happens. E.g. it can deactivate an active object in order to
-	prevent damage to the subsystem.
-      
-      
-	When the real object is not yet tracked by debugobjects then
-	the fixup_activate function is called if available. This is
-	necessary to allow the legitimate activation of statically
-	allocated and initialized objects. The fixup function checks
-	whether the object is valid and calls the debug_objects_init()
-	function to initialize the tracking of this object.
-      
-      
-	When the activation is legitimate, then the state of the
-	associated tracker object is set to ODEBUG_STATE_ACTIVE.
-      
-    
-
-    
-      debug_object_deactivate
-      
-	This function is called whenever the deactivation function of
-	a real object is called.
-      
-      
-	When the real object is tracked by debugobjects it is checked,
-	whether the object can be deactivated. Deactivating is not
-	allowed for untracked or destroyed objects.
-      
-      
-	When the deactivation is legitimate, then the state of the
-	associated tracker object is set to ODEBUG_STATE_INACTIVE.
-      
-    
-
-    
-      debug_object_destroy
-      
-	This function is called to mark an object destroyed. This is
-	useful to prevent the usage of invalid objects, which are
-	still available in memory: either statically allocated objects
-	or objects which are freed later.
-      
-      
-	When the real object is tracked by debugobjects it is checked,
-	whether the object can be destroyed. Destruction is not
-	allowed for active and destroyed objects. When debugobjects
-	detects an error, then it calls the fixup_destroy function of
-	the object type description structure if provided by the
-	caller. The fixup function can correct the problem before the
-	real destruction of the object happens. E.g. it can deactivate
-	an active object in order to prevent damage to the subsystem.
-      
-      
-	When the destruction is legitimate, then the state of the
-	associated tracker object is set to ODEBUG_STATE_DESTROYED.
-      
-    
-
-    
-      debug_object_free
-      
-	This function is called before an object is freed.
-      
-      
-	When the real object is tracked by debugobjects it is checked,
-	whether the object can be freed. Free is not allowed for
-	active objects. When debugobjects detects an error, then it
-	calls the fixup_free function of the object type description
-	structure if provided by the caller. The fixup function can
-	correct the problem before the real free of the object
-	happens. E.g. it can deactivate an active object in order to
-	prevent damage to the subsystem.
-      
-      
-	Note that debug_object_free removes the object from the
-	tracker. Later usage of the object is detected by the other
-	debug checks.
-      
-    
-
-    
-      debug_object_assert_init
-      
-	This function is called to assert that an object has been
-	initialized.
-      
-      
-	When the real object is not tracked by debugobjects, it calls
-	fixup_assert_init of the object type description structure
-	provided by the caller, with the hardcoded object state
-	ODEBUG_NOT_AVAILABLE. The fixup function can correct the problem
-	by calling debug_object_init and other specific initializing
-	functions.
-      
-      
-	When the real object is already tracked by debugobjects it is
-	ignored.
-      
-    
-  
-  
-    Fixup functions
-    
-      Debug object type description structure
-!Iinclude/linux/debugobjects.h
-    
-    
-      fixup_init
-      
-	This function is called from the debug code whenever a problem
-	in debug_object_init is detected. The function takes the
-	address of the object and the state which is currently
-	recorded in the tracker.
-      
-      
-	Called from debug_object_init when the object state is:
-	
-	  ODEBUG_STATE_ACTIVE
-	
-      
-      
-	The function returns true when the fixup was successful,
-	otherwise false. The return value is used to update the
-	statistics.
-      
-      
-	Note, that the function needs to call the debug_object_init()
-	function again, after the damage has been repaired in order to
-	keep the state consistent.
-      
-    
-
-    
-      fixup_activate
-      
-	This function is called from the debug code whenever a problem
-	in debug_object_activate is detected.
-      
-      
-	Called from debug_object_activate when the object state is:
-	
-	  ODEBUG_STATE_NOTAVAILABLE
-	  ODEBUG_STATE_ACTIVE
-	
-      
-      
-	The function returns true when the fixup was successful,
-	otherwise false. The return value is used to update the
-	statistics.
-      
-      
-	Note that the function needs to call the debug_object_activate()
-	function again after the damage has been repaired in order to
-	keep the state consistent.
-      
-      
-	The activation of statically initialized objects is a special
-	case. When debug_object_activate() has no tracked object for
-	this object address then fixup_activate() is called with
-	object state ODEBUG_STATE_NOTAVAILABLE. The fixup function
-	needs to check whether this is a legitimate case of a
-	statically initialized object or not. In case it is it calls
-	debug_object_init() and debug_object_activate() to make the
-	object known to the tracker and marked active. In this case
-	the function should return false because this is not a real
-	fixup.
-      
-    
-
-    
-      fixup_destroy
-      
-	This function is called from the debug code whenever a problem
-	in debug_object_destroy is detected.
-      
-      
-	Called from debug_object_destroy when the object state is:
-	
-	  ODEBUG_STATE_ACTIVE
-	
-      
-      
-	The function returns true when the fixup was successful,
-	otherwise false. The return value is used to update the
-	statistics.
-      
-    
-    
-      fixup_free
-      
-	This function is called from the debug code whenever a problem
-	in debug_object_free is detected. Further it can be called
-	from the debug checks in kfree/vfree, when an active object is
-	detected from the debug_check_no_obj_freed() sanity checks.
-      
-      
-	Called from debug_object_free() or debug_check_no_obj_freed()
-	when the object state is:
-	
-	  ODEBUG_STATE_ACTIVE
-	
-      
-      
-	The function returns true when the fixup was successful,
-	otherwise false. The return value is used to update the
-	statistics.
-      
-    
-    
-      fixup_assert_init
-      
-	This function is called from the debug code whenever a problem
-	in debug_object_assert_init is detected.
-      
-      
-	Called from debug_object_assert_init() with a hardcoded state
-	ODEBUG_STATE_NOTAVAILABLE when the object is not found in the
-	debug bucket.
-      
-      
-	The function returns true when the fixup was successful,
-	otherwise false. The return value is used to update the
-	statistics.
-      
-      
-	Note, this function should make sure debug_object_init() is
-	called before returning.
-      
-      
-	The handling of statically initialized objects is a special
-	case. The fixup function should check if this is a legitimate
-	case of a statically initialized object or not. In this case only
-	debug_object_init() should be called to make the object known to
-	the tracker. Then the function should return false because this
-	is not
-	a real fixup.
-      
-    
-  
-  
-    Known Bugs And Assumptions
-    
-	None (knock on wood).
-    
-  
-
diff --git a/Documentation/core-api/debug-objects.rst b/Documentation/core-api/debug-objects.rst
new file mode 100644
index 000000000000..50a9707addfe
--- /dev/null
+++ b/Documentation/core-api/debug-objects.rst
@@ -0,0 +1,314 @@
+============================================
+The object-lifetime debugging infrastructure
+============================================
+
+:Author: Thomas Gleixner
+
+Introduction
+============
+
+debugobjects is a generic infrastructure to track the life time of
+kernel objects and validate the operations on those.
+
+debugobjects is useful to check for the following error patterns:
+
+-  Activation of uninitialized objects
+
+-  Initialization of active objects
+
+-  Usage of freed/destroyed objects
+
+debugobjects is not changing the data structure of the real object so it
+can be compiled in with a minimal runtime impact and enabled on demand
+with a kernel command line option.
+
+Howto use debugobjects
+======================
+
+A kernel subsystem needs to provide a data structure which describes the
+object type and add calls into the debug code at appropriate places. The
+data structure to describe the object type needs at minimum the name of
+the object type. Optional functions can and should be provided to fixup
+detected problems so the kernel can continue to work and the debug
+information can be retrieved from a live system instead of hard core
+debugging with serial consoles and stack trace transcripts from the
+monitor.
+
+The debug calls provided by debugobjects are:
+
+-  debug_object_init
+
+-  debug_object_init_on_stack
+
+-  debug_object_activate
+
+-  debug_object_deactivate
+
+-  debug_object_destroy
+
+-  debug_object_free
+
+-  debug_object_assert_init
+
+Each of these functions takes the address of the real object and a
+pointer to the object type specific debug description structure.
+
+Each detected error is reported in the statistics and a limited number
+of errors are printk'ed including a full stack trace.
+
+The statistics are available via /sys/kernel/debug/debug_objects/stats.
+They provide information about the number of warnings and the number of
+successful fixups along with information about the usage of the internal
+tracking objects and the state of the internal tracking objects pool.
+
+Debug functions
+===============
+
+Debug object function reference
+-------------------------------
+
+.. kernel-doc:: lib/debugobjects.c
+   :export:
+
+debug_object_init
+-------------------
+
+This function is called whenever the initialization function of a real
+object is called.
+
+When the real object is already tracked by debugobjects it is checked,
+whether the object can be initialized. Initializing is not allowed for
+active and destroyed objects. When debugobjects detects an error, then
+it calls the fixup_init function of the object type description
+structure if provided by the caller. The fixup function can correct the
+problem before the real initialization of the object happens. E.g. it
+can deactivate an active object in order to prevent damage to the
+subsystem.
+
+When the real object is not yet tracked by debugobjects, debugobjects
+allocates a tracker object for the real object and sets the tracker
+object state to ODEBUG_STATE_INIT. It verifies that the object is not
+on the callers stack. If it is on the callers stack then a limited
+number of warnings including a full stack trace is printk'ed. The
+calling code must use debug_object_init_on_stack() and remove the
+object before leaving the function which allocated it. See next section.
+
+debug_object_init_on_stack
+------------------------------
+
+This function is called whenever the initialization function of a real
+object which resides on the stack is called.
+
+When the real object is already tracked by debugobjects it is checked,
+whether the object can be initialized. Initializing is not allowed for
+active and destroyed objects. When debugobjects detects an error, then
+it calls the fixup_init function of the object type description
+structure if provided by the caller. The fixup function can correct the
+problem before the real initialization of the object happens. E.g. it
+can deactivate an active object in order to prevent damage to the
+subsystem.
+
+When the real object is not yet tracked by debugobjects debugobjects
+allocates a tracker object for the real object and sets the tracker
+object state to ODEBUG_STATE_INIT. It verifies that the object is on
+the callers stack.
+
+An object which is on the stack must be removed from the tracker by
+calling debug_object_free() before the function which allocates the
+object returns. Otherwise we keep track of stale objects.
+
+debug_object_activate
+-----------------------
+
+This function is called whenever the activation function of a real
+object is called.
+
+When the real object is already tracked by debugobjects it is checked,
+whether the object can be activated. Activating is not allowed for
+active and destroyed objects. When debugobjects detects an error, then
+it calls the fixup_activate function of the object type description
+structure if provided by the caller. The fixup function can correct the
+problem before the real activation of the object happens. E.g. it can
+deactivate an active object in order to prevent damage to the subsystem.
+
+When the real object is not yet tracked by debugobjects then the
+fixup_activate function is called if available. This is necessary to
+allow the legitimate activation of statically allocated and initialized
+objects. The fixup function checks whether the object is valid and calls
+the debug_objects_init() function to initialize the tracking of this
+object.
+
+When the activation is legitimate, then the state of the associated
+tracker object is set to ODEBUG_STATE_ACTIVE.
+
+debug_object_deactivate
+-------------------------
+
+This function is called whenever the deactivation function of a real
+object is called.
+
+When the real object is tracked by debugobjects it is checked, whether
+the object can be deactivated. Deactivating is not allowed for untracked
+or destroyed objects.
+
+When the deactivation is legitimate, then the state of the associated
+tracker object is set to ODEBUG_STATE_INACTIVE.
+
+debug_object_destroy
+----------------------
+
+This function is called to mark an object destroyed. This is useful to
+prevent the usage of invalid objects, which are still available in
+memory: either statically allocated objects or objects which are freed
+later.
+
+When the real object is tracked by debugobjects it is checked, whether
+the object can be destroyed. Destruction is not allowed for active and
+destroyed objects. When debugobjects detects an error, then it calls the
+fixup_destroy function of the object type description structure if
+provided by the caller. The fixup function can correct the problem
+before the real destruction of the object happens. E.g. it can
+deactivate an active object in order to prevent damage to the subsystem.
+
+When the destruction is legitimate, then the state of the associated
+tracker object is set to ODEBUG_STATE_DESTROYED.
+
+debug_object_free
+-------------------
+
+This function is called before an object is freed.
+
+When the real object is tracked by debugobjects it is checked, whether
+the object can be freed. Free is not allowed for active objects. When
+debugobjects detects an error, then it calls the fixup_free function of
+the object type description structure if provided by the caller. The
+fixup function can correct the problem before the real free of the
+object happens. E.g. it can deactivate an active object in order to
+prevent damage to the subsystem.
+
+Note that debug_object_free removes the object from the tracker. Later
+usage of the object is detected by the other debug checks.
+
+debug_object_assert_init
+---------------------------
+
+This function is called to assert that an object has been initialized.
+
+When the real object is not tracked by debugobjects, it calls
+fixup_assert_init of the object type description structure provided by
+the caller, with the hardcoded object state ODEBUG_NOT_AVAILABLE. The
+fixup function can correct the problem by calling debug_object_init
+and other specific initializing functions.
+
+When the real object is already tracked by debugobjects it is ignored.
+
+Fixup functions
+===============
+
+Debug object type description structure
+---------------------------------------
+
+.. kernel-doc:: include/linux/debugobjects.h
+   :internal:
+
+fixup_init
+-----------
+
+This function is called from the debug code whenever a problem in
+debug_object_init is detected. The function takes the address of the
+object and the state which is currently recorded in the tracker.
+
+Called from debug_object_init when the object state is:
+
+-  ODEBUG_STATE_ACTIVE
+
+The function returns true when the fixup was successful, otherwise
+false. The return value is used to update the statistics.
+
+Note, that the function needs to call the debug_object_init() function
+again, after the damage has been repaired in order to keep the state
+consistent.
+
+fixup_activate
+---------------
+
+This function is called from the debug code whenever a problem in
+debug_object_activate is detected.
+
+Called from debug_object_activate when the object state is:
+
+-  ODEBUG_STATE_NOTAVAILABLE
+
+-  ODEBUG_STATE_ACTIVE
+
+The function returns true when the fixup was successful, otherwise
+false. The return value is used to update the statistics.
+
+Note that the function needs to call the debug_object_activate()
+function again after the damage has been repaired in order to keep the
+state consistent.
+
+The activation of statically initialized objects is a special case. When
+debug_object_activate() has no tracked object for this object address
+then fixup_activate() is called with object state
+ODEBUG_STATE_NOTAVAILABLE. The fixup function needs to check whether
+this is a legitimate case of a statically initialized object or not. In
+case it is it calls debug_object_init() and debug_object_activate()
+to make the object known to the tracker and marked active. In this case
+the function should return false because this is not a real fixup.
+
+fixup_destroy
+--------------
+
+This function is called from the debug code whenever a problem in
+debug_object_destroy is detected.
+
+Called from debug_object_destroy when the object state is:
+
+-  ODEBUG_STATE_ACTIVE
+
+The function returns true when the fixup was successful, otherwise
+false. The return value is used to update the statistics.
+
+fixup_free
+-----------
+
+This function is called from the debug code whenever a problem in
+debug_object_free is detected. Further it can be called from the debug
+checks in kfree/vfree, when an active object is detected from the
+debug_check_no_obj_freed() sanity checks.
+
+Called from debug_object_free() or debug_check_no_obj_freed() when
+the object state is:
+
+-  ODEBUG_STATE_ACTIVE
+
+The function returns true when the fixup was successful, otherwise
+false. The return value is used to update the statistics.
+
+fixup_assert_init
+-------------------
+
+This function is called from the debug code whenever a problem in
+debug_object_assert_init is detected.
+
+Called from debug_object_assert_init() with a hardcoded state
+ODEBUG_STATE_NOTAVAILABLE when the object is not found in the debug
+bucket.
+
+The function returns true when the fixup was successful, otherwise
+false. The return value is used to update the statistics.
+
+Note, this function should make sure debug_object_init() is called
+before returning.
+
+The handling of statically initialized objects is a special case. The
+fixup function should check if this is a legitimate case of a statically
+initialized object or not. In this case only debug_object_init()
+should be called to make the object known to the tracker. Then the
+function should return false because this is not a real fixup.
+
+Known Bugs And Assumptions
+==========================
+
+None (knock on wood).
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index f7ef7fda5763..c3a1402da0cd 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -1,14 +1,26 @@
 ======================
-Core-API Documentation
+Core API Documentation
 ======================
 
-Kernel and driver related documentation.
+This is the beginning of a manual for core kernel APIs.  The conversion
+(and writing!) of documents for this manual is much appreciated!
+
+Core utilities
+==============
 
 .. toctree::
    :maxdepth: 1
 
    workqueue
 
+Interfaces for kernel debugging
+===============================
+
+.. toctree::
+   :maxdepth: 1
+
+   debug-objects	      
+
 .. only::  subproject
 
    Indices
-- 
cgit v1.2.3


From 8da3dc53347205b0d32ded4ab9c96dcf336061d8 Mon Sep 17 00:00:00 2001
From: Jonathan Corbet 
Date: Fri, 18 Nov 2016 17:17:11 -0700
Subject: doc: debugobjects: actually pull in the kerneldoc comments

Add the appropriate markup to get the kerneldoc comments out of
lib/debugobjects.c that have never seen the light of day until now.

A logical next step, left for the reader at the moment, is to move the
function descriptions *out* of debug-objects.rst and into the kerneldoc
comments themselves.

Signed-off-by: Jonathan Corbet 
---
 Documentation/core-api/debug-objects.rst | 34 ++++++++++++++------------------
 1 file changed, 15 insertions(+), 19 deletions(-)

diff --git a/Documentation/core-api/debug-objects.rst b/Documentation/core-api/debug-objects.rst
index 50a9707addfe..ac926fd55a64 100644
--- a/Documentation/core-api/debug-objects.rst
+++ b/Documentation/core-api/debug-objects.rst
@@ -64,14 +64,8 @@ tracking objects and the state of the internal tracking objects pool.
 Debug functions
 ===============
 
-Debug object function reference
--------------------------------
-
 .. kernel-doc:: lib/debugobjects.c
-   :export:
-
-debug_object_init
--------------------
+   :functions: debug_object_init
 
 This function is called whenever the initialization function of a real
 object is called.
@@ -93,8 +87,8 @@ number of warnings including a full stack trace is printk'ed. The
 calling code must use debug_object_init_on_stack() and remove the
 object before leaving the function which allocated it. See next section.
 
-debug_object_init_on_stack
-------------------------------
+.. kernel-doc:: lib/debugobjects.c
+   :functions: debug_object_init_on_stack
 
 This function is called whenever the initialization function of a real
 object which resides on the stack is called.
@@ -117,8 +111,8 @@ An object which is on the stack must be removed from the tracker by
 calling debug_object_free() before the function which allocates the
 object returns. Otherwise we keep track of stale objects.
 
-debug_object_activate
------------------------
+.. kernel-doc:: lib/debugobjects.c
+   :functions: debug_object_activate
 
 This function is called whenever the activation function of a real
 object is called.
@@ -141,8 +135,9 @@ object.
 When the activation is legitimate, then the state of the associated
 tracker object is set to ODEBUG_STATE_ACTIVE.
 
-debug_object_deactivate
--------------------------
+
+.. kernel-doc:: lib/debugobjects.c
+   :functions: debug_object_deactivate
 
 This function is called whenever the deactivation function of a real
 object is called.
@@ -154,8 +149,8 @@ or destroyed objects.
 When the deactivation is legitimate, then the state of the associated
 tracker object is set to ODEBUG_STATE_INACTIVE.
 
-debug_object_destroy
-----------------------
+.. kernel-doc:: lib/debugobjects.c
+   :functions: debug_object_destroy
 
 This function is called to mark an object destroyed. This is useful to
 prevent the usage of invalid objects, which are still available in
@@ -173,8 +168,8 @@ deactivate an active object in order to prevent damage to the subsystem.
 When the destruction is legitimate, then the state of the associated
 tracker object is set to ODEBUG_STATE_DESTROYED.
 
-debug_object_free
--------------------
+.. kernel-doc:: lib/debugobjects.c
+   :functions: debug_object_free
 
 This function is called before an object is freed.
 
@@ -189,8 +184,9 @@ prevent damage to the subsystem.
 Note that debug_object_free removes the object from the tracker. Later
 usage of the object is detected by the other debug checks.
 
-debug_object_assert_init
----------------------------
+
+.. kernel-doc:: lib/debugobjects.c
+   :functions: debug_object_assert_init
 
 This function is called to assert that an object has been initialized.
 
-- 
cgit v1.2.3


From d6ba7a9c8b5a6a42e8f7a7efd8345122611b535c Mon Sep 17 00:00:00 2001
From: Jonathan Corbet 
Date: Fri, 18 Nov 2016 17:21:32 -0700
Subject: doc: Sphinxify the tracepoint docbook

Convert the tracepoint docbook template to RST and add it to the core-api
manual.  No changes to the actual text beyond the mechanical formatting
conversion.

Cc: Jason Baron 
Cc: William Cohen 
Signed-off-by: Jonathan Corbet 
---
 Documentation/DocBook/Makefile        |   3 +-
 Documentation/DocBook/tracepoint.tmpl | 112 ----------------------------------
 Documentation/core-api/index.rst      |   3 +-
 Documentation/core-api/tracepoint.rst |  55 +++++++++++++++++
 4 files changed, 58 insertions(+), 115 deletions(-)
 delete mode 100644 Documentation/DocBook/tracepoint.tmpl
 create mode 100644 Documentation/core-api/tracepoint.rst

diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
index bc6278d18090..caab9039362f 100644
--- a/Documentation/DocBook/Makefile
+++ b/Documentation/DocBook/Makefile
@@ -12,8 +12,7 @@ DOCBOOKS := z8530book.xml  \
 	    kernel-api.xml filesystems.xml lsm.xml kgdb.xml \
 	    gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
 	    genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
-	    80211.xml sh.xml regulator.xml \
-	    tracepoint.xml w1.xml \
+	    80211.xml sh.xml regulator.xml w1.xml \
 	    writing_musb_glue_layer.xml crypto-API.xml iio.xml
 
 ifeq ($(DOCBOOKS),)
diff --git a/Documentation/DocBook/tracepoint.tmpl b/Documentation/DocBook/tracepoint.tmpl
deleted file mode 100644
index b57a9ede3224..000000000000
--- a/Documentation/DocBook/tracepoint.tmpl
+++ /dev/null
@@ -1,112 +0,0 @@
-
-
-
-
- 
-  The Linux Kernel Tracepoint API
-
-  
-   
-    Jason
-    Baron
-    
-     

-      jbaron@redhat.com
-     

-    
-   
-   
-    William
-    Cohen
-    
-     

-      wcohen@redhat.com
-     

-    
-   
-  
-
-  
-   
-     This documentation is free software; you can redistribute
-     it and/or modify it under the terms of the GNU General Public
-     License as published by the Free Software Foundation; either
-     version 2 of the License, or (at your option) any later
-     version.
-   
-
-   
-     This program is distributed in the hope that it will be
-     useful, but WITHOUT ANY WARRANTY; without even the implied
-     warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-     See the GNU General Public License for more details.
-   
-
-   
-     You should have received a copy of the GNU General Public
-     License along with this program; if not, write to the Free
-     Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
-     MA 02111-1307 USA
-   
-
-   
-     For more details see the file COPYING in the source
-     distribution of Linux.
-   
-  
- 
-
- 
-  
-   Introduction
-   
-     Tracepoints are static probe points that are located in strategic points
-     throughout the kernel. 'Probes' register/unregister with tracepoints
-     via a callback mechanism. The 'probes' are strictly typed functions that
-     are passed a unique set of parameters defined by each tracepoint.
-   
-
-   
-     From this simple callback mechanism, 'probes' can be used to profile, debug,
-     and understand kernel behavior. There are a number of tools that provide a
-     framework for using 'probes'. These tools include Systemtap, ftrace, and
-     LTTng.
-   
-
-   
-     Tracepoints are defined in a number of header files via various macros. Thus,
-     the purpose of this document is to provide a clear accounting of the available
-     tracepoints. The intention is to understand not only what tracepoints are
-     available but also to understand where future tracepoints might be added.
-   
-
-   
-     The API presented has functions of the form:
-     trace_tracepointname(function parameters). These are the
-     tracepoints callbacks that are found throughout the code. Registering and
-     unregistering probes with these callback sites is covered in the
-     Documentation/trace/* directory.
-   
-  
-
-  
-   IRQ
-!Iinclude/trace/events/irq.h
-  
-
-  
-   SIGNAL
-!Iinclude/trace/events/signal.h
-  
-
-  
-   Block IO
-!Iinclude/trace/events/block.h
-  
-
-  
-   Workqueue
-!Iinclude/trace/events/workqueue.h
-  
-
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index c3a1402da0cd..91b3a010817a 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -19,7 +19,8 @@ Interfaces for kernel debugging
 .. toctree::
    :maxdepth: 1
 
-   debug-objects	      
+   debug-objects
+   tracepoint
 
 .. only::  subproject
 
diff --git a/Documentation/core-api/tracepoint.rst b/Documentation/core-api/tracepoint.rst
new file mode 100644
index 000000000000..6b44bec0de43
--- /dev/null
+++ b/Documentation/core-api/tracepoint.rst
@@ -0,0 +1,55 @@
+===============================
+The Linux Kernel Tracepoint API
+===============================
+
+:Author: Jason Baron
+:Author: William Cohen
+
+Introduction
+============
+
+Tracepoints are static probe points that are located in strategic points
+throughout the kernel. 'Probes' register/unregister with tracepoints via
+a callback mechanism. The 'probes' are strictly typed functions that are
+passed a unique set of parameters defined by each tracepoint.
+
+From this simple callback mechanism, 'probes' can be used to profile,
+debug, and understand kernel behavior. There are a number of tools that
+provide a framework for using 'probes'. These tools include Systemtap,
+ftrace, and LTTng.
+
+Tracepoints are defined in a number of header files via various macros.
+Thus, the purpose of this document is to provide a clear accounting of
+the available tracepoints. The intention is to understand not only what
+tracepoints are available but also to understand where future
+tracepoints might be added.
+
+The API presented has functions of the form:
+``trace_tracepointname(function parameters)``. These are the tracepoints
+callbacks that are found throughout the code. Registering and
+unregistering probes with these callback sites is covered in the
+``Documentation/trace/*`` directory.
+
+IRQ
+===
+
+.. kernel-doc:: include/trace/events/irq.h
+   :internal:
+
+SIGNAL
+======
+
+.. kernel-doc:: include/trace/events/signal.h
+   :internal:
+
+Block IO
+========
+
+.. kernel-doc:: include/trace/events/block.h
+   :internal:
+
+Workqueue
+=========
+
+.. kernel-doc:: include/trace/events/workqueue.h
+   :internal:
-- 
cgit v1.2.3


From 76cf11aa1590f51c49956f088585b2f97d531147 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:11 -0200
Subject: convert more media images to SVG

Using vectorial graphics provide a better visual. As those images
are originally using a vectorial graphics input at the pdf files,
use them, from an old media tree repository, converting them to SVG.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/media/Makefile                 |    7 +
 Documentation/media/uapi/v4l/crop.png        |  Bin 3334 -> 0 bytes
 Documentation/media/uapi/v4l/crop.rst        |    4 +-
 Documentation/media/uapi/v4l/crop.svg        |  269 +++
 Documentation/media/uapi/v4l/dev-raw-vbi.rst |   12 +-
 Documentation/media/uapi/v4l/field-order.rst |    8 +-
 Documentation/media/uapi/v4l/fieldseq_bt.png |  Bin 12306 -> 0 bytes
 Documentation/media/uapi/v4l/fieldseq_bt.svg | 2522 ++++++++++++++++++++++++++
 Documentation/media/uapi/v4l/fieldseq_tb.png |  Bin 12247 -> 0 bytes
 Documentation/media/uapi/v4l/fieldseq_tb.svg | 2510 +++++++++++++++++++++++++
 Documentation/media/uapi/v4l/vbi_525.png     |  Bin 2053 -> 0 bytes
 Documentation/media/uapi/v4l/vbi_525.svg     |  625 +++++++
 Documentation/media/uapi/v4l/vbi_625.png     |  Bin 2352 -> 0 bytes
 Documentation/media/uapi/v4l/vbi_625.svg     |  651 +++++++
 Documentation/media/uapi/v4l/vbi_hsync.png   |  Bin 906 -> 0 bytes
 Documentation/media/uapi/v4l/vbi_hsync.svg   |  253 +++
 16 files changed, 6849 insertions(+), 12 deletions(-)
 delete mode 100644 Documentation/media/uapi/v4l/crop.png
 create mode 100644 Documentation/media/uapi/v4l/crop.svg
 delete mode 100644 Documentation/media/uapi/v4l/fieldseq_bt.png
 create mode 100644 Documentation/media/uapi/v4l/fieldseq_bt.svg
 delete mode 100644 Documentation/media/uapi/v4l/fieldseq_tb.png
 create mode 100644 Documentation/media/uapi/v4l/fieldseq_tb.svg
 delete mode 100644 Documentation/media/uapi/v4l/vbi_525.png
 create mode 100644 Documentation/media/uapi/v4l/vbi_525.svg
 delete mode 100644 Documentation/media/uapi/v4l/vbi_625.png
 create mode 100644 Documentation/media/uapi/v4l/vbi_625.svg
 delete mode 100644 Documentation/media/uapi/v4l/vbi_hsync.png
 create mode 100644 Documentation/media/uapi/v4l/vbi_hsync.svg

diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index c22a30b07821..d79afe4d27e9 100644
--- a/Documentation/media/Makefile
+++ b/Documentation/media/Makefile
@@ -14,9 +14,16 @@ IMAGES = \
 	typical_media_device.svg \
 	uapi/dvb/dvbstb.svg \
 	uapi/v4l/constraints.svg \
+	uapi/v4l/crop.svg \
+	uapi/v4l/fieldseq_bt.svg \
+	uapi/v4l/fieldseq_tb.svg \
 	uapi/v4l/subdev-image-processing-full.svg \
 	uapi/v4l/subdev-image-processing-scaling-multi-source.svg \
 	uapi/v4l/subdev-image-processing-crop.svg \
+	uapi/v4l/vbi_525.svg \
+	uapi/v4l/vbi_625.svg \
+	uapi/v4l/vbi_hsync.svg \
+
 
 IMGTGT := $(patsubst %.png,%.pdf,$(patsubst %.svg,%.pdf,$(IMAGES)))
 IMGPDF := $(patsubst %,$(SRC_DIR)/%,$(IMGTGT))
diff --git a/Documentation/media/uapi/v4l/crop.png b/Documentation/media/uapi/v4l/crop.png
deleted file mode 100644
index 225998c395df..000000000000
Binary files a/Documentation/media/uapi/v4l/crop.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst
index 578c6f3d20f3..be58894c9c89 100644
--- a/Documentation/media/uapi/v4l/crop.rst
+++ b/Documentation/media/uapi/v4l/crop.rst
@@ -53,8 +53,8 @@ Cropping Structures
 
 .. _crop-scale:
 
-.. figure::  crop.png
-    :alt:    crop.png
+.. figure::  crop.*
+    :alt:    crop.pdf / crop.svg
     :align:  center
 
     Image Cropping, Insertion and Scaling
diff --git a/Documentation/media/uapi/v4l/crop.svg b/Documentation/media/uapi/v4l/crop.svg
new file mode 100644
index 000000000000..588bf8bd1ea7
--- /dev/null
+++ b/Documentation/media/uapi/v4l/crop.svg
@@ -0,0 +1,269 @@
+
+
+
+image/svg+xmlv4l2_cropcap.bounds
+v4l2_cropcap.defrect
+v4l2_crop.c
+v4l2_format
+
\ No newline at end of file
diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi.rst b/Documentation/media/uapi/v4l/dev-raw-vbi.rst
index f81d906137ee..baf5f2483927 100644
--- a/Documentation/media/uapi/v4l/dev-raw-vbi.rst
+++ b/Documentation/media/uapi/v4l/dev-raw-vbi.rst
@@ -221,8 +221,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT ` does
 
 .. _vbi-hsync:
 
-.. figure::  vbi_hsync.png
-    :alt:    vbi_hsync.png
+.. figure::  vbi_hsync.*
+    :alt:    vbi_hsync.pdf / vbi_hsync.svg
     :align:  center
 
     **Figure 4.1. Line synchronization**
@@ -230,8 +230,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT ` does
 
 .. _vbi-525:
 
-.. figure::  vbi_525.png
-    :alt:    vbi_525.png
+.. figure::  vbi_525.*
+    :alt:    vbi_525.pdf / vbi_525.svg
     :align:  center
 
     **Figure 4.2. ITU-R 525 line numbering (M/NTSC and M/PAL)**
@@ -240,8 +240,8 @@ and always returns default parameters as :ref:`VIDIOC_G_FMT ` does
 
 .. _vbi-625:
 
-.. figure::  vbi_625.png
-    :alt:    vbi_625.png
+.. figure::  vbi_625.*
+    :alt:    vbi_625.pdf / vbi_625.svg
     :align:  center
 
     **Figure 4.3. ITU-R 625 line numbering**
diff --git a/Documentation/media/uapi/v4l/field-order.rst b/Documentation/media/uapi/v4l/field-order.rst
index a7e1b4dae343..e05fb1041363 100644
--- a/Documentation/media/uapi/v4l/field-order.rst
+++ b/Documentation/media/uapi/v4l/field-order.rst
@@ -141,8 +141,8 @@ enum v4l2_field
 Field Order, Top Field First Transmitted
 ========================================
 
-.. figure::  fieldseq_tb.png
-    :alt:    fieldseq_tb.png
+.. figure::  fieldseq_tb.*
+    :alt:    fieldseq_tb.pdf / fieldseq_tb.svg
     :align:  center
 
 
@@ -151,7 +151,7 @@ Field Order, Top Field First Transmitted
 Field Order, Bottom Field First Transmitted
 ===========================================
 
-.. figure::  fieldseq_bt.png
-    :alt:    fieldseq_bt.png
+.. figure::  fieldseq_bt.*
+    :alt:    fieldseq_bt.pdf / fieldseq_bt.svg
     :align:  center
 
diff --git a/Documentation/media/uapi/v4l/fieldseq_bt.png b/Documentation/media/uapi/v4l/fieldseq_bt.png
deleted file mode 100644
index 888ce6fed817..000000000000
Binary files a/Documentation/media/uapi/v4l/fieldseq_bt.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/fieldseq_bt.svg b/Documentation/media/uapi/v4l/fieldseq_bt.svg
new file mode 100644
index 000000000000..2de2f187f217
--- /dev/null
+++ b/Documentation/media/uapi/v4l/fieldseq_bt.svg
@@ -0,0 +1,2522 @@
+
+
+
+image/svg+xmlV4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_ALTERNATE
+V4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_BOTTOMV4L2_FIELD_BOTTOMv4l2_buffer.field:
+Temporal order, bottom field first transmitted (e.g. M/NTSC)
+V4L2_FIELD_TOPV4L2_FIELD_TOP
+V4L2_FIELD_INTERLACED / V4L2_FIELD_INTERLACED_BTV4L2_FIELD_INTERLACED_TB (misaligned)V4L2_FIELD_SEQ_BT
+
\ No newline at end of file
diff --git a/Documentation/media/uapi/v4l/fieldseq_tb.png b/Documentation/media/uapi/v4l/fieldseq_tb.png
deleted file mode 100644
index b69426270b10..000000000000
Binary files a/Documentation/media/uapi/v4l/fieldseq_tb.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/fieldseq_tb.svg b/Documentation/media/uapi/v4l/fieldseq_tb.svg
new file mode 100644
index 000000000000..4e6460b28db7
--- /dev/null
+++ b/Documentation/media/uapi/v4l/fieldseq_tb.svg
@@ -0,0 +1,2510 @@
+
+
+
+image/svg+xmlV4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_ALTERNATE
+v4l2_buffer.field:V4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_TOPV4L2_FIELD_BOTTOM
+Temporal order, top field first transmitted (e.g. BG/PAL)V4L2_FIELD_SEQ_TBV4L2_FIELD_INTERLACED_BT (misaligned)V4L2_FIELD_INTERLACED / V4L2_FIELD_INTERLACED_TB
+
\ No newline at end of file
diff --git a/Documentation/media/uapi/v4l/vbi_525.png b/Documentation/media/uapi/v4l/vbi_525.png
deleted file mode 100644
index 24937dbec337..000000000000
Binary files a/Documentation/media/uapi/v4l/vbi_525.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/vbi_525.svg b/Documentation/media/uapi/v4l/vbi_525.svg
new file mode 100644
index 000000000000..3aee15d57c9a
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vbi_525.svg
@@ -0,0 +1,625 @@
+
+
+
+image/svg+xml(1)
+8745691012113226312622712702672682692722732752742662652632642624923156101112784923156101112785242615252622222232328522286231st field2nd field
+
\ No newline at end of file
diff --git a/Documentation/media/uapi/v4l/vbi_625.png b/Documentation/media/uapi/v4l/vbi_625.png
deleted file mode 100644
index 25c671af41ad..000000000000
Binary files a/Documentation/media/uapi/v4l/vbi_625.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/vbi_625.svg b/Documentation/media/uapi/v4l/vbi_625.svg
new file mode 100644
index 000000000000..d96a2628f305
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vbi_625.svg
@@ -0,0 +1,651 @@
+
+
+
+image/svg+xml1st field145678323123113102214567832625624623223086213096222nd field
+(1)
+7654323133123113363353213203193183173163153143133123111822233093093103102433723232424
+
\ No newline at end of file
diff --git a/Documentation/media/uapi/v4l/vbi_hsync.png b/Documentation/media/uapi/v4l/vbi_hsync.png
deleted file mode 100644
index b04ae50385a7..000000000000
Binary files a/Documentation/media/uapi/v4l/vbi_hsync.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/vbi_hsync.svg b/Documentation/media/uapi/v4l/vbi_hsync.svg
new file mode 100644
index 000000000000..17ddb5bcb071
--- /dev/null
+++ b/Documentation/media/uapi/v4l/vbi_hsync.svg
@@ -0,0 +1,253 @@
+
+
+
+image/svg+xmlBlack LevelSync LevelWhite Level
+offset
+Line synchr. pulseLine blanking
+
\ No newline at end of file
-- 
cgit v1.2.3


From 16bc3bfb237756f6985a968a0707865abba19222 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:12 -0200
Subject: svg files: cleanup them

Use sans-serif font on all documents, split text lines,
ungroup elements, and do other misc cleanups, in order to make
all of them to look better, and to have smaller columns inside
their lines.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/media/uapi/v4l/crop.svg              |  232 +-
 Documentation/media/uapi/v4l/fieldseq_bt.svg       | 3817 ++++++++++----------
 Documentation/media/uapi/v4l/fieldseq_tb.svg       | 3791 +++++++++----------
 .../uapi/v4l/subdev-image-processing-crop.svg      |  346 +-
 .../uapi/v4l/subdev-image-processing-full.svg      |  892 ++++-
 ...ubdev-image-processing-scaling-multi-source.svg |  626 +++-
 Documentation/media/uapi/v4l/vbi_525.svg           |  812 +++--
 Documentation/media/uapi/v4l/vbi_625.svg           |  717 ++--
 Documentation/media/uapi/v4l/vbi_hsync.svg         |  238 +-
 9 files changed, 6712 insertions(+), 4759 deletions(-)

diff --git a/Documentation/media/uapi/v4l/crop.svg b/Documentation/media/uapi/v4l/crop.svg
index 588bf8bd1ea7..dc9a471bae6b 100644
--- a/Documentation/media/uapi/v4l/crop.svg
+++ b/Documentation/media/uapi/v4l/crop.svg
@@ -19,7 +19,7 @@
    sodipodi:docname="crop.svg">image/svg+xmlv4l2_cropcap.bounds
+           d="m 1492.37,1607.5 1559.25,141.75" />v4l2_cropcap.bounds
 v4l2_cropcap.defrect
+       id="g126"
+       transform="matrix(1.4375794,0,0,1.4375794,-0.12334269,-0.08856738)">v4l2_cropcap.defrect
 v4l2_crop.c
+       id="g132"
+       transform="matrix(1.4375794,0,0,1.4375794,-0.12334269,-0.08856738)">v4l2_crop.c
 v4l2_format
-
\ No newline at end of file
+       id="g138"
+       transform="matrix(1.4375794,0,0,1.4375794,-0.12334269,-0.08856738)">v4l2_format
+
+
diff --git a/Documentation/media/uapi/v4l/fieldseq_bt.svg b/Documentation/media/uapi/v4l/fieldseq_bt.svg
index 2de2f187f217..b195301771ce 100644
--- a/Documentation/media/uapi/v4l/fieldseq_bt.svg
+++ b/Documentation/media/uapi/v4l/fieldseq_bt.svg
@@ -16,17 +16,7 @@
    width="198.48296mm"
    height="211.89406mm"
    viewBox="0 0 703.28606 750.80571"
-   sodipodi:docname="fieldseq_bt.svg">image/svg+xmlimage/svg+xmlV4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_ALTERNATE
+       id="path4837"
+       inkscape:connector-curvature="0" />V4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_ALTERNATE
+V4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_BOTTOMV4L2_FIELD_BOTTOMv4l2_buffer.field:
+Temporal order, bottom field first transmitted (e.g. M/NTSC)
+V4L2_FIELD_TOPV4L2_FIELD_TOP
+V4L2_FIELD_INTERLACED / V4L2_FIELD_INTERLACED_BTV4L2_FIELD_INTERLACED_TB (misaligned)V4L2_FIELD_SEQ_BT
+V4L2_FIELD_TOP
+V4L2_FIELD_BOTTOM
+V4L2_FIELD_ALTERNATE
+V4L2_FIELD_INTERLACED / V4L2_FIELD_INTERLACED_BT
 V4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_BOTTOMV4L2_FIELD_BOTTOMv4l2_buffer.field:
+       y="-192.9435"
+       x="1.5518398 9.5551729 16.226616 22.898062 29.569506 36.240948 43.572334 46.908058 54.911392 61.582836 70.246117 76.917557 80.253281 88.916557 96.247948 104.25128 112.91456 119.586 127.58932 136.25262 144.25595 152.91924 159.59067 166.92206 174.9254 178.26112 182.25679 192.25195 194.91573 200.91524 207.58667 210.25046 212.91423 219.58568 226.25713 232.92856 239.60001"
+       id="text5866"
+       style="font-variant:normal;font-weight:normal;font-size:11.9989996px;font-family:sans-serif;-inkscape-font-specification:sans-serif;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;font-style:normal;font-stretch:normal;"
+       transform="scale(1,-1)">V4L2_FIELD_INTERLACED_TB (misaligned)
 Temporal order, bottom field first transmitted (e.g. M/NTSC)
+       y="-86.653496"
+       x="5.8034 13.806733 20.478176 27.149622 33.821064 40.492508 47.823895 51.159618 59.162952 65.834396 74.497673 81.169121 89.172447 97.175781 106.511 113.18245 121.18579"
+       id="text5870"
+       style="font-variant:normal;font-weight:normal;font-size:11.9989996px;font-family:sans-serif;-inkscape-font-specification:sans-serif;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;font-style:normal;font-stretch:normal;"
+       transform="scale(1,-1)">V4L2_FIELD_SEQ_BT
 V4L2_FIELD_TOPV4L2_FIELD_TOP
+       y="-316.23969"
+       x="103.58983 109.09226 113.67899 118.26572 122.85246 127.43919 132.47964 134.77301 140.27545 144.86218 150.81833 155.40506 160.44553 166.86365 188.62184 194.12427 198.711 203.29774 207.88448 212.47121 217.51166 219.80502 225.30746 229.8942 235.85034 240.43707 245.9395 252.35764 257.3981 262.43854 268.85669 375.69293 381.19534 385.78207 390.3688 394.95554 399.54227 404.58273 406.8761 412.37854 416.96527 422.92142 427.50815 433.01059 439.42871 444.46918 449.50961 455.92776 1.551828 7.0542617 11.640993 16.227724 20.814463 25.401194 30.441652 32.735016 38.237442 42.824177 48.780331 53.367065 58.869492 65.287621 70.328079 75.368538 81.786659"
+       id="text7144"
+       style="font-variant:normal;font-weight:normal;font-size:8.2495203px;font-family:sans-serif;-inkscape-font-specification:sans-serif;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;font-style:normal;font-stretch:normal;"
+       transform="scale(1,-1)">V4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_BOTTOMV4L2_FIELD_BOTTOM
 V4L2_FIELD_INTERLACED / V4L2_FIELD_INTERLACED_BTV4L2_FIELD_INTERLACED_TB (misaligned)V4L2_FIELD_SEQ_BT
-
\ No newline at end of file
+       y="-328.99481"
+       x="10.054964 14.17972 18.766451 20.597849 25.18458 29.771311 34.358047 38.944778 41.238144 43.531509 48.118244 50.865334 53.158699 55.452068 57.283459 61.870193 63.701588 68.288322"
+       id="text7148"
+       style="font-variant:normal;font-weight:normal;font-size:8.2495203px;font-family:sans-serif;-inkscape-font-specification:sans-serif;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;font-style:normal;font-stretch:normal;"
+       transform="scale(1,-1)">v4l2_buffer.field:
+
\ No newline at end of file
diff --git a/Documentation/media/uapi/v4l/fieldseq_tb.svg b/Documentation/media/uapi/v4l/fieldseq_tb.svg
index 4e6460b28db7..6a7b10ad4ab8 100644
--- a/Documentation/media/uapi/v4l/fieldseq_tb.svg
+++ b/Documentation/media/uapi/v4l/fieldseq_tb.svg
@@ -16,17 +16,7 @@
    width="198.48296mm"
    height="210.39415mm"
    viewBox="0 0 703.28607 745.49109"
-   sodipodi:docname="fieldseq_tb.svg">image/svg+xmlimage/svg+xmlV4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_ALTERNATE
+       id="path6761"
+       inkscape:connector-curvature="0" />V4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_ALTERNATE
+v4l2_buffer.field:V4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_TOPV4L2_FIELD_BOTTOM
+Temporal order, top field first transmitted (e.g. BG/PAL)V4L2_FIELD_SEQ_TBV4L2_FIELD_INTERLACED_BT (misaligned)V4L2_FIELD_INTERLACED / V4L2_FIELD_INTERLACED_TB
+V4L2_FIELD_TOP
+V4L2_FIELD_BOTTOM
+V4L2_FIELD_ALTERNATE
+Temporal order, top field first transmitted (e.g. BG/PAL)
+V4L2_FIELD_SEQ_TB
+V4L2_FIELD_INTERLACED_BT (misaligned)
+V4L2_FIELD_INTERLACED / V4L2_FIELD_INTERLACED_TB
 v4l2_buffer.field:V4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_TOPV4L2_FIELD_BOTTOM
+       y="-324.69479"
+       x="10.05469 14.17945 18.766184 20.597576 25.184309 29.771042 34.357777 38.944508 41.237877 43.531242 48.117977 50.865067 53.158432 55.451801 57.283192 61.869926 63.701321 68.288048"
+       id="text7131"
+       style="font-variant:normal;font-weight:normal;font-size:8.2495203px;font-family:sans-serif;-inkscape-font-specification:sans-serif;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;font-style:normal;font-stretch:normal;"
+       transform="scale(1,-1)">v4l2_buffer.field:
 Temporal order, top field first transmitted (e.g. BG/PAL)V4L2_FIELD_SEQ_TBV4L2_FIELD_INTERLACED_BT (misaligned)V4L2_FIELD_INTERLACED / V4L2_FIELD_INTERLACED_TB
-
\ No newline at end of file
+       y="-311.9397"
+       x="10.05469 15.55712 20.143852 24.730585 29.317318 33.904053 38.944508 41.237877 46.740307 51.327042 57.283192 61.869926 66.910378 73.328506 95.0867 100.58913 105.17586 109.7626 114.34933 118.93606 123.97652 126.26987 131.77232 136.35905 142.3152 146.90193 152.40436 158.82249 163.86295 168.9034 175.32153 197.12534 202.62778 207.21451 211.80124 216.38797 220.9747 226.01515 228.30853 233.81096 238.39769 244.35384 248.94058 253.98103 260.39917 282.15695 287.65936 292.24609 296.83282 301.41956 306.00629 311.04675 313.34012 318.84256 323.42929 329.38544 333.97217 339.47461 345.89273 350.9332 355.97363 362.39175 384.19559 389.698 394.28473 398.87149 403.45822 408.04495 413.08539 415.37875 420.8812 425.46793 431.42407 436.0108 441.05127 447.46939 469.2276 474.73001 479.31674 483.90347 488.49023 493.07697 498.1174 500.41077 505.91321 510.49994 516.45612 521.04285 526.54523 532.96338 538.00385 543.04431 549.4624"
+       id="text7135"
+       style="font-variant:normal;font-weight:normal;font-size:8.2495203px;font-family:sans-serif;-inkscape-font-specification:sans-serif;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;font-style:normal;font-stretch:normal;"
+       transform="scale(1,-1)">V4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_TOPV4L2_FIELD_BOTTOMV4L2_FIELD_TOPV4L2_FIELD_BOTTOM
+
\ No newline at end of file
diff --git a/Documentation/media/uapi/v4l/subdev-image-processing-crop.svg b/Documentation/media/uapi/v4l/subdev-image-processing-crop.svg
index 18b0f5de9ed2..ba02e6f6214d 100644
--- a/Documentation/media/uapi/v4l/subdev-image-processing-crop.svg
+++ b/Documentation/media/uapi/v4l/subdev-image-processing-crop.svg
@@ -1,63 +1,313 @@
 
-
-
-  
-  
-    
-    
+
+  
+    
+      
+        image/svg+xml
+        
+      
+    
+  
+  
+  
+  
+  
+    
+    
   
-  
-    
-    
+  
+    
+    
   
-  
-    sink
-    crop
-    selection
+  
+    sink
+    crop
+    selection
   
-  
-    
+  
+    
   
-  
-    sink media
-    bus format
+  
+    sink media
+    bus format
   
-  
-    source media
-    bus format
+  
+    source media
+    bus format
   
-  
-    
-    
+  
+    
+    
   
-  
-  
-  
-  
-  
-    
-    
-    
+  
+  
+  
+  
+  
+    
+    
+    
   
-  
-    
-    
-    
+  
+    
+    
+    
   
-  
-    pad 1 (source)
+  
+    pad 1 (source)
   
-  
-    
-    
-    
+  
+    
+    
+    
   
-  
-    
-    
-    
+  
+    
+    
+    
   
-  
-    pad 0 (sink)
+  
+    pad 0 (sink)
   
 
diff --git a/Documentation/media/uapi/v4l/subdev-image-processing-full.svg b/Documentation/media/uapi/v4l/subdev-image-processing-full.svg
index 3322cf4c0093..c82291a4493e 100644
--- a/Documentation/media/uapi/v4l/subdev-image-processing-full.svg
+++ b/Documentation/media/uapi/v4l/subdev-image-processing-full.svg
@@ -1,163 +1,769 @@
 
-
-
-  
-    
-    
-  
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    pad 0 (sink)
+
+  
+    
+      
+        image/svg+xml
+        
+      
+    
+  
+  
+  
+  
+    
+    
+  
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    pad 0 (sink)
   
-  
-    pad 2 (source)
+  
+    pad 2 (source)
   
-  
-    
-    
+  
+    
+    
   
-  
-    
-    
+  
+    
+    
   
-  
-    
+  
+    
   
-  
-    sink media
-    bus format
+  
+    sink media
+    bus format
   
-  
-    
-    
-  
-  
-  
-  
-  
-  
-    sink compose
-    selection (scaling)
+  
+    
+    
+  
+  
+  
+  
+  
+  
+    sink compose
+    selection (scaling)
   
-  
-    
-    
+  
+    
+    
   
-  
-    source media
-    bus format
+  
+    source media
+    bus format
   
-  
-    
-    
-  
-  
-  
-  
-  
-  
-    sink compose
-    bounds selection
+  
+    
+    
+  
+  
+  
+  
+  
+  
+    sink compose
+    bounds selection
   
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    pad 1 (sink)
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    pad 1 (sink)
   
-  
-    
-    
+  
+    
+    
   
-  
-    
-    
+  
+    
+    
   
-  
-    
+  
+    
   
-  
-  
-  
-  
-  
-  
-  
-    
-    
-  
-  
-  
-  
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    pad 3 (source)
+  
+  
+  
+  
+  
+  
+  
+    
+    
+  
+  
+  
+  
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    pad 3 (source)
   
-  
-    sink
-    crop
-    selection
+  
+    sink
+    crop
+    selection
   
-  
-    source
-    crop
-    selection
+  
+    source
+    crop
+    selection
   
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
-  
-  
-    
-    
-    
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
+  
+  
+    
+    
+    
   
 
diff --git a/Documentation/media/uapi/v4l/subdev-image-processing-scaling-multi-source.svg b/Documentation/media/uapi/v4l/subdev-image-processing-scaling-multi-source.svg
index 2340c0f8bc92..e7b3786f8a9b 100644
--- a/Documentation/media/uapi/v4l/subdev-image-processing-scaling-multi-source.svg
+++ b/Documentation/media/uapi/v4l/subdev-image-processing-scaling-multi-source.svg
@@ -1,116 +1,560 @@
 
-
-
-  
-  
-    
-    
+
+  
+    
+      
+        image/svg+xml
+        
+      
+    
+  
+  
+  
+  
+  
+    
+    
   
-  
-    
-    
+  
+    
+    
   
-  
-    sink
-    crop
-    selection
+  
+    sink
+    crop
+    selection
   
-  
-    
+  
+    
   
-  
-    sink media
-    bus format
+  
+    sink media
+    bus format
   
-  
-    
-    
+  
+    
+    
   
-  
-  
-  
-  
-  
-    sink compose
-    selection (scaling)
+  
+  
+  
+  
+  
+    sink compose
+    selection (scaling)
   
-  
-    
-    
+  
+    
+    
   
-  
-    source
-    crop
-    selection
+  
+    source
+    crop
+    selection
   
-  
-    source media
-    bus format
+  
+    source media
+    bus format
   
-  
-    
-    
+  
+    
+    
   
-  
-  
-  
-  
-  
-    
-    
-    
+  
+  
+  
+  
+  
+    
+    
+    
   
-  
-    
-    
-    
+  
+    
+    
+    
   
-  
-    pad 1 (source)
+  
+    pad 1 (source)
   
-  
-    
-    
-    
+  
+    
+    
+    
   
-  
-    
-    
-    
+  
+    
+    
+    
   
-  
-    pad 0 (sink)
+  
+    pad 0 (sink)
   
-  
-  
-    
-    
+  
+  
+    
+    
   
-  
-  
-  
-  
-  
-    
-    
-    
+  
+  
+  
+  
+  
+    
+    
+    
   
-  
-    
-    
-    
+  
+    
+    
+    
   
-  
-    pad 2 (source)
+  
+    pad 2 (source)
   
-  
-    
-    
-    
+  
+    
+    
+    
   
-  
-    
-    
-    
+  
+    
+    
+    
   
 
diff --git a/Documentation/media/uapi/v4l/vbi_525.svg b/Documentation/media/uapi/v4l/vbi_525.svg
index 3aee15d57c9a..b05f7777ccf8 100644
--- a/Documentation/media/uapi/v4l/vbi_525.svg
+++ b/Documentation/media/uapi/v4l/vbi_525.svg
@@ -16,21 +16,7 @@
    width="208.73068mm"
    height="51.395489mm"
    viewBox="0 0 739.59691 182.11"
-   sodipodi:docname="vbi_525.svg">image/svg+xmlimage/svg+xml(1)
+         y="-4035.6582"
+         x="1621.9453 1642.3999 1676.5522">(1)
 8745691012113226312628745691012113226312622712702672682692722732752742662652632642622712702672682692722732752742662652632642624923156101112784923156101112784923156101112784923156101112785245242612615255252622622222222223232323285285222228628623231st field1st field2nd field
+874569101211322631262
+271270267268269272273275274266265263264262
+492315610111278
+2nd field
+         y="-4938.6074"
+         x="2725.5474 4568.3013 1988.446 2356.9966 1619.8953 3094.0981 3462.6489 4916.3638 4957.3472 5284.9146 5325.8975 5653.4653 5694.4482 3812.7788 4181.3296">492315610111278
+524
+261
+525
+262
+22
+22
+23
+23
+285
+22
+286
+23
+1st field
+2nd field
 
\ No newline at end of file
diff --git a/Documentation/media/uapi/v4l/vbi_625.svg b/Documentation/media/uapi/v4l/vbi_625.svg
index d96a2628f305..c117ddb7bf7e 100644
--- a/Documentation/media/uapi/v4l/vbi_625.svg
+++ b/Documentation/media/uapi/v4l/vbi_625.svg
@@ -16,21 +16,7 @@
    width="209.46608mm"
    height="51.576824mm"
    viewBox="0 0 742.20265 182.75252"
-   sodipodi:docname="vbi_625.svg">image/svg+xmlimage/svg+xml1st field145678323123113102214567832625624623223086213096222nd field
+       d="m 6636.6552,5109.5899 0,-73.9699" />1st field145678323123113102214567832625624623223086213096222nd field
+(1)
+7654323133123113363353213203193183173163153143133123111822233093093103102433723232424
+1st field
+1456783231231131022
+1456783262562462322
+308
+621
+309
+622
+2nd field
+765432313312311
+336335321320319318317316315314313312311
+182223309
+309
+310
+310
+24
+337
+23
+23
 (1)
+       transform="scale(1,-1)"
+       style="font-variant:normal;font-weight:normal;font-size:73.96984863px;font-family:sans-serif;-inkscape-font-specification:sans-serif;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;font-style:normal;font-stretch:normal;"
+       id="text4123"
+       x="6410.605 6451.7324"
+       y="-4943.1504">24
 7654323133123113363353213203193183173163153143133123111822233093093103102433723232424
-
\ No newline at end of file
+       transform="scale(1,-1)"
+       style="font-variant:normal;font-weight:normal;font-size:73.96984863px;font-family:sans-serif;-inkscape-font-specification:sans-serif;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;font-style:normal;font-stretch:normal;"
+       id="text4127"
+       x="6410.605 6451.7324"
+       y="-5054.106">24
+
\ No newline at end of file
diff --git a/Documentation/media/uapi/v4l/vbi_hsync.svg b/Documentation/media/uapi/v4l/vbi_hsync.svg
index 17ddb5bcb071..4d5c0b4f146e 100644
--- a/Documentation/media/uapi/v4l/vbi_hsync.svg
+++ b/Documentation/media/uapi/v4l/vbi_hsync.svg
@@ -16,29 +16,7 @@
    width="192.39857mm"
    height="146.83536mm"
    viewBox="0 0 681.72724 520.28277"
-   sodipodi:docname="vbi_hsync.svg">image/svg+xmlimage/svg+xmlBlack LevelSync LevelWhite Level
+           d="m 192.004,204.696 274.711,0" />Black LevelSync LevelWhite Level
+offset
+Line synchr. pulseLine blanking
+Line synchr. pulse
+Line blanking
+Black Level
 offset
+       id="text3611"
+       style="font-variant:normal;font-weight:normal;font-size:20.83772659px;font-family:sans-serif;-inkscape-font-specification:sans-serif;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;font-style:normal;font-stretch:normal;"
+       transform="scale(1,-1)"
+       x="438.29504 452.19382 462.61267 474.19846 484.61731 490.41019 501.99597 513.58173 524.00061 535.58636"
+       y="-83.096947">Sync Level
 Line synchr. pulseLine blanking
-
\ No newline at end of file
+       id="text3615"
+       style="font-variant:normal;font-weight:normal;font-size:20.83772659px;font-family:sans-serif;-inkscape-font-specification:sans-serif;writing-mode:lr-tb;fill:#000000;fill-opacity:1;fill-rule:nonzero;stroke:none;font-style:normal;font-stretch:normal;"
+       transform="scale(1,-1)"
+       x="438.29504 457.96585 469.55164 474.17761 479.97049 491.55627 497.34915 508.93494 520.52069 530.93958 542.52533"
+       y="-395.66284">White Level
+
\ No newline at end of file
-- 
cgit v1.2.3


From 2bd658de409da459a4e5028010715628e7f11b52 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:13 -0200
Subject: docs-rst: nv12mt zigzag images: replace by SVG images

Instead of using bitmap images to show the zigzag macroblock
parsing, replace it by a SVG ones, with is scalable.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/media/Makefile                    |    2 +
 Documentation/media/uapi/v4l/nv12mt.png         |  Bin 1920 -> 0 bytes
 Documentation/media/uapi/v4l/nv12mt.svg         |  450 +++++++
 Documentation/media/uapi/v4l/nv12mt_example.png |  Bin 5261 -> 0 bytes
 Documentation/media/uapi/v4l/nv12mt_example.svg | 1589 +++++++++++++++++++++++
 Documentation/media/uapi/v4l/pixfmt-nv12mt.rst  |    8 +-
 6 files changed, 2045 insertions(+), 4 deletions(-)
 delete mode 100644 Documentation/media/uapi/v4l/nv12mt.png
 create mode 100644 Documentation/media/uapi/v4l/nv12mt.svg
 delete mode 100644 Documentation/media/uapi/v4l/nv12mt_example.png
 create mode 100644 Documentation/media/uapi/v4l/nv12mt_example.svg

diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index d79afe4d27e9..ec95286e556c 100644
--- a/Documentation/media/Makefile
+++ b/Documentation/media/Makefile
@@ -17,6 +17,8 @@ IMAGES = \
 	uapi/v4l/crop.svg \
 	uapi/v4l/fieldseq_bt.svg \
 	uapi/v4l/fieldseq_tb.svg \
+	uapi/v4l/nv12mt.svg \
+	uapi/v4l/nv12mt_example.svg \
 	uapi/v4l/subdev-image-processing-full.svg \
 	uapi/v4l/subdev-image-processing-scaling-multi-source.svg \
 	uapi/v4l/subdev-image-processing-crop.svg \
diff --git a/Documentation/media/uapi/v4l/nv12mt.png b/Documentation/media/uapi/v4l/nv12mt.png
deleted file mode 100644
index 41401860fb73..000000000000
Binary files a/Documentation/media/uapi/v4l/nv12mt.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/nv12mt.svg b/Documentation/media/uapi/v4l/nv12mt.svg
new file mode 100644
index 000000000000..21fcccda9723
--- /dev/null
+++ b/Documentation/media/uapi/v4l/nv12mt.svg
@@ -0,0 +1,450 @@
+
+image/svg+xml0
+6
+1
+7
+2
+4
+3
+5
+
diff --git a/Documentation/media/uapi/v4l/nv12mt_example.png b/Documentation/media/uapi/v4l/nv12mt_example.png
deleted file mode 100644
index 7775f5d7cc46..000000000000
Binary files a/Documentation/media/uapi/v4l/nv12mt_example.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/nv12mt_example.svg b/Documentation/media/uapi/v4l/nv12mt_example.svg
new file mode 100644
index 000000000000..d65d989ee73b
--- /dev/null
+++ b/Documentation/media/uapi/v4l/nv12mt_example.svg
@@ -0,0 +1,1589 @@
+
+image/svg+xml0
+6
+1
+7
+9
+8
+2
+4
+3
+5
+11
+10
+12
+18
+13
+19
+21
+20
+14
+16
+15
+17
+23
+22
+24
+26
+25
+27
+29
+28
+
diff --git a/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst b/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst
index c8a77bc79f2f..32d0c8743460 100644
--- a/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst
+++ b/Documentation/media/uapi/v4l/pixfmt-nv12mt.rst
@@ -33,8 +33,8 @@ Layout of macroblocks in memory is presented in the following figure.
 
 .. _nv12mt:
 
-.. figure::  nv12mt.png
-    :alt:    nv12mt.png
+.. figure::  nv12mt.*
+    :alt:    nv12mt.pdf / nv12mt.svg
     :align:  center
 
     V4L2_PIX_FMT_NV12MT macroblock Z shape memory layout
@@ -50,8 +50,8 @@ interleaved. Height of the buffer is aligned to 32.
 
 .. _nv12mt_ex:
 
-.. figure::  nv12mt_example.png
-    :alt:    nv12mt_example.png
+.. figure::  nv12mt_example.*
+    :alt:    nv12mt_example.pdf / nv12mt_example.svg
     :align:  center
 
     Example V4L2_PIX_FMT_NV12MT memory layout of macroblocks
-- 
cgit v1.2.3


From 394709da73bc10f0b2d91495ff2440bc0ede5652 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:14 -0200
Subject: docs-rst: convert pipeline to SVG format

The pipeline image was produced from some dot file that has
long missed. Create a pipeline.dot with the graph and convert
it to SVG. As we're planning to add future support for graphviz
graphics, also store the .dot file on the tree, as this will
make easier when we add such Sphinx extension.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/media/Makefile                |   1 +
 Documentation/media/uapi/v4l/dev-subdev.rst |   4 +-
 Documentation/media/uapi/v4l/pipeline.dot   |  12 +++++
 Documentation/media/uapi/v4l/pipeline.png   | Bin 12130 -> 0 bytes
 Documentation/media/uapi/v4l/pipeline.svg   |  68 ++++++++++++++++++++++++++++
 5 files changed, 83 insertions(+), 2 deletions(-)
 create mode 100644 Documentation/media/uapi/v4l/pipeline.dot
 delete mode 100644 Documentation/media/uapi/v4l/pipeline.png
 create mode 100644 Documentation/media/uapi/v4l/pipeline.svg

diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index ec95286e556c..fff8e3b73e25 100644
--- a/Documentation/media/Makefile
+++ b/Documentation/media/Makefile
@@ -19,6 +19,7 @@ IMAGES = \
 	uapi/v4l/fieldseq_tb.svg \
 	uapi/v4l/nv12mt.svg \
 	uapi/v4l/nv12mt_example.svg \
+	uapi/v4l/pipeline.svg \
 	uapi/v4l/subdev-image-processing-full.svg \
 	uapi/v4l/subdev-image-processing-scaling-multi-source.svg \
 	uapi/v4l/subdev-image-processing-crop.svg \
diff --git a/Documentation/media/uapi/v4l/dev-subdev.rst b/Documentation/media/uapi/v4l/dev-subdev.rst
index c18e9c5427ee..cd2870180208 100644
--- a/Documentation/media/uapi/v4l/dev-subdev.rst
+++ b/Documentation/media/uapi/v4l/dev-subdev.rst
@@ -99,8 +99,8 @@ the video sensor and the host image processing hardware.
 
 .. _pipeline-scaling:
 
-.. figure::  pipeline.png
-    :alt:    pipeline.png
+.. figure::  pipeline.*
+    :alt:    pipeline.pdf / pipeline.svg
     :align:  center
 
     Image Format Negotiation on Pipelines
diff --git a/Documentation/media/uapi/v4l/pipeline.dot b/Documentation/media/uapi/v4l/pipeline.dot
new file mode 100644
index 000000000000..02d7fcf12b26
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pipeline.dot
@@ -0,0 +1,12 @@
+digraph board {
+	rankdir=TB
+	colorscheme=x11
+	scaler [label="{ 0} | Host\nScaler | { 1} ", shape=Mrecord, style=filled, fillcolor=lightblue]
+	frontend [label="{ 0} | Host\nFrontend | { 1}", shape=Mrecord, style=filled, fillcolor=lightblue]
+	sensor [label="Sensor | { 0}", shape=Mrecord, style=filled, fillcolor=aquamarine]
+	io [label="{ 0} | V4L I/O", shape=Mrecord, style=filled, fillcolor=aquamarine]
+
+	sensor:sensor_0 -> frontend:frontend_0 [color=blue, label="HQ: 2592x1968\nHS: 1296x984"]
+	frontend:frontend_1 -> scaler:scaler_0 [color=blue, label="HQ: 2592x1968\nHS: 1296x984"]
+	scaler:scaler_1 -> io:io_0 [color=blue, label="HQ: 1280x720\nHS: 1280x720"]
+}
diff --git a/Documentation/media/uapi/v4l/pipeline.png b/Documentation/media/uapi/v4l/pipeline.png
deleted file mode 100644
index f19b86c2c24d..000000000000
Binary files a/Documentation/media/uapi/v4l/pipeline.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/pipeline.svg b/Documentation/media/uapi/v4l/pipeline.svg
new file mode 100644
index 000000000000..70f4c1b23ca1
--- /dev/null
+++ b/Documentation/media/uapi/v4l/pipeline.svg
@@ -0,0 +1,68 @@
+
+
+
+
+
+
+board
+
+
+scaler
+
+0
+
+Host
+Scaler
+
+1
+
+
+io
+
+0
+
+V4L I/O
+
+
+scaler:scaler_1->io:io_0
+
+
+HQ: 1280x720
+HS: 1280x720
+
+
+frontend
+
+0
+
+Host
+Frontend
+
+1
+
+
+frontend:frontend_1->scaler:scaler_0
+
+
+HQ: 2592x1968
+HS: 1296x984
+
+
+sensor
+
+Sensor
+
+0
+
+
+sensor:sensor_0->frontend:frontend_0
+
+
+HQ: 2592x1968
+HS: 1296x984
+
+
+
-- 
cgit v1.2.3


From 86e6808abbdf302c8e9518e9908ce333ea388351 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:15 -0200
Subject: docs-rst: replace the selection.png by a SVG image

bitmap images don't scale too well. So, replace it by a SVG
image, written in inkscape. I'm using the 2009's temporary
logo.svg image from 8032b526d1a3 ("linux.conf.au 2009: Tuz"),
with a Tasmanian Devil wearing a tux mask.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/media/Makefile                       |    1 +
 Documentation/media/uapi/v4l/selection-api-003.rst |    4 +-
 Documentation/media/uapi/v4l/selection.png         |  Bin 11716 -> 0 bytes
 Documentation/media/uapi/v4l/selection.svg         | 5812 ++++++++++++++++++++
 4 files changed, 5815 insertions(+), 2 deletions(-)
 delete mode 100644 Documentation/media/uapi/v4l/selection.png
 create mode 100644 Documentation/media/uapi/v4l/selection.svg

diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index fff8e3b73e25..d97e969c3ac0 100644
--- a/Documentation/media/Makefile
+++ b/Documentation/media/Makefile
@@ -20,6 +20,7 @@ IMAGES = \
 	uapi/v4l/nv12mt.svg \
 	uapi/v4l/nv12mt_example.svg \
 	uapi/v4l/pipeline.svg \
+	uapi/v4l/selection.svg \
 	uapi/v4l/subdev-image-processing-full.svg \
 	uapi/v4l/subdev-image-processing-scaling-multi-source.svg \
 	uapi/v4l/subdev-image-processing-crop.svg \
diff --git a/Documentation/media/uapi/v4l/selection-api-003.rst b/Documentation/media/uapi/v4l/selection-api-003.rst
index 207349c17ead..21686f93c38f 100644
--- a/Documentation/media/uapi/v4l/selection-api-003.rst
+++ b/Documentation/media/uapi/v4l/selection-api-003.rst
@@ -7,8 +7,8 @@ Selection targets
 
 .. _sel-targets-capture:
 
-.. figure::  selection.png
-    :alt:    selection.png
+.. figure::  selection.*
+    :alt:    selection.pdf / selection.svg
     :align:  center
 
     Cropping and composing targets
diff --git a/Documentation/media/uapi/v4l/selection.png b/Documentation/media/uapi/v4l/selection.png
deleted file mode 100644
index bfc523eae570..000000000000
Binary files a/Documentation/media/uapi/v4l/selection.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/selection.svg b/Documentation/media/uapi/v4l/selection.svg
new file mode 100644
index 000000000000..d309187af967
--- /dev/null
+++ b/Documentation/media/uapi/v4l/selection.svg
@@ -0,0 +1,5812 @@
+
+
+
+
+  
+  
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+      
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+      
+    
+    
+      
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+      
+    
+    
+      
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+      
+    
+    
+      
+      
+      
+    
+    
+      
+      
+      
+    
+    
+      
+      
+      
+    
+    
+      
+      
+      
+      
+      
+    
+    
+    
+    
+    
+    
+    
+      
+    
+    
+    
+      
+    
+    
+    
+    
+    
+    
+      
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+    
+      
+    
+    
+      
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+    
+      
+    
+    
+    
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+    
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+      
+    
+    
+      
+    
+    
+      
+    
+    
+    
+    
+      
+    
+    
+      
+    
+    
+    
+      
+    
+    
+    
+      
+    
+    
+      
+    
+    
+    
+      
+    
+    
+    
+    
+      
+    
+    
+    
+    
+      
+    
+    
+    
+      
+    
+    
+    
+    
+      
+    
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+      
+    
+    
+      
+    
+  
+  
+    
+      
+        image/svg+xml
+        
+        
+      
+    
+  
+  
+  
+  
+  
+  
+    
+    
+    
+    
+      
+      
+        
+        
+        
+      
+      
+      
+      
+      
+      
+      
+      
+      
+        
+        
+          
+          
+          
+        
+        
+          
+          
+        
+      
+      
+      
+      
+      
+      
+        
+          
+            
+            
+          
+          
+            
+            
+          
+        
+        
+          
+            
+            
+          
+          
+            
+            
+          
+        
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+        
+        
+        
+        
+      
+      
+      
+      
+      
+      
+      
+        
+        
+        
+        
+        
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+      
+        
+          
+            
+            
+          
+        
+        
+          
+            
+            
+          
+        
+      
+      
+      
+        
+        
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+          
+        
+      
+      
+      
+      
+      
+      
+      
+      
+        
+        
+      
+      
+      
+      
+      
+      
+        
+        
+      
+      
+        
+        
+      
+      
+      
+      
+      
+        
+        
+      
+      
+      
+      
+      
+      
+        
+        
+      
+      
+        
+        
+      
+    
+    
+    
+    
+    
+      
+      
+        
+        
+          
+          
+          
+        
+        
+        
+        
+        
+        
+        
+        
+        
+          
+          
+            
+            
+            
+          
+          
+            
+            
+          
+        
+        
+        
+        
+        
+        
+          
+            
+              
+              
+            
+            
+              
+              
+            
+          
+          
+            
+              
+              
+            
+            
+              
+              
+            
+          
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+          
+          
+          
+          
+        
+        
+        
+        
+        
+        
+        
+          
+          
+          
+          
+          
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+        
+          
+            
+              
+              
+            
+          
+          
+            
+              
+              
+            
+          
+        
+        
+        
+          
+          
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+              
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+            
+          
+        
+        
+        
+        
+        
+        
+        
+        
+          
+          
+        
+        
+        
+        
+        
+        
+          
+          
+        
+        
+          
+          
+        
+        
+        
+        
+        
+          
+          
+        
+        
+        
+        
+        
+        
+          
+          
+        
+        
+          
+          
+        
+      
+    
+    
+    
+    CROP_DEFAULT
+    COMPOSE_PADDED
+    COMPOSE_ACTIVE
+    COMPOSE_DEFAULT
+    COMPOSE_PADDED
+    COMPOSE_BONDS
+    CROP_BONDS
+    overscan area
+    CROP_ACTIVE
+    DATA SOURCE
+    DATA SINK
+      
+
-- 
cgit v1.2.3


From ffbdad94d07f89391563d59f1789deb6c9ab4876 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:16 -0200
Subject: docs-rst: replace bayer.png by a SVG image

SVG images are scalable, with makes easier to output on
different formats.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/media/Makefile                    |   1 +
 Documentation/media/uapi/v4l/bayer.png          | Bin 9725 -> 0 bytes
 Documentation/media/uapi/v4l/bayer.svg          | 984 ++++++++++++++++++++++++
 Documentation/media/uapi/v4l/subdev-formats.rst |   4 +-
 4 files changed, 987 insertions(+), 2 deletions(-)
 delete mode 100644 Documentation/media/uapi/v4l/bayer.png
 create mode 100644 Documentation/media/uapi/v4l/bayer.svg

diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index d97e969c3ac0..998e8dd49352 100644
--- a/Documentation/media/Makefile
+++ b/Documentation/media/Makefile
@@ -13,6 +13,7 @@ TARGETS := $(addprefix $(BUILDDIR)/, $(FILES))
 IMAGES = \
 	typical_media_device.svg \
 	uapi/dvb/dvbstb.svg \
+	uapi/v4l/bayer.svg \
 	uapi/v4l/constraints.svg \
 	uapi/v4l/crop.svg \
 	uapi/v4l/fieldseq_bt.svg \
diff --git a/Documentation/media/uapi/v4l/bayer.png b/Documentation/media/uapi/v4l/bayer.png
deleted file mode 100644
index 9b15fb22e817..000000000000
Binary files a/Documentation/media/uapi/v4l/bayer.png and /dev/null differ
diff --git a/Documentation/media/uapi/v4l/bayer.svg b/Documentation/media/uapi/v4l/bayer.svg
new file mode 100644
index 000000000000..fbd4cfb5e6bf
--- /dev/null
+++ b/Documentation/media/uapi/v4l/bayer.svg
@@ -0,0 +1,984 @@
+
+image/svg+xmlB
+G
+G
+R
+BGGR
+B
+G
+G
+R
+GBRG
+B
+G
+G
+R
+RGGB
+B
+G
+G
+R
+GRBG
+
\ No newline at end of file
diff --git a/Documentation/media/uapi/v4l/subdev-formats.rst b/Documentation/media/uapi/v4l/subdev-formats.rst
index 2f9c135dfadd..d6152c907b8b 100644
--- a/Documentation/media/uapi/v4l/subdev-formats.rst
+++ b/Documentation/media/uapi/v4l/subdev-formats.rst
@@ -1514,8 +1514,8 @@ be named ``MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE``.
 
 .. _bayer-patterns:
 
-.. figure::  bayer.png
-    :alt:    bayer.png
+.. figure::  bayer.*
+    :alt:    bayer.pdf / bayer.svg
     :align:  center
 
     **Figure 4.8 Bayer Patterns**
-- 
cgit v1.2.3


From ec868e4ee2bcebb9e4c03979d90e0ac0b79fe05a Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:17 -0200
Subject: docs-rst: media: build SVG from graphviz files

Instead of keeping both SVG and graphviz files, dynamically
build SVG from its graphviz sources.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/media/.gitignore            |  2 +
 Documentation/media/Makefile              | 20 ++++++---
 Documentation/media/uapi/v4l/pipeline.svg | 68 -------------------------------
 3 files changed, 16 insertions(+), 74 deletions(-)
 delete mode 100644 Documentation/media/uapi/v4l/pipeline.svg

diff --git a/Documentation/media/.gitignore b/Documentation/media/.gitignore
index a1363379944a..08b21de3ef94 100644
--- a/Documentation/media/.gitignore
+++ b/Documentation/media/.gitignore
@@ -1 +1,3 @@
 *.pdf
+# Files generated from *.dot
+uapi/v4l/pipeline.svg
diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index 998e8dd49352..547b4105f826 100644
--- a/Documentation/media/Makefile
+++ b/Documentation/media/Makefile
@@ -10,6 +10,9 @@ FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst net.h.rst video.h.rst \
 
 TARGETS := $(addprefix $(BUILDDIR)/, $(FILES))
 
+DOTS = \
+	uapi/v4l/pipeline.dot \
+
 IMAGES = \
 	typical_media_device.svg \
 	uapi/dvb/dvbstb.svg \
@@ -29,8 +32,10 @@ IMAGES = \
 	uapi/v4l/vbi_625.svg \
 	uapi/v4l/vbi_hsync.svg \
 
+DOTTGT := $(patsubst %.dot,%.svg,$(DOTS))
+IMGDOT := $(patsubst %,$(SRC_DIR)/%,$(DOTTGT))
 
-IMGTGT := $(patsubst %.png,%.pdf,$(patsubst %.svg,%.pdf,$(IMAGES)))
+IMGTGT := $(patsubst %.svg,%.pdf,$(IMAGES))
 IMGPDF := $(patsubst %,$(SRC_DIR)/%,$(IMGTGT))
 
 cmd = $(echo-cmd) $(cmd_$(1))
@@ -38,19 +43,25 @@ cmd = $(echo-cmd) $(cmd_$(1))
 quiet_cmd_genpdf = GENPDF  $2
       cmd_genpdf = convert $2 $3
 
+quiet_cmd_gendot = DOT     $2
+      cmd_gendot = dot -Tsvg $2 > $3
+
 %.pdf: %.svg
 	@$(call cmd,genpdf,$<,$@)
 
+%.svg: %.dot
+	@$(call cmd,gendot,$<,$@)
+
 .PHONY: all html epub xml latex
 
-all: $(BUILDDIR) ${TARGETS}
+all: $(IMGDOT) $(BUILDDIR) ${TARGETS}
 html: all
 epub: all
 xml: all
 latex: $(IMGPDF) all
 
 clean:
-	-rm -f $(IMGTGT) 2>/dev/null
+	-rm -f $(DOTTGT) $(IMGTGT) $(patsubst %,$(SRC_DIR)/%,${TARGETS}) 2>/dev/null
 
 $(BUILDDIR):
 	$(Q)mkdir -p $@
@@ -95,6 +106,3 @@ $(BUILDDIR)/cec.h.rst: ${KAPI}/cec.h ${PARSER} $(SRC_DIR)/cec.h.rst.exceptions
 
 $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exceptions
 	@$($(quiet)gen_rst)
-
-cleandocs:
-	-rm -f ${TARGETS}
diff --git a/Documentation/media/uapi/v4l/pipeline.svg b/Documentation/media/uapi/v4l/pipeline.svg
deleted file mode 100644
index 70f4c1b23ca1..000000000000
--- a/Documentation/media/uapi/v4l/pipeline.svg
+++ /dev/null
@@ -1,68 +0,0 @@
-
-
-
-
-
-
-board
-
-
-scaler
-
-0
-
-Host
-Scaler
-
-1
-
-
-io
-
-0
-
-V4L I/O
-
-
-scaler:scaler_1->io:io_0
-
-
-HQ: 1280x720
-HS: 1280x720
-
-
-frontend
-
-0
-
-Host
-Frontend
-
-1
-
-
-frontend:frontend_1->scaler:scaler_0
-
-
-HQ: 2592x1968
-HS: 1296x984
-
-
-sensor
-
-Sensor
-
-0
-
-
-sensor:sensor_0->frontend:frontend_0
-
-
-HQ: 2592x1968
-HS: 1296x984
-
-
-
-- 
cgit v1.2.3


From bf5bfe85ec1e94c58becd3e2cb3385310bc68b81 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:18 -0200
Subject: docs-rst: media/Makefile: reorganize the rules

Better organize the media/Makefile, in order to better
split what's related to image conversion from the ones
related to parse-headers.pl.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/media/Makefile | 45 +++++++++++++++++++++++---------------------
 1 file changed, 24 insertions(+), 21 deletions(-)

diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index 547b4105f826..ab05323b779b 100644
--- a/Documentation/media/Makefile
+++ b/Documentation/media/Makefile
@@ -1,15 +1,7 @@
-# Generate the *.h.rst files from uAPI headers
+# Rules to convert DOT and SVG to Sphinx images
 
-PARSER = $(srctree)/Documentation/sphinx/parse-headers.pl
-UAPI = $(srctree)/include/uapi/linux
-KAPI = $(srctree)/include/linux
 SRC_DIR=$(srctree)/Documentation/media
 
-FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst net.h.rst video.h.rst \
-	  videodev2.h.rst media.h.rst cec.h.rst lirc.h.rst
-
-TARGETS := $(addprefix $(BUILDDIR)/, $(FILES))
-
 DOTS = \
 	uapi/v4l/pipeline.dot \
 
@@ -52,21 +44,16 @@ quiet_cmd_gendot = DOT     $2
 %.svg: %.dot
 	@$(call cmd,gendot,$<,$@)
 
-.PHONY: all html epub xml latex
-
-all: $(IMGDOT) $(BUILDDIR) ${TARGETS}
-html: all
-epub: all
-xml: all
-latex: $(IMGPDF) all
+# Rules to convert a .h file to inline RST documentation
 
-clean:
-	-rm -f $(DOTTGT) $(IMGTGT) $(patsubst %,$(SRC_DIR)/%,${TARGETS}) 2>/dev/null
+PARSER = $(srctree)/Documentation/sphinx/parse-headers.pl
+UAPI = $(srctree)/include/uapi/linux
+KAPI = $(srctree)/include/linux
 
-$(BUILDDIR):
-	$(Q)mkdir -p $@
+FILES = audio.h.rst ca.h.rst dmx.h.rst frontend.h.rst net.h.rst video.h.rst \
+	  videodev2.h.rst media.h.rst cec.h.rst lirc.h.rst
 
-# Rule to convert a .h file to inline RST documentation
+TARGETS := $(addprefix $(BUILDDIR)/, $(FILES))
 
 gen_rst = \
 	echo ${PARSER} $< $@ $(SRC_DIR)/$(notdir $@).exceptions; \
@@ -106,3 +93,19 @@ $(BUILDDIR)/cec.h.rst: ${KAPI}/cec.h ${PARSER} $(SRC_DIR)/cec.h.rst.exceptions
 
 $(BUILDDIR)/lirc.h.rst: ${UAPI}/lirc.h ${PARSER} $(SRC_DIR)/lirc.h.rst.exceptions
 	@$($(quiet)gen_rst)
+
+# Media build rules
+
+.PHONY: all html epub xml latex
+
+all: $(IMGDOT) $(BUILDDIR) ${TARGETS}
+html: all
+epub: all
+xml: all
+latex: $(IMGPDF) all
+
+clean:
+	-rm -f $(DOTTGT) $(IMGTGT) $(patsubst %,$(SRC_DIR)/%,${TARGETS}) 2>/dev/null
+
+$(BUILDDIR):
+	$(Q)mkdir -p $@
-- 
cgit v1.2.3


From 293fbd4fefec92f5d8e7d8256f9228a9aaf99070 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:19 -0200
Subject: docs-rst: fix media cleandocs target

The builddir prefix was missing on make cleandocs. Fix it.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/Makefile.sphinx | 2 +-
 Documentation/media/Makefile  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
index a23d3c8b4848..707c65337ebf 100644
--- a/Documentation/Makefile.sphinx
+++ b/Documentation/Makefile.sphinx
@@ -98,7 +98,7 @@ installmandocs:
 
 cleandocs:
 	$(Q)rm -rf $(BUILDDIR)
-	$(Q)$(MAKE) -C Documentation/media clean
+	$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) -C Documentation/media clean
 
 endif # HAVE_SPHINX
 
diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index ab05323b779b..4d8e2ff378c4 100644
--- a/Documentation/media/Makefile
+++ b/Documentation/media/Makefile
@@ -105,7 +105,7 @@ xml: all
 latex: $(IMGPDF) all
 
 clean:
-	-rm -f $(DOTTGT) $(IMGTGT) $(patsubst %,$(SRC_DIR)/%,${TARGETS}) 2>/dev/null
+	-rm -f $(DOTTGT) $(IMGTGT) ${TARGETS} 2>/dev/null
 
 $(BUILDDIR):
 	$(Q)mkdir -p $@
-- 
cgit v1.2.3


From c3396656666c2c98db306dc91c480d9fbde35cc9 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:20 -0200
Subject: docs-rst: parse-headers.pl: cleanup the documentation

Keeping both rst and in-file documentation in sync can be harsh.

So, simplify the script's internal documntation to a bare minimum,
and add a mention to the ReST file with its full documentation.

This way, a quick help is still available at the command line,
while the complete one is maintained at the ReST format.

As we won't be using pad2rst anymore, do a cleanup at the ReST
file.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/doc-guide/parse-headers.rst |  22 +-----
 Documentation/sphinx/parse-headers.pl     | 116 +++---------------------------
 2 files changed, 12 insertions(+), 126 deletions(-)

diff --git a/Documentation/doc-guide/parse-headers.rst b/Documentation/doc-guide/parse-headers.rst
index 615e25ec64bb..96a0423d5dba 100644
--- a/Documentation/doc-guide/parse-headers.rst
+++ b/Documentation/doc-guide/parse-headers.rst
@@ -18,13 +18,6 @@ about how to use it inside the Kernel tree.
 parse_headers.pl
 ^^^^^^^^^^^^^^^^
 
-.. NOTE: the man pages below were generated using pod2rst tool:
-.. http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst
-.. If you need to change anything below this point, please do the changes
-.. at parse-headers.pl directly, re-run the script and paste the output of
-.. the script here.
-
-****
 NAME
 ****
 
@@ -33,7 +26,6 @@ parse_headers.pl - parse a C file, in order to identify functions, structs,
 enums and defines and create cross-references to a Sphinx book.
 
 
-********
 SYNOPSIS
 ********
 
@@ -43,7 +35,6 @@ SYNOPSIS
 Where  can be: --debug, --help or --man.
 
 
-*******
 OPTIONS
 *******
 
@@ -55,20 +46,17 @@ OPTIONS
 
 
 
-\ **--help**\
+\ **--usage**\
 
  Prints a brief help message and exits.
 
 
 
-\ **--man**\
-
- Prints the manual page and exits.
-
+\ **--help**\
 
+ Prints a more detailed help message and exits.
 
 
-***********
 DESCRIPTION
 ***********
 
@@ -155,8 +143,6 @@ For both statements, \ **type**\  can be either one of the following:
 
 
 
-
-********
 EXAMPLES
 ********
 
@@ -187,7 +173,6 @@ It will make the BAR1 and BAR2 enum symbols to cross reference the foo
 symbol at the C domain.
 
 
-****
 BUGS
 ****
 
@@ -195,7 +180,6 @@ BUGS
 Report bugs to Mauro Carvalho Chehab 
 
 
-*********
 COPYRIGHT
 *********
 
diff --git a/Documentation/sphinx/parse-headers.pl b/Documentation/sphinx/parse-headers.pl
index 20dbdf55c71e..a958d8b5e99d 100755
--- a/Documentation/sphinx/parse-headers.pl
+++ b/Documentation/sphinx/parse-headers.pl
@@ -10,8 +10,8 @@ my $man;
 
 GetOptions(
 	"debug" => \$debug,
-	'help|?' => \$help,
-	man => \$man
+	'usage|?' => \$help,
+	'help' => \$man
 ) or pod2usage(2);
 
 pod2usage(1) if $help;
@@ -354,13 +354,13 @@ Where  can be: --debug, --help or --man.
 
 Put the script in verbose mode, useful for debugging.
 
-=item B<--help>
+=item B<--usage>
 
 Prints a brief help message and exits.
 
-=item B<--man>
+=item B<--help>
 
-Prints the manual page and exits.
+Prints a more detailed help message and exits.
 
 =back
 
@@ -379,109 +379,11 @@ enums and enum symbols and create cross-references for all of them.
 It is also capable of distinguish #define used for specifying a Linux
 ioctl.
 
-The EXCEPTIONS_FILE contain two types of statements: B or B.
-
-The syntax for the ignore tag is:
-
-=over 8
-
-ignore B B
-
-=back
-
-The B means that it won't generate cross references for a
-B symbol of type B.
-
-The syntax for the replace tag is:
-
-=over 8
-
-replace B B B
-
-=back
-
-The B means that it will generate cross references for a
-B symbol of type B, but, instead of using the default
-replacement rule, it will use B.
-
-For both statements, B can be either one of the following:
-
-=over 8
-
-=item B
-
-The ignore or replace statement will apply to ioctl definitions like:
-
-#define	VIDIOC_DBG_S_REGISTER 	 _IOW('V', 79, struct v4l2_dbg_register)
-
-=item B
-
-The ignore or replace statement will apply to any other #define found
-at C_FILE.
-
-=item B
-
-The ignore or replace statement will apply to typedef statements at C_FILE.
-
-=item B
-
-The ignore or replace statement will apply to the name of struct statements
-at C_FILE.
-
-=item B
-
-The ignore or replace statement will apply to the name of enum statements
-at C_FILE.
+The EXCEPTIONS_FILE contain two rules to allow ignoring a symbol or
+to replace the default references by a custom one.
 
-=item B
-
-The ignore or replace statement will apply to the name of enum statements
-at C_FILE.
-
-
-For replace statements, B will automatically use :c:type:
-references for B, B and B types. It will use :ref:
-for B, B and B types. The type of reference can
-also be explicitly defined at the replace statement.
-
-=back
-
-=head1 EXAMPLES
-
-ignore define _VIDEODEV2_H
-
-=over 8
-
-
-Ignore a #define _VIDEODEV2_H at the C_FILE.
-
-=back
-
-ignore symbol PRIVATE
-
-=over 8
-
-On a struct like:
-
-enum foo { BAR1, BAR2, PRIVATE };
-
-It won't generate cross-references for B.
-
-=back
-
-replace symbol BAR1 :c:type:`foo`
-replace symbol BAR2 :c:type:`foo`
-
-=over 8
-
-On a struct like:
-
-enum foo { BAR1, BAR2, PRIVATE };
-
-It will make the BAR1 and BAR2 enum symbols to cross reference the foo
-symbol at the C domain.
-
-=back
+Please read Documentation/doc-guide/parse-headers.rst at the Kernel's
+tree for more details.
 
 =head1 BUGS
 
-- 
cgit v1.2.3


From c3cbf1a704797bc6ba4d3b6cfd766a091081eeaa Mon Sep 17 00:00:00 2001
From: Silvio Fricke 
Date: Mon, 28 Nov 2016 18:30:53 +0100
Subject: Documentation/assoc_array.txt: convert to ReST markup

... and move to Documentation/core-api folder.

Signed-off-by: Silvio Fricke 
Reviewed-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/assoc_array.txt          | 574 ---------------------------------
 Documentation/core-api/assoc_array.rst | 551 +++++++++++++++++++++++++++++++
 Documentation/core-api/index.rst       |   1 +
 3 files changed, 552 insertions(+), 574 deletions(-)
 delete mode 100644 Documentation/assoc_array.txt
 create mode 100644 Documentation/core-api/assoc_array.rst

diff --git a/Documentation/assoc_array.txt b/Documentation/assoc_array.txt
deleted file mode 100644
index 2f2c6cdd73c0..000000000000
--- a/Documentation/assoc_array.txt
+++ /dev/null
@@ -1,574 +0,0 @@
-		   ========================================
-		   GENERIC ASSOCIATIVE ARRAY IMPLEMENTATION
-		   ========================================
-
-Contents:
-
- - Overview.
-
- - The public API.
-   - Edit script.
-   - Operations table.
-   - Manipulation functions.
-   - Access functions.
-   - Index key form.
-
- - Internal workings.
-   - Basic internal tree layout.
-   - Shortcuts.
-   - Splitting and collapsing nodes.
-   - Non-recursive iteration.
-   - Simultaneous alteration and iteration.
-
-
-========
-OVERVIEW
-========
-
-This associative array implementation is an object container with the following
-properties:
-
- (1) Objects are opaque pointers.  The implementation does not care where they
-     point (if anywhere) or what they point to (if anything).
-
-     [!] NOTE: Pointers to objects _must_ be zero in the least significant bit.
-
- (2) Objects do not need to contain linkage blocks for use by the array.  This
-     permits an object to be located in multiple arrays simultaneously.
-     Rather, the array is made up of metadata blocks that point to objects.
-
- (3) Objects require index keys to locate them within the array.
-
- (4) Index keys must be unique.  Inserting an object with the same key as one
-     already in the array will replace the old object.
-
- (5) Index keys can be of any length and can be of different lengths.
-
- (6) Index keys should encode the length early on, before any variation due to
-     length is seen.
-
- (7) Index keys can include a hash to scatter objects throughout the array.
-
- (8) The array can iterated over.  The objects will not necessarily come out in
-     key order.
-
- (9) The array can be iterated over whilst it is being modified, provided the
-     RCU readlock is being held by the iterator.  Note, however, under these
-     circumstances, some objects may be seen more than once.  If this is a
-     problem, the iterator should lock against modification.  Objects will not
-     be missed, however, unless deleted.
-
-(10) Objects in the array can be looked up by means of their index key.
-
-(11) Objects can be looked up whilst the array is being modified, provided the
-     RCU readlock is being held by the thread doing the look up.
-
-The implementation uses a tree of 16-pointer nodes internally that are indexed
-on each level by nibbles from the index key in the same manner as in a radix
-tree.  To improve memory efficiency, shortcuts can be emplaced to skip over
-what would otherwise be a series of single-occupancy nodes.  Further, nodes
-pack leaf object pointers into spare space in the node rather than making an
-extra branch until as such time an object needs to be added to a full node.
-
-
-==============
-THE PUBLIC API
-==============
-
-The public API can be found in .  The associative array is
-rooted on the following structure:
-
-	struct assoc_array {
-		...
-	};
-
-The code is selected by enabling CONFIG_ASSOCIATIVE_ARRAY.
-
-
-EDIT SCRIPT
------------
-
-The insertion and deletion functions produce an 'edit script' that can later be
-applied to effect the changes without risking ENOMEM.  This retains the
-preallocated metadata blocks that will be installed in the internal tree and
-keeps track of the metadata blocks that will be removed from the tree when the
-script is applied.
-
-This is also used to keep track of dead blocks and dead objects after the
-script has been applied so that they can be freed later.  The freeing is done
-after an RCU grace period has passed - thus allowing access functions to
-proceed under the RCU read lock.
-
-The script appears as outside of the API as a pointer of the type:
-
-	struct assoc_array_edit;
-
-There are two functions for dealing with the script:
-
- (1) Apply an edit script.
-
-	void assoc_array_apply_edit(struct assoc_array_edit *edit);
-
-     This will perform the edit functions, interpolating various write barriers
-     to permit accesses under the RCU read lock to continue.  The edit script
-     will then be passed to call_rcu() to free it and any dead stuff it points
-     to.
-
- (2) Cancel an edit script.
-
-	void assoc_array_cancel_edit(struct assoc_array_edit *edit);
-
-     This frees the edit script and all preallocated memory immediately.  If
-     this was for insertion, the new object is _not_ released by this function,
-     but must rather be released by the caller.
-
-These functions are guaranteed not to fail.
-
-
-OPERATIONS TABLE
-----------------
-
-Various functions take a table of operations:
-
-	struct assoc_array_ops {
-		...
-	};
-
-This points to a number of methods, all of which need to be provided:
-
- (1) Get a chunk of index key from caller data:
-
-	unsigned long (*get_key_chunk)(const void *index_key, int level);
-
-     This should return a chunk of caller-supplied index key starting at the
-     *bit* position given by the level argument.  The level argument will be a
-     multiple of ASSOC_ARRAY_KEY_CHUNK_SIZE and the function should return
-     ASSOC_ARRAY_KEY_CHUNK_SIZE bits.  No error is possible.
-
-
- (2) Get a chunk of an object's index key.
-
-	unsigned long (*get_object_key_chunk)(const void *object, int level);
-
-     As the previous function, but gets its data from an object in the array
-     rather than from a caller-supplied index key.
-
-
- (3) See if this is the object we're looking for.
-
-	bool (*compare_object)(const void *object, const void *index_key);
-
-     Compare the object against an index key and return true if it matches and
-     false if it doesn't.
-
-
- (4) Diff the index keys of two objects.
-
-	int (*diff_objects)(const void *object, const void *index_key);
-
-     Return the bit position at which the index key of the specified object
-     differs from the given index key or -1 if they are the same.
-
-
- (5) Free an object.
-
-	void (*free_object)(void *object);
-
-     Free the specified object.  Note that this may be called an RCU grace
-     period after assoc_array_apply_edit() was called, so synchronize_rcu() may
-     be necessary on module unloading.
-
-
-MANIPULATION FUNCTIONS
-----------------------
-
-There are a number of functions for manipulating an associative array:
-
- (1) Initialise an associative array.
-
-	void assoc_array_init(struct assoc_array *array);
-
-     This initialises the base structure for an associative array.  It can't
-     fail.
-
-
- (2) Insert/replace an object in an associative array.
-
-	struct assoc_array_edit *
-	assoc_array_insert(struct assoc_array *array,
-			   const struct assoc_array_ops *ops,
-			   const void *index_key,
-			   void *object);
-
-     This inserts the given object into the array.  Note that the least
-     significant bit of the pointer must be zero as it's used to type-mark
-     pointers internally.
-
-     If an object already exists for that key then it will be replaced with the
-     new object and the old one will be freed automatically.
-
-     The index_key argument should hold index key information and is
-     passed to the methods in the ops table when they are called.
-
-     This function makes no alteration to the array itself, but rather returns
-     an edit script that must be applied.  -ENOMEM is returned in the case of
-     an out-of-memory error.
-
-     The caller should lock exclusively against other modifiers of the array.
-
-
- (3) Delete an object from an associative array.
-
-	struct assoc_array_edit *
-	assoc_array_delete(struct assoc_array *array,
-			   const struct assoc_array_ops *ops,
-			   const void *index_key);
-
-     This deletes an object that matches the specified data from the array.
-
-     The index_key argument should hold index key information and is
-     passed to the methods in the ops table when they are called.
-
-     This function makes no alteration to the array itself, but rather returns
-     an edit script that must be applied.  -ENOMEM is returned in the case of
-     an out-of-memory error.  NULL will be returned if the specified object is
-     not found within the array.
-
-     The caller should lock exclusively against other modifiers of the array.
-
-
- (4) Delete all objects from an associative array.
-
-	struct assoc_array_edit *
-	assoc_array_clear(struct assoc_array *array,
-			  const struct assoc_array_ops *ops);
-
-     This deletes all the objects from an associative array and leaves it
-     completely empty.
-
-     This function makes no alteration to the array itself, but rather returns
-     an edit script that must be applied.  -ENOMEM is returned in the case of
-     an out-of-memory error.
-
-     The caller should lock exclusively against other modifiers of the array.
-
-
- (5) Destroy an associative array, deleting all objects.
-
-	void assoc_array_destroy(struct assoc_array *array,
-				 const struct assoc_array_ops *ops);
-
-     This destroys the contents of the associative array and leaves it
-     completely empty.  It is not permitted for another thread to be traversing
-     the array under the RCU read lock at the same time as this function is
-     destroying it as no RCU deferral is performed on memory release -
-     something that would require memory to be allocated.
-
-     The caller should lock exclusively against other modifiers and accessors
-     of the array.
-
-
- (6) Garbage collect an associative array.
-
-	int assoc_array_gc(struct assoc_array *array,
-			   const struct assoc_array_ops *ops,
-			   bool (*iterator)(void *object, void *iterator_data),
-			   void *iterator_data);
-
-     This iterates over the objects in an associative array and passes each one
-     to iterator().  If iterator() returns true, the object is kept.  If it
-     returns false, the object will be freed.  If the iterator() function
-     returns true, it must perform any appropriate refcount incrementing on the
-     object before returning.
-
-     The internal tree will be packed down if possible as part of the iteration
-     to reduce the number of nodes in it.
-
-     The iterator_data is passed directly to iterator() and is otherwise
-     ignored by the function.
-
-     The function will return 0 if successful and -ENOMEM if there wasn't
-     enough memory.
-
-     It is possible for other threads to iterate over or search the array under
-     the RCU read lock whilst this function is in progress.  The caller should
-     lock exclusively against other modifiers of the array.
-
-
-ACCESS FUNCTIONS
-----------------
-
-There are two functions for accessing an associative array:
-
- (1) Iterate over all the objects in an associative array.
-
-	int assoc_array_iterate(const struct assoc_array *array,
-				int (*iterator)(const void *object,
-						void *iterator_data),
-				void *iterator_data);
-
-     This passes each object in the array to the iterator callback function.
-     iterator_data is private data for that function.
-
-     This may be used on an array at the same time as the array is being
-     modified, provided the RCU read lock is held.  Under such circumstances,
-     it is possible for the iteration function to see some objects twice.  If
-     this is a problem, then modification should be locked against.  The
-     iteration algorithm should not, however, miss any objects.
-
-     The function will return 0 if no objects were in the array or else it will
-     return the result of the last iterator function called.  Iteration stops
-     immediately if any call to the iteration function results in a non-zero
-     return.
-
-
- (2) Find an object in an associative array.
-
-	void *assoc_array_find(const struct assoc_array *array,
-			       const struct assoc_array_ops *ops,
-			       const void *index_key);
-
-     This walks through the array's internal tree directly to the object
-     specified by the index key..
-
-     This may be used on an array at the same time as the array is being
-     modified, provided the RCU read lock is held.
-
-     The function will return the object if found (and set *_type to the object
-     type) or will return NULL if the object was not found.
-
-
-INDEX KEY FORM
---------------
-
-The index key can be of any form, but since the algorithms aren't told how long
-the key is, it is strongly recommended that the index key includes its length
-very early on before any variation due to the length would have an effect on
-comparisons.
-
-This will cause leaves with different length keys to scatter away from each
-other - and those with the same length keys to cluster together.
-
-It is also recommended that the index key begin with a hash of the rest of the
-key to maximise scattering throughout keyspace.
-
-The better the scattering, the wider and lower the internal tree will be.
-
-Poor scattering isn't too much of a problem as there are shortcuts and nodes
-can contain mixtures of leaves and metadata pointers.
-
-The index key is read in chunks of machine word.  Each chunk is subdivided into
-one nibble (4 bits) per level, so on a 32-bit CPU this is good for 8 levels and
-on a 64-bit CPU, 16 levels.  Unless the scattering is really poor, it is
-unlikely that more than one word of any particular index key will have to be
-used.
-
-
-=================
-INTERNAL WORKINGS
-=================
-
-The associative array data structure has an internal tree.  This tree is
-constructed of two types of metadata blocks: nodes and shortcuts.
-
-A node is an array of slots.  Each slot can contain one of four things:
-
- (*) A NULL pointer, indicating that the slot is empty.
-
- (*) A pointer to an object (a leaf).
-
- (*) A pointer to a node at the next level.
-
- (*) A pointer to a shortcut.
-
-
-BASIC INTERNAL TREE LAYOUT
---------------------------
-
-Ignoring shortcuts for the moment, the nodes form a multilevel tree.  The index
-key space is strictly subdivided by the nodes in the tree and nodes occur on
-fixed levels.  For example:
-
- Level:	0		1		2		3
-	===============	===============	===============	===============
-							NODE D
-			NODE B		NODE C	+------>+---+
-		+------>+---+	+------>+---+	|	| 0 |
-	NODE A	|	| 0 |	|	| 0 |	|	+---+
-	+---+	|	+---+	|	+---+	|	:   :
-	| 0 |	|	:   :	|	:   :	|	+---+
-	+---+	|	+---+	|	+---+	|	| f |
-	| 1 |---+	| 3 |---+	| 7 |---+	+---+
-	+---+		+---+		+---+
-	:   :		:   :		| 8 |---+
-	+---+		+---+		+---+	|	NODE E
-	| e |---+	| f |		:   :   +------>+---+
-	+---+	|	+---+		+---+		| 0 |
-	| f |	|			| f |		+---+
-	+---+	|			+---+		:   :
-		|	NODE F				+---+
-		+------>+---+				| f |
-			| 0 |		NODE G		+---+
-			+---+	+------>+---+
-			:   :	|	| 0 |
-			+---+	|	+---+
-			| 6 |---+	:   :
-			+---+		+---+
-			:   :		| f |
-			+---+		+---+
-			| f |
-			+---+
-
-In the above example, there are 7 nodes (A-G), each with 16 slots (0-f).
-Assuming no other meta data nodes in the tree, the key space is divided thusly:
-
-	KEY PREFIX	NODE
-	==========	====
-	137*		D
-	138*		E
-	13[0-69-f]*	C
-	1[0-24-f]*	B
-	e6*		G
-	e[0-57-f]*	F
-	[02-df]*	A
-
-So, for instance, keys with the following example index keys will be found in
-the appropriate nodes:
-
-	INDEX KEY	PREFIX	NODE
-	===============	=======	====
-	13694892892489	13	C
-	13795289025897	137	D
-	13889dde88793	138	E
-	138bbb89003093	138	E
-	1394879524789	12	C
-	1458952489	1	B
-	9431809de993ba	-	A
-	b4542910809cd	-	A
-	e5284310def98	e	F
-	e68428974237	e6	G
-	e7fffcbd443	e	F
-	f3842239082	-	A
-
-To save memory, if a node can hold all the leaves in its portion of keyspace,
-then the node will have all those leaves in it and will not have any metadata
-pointers - even if some of those leaves would like to be in the same slot.
-
-A node can contain a heterogeneous mix of leaves and metadata pointers.
-Metadata pointers must be in the slots that match their subdivisions of key
-space.  The leaves can be in any slot not occupied by a metadata pointer.  It
-is guaranteed that none of the leaves in a node will match a slot occupied by a
-metadata pointer.  If the metadata pointer is there, any leaf whose key matches
-the metadata key prefix must be in the subtree that the metadata pointer points
-to.
-
-In the above example list of index keys, node A will contain:
-
-	SLOT	CONTENT		INDEX KEY (PREFIX)
-	====	===============	==================
-	1	PTR TO NODE B	1*
-	any	LEAF		9431809de993ba
-	any	LEAF		b4542910809cd
-	e	PTR TO NODE F	e*
-	any	LEAF		f3842239082
-
-and node B:
-
-	3	PTR TO NODE C	13*
-	any	LEAF		1458952489
-
-
-SHORTCUTS
----------
-
-Shortcuts are metadata records that jump over a piece of keyspace.  A shortcut
-is a replacement for a series of single-occupancy nodes ascending through the
-levels.  Shortcuts exist to save memory and to speed up traversal.
-
-It is possible for the root of the tree to be a shortcut - say, for example,
-the tree contains at least 17 nodes all with key prefix '1111'.  The insertion
-algorithm will insert a shortcut to skip over the '1111' keyspace in a single
-bound and get to the fourth level where these actually become different.
-
-
-SPLITTING AND COLLAPSING NODES
-------------------------------
-
-Each node has a maximum capacity of 16 leaves and metadata pointers.  If the
-insertion algorithm finds that it is trying to insert a 17th object into a
-node, that node will be split such that at least two leaves that have a common
-key segment at that level end up in a separate node rooted on that slot for
-that common key segment.
-
-If the leaves in a full node and the leaf that is being inserted are
-sufficiently similar, then a shortcut will be inserted into the tree.
-
-When the number of objects in the subtree rooted at a node falls to 16 or
-fewer, then the subtree will be collapsed down to a single node - and this will
-ripple towards the root if possible.
-
-
-NON-RECURSIVE ITERATION
------------------------
-
-Each node and shortcut contains a back pointer to its parent and the number of
-slot in that parent that points to it.  None-recursive iteration uses these to
-proceed rootwards through the tree, going to the parent node, slot N + 1 to
-make sure progress is made without the need for a stack.
-
-The backpointers, however, make simultaneous alteration and iteration tricky.
-
-
-SIMULTANEOUS ALTERATION AND ITERATION
--------------------------------------
-
-There are a number of cases to consider:
-
- (1) Simple insert/replace.  This involves simply replacing a NULL or old
-     matching leaf pointer with the pointer to the new leaf after a barrier.
-     The metadata blocks don't change otherwise.  An old leaf won't be freed
-     until after the RCU grace period.
-
- (2) Simple delete.  This involves just clearing an old matching leaf.  The
-     metadata blocks don't change otherwise.  The old leaf won't be freed until
-     after the RCU grace period.
-
- (3) Insertion replacing part of a subtree that we haven't yet entered.  This
-     may involve replacement of part of that subtree - but that won't affect
-     the iteration as we won't have reached the pointer to it yet and the
-     ancestry blocks are not replaced (the layout of those does not change).
-
- (4) Insertion replacing nodes that we're actively processing.  This isn't a
-     problem as we've passed the anchoring pointer and won't switch onto the
-     new layout until we follow the back pointers - at which point we've
-     already examined the leaves in the replaced node (we iterate over all the
-     leaves in a node before following any of its metadata pointers).
-
-     We might, however, re-see some leaves that have been split out into a new
-     branch that's in a slot further along than we were at.
-
- (5) Insertion replacing nodes that we're processing a dependent branch of.
-     This won't affect us until we follow the back pointers.  Similar to (4).
-
- (6) Deletion collapsing a branch under us.  This doesn't affect us because the
-     back pointers will get us back to the parent of the new node before we
-     could see the new node.  The entire collapsed subtree is thrown away
-     unchanged - and will still be rooted on the same slot, so we shouldn't
-     process it a second time as we'll go back to slot + 1.
-
-Note:
-
- (*) Under some circumstances, we need to simultaneously change the parent
-     pointer and the parent slot pointer on a node (say, for example, we
-     inserted another node before it and moved it up a level).  We cannot do
-     this without locking against a read - so we have to replace that node too.
-
-     However, when we're changing a shortcut into a node this isn't a problem
-     as shortcuts only have one slot and so the parent slot number isn't used
-     when traversing backwards over one.  This means that it's okay to change
-     the slot number first - provided suitable barriers are used to make sure
-     the parent slot number is read after the back pointer.
-
-Obsolete blocks and leaves are freed up after an RCU grace period has passed,
-so as long as anyone doing walking or iteration holds the RCU read lock, the
-old superstructure should not go away on them.
diff --git a/Documentation/core-api/assoc_array.rst b/Documentation/core-api/assoc_array.rst
new file mode 100644
index 000000000000..dcda7c623cec
--- /dev/null
+++ b/Documentation/core-api/assoc_array.rst
@@ -0,0 +1,551 @@
+========================================
+Generic Associative Array Implementation
+========================================
+
+Overview
+========
+
+This associative array implementation is an object container with the following
+properties:
+
+1. Objects are opaque pointers.  The implementation does not care where they
+   point (if anywhere) or what they point to (if anything).
+.. note:: Pointers to objects _must_ be zero in the least significant bit.**
+
+2. Objects do not need to contain linkage blocks for use by the array.  This
+   permits an object to be located in multiple arrays simultaneously.
+   Rather, the array is made up of metadata blocks that point to objects.
+
+3. Objects require index keys to locate them within the array.
+
+4. Index keys must be unique.  Inserting an object with the same key as one
+   already in the array will replace the old object.
+
+5. Index keys can be of any length and can be of different lengths.
+
+6. Index keys should encode the length early on, before any variation due to
+   length is seen.
+
+7. Index keys can include a hash to scatter objects throughout the array.
+
+8. The array can iterated over.  The objects will not necessarily come out in
+   key order.
+
+9. The array can be iterated over whilst it is being modified, provided the
+   RCU readlock is being held by the iterator.  Note, however, under these
+   circumstances, some objects may be seen more than once.  If this is a
+   problem, the iterator should lock against modification.  Objects will not
+   be missed, however, unless deleted.
+
+10. Objects in the array can be looked up by means of their index key.
+
+11. Objects can be looked up whilst the array is being modified, provided the
+    RCU readlock is being held by the thread doing the look up.
+
+The implementation uses a tree of 16-pointer nodes internally that are indexed
+on each level by nibbles from the index key in the same manner as in a radix
+tree.  To improve memory efficiency, shortcuts can be emplaced to skip over
+what would otherwise be a series of single-occupancy nodes.  Further, nodes
+pack leaf object pointers into spare space in the node rather than making an
+extra branch until as such time an object needs to be added to a full node.
+
+
+The Public API
+==============
+
+The public API can be found in ````.  The associative
+array is rooted on the following structure::
+
+    struct assoc_array {
+            ...
+    };
+
+The code is selected by enabling ``CONFIG_ASSOCIATIVE_ARRAY`` with::
+
+    ./script/config -e ASSOCIATIVE_ARRAY
+
+
+Edit Script
+-----------
+
+The insertion and deletion functions produce an 'edit script' that can later be
+applied to effect the changes without risking ``ENOMEM``. This retains the
+preallocated metadata blocks that will be installed in the internal tree and
+keeps track of the metadata blocks that will be removed from the tree when the
+script is applied.
+
+This is also used to keep track of dead blocks and dead objects after the
+script has been applied so that they can be freed later.  The freeing is done
+after an RCU grace period has passed - thus allowing access functions to
+proceed under the RCU read lock.
+
+The script appears as outside of the API as a pointer of the type::
+
+    struct assoc_array_edit;
+
+There are two functions for dealing with the script:
+
+1. Apply an edit script::
+
+    void assoc_array_apply_edit(struct assoc_array_edit *edit);
+
+This will perform the edit functions, interpolating various write barriers
+to permit accesses under the RCU read lock to continue.  The edit script
+will then be passed to ``call_rcu()`` to free it and any dead stuff it points
+to.
+
+2. Cancel an edit script::
+
+    void assoc_array_cancel_edit(struct assoc_array_edit *edit);
+
+This frees the edit script and all preallocated memory immediately. If
+this was for insertion, the new object is _not_ released by this function,
+but must rather be released by the caller.
+
+These functions are guaranteed not to fail.
+
+
+Operations Table
+----------------
+
+Various functions take a table of operations::
+
+    struct assoc_array_ops {
+            ...
+    };
+
+This points to a number of methods, all of which need to be provided:
+
+1. Get a chunk of index key from caller data::
+
+    unsigned long (*get_key_chunk)(const void *index_key, int level);
+
+This should return a chunk of caller-supplied index key starting at the
+*bit* position given by the level argument.  The level argument will be a
+multiple of ``ASSOC_ARRAY_KEY_CHUNK_SIZE`` and the function should return
+``ASSOC_ARRAY_KEY_CHUNK_SIZE bits``.  No error is possible.
+
+
+2. Get a chunk of an object's index key::
+
+    unsigned long (*get_object_key_chunk)(const void *object, int level);
+
+As the previous function, but gets its data from an object in the array
+rather than from a caller-supplied index key.
+
+
+3. See if this is the object we're looking for::
+
+    bool (*compare_object)(const void *object, const void *index_key);
+
+Compare the object against an index key and return ``true`` if it matches and
+``false`` if it doesn't.
+
+
+4. Diff the index keys of two objects::
+
+    int (*diff_objects)(const void *object, const void *index_key);
+
+Return the bit position at which the index key of the specified object
+differs from the given index key or -1 if they are the same.
+
+
+5. Free an object::
+
+    void (*free_object)(void *object);
+
+Free the specified object.  Note that this may be called an RCU grace period
+after ``assoc_array_apply_edit()`` was called, so ``synchronize_rcu()`` may be
+necessary on module unloading.
+
+
+Manipulation Functions
+----------------------
+
+There are a number of functions for manipulating an associative array:
+
+1. Initialise an associative array::
+
+    void assoc_array_init(struct assoc_array *array);
+
+This initialises the base structure for an associative array.  It can't fail.
+
+
+2. Insert/replace an object in an associative array::
+
+    struct assoc_array_edit *
+    assoc_array_insert(struct assoc_array *array,
+                       const struct assoc_array_ops *ops,
+                       const void *index_key,
+                       void *object);
+
+This inserts the given object into the array.  Note that the least
+significant bit of the pointer must be zero as it's used to type-mark
+pointers internally.
+
+If an object already exists for that key then it will be replaced with the
+new object and the old one will be freed automatically.
+
+The ``index_key`` argument should hold index key information and is
+passed to the methods in the ops table when they are called.
+
+This function makes no alteration to the array itself, but rather returns
+an edit script that must be applied.  ``-ENOMEM`` is returned in the case of
+an out-of-memory error.
+
+The caller should lock exclusively against other modifiers of the array.
+
+
+3. Delete an object from an associative array::
+
+    struct assoc_array_edit *
+    assoc_array_delete(struct assoc_array *array,
+                       const struct assoc_array_ops *ops,
+                       const void *index_key);
+
+This deletes an object that matches the specified data from the array.
+
+The ``index_key`` argument should hold index key information and is
+passed to the methods in the ops table when they are called.
+
+This function makes no alteration to the array itself, but rather returns
+an edit script that must be applied.  ``-ENOMEM`` is returned in the case of
+an out-of-memory error.  ``NULL`` will be returned if the specified object is
+not found within the array.
+
+The caller should lock exclusively against other modifiers of the array.
+
+
+4. Delete all objects from an associative array::
+
+    struct assoc_array_edit *
+    assoc_array_clear(struct assoc_array *array,
+                      const struct assoc_array_ops *ops);
+
+This deletes all the objects from an associative array and leaves it
+completely empty.
+
+This function makes no alteration to the array itself, but rather returns
+an edit script that must be applied.  ``-ENOMEM`` is returned in the case of
+an out-of-memory error.
+
+The caller should lock exclusively against other modifiers of the array.
+
+
+5. Destroy an associative array, deleting all objects::
+
+    void assoc_array_destroy(struct assoc_array *array,
+                             const struct assoc_array_ops *ops);
+
+This destroys the contents of the associative array and leaves it
+completely empty.  It is not permitted for another thread to be traversing
+the array under the RCU read lock at the same time as this function is
+destroying it as no RCU deferral is performed on memory release -
+something that would require memory to be allocated.
+
+The caller should lock exclusively against other modifiers and accessors
+of the array.
+
+
+6. Garbage collect an associative array::
+
+    int assoc_array_gc(struct assoc_array *array,
+                       const struct assoc_array_ops *ops,
+                       bool (*iterator)(void *object, void *iterator_data),
+                       void *iterator_data);
+
+This iterates over the objects in an associative array and passes each one to
+``iterator()``.  If ``iterator()`` returns ``true``, the object is kept.  If it
+returns ``false``, the object will be freed.  If the ``iterator()`` function
+returns ``true``, it must perform any appropriate refcount incrementing on the
+object before returning.
+
+The internal tree will be packed down if possible as part of the iteration
+to reduce the number of nodes in it.
+
+The ``iterator_data`` is passed directly to ``iterator()`` and is otherwise
+ignored by the function.
+
+The function will return ``0`` if successful and ``-ENOMEM`` if there wasn't
+enough memory.
+
+It is possible for other threads to iterate over or search the array under
+the RCU read lock whilst this function is in progress.  The caller should
+lock exclusively against other modifiers of the array.
+
+
+Access Functions
+----------------
+
+There are two functions for accessing an associative array:
+
+1. Iterate over all the objects in an associative array::
+
+    int assoc_array_iterate(const struct assoc_array *array,
+                            int (*iterator)(const void *object,
+                                            void *iterator_data),
+                            void *iterator_data);
+
+This passes each object in the array to the iterator callback function.
+``iterator_data`` is private data for that function.
+
+This may be used on an array at the same time as the array is being
+modified, provided the RCU read lock is held.  Under such circumstances,
+it is possible for the iteration function to see some objects twice.  If
+this is a problem, then modification should be locked against.  The
+iteration algorithm should not, however, miss any objects.
+
+The function will return ``0`` if no objects were in the array or else it will
+return the result of the last iterator function called.  Iteration stops
+immediately if any call to the iteration function results in a non-zero
+return.
+
+
+2. Find an object in an associative array::
+
+    void *assoc_array_find(const struct assoc_array *array,
+                           const struct assoc_array_ops *ops,
+                           const void *index_key);
+
+This walks through the array's internal tree directly to the object
+specified by the index key..
+
+This may be used on an array at the same time as the array is being
+modified, provided the RCU read lock is held.
+
+The function will return the object if found (and set ``*_type`` to the object
+type) or will return ``NULL`` if the object was not found.
+
+
+Index Key Form
+--------------
+
+The index key can be of any form, but since the algorithms aren't told how long
+the key is, it is strongly recommended that the index key includes its length
+very early on before any variation due to the length would have an effect on
+comparisons.
+
+This will cause leaves with different length keys to scatter away from each
+other - and those with the same length keys to cluster together.
+
+It is also recommended that the index key begin with a hash of the rest of the
+key to maximise scattering throughout keyspace.
+
+The better the scattering, the wider and lower the internal tree will be.
+
+Poor scattering isn't too much of a problem as there are shortcuts and nodes
+can contain mixtures of leaves and metadata pointers.
+
+The index key is read in chunks of machine word.  Each chunk is subdivided into
+one nibble (4 bits) per level, so on a 32-bit CPU this is good for 8 levels and
+on a 64-bit CPU, 16 levels.  Unless the scattering is really poor, it is
+unlikely that more than one word of any particular index key will have to be
+used.
+
+
+Internal Workings
+=================
+
+The associative array data structure has an internal tree.  This tree is
+constructed of two types of metadata blocks: nodes and shortcuts.
+
+A node is an array of slots.  Each slot can contain one of four things:
+
+* A NULL pointer, indicating that the slot is empty.
+* A pointer to an object (a leaf).
+* A pointer to a node at the next level.
+* A pointer to a shortcut.
+
+
+Basic Internal Tree Layout
+--------------------------
+
+Ignoring shortcuts for the moment, the nodes form a multilevel tree.  The index
+key space is strictly subdivided by the nodes in the tree and nodes occur on
+fixed levels.  For example::
+
+ Level: 0               1               2               3
+        =============== =============== =============== ===============
+                                                        NODE D
+                        NODE B          NODE C  +------>+---+
+                +------>+---+   +------>+---+   |       | 0 |
+        NODE A  |       | 0 |   |       | 0 |   |       +---+
+        +---+   |       +---+   |       +---+   |       :   :
+        | 0 |   |       :   :   |       :   :   |       +---+
+        +---+   |       +---+   |       +---+   |       | f |
+        | 1 |---+       | 3 |---+       | 7 |---+       +---+
+        +---+           +---+           +---+
+        :   :           :   :           | 8 |---+
+        +---+           +---+           +---+   |       NODE E
+        | e |---+       | f |           :   :   +------>+---+
+        +---+   |       +---+           +---+           | 0 |
+        | f |   |                       | f |           +---+
+        +---+   |                       +---+           :   :
+                |       NODE F                          +---+
+                +------>+---+                           | f |
+                        | 0 |           NODE G          +---+
+                        +---+   +------>+---+
+                        :   :   |       | 0 |
+                        +---+   |       +---+
+                        | 6 |---+       :   :
+                        +---+           +---+
+                        :   :           | f |
+                        +---+           +---+
+                        | f |
+                        +---+
+
+In the above example, there are 7 nodes (A-G), each with 16 slots (0-f).
+Assuming no other meta data nodes in the tree, the key space is divided
+thusly::
+
+    KEY PREFIX      NODE
+    ==========      ====
+    137*            D
+    138*            E
+    13[0-69-f]*     C
+    1[0-24-f]*      B
+    e6*             G
+    e[0-57-f]*      F
+    [02-df]*        A
+
+So, for instance, keys with the following example index keys will be found in
+the appropriate nodes::
+
+    INDEX KEY       PREFIX  NODE
+    =============== ======= ====
+    13694892892489  13      C
+    13795289025897  137     D
+    13889dde88793   138     E
+    138bbb89003093  138     E
+    1394879524789   12      C
+    1458952489      1       B
+    9431809de993ba  -       A
+    b4542910809cd   -       A
+    e5284310def98   e       F
+    e68428974237    e6      G
+    e7fffcbd443     e       F
+    f3842239082     -       A
+
+To save memory, if a node can hold all the leaves in its portion of keyspace,
+then the node will have all those leaves in it and will not have any metadata
+pointers - even if some of those leaves would like to be in the same slot.
+
+A node can contain a heterogeneous mix of leaves and metadata pointers.
+Metadata pointers must be in the slots that match their subdivisions of key
+space.  The leaves can be in any slot not occupied by a metadata pointer.  It
+is guaranteed that none of the leaves in a node will match a slot occupied by a
+metadata pointer.  If the metadata pointer is there, any leaf whose key matches
+the metadata key prefix must be in the subtree that the metadata pointer points
+to.
+
+In the above example list of index keys, node A will contain::
+
+    SLOT    CONTENT         INDEX KEY (PREFIX)
+    ====    =============== ==================
+    1       PTR TO NODE B   1*
+    any     LEAF            9431809de993ba
+    any     LEAF            b4542910809cd
+    e       PTR TO NODE F   e*
+    any     LEAF            f3842239082
+
+and node B::
+
+    3	PTR TO NODE C	13*
+    any	LEAF		1458952489
+
+
+Shortcuts
+---------
+
+Shortcuts are metadata records that jump over a piece of keyspace.  A shortcut
+is a replacement for a series of single-occupancy nodes ascending through the
+levels.  Shortcuts exist to save memory and to speed up traversal.
+
+It is possible for the root of the tree to be a shortcut - say, for example,
+the tree contains at least 17 nodes all with key prefix ``1111``.  The
+insertion algorithm will insert a shortcut to skip over the ``1111`` keyspace
+in a single bound and get to the fourth level where these actually become
+different.
+
+
+Splitting And Collapsing Nodes
+------------------------------
+
+Each node has a maximum capacity of 16 leaves and metadata pointers.  If the
+insertion algorithm finds that it is trying to insert a 17th object into a
+node, that node will be split such that at least two leaves that have a common
+key segment at that level end up in a separate node rooted on that slot for
+that common key segment.
+
+If the leaves in a full node and the leaf that is being inserted are
+sufficiently similar, then a shortcut will be inserted into the tree.
+
+When the number of objects in the subtree rooted at a node falls to 16 or
+fewer, then the subtree will be collapsed down to a single node - and this will
+ripple towards the root if possible.
+
+
+Non-Recursive Iteration
+-----------------------
+
+Each node and shortcut contains a back pointer to its parent and the number of
+slot in that parent that points to it.  None-recursive iteration uses these to
+proceed rootwards through the tree, going to the parent node, slot N + 1 to
+make sure progress is made without the need for a stack.
+
+The backpointers, however, make simultaneous alteration and iteration tricky.
+
+
+Simultaneous Alteration And Iteration
+-------------------------------------
+
+There are a number of cases to consider:
+
+1. Simple insert/replace.  This involves simply replacing a NULL or old
+   matching leaf pointer with the pointer to the new leaf after a barrier.
+   The metadata blocks don't change otherwise.  An old leaf won't be freed
+   until after the RCU grace period.
+
+2. Simple delete.  This involves just clearing an old matching leaf.  The
+   metadata blocks don't change otherwise.  The old leaf won't be freed until
+   after the RCU grace period.
+
+3. Insertion replacing part of a subtree that we haven't yet entered.  This
+   may involve replacement of part of that subtree - but that won't affect
+   the iteration as we won't have reached the pointer to it yet and the
+   ancestry blocks are not replaced (the layout of those does not change).
+
+4. Insertion replacing nodes that we're actively processing.  This isn't a
+   problem as we've passed the anchoring pointer and won't switch onto the
+   new layout until we follow the back pointers - at which point we've
+   already examined the leaves in the replaced node (we iterate over all the
+   leaves in a node before following any of its metadata pointers).
+
+   We might, however, re-see some leaves that have been split out into a new
+   branch that's in a slot further along than we were at.
+
+5. Insertion replacing nodes that we're processing a dependent branch of.
+   This won't affect us until we follow the back pointers.  Similar to (4).
+
+6. Deletion collapsing a branch under us.  This doesn't affect us because the
+   back pointers will get us back to the parent of the new node before we
+   could see the new node.  The entire collapsed subtree is thrown away
+   unchanged - and will still be rooted on the same slot, so we shouldn't
+   process it a second time as we'll go back to slot + 1.
+
+.. note::
+
+   Under some circumstances, we need to simultaneously change the parent
+   pointer and the parent slot pointer on a node (say, for example, we
+   inserted another node before it and moved it up a level).  We cannot do
+   this without locking against a read - so we have to replace that node too.
+
+   However, when we're changing a shortcut into a node this isn't a problem
+   as shortcuts only have one slot and so the parent slot number isn't used
+   when traversing backwards over one.  This means that it's okay to change
+   the slot number first - provided suitable barriers are used to make sure
+   the parent slot number is read after the back pointer.
+
+Obsolete blocks and leaves are freed up after an RCU grace period has passed,
+so as long as anyone doing walking or iteration holds the RCU read lock, the
+old superstructure should not go away on them.
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index f7ef7fda5763..480d9a323b60 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -7,6 +7,7 @@ Kernel and driver related documentation.
 .. toctree::
    :maxdepth: 1
 
+   assoc_array
    workqueue
 
 .. only::  subproject
-- 
cgit v1.2.3


From c232694ec155daf5a863b25745646edc3f61ba70 Mon Sep 17 00:00:00 2001
From: Silvio Fricke 
Date: Mon, 28 Nov 2016 18:30:54 +0100
Subject: Documentation/local_ops.txt: convert to ReST markup

... and move to core-api folder.

Signed-off-by: Silvio Fricke 
Reviewed-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/core-api/index.rst     |   1 +
 Documentation/core-api/local_ops.rst | 206 +++++++++++++++++++++++++++++++++++
 Documentation/local_ops.txt          | 191 --------------------------------
 3 files changed, 207 insertions(+), 191 deletions(-)
 create mode 100644 Documentation/core-api/local_ops.rst
 delete mode 100644 Documentation/local_ops.txt

diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index 480d9a323b60..f53555ee4931 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -8,6 +8,7 @@ Kernel and driver related documentation.
    :maxdepth: 1
 
    assoc_array
+   local_ops
    workqueue
 
 .. only::  subproject
diff --git a/Documentation/core-api/local_ops.rst b/Documentation/core-api/local_ops.rst
new file mode 100644
index 000000000000..1062ddba62c7
--- /dev/null
+++ b/Documentation/core-api/local_ops.rst
@@ -0,0 +1,206 @@
+
+.. _local_ops:
+
+=================================================
+Semantics and Behavior of Local Atomic Operations
+=================================================
+
+:Author: Mathieu Desnoyers
+
+
+This document explains the purpose of the local atomic operations, how
+to implement them for any given architecture and shows how they can be used
+properly. It also stresses on the precautions that must be taken when reading
+those local variables across CPUs when the order of memory writes matters.
+
+.. note::
+
+    Note that ``local_t`` based operations are not recommended for general
+    kernel use. Please use the ``this_cpu`` operations instead unless there is
+    really a special purpose. Most uses of ``local_t`` in the kernel have been
+    replaced by ``this_cpu`` operations. ``this_cpu`` operations combine the
+    relocation with the ``local_t`` like semantics in a single instruction and
+    yield more compact and faster executing code.
+
+
+Purpose of local atomic operations
+==================================
+
+Local atomic operations are meant to provide fast and highly reentrant per CPU
+counters. They minimize the performance cost of standard atomic operations by
+removing the LOCK prefix and memory barriers normally required to synchronize
+across CPUs.
+
+Having fast per CPU atomic counters is interesting in many cases: it does not
+require disabling interrupts to protect from interrupt handlers and it permits
+coherent counters in NMI handlers. It is especially useful for tracing purposes
+and for various performance monitoring counters.
+
+Local atomic operations only guarantee variable modification atomicity wrt the
+CPU which owns the data. Therefore, care must taken to make sure that only one
+CPU writes to the ``local_t`` data. This is done by using per cpu data and
+making sure that we modify it from within a preemption safe context. It is
+however permitted to read ``local_t`` data from any CPU: it will then appear to
+be written out of order wrt other memory writes by the owner CPU.
+
+
+Implementation for a given architecture
+=======================================
+
+It can be done by slightly modifying the standard atomic operations: only
+their UP variant must be kept. It typically means removing LOCK prefix (on
+i386 and x86_64) and any SMP synchronization barrier. If the architecture does
+not have a different behavior between SMP and UP, including
+``asm-generic/local.h`` in your architecture's ``local.h`` is sufficient.
+
+The ``local_t`` type is defined as an opaque ``signed long`` by embedding an
+``atomic_long_t`` inside a structure. This is made so a cast from this type to
+a ``long`` fails. The definition looks like::
+
+    typedef struct { atomic_long_t a; } local_t;
+
+
+Rules to follow when using local atomic operations
+==================================================
+
+* Variables touched by local ops must be per cpu variables.
+* *Only* the CPU owner of these variables must write to them.
+* This CPU can use local ops from any context (process, irq, softirq, nmi, ...)
+  to update its ``local_t`` variables.
+* Preemption (or interrupts) must be disabled when using local ops in
+  process context to make sure the process won't be migrated to a
+  different CPU between getting the per-cpu variable and doing the
+  actual local op.
+* When using local ops in interrupt context, no special care must be
+  taken on a mainline kernel, since they will run on the local CPU with
+  preemption already disabled. I suggest, however, to explicitly
+  disable preemption anyway to make sure it will still work correctly on
+  -rt kernels.
+* Reading the local cpu variable will provide the current copy of the
+  variable.
+* Reads of these variables can be done from any CPU, because updates to
+  "``long``", aligned, variables are always atomic. Since no memory
+  synchronization is done by the writer CPU, an outdated copy of the
+  variable can be read when reading some *other* cpu's variables.
+
+
+How to use local atomic operations
+==================================
+
+::
+
+    #include 
+    #include 
+
+    static DEFINE_PER_CPU(local_t, counters) = LOCAL_INIT(0);
+
+
+Counting
+========
+
+Counting is done on all the bits of a signed long.
+
+In preemptible context, use ``get_cpu_var()`` and ``put_cpu_var()`` around
+local atomic operations: it makes sure that preemption is disabled around write
+access to the per cpu variable. For instance::
+
+    local_inc(&get_cpu_var(counters));
+    put_cpu_var(counters);
+
+If you are already in a preemption-safe context, you can use
+``this_cpu_ptr()`` instead::
+
+    local_inc(this_cpu_ptr(&counters));
+
+
+
+Reading the counters
+====================
+
+Those local counters can be read from foreign CPUs to sum the count. Note that
+the data seen by local_read across CPUs must be considered to be out of order
+relatively to other memory writes happening on the CPU that owns the data::
+
+    long sum = 0;
+    for_each_online_cpu(cpu)
+            sum += local_read(&per_cpu(counters, cpu));
+
+If you want to use a remote local_read to synchronize access to a resource
+between CPUs, explicit ``smp_wmb()`` and ``smp_rmb()`` memory barriers must be used
+respectively on the writer and the reader CPUs. It would be the case if you use
+the ``local_t`` variable as a counter of bytes written in a buffer: there should
+be a ``smp_wmb()`` between the buffer write and the counter increment and also a
+``smp_rmb()`` between the counter read and the buffer read.
+
+
+Here is a sample module which implements a basic per cpu counter using
+``local.h``::
+
+    /* test-local.c
+     *
+     * Sample module for local.h usage.
+     */
+
+
+    #include 
+    #include 
+    #include 
+
+    static DEFINE_PER_CPU(local_t, counters) = LOCAL_INIT(0);
+
+    static struct timer_list test_timer;
+
+    /* IPI called on each CPU. */
+    static void test_each(void *info)
+    {
+            /* Increment the counter from a non preemptible context */
+            printk("Increment on cpu %d\n", smp_processor_id());
+            local_inc(this_cpu_ptr(&counters));
+
+            /* This is what incrementing the variable would look like within a
+             * preemptible context (it disables preemption) :
+             *
+             * local_inc(&get_cpu_var(counters));
+             * put_cpu_var(counters);
+             */
+    }
+
+    static void do_test_timer(unsigned long data)
+    {
+            int cpu;
+
+            /* Increment the counters */
+            on_each_cpu(test_each, NULL, 1);
+            /* Read all the counters */
+            printk("Counters read from CPU %d\n", smp_processor_id());
+            for_each_online_cpu(cpu) {
+                    printk("Read : CPU %d, count %ld\n", cpu,
+                            local_read(&per_cpu(counters, cpu)));
+            }
+            del_timer(&test_timer);
+            test_timer.expires = jiffies + 1000;
+            add_timer(&test_timer);
+    }
+
+    static int __init test_init(void)
+    {
+            /* initialize the timer that will increment the counter */
+            init_timer(&test_timer);
+            test_timer.function = do_test_timer;
+            test_timer.expires = jiffies + 1;
+            add_timer(&test_timer);
+
+            return 0;
+    }
+
+    static void __exit test_exit(void)
+    {
+            del_timer_sync(&test_timer);
+    }
+
+    module_init(test_init);
+    module_exit(test_exit);
+
+    MODULE_LICENSE("GPL");
+    MODULE_AUTHOR("Mathieu Desnoyers");
+    MODULE_DESCRIPTION("Local Atomic Ops");
diff --git a/Documentation/local_ops.txt b/Documentation/local_ops.txt
deleted file mode 100644
index 407576a23317..000000000000
--- a/Documentation/local_ops.txt
+++ /dev/null
@@ -1,191 +0,0 @@
-	     Semantics and Behavior of Local Atomic Operations
-
-			    Mathieu Desnoyers
-
-
-	This document explains the purpose of the local atomic operations, how
-to implement them for any given architecture and shows how they can be used
-properly. It also stresses on the precautions that must be taken when reading
-those local variables across CPUs when the order of memory writes matters.
-
-Note that local_t based operations are not recommended for general kernel use.
-Please use the this_cpu operations instead unless there is really a special purpose.
-Most uses of local_t in the kernel have been replaced by this_cpu operations.
-this_cpu operations combine the relocation with the local_t like semantics in
-a single instruction and yield more compact and faster executing code.
-
-
-* Purpose of local atomic operations
-
-Local atomic operations are meant to provide fast and highly reentrant per CPU
-counters. They minimize the performance cost of standard atomic operations by
-removing the LOCK prefix and memory barriers normally required to synchronize
-across CPUs.
-
-Having fast per CPU atomic counters is interesting in many cases : it does not
-require disabling interrupts to protect from interrupt handlers and it permits
-coherent counters in NMI handlers. It is especially useful for tracing purposes
-and for various performance monitoring counters.
-
-Local atomic operations only guarantee variable modification atomicity wrt the
-CPU which owns the data. Therefore, care must taken to make sure that only one
-CPU writes to the local_t data. This is done by using per cpu data and making
-sure that we modify it from within a preemption safe context. It is however
-permitted to read local_t data from any CPU : it will then appear to be written
-out of order wrt other memory writes by the owner CPU.
-
-
-* Implementation for a given architecture
-
-It can be done by slightly modifying the standard atomic operations : only
-their UP variant must be kept. It typically means removing LOCK prefix (on
-i386 and x86_64) and any SMP synchronization barrier. If the architecture does
-not have a different behavior between SMP and UP, including asm-generic/local.h
-in your architecture's local.h is sufficient.
-
-The local_t type is defined as an opaque signed long by embedding an
-atomic_long_t inside a structure. This is made so a cast from this type to a
-long fails. The definition looks like :
-
-typedef struct { atomic_long_t a; } local_t;
-
-
-* Rules to follow when using local atomic operations
-
-- Variables touched by local ops must be per cpu variables.
-- _Only_ the CPU owner of these variables must write to them.
-- This CPU can use local ops from any context (process, irq, softirq, nmi, ...)
-  to update its local_t variables.
-- Preemption (or interrupts) must be disabled when using local ops in
-  process context to   make sure the process won't be migrated to a
-  different CPU between getting the per-cpu variable and doing the
-  actual local op.
-- When using local ops in interrupt context, no special care must be
-  taken on a mainline kernel, since they will run on the local CPU with
-  preemption already disabled. I suggest, however, to explicitly
-  disable preemption anyway to make sure it will still work correctly on
-  -rt kernels.
-- Reading the local cpu variable will provide the current copy of the
-  variable.
-- Reads of these variables can be done from any CPU, because updates to
-  "long", aligned, variables are always atomic. Since no memory
-  synchronization is done by the writer CPU, an outdated copy of the
-  variable can be read when reading some _other_ cpu's variables.
-
-
-* How to use local atomic operations
-
-#include 
-#include 
-
-static DEFINE_PER_CPU(local_t, counters) = LOCAL_INIT(0);
-
-
-* Counting
-
-Counting is done on all the bits of a signed long.
-
-In preemptible context, use get_cpu_var() and put_cpu_var() around local atomic
-operations : it makes sure that preemption is disabled around write access to
-the per cpu variable. For instance :
-
-	local_inc(&get_cpu_var(counters));
-	put_cpu_var(counters);
-
-If you are already in a preemption-safe context, you can use
-this_cpu_ptr() instead.
-
-	local_inc(this_cpu_ptr(&counters));
-
-
-
-* Reading the counters
-
-Those local counters can be read from foreign CPUs to sum the count. Note that
-the data seen by local_read across CPUs must be considered to be out of order
-relatively to other memory writes happening on the CPU that owns the data.
-
-	long sum = 0;
-	for_each_online_cpu(cpu)
-		sum += local_read(&per_cpu(counters, cpu));
-
-If you want to use a remote local_read to synchronize access to a resource
-between CPUs, explicit smp_wmb() and smp_rmb() memory barriers must be used
-respectively on the writer and the reader CPUs. It would be the case if you use
-the local_t variable as a counter of bytes written in a buffer : there should
-be a smp_wmb() between the buffer write and the counter increment and also a
-smp_rmb() between the counter read and the buffer read.
-
-
-Here is a sample module which implements a basic per cpu counter using local.h.
-
---- BEGIN ---
-/* test-local.c
- *
- * Sample module for local.h usage.
- */
-
-
-#include 
-#include 
-#include 
-
-static DEFINE_PER_CPU(local_t, counters) = LOCAL_INIT(0);
-
-static struct timer_list test_timer;
-
-/* IPI called on each CPU. */
-static void test_each(void *info)
-{
-	/* Increment the counter from a non preemptible context */
-	printk("Increment on cpu %d\n", smp_processor_id());
-	local_inc(this_cpu_ptr(&counters));
-
-	/* This is what incrementing the variable would look like within a
-	 * preemptible context (it disables preemption) :
-	 *
-	 * local_inc(&get_cpu_var(counters));
-	 * put_cpu_var(counters);
-	 */
-}
-
-static void do_test_timer(unsigned long data)
-{
-	int cpu;
-
-	/* Increment the counters */
-	on_each_cpu(test_each, NULL, 1);
-	/* Read all the counters */
-	printk("Counters read from CPU %d\n", smp_processor_id());
-	for_each_online_cpu(cpu) {
-		printk("Read : CPU %d, count %ld\n", cpu,
-			local_read(&per_cpu(counters, cpu)));
-	}
-	del_timer(&test_timer);
-	test_timer.expires = jiffies + 1000;
-	add_timer(&test_timer);
-}
-
-static int __init test_init(void)
-{
-	/* initialize the timer that will increment the counter */
-	init_timer(&test_timer);
-	test_timer.function = do_test_timer;
-	test_timer.expires = jiffies + 1;
-	add_timer(&test_timer);
-
-	return 0;
-}
-
-static void __exit test_exit(void)
-{
-	del_timer_sync(&test_timer);
-}
-
-module_init(test_init);
-module_exit(test_exit);
-
-MODULE_LICENSE("GPL");
-MODULE_AUTHOR("Mathieu Desnoyers");
-MODULE_DESCRIPTION("Local Atomic Ops");
---- END ---
-- 
cgit v1.2.3


From 326bc876fed4fad2f46dd1be637e90e1b525ee8c Mon Sep 17 00:00:00 2001
From: Silvio Fricke 
Date: Mon, 28 Nov 2016 18:30:55 +0100
Subject: Documentation/atomic_ops.txt: convert to ReST markup

... and move to core-api folder.

Signed-off-by: Silvio Fricke 
Signed-off-by: Jonathan Corbet 
---
 Documentation/atomic_ops.txt                       | 640 --------------------
 Documentation/core-api/atomic_ops.rst              | 658 +++++++++++++++++++++
 Documentation/core-api/index.rst                   |   1 +
 .../process/volatile-considered-harmful.rst        |   3 +
 4 files changed, 662 insertions(+), 640 deletions(-)
 delete mode 100644 Documentation/atomic_ops.txt
 create mode 100644 Documentation/core-api/atomic_ops.rst

diff --git a/Documentation/atomic_ops.txt b/Documentation/atomic_ops.txt
deleted file mode 100644
index 6c5e8a9d2c6e..000000000000
--- a/Documentation/atomic_ops.txt
+++ /dev/null
@@ -1,640 +0,0 @@
-		Semantics and Behavior of Atomic and
-		         Bitmask Operations
-
-			  David S. Miller	 
-
-	This document is intended to serve as a guide to Linux port
-maintainers on how to implement atomic counter, bitops, and spinlock
-interfaces properly.
-
-	The atomic_t type should be defined as a signed integer and
-the atomic_long_t type as a signed long integer.  Also, they should
-be made opaque such that any kind of cast to a normal C integer type
-will fail.  Something like the following should suffice:
-
-	typedef struct { int counter; } atomic_t;
-	typedef struct { long counter; } atomic_long_t;
-
-Historically, counter has been declared volatile.  This is now discouraged.
-See Documentation/process/volatile-considered-harmful.rst for the complete rationale.
-
-local_t is very similar to atomic_t. If the counter is per CPU and only
-updated by one CPU, local_t is probably more appropriate. Please see
-Documentation/local_ops.txt for the semantics of local_t.
-
-The first operations to implement for atomic_t's are the initializers and
-plain reads.
-
-	#define ATOMIC_INIT(i)		{ (i) }
-	#define atomic_set(v, i)	((v)->counter = (i))
-
-The first macro is used in definitions, such as:
-
-static atomic_t my_counter = ATOMIC_INIT(1);
-
-The initializer is atomic in that the return values of the atomic operations
-are guaranteed to be correct reflecting the initialized value if the
-initializer is used before runtime.  If the initializer is used at runtime, a
-proper implicit or explicit read memory barrier is needed before reading the
-value with atomic_read from another thread.
-
-As with all of the atomic_ interfaces, replace the leading "atomic_"
-with "atomic_long_" to operate on atomic_long_t.
-
-The second interface can be used at runtime, as in:
-
-	struct foo { atomic_t counter; };
-	...
-
-	struct foo *k;
-
-	k = kmalloc(sizeof(*k), GFP_KERNEL);
-	if (!k)
-		return -ENOMEM;
-	atomic_set(&k->counter, 0);
-
-The setting is atomic in that the return values of the atomic operations by
-all threads are guaranteed to be correct reflecting either the value that has
-been set with this operation or set with another operation.  A proper implicit
-or explicit memory barrier is needed before the value set with the operation
-is guaranteed to be readable with atomic_read from another thread.
-
-Next, we have:
-
-	#define atomic_read(v)	((v)->counter)
-
-which simply reads the counter value currently visible to the calling thread.
-The read is atomic in that the return value is guaranteed to be one of the
-values initialized or modified with the interface operations if a proper
-implicit or explicit memory barrier is used after possible runtime
-initialization by any other thread and the value is modified only with the
-interface operations.  atomic_read does not guarantee that the runtime
-initialization by any other thread is visible yet, so the user of the
-interface must take care of that with a proper implicit or explicit memory
-barrier.
-
-*** WARNING: atomic_read() and atomic_set() DO NOT IMPLY BARRIERS! ***
-
-Some architectures may choose to use the volatile keyword, barriers, or inline
-assembly to guarantee some degree of immediacy for atomic_read() and
-atomic_set().  This is not uniformly guaranteed, and may change in the future,
-so all users of atomic_t should treat atomic_read() and atomic_set() as simple
-C statements that may be reordered or optimized away entirely by the compiler
-or processor, and explicitly invoke the appropriate compiler and/or memory
-barrier for each use case.  Failure to do so will result in code that may
-suddenly break when used with different architectures or compiler
-optimizations, or even changes in unrelated code which changes how the
-compiler optimizes the section accessing atomic_t variables.
-
-*** YOU HAVE BEEN WARNED! ***
-
-Properly aligned pointers, longs, ints, and chars (and unsigned
-equivalents) may be atomically loaded from and stored to in the same
-sense as described for atomic_read() and atomic_set().  The READ_ONCE()
-and WRITE_ONCE() macros should be used to prevent the compiler from using
-optimizations that might otherwise optimize accesses out of existence on
-the one hand, or that might create unsolicited accesses on the other.
-
-For example consider the following code:
-
-	while (a > 0)
-		do_something();
-
-If the compiler can prove that do_something() does not store to the
-variable a, then the compiler is within its rights transforming this to
-the following:
-
-	tmp = a;
-	if (a > 0)
-		for (;;)
-			do_something();
-
-If you don't want the compiler to do this (and you probably don't), then
-you should use something like the following:
-
-	while (READ_ONCE(a) < 0)
-		do_something();
-
-Alternatively, you could place a barrier() call in the loop.
-
-For another example, consider the following code:
-
-	tmp_a = a;
-	do_something_with(tmp_a);
-	do_something_else_with(tmp_a);
-
-If the compiler can prove that do_something_with() does not store to the
-variable a, then the compiler is within its rights to manufacture an
-additional load as follows:
-
-	tmp_a = a;
-	do_something_with(tmp_a);
-	tmp_a = a;
-	do_something_else_with(tmp_a);
-
-This could fatally confuse your code if it expected the same value
-to be passed to do_something_with() and do_something_else_with().
-
-The compiler would be likely to manufacture this additional load if
-do_something_with() was an inline function that made very heavy use
-of registers: reloading from variable a could save a flush to the
-stack and later reload.  To prevent the compiler from attacking your
-code in this manner, write the following:
-
-	tmp_a = READ_ONCE(a);
-	do_something_with(tmp_a);
-	do_something_else_with(tmp_a);
-
-For a final example, consider the following code, assuming that the
-variable a is set at boot time before the second CPU is brought online
-and never changed later, so that memory barriers are not needed:
-
-	if (a)
-		b = 9;
-	else
-		b = 42;
-
-The compiler is within its rights to manufacture an additional store
-by transforming the above code into the following:
-
-	b = 42;
-	if (a)
-		b = 9;
-
-This could come as a fatal surprise to other code running concurrently
-that expected b to never have the value 42 if a was zero.  To prevent
-the compiler from doing this, write something like:
-
-	if (a)
-		WRITE_ONCE(b, 9);
-	else
-		WRITE_ONCE(b, 42);
-
-Don't even -think- about doing this without proper use of memory barriers,
-locks, or atomic operations if variable a can change at runtime!
-
-*** WARNING: READ_ONCE() OR WRITE_ONCE() DO NOT IMPLY A BARRIER! ***
-
-Now, we move onto the atomic operation interfaces typically implemented with
-the help of assembly code.
-
-	void atomic_add(int i, atomic_t *v);
-	void atomic_sub(int i, atomic_t *v);
-	void atomic_inc(atomic_t *v);
-	void atomic_dec(atomic_t *v);
-
-These four routines add and subtract integral values to/from the given
-atomic_t value.  The first two routines pass explicit integers by
-which to make the adjustment, whereas the latter two use an implicit
-adjustment value of "1".
-
-One very important aspect of these two routines is that they DO NOT
-require any explicit memory barriers.  They need only perform the
-atomic_t counter update in an SMP safe manner.
-
-Next, we have:
-
-	int atomic_inc_return(atomic_t *v);
-	int atomic_dec_return(atomic_t *v);
-
-These routines add 1 and subtract 1, respectively, from the given
-atomic_t and return the new counter value after the operation is
-performed.
-
-Unlike the above routines, it is required that these primitives
-include explicit memory barriers that are performed before and after
-the operation.  It must be done such that all memory operations before
-and after the atomic operation calls are strongly ordered with respect
-to the atomic operation itself.
-
-For example, it should behave as if a smp_mb() call existed both
-before and after the atomic operation.
-
-If the atomic instructions used in an implementation provide explicit
-memory barrier semantics which satisfy the above requirements, that is
-fine as well.
-
-Let's move on:
-
-	int atomic_add_return(int i, atomic_t *v);
-	int atomic_sub_return(int i, atomic_t *v);
-
-These behave just like atomic_{inc,dec}_return() except that an
-explicit counter adjustment is given instead of the implicit "1".
-This means that like atomic_{inc,dec}_return(), the memory barrier
-semantics are required.
-
-Next:
-
-	int atomic_inc_and_test(atomic_t *v);
-	int atomic_dec_and_test(atomic_t *v);
-
-These two routines increment and decrement by 1, respectively, the
-given atomic counter.  They return a boolean indicating whether the
-resulting counter value was zero or not.
-
-Again, these primitives provide explicit memory barrier semantics around
-the atomic operation.
-
-	int atomic_sub_and_test(int i, atomic_t *v);
-
-This is identical to atomic_dec_and_test() except that an explicit
-decrement is given instead of the implicit "1".  This primitive must
-provide explicit memory barrier semantics around the operation.
-
-	int atomic_add_negative(int i, atomic_t *v);
-
-The given increment is added to the given atomic counter value.  A boolean
-is return which indicates whether the resulting counter value is negative.
-This primitive must provide explicit memory barrier semantics around
-the operation.
-
-Then:
-
-	int atomic_xchg(atomic_t *v, int new);
-
-This performs an atomic exchange operation on the atomic variable v, setting
-the given new value.  It returns the old value that the atomic variable v had
-just before the operation.
-
-atomic_xchg must provide explicit memory barriers around the operation.
-
-	int atomic_cmpxchg(atomic_t *v, int old, int new);
-
-This performs an atomic compare exchange operation on the atomic value v,
-with the given old and new values. Like all atomic_xxx operations,
-atomic_cmpxchg will only satisfy its atomicity semantics as long as all
-other accesses of *v are performed through atomic_xxx operations.
-
-atomic_cmpxchg must provide explicit memory barriers around the operation,
-although if the comparison fails then no memory ordering guarantees are
-required.
-
-The semantics for atomic_cmpxchg are the same as those defined for 'cas'
-below.
-
-Finally:
-
-	int atomic_add_unless(atomic_t *v, int a, int u);
-
-If the atomic value v is not equal to u, this function adds a to v, and
-returns non zero. If v is equal to u then it returns zero. This is done as
-an atomic operation.
-
-atomic_add_unless must provide explicit memory barriers around the
-operation unless it fails (returns 0).
-
-atomic_inc_not_zero, equivalent to atomic_add_unless(v, 1, 0)
-
-
-If a caller requires memory barrier semantics around an atomic_t
-operation which does not return a value, a set of interfaces are
-defined which accomplish this:
-
-	void smp_mb__before_atomic(void);
-	void smp_mb__after_atomic(void);
-
-For example, smp_mb__before_atomic() can be used like so:
-
-	obj->dead = 1;
-	smp_mb__before_atomic();
-	atomic_dec(&obj->ref_count);
-
-It makes sure that all memory operations preceding the atomic_dec()
-call are strongly ordered with respect to the atomic counter
-operation.  In the above example, it guarantees that the assignment of
-"1" to obj->dead will be globally visible to other cpus before the
-atomic counter decrement.
-
-Without the explicit smp_mb__before_atomic() call, the
-implementation could legally allow the atomic counter update visible
-to other cpus before the "obj->dead = 1;" assignment.
-
-A missing memory barrier in the cases where they are required by the
-atomic_t implementation above can have disastrous results.  Here is
-an example, which follows a pattern occurring frequently in the Linux
-kernel.  It is the use of atomic counters to implement reference
-counting, and it works such that once the counter falls to zero it can
-be guaranteed that no other entity can be accessing the object:
-
-static void obj_list_add(struct obj *obj, struct list_head *head)
-{
-	obj->active = 1;
-	list_add(&obj->list, head);
-}
-
-static void obj_list_del(struct obj *obj)
-{
-	list_del(&obj->list);
-	obj->active = 0;
-}
-
-static void obj_destroy(struct obj *obj)
-{
-	BUG_ON(obj->active);
-	kfree(obj);
-}
-
-struct obj *obj_list_peek(struct list_head *head)
-{
-	if (!list_empty(head)) {
-		struct obj *obj;
-
-		obj = list_entry(head->next, struct obj, list);
-		atomic_inc(&obj->refcnt);
-		return obj;
-	}
-	return NULL;
-}
-
-void obj_poke(void)
-{
-	struct obj *obj;
-
-	spin_lock(&global_list_lock);
-	obj = obj_list_peek(&global_list);
-	spin_unlock(&global_list_lock);
-
-	if (obj) {
-		obj->ops->poke(obj);
-		if (atomic_dec_and_test(&obj->refcnt))
-			obj_destroy(obj);
-	}
-}
-
-void obj_timeout(struct obj *obj)
-{
-	spin_lock(&global_list_lock);
-	obj_list_del(obj);
-	spin_unlock(&global_list_lock);
-
-	if (atomic_dec_and_test(&obj->refcnt))
-		obj_destroy(obj);
-}
-
-(This is a simplification of the ARP queue management in the
- generic neighbour discover code of the networking.  Olaf Kirch
- found a bug wrt. memory barriers in kfree_skb() that exposed
- the atomic_t memory barrier requirements quite clearly.)
-
-Given the above scheme, it must be the case that the obj->active
-update done by the obj list deletion be visible to other processors
-before the atomic counter decrement is performed.
-
-Otherwise, the counter could fall to zero, yet obj->active would still
-be set, thus triggering the assertion in obj_destroy().  The error
-sequence looks like this:
-
-	cpu 0				cpu 1
-	obj_poke()			obj_timeout()
-	obj = obj_list_peek();
-	... gains ref to obj, refcnt=2
-					obj_list_del(obj);
-					obj->active = 0 ...
-					... visibility delayed ...
-					atomic_dec_and_test()
-					... refcnt drops to 1 ...
-	atomic_dec_and_test()
-	... refcount drops to 0 ...
-	obj_destroy()
-	BUG() triggers since obj->active
-	still seen as one
-					obj->active update visibility occurs
-
-With the memory barrier semantics required of the atomic_t operations
-which return values, the above sequence of memory visibility can never
-happen.  Specifically, in the above case the atomic_dec_and_test()
-counter decrement would not become globally visible until the
-obj->active update does.
-
-As a historical note, 32-bit Sparc used to only allow usage of
-24-bits of its atomic_t type.  This was because it used 8 bits
-as a spinlock for SMP safety.  Sparc32 lacked a "compare and swap"
-type instruction.  However, 32-bit Sparc has since been moved over
-to a "hash table of spinlocks" scheme, that allows the full 32-bit
-counter to be realized.  Essentially, an array of spinlocks are
-indexed into based upon the address of the atomic_t being operated
-on, and that lock protects the atomic operation.  Parisc uses the
-same scheme.
-
-Another note is that the atomic_t operations returning values are
-extremely slow on an old 386.
-
-We will now cover the atomic bitmask operations.  You will find that
-their SMP and memory barrier semantics are similar in shape and scope
-to the atomic_t ops above.
-
-Native atomic bit operations are defined to operate on objects aligned
-to the size of an "unsigned long" C data type, and are least of that
-size.  The endianness of the bits within each "unsigned long" are the
-native endianness of the cpu.
-
-	void set_bit(unsigned long nr, volatile unsigned long *addr);
-	void clear_bit(unsigned long nr, volatile unsigned long *addr);
-	void change_bit(unsigned long nr, volatile unsigned long *addr);
-
-These routines set, clear, and change, respectively, the bit number
-indicated by "nr" on the bit mask pointed to by "ADDR".
-
-They must execute atomically, yet there are no implicit memory barrier
-semantics required of these interfaces.
-
-	int test_and_set_bit(unsigned long nr, volatile unsigned long *addr);
-	int test_and_clear_bit(unsigned long nr, volatile unsigned long *addr);
-	int test_and_change_bit(unsigned long nr, volatile unsigned long *addr);
-
-Like the above, except that these routines return a boolean which
-indicates whether the changed bit was set _BEFORE_ the atomic bit
-operation.
-
-WARNING! It is incredibly important that the value be a boolean,
-ie. "0" or "1".  Do not try to be fancy and save a few instructions by
-declaring the above to return "long" and just returning something like
-"old_val & mask" because that will not work.
-
-For one thing, this return value gets truncated to int in many code
-paths using these interfaces, so on 64-bit if the bit is set in the
-upper 32-bits then testers will never see that.
-
-One great example of where this problem crops up are the thread_info
-flag operations.  Routines such as test_and_set_ti_thread_flag() chop
-the return value into an int.  There are other places where things
-like this occur as well.
-
-These routines, like the atomic_t counter operations returning values,
-must provide explicit memory barrier semantics around their execution.
-All memory operations before the atomic bit operation call must be
-made visible globally before the atomic bit operation is made visible.
-Likewise, the atomic bit operation must be visible globally before any
-subsequent memory operation is made visible.  For example:
-
-	obj->dead = 1;
-	if (test_and_set_bit(0, &obj->flags))
-		/* ... */;
-	obj->killed = 1;
-
-The implementation of test_and_set_bit() must guarantee that
-"obj->dead = 1;" is visible to cpus before the atomic memory operation
-done by test_and_set_bit() becomes visible.  Likewise, the atomic
-memory operation done by test_and_set_bit() must become visible before
-"obj->killed = 1;" is visible.
-
-Finally there is the basic operation:
-
-	int test_bit(unsigned long nr, __const__ volatile unsigned long *addr);
-
-Which returns a boolean indicating if bit "nr" is set in the bitmask
-pointed to by "addr".
-
-If explicit memory barriers are required around {set,clear}_bit() (which do
-not return a value, and thus does not need to provide memory barrier
-semantics), two interfaces are provided:
-
-	void smp_mb__before_atomic(void);
-	void smp_mb__after_atomic(void);
-
-They are used as follows, and are akin to their atomic_t operation
-brothers:
-
-	/* All memory operations before this call will
-	 * be globally visible before the clear_bit().
-	 */
-	smp_mb__before_atomic();
-	clear_bit( ... );
-
-	/* The clear_bit() will be visible before all
-	 * subsequent memory operations.
-	 */
-	 smp_mb__after_atomic();
-
-There are two special bitops with lock barrier semantics (acquire/release,
-same as spinlocks). These operate in the same way as their non-_lock/unlock
-postfixed variants, except that they are to provide acquire/release semantics,
-respectively. This means they can be used for bit_spin_trylock and
-bit_spin_unlock type operations without specifying any more barriers.
-
-	int test_and_set_bit_lock(unsigned long nr, unsigned long *addr);
-	void clear_bit_unlock(unsigned long nr, unsigned long *addr);
-	void __clear_bit_unlock(unsigned long nr, unsigned long *addr);
-
-The __clear_bit_unlock version is non-atomic, however it still implements
-unlock barrier semantics. This can be useful if the lock itself is protecting
-the other bits in the word.
-
-Finally, there are non-atomic versions of the bitmask operations
-provided.  They are used in contexts where some other higher-level SMP
-locking scheme is being used to protect the bitmask, and thus less
-expensive non-atomic operations may be used in the implementation.
-They have names similar to the above bitmask operation interfaces,
-except that two underscores are prefixed to the interface name.
-
-	void __set_bit(unsigned long nr, volatile unsigned long *addr);
-	void __clear_bit(unsigned long nr, volatile unsigned long *addr);
-	void __change_bit(unsigned long nr, volatile unsigned long *addr);
-	int __test_and_set_bit(unsigned long nr, volatile unsigned long *addr);
-	int __test_and_clear_bit(unsigned long nr, volatile unsigned long *addr);
-	int __test_and_change_bit(unsigned long nr, volatile unsigned long *addr);
-
-These non-atomic variants also do not require any special memory
-barrier semantics.
-
-The routines xchg() and cmpxchg() must provide the same exact
-memory-barrier semantics as the atomic and bit operations returning
-values.
-
-Note: If someone wants to use xchg(), cmpxchg() and their variants,
-linux/atomic.h should be included rather than asm/cmpxchg.h, unless
-the code is in arch/* and can take care of itself.
-
-Spinlocks and rwlocks have memory barrier expectations as well.
-The rule to follow is simple:
-
-1) When acquiring a lock, the implementation must make it globally
-   visible before any subsequent memory operation.
-
-2) When releasing a lock, the implementation must make it such that
-   all previous memory operations are globally visible before the
-   lock release.
-
-Which finally brings us to _atomic_dec_and_lock().  There is an
-architecture-neutral version implemented in lib/dec_and_lock.c,
-but most platforms will wish to optimize this in assembler.
-
-	int _atomic_dec_and_lock(atomic_t *atomic, spinlock_t *lock);
-
-Atomically decrement the given counter, and if will drop to zero
-atomically acquire the given spinlock and perform the decrement
-of the counter to zero.  If it does not drop to zero, do nothing
-with the spinlock.
-
-It is actually pretty simple to get the memory barrier correct.
-Simply satisfy the spinlock grab requirements, which is make
-sure the spinlock operation is globally visible before any
-subsequent memory operation.
-
-We can demonstrate this operation more clearly if we define
-an abstract atomic operation:
-
-	long cas(long *mem, long old, long new);
-
-"cas" stands for "compare and swap".  It atomically:
-
-1) Compares "old" with the value currently at "mem".
-2) If they are equal, "new" is written to "mem".
-3) Regardless, the current value at "mem" is returned.
-
-As an example usage, here is what an atomic counter update
-might look like:
-
-void example_atomic_inc(long *counter)
-{
-	long old, new, ret;
-
-	while (1) {
-		old = *counter;
-		new = old + 1;
-
-		ret = cas(counter, old, new);
-		if (ret == old)
-			break;
-	}
-}
-
-Let's use cas() in order to build a pseudo-C atomic_dec_and_lock():
-
-int _atomic_dec_and_lock(atomic_t *atomic, spinlock_t *lock)
-{
-	long old, new, ret;
-	int went_to_zero;
-
-	went_to_zero = 0;
-	while (1) {
-		old = atomic_read(atomic);
-		new = old - 1;
-		if (new == 0) {
-			went_to_zero = 1;
-			spin_lock(lock);
-		}
-		ret = cas(atomic, old, new);
-		if (ret == old)
-			break;
-		if (went_to_zero) {
-			spin_unlock(lock);
-			went_to_zero = 0;
-		}
-	}
-
-	return went_to_zero;
-}
-
-Now, as far as memory barriers go, as long as spin_lock()
-strictly orders all subsequent memory operations (including
-the cas()) with respect to itself, things will be fine.
-
-Said another way, _atomic_dec_and_lock() must guarantee that
-a counter dropping to zero is never made visible before the
-spinlock being acquired.
-
-Note that this also means that for the case where the counter
-is not dropping to zero, there are no memory ordering
-requirements.
diff --git a/Documentation/core-api/atomic_ops.rst b/Documentation/core-api/atomic_ops.rst
new file mode 100644
index 000000000000..55e43f1c80de
--- /dev/null
+++ b/Documentation/core-api/atomic_ops.rst
@@ -0,0 +1,658 @@
+=======================================================
+Semantics and Behavior of Atomic and Bitmask Operations
+=======================================================
+
+:Author: David S. Miller
+
+This document is intended to serve as a guide to Linux port
+maintainers on how to implement atomic counter, bitops, and spinlock
+interfaces properly.
+
+Atomic Type And Operations
+==========================
+
+The atomic_t type should be defined as a signed integer and
+the atomic_long_t type as a signed long integer.  Also, they should
+be made opaque such that any kind of cast to a normal C integer type
+will fail.  Something like the following should suffice::
+
+	typedef struct { int counter; } atomic_t;
+	typedef struct { long counter; } atomic_long_t;
+
+Historically, counter has been declared volatile.  This is now discouraged.
+See :ref:`Documentation/process/volatile-considered-harmful.rst
+` for the complete rationale.
+
+local_t is very similar to atomic_t. If the counter is per CPU and only
+updated by one CPU, local_t is probably more appropriate. Please see
+:ref:`Documentation/core-api/local_ops.rst ` for the semantics of
+local_t.
+
+The first operations to implement for atomic_t's are the initializers and
+plain reads. ::
+
+	#define ATOMIC_INIT(i)		{ (i) }
+	#define atomic_set(v, i)	((v)->counter = (i))
+
+The first macro is used in definitions, such as::
+
+	static atomic_t my_counter = ATOMIC_INIT(1);
+
+The initializer is atomic in that the return values of the atomic operations
+are guaranteed to be correct reflecting the initialized value if the
+initializer is used before runtime.  If the initializer is used at runtime, a
+proper implicit or explicit read memory barrier is needed before reading the
+value with atomic_read from another thread.
+
+As with all of the ``atomic_`` interfaces, replace the leading ``atomic_``
+with ``atomic_long_`` to operate on atomic_long_t.
+
+The second interface can be used at runtime, as in::
+
+	struct foo { atomic_t counter; };
+	...
+
+	struct foo *k;
+
+	k = kmalloc(sizeof(*k), GFP_KERNEL);
+	if (!k)
+		return -ENOMEM;
+	atomic_set(&k->counter, 0);
+
+The setting is atomic in that the return values of the atomic operations by
+all threads are guaranteed to be correct reflecting either the value that has
+been set with this operation or set with another operation.  A proper implicit
+or explicit memory barrier is needed before the value set with the operation
+is guaranteed to be readable with atomic_read from another thread.
+
+Next, we have::
+
+	#define atomic_read(v)	((v)->counter)
+
+which simply reads the counter value currently visible to the calling thread.
+The read is atomic in that the return value is guaranteed to be one of the
+values initialized or modified with the interface operations if a proper
+implicit or explicit memory barrier is used after possible runtime
+initialization by any other thread and the value is modified only with the
+interface operations.  atomic_read does not guarantee that the runtime
+initialization by any other thread is visible yet, so the user of the
+interface must take care of that with a proper implicit or explicit memory
+barrier.
+
+.. warning::
+
+	``atomic_read()`` and ``atomic_set()`` DO NOT IMPLY BARRIERS!
+
+	Some architectures may choose to use the volatile keyword, barriers, or
+	inline assembly to guarantee some degree of immediacy for atomic_read()
+	and atomic_set().  This is not uniformly guaranteed, and may change in
+	the future, so all users of atomic_t should treat atomic_read() and
+	atomic_set() as simple C statements that may be reordered or optimized
+	away entirely by the compiler or processor, and explicitly invoke the
+	appropriate compiler and/or memory barrier for each use case.  Failure
+	to do so will result in code that may suddenly break when used with
+	different architectures or compiler optimizations, or even changes in
+	unrelated code which changes how the compiler optimizes the section
+	accessing atomic_t variables.
+
+Properly aligned pointers, longs, ints, and chars (and unsigned
+equivalents) may be atomically loaded from and stored to in the same
+sense as described for atomic_read() and atomic_set().  The READ_ONCE()
+and WRITE_ONCE() macros should be used to prevent the compiler from using
+optimizations that might otherwise optimize accesses out of existence on
+the one hand, or that might create unsolicited accesses on the other.
+
+For example consider the following code::
+
+	while (a > 0)
+		do_something();
+
+If the compiler can prove that do_something() does not store to the
+variable a, then the compiler is within its rights transforming this to
+the following::
+
+	tmp = a;
+	if (a > 0)
+		for (;;)
+			do_something();
+
+If you don't want the compiler to do this (and you probably don't), then
+you should use something like the following::
+
+	while (READ_ONCE(a) < 0)
+		do_something();
+
+Alternatively, you could place a barrier() call in the loop.
+
+For another example, consider the following code::
+
+	tmp_a = a;
+	do_something_with(tmp_a);
+	do_something_else_with(tmp_a);
+
+If the compiler can prove that do_something_with() does not store to the
+variable a, then the compiler is within its rights to manufacture an
+additional load as follows::
+
+	tmp_a = a;
+	do_something_with(tmp_a);
+	tmp_a = a;
+	do_something_else_with(tmp_a);
+
+This could fatally confuse your code if it expected the same value
+to be passed to do_something_with() and do_something_else_with().
+
+The compiler would be likely to manufacture this additional load if
+do_something_with() was an inline function that made very heavy use
+of registers: reloading from variable a could save a flush to the
+stack and later reload.  To prevent the compiler from attacking your
+code in this manner, write the following::
+
+	tmp_a = READ_ONCE(a);
+	do_something_with(tmp_a);
+	do_something_else_with(tmp_a);
+
+For a final example, consider the following code, assuming that the
+variable a is set at boot time before the second CPU is brought online
+and never changed later, so that memory barriers are not needed::
+
+	if (a)
+		b = 9;
+	else
+		b = 42;
+
+The compiler is within its rights to manufacture an additional store
+by transforming the above code into the following::
+
+	b = 42;
+	if (a)
+		b = 9;
+
+This could come as a fatal surprise to other code running concurrently
+that expected b to never have the value 42 if a was zero.  To prevent
+the compiler from doing this, write something like::
+
+	if (a)
+		WRITE_ONCE(b, 9);
+	else
+		WRITE_ONCE(b, 42);
+
+Don't even -think- about doing this without proper use of memory barriers,
+locks, or atomic operations if variable a can change at runtime!
+
+.. warning::
+
+	``READ_ONCE()`` OR ``WRITE_ONCE()`` DO NOT IMPLY A BARRIER!
+
+Now, we move onto the atomic operation interfaces typically implemented with
+the help of assembly code. ::
+
+	void atomic_add(int i, atomic_t *v);
+	void atomic_sub(int i, atomic_t *v);
+	void atomic_inc(atomic_t *v);
+	void atomic_dec(atomic_t *v);
+
+These four routines add and subtract integral values to/from the given
+atomic_t value.  The first two routines pass explicit integers by
+which to make the adjustment, whereas the latter two use an implicit
+adjustment value of "1".
+
+One very important aspect of these two routines is that they DO NOT
+require any explicit memory barriers.  They need only perform the
+atomic_t counter update in an SMP safe manner.
+
+Next, we have::
+
+	int atomic_inc_return(atomic_t *v);
+	int atomic_dec_return(atomic_t *v);
+
+These routines add 1 and subtract 1, respectively, from the given
+atomic_t and return the new counter value after the operation is
+performed.
+
+Unlike the above routines, it is required that these primitives
+include explicit memory barriers that are performed before and after
+the operation.  It must be done such that all memory operations before
+and after the atomic operation calls are strongly ordered with respect
+to the atomic operation itself.
+
+For example, it should behave as if a smp_mb() call existed both
+before and after the atomic operation.
+
+If the atomic instructions used in an implementation provide explicit
+memory barrier semantics which satisfy the above requirements, that is
+fine as well.
+
+Let's move on::
+
+	int atomic_add_return(int i, atomic_t *v);
+	int atomic_sub_return(int i, atomic_t *v);
+
+These behave just like atomic_{inc,dec}_return() except that an
+explicit counter adjustment is given instead of the implicit "1".
+This means that like atomic_{inc,dec}_return(), the memory barrier
+semantics are required.
+
+Next::
+
+	int atomic_inc_and_test(atomic_t *v);
+	int atomic_dec_and_test(atomic_t *v);
+
+These two routines increment and decrement by 1, respectively, the
+given atomic counter.  They return a boolean indicating whether the
+resulting counter value was zero or not.
+
+Again, these primitives provide explicit memory barrier semantics around
+the atomic operation::
+
+	int atomic_sub_and_test(int i, atomic_t *v);
+
+This is identical to atomic_dec_and_test() except that an explicit
+decrement is given instead of the implicit "1".  This primitive must
+provide explicit memory barrier semantics around the operation::
+
+	int atomic_add_negative(int i, atomic_t *v);
+
+The given increment is added to the given atomic counter value.  A boolean
+is return which indicates whether the resulting counter value is negative.
+This primitive must provide explicit memory barrier semantics around
+the operation.
+
+Then::
+
+	int atomic_xchg(atomic_t *v, int new);
+
+This performs an atomic exchange operation on the atomic variable v, setting
+the given new value.  It returns the old value that the atomic variable v had
+just before the operation.
+
+atomic_xchg must provide explicit memory barriers around the operation. ::
+
+	int atomic_cmpxchg(atomic_t *v, int old, int new);
+
+This performs an atomic compare exchange operation on the atomic value v,
+with the given old and new values. Like all atomic_xxx operations,
+atomic_cmpxchg will only satisfy its atomicity semantics as long as all
+other accesses of \*v are performed through atomic_xxx operations.
+
+atomic_cmpxchg must provide explicit memory barriers around the operation,
+although if the comparison fails then no memory ordering guarantees are
+required.
+
+The semantics for atomic_cmpxchg are the same as those defined for 'cas'
+below.
+
+Finally::
+
+	int atomic_add_unless(atomic_t *v, int a, int u);
+
+If the atomic value v is not equal to u, this function adds a to v, and
+returns non zero. If v is equal to u then it returns zero. This is done as
+an atomic operation.
+
+atomic_add_unless must provide explicit memory barriers around the
+operation unless it fails (returns 0).
+
+atomic_inc_not_zero, equivalent to atomic_add_unless(v, 1, 0)
+
+
+If a caller requires memory barrier semantics around an atomic_t
+operation which does not return a value, a set of interfaces are
+defined which accomplish this::
+
+	void smp_mb__before_atomic(void);
+	void smp_mb__after_atomic(void);
+
+For example, smp_mb__before_atomic() can be used like so::
+
+	obj->dead = 1;
+	smp_mb__before_atomic();
+	atomic_dec(&obj->ref_count);
+
+It makes sure that all memory operations preceding the atomic_dec()
+call are strongly ordered with respect to the atomic counter
+operation.  In the above example, it guarantees that the assignment of
+"1" to obj->dead will be globally visible to other cpus before the
+atomic counter decrement.
+
+Without the explicit smp_mb__before_atomic() call, the
+implementation could legally allow the atomic counter update visible
+to other cpus before the "obj->dead = 1;" assignment.
+
+A missing memory barrier in the cases where they are required by the
+atomic_t implementation above can have disastrous results.  Here is
+an example, which follows a pattern occurring frequently in the Linux
+kernel.  It is the use of atomic counters to implement reference
+counting, and it works such that once the counter falls to zero it can
+be guaranteed that no other entity can be accessing the object::
+
+	static void obj_list_add(struct obj *obj, struct list_head *head)
+	{
+		obj->active = 1;
+		list_add(&obj->list, head);
+	}
+
+	static void obj_list_del(struct obj *obj)
+	{
+		list_del(&obj->list);
+		obj->active = 0;
+	}
+
+	static void obj_destroy(struct obj *obj)
+	{
+		BUG_ON(obj->active);
+		kfree(obj);
+	}
+
+	struct obj *obj_list_peek(struct list_head *head)
+	{
+		if (!list_empty(head)) {
+			struct obj *obj;
+
+			obj = list_entry(head->next, struct obj, list);
+			atomic_inc(&obj->refcnt);
+			return obj;
+		}
+		return NULL;
+	}
+
+	void obj_poke(void)
+	{
+		struct obj *obj;
+
+		spin_lock(&global_list_lock);
+		obj = obj_list_peek(&global_list);
+		spin_unlock(&global_list_lock);
+
+		if (obj) {
+			obj->ops->poke(obj);
+			if (atomic_dec_and_test(&obj->refcnt))
+				obj_destroy(obj);
+		}
+	}
+
+	void obj_timeout(struct obj *obj)
+	{
+		spin_lock(&global_list_lock);
+		obj_list_del(obj);
+		spin_unlock(&global_list_lock);
+
+		if (atomic_dec_and_test(&obj->refcnt))
+			obj_destroy(obj);
+	}
+
+.. note::
+
+	This is a simplification of the ARP queue management in the generic
+	neighbour discover code of the networking.  Olaf Kirch found a bug wrt.
+	memory barriers in kfree_skb() that exposed the atomic_t memory barrier
+	requirements quite clearly.
+
+Given the above scheme, it must be the case that the obj->active
+update done by the obj list deletion be visible to other processors
+before the atomic counter decrement is performed.
+
+Otherwise, the counter could fall to zero, yet obj->active would still
+be set, thus triggering the assertion in obj_destroy().  The error
+sequence looks like this::
+
+	cpu 0				cpu 1
+	obj_poke()			obj_timeout()
+	obj = obj_list_peek();
+	... gains ref to obj, refcnt=2
+					obj_list_del(obj);
+					obj->active = 0 ...
+					... visibility delayed ...
+					atomic_dec_and_test()
+					... refcnt drops to 1 ...
+	atomic_dec_and_test()
+	... refcount drops to 0 ...
+	obj_destroy()
+	BUG() triggers since obj->active
+	still seen as one
+					obj->active update visibility occurs
+
+With the memory barrier semantics required of the atomic_t operations
+which return values, the above sequence of memory visibility can never
+happen.  Specifically, in the above case the atomic_dec_and_test()
+counter decrement would not become globally visible until the
+obj->active update does.
+
+As a historical note, 32-bit Sparc used to only allow usage of
+24-bits of its atomic_t type.  This was because it used 8 bits
+as a spinlock for SMP safety.  Sparc32 lacked a "compare and swap"
+type instruction.  However, 32-bit Sparc has since been moved over
+to a "hash table of spinlocks" scheme, that allows the full 32-bit
+counter to be realized.  Essentially, an array of spinlocks are
+indexed into based upon the address of the atomic_t being operated
+on, and that lock protects the atomic operation.  Parisc uses the
+same scheme.
+
+Another note is that the atomic_t operations returning values are
+extremely slow on an old 386.
+
+
+Atomic Bitmask
+==============
+
+We will now cover the atomic bitmask operations.  You will find that
+their SMP and memory barrier semantics are similar in shape and scope
+to the atomic_t ops above.
+
+Native atomic bit operations are defined to operate on objects aligned
+to the size of an "unsigned long" C data type, and are least of that
+size.  The endianness of the bits within each "unsigned long" are the
+native endianness of the cpu. ::
+
+	void set_bit(unsigned long nr, volatile unsigned long *addr);
+	void clear_bit(unsigned long nr, volatile unsigned long *addr);
+	void change_bit(unsigned long nr, volatile unsigned long *addr);
+
+These routines set, clear, and change, respectively, the bit number
+indicated by "nr" on the bit mask pointed to by "ADDR".
+
+They must execute atomically, yet there are no implicit memory barrier
+semantics required of these interfaces. ::
+
+	int test_and_set_bit(unsigned long nr, volatile unsigned long *addr);
+	int test_and_clear_bit(unsigned long nr, volatile unsigned long *addr);
+	int test_and_change_bit(unsigned long nr, volatile unsigned long *addr);
+
+Like the above, except that these routines return a boolean which
+indicates whether the changed bit was set _BEFORE_ the atomic bit
+operation.
+
+WARNING! It is incredibly important that the value be a boolean,
+ie. "0" or "1".  Do not try to be fancy and save a few instructions by
+declaring the above to return "long" and just returning something like
+"old_val & mask" because that will not work.
+
+For one thing, this return value gets truncated to int in many code
+paths using these interfaces, so on 64-bit if the bit is set in the
+upper 32-bits then testers will never see that.
+
+One great example of where this problem crops up are the thread_info
+flag operations.  Routines such as test_and_set_ti_thread_flag() chop
+the return value into an int.  There are other places where things
+like this occur as well.
+
+These routines, like the atomic_t counter operations returning values,
+must provide explicit memory barrier semantics around their execution.
+All memory operations before the atomic bit operation call must be
+made visible globally before the atomic bit operation is made visible.
+Likewise, the atomic bit operation must be visible globally before any
+subsequent memory operation is made visible.  For example::
+
+	obj->dead = 1;
+	if (test_and_set_bit(0, &obj->flags))
+		/* ... */;
+	obj->killed = 1;
+
+The implementation of test_and_set_bit() must guarantee that
+"obj->dead = 1;" is visible to cpus before the atomic memory operation
+done by test_and_set_bit() becomes visible.  Likewise, the atomic
+memory operation done by test_and_set_bit() must become visible before
+"obj->killed = 1;" is visible.
+
+Finally there is the basic operation::
+
+	int test_bit(unsigned long nr, __const__ volatile unsigned long *addr);
+
+Which returns a boolean indicating if bit "nr" is set in the bitmask
+pointed to by "addr".
+
+If explicit memory barriers are required around {set,clear}_bit() (which do
+not return a value, and thus does not need to provide memory barrier
+semantics), two interfaces are provided::
+
+	void smp_mb__before_atomic(void);
+	void smp_mb__after_atomic(void);
+
+They are used as follows, and are akin to their atomic_t operation
+brothers::
+
+	/* All memory operations before this call will
+	 * be globally visible before the clear_bit().
+	 */
+	smp_mb__before_atomic();
+	clear_bit( ... );
+
+	/* The clear_bit() will be visible before all
+	 * subsequent memory operations.
+	 */
+	 smp_mb__after_atomic();
+
+There are two special bitops with lock barrier semantics (acquire/release,
+same as spinlocks). These operate in the same way as their non-_lock/unlock
+postfixed variants, except that they are to provide acquire/release semantics,
+respectively. This means they can be used for bit_spin_trylock and
+bit_spin_unlock type operations without specifying any more barriers. ::
+
+	int test_and_set_bit_lock(unsigned long nr, unsigned long *addr);
+	void clear_bit_unlock(unsigned long nr, unsigned long *addr);
+	void __clear_bit_unlock(unsigned long nr, unsigned long *addr);
+
+The __clear_bit_unlock version is non-atomic, however it still implements
+unlock barrier semantics. This can be useful if the lock itself is protecting
+the other bits in the word.
+
+Finally, there are non-atomic versions of the bitmask operations
+provided.  They are used in contexts where some other higher-level SMP
+locking scheme is being used to protect the bitmask, and thus less
+expensive non-atomic operations may be used in the implementation.
+They have names similar to the above bitmask operation interfaces,
+except that two underscores are prefixed to the interface name. ::
+
+	void __set_bit(unsigned long nr, volatile unsigned long *addr);
+	void __clear_bit(unsigned long nr, volatile unsigned long *addr);
+	void __change_bit(unsigned long nr, volatile unsigned long *addr);
+	int __test_and_set_bit(unsigned long nr, volatile unsigned long *addr);
+	int __test_and_clear_bit(unsigned long nr, volatile unsigned long *addr);
+	int __test_and_change_bit(unsigned long nr, volatile unsigned long *addr);
+
+These non-atomic variants also do not require any special memory
+barrier semantics.
+
+The routines xchg() and cmpxchg() must provide the same exact
+memory-barrier semantics as the atomic and bit operations returning
+values.
+
+.. note::
+
+	If someone wants to use xchg(), cmpxchg() and their variants,
+	linux/atomic.h should be included rather than asm/cmpxchg.h, unless the
+	code is in arch/* and can take care of itself.
+
+Spinlocks and rwlocks have memory barrier expectations as well.
+The rule to follow is simple:
+
+1) When acquiring a lock, the implementation must make it globally
+   visible before any subsequent memory operation.
+
+2) When releasing a lock, the implementation must make it such that
+   all previous memory operations are globally visible before the
+   lock release.
+
+Which finally brings us to _atomic_dec_and_lock().  There is an
+architecture-neutral version implemented in lib/dec_and_lock.c,
+but most platforms will wish to optimize this in assembler. ::
+
+	int _atomic_dec_and_lock(atomic_t *atomic, spinlock_t *lock);
+
+Atomically decrement the given counter, and if will drop to zero
+atomically acquire the given spinlock and perform the decrement
+of the counter to zero.  If it does not drop to zero, do nothing
+with the spinlock.
+
+It is actually pretty simple to get the memory barrier correct.
+Simply satisfy the spinlock grab requirements, which is make
+sure the spinlock operation is globally visible before any
+subsequent memory operation.
+
+We can demonstrate this operation more clearly if we define
+an abstract atomic operation::
+
+	long cas(long *mem, long old, long new);
+
+"cas" stands for "compare and swap".  It atomically:
+
+1) Compares "old" with the value currently at "mem".
+2) If they are equal, "new" is written to "mem".
+3) Regardless, the current value at "mem" is returned.
+
+As an example usage, here is what an atomic counter update
+might look like::
+
+	void example_atomic_inc(long *counter)
+	{
+		long old, new, ret;
+
+		while (1) {
+			old = *counter;
+			new = old + 1;
+
+			ret = cas(counter, old, new);
+			if (ret == old)
+				break;
+		}
+	}
+
+Let's use cas() in order to build a pseudo-C atomic_dec_and_lock()::
+
+	int _atomic_dec_and_lock(atomic_t *atomic, spinlock_t *lock)
+	{
+		long old, new, ret;
+		int went_to_zero;
+
+		went_to_zero = 0;
+		while (1) {
+			old = atomic_read(atomic);
+			new = old - 1;
+			if (new == 0) {
+				went_to_zero = 1;
+				spin_lock(lock);
+			}
+			ret = cas(atomic, old, new);
+			if (ret == old)
+				break;
+			if (went_to_zero) {
+				spin_unlock(lock);
+				went_to_zero = 0;
+			}
+		}
+
+		return went_to_zero;
+	}
+
+Now, as far as memory barriers go, as long as spin_lock()
+strictly orders all subsequent memory operations (including
+the cas()) with respect to itself, things will be fine.
+
+Said another way, _atomic_dec_and_lock() must guarantee that
+a counter dropping to zero is never made visible before the
+spinlock being acquired.
+
+.. note::
+
+	Note that this also means that for the case where the counter is not
+	dropping to zero, there are no memory ordering requirements.
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index f53555ee4931..25b4e4a4d017 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -8,6 +8,7 @@ Kernel and driver related documentation.
    :maxdepth: 1
 
    assoc_array
+   atomic_ops
    local_ops
    workqueue
 
diff --git a/Documentation/process/volatile-considered-harmful.rst b/Documentation/process/volatile-considered-harmful.rst
index e0d042af386c..4934e656a6f3 100644
--- a/Documentation/process/volatile-considered-harmful.rst
+++ b/Documentation/process/volatile-considered-harmful.rst
@@ -1,3 +1,6 @@
+
+.. _volatile_considered_harmful:
+
 Why the "volatile" type class should not be used
 ------------------------------------------------
 
-- 
cgit v1.2.3


From 7d56f0facd6c1cb4ed2169bb8e65294bfd7783f8 Mon Sep 17 00:00:00 2001
From: Sanjeev 
Date: Thu, 1 Dec 2016 23:36:00 +0800
Subject: Doc: Correct typo, "Introdution" => "Introduction"

This corrects a set of spelling mistakes, probably from an
automated conversion.

Signed-off-by: Sanjeev Gupta 
Signed-off-by: Jonathan Corbet 
---
 Documentation/admin-guide/unicode.rst         | 4 ++--
 Documentation/media/dvb-drivers/intro.rst     | 4 ++--
 Documentation/media/v4l-drivers/cafe_ccic.rst | 4 ++--
 Documentation/process/1.Intro.rst             | 4 ++--
 4 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/admin-guide/unicode.rst b/Documentation/admin-guide/unicode.rst
index 4e5c3df9d55f..7425a3351321 100644
--- a/Documentation/admin-guide/unicode.rst
+++ b/Documentation/admin-guide/unicode.rst
@@ -9,8 +9,8 @@ The current version can be found at:
 
 	    http://www.lanana.org/docs/unicode/admin-guide/unicode.rst
 
-Introdution
------------
+Introduction
+------------
 
 The Linux kernel code has been rewritten to use Unicode to map
 characters to fonts.  By downloading a single Unicode-to-font table,
diff --git a/Documentation/media/dvb-drivers/intro.rst b/Documentation/media/dvb-drivers/intro.rst
index 7681835ea76d..d6eeb2708b9b 100644
--- a/Documentation/media/dvb-drivers/intro.rst
+++ b/Documentation/media/dvb-drivers/intro.rst
@@ -1,5 +1,5 @@
-Introdution
-===========
+Introduction
+============
 
 The main development site and GIT repository for these
 drivers is https://linuxtv.org.
diff --git a/Documentation/media/v4l-drivers/cafe_ccic.rst b/Documentation/media/v4l-drivers/cafe_ccic.rst
index b98eb3b7cb4a..94f0f58ebe37 100644
--- a/Documentation/media/v4l-drivers/cafe_ccic.rst
+++ b/Documentation/media/v4l-drivers/cafe_ccic.rst
@@ -3,8 +3,8 @@ The cafe_ccic driver
 
 Author: Jonathan Corbet 
 
-Introdution
------------
+Introduction
+------------
 
 "cafe_ccic" is a driver for the Marvell 88ALP01 "cafe" CMOS camera
 controller.  This is the controller found in first-generation OLPC systems,
diff --git a/Documentation/process/1.Intro.rst b/Documentation/process/1.Intro.rst
index 22642b3fe903..e782ae2eef58 100644
--- a/Documentation/process/1.Intro.rst
+++ b/Documentation/process/1.Intro.rst
@@ -1,5 +1,5 @@
-Introdution
-===========
+Introduction
+============
 
 Executive summary
 -----------------
-- 
cgit v1.2.3


From c3cbd075fce77cf3f8782be9f971e8257508c98e Mon Sep 17 00:00:00 2001
From: Balbir Singh 
Date: Fri, 2 Dec 2016 00:08:26 +1100
Subject: ppc/idle: Add documentation for powersave=off

Update kernel-parameters.txt to add Documentation
for powersave=off.

Signed-off-by: Balbir Singh 
Signed-off-by: Jonathan Corbet 
---
 Documentation/admin-guide/kernel-parameters.txt | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index e48c5632bd6c..456248b27220 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -3036,6 +3036,12 @@
 			may be specified.
 			Format: ,....
 
+	powersave=off	[PPC] This option disables power saving features.
+			It specifically disables cpuidle and sets the
+			platform machine description specific power_save
+			function to NULL. On Idle the CPU just reduces
+			execution priority.
+
 	ppc_strict_facility_enable
 			[PPC] This option catches any kernel floating point,
 			Altivec, VSX and SPE outside of regions specifically
-- 
cgit v1.2.3


From 2ba90ccca7758fe77f47750dc8a938a99b8bd4af Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Thu, 1 Dec 2016 10:15:11 -0200
Subject: core-api: remove an unexpected unident

As complained by Sphinx:
	Documentation/core-api/assoc_array.rst:13: WARNING: Enumerated list ends without a blank line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/core-api/assoc_array.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/core-api/assoc_array.rst b/Documentation/core-api/assoc_array.rst
index dcda7c623cec..d83cfff9ea43 100644
--- a/Documentation/core-api/assoc_array.rst
+++ b/Documentation/core-api/assoc_array.rst
@@ -10,7 +10,7 @@ properties:
 
 1. Objects are opaque pointers.  The implementation does not care where they
    point (if anywhere) or what they point to (if anything).
-.. note:: Pointers to objects _must_ be zero in the least significant bit.**
+.. note:: Pointers to objects _must_ be zero in the least significant bit.
 
 2. Objects do not need to contain linkage blocks for use by the array.  This
    permits an object to be located in multiple arrays simultaneously.
-- 
cgit v1.2.3


From aad800403a8761073511abb93075738302983956 Mon Sep 17 00:00:00 2001
From: Lukas Wunner 
Date: Sun, 4 Dec 2016 13:10:04 +0100
Subject: Documentation/core-api/device_link: Add initial documentation

Document device links as introduced in v4.10 with commits:
    4bdb35506b89 ("driver core: Add a wrapper around
                   __device_release_driver()")
    9ed9895370ae ("driver core: Functional dependencies tracking
                   support")
    8c73b4288496 ("PM / sleep: Make async suspend/resume of devices use
                   device links")
    21d5c57b3726 ("PM / runtime: Use device links")
    baa8809f6097 ("PM / runtime: Optimize the use of device links")

Signed-off-by: Lukas Wunner 
[ jc: Moved from core-api to driver-api ]
Signed-off-by: Jonathan Corbet 
---
 Documentation/driver-api/device_link.rst | 279 +++++++++++++++++++++++++++++++
 Documentation/driver-api/index.rst       |   1 +
 2 files changed, 280 insertions(+)
 create mode 100644 Documentation/driver-api/device_link.rst

diff --git a/Documentation/driver-api/device_link.rst b/Documentation/driver-api/device_link.rst
new file mode 100644
index 000000000000..5f5713448703
--- /dev/null
+++ b/Documentation/driver-api/device_link.rst
@@ -0,0 +1,279 @@
+============
+Device links
+============
+
+By default, the driver core only enforces dependencies between devices
+that are borne out of a parent/child relationship within the device
+hierarchy: When suspending, resuming or shutting down the system, devices
+are ordered based on this relationship, i.e. children are always suspended
+before their parent, and the parent is always resumed before its children.
+
+Sometimes there is a need to represent device dependencies beyond the
+mere parent/child relationship, e.g. between siblings, and have the
+driver core automatically take care of them.
+
+Secondly, the driver core by default does not enforce any driver presence
+dependencies, i.e. that one device must be bound to a driver before
+another one can probe or function correctly.
+
+Often these two dependency types come together, so a device depends on
+another one both with regards to driver presence *and* with regards to
+suspend/resume and shutdown ordering.
+
+Device links allow representation of such dependencies in the driver core.
+
+In its standard form, a device link combines *both* dependency types:
+It guarantees correct suspend/resume and shutdown ordering between a
+"supplier" device and its "consumer" devices, and it guarantees driver
+presence on the supplier.  The consumer devices are not probed before the
+supplier is bound to a driver, and they're unbound before the supplier
+is unbound.
+
+When driver presence on the supplier is irrelevant and only correct
+suspend/resume and shutdown ordering is needed, the device link may
+simply be set up with the ``DL_FLAG_STATELESS`` flag.  In other words,
+enforcing driver presence on the supplier is optional.
+
+Another optional feature is runtime PM integration:  By setting the
+``DL_FLAG_PM_RUNTIME`` flag on addition of the device link, the PM core
+is instructed to runtime resume the supplier and keep it active
+whenever and for as long as the consumer is runtime resumed.
+
+Usage
+=====
+
+The earliest point in time when device links can be added is after
+:c:func:`device_add()` has been called for the supplier and
+:c:func:`device_initialize()` has been called for the consumer.
+
+It is legal to add them later, but care must be taken that the system
+remains in a consistent state:  E.g. a device link cannot be added in
+the midst of a suspend/resume transition, so either commencement of
+such a transition needs to be prevented with :c:func:`lock_system_sleep()`,
+or the device link needs to be added from a function which is guaranteed
+not to run in parallel to a suspend/resume transition, such as from a
+device ``->probe`` callback or a boot-time PCI quirk.
+
+Another example for an inconsistent state would be a device link that
+represents a driver presence dependency, yet is added from the consumer's
+``->probe`` callback while the supplier hasn't probed yet:  Had the driver
+core known about the device link earlier, it wouldn't have probed the
+consumer in the first place.  The onus is thus on the consumer to check
+presence of the supplier after adding the link, and defer probing on
+non-presence.
+
+If a device link is added in the ``->probe`` callback of the supplier or
+consumer driver, it is typically deleted in its ``->remove`` callback for
+symmetry.  That way, if the driver is compiled as a module, the device
+link is added on module load and orderly deleted on unload.  The same
+restrictions that apply to device link addition (e.g. exclusion of a
+parallel suspend/resume transition) apply equally to deletion.
+
+Several flags may be specified on device link addition, two of which
+have already been mentioned above:  ``DL_FLAG_STATELESS`` to express that no
+driver presence dependency is needed (but only correct suspend/resume and
+shutdown ordering) and ``DL_FLAG_PM_RUNTIME`` to express that runtime PM
+integration is desired.
+
+Two other flags are specifically targeted at use cases where the device
+link is added from the consumer's ``->probe`` callback:  ``DL_FLAG_RPM_ACTIVE``
+can be specified to runtime resume the supplier upon addition of the
+device link.  ``DL_FLAG_AUTOREMOVE`` causes the device link to be automatically
+purged when the consumer fails to probe or later unbinds.  This obviates
+the need to explicitly delete the link in the ``->remove`` callback or in
+the error path of the ``->probe`` callback.
+
+Limitations
+===========
+
+Driver authors should be aware that a driver presence dependency (i.e. when
+``DL_FLAG_STATELESS`` is not specified on link addition) may cause probing of
+the consumer to be deferred indefinitely.  This can become a problem if the
+consumer is required to probe before a certain initcall level is reached.
+Worse, if the supplier driver is blacklisted or missing, the consumer will
+never be probed.
+
+Sometimes drivers depend on optional resources.  They are able to operate
+in a degraded mode (reduced feature set or performance) when those resources
+are not present.  An example is an SPI controller that can use a DMA engine
+or work in PIO mode.  The controller can determine presence of the optional
+resources at probe time but on non-presence there is no way to know whether
+they will become available in the near future (due to a supplier driver
+probing) or never.  Consequently it cannot be determined whether to defer
+probing or not.  It would be possible to notify drivers when optional
+resources become available after probing, but it would come at a high cost
+for drivers as switching between modes of operation at runtime based on the
+availability of such resources would be much more complex than a mechanism
+based on probe deferral.  In any case optional resources are beyond the
+scope of device links.
+
+Examples
+========
+
+* An MMU device exists alongside a busmaster device, both are in the same
+  power domain.  The MMU implements DMA address translation for the busmaster
+  device and shall be runtime resumed and kept active whenever and as long
+  as the busmaster device is active.  The busmaster device's driver shall
+  not bind before the MMU is bound.  To achieve this, a device link with
+  runtime PM integration is added from the busmaster device (consumer)
+  to the MMU device (supplier).  The effect with regards to runtime PM
+  is the same as if the MMU was the parent of the master device.
+
+  The fact that both devices share the same power domain would normally
+  suggest usage of a :c:type:`struct dev_pm_domain` or :c:type:`struct
+  generic_pm_domain`, however these are not independent devices that
+  happen to share a power switch, but rather the MMU device serves the
+  busmaster device and is useless without it.  A device link creates a
+  synthetic hierarchical relationship between the devices and is thus
+  more apt.
+
+* A Thunderbolt host controller comprises a number of PCIe hotplug ports
+  and an NHI device to manage the PCIe switch.  On resume from system sleep,
+  the NHI device needs to re-establish PCI tunnels to attached devices
+  before the hotplug ports can resume.  If the hotplug ports were children
+  of the NHI, this resume order would automatically be enforced by the
+  PM core, but unfortunately they're aunts.  The solution is to add
+  device links from the hotplug ports (consumers) to the NHI device
+  (supplier).  A driver presence dependency is not necessary for this
+  use case.
+
+* Discrete GPUs in hybrid graphics laptops often feature an HDA controller
+  for HDMI/DP audio.  In the device hierarchy the HDA controller is a sibling
+  of the VGA device, yet both share the same power domain and the HDA
+  controller is only ever needed when an HDMI/DP display is attached to the
+  VGA device.  A device link from the HDA controller (consumer) to the
+  VGA device (supplier) aptly represents this relationship.
+
+* ACPI allows definition of a device start order by way of _DEP objects.
+  A classical example is when ACPI power management methods on one device
+  are implemented in terms of I\ :sup:`2`\ C accesses and require a specific
+  I\ :sup:`2`\ C controller to be present and functional for the power
+  management of the device in question to work.
+
+* In some SoCs a functional dependency exists from display, video codec and
+  video processing IP cores on transparent memory access IP cores that handle
+  burst access and compression/decompression.
+
+Alternatives
+============
+
+* A :c:type:`struct dev_pm_domain` can be used to override the bus,
+  class or device type callbacks.  It is intended for devices sharing
+  a single on/off switch, however it does not guarantee a specific
+  suspend/resume ordering, this needs to be implemented separately.
+  It also does not by itself track the runtime PM status of the involved
+  devices and turn off the power switch only when all of them are runtime
+  suspended.  Furthermore it cannot be used to enforce a specific shutdown
+  ordering or a driver presence dependency.
+
+* A :c:type:`struct generic_pm_domain` is a lot more heavyweight than a
+  device link and does not allow for shutdown ordering or driver presence
+  dependencies.  It also cannot be used on ACPI systems.
+
+Implementation
+==============
+
+The device hierarchy, which -- as the name implies -- is a tree,
+becomes a directed acyclic graph once device links are added.
+
+Ordering of these devices during suspend/resume is determined by the
+dpm_list.  During shutdown it is determined by the devices_kset.  With
+no device links present, the two lists are a flattened, one-dimensional
+representations of the device tree such that a device is placed behind
+all its ancestors.  That is achieved by traversing the ACPI namespace
+or OpenFirmware device tree top-down and appending devices to the lists
+as they are discovered.
+
+Once device links are added, the lists need to satisfy the additional
+constraint that a device is placed behind all its suppliers, recursively.
+To ensure this, upon addition of the device link the consumer and the
+entire sub-graph below it (all children and consumers of the consumer)
+are moved to the end of the list.  (Call to :c:func:`device_reorder_to_tail()`
+from :c:func:`device_link_add()`.)
+
+To prevent introduction of dependency loops into the graph, it is
+verified upon device link addition that the supplier is not dependent
+on the consumer or any children or consumers of the consumer.
+(Call to :c:func:`device_is_dependent()` from :c:func:`device_link_add()`.)
+If that constraint is violated, :c:func:`device_link_add()` will return
+``NULL`` and a ``WARNING`` will be logged.
+
+Notably this also prevents the addition of a device link from a parent
+device to a child.  However the converse is allowed, i.e. a device link
+from a child to a parent.  Since the driver core already guarantees
+correct suspend/resume and shutdown ordering between parent and child,
+such a device link only makes sense if a driver presence dependency is
+needed on top of that.  In this case driver authors should weigh
+carefully if a device link is at all the right tool for the purpose.
+A more suitable approach might be to simply use deferred probing or
+add a device flag causing the parent driver to be probed before the
+child one.
+
+State machine
+=============
+
+.. kernel-doc:: include/linux/device.h
+   :functions: device_link_state
+
+::
+
+                 .=============================.
+                 |                             |
+                 v                             |
+ DORMANT <=> AVAILABLE <=> CONSUMER_PROBE => ACTIVE
+    ^                                          |
+    |                                          |
+    '============ SUPPLIER_UNBIND <============'
+
+* The initial state of a device link is automatically determined by
+  :c:func:`device_link_add()` based on the driver presence on the supplier
+  and consumer.  If the link is created before any devices are probed, it
+  is set to ``DL_STATE_DORMANT``.
+
+* When a supplier device is bound to a driver, links to its consumers
+  progress to ``DL_STATE_AVAILABLE``.
+  (Call to :c:func:`device_links_driver_bound()` from
+  :c:func:`driver_bound()`.)
+
+* Before a consumer device is probed, presence of supplier drivers is
+  verified by checking that links to suppliers are in ``DL_STATE_AVAILABLE``
+  state.  The state of the links is updated to ``DL_STATE_CONSUMER_PROBE``.
+  (Call to :c:func:`device_links_check_suppliers()` from
+  :c:func:`really_probe()`.)
+  This prevents the supplier from unbinding.
+  (Call to :c:func:`wait_for_device_probe()` from
+  :c:func:`device_links_unbind_consumers()`.)
+
+* If the probe fails, links to suppliers revert back to ``DL_STATE_AVAILABLE``.
+  (Call to :c:func:`device_links_no_driver()` from :c:func:`really_probe()`.)
+
+* If the probe succeeds, links to suppliers progress to ``DL_STATE_ACTIVE``.
+  (Call to :c:func:`device_links_driver_bound()` from :c:func:`driver_bound()`.)
+
+* When the consumer's driver is later on removed, links to suppliers revert
+  back to ``DL_STATE_AVAILABLE``.
+  (Call to :c:func:`__device_links_no_driver()` from
+  :c:func:`device_links_driver_cleanup()`, which in turn is called from
+  :c:func:`__device_release_driver()`.)
+
+* Before a supplier's driver is removed, links to consumers that are not
+  bound to a driver are updated to ``DL_STATE_SUPPLIER_UNBIND``.
+  (Call to :c:func:`device_links_busy()` from
+  :c:func:`__device_release_driver()`.)
+  This prevents the consumers from binding.
+  (Call to :c:func:`device_links_check_suppliers()` from
+  :c:func:`really_probe()`.)
+  Consumers that are bound are freed from their driver; consumers that are
+  probing are waited for until they are done.
+  (Call to :c:func:`device_links_unbind_consumers()` from
+  :c:func:`__device_release_driver()`.)
+  Once all links to consumers are in ``DL_STATE_SUPPLIER_UNBIND`` state,
+  the supplier driver is released and the links revert to ``DL_STATE_DORMANT``.
+  (Call to :c:func:`device_links_driver_cleanup()` from
+  :c:func:`__device_release_driver()`.)
+
+API
+===
+
+.. kernel-doc:: drivers/base/core.c
+   :functions: device_link_add device_link_del
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 0dec394b9038..0823a6a52f43 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -16,6 +16,7 @@ available subsections can be seen below.
 
    basics
    infrastructure
+   device_link
    message-based
    sound
    frame-buffer
-- 
cgit v1.2.3


From 20b786eb2598ac10c9743535b65611ce808c8d71 Mon Sep 17 00:00:00 2001
From: Kevin Peng 
Date: Sun, 4 Dec 2016 02:58:02 -0800
Subject: Docs: change sh -> awk in REPORTING-BUGS

scripts/ver_linux has been rewritten as an awk script; update
documentation to reflect this fact.

Signed-off-by: Kevin Peng 
Signed-off-by: Jonathan Corbet 
---
 Documentation/admin-guide/reporting-bugs.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
index 0c0f2698ec5a..26b60b419652 100644
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ b/Documentation/admin-guide/reporting-bugs.rst
@@ -106,7 +106,7 @@ relevant to your bug, feel free to exclude it.
 
 First run the ver_linux script included as scripts/ver_linux, which
 reports the version of some important subsystems.  Run this script with
-the command ``sh scripts/ver_linux``.
+the command ``awk -f scripts/ver_linux``.
 
 Use that information to fill in all fields of the bug report form, and
 post it to the mailing list with a subject of "PROBLEM: 
Date: Mon, 5 Dec 2016 09:41:41 -0200
Subject: scripts: add a script to check if Documentation/00-INDEX is sane

It is easy to forget adding/removing entries at the
Documentation/00-INDEX file. In a matter of fact, even before
ReST conversion, people use to forget adding things here, as
there are lots of missing stuff out there.

Now that we're doing a hard work converting entries to ReST,
and while this hole file is not outdated, it is good to have
some tool that would help to verify that this file is kept
updated.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 scripts/check_00index.sh | 66 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100755 scripts/check_00index.sh

diff --git a/scripts/check_00index.sh b/scripts/check_00index.sh
new file mode 100755
index 000000000000..6ac9527aeddb
--- /dev/null
+++ b/scripts/check_00index.sh
@@ -0,0 +1,66 @@
+#!/bin/bash
+
+cd Documentation/
+
+# Check entries that should be removed
+
+obsolete=""
+for i in $(tail -n +12 00-INDEX |grep -E '^[a-zA-Z0-9]+'); do
+	if [ ! -e $i ]; then
+		obsolete="$obsolete $i"
+	fi
+done
+
+# Check directory entries that should be added
+search=""
+dir=""
+for i in $(find . -maxdepth 1 -type d); do
+	if [ "$i" != "." ]; then
+		new=$(echo $i|perl -ne 's,./(.*),$1/,; print $_')
+		search="$search $new"
+	fi
+done
+
+for i in $search; do
+	if [ "$(grep -P "^$i" 00-INDEX)" == "" ]; then
+		dir="$dir $i"
+	fi
+done
+
+# Check file entries that should be added
+search=""
+file=""
+for i in $(find . -maxdepth 1 -type f); do
+	if [ "$i" != "./.gitignore" ]; then
+		new=$(echo $i|perl -ne 's,./(.*),$1,; print $_')
+		search="$search $new"
+	fi
+done
+
+for i in $search; do
+	if [ "$(grep -P "^$i\$" 00-INDEX)" == "" ]; then
+		file="$file $i"
+	fi
+done
+
+# Output its findings
+
+echo -e "Documentation/00-INDEX check results:\n"
+
+if [ "$obsolete" != "" ]; then
+	echo -e "- Should remove those entries:\n\t$obsolete\n"
+else
+	echo -e "- No obsolete entries\n"
+fi
+
+if [ "$dir" != "" ]; then
+	echo -e "- Should document those directories:\n\t$dir\n"
+else
+	echo -e "- No new directories to add\n"
+fi
+
+if [ "$file" != "" ]; then
+	echo -e "- Should document those files:\n\t$file"
+else
+	echo "- No new files to add"
+fi
-- 
cgit v1.2.3


From 79c87c30d0e6d02b2a7d0f1eed372d0979c03930 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 5 Dec 2016 09:41:42 -0200
Subject: docs: 00-INDEX: consolidate process/ and admin-guide/ description

Instead of having descriptions for individual files inside
the process/ and admin-guide/ documentation, consolidate them
into one entry per directory, just like other descriptions
inside 00-INDEX.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/00-INDEX | 61 ++++----------------------------------------------
 1 file changed, 4 insertions(+), 57 deletions(-)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index c08de5574d48..02583a1f409c 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -14,13 +14,6 @@ Following translations are available on the WWW:
 	- this file.
 ABI/
 	- info on kernel <-> userspace ABI and relative interface stability.
-
-admin-guide/bug-hunting.rst
-	- brute force method of doing binary search of patches to find bug.
-process/changes.rst
-	- list of changes that break older software packages.
-process/coding-style.rst
-	- how the maintainers expect the C code in the kernel to look.
 DMA-API.txt
 	- DMA API, pci_ API & extensions for non-consistent memory machines.
 DMA-API-HOWTO.txt
@@ -33,8 +26,6 @@ DocBook/
 	- directory with DocBook templates etc. for kernel documentation.
 EDID/
 	- directory with info on customizing EDID for broken gfx/displays.
-process/howto.rst
-	- the process and procedures of how to do Linux kernel development.
 IPMI.txt
 	- info on Linux Intelligent Platform Management Interface (IPMI) Driver.
 IRQ-affinity.txt
@@ -48,32 +39,22 @@ Intel-IOMMU.txt
 Makefile
 	- This file does nothing. Removing it breaks make htmldocs and
 	  make distclean.
-process/management-style.rst
-	- how to (attempt to) manage kernel hackers.
 RCU/
 	- directory with info on RCU (read-copy update).
 SAK.txt
 	- info on Secure Attention Keys.
 SM501.txt
 	- Silicon Motion SM501 multimedia companion chip
-admin-guide/security-bugs.rst
-	- procedure for reporting security bugs found in the kernel.
-process/submit-checklist.rst
-	- Linux kernel patch submission checklist.
-process/submitting-drivers.rst
-	- procedure to get a new driver source included into the kernel tree.
-process/submitting-patches.rst
-	- procedure to get a source patch included into the kernel tree.
 VGA-softcursor.txt
 	- how to change your VGA cursor from a blinking underscore.
 accounting/
 	- documentation on accounting and taskstats.
 acpi/
 	- info on ACPI-specific hooks in the kernel.
+admin-guide/
+	- info related to Linux users and system admins.
 aoe/
 	- description of AoE (ATA over Ethernet) along with config examples.
-process/applying-patches.rst
-	- description of various trees and how to apply their patches.
 arm/
 	- directory with info about Linux on the ARM architecture.
 arm64/
@@ -86,8 +67,6 @@ auxdisplay/
 	- misc. LCD driver documentation (cfag12864b, ks0108).
 backlight/
 	- directory with info on controlling backlights in flat panel displays
-admin-guide/bad-memory.rst
-	- how to use kernel parameters to exclude bad RAM regions.
 basic_profiling.txt
 	- basic instructions for those who wants to profile Linux kernel.
 bcache.txt
@@ -152,12 +131,8 @@ debugging-via-ohci1394.txt
 	- how to use firewire like a hardware debugger memory reader.
 dell_rbu.txt
 	- document demonstrating the use of the Dell Remote BIOS Update driver.
-process/
-	- how to work with the mainline kernel development process.
 device-mapper/
 	- directory with info on Device Mapper.
-admin-guide/devices.rst
-	- plain ASCII listing of all the nodes in /dev/ with major minor #'s.
 devicetree/
 	- directory with info on device tree files used by OF/PowerPC/ARM
 digsig.txt
@@ -178,8 +153,6 @@ efi-stub.txt
 	- How to use the EFI boot stub to bypass GRUB or elilo on EFI systems.
 eisa.txt
 	- info on EISA bus support.
-process/email-clients.rst
-	- info on how to use e-mail to send un-mangled (git) patches.
 extcon/
 	- directory with porting guide for Android kernel switch driver.
 fault-injection/
@@ -226,10 +199,6 @@ ia64/
 	- directory with info about Linux on Intel 64 bit architecture.
 infiniband/
 	- directory with documents concerning Linux InfiniBand support.
-admin-guide/init.rst
-	- what to do when the kernel can't find the 1st process to run.
-admin-guide/initrd.rst
-	- how to use the RAM disk as an initial/temporary root filesystem.
 input/
 	- info on Linux input device support.
 intel_txt.txt
@@ -248,20 +217,14 @@ isapnp.txt
 	- info on Linux ISA Plug & Play support.
 isdn/
 	- directory with info on the Linux ISDN support, and supported cards.
-admin-guide/java.rst
-	- info on the in-kernel binary support for Java(tm).
 ja_JP/
 	- directory with Japanese translations of various documents
 kbuild/
 	- directory with info about the kernel build process.
 kdump/
 	- directory with mini HowTo on getting the crash dump code to work.
-process/kernel-docs.rst
-	- listing of various WWW + books that document kernel internals.
 doc-guide/
 	- how to write and format reStructuredText kernel documentation
-admin-guide/kernel-parameters.rst
-	- summary listing of command line / boot prompt args for the kernel.
 kernel-per-CPU-kthreads.txt
 	- List of all per-CPU kthreads and how they introduce jitter.
 kmemcheck.txt
@@ -302,8 +265,6 @@ magic-number.txt
 	- list of magic numbers used to mark/protect kernel data structures.
 mailbox.txt
 	- How to write drivers for the common mailbox framework (IPC).
-admin-guide/md.rst
-	- info on boot arguments for the multiple devices driver.
 media-framework.txt
 	- info on media framework, its data structures, functions and usage.
 memory-barriers.txt
@@ -326,8 +287,6 @@ module-signing.txt
 	- Kernel module signing for increased security when loading modules.
 mtd/
 	- directory with info about memory technology devices (flash)
-admin-guide/mono.rst
-	- how to execute Mono-based .NET binaries with the help of BINFMT_MISC.
 namespaces/
 	- directory with various information about namespaces
 netlabel/
@@ -340,8 +299,6 @@ nommu-mmap.txt
 	- documentation about no-mmu memory mapping support.
 numastat.txt
 	- info on how to read Numa policy hit/miss statistics in sysfs.
-admin-guide/oops-tracing.rst
-	- how to decode those nasty internal kernel error dump messages.
 padata.txt
 	- An introduction to the "padata" parallel execution API
 parisc/
@@ -372,14 +329,14 @@ preempt-locking.txt
 	- info on locking under a preemptive kernel.
 printk-formats.txt
 	- how to get printk format specifiers right
+process/
+	- how to work with the mainline kernel development process.
 pps/
 	- directory with information on the pulse-per-second support
 ptp/
 	- directory with info on support for IEEE 1588 PTP clocks in Linux.
 pwm.txt
 	- info on the pulse width modulation driver subsystem
-admin-guide/ramoops.rst
-	- documentation of the ramoops oops/panic logging module.
 rapidio/
 	- directory with info on RapidIO packet-based fabric interconnect
 rbtree.txt
@@ -406,8 +363,6 @@ security/
 	- directory that contains security-related info
 serial/
 	- directory with info on the low level serial API.
-admin-guide/serial-console.rst
-	- how to set up Linux with a serial line console as the default.
 sgi-ioc4.txt
 	- description of the SGI IOC4 PCI (multi function) device.
 sh/
@@ -420,10 +375,6 @@ sparse.txt
 	- info on how to obtain and use the sparse tool for typechecking.
 spi/
 	- overview of Linux kernel Serial Peripheral Interface (SPI) support.
-process/stable-api-nonsense.rst
-	- info on why the kernel does not have a stable in-kernel api or abi.
-process/stable-kernel-rules.rst
-	- rules and procedures for the -stable kernel releases.
 static-keys.txt
 	- info on how static keys allow debug code in hotpaths via patching
 svga.txt
@@ -444,8 +395,6 @@ trace/
 	- directory with info on tracing technologies within linux
 unaligned-memory-access.txt
 	- info on how to avoid arch breaking unaligned memory access in code.
-admin-guide/unicode.rst
-	- info on the Unicode character/font mapping used in Linux.
 unshare.txt
 	- description of the Linux unshare system call.
 usb/
@@ -464,8 +413,6 @@ vm/
 	- directory with info on the Linux vm code.
 vme_api.txt
 	- file relating info on the VME bus API in linux
-process/volatile-considered-harmful.rst
-	- Why the "volatile" type class should not be used
 w1/
 	- directory with documents regarding the 1-wire (w1) subsystem.
 watchdog/
-- 
cgit v1.2.3


From 822d289f2872317d2536028d063d1e1b9d9fd76f Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 5 Dec 2016 09:41:43 -0200
Subject: docs: 00-INDEX: add missing entries for documentation files/dirs

Several directories and individual files don't have entries at
00-INDEX. Add them, using, as reference, the initial text inside
the documentation file(s).

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/00-INDEX | 64 ++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 60 insertions(+), 4 deletions(-)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 02583a1f409c..bd532a7e03e6 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -39,6 +39,8 @@ Intel-IOMMU.txt
 Makefile
 	- This file does nothing. Removing it breaks make htmldocs and
 	  make distclean.
+PCI/
+	- info related to PCI drivers.
 RCU/
 	- directory with info on RCU (read-copy update).
 SAK.txt
@@ -93,12 +95,16 @@ cachetlb.txt
 	- describes the cache/TLB flushing interfaces Linux uses.
 cdrom/
 	- directory with information on the CD-ROM drivers that Linux has.
-cgroups/
-	- cgroups features, including cpusets and memory controller.
+cgroup-v1/
+	- cgroups v1 features, including cpusets and memory controller.
+cgroup-v2.txt
+	- cgroups v2 features, including cpusets and memory controller.
 circular-buffers.txt
 	- how to make use of the existing circular buffer infrastructure
 clk.txt
 	- info on the common clock framework
+cma/
+	- Continuous Memory Area (CMA) debugfs interface.
 coccinelle.txt
 	- info on how to get and use the Coccinelle code checking tool.
 connector/
@@ -131,8 +137,12 @@ debugging-via-ohci1394.txt
 	- how to use firewire like a hardware debugger memory reader.
 dell_rbu.txt
 	- document demonstrating the use of the Dell Remote BIOS Update driver.
+dev-tools/
+	- directory with info on development tools for the kernel.
 device-mapper/
 	- directory with info on Device Mapper.
+dmaengine/
+	- the DMA engine and controller API guides.
 devicetree/
 	- directory with info on device tree files used by OF/PowerPC/ARM
 digsig.txt
@@ -141,6 +151,8 @@ dma-buf-sharing.txt
 	- the DMA Buffer Sharing API Guide
 dontdiff
 	- file containing a list of files that should never be diff'ed.
+driver-api/
+	- the Linux driver implementer's API guide.
 driver-model/
 	- directory with info about Linux driver model.
 dynamic-debug-howto.txt
@@ -155,10 +167,14 @@ eisa.txt
 	- info on EISA bus support.
 extcon/
 	- directory with porting guide for Android kernel switch driver.
+isa.txt
+	- info on EISA bus support.
 fault-injection/
 	- dir with docs about the fault injection capabilities infrastructure.
 fb/
 	- directory with info on the frame buffer graphics abstraction layer.
+features/
+	- status of feature implementation on different architectures.
 filesystems/
 	- info on the vfs and the various filesystems that Linux supports.
 firmware_class/
@@ -167,14 +183,20 @@ flexible-arrays.txt
 	- how to make use of flexible sized arrays in linux
 fmc/
 	- information about the FMC bus abstraction
+fpga/
+	- FPGA Manager Core.
 frv/
 	- Fujitsu FR-V Linux documentation.
 futex-requeue-pi.txt
 	- info on requeueing of tasks from a non-PI futex to a PI futex
+gcc-plugins.txt
+	- GCC plugin infrastructure.
 gcov.txt
 	- use of GCC's coverage testing tool "gcov" with the Linux kernel
 gpio/
 	- gpio related documentation
+gpu/
+	- directory with information on GPU driver developer's guide.
 hid/
 	- directory with information on human interface devices
 highuid.txt
@@ -197,6 +219,10 @@ x86/i386/
 	- directory with info about Linux on Intel 32 bit architecture.
 ia64/
 	- directory with info about Linux on Intel 64 bit architecture.
+ide/
+	- Information regarding the Enhanced IDE drive.
+iio/
+	- info on industrial IIO configfs support.
 infiniband/
 	- directory with documents concerning Linux InfiniBand support.
 input/
@@ -221,6 +247,8 @@ ja_JP/
 	- directory with Japanese translations of various documents
 kbuild/
 	- directory with info about the kernel build process.
+kernel-doc-nano-HOWTO.txt
+	- outdated info about kernel-doc documentation.
 kdump/
 	- directory with mini HowTo on getting the crash dump code to work.
 doc-guide/
@@ -247,6 +275,8 @@ ldm.txt
 	- a brief description of LDM (Windows Dynamic Disks).
 leds/
 	- directory with info about LED handling under Linux.
+livepatch/
+	- info on kernel live patching.
 local_ops.txt
 	- semantics and behavior of local atomic operations.
 locking/
@@ -265,16 +295,22 @@ magic-number.txt
 	- list of magic numbers used to mark/protect kernel data structures.
 mailbox.txt
 	- How to write drivers for the common mailbox framework (IPC).
-media-framework.txt
-	- info on media framework, its data structures, functions and usage.
+md-cluster.txt
+	- info on shared-device RAID MD cluster.
+media/
+	- info on media drivers: uAPI, kAPI and driver documentation.
 memory-barriers.txt
 	- info on Linux kernel memory barriers.
 memory-devices/
 	- directory with info on parts like the Texas Instruments EMIF driver
 memory-hotplug.txt
 	- Hotpluggable memory support, how to use and current status.
+men-chameleon-bus.txt
+	- info on MEN chameleon bus.
 metag/
 	- directory with info about Linux on Meta architecture.
+mic/
+	- Intel Many Integrated Core (MIC) architecture device driver.
 mips/
 	- directory with info about Linux on MIPS architecture.
 misc-devices/
@@ -295,10 +331,18 @@ networking/
 	- directory with info on various aspects of networking with Linux.
 nfc/
 	- directory relating info about Near Field Communications support.
+nios2/
+	- Linux on the Nios II architecture.
 nommu-mmap.txt
 	- documentation about no-mmu memory mapping support.
 numastat.txt
 	- info on how to read Numa policy hit/miss statistics in sysfs.
+ntb.txt
+	- info on Non-Transparent Bridge (NTB) drivers.
+nvdimm/
+	- info on non-volatile devices.
+nvmem/
+	- info on non volatile memory framework.
 padata.txt
 	- An introduction to the "padata" parallel execution API
 parisc/
@@ -311,12 +355,18 @@ pcmcia/
 	- info on the Linux PCMCIA driver.
 percpu-rw-semaphore.txt
 	- RCU based read-write semaphore optimized for locking for reading
+perf/
+	- info about the APM X-Gene SoC Performance Monitoring Unit (PMU).
+phy/
+	- ino on Samsung USB 2.0 PHY adaptation layer.
 phy.txt
 	- Description of the generic PHY framework.
 pi-futex.txt
 	- documentation on lightweight priority inheritance futexes.
 pinctrl.txt
 	- info on pinctrl subsystem and the PINMUX/PINCONF and drivers
+platform/
+	- List of supported hardware by compal and Dell laptop.
 pnp.txt
 	- Linux Plug and Play documentation.
 power/
@@ -333,6 +383,8 @@ process/
 	- how to work with the mainline kernel development process.
 pps/
 	- directory with information on the pulse-per-second support
+pti/
+	- directory with info on Intel MID PTI.
 ptp/
 	- directory with info on support for IEEE 1588 PTP clocks in Linux.
 pwm.txt
@@ -379,6 +431,8 @@ static-keys.txt
 	- info on how static keys allow debug code in hotpaths via patching
 svga.txt
 	- short guide on selecting video modes at boot via VGA BIOS.
+sync_file.txt
+	- Sync file API guide.
 sysfs-rules.txt
 	- How not to use sysfs.
 sysctl/
@@ -393,6 +447,8 @@ thermal/
 	- directory with information on managing thermal issues (CPU/temp)
 trace/
 	- directory with info on tracing technologies within linux
+translations/
+	- translations of this document from English to another language
 unaligned-memory-access.txt
 	- info on how to avoid arch breaking unaligned memory access in code.
 unshare.txt
-- 
cgit v1.2.3


From a240bfedee7fe2bad1a5ac5d104c513e7fe09d30 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 5 Dec 2016 09:41:44 -0200
Subject: docs: 00-INDEX: remove non-existing entries

Several entries were moved to a directory; others got simply
removed. Get rid of those entries.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/00-INDEX | 52 --------------------------------------------------
 1 file changed, 52 deletions(-)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index bd532a7e03e6..272f5c4481f1 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -47,8 +47,6 @@ SAK.txt
 	- info on Secure Attention Keys.
 SM501.txt
 	- Silicon Motion SM501 multimedia companion chip
-VGA-softcursor.txt
-	- how to change your VGA cursor from a blinking underscore.
 accounting/
 	- documentation on accounting and taskstats.
 acpi/
@@ -61,28 +59,18 @@ arm/
 	- directory with info about Linux on the ARM architecture.
 arm64/
 	- directory with info about Linux on the 64 bit ARM architecture.
-assoc_array.txt
-	- generic associative array intro.
-atomic_ops.txt
-	- semantics and behavior of atomic and bitmask operations.
 auxdisplay/
 	- misc. LCD driver documentation (cfag12864b, ks0108).
 backlight/
 	- directory with info on controlling backlights in flat panel displays
-basic_profiling.txt
-	- basic instructions for those who wants to profile Linux kernel.
 bcache.txt
 	- Block-layer cache on fast SSDs to improve slow (raid) I/O performance.
-binfmt_misc.txt
-	- info on the kernel support for extra binary formats.
 blackfin/
 	- directory with documentation for the Blackfin arch.
 block/
 	- info on the Block I/O (BIO) layer.
 blockdev/
 	- info on block devices & drivers
-braille-console.txt
-	- info on how to use serial devices for Braille support.
 bt8xxgpio.txt
 	- info on how to modify a bt8xx video card for GPIO usage.
 btmrvl.txt
@@ -105,8 +93,6 @@ clk.txt
 	- info on the common clock framework
 cma/
 	- Continuous Memory Area (CMA) debugfs interface.
-coccinelle.txt
-	- info on how to get and use the Coccinelle code checking tool.
 connector/
 	- docs on the netlink based userspace<->kernel space communication mod.
 console/
@@ -155,8 +141,6 @@ driver-api/
 	- the Linux driver implementer's API guide.
 driver-model/
 	- directory with info about Linux driver model.
-dynamic-debug-howto.txt
-	- how to use the dynamic debug (dyndbg) feature.
 early-userspace/
 	- info about initramfs, klibc, and userspace early during boot.
 edac.txt
@@ -191,8 +175,6 @@ futex-requeue-pi.txt
 	- info on requeueing of tasks from a non-PI futex to a PI futex
 gcc-plugins.txt
 	- GCC plugin infrastructure.
-gcov.txt
-	- use of GCC's coverage testing tool "gcov" with the Linux kernel
 gpio/
 	- gpio related documentation
 gpu/
@@ -201,8 +183,6 @@ hid/
 	- directory with information on human interface devices
 highuid.txt
 	- notes on the change from 16 bit to 32 bit user/group IDs.
-hsi.txt
-	- HSI subsystem overview.
 hwspinlock.txt
 	- hardware spinlock provides hardware assistance for synchronization
 timers/
@@ -213,8 +193,6 @@ hwmon/
 	- directory with docs on various hardware monitoring drivers.
 i2c/
 	- directory with info about the I2C bus/protocol (2 wire, kHz speed).
-i2o/
-	- directory with info about the Linux I2O subsystem.
 x86/i386/
 	- directory with info about Linux on Intel 32 bit architecture.
 ia64/
@@ -243,8 +221,6 @@ isapnp.txt
 	- info on Linux ISA Plug & Play support.
 isdn/
 	- directory with info on the Linux ISDN support, and supported cards.
-ja_JP/
-	- directory with Japanese translations of various documents
 kbuild/
 	- directory with info about the kernel build process.
 kernel-doc-nano-HOWTO.txt
@@ -255,12 +231,6 @@ doc-guide/
 	- how to write and format reStructuredText kernel documentation
 kernel-per-CPU-kthreads.txt
 	- List of all per-CPU kthreads and how they introduce jitter.
-kmemcheck.txt
-	- info on dynamic checker that detects uses of uninitialized memory.
-kmemleak.txt
-	- info on how to make use of the kernel memory leak detection system
-ko_KR/
-	- directory with Korean translations of various documents
 kobject.txt
 	- info of the kobject infrastructure of the Linux kernel.
 kprobes.txt
@@ -277,8 +247,6 @@ leds/
 	- directory with info about LED handling under Linux.
 livepatch/
 	- info on kernel live patching.
-local_ops.txt
-	- semantics and behavior of local atomic operations.
 locking/
 	- directory with info about kernel locking primitives
 lockup-watchdogs.txt
@@ -291,8 +259,6 @@ lzo.txt
 	- kernel LZO decompressor input formats
 m68k/
 	- directory with info about Linux on Motorola 68k architecture.
-magic-number.txt
-	- list of magic numbers used to mark/protect kernel data structures.
 mailbox.txt
 	- How to write drivers for the common mailbox framework (IPC).
 md-cluster.txt
@@ -319,8 +285,6 @@ mmc/
 	- directory with info about the MMC subsystem
 mn10300/
 	- directory with info about the mn10300 architecture port
-module-signing.txt
-	- Kernel module signing for increased security when loading modules.
 mtd/
 	- directory with info about memory technology devices (flash)
 namespaces/
@@ -347,8 +311,6 @@ padata.txt
 	- An introduction to the "padata" parallel execution API
 parisc/
 	- directory with info on using Linux on PA-RISC architecture.
-parport.txt
-	- how to use the parallel-port driver.
 parport-lowlevel.txt
 	- description and usage of the low level parallel port functions.
 pcmcia/
@@ -423,8 +385,6 @@ smsc_ece1099.txt
 	-info on the smsc Keyboard Scan Expansion/GPIO Expansion device.
 sound/
 	- directory with info on sound card support.
-sparse.txt
-	- info on how to obtain and use the sparse tool for typechecking.
 spi/
 	- overview of Linux kernel Serial Peripheral Interface (SPI) support.
 static-keys.txt
@@ -433,12 +393,8 @@ svga.txt
 	- short guide on selecting video modes at boot via VGA BIOS.
 sync_file.txt
 	- Sync file API guide.
-sysfs-rules.txt
-	- How not to use sysfs.
 sysctl/
 	- directory with info on the /proc/sys/* files.
-sysrq.txt
-	- info on the magic SysRq key.
 target/
 	- directory with info on generating TCM v4 fabric .ko modules
 this_cpu_ops.txt
@@ -455,20 +411,14 @@ unshare.txt
 	- description of the Linux unshare system call.
 usb/
 	- directory with info regarding the Universal Serial Bus.
-vDSO/
-	- directory with info regarding virtual dynamic shared objects
 vfio.txt
 	- info on Virtual Function I/O used in guest/hypervisor instances.
-vgaarbiter.txt
-	- info on enable/disable the legacy decoding on different VGA devices
 video-output.txt
 	- sysfs class driver interface to enable/disable a video output device.
 virtual/
 	- directory with information on the various linux virtualizations.
 vm/
 	- directory with info on the Linux vm code.
-vme_api.txt
-	- file relating info on the VME bus API in linux
 w1/
 	- directory with documents regarding the 1-wire (w1) subsystem.
 watchdog/
@@ -485,7 +435,5 @@ xtensa/
 	- directory with documents relating to arch/xtensa port/implementation
 xz.txt
 	- how to make use of the XZ data compression within linux kernel
-zh_CN/
-	- directory with Chinese translations of various documents
 zorro.txt
 	- info on writing drivers for Zorro bus devices found on Amigas.
-- 
cgit v1.2.3


From 0f60724f53c2230615c7a3b2abf30a0bc7e8a8de Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 5 Dec 2016 09:41:45 -0200
Subject: docs: 00-INDEX: document directories/files with no docs

There are a number of files/directories that don't contain
any documentation. They're related to ReST file conversion.

As a matter of completeness, since Makefile is also documented
there, add an entry for those files too.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/00-INDEX | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 272f5c4481f1..6d488509285d 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -14,6 +14,8 @@ Following translations are available on the WWW:
 	- this file.
 ABI/
 	- info on kernel <-> userspace ABI and relative interface stability.
+CodingStyle
+	- nothing here, just a pointer to process/coding-style.rst.
 DMA-API.txt
 	- DMA API, pci_ API & extensions for non-consistent memory machines.
 DMA-API-HOWTO.txt
@@ -39,6 +41,9 @@ Intel-IOMMU.txt
 Makefile
 	- This file does nothing. Removing it breaks make htmldocs and
 	  make distclean.
+Makefile.sphinx
+	- This file does nothing. Removing it breaks make htmldocs and
+	  make distclean.
 PCI/
 	- info related to PCI drivers.
 RCU/
@@ -47,6 +52,8 @@ SAK.txt
 	- info on Secure Attention Keys.
 SM501.txt
 	- Silicon Motion SM501 multimedia companion chip
+SubmittingPatches
+	- nothing here, just a pointer to process/coding-style.rst.
 accounting/
 	- documentation on accounting and taskstats.
 acpi/
@@ -93,6 +100,8 @@ clk.txt
 	- info on the common clock framework
 cma/
 	- Continuous Memory Area (CMA) debugfs interface.
+conf.py
+	- nothing here. Just a configuration file for Sphinx.
 connector/
 	- docs on the netlink based userspace<->kernel space communication mod.
 console/
@@ -135,6 +144,8 @@ digsig.txt
 	-info on the Digital Signature Verification API
 dma-buf-sharing.txt
 	- the DMA Buffer Sharing API Guide
+docutils.conf
+	- nothing here. Just a configuration file for docutils.
 dontdiff
 	- file containing a list of files that should never be diff'ed.
 driver-api/
@@ -201,6 +212,8 @@ ide/
 	- Information regarding the Enhanced IDE drive.
 iio/
 	- info on industrial IIO configfs support.
+index.rst
+	- main index for the documentation at ReST format.
 infiniband/
 	- directory with documents concerning Linux InfiniBand support.
 input/
@@ -307,6 +320,8 @@ nvdimm/
 	- info on non-volatile devices.
 nvmem/
 	- info on non volatile memory framework.
+output/
+	- default directory where html/LaTeX/pdf files will be written.
 padata.txt
 	- An introduction to the "padata" parallel execution API
 parisc/
@@ -387,6 +402,10 @@ sound/
 	- directory with info on sound card support.
 spi/
 	- overview of Linux kernel Serial Peripheral Interface (SPI) support.
+sphinx/
+	- no doumentation here, just files required by Sphinx toolchain.
+sphinx-static/
+	- no doumentation here, just files required by Sphinx toolchain.
 static-keys.txt
 	- info on how static keys allow debug code in hotpaths via patching
 svga.txt
-- 
cgit v1.2.3


From 9e22ff439fa2e1201b168c001683f275afd46258 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Tue, 6 Dec 2016 10:51:51 -0200
Subject: Update Documentation/00-INDEX

Em Mon, 5 Dec 2016 14:23:01 -0700
Jonathan Corbet  escreveu:

> On Mon,  5 Dec 2016 09:41:40 -0200
> Mauro Carvalho Chehab  wrote:
>
> > So, in order to check it, I wrote a small script that compares the files
> > and directories at Documentation/ with the ones at 00-INDEX.
> >
> > Then, I synchronized the entries, making the script happy.
> >
> > We might think on integrating the script with checkpatch.pl, but, as
> > we should get rid of 00-INDEX, it probably not worth the efforts.
>
> I would agree with that; I don't see the point of keeping those files
> around in the longer term.
>
> I've applied the set.  I do have a few quibbles with the final patch that
> I'll send separately, but they're not something to hold this set up for.

Jon,

Did a patch fixing the quibbles.

As it seems you didn't push yet the changeset upstream, feel free to
just fold it with patch 5/5 if you prefer so, or to add as a separate
patch at the end of the series.

Patch enclosed.

Thanks,
Mauro

[PATCH] docs: 00-INDEX: change text related to the building system

Let be clearer on those files related to the build system.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
---
 Documentation/00-INDEX | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index 6d488509285d..5bd4b07c2f90 100644
--- a/Documentation/00-INDEX
+++ b/Documentation/00-INDEX
@@ -39,11 +39,9 @@ IRQ.txt
 Intel-IOMMU.txt
 	- basic info on the Intel IOMMU virtualization support.
 Makefile
-	- This file does nothing. Removing it breaks make htmldocs and
-	  make distclean.
+	- It's not of interest for those who aren't touching the build system.
 Makefile.sphinx
-	- This file does nothing. Removing it breaks make htmldocs and
-	  make distclean.
+	- It's not of interest for those who aren't touching the build system.
 PCI/
 	- info related to PCI drivers.
 RCU/
@@ -101,7 +99,7 @@ clk.txt
 cma/
 	- Continuous Memory Area (CMA) debugfs interface.
 conf.py
-	- nothing here. Just a configuration file for Sphinx.
+	- It's not of interest for those who aren't touching the build system.
 connector/
 	- docs on the netlink based userspace<->kernel space communication mod.
 console/
@@ -403,9 +401,9 @@ sound/
 spi/
 	- overview of Linux kernel Serial Peripheral Interface (SPI) support.
 sphinx/
-	- no doumentation here, just files required by Sphinx toolchain.
+	- no documentation here, just files required by Sphinx toolchain.
 sphinx-static/
-	- no doumentation here, just files required by Sphinx toolchain.
+	- no documentation here, just files required by Sphinx toolchain.
 static-keys.txt
 	- info on how static keys allow debug code in hotpaths via patching
 svga.txt
-- 
cgit v1.2.3


From 868c97a846a73e937d835b09b8c885a69df50ec8 Mon Sep 17 00:00:00 2001
From: Daniel Vetter 
Date: Fri, 9 Dec 2016 19:53:05 +0100
Subject: dma-buf: Extract dma-buf.rst

Just prep work to polish and consolidate all the dma-buf related
documenation.

Unfortunately I didn't discover a way to both integrate this new file
into the overall toc while keeping it at the current place. Work
around that by moving it into the overall driver-api/index.rst.

Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet 
Cc: Sumit Semwal 
Signed-off-by: Daniel Vetter 
Signed-off-by: Jonathan Corbet 
---
 Documentation/driver-api/dma-buf.rst        | 73 +++++++++++++++++++++++++++++
 Documentation/driver-api/index.rst          |  1 +
 Documentation/driver-api/infrastructure.rst | 70 ---------------------------
 3 files changed, 74 insertions(+), 70 deletions(-)
 create mode 100644 Documentation/driver-api/dma-buf.rst

diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst
new file mode 100644
index 000000000000..a9b457a4b949
--- /dev/null
+++ b/Documentation/driver-api/dma-buf.rst
@@ -0,0 +1,73 @@
+Buffer Sharing and Synchronization
+==================================
+
+The dma-buf subsystem provides the framework for sharing buffers for
+hardware (DMA) access across multiple device drivers and subsystems, and
+for synchronizing asynchronous hardware access.
+
+This is used, for example, by drm "prime" multi-GPU support, but is of
+course not limited to GPU use cases.
+
+The three main components of this are: (1) dma-buf, representing a
+sg_table and exposed to userspace as a file descriptor to allow passing
+between devices, (2) fence, which provides a mechanism to signal when
+one device as finished access, and (3) reservation, which manages the
+shared or exclusive fence(s) associated with the buffer.
+
+Shared DMA Buffers
+------------------
+
+.. kernel-doc:: drivers/dma-buf/dma-buf.c
+   :export:
+
+.. kernel-doc:: include/linux/dma-buf.h
+   :internal:
+
+Reservation Objects
+-------------------
+
+.. kernel-doc:: drivers/dma-buf/reservation.c
+   :doc: Reservation Object Overview
+
+.. kernel-doc:: drivers/dma-buf/reservation.c
+   :export:
+
+.. kernel-doc:: include/linux/reservation.h
+   :internal:
+
+DMA Fences
+----------
+
+.. kernel-doc:: drivers/dma-buf/dma-fence.c
+   :export:
+
+.. kernel-doc:: include/linux/dma-fence.h
+   :internal:
+
+Seqno Hardware Fences
+~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: drivers/dma-buf/seqno-fence.c
+   :export:
+
+.. kernel-doc:: include/linux/seqno-fence.h
+   :internal:
+
+DMA Fence Array
+~~~~~~~~~~~~~~~
+
+.. kernel-doc:: drivers/dma-buf/dma-fence-array.c
+   :export:
+
+.. kernel-doc:: include/linux/dma-fence-array.h
+   :internal:
+
+DMA Fence uABI/Sync File
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. kernel-doc:: drivers/dma-buf/sync_file.c
+   :export:
+
+.. kernel-doc:: include/linux/sync_file.h
+   :internal:
+
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 0823a6a52f43..a528178a54a5 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -16,6 +16,7 @@ available subsections can be seen below.
 
    basics
    infrastructure
+   dma-buf
    device_link
    message-based
    sound
diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst
index a0d65eb49055..0bb0b5fc9512 100644
--- a/Documentation/driver-api/infrastructure.rst
+++ b/Documentation/driver-api/infrastructure.rst
@@ -46,76 +46,6 @@ Device Drivers Base
 .. kernel-doc:: drivers/base/bus.c
    :export:
 
-Buffer Sharing and Synchronization
-----------------------------------
-
-The dma-buf subsystem provides the framework for sharing buffers for
-hardware (DMA) access across multiple device drivers and subsystems, and
-for synchronizing asynchronous hardware access.
-
-This is used, for example, by drm "prime" multi-GPU support, but is of
-course not limited to GPU use cases.
-
-The three main components of this are: (1) dma-buf, representing a
-sg_table and exposed to userspace as a file descriptor to allow passing
-between devices, (2) fence, which provides a mechanism to signal when
-one device as finished access, and (3) reservation, which manages the
-shared or exclusive fence(s) associated with the buffer.
-
-dma-buf
-~~~~~~~
-
-.. kernel-doc:: drivers/dma-buf/dma-buf.c
-   :export:
-
-.. kernel-doc:: include/linux/dma-buf.h
-   :internal:
-
-reservation
-~~~~~~~~~~~
-
-.. kernel-doc:: drivers/dma-buf/reservation.c
-   :doc: Reservation Object Overview
-
-.. kernel-doc:: drivers/dma-buf/reservation.c
-   :export:
-
-.. kernel-doc:: include/linux/reservation.h
-   :internal:
-
-fence
-~~~~~
-
-.. kernel-doc:: drivers/dma-buf/dma-fence.c
-   :export:
-
-.. kernel-doc:: include/linux/dma-fence.h
-   :internal:
-
-.. kernel-doc:: drivers/dma-buf/seqno-fence.c
-   :export:
-
-.. kernel-doc:: include/linux/seqno-fence.h
-   :internal:
-
-.. kernel-doc:: drivers/dma-buf/dma-fence-array.c
-   :export:
-
-.. kernel-doc:: include/linux/dma-fence-array.h
-   :internal:
-
-.. kernel-doc:: drivers/dma-buf/reservation.c
-   :export:
-
-.. kernel-doc:: include/linux/reservation.h
-   :internal:
-
-.. kernel-doc:: drivers/dma-buf/sync_file.c
-   :export:
-
-.. kernel-doc:: include/linux/sync_file.h
-   :internal:
-
 Device Drivers DMA Management
 -----------------------------
 
-- 
cgit v1.2.3