From 58af04dff742b6b49fae3de585bdea8c77b62ddc Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 19 Oct 2016 13:44:37 +0300 Subject: [PATCH 001/193] 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 => kerneldoc.py} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename Documentation/sphinx/{kernel-doc.py => kerneldoc.py} (100%) diff --git a/Documentation/conf.py b/Documentation/conf.py index bf6f310e51705..4db1993658eab 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/kerneldoc.py similarity index 100% rename from Documentation/sphinx/kernel-doc.py rename to Documentation/sphinx/kerneldoc.py -- GitLab From 7058763b3f1ca6086d2be8f23a6c2a7c645077f2 Mon Sep 17 00:00:00 2001 From: Marcin Nowakowski Date: Thu, 6 Oct 2016 09:52:12 +0200 Subject: [PATCH 002/193] 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 94b6b45817635..fa7b680ee8a00 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: -- GitLab From 5ac9baf47a571d74c995529b2f7ded8348389e10 Mon Sep 17 00:00:00 2001 From: Masanari Iida Date: Mon, 17 Oct 2016 21:17:10 +0900 Subject: [PATCH 003/193] 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 e5b6497116f41..89ecc8021178f 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. -- GitLab From a164a8a6635469b653fa132a3ec283df6bc147f4 Mon Sep 17 00:00:00 2001 From: Stephen Hemminger Date: Mon, 17 Oct 2016 12:33:19 -0700 Subject: [PATCH 004/193] 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 cd0e452dfed56..5210f8a577c64 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 -- GitLab From 5d812b47a668f539f763a9e95167fd2bdf488a7a Mon Sep 17 00:00:00 2001 From: Masanari Iida Date: Fri, 21 Oct 2016 04:59:32 +0900 Subject: [PATCH 005/193] 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 b79d0a13e7cdd..3a5477cc456ef 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: -- GitLab From 75a163c4a3ee8235072f0e1bd4875dd2443cdb8e Mon Sep 17 00:00:00 2001 From: Martyn Welch Date: Fri, 21 Oct 2016 22:15:27 +0100 Subject: [PATCH 006/193] 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 + .../{vme_api.txt => driver-api/vme.rst} | 115 ++++++++++++++---- MAINTAINERS | 2 +- 3 files changed, 90 insertions(+), 28 deletions(-) rename Documentation/{vme_api.txt => driver-api/vme.rst} (92%) diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 8e259c5d03226..b567907db3509 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/vme_api.txt b/Documentation/driver-api/vme.rst similarity index 92% rename from Documentation/vme_api.txt rename to Documentation/driver-api/vme.rst index 90006550f4858..89776fb3c8bd0 100644 --- a/Documentation/vme_api.txt +++ b/Documentation/driver-api/vme.rst @@ -1,13 +1,15 @@ - VME Device Driver API - ===================== +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 @@ -17,6 +19,8 @@ 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; @@ -38,6 +42,8 @@ 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) @@ -51,6 +57,8 @@ 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; @@ -66,11 +74,13 @@ 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 @@ -86,6 +96,8 @@ 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); @@ -112,6 +124,8 @@ 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); @@ -120,7 +134,7 @@ during resource allocation: 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 @@ -128,11 +142,13 @@ 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); @@ -149,11 +165,13 @@ 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); @@ -164,6 +182,8 @@ 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); @@ -175,12 +195,14 @@ 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 @@ -189,11 +211,13 @@ 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); @@ -210,13 +234,15 @@ 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); @@ -225,14 +251,14 @@ taken to ensure that they are contiguous and accessible by the VME bridge: 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 @@ -241,29 +267,35 @@ 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 +.. 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 @@ -271,7 +303,7 @@ NOTE: The detailed attributes of the transfers source and destination 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 @@ -280,33 +312,43 @@ 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 @@ -314,13 +356,15 @@ 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); @@ -329,31 +373,37 @@ passed to the callback function, the use of this pointer is user undefined: 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); @@ -362,15 +412,19 @@ 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); @@ -379,12 +433,14 @@ are provided to configure the location and mode of the location monitor: 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 *)); @@ -392,22 +448,27 @@ adjacent locations: 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. - int vme_bus_num(struct vme_dev *dev); +.. code-block:: c + int vme_bus_num(struct vme_dev *dev); diff --git a/MAINTAINERS b/MAINTAINERS index 1cd38a7e0064e..de0451df542ff 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* -- GitLab From 3a61baddcec3e7873b49deb5804d3d6f39b92def Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 10:04:16 -0300 Subject: [PATCH 007/193] 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 02ce4924468e3..3395da13d415b 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. -- GitLab From 12983bcd822f5c13a0f350cc97bc9fb781cae944 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 13:14:35 -0300 Subject: [PATCH 008/193] 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 --- ...adding-syscalls.txt => adding-syscals.txt} | 269 +++++++++--------- 1 file changed, 142 insertions(+), 127 deletions(-) rename Documentation/{adding-syscalls.txt => adding-syscals.txt} (65%) diff --git a/Documentation/adding-syscalls.txt b/Documentation/adding-syscals.txt similarity index 65% rename from Documentation/adding-syscalls.txt rename to Documentation/adding-syscals.txt index bbb31e091b282..f5b5b1aa51b34 100644 --- a/Documentation/adding-syscalls.txt +++ b/Documentation/adding-syscals.txt @@ -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 -Documentation/SubmittingPatches. +:ref:`Documentation/SubmittingPatches `. System Call Alternatives @@ -19,30 +19,33 @@ interface. 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. + ``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 + (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 + 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 fcntl(2) functionality, or the new functionality is very simple + 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 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. + 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 @@ -54,15 +57,16 @@ 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 +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: +flags, and reject the system call (with ``EINVAL``) if it does:: if (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3)) return -EINVAL; @@ -72,7 +76,7 @@ flags, and reject the system call (with EINVAL) if it does: 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: +by including a size argument in the structure:: struct xyzzy_params { u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */ @@ -81,19 +85,19 @@ by including a size argument in the structure: u64 param_3; }; -As long as any subsequently added field, say param_4, is designed so that a +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). + 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). + 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. +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 @@ -104,57 +108,60 @@ 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 +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.) +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 +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 xyzzy(2) system call involves a filename argument: +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 xyzzyat(2) version is more appropriate: +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 fxyzzy(3) operation for free: +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 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. +(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 @@ -175,7 +182,7 @@ distinct commits (each of which is described further below): - 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/. + 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. @@ -186,24 +193,24 @@ 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 +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: +``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: +``include/uapi/asm-generic/unistd.h``:: #define __NR_xyzzy 292 __SYSCALL(__NR_xyzzy, sys_xyzzy) @@ -212,30 +219,30 @@ 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: +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: +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"). + 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 + - ``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 @@ -244,11 +251,11 @@ 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: +arch/x86/entry/syscalls/syscall_64.tbl:: 333 common xyzzy sys_xyzzy -and an "i386" entry in arch/x86/entry/syscalls/syscall_32.tbl: +and an "i386" entry in ``arch/x86/entry/syscalls/syscall_32.tbl``:: 380 i386 xyzzy sys_xyzzy @@ -267,48 +274,49 @@ 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 +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 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. +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.) +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 +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 +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: +``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. +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: +For example, if there are fields:: struct xyzzy_args { const char __user *ptr; @@ -317,7 +325,7 @@ For example, if there are fields: /* ... */ }; -in struct xyzzy_args, then struct compat_xyzzy_args would have: +in struct xyzzy_args, then struct compat_xyzzy_args would have:: struct compat_xyzzy_args { compat_uptr_t ptr; @@ -327,18 +335,19 @@ in struct xyzzy_args, then struct compat_xyzzy_args would have: }; 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: +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 + - 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) @@ -347,9 +356,9 @@ 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 +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: +should hit the compat entry point:: 380 i386 xyzzy sys_xyzzy compat_sys_xyzzy @@ -359,8 +368,8 @@ 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: +``arch/x86/entry/syscalls/syscall_64.tbl`` is split so that x32 programs hit +the compatibility wrapper:: 333 64 xyzzy sys_xyzzy ... @@ -384,8 +393,9 @@ 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. +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 @@ -395,31 +405,31 @@ 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: +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, +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: +``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 +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_ +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 +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: +``arch/x86/um/sys_call_table_64.c``:: #define stub_xyzzy sys_xyzzy @@ -432,9 +442,9 @@ 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. +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 @@ -447,10 +457,10 @@ 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/. +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 +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. @@ -461,6 +471,7 @@ 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 @@ -487,12 +498,14 @@ References and Sources 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: + :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(): + - 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 @@ -507,17 +520,19 @@ References and Sources 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: + - 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 -- GitLab From 684adc0aa3d482228d0727ee9a9a7b8deec62ca5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 09:48:55 -0300 Subject: [PATCH 009/193] 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 37babf91f2cb6..b0804273b6e39 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. -- GitLab From d078a815196bc4b3d8fe728a0dbd83c07b928a47 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 13:24:12 -0300 Subject: [PATCH 010/193] 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 df84162132028..5cac93e27a978 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 -- GitLab From 3bdb5971ffc6e87362787c770353eb3e54b7af30 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 13:38:38 -0300 Subject: [PATCH 011/193] 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 8764e9f70821e..15a49dbd0189c 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. -- GitLab From 5902981bce634dc218f0f8884649efebca7b8bcc Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 13:56:19 -0300 Subject: [PATCH 012/193] 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 ec83bbce547a5..9c5ff8f260bfb 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. -- GitLab From c2ffd5dafa9dfbc48d5198c6d355617a756d2690 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 14:08:10 -0300 Subject: [PATCH 013/193] 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 9a7bc8b3f479b..1d9a3e48e929b 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 -- GitLab From 8e7fbec662554b25ac832116cfe2d47db635d33c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 14:44:59 -0300 Subject: [PATCH 014/193] 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 d0d042c2fd5e9..fa3702dc04ab9 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 1d9a3e48e929b..a8d1e36b627a1 100644 --- a/Documentation/serial-console.txt +++ b/Documentation/serial-console.txt @@ -1,3 +1,5 @@ +.. _serial_console: + Linux Serial Console ==================== -- GitLab From 953ab835a98166529e971e91d20d78c2ce2c7f7d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 15:16:45 -0300 Subject: [PATCH 015/193] 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 65022a87bf179..a8ef794aadaef 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. -- GitLab From d9f92f9f9d0e6e6ea98cd5c52cfd474cff20af22 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 15:47:58 -0300 Subject: [PATCH 016/193] 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 4035eca87144c..17b365331f235 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. -- GitLab From 7d4e3517bdc2972e0dd35be34e07832841fc036a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 16:32:00 -0300 Subject: [PATCH 017/193] 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 9417871b8758f..88adcfdf5b2b0 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" -- GitLab From 5d0ad553783f408f9c79d23e06fdfe9c4bc6c0a9 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 16:52:26 -0300 Subject: [PATCH 018/193] 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 4e1839ccb555e..a03dabaaf3a3d 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/ -- GitLab From 8887addef55f1298b967bcf67285f4a43c9db85c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 16:59:42 -0300 Subject: [PATCH 019/193] 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 535ad5e82b98c..e89d97f31eaf0 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. -- GitLab From 9a11e15381b3503e51c4bbab4f9dad7c001f7c94 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 17:18:36 -0300 Subject: [PATCH 020/193] 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 28befed9f6102..c74199f60c6c7 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``. -- GitLab From aeb04e52f1145308c013b2ec7ea660309857a1f1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 13:22:41 -0300 Subject: [PATCH 021/193] 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 d6e2fcf273375..e449fb5f277c2 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 -- GitLab From 94e980cc45f2b21afceff0cb1866a1af32d20325 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 13:44:24 -0300 Subject: [PATCH 022/193] 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 --- .../module-signing.rst} | 128 +++++++++--------- 1 file changed, 67 insertions(+), 61 deletions(-) rename Documentation/{module-signing.txt => admin-guide/module-signing.rst} (71%) diff --git a/Documentation/module-signing.txt b/Documentation/admin-guide/module-signing.rst similarity index 71% rename from Documentation/module-signing.txt rename to Documentation/admin-guide/module-signing.rst index f0e3361db20ca..27e59498b4873 100644 --- a/Documentation/module-signing.txt +++ b/Documentation/admin-guide/module-signing.rst @@ -1,22 +1,21 @@ - ============================== - 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. +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 +Overview ======== The kernel module signing facility cryptographically signs modules during @@ -36,17 +35,19 @@ SHA-512 (the algorithm is selected by data in the signature). ========================== -CONFIGURING MODULE SIGNING +Configuring module signing ========================== -The module signing facility is enabled by going to the "Enable Loadable Module -Support" section of the kernel configuration and turning on +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) "Require modules to be validly signed" (CONFIG_MODULE_SIG_FORCE) + (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. @@ -64,35 +65,39 @@ This has a number of options available: cannot be parsed, it will be rejected out of hand. - (2) "Automatically sign all modules" (CONFIG_MODULE_SIG_ALL) + (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: + be signed manually using:: scripts/sign-file - (3) "Which hash algorithm should modules be signed with?" + (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 "Sign modules with SHA-1" - CONFIG_MODULE_SIG_SHA224 "Sign modules with SHA-224" - CONFIG_MODULE_SIG_SHA256 "Sign modules with SHA-256" - CONFIG_MODULE_SIG_SHA384 "Sign modules with SHA-384" - CONFIG_MODULE_SIG_SHA512 "Sign modules with SHA-512" + =============================== ========================================== + ``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) "File name or PKCS#11 URI of module signing key" (CONFIG_MODULE_SIG_KEY) + (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 + ``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 @@ -102,10 +107,11 @@ This has a number of options available: 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. + means of the ``KBUILD_SIGN_PIN`` variable. - (5) "Additional X.509 keys for default system keyring" (CONFIG_SYSTEM_TRUSTED_KEYS) + (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 @@ -116,7 +122,7 @@ packages to the kernel build processes for the tool that does the signing. ======================= -GENERATING SIGNING KEYS +Generating signing keys ======================= Cryptographic keypairs are required to generate and check signatures. A @@ -126,14 +132,14 @@ 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 +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: +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: +into vmlinux) using parameters in the:: certs/x509.genkey @@ -142,14 +148,14 @@ 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: +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: +The generated RSA key size can also be set with:: [ req ] default_bits = 4096 @@ -158,23 +164,23 @@ The generated RSA key size can also be set with: 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: +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 +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 +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: +in a keyring called ".system_keyring" that can be seen by:: [root@deneb ~]# cat /proc/keys ... @@ -184,27 +190,27 @@ in a keyring called ".system_keyring" that can be seen by: 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. +``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: +Finally, it is possible to add additional public keys by doing:: keyctl padd asymmetric "" [.system_keyring-ID] <[key-file] -e.g.: +e.g.:: keyctl padd asymmetric "" 0x223c7853 Date: Fri, 23 Sep 2016 13:52:05 -0300 Subject: [PATCH 023/193] 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 d01ac60521943..9a9744ca0cf3d 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. -- GitLab From 503c5bf9fa4622195bef0b46ebcc0ab6afeefed8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 14:02:36 -0300 Subject: [PATCH 024/193] 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 418020584ccc1..ae33d959638c7 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 -- GitLab From 9f4b9ec63cff0048aae43b0119e64f10a7887836 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 14:40:40 -0300 Subject: [PATCH 025/193] 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 f3ac05cc23e4a..3e25ea7349eec 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 -- GitLab From e095f0711b49269e34941098b9bd60a87eb50866 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 15:07:00 -0300 Subject: [PATCH 026/193] 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 c208e4366c033..3273ce79f9e3b 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 -- GitLab From b2777b650c5073010adea8ec2bb38eaad1cf800a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 15:24:07 -0300 Subject: [PATCH 027/193] 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 26b9f31cf65ae..7eaf1e71c0833 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 -- GitLab From 3177ae4a1034482efe2c3eef5ab9988d050c5b4f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 15:44:01 -0300 Subject: [PATCH 028/193] 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 ce60ffa94d2d7..04bdd52cba1d1 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. -- GitLab From c8956bb7dd9525bba4155bf5a09022f036224b3c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 16:07:08 -0300 Subject: [PATCH 029/193] 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 3a3b30ac2a755..d1712ea2d314d 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 -- GitLab From 77514391ee1af3adaa33219109d2ca81fc09e30e Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 16:14:29 -0300 Subject: [PATCH 030/193] 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 4a33f81cadb10..012e8e895842b 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 -------------------------------------- -- GitLab From 27641b953c54643acfd28fcd9ebbe03cdc724605 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 16:26:03 -0300 Subject: [PATCH 031/193] 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 70acfbf399ebf..9eac6744b3a19 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' -- GitLab From 9c27d77d999491d6c80c570887dc95d32908cae5 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 16:33:27 -0300 Subject: [PATCH 032/193] 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 db0cb228d64aa..e0d042af386c4 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. -- GitLab From 35a1beb9c45d62d1e22e5d4274a220dfa6246cce Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Fri, 23 Sep 2016 17:22:55 -0300 Subject: [PATCH 033/193] 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 3273ce79f9e3b..ad3f9b8a11e19 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 -- GitLab From 8c287de37b2cd4ae9ef95a9e83d7e0da3d60aa1f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 11:57:16 -0200 Subject: [PATCH 034/193] 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 49a8ecc157a27..47b6de7632030 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 -- GitLab From afeb000e1a0596e89174a85c96e890f4f0e802e0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 09:27:00 -0300 Subject: [PATCH 035/193] 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 914baf9cf5fa1..05c53ac7fa76e 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 -- GitLab From 44b10006a97ec50874634ba5325a6499ead7db66 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 09:09:49 -0300 Subject: [PATCH 036/193] 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 09f34f78f2bb6..3335b3b2973a7 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. -- GitLab From 0e4f07a65f53e7b3afab71925e56fe6aaa07d696 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 09:05:32 -0200 Subject: [PATCH 037/193] 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/index.rst | 2 +- Documentation/{development-process => process}/1.Intro.rst | 0 Documentation/{development-process => process}/2.Process.rst | 0 .../{development-process => process}/3.Early-stage.rst | 0 Documentation/{development-process => process}/4.Coding.rst | 0 Documentation/{development-process => process}/5.Posting.rst | 0 .../{development-process => process}/6.Followthrough.rst | 0 .../{development-process => process}/7.AdvancedTopics.rst | 2 -- Documentation/{development-process => process}/8.Conclusion.rst | 0 Documentation/{development-process => process}/conf.py | 2 +- .../{development-process => process}/development-process.rst | 1 - Documentation/{development-process => process}/index.rst | 0 15 files changed, 5 insertions(+), 8 deletions(-) rename Documentation/{development-process => process}/1.Intro.rst (100%) rename Documentation/{development-process => process}/2.Process.rst (100%) rename Documentation/{development-process => process}/3.Early-stage.rst (100%) rename Documentation/{development-process => process}/4.Coding.rst (100%) rename Documentation/{development-process => process}/5.Posting.rst (100%) rename Documentation/{development-process => process}/6.Followthrough.rst (100%) rename Documentation/{development-process => process}/7.AdvancedTopics.rst (99%) rename Documentation/{development-process => process}/8.Conclusion.rst (100%) rename Documentation/{development-process => process}/conf.py (69%) rename Documentation/{development-process => process}/development-process.rst (99%) rename Documentation/{development-process => process}/index.rst (100%) diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 3acc4f1a6f842..d07575a8499ee 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 36f1dedc944cc..e62ddcdcaf5db 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 4db1993658eab..b08e0c9b73b7f 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/index.rst b/Documentation/index.rst index c53d089455a42..e1f18b3db6e47 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/development-process/1.Intro.rst b/Documentation/process/1.Intro.rst similarity index 100% rename from Documentation/development-process/1.Intro.rst rename to Documentation/process/1.Intro.rst diff --git a/Documentation/development-process/2.Process.rst b/Documentation/process/2.Process.rst similarity index 100% rename from Documentation/development-process/2.Process.rst rename to Documentation/process/2.Process.rst diff --git a/Documentation/development-process/3.Early-stage.rst b/Documentation/process/3.Early-stage.rst similarity index 100% rename from Documentation/development-process/3.Early-stage.rst rename to Documentation/process/3.Early-stage.rst diff --git a/Documentation/development-process/4.Coding.rst b/Documentation/process/4.Coding.rst similarity index 100% rename from Documentation/development-process/4.Coding.rst rename to Documentation/process/4.Coding.rst diff --git a/Documentation/development-process/5.Posting.rst b/Documentation/process/5.Posting.rst similarity index 100% rename from Documentation/development-process/5.Posting.rst rename to Documentation/process/5.Posting.rst diff --git a/Documentation/development-process/6.Followthrough.rst b/Documentation/process/6.Followthrough.rst similarity index 100% rename from Documentation/development-process/6.Followthrough.rst rename to Documentation/process/6.Followthrough.rst diff --git a/Documentation/development-process/7.AdvancedTopics.rst b/Documentation/process/7.AdvancedTopics.rst similarity index 99% rename from Documentation/development-process/7.AdvancedTopics.rst rename to Documentation/process/7.AdvancedTopics.rst index 81d61c5d62ddc..172733cff097f 100644 --- a/Documentation/development-process/7.AdvancedTopics.rst +++ b/Documentation/process/7.AdvancedTopics.rst @@ -176,5 +176,3 @@ 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/process/8.Conclusion.rst similarity index 100% rename from Documentation/development-process/8.Conclusion.rst rename to Documentation/process/8.Conclusion.rst diff --git a/Documentation/development-process/conf.py b/Documentation/process/conf.py similarity index 69% rename from Documentation/development-process/conf.py rename to Documentation/process/conf.py index 4b4a12dace02f..1b01a80ad9ce6 100644 --- a/Documentation/development-process/conf.py +++ b/Documentation/process/conf.py @@ -5,6 +5,6 @@ project = 'Linux Kernel Development Documentation' tags.add("subproject") latex_documents = [ - ('index', 'development-process.tex', 'Linux Kernel Development Documentation', + ('index', 'process.tex', 'Linux Kernel Development Documentation', 'The kernel development community', 'manual'), ] diff --git a/Documentation/development-process/development-process.rst b/Documentation/process/development-process.rst similarity index 99% rename from Documentation/development-process/development-process.rst rename to Documentation/process/development-process.rst index bd1399f7202a5..61c627e41ba8c 100644 --- a/Documentation/development-process/development-process.rst +++ b/Documentation/process/development-process.rst @@ -26,4 +26,3 @@ 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/process/index.rst similarity index 100% rename from Documentation/development-process/index.rst rename to Documentation/process/index.rst -- GitLab From 186128f75392f8478ad1b32a675627d738881ca4 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 08:40:21 -0300 Subject: [PATCH 038/193] 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 --- .../adding-syscalls.rst} | 0 .../applying-patches.rst} | 1 - .../{Changes => process/changes.rst} | 0 .../code-of-conflict.rst} | 0 .../{CodingStyle => process/coding-style.rst} | 0 .../email-clients.rst} | 0 Documentation/{HOWTO => process/howto.rst} | 0 Documentation/process/index.rst | 23 +++++++++++++++++++ .../kernel-docs.rst} | 0 .../magic-number.rst} | 0 .../management-style.rst} | 0 .../stable-api-nonsense.rst} | 0 .../stable-kernel-rules.rst} | 0 .../submit-checklist.rst} | 0 .../submitting-drivers.rst} | 0 .../submitting-patches.rst} | 1 - .../volatile-considered-harmful.rst} | 0 17 files changed, 23 insertions(+), 2 deletions(-) rename Documentation/{adding-syscals.txt => process/adding-syscalls.rst} (100%) rename Documentation/{applying-patches.txt => process/applying-patches.rst} (99%) rename Documentation/{Changes => process/changes.rst} (100%) rename Documentation/{CodeOfConflict => process/code-of-conflict.rst} (100%) rename Documentation/{CodingStyle => process/coding-style.rst} (100%) rename Documentation/{email-clients.txt => process/email-clients.rst} (100%) rename Documentation/{HOWTO => process/howto.rst} (100%) rename Documentation/{kernel-docs.txt => process/kernel-docs.rst} (100%) rename Documentation/{magic-number.txt => process/magic-number.rst} (100%) rename Documentation/{ManagementStyle => process/management-style.rst} (100%) rename Documentation/{stable_api_nonsense.txt => process/stable-api-nonsense.rst} (100%) rename Documentation/{stable_kernel_rules.txt => process/stable-kernel-rules.rst} (100%) rename Documentation/{SubmitChecklist => process/submit-checklist.rst} (100%) rename Documentation/{SubmittingDrivers => process/submitting-drivers.rst} (100%) rename Documentation/{SubmittingPatches => process/submitting-patches.rst} (99%) rename Documentation/{volatile-considered-harmful.txt => process/volatile-considered-harmful.rst} (100%) diff --git a/Documentation/adding-syscals.txt b/Documentation/process/adding-syscalls.rst similarity index 100% rename from Documentation/adding-syscals.txt rename to Documentation/process/adding-syscalls.rst diff --git a/Documentation/applying-patches.txt b/Documentation/process/applying-patches.rst similarity index 99% rename from Documentation/applying-patches.txt rename to Documentation/process/applying-patches.rst index 3395da13d415b..abd7dc7ae2405 100644 --- a/Documentation/applying-patches.txt +++ b/Documentation/process/applying-patches.rst @@ -462,4 +462,3 @@ 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/Changes b/Documentation/process/changes.rst similarity index 100% rename from Documentation/Changes rename to Documentation/process/changes.rst diff --git a/Documentation/CodeOfConflict b/Documentation/process/code-of-conflict.rst similarity index 100% rename from Documentation/CodeOfConflict rename to Documentation/process/code-of-conflict.rst diff --git a/Documentation/CodingStyle b/Documentation/process/coding-style.rst similarity index 100% rename from Documentation/CodingStyle rename to Documentation/process/coding-style.rst diff --git a/Documentation/email-clients.txt b/Documentation/process/email-clients.rst similarity index 100% rename from Documentation/email-clients.txt rename to Documentation/process/email-clients.rst diff --git a/Documentation/HOWTO b/Documentation/process/howto.rst similarity index 100% rename from Documentation/HOWTO rename to Documentation/process/howto.rst diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index c37475d910903..6ee818752474a 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/kernel-docs.txt b/Documentation/process/kernel-docs.rst similarity index 100% rename from Documentation/kernel-docs.txt rename to Documentation/process/kernel-docs.rst diff --git a/Documentation/magic-number.txt b/Documentation/process/magic-number.rst similarity index 100% rename from Documentation/magic-number.txt rename to Documentation/process/magic-number.rst diff --git a/Documentation/ManagementStyle b/Documentation/process/management-style.rst similarity index 100% rename from Documentation/ManagementStyle rename to Documentation/process/management-style.rst diff --git a/Documentation/stable_api_nonsense.txt b/Documentation/process/stable-api-nonsense.rst similarity index 100% rename from Documentation/stable_api_nonsense.txt rename to Documentation/process/stable-api-nonsense.rst diff --git a/Documentation/stable_kernel_rules.txt b/Documentation/process/stable-kernel-rules.rst similarity index 100% rename from Documentation/stable_kernel_rules.txt rename to Documentation/process/stable-kernel-rules.rst diff --git a/Documentation/SubmitChecklist b/Documentation/process/submit-checklist.rst similarity index 100% rename from Documentation/SubmitChecklist rename to Documentation/process/submit-checklist.rst diff --git a/Documentation/SubmittingDrivers b/Documentation/process/submitting-drivers.rst similarity index 100% rename from Documentation/SubmittingDrivers rename to Documentation/process/submitting-drivers.rst diff --git a/Documentation/SubmittingPatches b/Documentation/process/submitting-patches.rst similarity index 99% rename from Documentation/SubmittingPatches rename to Documentation/process/submitting-patches.rst index e62ddcdcaf5db..4cc20b2c6df38 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/process/submitting-patches.rst @@ -838,4 +838,3 @@ 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/volatile-considered-harmful.txt b/Documentation/process/volatile-considered-harmful.rst similarity index 100% rename from Documentation/volatile-considered-harmful.txt rename to Documentation/process/volatile-considered-harmful.rst -- GitLab From 9d85025b0418163fae079c9ba8f8445212de8568 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Wed, 21 Sep 2016 09:51:11 -0300 Subject: [PATCH 039/193] 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 --- .../admin-guide/README.rst | 1 - .../bad-memory.rst} | 1 - .../basic-profiling.rst} | 1 - .../binfmt-misc.rst} | 0 .../braille-console.rst} | 0 .../bug-hunting.rst} | 0 Documentation/admin-guide/conf.py | 10 ++++++ .../{devices.txt => admin-guide/devices.rst} | 1 - .../dynamic-debug-howto.rst} | 0 Documentation/admin-guide/index.rst | 34 +++++++++++++++++++ .../{init.txt => admin-guide/init.rst} | 0 .../{initrd.txt => admin-guide/initrd.rst} | 0 .../{java.txt => admin-guide/java.rst} | 1 - .../kernel-parameters.rst} | 0 Documentation/{md.txt => admin-guide/md.rst} | 0 .../{mono.txt => admin-guide/mono.rst} | 0 .../oops-tracing.rst} | 0 .../{parport.txt => admin-guide/parport.rst} | 0 .../{ramoops.txt => admin-guide/ramoops.rst} | 0 .../admin-guide/reporting-bugs.rst | 0 .../security-bugs.rst} | 12 +++---- .../serial-console.rst} | 0 .../sysfs-rules.rst} | 0 .../{sysrq.txt => admin-guide/sysrq.rst} | 0 .../{unicode.txt => admin-guide/unicode.rst} | 0 .../vga-softcursor.rst} | 0 Documentation/conf.py | 2 ++ Documentation/index.rst | 1 + 28 files changed, 53 insertions(+), 11 deletions(-) rename README => Documentation/admin-guide/README.rst (99%) rename Documentation/{bad_memory.txt => admin-guide/bad-memory.rst} (99%) rename Documentation/{basic_profiling.txt => admin-guide/basic-profiling.rst} (99%) rename Documentation/{binfmt_misc.txt => admin-guide/binfmt-misc.rst} (100%) rename Documentation/{braille-console.txt => admin-guide/braille-console.rst} (100%) rename Documentation/{BUG-HUNTING => admin-guide/bug-hunting.rst} (100%) create mode 100644 Documentation/admin-guide/conf.py rename Documentation/{devices.txt => admin-guide/devices.rst} (99%) rename Documentation/{dynamic-debug-howto.txt => admin-guide/dynamic-debug-howto.rst} (100%) create mode 100644 Documentation/admin-guide/index.rst rename Documentation/{init.txt => admin-guide/init.rst} (100%) rename Documentation/{initrd.txt => admin-guide/initrd.rst} (100%) rename Documentation/{java.txt => admin-guide/java.rst} (99%) rename Documentation/{kernel-parameters.txt => admin-guide/kernel-parameters.rst} (100%) rename Documentation/{md.txt => admin-guide/md.rst} (100%) rename Documentation/{mono.txt => admin-guide/mono.rst} (100%) rename Documentation/{oops-tracing.txt => admin-guide/oops-tracing.rst} (100%) rename Documentation/{parport.txt => admin-guide/parport.rst} (100%) rename Documentation/{ramoops.txt => admin-guide/ramoops.rst} (100%) rename REPORTING-BUGS => Documentation/admin-guide/reporting-bugs.rst (100%) rename Documentation/{SecurityBugs => admin-guide/security-bugs.rst} (95%) rename Documentation/{serial-console.txt => admin-guide/serial-console.rst} (100%) rename Documentation/{sysfs-rules.txt => admin-guide/sysfs-rules.rst} (100%) rename Documentation/{sysrq.txt => admin-guide/sysrq.rst} (100%) rename Documentation/{unicode.txt => admin-guide/unicode.rst} (100%) rename Documentation/{VGA-softcursor.txt => admin-guide/vga-softcursor.rst} (100%) diff --git a/README b/Documentation/admin-guide/README.rst similarity index 99% rename from README rename to Documentation/admin-guide/README.rst index 3335b3b2973a7..05aad85433403 100644 --- a/README +++ b/Documentation/admin-guide/README.rst @@ -408,4 +408,3 @@ If something goes wrong 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/bad_memory.txt b/Documentation/admin-guide/bad-memory.rst similarity index 99% rename from Documentation/bad_memory.txt rename to Documentation/admin-guide/bad-memory.rst index 5cac93e27a978..017fc86430c34 100644 --- a/Documentation/bad_memory.txt +++ b/Documentation/admin-guide/bad-memory.rst @@ -48,4 +48,3 @@ With the numbers of the example above:: or:: memmap=0x10000$0x18690000 - diff --git a/Documentation/basic_profiling.txt b/Documentation/admin-guide/basic-profiling.rst similarity index 99% rename from Documentation/basic_profiling.txt rename to Documentation/admin-guide/basic-profiling.rst index 15a49dbd0189c..72babc71b7713 100644 --- a/Documentation/basic_profiling.txt +++ b/Documentation/admin-guide/basic-profiling.rst @@ -66,4 +66,3 @@ Some ``opcontrol`` commands:: 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/admin-guide/binfmt-misc.rst similarity index 100% rename from Documentation/binfmt_misc.txt rename to Documentation/admin-guide/binfmt-misc.rst diff --git a/Documentation/braille-console.txt b/Documentation/admin-guide/braille-console.rst similarity index 100% rename from Documentation/braille-console.txt rename to Documentation/admin-guide/braille-console.rst diff --git a/Documentation/BUG-HUNTING b/Documentation/admin-guide/bug-hunting.rst similarity index 100% rename from Documentation/BUG-HUNTING rename to Documentation/admin-guide/bug-hunting.rst diff --git a/Documentation/admin-guide/conf.py b/Documentation/admin-guide/conf.py new file mode 100644 index 0000000000000..86f738953799a --- /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/devices.txt b/Documentation/admin-guide/devices.rst similarity index 99% rename from Documentation/devices.txt rename to Documentation/admin-guide/devices.rst index 17b365331f235..b29555041531b 100644 --- a/Documentation/devices.txt +++ b/Documentation/admin-guide/devices.rst @@ -3348,4 +3348,3 @@ 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/admin-guide/dynamic-debug-howto.rst similarity index 100% rename from Documentation/dynamic-debug-howto.txt rename to Documentation/admin-guide/dynamic-debug-howto.rst diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst new file mode 100644 index 0000000000000..4e5abbb4bbd58 --- /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/init.txt b/Documentation/admin-guide/init.rst similarity index 100% rename from Documentation/init.txt rename to Documentation/admin-guide/init.rst diff --git a/Documentation/initrd.txt b/Documentation/admin-guide/initrd.rst similarity index 100% rename from Documentation/initrd.txt rename to Documentation/admin-guide/initrd.rst diff --git a/Documentation/java.txt b/Documentation/admin-guide/java.rst similarity index 99% rename from Documentation/java.txt rename to Documentation/admin-guide/java.rst index ae33d959638c7..a0de7c1a1ed90 100644 --- a/Documentation/java.txt +++ b/Documentation/admin-guide/java.rst @@ -415,4 +415,3 @@ 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/admin-guide/kernel-parameters.rst similarity index 100% rename from Documentation/kernel-parameters.txt rename to Documentation/admin-guide/kernel-parameters.rst diff --git a/Documentation/md.txt b/Documentation/admin-guide/md.rst similarity index 100% rename from Documentation/md.txt rename to Documentation/admin-guide/md.rst diff --git a/Documentation/mono.txt b/Documentation/admin-guide/mono.rst similarity index 100% rename from Documentation/mono.txt rename to Documentation/admin-guide/mono.rst diff --git a/Documentation/oops-tracing.txt b/Documentation/admin-guide/oops-tracing.rst similarity index 100% rename from Documentation/oops-tracing.txt rename to Documentation/admin-guide/oops-tracing.rst diff --git a/Documentation/parport.txt b/Documentation/admin-guide/parport.rst similarity index 100% rename from Documentation/parport.txt rename to Documentation/admin-guide/parport.rst diff --git a/Documentation/ramoops.txt b/Documentation/admin-guide/ramoops.rst similarity index 100% rename from Documentation/ramoops.txt rename to Documentation/admin-guide/ramoops.rst diff --git a/REPORTING-BUGS b/Documentation/admin-guide/reporting-bugs.rst similarity index 100% rename from REPORTING-BUGS rename to Documentation/admin-guide/reporting-bugs.rst diff --git a/Documentation/SecurityBugs b/Documentation/admin-guide/security-bugs.rst similarity index 95% rename from Documentation/SecurityBugs rename to Documentation/admin-guide/security-bugs.rst index 342d769834f60..df795e22d08be 100644 --- a/Documentation/SecurityBugs +++ b/Documentation/admin-guide/security-bugs.rst @@ -8,8 +8,8 @@ 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 ----------- +Contact +------- The Linux kernel security team can be contacted by email at . This is a private list of security officers @@ -23,8 +23,8 @@ 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 -------------- +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 @@ -39,8 +39,8 @@ 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 ----------------------------- +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/serial-console.txt b/Documentation/admin-guide/serial-console.rst similarity index 100% rename from Documentation/serial-console.txt rename to Documentation/admin-guide/serial-console.rst diff --git a/Documentation/sysfs-rules.txt b/Documentation/admin-guide/sysfs-rules.rst similarity index 100% rename from Documentation/sysfs-rules.txt rename to Documentation/admin-guide/sysfs-rules.rst diff --git a/Documentation/sysrq.txt b/Documentation/admin-guide/sysrq.rst similarity index 100% rename from Documentation/sysrq.txt rename to Documentation/admin-guide/sysrq.rst diff --git a/Documentation/unicode.txt b/Documentation/admin-guide/unicode.rst similarity index 100% rename from Documentation/unicode.txt rename to Documentation/admin-guide/unicode.rst diff --git a/Documentation/VGA-softcursor.txt b/Documentation/admin-guide/vga-softcursor.rst similarity index 100% rename from Documentation/VGA-softcursor.txt rename to Documentation/admin-guide/vga-softcursor.rst diff --git a/Documentation/conf.py b/Documentation/conf.py index b08e0c9b73b7f..d9bad21dd4273 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/index.rst b/Documentation/index.rst index e1f18b3db6e47..f6a3d4766495f 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 -- GitLab From 8c27ceff3604b249a9efafbd1bd8b141b79e619d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 10:12:27 -0200 Subject: [PATCH 040/193] 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 +- .../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 +- .../devicetree/bindings/rtc/pcf8563.txt | 2 +- .../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 +- .../virtual/kvm/review-checklist.txt | 4 +- Documentation/vm/numa | 2 +- .../convert_drivers_to_kernel_api.txt | 2 +- .../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 d07575a8499ee..39caa6544d1fe 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 1fafc4b0753b4..3121029dce210 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 91bd6ca5440f3..2cc0a72b64be6 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 2a272275c81bc..da5c087462b1d 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 78b32ac024666..79bf6a4921bee 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 05aad85433403..1b6dfb2b3adb0 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 017fc86430c34..a5c0e25e496ff 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 9c5ff8f260bfb..97b0d79270782 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 fa3702dc04ab9..18e79337dcfd7 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 a8ef794aadaef..d35dd9fd1af0e 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 b29555041531b..89db341fba7ab 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 b0804273b6e39..d2f2725f032ea 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 3e25ea7349eec..13be8d7bcfe7a 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 7eaf1e71c0833..fe95c027e37c1 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 05c53ac7fa76e..0c0f2698ec5a4 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 df795e22d08be..4f7414cad5861 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 012e8e895842b..4e5c3df9d55fb 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 83c1df2fc758b..259f00af3ab34 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 c9d1cacb43959..7281bf939779b 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 fe2ef978d85a4..501e12e0323e4 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 106885ad670d6..13e0c85e7b357 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 ddef330d2709e..1ad4c1c2b3b37 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 72f6d2c9665e4..086c998c55610 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 7d44eae7ab0b9..274058c583dde 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 2cf81082581db..5368690f412e5 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 0b2883b17d4c1..5efae00f6c7fd 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 9bdf4b46e741e..cd9dc1dfb144f 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 57f60307accc6..f88221b461534 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 cfb1884342eeb..32d4e80c2c03f 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 581c14bdd7be2..b03fc8047f03e 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 cb5507b1ac818..60c7c35ac517c 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 5d6ae639bfa0a..02139656463eb 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 7653b5cbfed2b..a3b40a4bdcfd2 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 9dbda9b5d21ed..f9249aecba64b 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 bbc3a8b8cff49..df31e30b6a025 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 9a3e65924d549..025252731af51 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 3ba10b11d5563..4d93af1efd61e 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 4a6e33e1af61e..c8b8378513d6e 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 eaf32a1fd0b10..79d21246c75a4 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 76b2ecab86577..8209eeb63dd24 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 7abc1c9a261bd..bc63b12efafd0 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 0d7cb955aa01d..5de846d3ecc07 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 30409a36e95da..296ea00fd3eb6 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 0fe1c6e0dbcd5..cdebc5c8705f0 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 97282da82b75c..ad3dead052a4a 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 ad04cc8097ed9..7cb6085839f38 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 44558882aa602..85c746cbab2c8 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 1fd1fbe9ce95a..4870980e967e0 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 59931b46ff7ee..b802fbfd95ef0 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 9d5cef996f7f9..983d628c1112d 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 b511ddf7e82ac..1b7728b19ea7a 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 23ec7cbc2d2b5..1c7f54cd02610 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 f5b5b1aa51b34..8cc25a06f3533 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 9c61c039ccd97..968808bec4075 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 5f042349f987a..3f66a1980726a 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 dea2e66c9a101..45595fd8a66bd 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 4d82e31b79589..11ec2d93a5e08 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 894289b22b155..a0d9d34bfb6d2 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 252b77a23fada..0939d018c2893 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 4cc20b2c6df38..b4cf8f3751843 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 1f0c27049340d..8c174063b3f0c 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 8e66dafa41e1b..8477655c0e46e 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 2550751575116..6338400eed73d 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 6af8f7a7770fa..d28186553fb05 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 0fa40679b0802..72eced86f035e 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 3ab391e7c2954..cc675f25eee4a 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 ffab8b5caa603..6bb78f8729291 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 a850986ed684c..a83b27635fdd6 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 e0b58c0e6b499..a08f716477145 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 271b8850dde76..9fffb2958d130 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 a8d364227a770..e21850e270a05 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 9da6f35122496..5e9b826b5f62f 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 12717791baac0..b027380427992 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 f0613b92e0bed..11be075ba5fa4 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 d21eb07fe9438..2d0fffd122cee 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 d313f5d8448d7..929385e4b1941 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 1d3a10f8746ba..e9098da8f1a4f 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 6158a64df80c5..1fe866f8218f2 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 b9a1a3e6c78d5..ec31d97e8d0e9 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 9312608ffb8d1..41ab53cc0e839 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 c26a27d1ee7de..a2b27fab382c9 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 26ea5ed7cd9c4..db4ba5a0c39aa 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 ba8149d2233a0..4751259671974 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 de0451df542ff..69820b75b2e04 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 bada636d1065c..19d237b0737dc 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 535e7828445ab..c5f9cbe0ae21d 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 223a770f78f36..59ce0dd50701e 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 c115217c79aec..e051fc8aa7d77 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 db9538d4b3586..a7be12d9a1398 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 8b2b740d6679e..b20ce7da1ee45 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 5dd430f8f9213..d84dffb894f43 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 f948baa16d829..e219a0a220770 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 77590320d44ce..623f72334fa55 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 4c09d93d95694..b2f82cf6bf868 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 be40813eff52c..b42e5bd6d8ffd 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 bc41e87a969bf..36d3a9867da97 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 06eb353182abe..efa67b2dfee95 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 620252e69b44a..19e195bee990f 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 34407f15e6d34..172f80ea0d588 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 2858be732f6d2..691eb9351a831 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 33bc56cf60d71..d2df3a93284b6 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 a8368d1c4348c..d0c729ccec20f 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 0558bb9ce0a6e..f3926c33ed4cb 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. -- GitLab From 08a9a8d44c1c0e1b6d765a627b6f895dc6202e9b Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 09:22:55 -0200 Subject: [PATCH 041/193] 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 0000000000000..320983ca114e7 --- /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 0000000000000..81455705e4a62 --- /dev/null +++ b/Documentation/SubmittingPatches @@ -0,0 +1 @@ +This file has moved to process/submitting-patches.rst -- GitLab From 6bef44b9b969a8bcf49f28a3079400ab1dac5769 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 10:46:38 -0200 Subject: [PATCH 042/193] 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 0000000000000..b2ba4aaa3a710 --- /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. -- GitLab From 3cbd4b543bef00c638fd63f6f043006c0c432f23 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 18 Oct 2016 12:31:12 -0200 Subject: [PATCH 043/193] 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 39caa6544d1fe..903ebc494f298 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/ -- GitLab From 7b855a120b2281e74c8533faf3436e5233d83601 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Fri, 21 Oct 2016 23:10:02 +0900 Subject: [PATCH 044/193] 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 34d3d380893d3..a3228a676cc18 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 문을 뒤따르는 코드에는 적용되지 -않습니다-. + (*) 컨트롤 의존성은 보통 다른 타입의 배리어들과 짝을 맞춰 사용됩니다. (*) 컨트롤 의존성은 이행성을 제공하지 -않습니다-. 이행성이 필요하다면, -- GitLab From bb118c56fda53fbca71ee8f35ff870d35370c969 Mon Sep 17 00:00:00 2001 From: Igor Vuk Date: Tue, 25 Oct 2016 21:00:31 +0200 Subject: [PATCH 045/193] 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 dd68821c22d4b..d02e8a451872c 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: -- GitLab From 452a256898e7ca88115aa02d3851e67994ce3e19 Mon Sep 17 00:00:00 2001 From: anish kumar Date: Sun, 23 Oct 2016 21:03:53 -0700 Subject: [PATCH 046/193] ASoC: Codec to codec dai link description Signed-off-by: anish kumar Acked-by: Charles Keepax Signed-off-by: Mark Brown --- .../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 0000000000000..704a6483652ca --- /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. -- GitLab From c289312f964b6e8851d0812b65f59c8b0387e78d Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 26 Oct 2016 08:23:14 +0200 Subject: [PATCH 047/193] 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/{tools.rst => index.rst} | 8 ++++++++ Documentation/index.rst | 2 +- 3 files changed, 19 insertions(+), 1 deletion(-) create mode 100644 Documentation/dev-tools/conf.py rename Documentation/dev-tools/{tools.rst => index.rst} (87%) diff --git a/Documentation/dev-tools/conf.py b/Documentation/dev-tools/conf.py new file mode 100644 index 0000000000000..7faafa3f78886 --- /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/tools.rst b/Documentation/dev-tools/index.rst similarity index 87% rename from Documentation/dev-tools/tools.rst rename to Documentation/dev-tools/index.rst index 824ae8e54dd5b..07d881147ef3c 100644 --- a/Documentation/dev-tools/tools.rst +++ b/Documentation/dev-tools/index.rst @@ -23,3 +23,11 @@ whole; patches welcome! kmemleak kmemcheck gdb-kernel-debugging + + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex` diff --git a/Documentation/index.rst b/Documentation/index.rst index f6a3d4766495f..0f98823126f2c 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 -- GitLab From 241a8021c60fb19d9d8524d2f6d0d5a52a1e056f Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 26 Oct 2016 08:23:15 +0200 Subject: [PATCH 048/193] 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 0000000000000..202726d20088a --- /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 b567907db3509..e18135b513e24 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` -- GitLab From 6f2ec3a9d5489e2b54c63ca648bb00d0857c7a96 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 26 Oct 2016 08:23:16 +0200 Subject: [PATCH 049/193] 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 90bba476f4429..af210859d3e10 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 4e5abbb4bbd58..fb779e67097b9 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 be0dafcf5556d..367d7c36b8e90 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 6ee818752474a..cddf580671e7e 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` -- GitLab From fdd91a3dfadfa73bbb54702f1e951e7c17a507d6 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 26 Oct 2016 08:23:17 +0200 Subject: [PATCH 050/193] 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 20c7c275ef4a9..4424b4b0b9c35 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 6314d17082309..1757b040fb32f 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'), +] -- GitLab From b51208d41c6a4e7fc2f05e63df49f1834cd3c208 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 15:43:00 -0600 Subject: [PATCH 051/193] 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 f6a3d4766495f..7cec8432ce7ae 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 -- GitLab From 555af62431e69105b4d20628181acf414759a70d Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 15:55:20 -0600 Subject: [PATCH 052/193] 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 10cc7ddb62356..c66ab937c2cae 100644 --- a/Documentation/kernel-documentation.rst +++ b/Documentation/kernel-documentation.rst @@ -1,6 +1,6 @@ -========================== -Linux Kernel Documentation -========================== +================================= +How to write kernel documentation +================================= Introduction ============ -- GitLab From 7358bb2f3293461737a61850c56523695f5b2219 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:14:52 -0600 Subject: [PATCH 053/193] 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 +++++++++++++++---- .../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 4e5abbb4bbd58..2ce2bf02824bb 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 d2f2725f032ea..37105aedb2e4f 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 04bdd52cba1d1..abad33526acad 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 9eac6744b3a19..a663a745cff4b 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:: -- GitLab From 2c79dcafd8ecdfd44ee4c509a9c55785b022eba9 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:20:27 -0600 Subject: [PATCH 054/193] 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 a5c0e25e496ff..0000000000000 --- 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 2ce2bf02824bb..d737ae71efc6b 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 -- GitLab From 5700d1974818a98983e018efa01da9bc81b84e1a Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:22:01 -0600 Subject: [PATCH 055/193] 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 72babc71b7713..0000000000000 --- 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 d737ae71efc6b..2872c0c70ea4c 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 -- GitLab From 9b4ebd98da9112f974a6db58555a33eb1bd7c0b0 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:34:09 -0600 Subject: [PATCH 056/193] 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 22797a15dc24e..56ce661146656 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 6ee818752474a..0cbc62adbbb1f 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 -- GitLab From 89edeedd61e8faa4e092f3797606739317abeb6c Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:37:53 -0600 Subject: [PATCH 057/193] 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 b4cf8f3751843..3e10719fee35d 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). -- GitLab From be4612447b3721a9a9f14ea5189217d69bc83078 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:41:05 -0600 Subject: [PATCH 058/193] 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 0cbc62adbbb1f..0557144cef2b4 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 -- GitLab From 31b24bee33572031632c33091bb73ed0e949c53a Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:45:29 -0600 Subject: [PATCH 059/193] 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 0939d018c2893..afb82ee0cbea2 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. -- GitLab From 67972a539e9ff1a3ed794c463c4e544442df693e Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 26 Oct 2016 16:48:36 -0600 Subject: [PATCH 060/193] 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 abd7dc7ae2405..87825cf96f332 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 -- GitLab From 2797cd03f5cca4d9fb2875c9f9c995737ce73469 Mon Sep 17 00:00:00 2001 From: Oliver Neukum Date: Thu, 20 Oct 2016 15:15:00 +0200 Subject: [PATCH 061/193] 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 bc776be0f19c1..8ec4d595b2185 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. -- GitLab From c950a1739eaef2ab64372fc35af7301fcef2c9a7 Mon Sep 17 00:00:00 2001 From: Silvio Fricke Date: Fri, 28 Oct 2016 10:14:08 +0200 Subject: [PATCH 062/193] 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 93721f3c91bff..e10378f769f9e 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"; } -- GitLab From 42412c3aae5d8ea57a46b8ff86bb67bc1a270d9c Mon Sep 17 00:00:00 2001 From: Silvio Fricke Date: Fri, 28 Oct 2016 10:14:09 +0200 Subject: [PATCH 063/193] 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 fc6e221864058..d4f16cf6281c3 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. -- GitLab From 24755a55b01ffbf6ed128c1dd4028c05a2b0b1ef Mon Sep 17 00:00:00 2001 From: Silvio Fricke Date: Fri, 28 Oct 2016 10:14:10 +0200 Subject: [PATCH 064/193] 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 903ebc494f298..e2e74448d4258 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 0000000000000..fed87ab7f4867 --- /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 0000000000000..ed3eb6499e114 --- /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 85a66270f96ce..3bb82fb11a4d4 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 -- GitLab From e7f08ffb1855c482b0220cac12669ea06039da6d Mon Sep 17 00:00:00 2001 From: Silvio Fricke Date: Fri, 28 Oct 2016 10:14:11 +0200 Subject: [PATCH 065/193] 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 + .../{workqueue.txt => core-api/workqueue.rst} | 260 +++++++++--------- MAINTAINERS | 2 +- 3 files changed, 136 insertions(+), 128 deletions(-) rename Documentation/{workqueue.txt => core-api/workqueue.rst} (63%) diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst index ed3eb6499e114..f7ef7fda5763f 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/workqueue.txt b/Documentation/core-api/workqueue.rst similarity index 63% rename from Documentation/workqueue.txt rename to Documentation/core-api/workqueue.rst index c49e3178178d3..ffdec94fbca18 100644 --- a/Documentation/workqueue.txt +++ b/Documentation/core-api/workqueue.rst @@ -1,21 +1,14 @@ - +==================================== 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 +:Date: September, 2010 +:Author: Tejun Heo +:Author: Florian Mickler -1. Introduction +Introduction +============ There are many cases where an asynchronous process execution context is needed and the workqueue (wq) API is the most commonly used @@ -32,7 +25,8 @@ 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? +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 @@ -71,7 +65,8 @@ focus on the following goals. the API users don't need to worry about such details. -3. The Design +The Design +========== In order to ease the asynchronous execution of functions a new abstraction, the work item, is introduced. @@ -102,7 +97,7 @@ 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. +``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 @@ -136,7 +131,7 @@ 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 +``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 @@ -151,94 +146,95 @@ pressure. Else it is possible that the worker-pool deadlocks waiting for execution contexts to free up. -4. Application Programming Interface (API) +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. +``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 +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 +``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. +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 @@ -247,13 +243,14 @@ 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. +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 +Example Execution Scenarios +=========================== The following example execution scenarios try to illustrate how cmwq behave under different configurations. @@ -265,7 +262,7 @@ behave under different configurations. 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. +of possible sequences of events with the original wq. :: TIME IN MSECS EVENT 0 w0 starts and burns CPU @@ -279,7 +276,7 @@ of possible sequences of events with the original wq. 40 w2 sleeps 50 w2 wakes up and finishes -And with cmwq with @max_active >= 3, +And with cmwq with ``@max_active`` >= 3, :: TIME IN MSECS EVENT 0 w0 starts and burns CPU @@ -293,7 +290,7 @@ And with cmwq with @max_active >= 3, 20 w1 wakes up and finishes 25 w2 wakes up and finishes -If @max_active == 2, +If ``@max_active`` == 2, :: TIME IN MSECS EVENT 0 w0 starts and burns CPU @@ -308,7 +305,7 @@ If @max_active == 2, 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, +``WQ_CPU_INTENSIVE`` set, :: TIME IN MSECS EVENT 0 w0 starts and burns CPU @@ -322,13 +319,15 @@ WQ_CPU_INTENSIVE set, 25 w2 wakes up and finishes -6. Guidelines +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. +* 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. @@ -337,30 +336,31 @@ WQ_CPU_INTENSIVE set, 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. + (``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 +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: +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] + 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: @@ -368,7 +368,7 @@ 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: +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 @@ -380,9 +380,15 @@ 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. +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/MAINTAINERS b/MAINTAINERS index 69820b75b2e04..489a913a0bd4b 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 -- GitLab From 1171a28bacee936be4da7c83de429e0258e647c3 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 2 Nov 2016 10:38:43 +0200 Subject: [PATCH 066/193] 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 92deea30b183c..1314e3ee31c4e 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: -- GitLab From 207fc55bc32f6baf0f4793afb5e79267d528e1ae Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 2 Nov 2016 11:13:19 +0200 Subject: [PATCH 067/193] 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 1314e3ee31c4e..4819638f7e216 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 -- GitLab From c8556966720f9b54104b55f648a7bbc6f01d7b43 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 2 Nov 2016 10:56:31 +0200 Subject: [PATCH 068/193] 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 4819638f7e216..4d3ff4b7a2a53 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) \ -- GitLab From eaed1b25a783121ecd4fb4eccebe45b08675b915 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 2 Nov 2016 13:20:15 +0200 Subject: [PATCH 069/193] 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 4d3ff4b7a2a53..d58d776d8d007 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) -- GitLab From 0af205ea6c35ad540d638351ce37457e3ee2bac8 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Wed, 2 Nov 2016 16:37:11 +0200 Subject: [PATCH 070/193] 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 d58d776d8d007..ec0c77d028dbf 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 -- GitLab From 8d26d90ba3e1cfb75c4af2882045ca2c8120fbab Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Wed, 2 Nov 2016 13:05:59 +0200 Subject: [PATCH 071/193] 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 d9bad21dd4273..7830051b6837a 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'), -- GitLab From b459106ea4b7f317faa24b47e9a6b20c2f254d2d Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 3 Nov 2016 10:26:54 +0200 Subject: [PATCH 072/193] 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 7830051b6837a..bcb1af786e78c 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 ---------------------------------------------- -- GitLab From 07a37ba5835315f40431900dd1a8e80af4682294 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 3 Nov 2016 11:43:29 +0200 Subject: [PATCH 073/193] 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 a0de7c1a1ed90..8744e272e6f8b 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 9a9744ca0cf3d..cdddc099af646 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 fe95c027e37c1..4efd7ce775653 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 [...] -- GitLab From 57131dd3fd9f51a6b54a917d7faa6ce59d7f3e48 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 3 Nov 2016 11:44:04 +0200 Subject: [PATCH 074/193] 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 19eedfea8800d..69a7d90c320ad 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 aca0e27ca1972..2c41b713841fd 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 -- GitLab From 29849a695ffefd0055e23f5c59659dd377e361fe Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 3 Nov 2016 11:44:23 +0200 Subject: [PATCH 075/193] 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 53b872c105d24..38af5d1cc59f5 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 bca808535dfd8..cb5daffcd6be2 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; -- GitLab From e52347bd66f6fb428464f84f4c867e68bcb4ad4e Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 3 Nov 2016 12:10:10 +0200 Subject: [PATCH 076/193] 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 --- .../admin-guide/kernel-parameters.rst | 4374 +---------------- .../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 37105aedb2e4f..b516164999a80 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 0000000000000..e48c5632bd6c9 --- /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: + ,,,,,[,[,[,]]] -- GitLab From 07c7e30c1885393b07efcaf62d51b219755b6bf5 Mon Sep 17 00:00:00 2001 From: Jani Nikula Date: Thu, 3 Nov 2016 12:11:50 +0200 Subject: [PATCH 077/193] 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 89db341fba7ab..7fadc05330dd7 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 0000000000000..c9cea2e39c218 --- /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 -- GitLab From ab0e44c155519d9b16f9eca1644d520788dd4545 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 7 Nov 2016 17:03:16 -0200 Subject: [PATCH 078/193] 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 d35dd9fd1af0e..818b3e09267fa 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 -- GitLab From c730904b16c7ee6f3bba2d1536621151745fc314 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 7 Nov 2016 17:03:17 -0200 Subject: [PATCH 079/193] 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 0000000000000..5682d742017c8 --- /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 818b3e09267fa..d245d4677ae2a 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 368845e9900a2..98e60f678352f 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 -- GitLab From 337c188dff4a850643ee299c38b2591bbda937a7 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 7 Nov 2016 17:03:18 -0200 Subject: [PATCH 080/193] 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 98e60f678352f..86a6ab98d6b6a 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 13be8d7bcfe7a..1f5e2b716631e 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 0000000000000..1df03b5cb02f7 --- /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. -- GitLab From f226e460875da8e00febf55e5ec3438e498ca676 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 7 Nov 2016 17:03:19 -0200 Subject: [PATCH 081/193] 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 d245d4677ae2a..08c4b13081898 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 86a6ab98d6b6a..2681cbd24cddf 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 1f5e2b716631e..0000000000000 --- 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 - - ---------------------------------------------------------------------------- - -- GitLab From d80b9d2aba35d2c9c030c77ad463454c077959ea Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:10 +0900 Subject: [PATCH 082/193] 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 3f66a1980726a..449ca1f199f4e 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 -- GitLab From a9c9c70e3422ae673c7f95d0bc25bbdaf4e10576 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:11 +0900 Subject: [PATCH 083/193] 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 025252731af51..4f5778dfeed2b 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에게 제출할 수 있다. 대개 이 패치들은 -- GitLab From a9fb9356af8120db6f10d061ed70382ed8a161f0 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:12 +0900 Subject: [PATCH 084/193] 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 4f5778dfeed2b..1a5d7a8d66be5 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에 모든 변화들이 여기서 메 커널 커뮤니티와 기업 조직간의 차이점 ------------------------------------------------------------------ +------------------------------------ 커널 커뮤니티는 가장 전통적인 회사의 개발 환경과는 다르다. 여기에 여러분들의 문제를 피하기 위한 목록이 있다. 여러분들이 제안한 변경들에 관하여 말할 때 좋은 것들 : -- GitLab From d7e81bfd55810bac093b478e9d7bdb2faf4cd997 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:13 +0900 Subject: [PATCH 085/193] 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 1a5d7a8d66be5..f3348ef68bbd3 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 파일은 커널 버그라고 생각되는 것을 보고하는 방법에 관한 좋은 템플릿이며 문제를 추적하기 위해서 커널 -- GitLab From 1c9feddacdfaf27bcef94ae691420a302b7f0a8e Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:14 +0900 Subject: [PATCH 086/193] 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 f3348ef68bbd3..c2a3f17197532 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에게 감사한다. 여러분들이 말해야 할 것과 말해서는 안되는 것의 목록 중 일부를 제공해준 -- GitLab From ae8fc192811f206cc136ffffcf8229ea380edf15 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:15 +0900 Subject: [PATCH 087/193] 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 c2a3f17197532..7f0b4e66e6c23 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 ` 패치가 무엇이며 그것을 커널의 다른 개발 브랜치들에 어떻게 적용하는지에 관하여 자세히 설명하고 있는 좋은 입문서이다. -- GitLab From 48fe44ccf311fb68eba235eed9358559e893d2f5 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:16 +0900 Subject: [PATCH 088/193] 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 7f0b4e66e6c23..918be41b75dee 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 커널 개발자가 되는 것 --------------------- -- GitLab From 80f0fceb4fc78c2cc6830dc707af51ac285bd8aa Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:17 +0900 Subject: [PATCH 089/193] 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 918be41b75dee..4df8ef3d0ffe6 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의 이야기가 있다. -:: - - "학생의 수학 숙제를 채점하는 선생님을 생각해보라. 선생님은 학생들이 + *"학생의 수학 숙제를 채점하는 선생님을 생각해보라. 선생님은 학생들이 답을 얻을때까지 겪은 시행착오를 보길 원하지 않는다. 선생님들은 간결하고 가장 뛰어난 답을 보길 원한다. 훌륭한 학생은 이것을 알고 - 마지막으로 답을 얻기 전 중간 과정들을 제출하진 않는다. + 마지막으로 답을 얻기 전 중간 과정들을 제출하진 않는다.* - 커널 개발도 마찬가지이다. 메인테이너들과 검토하는 사람들은 문제를 + *커널 개발도 마찬가지이다. 메인테이너들과 검토하는 사람들은 문제를 풀어나가는 과정속에 숨겨진 과정을 보길 원하진 않는다. 그들은 - 간결하고 멋진 답을 보길 원한다." + 간결하고 멋진 답을 보길 원한다."* 커뮤니티와 협력하며 뛰어난 답을 찾는 것과 여러분들의 끝마치지 못한 작업들 사이에 균형을 유지해야 하는 것은 어려울지도 모른다. 그러므로 프로세스의 -- GitLab From a1456a7303bbcca1e5e0dbe91927bd6efd5d97fd Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:18 +0900 Subject: [PATCH 090/193] 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 4df8ef3d0ffe6..8f3a1a68758d2 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에게 감사한다. 또한 검토와 의견 그리고 -- GitLab From 602facb35b065f59ddfafe194c1ca8c9a013ddde Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:19 +0900 Subject: [PATCH 091/193] 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 8f3a1a68758d2..2a91ebd8391f5 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 -- GitLab From 15c467f981828cde5be50ca13aeba70bf64bfee4 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:20 +0900 Subject: [PATCH 092/193] 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 2a91ebd8391f5..9aea302ed8c3f 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에 모든 변화들이 여기서 메일로 전해진다) 에 등록하면 된다. -- GitLab From ac72618fc84da69337d692e9af41f9049fc3b6a2 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Tue, 1 Nov 2016 05:27:21 +0900 Subject: [PATCH 093/193] 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 9aea302ed8c3f..3b0c15b277e00 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 커널들 보다도 더 실험적이다. 서브시스템 커널 트리들과 패치들 -------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + 다양한 커널 서브시스템의 메인테이너들 --- 그리고 많은 커널 서브시스템 개발자들 --- 은 그들의 현재 개발 상태를 소스 저장소로 노출한다. 이를 통해 다른 사람들도 커널의 다른 영역에 어떤 변화가 이루어지고 있는지 알 수 있다. 급속히 개발이 -- GitLab From ca4354543a7d7f5a6ed50b01b42a61f1d42e725d Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 7 Nov 2016 18:03:13 -0700 Subject: [PATCH 094/193] 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 5682d742017c8..59567da344e8b 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: -- GitLab From 78566cf137dab5682d00721d6f7277cedbc2635d Mon Sep 17 00:00:00 2001 From: Shuah Khan Date: Mon, 7 Nov 2016 13:24:14 -0700 Subject: [PATCH 095/193] 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 54bee77fa7285..e5c7254e73d7d 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 ====================== -- GitLab From 9e355ba76455d6d44f5cf888eee820ae9a06b3ec Mon Sep 17 00:00:00 2001 From: Jarkko Sakkinen Date: Thu, 3 Nov 2016 17:57:51 -0600 Subject: [PATCH 096/193] 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 +++ ...{tpm_vtpm_proxy.txt => tpm_vtpm_proxy.rst} | 55 ++++++------------- 3 files changed, 25 insertions(+), 38 deletions(-) create mode 100644 Documentation/tpm/index.rst rename Documentation/tpm/{tpm_vtpm_proxy.txt => tpm_vtpm_proxy.rst} (53%) diff --git a/Documentation/index.rst b/Documentation/index.rst index e0fc72963e879..0058b65d361c7 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 0000000000000..af77a7bbb0700 --- /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.txt b/Documentation/tpm/tpm_vtpm_proxy.rst similarity index 53% rename from Documentation/tpm/tpm_vtpm_proxy.txt rename to Documentation/tpm/tpm_vtpm_proxy.rst index 30d19022f8690..ea08e76b17f5a 100644 --- a/Documentation/tpm/tpm_vtpm_proxy.txt +++ b/Documentation/tpm/tpm_vtpm_proxy.rst @@ -1,71 +1,50 @@ +============================================= Virtual TPM Proxy Driver for Linux Containers +============================================= -Authors: Stefan Berger (IBM) +| Authors: +| Stefan Berger This document describes the virtual Trusted Platform Module (vTPM) proxy device driver for Linux containers. -INTRODUCTION ------------- +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 ------- +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 +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 +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. +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. -Depending on the version of TPM the following commands will be sent by the -driver: +UAPI +==== -- 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 +.. kernel-doc:: include/uapi/linux/vtpm_proxy.h -The TPM device /dev/tpmX will only appear if all of the relevant commands -were responded to properly. +.. kernel-doc:: drivers/char/tpm/tpm_vtpm_proxy.c + :functions: vtpmx_ioc_new_dev -- GitLab From 799a545bb9383c6185ad27063adca03d28ee1823 Mon Sep 17 00:00:00 2001 From: Jarkko Sakkinen Date: Thu, 3 Nov 2016 17:57:52 -0600 Subject: [PATCH 097/193] 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 | 0 Documentation/{ => security}/tpm/tpm_vtpm_proxy.rst | 0 Documentation/{ => security}/tpm/xen-tpmfront.txt | 0 5 files changed, 8 insertions(+), 1 deletion(-) create mode 100644 Documentation/security/index.rst rename Documentation/{ => security}/tpm/index.rst (100%) rename Documentation/{ => security}/tpm/tpm_vtpm_proxy.rst (100%) rename Documentation/{ => security}/tpm/xen-tpmfront.txt (100%) diff --git a/Documentation/index.rst b/Documentation/index.rst index 0058b65d361c7..b4c3034ebc09f 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 0000000000000..9bae6bb20e7fd --- /dev/null +++ b/Documentation/security/index.rst @@ -0,0 +1,7 @@ +====================== +Security documentation +====================== + +.. toctree:: + + tpm/index diff --git a/Documentation/tpm/index.rst b/Documentation/security/tpm/index.rst similarity index 100% rename from Documentation/tpm/index.rst rename to Documentation/security/tpm/index.rst diff --git a/Documentation/tpm/tpm_vtpm_proxy.rst b/Documentation/security/tpm/tpm_vtpm_proxy.rst similarity index 100% rename from Documentation/tpm/tpm_vtpm_proxy.rst rename to Documentation/security/tpm/tpm_vtpm_proxy.rst diff --git a/Documentation/tpm/xen-tpmfront.txt b/Documentation/security/tpm/xen-tpmfront.txt similarity index 100% rename from Documentation/tpm/xen-tpmfront.txt rename to Documentation/security/tpm/xen-tpmfront.txt -- GitLab From 05d5f95dc7c6a61fb2b2af0935727a6ea61cb0f1 Mon Sep 17 00:00:00 2001 From: Markus Heiser Date: Tue, 1 Nov 2016 15:36:02 +0100 Subject: [PATCH 098/193] 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 fdf8232d0eeb2..263e6577de663 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 -- GitLab From beab6cb20c1dff4a0fb1ee9d14ff5f826ccd2c84 Mon Sep 17 00:00:00 2001 From: Masahiro Yamada Date: Thu, 3 Nov 2016 01:57:34 +0900 Subject: [PATCH 099/193] 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 968808bec4075..3e7905172000c 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: -- GitLab From d55003d86e0ce598b599277973035327779b643b Mon Sep 17 00:00:00 2001 From: Luis de Bethencourt Date: Tue, 1 Nov 2016 15:23:37 +0000 Subject: [PATCH 100/193] 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 8ec4d595b2185..e322691be67eb 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. -- GitLab From 3a5182c04a020e5ba5339c3b393cae0d17b74ef5 Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Thu, 10 Nov 2016 17:37:15 +0100 Subject: [PATCH 101/193] 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 0fa40679b0802..0000000000000 --- 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] -- GitLab From 8551914a5e19094255a0e2aadb24f70736f7ba7d Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 2 Nov 2016 21:30:39 +0100 Subject: [PATCH 102/193] 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 ++ .../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 fdf8232d0eeb2..e173497959fa7 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 53f439dcc94b7..0000000000000 --- 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 c53d089455a42..115c551da5f53 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 0000000000000..280a57115f00e --- /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 0000000000000..14cd138989e35 --- /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 0000000000000..73c13497dec7b --- /dev/null +++ b/Documentation/sound/kernel-api/index.rst @@ -0,0 +1,7 @@ +ALSA Kernel API Documentation +============================= + +.. toctree:: + :maxdepth: 2 + + alsa-driver-api -- GitLab From 7ddedebb03b7ec030c528ebacdd43e45373476e3 Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Thu, 29 Sep 2016 18:21:46 +0200 Subject: [PATCH 103/193] 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 +- .../DocBook/writing-an-alsa-driver.tmpl | 6206 ----------------- Documentation/sound/kernel-api/index.rst | 1 + .../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 e173497959fa7..72f78ae46c102 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 a27ab9f53fb68..0000000000000 --- 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 73c13497dec7b..d0e6df35b4b4d 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 0000000000000..95c5443eff38b --- /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. -- GitLab From 9000d69925ac45dcb346b5ea68e71b83cd897d3d Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 13:01:05 +0100 Subject: [PATCH 104/193] 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/hd-audio/index.rst | 7 + .../{alsa/HD-Audio.txt => hd-audio/notes.rst} | 635 +++++++++--------- Documentation/sound/index.rst | 1 + 3 files changed, 339 insertions(+), 304 deletions(-) create mode 100644 Documentation/sound/hd-audio/index.rst rename Documentation/sound/{alsa/HD-Audio.txt => hd-audio/notes.rst} (61%) diff --git a/Documentation/sound/hd-audio/index.rst b/Documentation/sound/hd-audio/index.rst new file mode 100644 index 0000000000000..f2dc29019f12f --- /dev/null +++ b/Documentation/sound/hd-audio/index.rst @@ -0,0 +1,7 @@ +HD-Audio +======== + +.. toctree:: + :maxdepth: 2 + + notes diff --git a/Documentation/sound/alsa/HD-Audio.txt b/Documentation/sound/hd-audio/notes.rst similarity index 61% rename from Documentation/sound/alsa/HD-Audio.txt rename to Documentation/sound/hd-audio/notes.rst index d4510ebf2e8c5..168d0cfab1cec 100644 --- a/Documentation/sound/alsa/HD-Audio.txt +++ b/Documentation/sound/hd-audio/notes.rst @@ -1,10 +1,12 @@ -MORE NOTES ON HD-AUDIO DRIVER ============================= - Takashi Iwai +More Notes on HD-Audio Driver +============================= +Takashi Iwai -GENERAL -------- + +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 @@ -40,28 +42,28 @@ 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/ +* http://www.intel.com/standards/hdaudio/ -HD-AUDIO CONTROLLER -------------------- +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. +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 +``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, +``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 @@ -74,9 +76,9 @@ 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. +via ``bdl_pos_adj`` option. -When `bdl_pos_adj` is a negative value (as default), it's assigned to +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 @@ -84,19 +86,19 @@ 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 ------------------------------------------------------------------------- +:: + + 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 @@ -108,24 +110,24 @@ 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 +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. +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. +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 +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 @@ -134,17 +136,17 @@ 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 +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 --------------- +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 @@ -153,13 +155,15 @@ 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 @@ -182,32 +186,33 @@ 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 +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. +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, +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 +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 +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 + +* 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 +* 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 @@ -236,23 +241,23 @@ 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 +* 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 +* 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 +* 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 +* 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 @@ -284,7 +289,7 @@ 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 @@ -293,45 +298,45 @@ below. You'd need to enable hwdep for using these tools. See "Kernel Configuration" section. -OTHER ISSUES ------------- +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. +``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 +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_*` +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. +``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 +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 +``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. +``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. @@ -351,161 +356,178 @@ 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. +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 ------------------------------------------------------------------------- +:: + + # 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 +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. +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 +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. +-------------- +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 +:: + + [codec] + 0x12345678 0xabcd1234 2 - [model] - auto + [model] + auto - [pincfg] - 0x12 0x411111f0 + [pincfg] + 0x12 0x411111f0 - [verb] - 0x20 0x500 0x03 - 0x20 0x400 0xff + [verb] + 0x20 0x500 0x03 + 0x20 0x400 0xff - [hint] - jack_detect = no ------------------------------------------------------------------------- + [hint] + jack_detect = no -The file needs to have a line `[codec]`. The next line should contain + +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 @@ -514,66 +536,68 @@ 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. +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. +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` +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 +:: + + [codec] + 0x12345678 0xabcd1234 2 + + [vendor_id] + 0xdeadbeef - [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]``, 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 - [subsystem_id] - 0xffff1111 + [revision_id] + 0x10 - [revision_id] - 0x10 + [chip_name] + My-own NEWS-0002 - [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 +``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 +``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 @@ -592,63 +616,65 @@ 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 +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` +``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 +``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 ------------------------------------------------------------------------- +:: + + # 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 +:: + + # 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 ------------------------------------------------------------------------- +:: + + % 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 +* 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 @@ -657,14 +683,14 @@ 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 +* 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 @@ -673,60 +699,60 @@ 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 +kernel-bugzilla + https://bugzilla.kernel.org/ +alsa-devel ML + alsa-devel@alsa-project.org -DEBUG TOOLS ------------ +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 +--------- +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 +* 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 +* 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. +run with ``--no-upload`` option, and attach the generated file. -There are some other useful options. See `--help` option output for +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 +``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 +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 +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. +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 @@ -739,19 +765,20 @@ 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 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 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 - % 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 @@ -760,22 +787,22 @@ 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 +* 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/ +* 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 +* 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 @@ -784,14 +811,14 @@ proc-compatible output. The hda-analyzer: -- http://git.alsa-project.org/?p=alsa.git;a=tree;f=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 +* 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 @@ -800,11 +827,11 @@ program. The tarball and GIT trees are found in the web page at: -- http://helllabs.org/codecgraph/ +* 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 @@ -817,13 +844,14 @@ 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 - .... ------------------------------------------------------------------------- +:: + + % 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 @@ -832,14 +860,14 @@ 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 +* 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 @@ -849,5 +877,4 @@ firmware patch file (see "Early Patching" section). The program is included in alsa-tools now: -- git://git.alsa-project.org/alsa-tools.git - +* git://git.alsa-project.org/alsa-tools.git diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst index 280a57115f00e..e9bac7c8b893d 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 -- GitLab From a4caad753f0ccc201482bee4bdaa1875524bf2ab Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 14:43:16 +0100 Subject: [PATCH 105/193] 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 ec099d4343f20..0000000000000 --- 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 f2dc29019f12f..1e8376b0066c4 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 0000000000000..5338673c88d95 --- /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) -- GitLab From fe0abd18e1ef3cb258b0a5e41ba26ed0c4b88dab Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 16:56:01 +0100 Subject: [PATCH 106/193] 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 --- .../controls.rst} | 33 +++++++++++-------- Documentation/sound/hd-audio/index.rst | 1 + 2 files changed, 20 insertions(+), 14 deletions(-) rename Documentation/sound/{alsa/HD-Audio-Controls.txt => hd-audio/controls.rst} (92%) diff --git a/Documentation/sound/alsa/HD-Audio-Controls.txt b/Documentation/sound/hd-audio/controls.rst similarity index 92% rename from Documentation/sound/alsa/HD-Audio-Controls.txt rename to Documentation/sound/hd-audio/controls.rst index e9621e349e173..f2ebc4f79b44d 100644 --- a/Documentation/sound/alsa/HD-Audio-Controls.txt +++ b/Documentation/sound/hd-audio/controls.rst @@ -1,16 +1,21 @@ +====================================== +HD-Audio Codec-Specific Mixer Controls +====================================== + + This file explains the codec-specific mixer controls. Realtek codecs -------------- -* Channel Mode +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 +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 @@ -30,24 +35,24 @@ Realtek codecs IDT/Sigmatel codecs ------------------- -* Analog Loopback +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 +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 +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 +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" @@ -57,19 +62,19 @@ IDT/Sigmatel codecs VIA codecs ---------- -* Smart 5.1 +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 +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 +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 @@ -78,7 +83,7 @@ VIA codecs headphones and speakers because there is only one DAC connected to a mixer widget. -* Dynamic Power-Control +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 @@ -86,7 +91,7 @@ VIA codecs doesn't provide a proper jack-detection, this won't work; in such a case, turn this control OFF. -* Jack Detect +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 @@ -96,21 +101,21 @@ VIA codecs Conexant codecs --------------- -* Auto-Mute Mode +Auto-Mute Mode See Reatek codecs. Analog codecs -------------- -* Channel Mode +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 +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 1e8376b0066c4..c6efd55a219f8 100644 --- a/Documentation/sound/hd-audio/index.rst +++ b/Documentation/sound/hd-audio/index.rst @@ -6,3 +6,4 @@ HD-Audio notes models + controls -- GitLab From 76ab4e15158c677141e8b8ff5f0295166f474553 Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Thu, 10 Nov 2016 17:41:45 +0100 Subject: [PATCH 107/193] 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 --- .../dp-mst.rst} | 30 ++++++++++++------- Documentation/sound/hd-audio/index.rst | 1 + 2 files changed, 21 insertions(+), 10 deletions(-) rename Documentation/sound/{alsa/HD-Audio-DP-MST-audio.txt => hd-audio/dp-mst.rst} (69%) diff --git a/Documentation/sound/alsa/HD-Audio-DP-MST-audio.txt b/Documentation/sound/hd-audio/dp-mst.rst similarity index 69% rename from Documentation/sound/alsa/HD-Audio-DP-MST-audio.txt rename to Documentation/sound/hd-audio/dp-mst.rst index 82744ac3513d8..58b72437e6c3e 100644 --- a/Documentation/sound/alsa/HD-Audio-DP-MST-audio.txt +++ b/Documentation/sound/hd-audio/dp-mst.rst @@ -1,3 +1,7 @@ +======================= +HD-Audio DP-MST Support +======================= + To support DP MST audio, HD Audio hdmi codec driver introduces virtual pin and dynamic pcm assignment. @@ -44,10 +48,12 @@ Build Jack ---------- - dyn_pcm_assign -Will not use hda_jack but use snd_jack in spec->pcm_rec[pcm_idx].jack directly. + + 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. + + Use hda_jack and assign spec->pcm_rec[pcm_idx].jack = jack->jack statically. Unsolicited Event Enabling @@ -58,16 +64,20 @@ 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 + + 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. + + 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 c6efd55a219f8..f8a72ffffe66f 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 -- GitLab From f6d23df5cac135e7375f14557b2da959405480b6 Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 15:40:00 +0100 Subject: [PATCH 108/193] 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 +++++++++++++++++ .../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 0000000000000..aed6b4fb8e464 --- /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 fc53ccd9a6293..0000000000000 --- 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 e9bac7c8b893d..64fe47af05b61 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 -- GitLab From afb8fd3c72a9f00018f7335590c173ce4cc2a43d Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 15:52:06 +0100 Subject: [PATCH 109/193] 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/designs/index.rst | 7 ++ .../Procfile.txt => designs/procfile.rst} | 106 +++++++++--------- Documentation/sound/index.rst | 1 + 3 files changed, 63 insertions(+), 51 deletions(-) create mode 100644 Documentation/sound/designs/index.rst rename Documentation/sound/{alsa/Procfile.txt => designs/procfile.rst} (71%) diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst new file mode 100644 index 0000000000000..82d19fe3c3800 --- /dev/null +++ b/Documentation/sound/designs/index.rst @@ -0,0 +1,7 @@ +Designs and Implementations +=========================== + +.. toctree:: + :maxdepth: 2 + + procfile diff --git a/Documentation/sound/alsa/Procfile.txt b/Documentation/sound/designs/procfile.rst similarity index 71% rename from Documentation/sound/alsa/Procfile.txt rename to Documentation/sound/designs/procfile.rst index 7f8a0d3259057..29a466851fd2e 100644 --- a/Documentation/sound/alsa/Procfile.txt +++ b/Documentation/sound/designs/procfile.rst @@ -1,20 +1,22 @@ - Proc Files of ALSA Drivers - ========================== - Takashi Iwai +========================== +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. +card-specific files are stored in the ``card*`` subdirectories. Global Information ------------------- +================== cards Shows the list of currently configured ALSA drivers, @@ -31,15 +33,15 @@ devices meminfo Shows the status of allocated pages via ALSA drivers. - Appears only when CONFIG_SND_DEBUG=y. + 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 @@ -54,23 +56,23 @@ oss/sndstat Card Specific Files -------------------- +=================== -The card-specific files are found in /proc/asound/card* directories. +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 +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 +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 +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#* +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), @@ -81,26 +83,27 @@ details. PCM Proc Files --------------- +============== -card*/pcm*/info +``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. +``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 + 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 + + * 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 @@ -117,72 +120,74 @@ card*/pcm*/xrun_debug buggy) hardware that doesn't give smooth pointer updates. This feature is enabled via the bit 2. -card*/pcm*/sub*/info +``card*/pcm*/sub*/info`` The general information of this PCM sub-stream. -card*/pcm*/sub*/status +``card*/pcm*/sub*/status`` The current status of this PCM sub-stream, elapsed time, H/W position, etc. -card*/pcm*/sub*/hw_params +``card*/pcm*/sub*/hw_params`` The hardware parameters set for this sub-stream. -card*/pcm*/sub*/sw_params +``card*/pcm*/sub*/sw_params`` The soft parameters set for this sub-stream. -card*/pcm*/sub*/prealloc +``card*/pcm*/sub*/prealloc`` The buffer pre-allocation information. -card*/pcm*/sub*/xrun_injection +``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#?-? +``card*/codec97#*/ac97#?-?`` Shows the general information of this AC97 codec chip, such as name, capabilities, set up. -card*/codec97#0/ac97#?-?+regs +``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* +``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#* +``card*/codec#*`` Shows the general codec information and the attribute of each widget node. -card*/eld#* +``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#*`. + 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. @@ -203,7 +208,7 @@ seq/oss 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 @@ -211,24 +216,23 @@ 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) +- 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 +- 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 +- AC97 proc files, ``codec97#*/*`` files for USB audio/midi, - - output of lsusb -v - - stream* files in card directory +- output of ``lsusb -v`` +- ``stream*`` files in card directory The ALSA bug-tracking system is found at: - - https://bugtrack.alsa-project.org/alsa-bug/ +https://bugtrack.alsa-project.org/alsa-bug/ diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst index 64fe47af05b61..e9fbbfff9d0d6 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 -- GitLab From 48e92b488d3c419e11bbf03c56ceb43399ac1901 Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 15:54:47 +0100 Subject: [PATCH 110/193] 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/designs/index.rst | 1 + .../powersave.txt => designs/powersave.rst} | 16 +++++++++------- 2 files changed, 10 insertions(+), 7 deletions(-) rename Documentation/sound/{alsa/powersave.txt => designs/powersave.rst} (76%) diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst index 82d19fe3c3800..362e1c23d51f9 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/alsa/powersave.txt b/Documentation/sound/designs/powersave.rst similarity index 76% rename from Documentation/sound/alsa/powersave.txt rename to Documentation/sound/designs/powersave.rst index 9657e8099228d..138157452eb92 100644 --- a/Documentation/sound/alsa/powersave.txt +++ b/Documentation/sound/designs/powersave.rst @@ -1,9 +1,10 @@ +========================== 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. +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 @@ -11,20 +12,21 @@ 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 +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 +``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 +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): +``/sys/modules/snd_ac97_codec/parameters/power_save`` (usually as root): +:: # echo 10 > /sys/modules/snd_ac97_codec/parameters/power_save -- GitLab From efe541c230e41106ce912e096e19518630e810db Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 16:05:18 +0100 Subject: [PATCH 111/193] ALSA: doc: ReSTize Channel-Mapping-API document A simple conversion from a text file. Put to designs subdirectory. Signed-off-by: Takashi Iwai --- .../channel-mapping-api.rst} | 77 +++++++++++-------- Documentation/sound/designs/index.rst | 1 + 2 files changed, 45 insertions(+), 33 deletions(-) rename Documentation/sound/{alsa/Channel-Mapping-API.txt => designs/channel-mapping-api.rst} (75%) diff --git a/Documentation/sound/alsa/Channel-Mapping-API.txt b/Documentation/sound/designs/channel-mapping-api.rst similarity index 75% rename from Documentation/sound/alsa/Channel-Mapping-API.txt rename to Documentation/sound/designs/channel-mapping-api.rst index 3c43d1a4ca0ea..58e6312a43c00 100644 --- a/Documentation/sound/alsa/Channel-Mapping-API.txt +++ b/Documentation/sound/designs/channel-mapping-api.rst @@ -1,9 +1,11 @@ +============================ ALSA PCM channel-mapping API ============================ - Takashi Iwai -GENERAL -------- +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 @@ -11,9 +13,9 @@ 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 } +``{ front_left, front_right }`` while a 4.0 surround PCM stream has a channel map of - { front left, front right, rear left, rear right }. +``{ 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 @@ -29,8 +31,8 @@ specification. These are the main motivations for the new channel mapping API. -DESIGN ------- +Design +====== Actually, "the channel mapping API" doesn't introduce anything new in the kernel/user-space ABI perspective. It uses only the existing @@ -39,10 +41,11 @@ 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 + +* 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. @@ -50,32 +53,35 @@ 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 +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... +``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 +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 +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. +These new TLV types are defined in ``sound/tlv.h``. -The available channel position values are defined in sound/asound.h, +The available channel position values are defined in ``sound/asound.h``, here is a cut: -/* channel positions */ -enum { +:: + + /* channel positions */ + enum { SNDRV_CHMAP_UNKNOWN = 0, SNDRV_CHMAP_NA, /* N/A, silent */ SNDRV_CHMAP_MONO, /* mono stream */ @@ -107,11 +113,13 @@ enum { 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 @@ -120,19 +128,21 @@ to be returned will contain such as: 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) + #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, +``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 +When ``SNDRV_CHMAP_DRIVER_SPEC`` is set, all the channel position values don't follow the standard definition above but driver-specific. -* READ OPERATION +Read Operation +-------------- The control read operation is for providing the current channel map of the given stream. The control element returns an integer array @@ -140,9 +150,10 @@ 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. +``UNKNOWN``. -* WRITE OPERATION +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 diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst index 362e1c23d51f9..dd4fcbcb2b923 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 -- GitLab From 0c266c4b707e263ac74e0bd4330b4193fa46c434 Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 16:18:14 +0100 Subject: [PATCH 112/193] ALSA: doc: ReSTize OSS-Emulation document A simple conversion from a text file. Put to designs subdirectory. Signed-off-by: Takashi Iwai --- Documentation/sound/designs/index.rst | 1 + .../oss-emulation.rst} | 169 +++++++++++------- 2 files changed, 101 insertions(+), 69 deletions(-) rename Documentation/sound/{alsa/OSS-Emulation.txt => designs/oss-emulation.rst} (70%) diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst index dd4fcbcb2b923..5b3033c556d00 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/alsa/OSS-Emulation.txt b/Documentation/sound/designs/oss-emulation.rst similarity index 70% rename from Documentation/sound/alsa/OSS-Emulation.txt rename to Documentation/sound/designs/oss-emulation.rst index 152ca2a3f1bd9..e8dcb9633e7b7 100644 --- a/Documentation/sound/alsa/OSS-Emulation.txt +++ b/Documentation/sound/designs/oss-emulation.rst @@ -1,7 +1,8 @@ - NOTES ON KERNEL OSS-EMULATION - ============================= +============================= +Notes on Kernel OSS-Emulation +============================= - Jan. 22, 2004 Takashi Iwai +Jan. 22, 2004 Takashi Iwai Modules @@ -14,18 +15,18 @@ 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 +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 +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. +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 +``alias sound-slot-0 snd-card-0`` doesn't work any more like the old modutils). The currently available OSS configuration is shown in @@ -42,6 +43,7 @@ Device Mapping ============== ALSA supports the following OSS device files: +:: PCM: /dev/dspX @@ -61,48 +63,55 @@ ALSA supports the following OSS device files: 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.) +/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 +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) +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, +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) +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 @@ -118,43 +127,52 @@ 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 +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 +``app_name`` is the name of application with (higher priority) or without path. -fragments specifies the number of fragments or zero if no specific +``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 +``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 +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 +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 @@ -171,10 +189,11 @@ 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. +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 @@ -183,15 +202,18 @@ 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 +Also, for clearing all the current configuration, send ``erase`` command as below: +:: % echo "erase" > /proc/asound/card0/pcm0p/oss @@ -211,40 +233,43 @@ 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 +==================== ===================== ===== +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. +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 @@ -261,6 +286,7 @@ 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 @@ -284,12 +310,18 @@ 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. @@ -302,4 +334,3 @@ 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. - -- GitLab From 07aecc06eb32ff0010dff69438806b6f200fc1fd Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 16:46:02 +0100 Subject: [PATCH 113/193] 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 9663b45f6fde6..0000000000000 --- 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 5b3033c556d00..0ca3a6b0a5ce6 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 0000000000000..e82ffe0e7f436
--- /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.
+
-- 
GitLab


From 5a481fe309e79df2e713d7ea32175f121b251069 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Wed, 9 Nov 2016 17:55:28 +0100
Subject: [PATCH 114/193] 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 3fc1cf50d28e1..0000000000000
--- 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 0000000000000..7fedd0f33cd97
--- /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 0ca3a6b0a5ce6..e53a5fac0acf8 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
-- 
GitLab


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

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

Signed-off-by: Takashi Iwai 
---
 .../compress-offload.rst}                     | 127 ++++++++++--------
 Documentation/sound/designs/index.rst         |   1 +
 2 files changed, 70 insertions(+), 58 deletions(-)
 rename Documentation/sound/{alsa/compress_offload.txt => designs/compress-offload.rst} (73%)

diff --git a/Documentation/sound/alsa/compress_offload.txt b/Documentation/sound/designs/compress-offload.rst
similarity index 73%
rename from Documentation/sound/alsa/compress_offload.txt
rename to Documentation/sound/designs/compress-offload.rst
index 8ba556a131c37..ad4bfbdacc835 100644
--- a/Documentation/sound/alsa/compress_offload.txt
+++ b/Documentation/sound/designs/compress-offload.rst
@@ -1,10 +1,14 @@
-		compress_offload.txt
-		=====================
-	Pierre-Louis.Bossart 
-		Vinod Koul 
+=========================
+ALSA Compress-Offload API
+=========================
+
+Pierre-Louis.Bossart 
+
+Vinod Koul 
 
-Overview
 
+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
@@ -27,8 +31,9 @@ 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
 
+Requirements
+============
 The main requirements are:
 
 - separation between byte counts and time. Compressed formats may have
@@ -63,7 +68,7 @@ The main requirements are:
   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
+- 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
@@ -72,7 +77,7 @@ The main requirements are:
 
 
 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.
@@ -95,43 +100,44 @@ 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.
+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.
@@ -145,6 +151,7 @@ Modifications include:
 - 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
@@ -162,19 +169,19 @@ 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_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
+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
+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
@@ -189,10 +196,12 @@ Sequence flow for gapless would be:
 - 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:
 
+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.
@@ -225,7 +234,9 @@ Not supported:
   rendered output in time, this does not deal with underrun/overrun and
   maybe dealt in user-library
 
-Credits:
+
+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
diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst
index e53a5fac0acf8..f7ca11307033c 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
-- 
GitLab


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

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

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/designs/index.rst         |   1 +
 .../timestamping.rst}                         | 143 ++++++++++--------
 2 files changed, 80 insertions(+), 64 deletions(-)
 rename Documentation/sound/{alsa/timestamping.txt => designs/timestamping.rst} (56%)

diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst
index f7ca11307033c..798b1a44bbbd6 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/alsa/timestamping.txt b/Documentation/sound/designs/timestamping.rst
similarity index 56%
rename from Documentation/sound/alsa/timestamping.txt
rename to Documentation/sound/designs/timestamping.rst
index 9d579aefbffd4..2b0fff5034151 100644
--- a/Documentation/sound/alsa/timestamping.txt
+++ b/Documentation/sound/designs/timestamping.rst
@@ -1,18 +1,22 @@
+=====================
+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.
+  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.
+  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
@@ -22,15 +26,15 @@ 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.
+- ``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
+``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
 
 
@@ -38,17 +42,18 @@ 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---->|
 
---------------------------------------------------------------> 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
@@ -113,11 +118,11 @@ 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
+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
+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.
+``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
@@ -135,36 +140,42 @@ 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
+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
+::
+
+  $ ./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
+::
+
+  $ ./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
+::
+
+  $ ./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
@@ -181,20 +192,24 @@ 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
+::
+
+  $ ./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
+::
+
+  $ ./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
-- 
GitLab


From df3a57105c04a7bfe0874316a9e6ec968c35a6f5 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 11:10:35 +0100
Subject: [PATCH 117/193] 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/designs/index.rst               |  1 +
 .../Jack-Controls.txt => designs/jack-controls.rst} | 13 +++++++++----
 2 files changed, 10 insertions(+), 4 deletions(-)
 rename Documentation/sound/{alsa/Jack-Controls.txt => designs/jack-controls.rst} (86%)

diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst
index 798b1a44bbbd6..04dcdae3e4f2a 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/alsa/Jack-Controls.txt b/Documentation/sound/designs/jack-controls.rst
similarity index 86%
rename from Documentation/sound/alsa/Jack-Controls.txt
rename to Documentation/sound/designs/jack-controls.rst
index fe1c5e0c8555e..ae25b1531bb0c 100644
--- a/Documentation/sound/alsa/Jack-Controls.txt
+++ b/Documentation/sound/designs/jack-controls.rst
@@ -1,3 +1,7 @@
+==================
+ALSA Jack Controls
+==================
+
 Why we need Jack kcontrols
 ==========================
 
@@ -29,11 +33,12 @@ How to use jack kcontrols
 =========================
 
 In order to keep compatibility, snd_jack_new() has been modified by
-adding two params :-
+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.
+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
-- 
GitLab


From f59c3c6d87d6f7e1593ca874b755265cf08f8714 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Wed, 9 Nov 2016 17:04:22 +0100
Subject: [PATCH 118/193] 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/cards/index.rst           |  7 ++
 .../{alsa/Joystick.txt => cards/joystick.rst} | 71 ++++++++++---------
 Documentation/sound/index.rst                 |  1 +
 3 files changed, 46 insertions(+), 33 deletions(-)
 create mode 100644 Documentation/sound/cards/index.rst
 rename Documentation/sound/{alsa/Joystick.txt => cards/joystick.rst} (56%)

diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
new file mode 100644
index 0000000000000..e1f4b78c75d66
--- /dev/null
+++ b/Documentation/sound/cards/index.rst
@@ -0,0 +1,7 @@
+Card-Specific Information
+=========================
+
+.. toctree::
+   :maxdepth: 2
+
+   joystick
diff --git a/Documentation/sound/alsa/Joystick.txt b/Documentation/sound/cards/joystick.rst
similarity index 56%
rename from Documentation/sound/alsa/Joystick.txt
rename to Documentation/sound/cards/joystick.rst
index ccda41b10f8a3..a6e468c81d02f 100644
--- a/Documentation/sound/alsa/Joystick.txt
+++ b/Documentation/sound/cards/joystick.rst
@@ -1,7 +1,10 @@
+=======================================
 Analog Joystick Support on ALSA Drivers
 =======================================
-                          Oct. 14, 2003
-           Takashi Iwai 
+
+Oct. 14, 2003
+
+Takashi Iwai 
 
 General
 -------
@@ -34,44 +37,46 @@ 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
+==============	=============	============================================
+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
-    -----------------------------
+=======	=================
+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.
+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"
diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst
index e9fbbfff9d0d6..1f5d166f81c4c 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
 
-- 
GitLab


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

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

Signed-off-by: Takashi Iwai 
---
 .../{alsa/CMIPCI.txt => cards/cmipci.rst}     | 62 ++++++++++++-------
 Documentation/sound/cards/index.rst           |  1 +
 2 files changed, 41 insertions(+), 22 deletions(-)
 rename Documentation/sound/{alsa/CMIPCI.txt => cards/cmipci.rst} (86%)

diff --git a/Documentation/sound/alsa/CMIPCI.txt b/Documentation/sound/cards/cmipci.rst
similarity index 86%
rename from Documentation/sound/alsa/CMIPCI.txt
rename to Documentation/sound/cards/cmipci.rst
index 4e36e6e809cab..9ea1de6ec4ce6 100644
--- a/Documentation/sound/alsa/CMIPCI.txt
+++ b/Documentation/sound/cards/cmipci.rst
@@ -1,7 +1,8 @@
-         Brief Notes on C-Media 8338/8738/8768/8770 Driver
-         =================================================
+=================================================
+Brief Notes on C-Media 8338/8738/8768/8770 Driver
+=================================================
 
-                   Takashi Iwai 
+Takashi Iwai 
 
 
 Front/Rear Multi-channel Playback
@@ -30,19 +31,20 @@ 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 ***
+.. 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
+
+.. [#]
+  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... ]
+  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
@@ -73,12 +75,14 @@ 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
@@ -89,13 +93,15 @@ 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
+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
+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
@@ -111,11 +117,14 @@ 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.
@@ -140,31 +149,40 @@ 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
+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)
+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
+IEC958 Loop
+	SPDIF input data is loop back into SPDIF
 	output (aka bypass)
 
-"IEC958 Copyright"  - Set the copyright bit.
+IEC958 Copyright
+	Set the copyright bit.
 
-"IEC958 5V"         - Select 0.5V (coax) or 5V (optical) interface.
+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 Monitor
+	SPDIF input is routed to DAC.
 
-"IEC958 In Phase Inverse" - Set SPDIF input format as inverse.
+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.
+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.
@@ -217,7 +235,7 @@ to enable MIDI support.  Valid I/O ports are 0x300, 0x310, 0x320 and
 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
+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
diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index e1f4b78c75d66..67a3073157b91 100644
--- a/Documentation/sound/cards/index.rst
+++ b/Documentation/sound/cards/index.rst
@@ -5,3 +5,4 @@ Card-Specific Information
    :maxdepth: 2
 
    joystick
+   cmipci
-- 
GitLab


From ecef1481d516e004a38d9472c403205dcdd1491e Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 16:17:56 +0100
Subject: [PATCH 120/193] 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/cards/index.rst           |   1 +
 .../sb-live-mixer.rst}                        | 337 +++++++++---------
 2 files changed, 178 insertions(+), 160 deletions(-)
 rename Documentation/sound/{alsa/SB-Live-mixer.txt => cards/sb-live-mixer.rst} (54%)

diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index 67a3073157b91..294efdb75bc97 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/alsa/SB-Live-mixer.txt b/Documentation/sound/cards/sb-live-mixer.rst
similarity index 54%
rename from Documentation/sound/alsa/SB-Live-mixer.txt
rename to Documentation/sound/cards/sb-live-mixer.rst
index f4b5988f450cf..bcb62fc99bbb7 100644
--- a/Documentation/sound/alsa/SB-Live-mixer.txt
+++ b/Documentation/sound/cards/sb-live-mixer.rst
@@ -1,6 +1,6 @@
-
-		Sound Blaster Live mixer / default DSP code
-		===========================================
+===========================================
+Sound Blaster Live mixer / default DSP code
+===========================================
 
 
 The EMU10K1 chips have a DSP part which can be programmed to support
@@ -12,8 +12,8 @@ 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
---------------------------
+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
@@ -27,8 +27,8 @@ at the time.
 Look to tram_poke routines in lowlevel/emu10k1/emufx.c for more details.
 
 
-2) Digital mixer controls
--------------------------
+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
@@ -40,317 +40,334 @@ is mentioned in multiple controls, the signal is accumulated and can be wrapped
 
 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
-
+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
-
+``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
-
+``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
-
+``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
-
+``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
-
+``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
-
+``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
-
+``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
-
+``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
-
+``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
-
+``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
-
+``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
+.. 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
+.. 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
-
+``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
-
+``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
-
+``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
-
+``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
-
+``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
-
+``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
-
+``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
-
+``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
-
+``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
-
+``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
-
+``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
-
+``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
-
+``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
-
+``name='Headphone Playback Volume',index=1``
+--------------------------------------------
 This control attenuates the samples for the headphone output.
 
-name='Headphone Center Playback Switch',index=1
-
+``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
-
+``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
+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
+* 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
+*  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
-
+``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)
+*  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:
--------------------
+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
+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 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)
+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
+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)
-- 
GitLab


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

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

Signed-off-by: Takashi Iwai 
---
 .../audigy-mixer.rst}                         | 297 ++++++++++--------
 Documentation/sound/cards/index.rst           |   2 +
 2 files changed, 162 insertions(+), 137 deletions(-)
 rename Documentation/sound/{alsa/Audigy-mixer.txt => cards/audigy-mixer.rst} (57%)

diff --git a/Documentation/sound/alsa/Audigy-mixer.txt b/Documentation/sound/cards/audigy-mixer.rst
similarity index 57%
rename from Documentation/sound/alsa/Audigy-mixer.txt
rename to Documentation/sound/cards/audigy-mixer.rst
index 7f10dc6ff28ca..86213234435fe 100644
--- a/Documentation/sound/alsa/Audigy-mixer.txt
+++ b/Documentation/sound/cards/audigy-mixer.rst
@@ -1,8 +1,8 @@
+=============================================
+Sound Blaster Audigy mixer / default DSP code
+=============================================
 
-		Sound Blaster Audigy mixer / default DSP code
-		===========================================
-
-This is based on SB-Live-mixer.txt.
+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.
@@ -13,8 +13,8 @@ The ALSA driver programs this portion of chip by default code
 (can be altered later) which offers the following functionality:
 
 
-1) Digital mixer controls
--------------------------
+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
@@ -26,320 +26,343 @@ is mentioned in multiple controls, the signal is accumulated and can be wrapped
 
 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.
+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
-------------------------------
+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)
+* 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
+* 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:
--------------------
+*  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
 -------------------------------------
 
-        Files:
-        LM4545.pdf      AC97 Codec
+LM4545.pdf
+	AC97 Codec
 
-        m2049.pdf       The EMU10K1 Digital Audio Processor
+m2049.pdf
+	The EMU10K1 Digital Audio Processor
 
-        hog63.ps        FX8010 - A DSP Chip Architecture for Audio Effects
+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 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)
+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
+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 294efdb75bc97..c9d7ce4286b2f 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
+  
-- 
GitLab


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

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

Signed-off-by: Takashi Iwai 
---
 .../emu10k1-jack.rst}                         | 20 +++++++++++--------
 Documentation/sound/cards/index.rst           |  2 +-
 2 files changed, 13 insertions(+), 9 deletions(-)
 rename Documentation/sound/{alsa/emu10k1-jack.txt => cards/emu10k1-jack.rst} (89%)

diff --git a/Documentation/sound/alsa/emu10k1-jack.txt b/Documentation/sound/cards/emu10k1-jack.rst
similarity index 89%
rename from Documentation/sound/alsa/emu10k1-jack.txt
rename to Documentation/sound/cards/emu10k1-jack.rst
index 751d45036a05a..6597f1ea83f01 100644
--- a/Documentation/sound/alsa/emu10k1-jack.txt
+++ b/Documentation/sound/cards/emu10k1-jack.rst
@@ -1,3 +1,7 @@
+=================================================================
+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 
@@ -7,8 +11,6 @@ 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
@@ -23,14 +25,15 @@ 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
+  /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).
+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
@@ -49,10 +52,11 @@ 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 (& 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)	
@@ -69,6 +73,6 @@ 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 c9d7ce4286b2f..251f1d7675f75 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
-- 
GitLab


From 312c01b1736e81fe0d23217fe537d415785256d2 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 16:32:49 +0100
Subject: [PATCH 123/193] 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 1b0ac06ba95db..0000000000000
--- 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 251f1d7675f75..4fcb88049cccc 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 0000000000000..6ee993d4535be
--- /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.
-- 
GitLab


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

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

Signed-off-by: Takashi Iwai 
---
 .../audiophile-usb.rst}                       | 258 +++++++++++++-----
 Documentation/sound/cards/index.rst           |   1 +
 2 files changed, 184 insertions(+), 75 deletions(-)
 rename Documentation/sound/{alsa/Audiophile-Usb.txt => cards/audiophile-usb.rst} (81%)

diff --git a/Documentation/sound/alsa/Audiophile-Usb.txt b/Documentation/sound/cards/audiophile-usb.rst
similarity index 81%
rename from Documentation/sound/alsa/Audiophile-Usb.txt
rename to Documentation/sound/cards/audiophile-usb.rst
index e7a5ed4dcae86..a7bb5648331fd 100644
--- a/Documentation/sound/alsa/Audiophile-Usb.txt
+++ b/Documentation/sound/cards/audiophile-usb.rst
@@ -1,32 +1,41 @@
-	Guide to using M-Audio Audiophile USB with ALSA and Jack	v1.5
-	========================================================
+========================================================
+Guide to using M-Audio Audiophile USB with ALSA and Jack
+========================================================
 
-	    Thibault Le Meur 
+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
+
+  - 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
+  - Added AC3/DTS passthru info
 
 
-1 - Audiophile USB Specs and correct usage
-==========================================
+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)
@@ -34,56 +43,69 @@ The device has 4 audio interfaces, and 2 MIDI ports:
  * 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"
+  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
+   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
+   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
+   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
+     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)
+     synchronization error (for instance sound played at an odd sample rate)
 
 
-2 - Audiophile USB MIDI support in ALSA
-=======================================
+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
-========================================
+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".
+``device_setup``.
 
-3.1 - Default Alsa driver mode
-------------------------------
+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 
@@ -101,6 +123,7 @@ 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
@@ -115,20 +138,28 @@ 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
+
+ * 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
+
+ * 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
+
+ * 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
+
+ * 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
----------------------------
+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 
@@ -137,34 +168,39 @@ 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
+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
+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
+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
+16-bit modes
+~~~~~~~~~~~~
 
 The two supported modes are:
 
- * device_setup=0x01
+ * ``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
+ * ``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
@@ -173,33 +209,43 @@ The two supported modes are:
 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
+
+24-bit modes
+~~~~~~~~~~~~
 
 The three supported modes are:
 
- * device_setup=0x09
+ * ``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
+ * ``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
+ * ``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
@@ -210,29 +256,35 @@ The three supported modes are:
 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
+AC3 w/ DTS passthru mode
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 Thanks to Hakan Lennestal, I now have a report saying that this mode works.
 
- * device_setup=0x03
+ * ``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
-----------------------------------------------
+How to use the ``device_setup`` parameter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The parameter can be given:
 
- * By manually probing the device (as root):
+ * 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:
+   (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
 
@@ -250,26 +302,31 @@ CAUTION when initializing the device
  * 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
+     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
--------------------------------------
+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
+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|
@@ -278,38 +335,55 @@ The device_setup is one byte long and its structure is the following:
        +---+---+---+---+---+---+---+---+
 
 Where:
- * b0 is the "SET" bit
+
+ * b0 is the ``SET`` bit
+
    - it MUST be set if device_setup is initialized 
- * b1 is the "DTS" bit
+
+ * 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
+
+   - 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
+
+   - 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 
+
+   - 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"
+
+ * 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
+USB implementation details for this device
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You may safely skip this section if you're not interested in driver 
 hacking.
@@ -319,46 +393,72 @@ 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
+
+* 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
+
+* AltSettings 2 corresponds to
+
   - 24-bit depth, 8-48kHz sample mode
   - Asynch capture and playback  (Ao,Ai,Do,Di)
- * AltSettings 3 corresponds to
+
+* AltSettings 3 corresponds to
+
   - 24-bit depth, 8-48kHz sample mode
   - Synch capture (Ai) and Adaptive playback (Ao,Do)
- * AltSettings 4 corresponds to
+
+* AltSettings 4 corresponds to
+
   - 16-bit depth, 8-48kHz sample mode
   - Asynch capture and playback  (Ao,Ai,Do,Di)
- * AltSettings 5 corresponds to
+
+* AltSettings 5 corresponds to
+
   - 16-bit depth, 8-48kHz sample mode
   - Synch capture (Ai) and Adaptive playback (Ao,Do)
- * AltSettings 6 corresponds to
+
+* 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:
+*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
@@ -371,20 +471,21 @@ _must_know_ how the device will be used:
 
 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 
+``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
-===================================
+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
------------------------------
+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 
@@ -396,29 +497,35 @@ 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
------------------------
+Using Alsa plughw
+-----------------
+
 If you don't have a recent Jackd installed, you can downgrade to using
-the Alsa "plug" converter.
+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."
+  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
-------------------------------------------------------
+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)
@@ -432,6 +539,7 @@ 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
diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index 4fcb88049cccc..e92a4f7e86fc0 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
-- 
GitLab


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

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

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/cards/index.rst           |  1 +
 .../{alsa/MIXART.txt => cards/mixart.rst}     | 26 +++++++++++++------
 2 files changed, 19 insertions(+), 8 deletions(-)
 rename Documentation/sound/{alsa/MIXART.txt => cards/mixart.rst} (83%)

diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index e92a4f7e86fc0..0006bc547bb8d 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/alsa/MIXART.txt b/Documentation/sound/cards/mixart.rst
similarity index 83%
rename from Documentation/sound/alsa/MIXART.txt
rename to Documentation/sound/cards/mixart.rst
index 4ee35b4fbe4a1..48aba98b088fa 100644
--- a/Documentation/sound/alsa/MIXART.txt
+++ b/Documentation/sound/cards/mixart.rst
@@ -1,5 +1,8 @@
-    Alsa driver for Digigram miXart8 and miXart8AES/EBU soundcards
-	    Digigram 
+==============================================================
+Alsa driver for Digigram miXart8 and miXart8AES/EBU soundcards
+==============================================================
+
+Digigram 
 
 
 GENERAL
@@ -48,11 +51,15 @@ 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.
+ 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
@@ -79,11 +86,14 @@ FIRMWARE
 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.)
+/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
-- 
GitLab


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

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

Signed-off-by: Takashi Iwai 
---
 .../sound/{alsa/Bt87x.txt => cards/bt87x.rst} | 23 +++++++++++--------
 Documentation/sound/cards/index.rst           |  1 +
 2 files changed, 15 insertions(+), 9 deletions(-)
 rename Documentation/sound/{alsa/Bt87x.txt => cards/bt87x.rst} (82%)

diff --git a/Documentation/sound/alsa/Bt87x.txt b/Documentation/sound/cards/bt87x.rst
similarity index 82%
rename from Documentation/sound/alsa/Bt87x.txt
rename to Documentation/sound/cards/bt87x.rst
index f158cde8b065a..912732d3ef9e2 100644
--- a/Documentation/sound/alsa/Bt87x.txt
+++ b/Documentation/sound/cards/bt87x.rst
@@ -1,18 +1,23 @@
+=================
+ALSA BT87x Driver
+=================
+
 Intro
 =====
 
 You might have noticed that the bt878 grabber cards have actually
-_two_ PCI functions:
+*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)
-[ ... ]
+  $ 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
+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...
@@ -30,9 +35,9 @@ 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
+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
+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
diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index 0006bc547bb8d..157372faae068 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
-- 
GitLab


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

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

Signed-off-by: Takashi Iwai 
---
 Documentation/sound/cards/index.rst           |   1 +
 .../{alsa/README.maya44 => cards/maya44.rst}  | 137 ++++++++++--------
 2 files changed, 81 insertions(+), 57 deletions(-)
 rename Documentation/sound/{alsa/README.maya44 => cards/maya44.rst} (65%)

diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index 157372faae068..6c8e4141df9a2 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/alsa/README.maya44 b/Documentation/sound/cards/maya44.rst
similarity index 65%
rename from Documentation/sound/alsa/README.maya44
rename to Documentation/sound/cards/maya44.rst
index 67b2ea1cc31dc..bf09a584b4431 100644
--- a/Documentation/sound/alsa/README.maya44
+++ b/Documentation/sound/cards/maya44.rst
@@ -1,10 +1,18 @@
-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
+=================================
+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:
+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).
@@ -44,16 +52,17 @@ Things that do not seem to work:
 - 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:
+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
+* 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.
@@ -62,25 +71,26 @@ This is done in maya44.c, mainly because some of the WM8776 controls are used in
 
 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
+* 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:
+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.
 
@@ -98,66 +108,79 @@ I propose some additional code for limiting the sampling rate when setting on a
 The proposed code (currently deactivated) is in ice1712.h.patch, ice1724.c and maya44.c (in pci/ice1712).
 
 
-SOUND DEVICES:
+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)
+* 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:
+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
+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.
 
-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).
+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.
 
-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
 
-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.
 
-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:
-
+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
+    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.
 
-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
+PCM out
+	DAC output of the corresponding channel (default setting)
+Input 1 ... Input 4
+	direct routing from ADC output of the selected input channel
 
-- 
GitLab


From c79b5bb0a36f6290d38d9a4dc126cff5c7f44f2a Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 17:20:32 +0100
Subject: [PATCH 128/193] 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 
---
 .../sound/{alsa/hdspm.txt => cards/hdspm.rst} | 253 ++++++++++--------
 Documentation/sound/cards/index.rst           |   1 +
 2 files changed, 136 insertions(+), 118 deletions(-)
 rename Documentation/sound/{alsa/hdspm.txt => cards/hdspm.rst} (56%)

diff --git a/Documentation/sound/alsa/hdspm.txt b/Documentation/sound/cards/hdspm.rst
similarity index 56%
rename from Documentation/sound/alsa/hdspm.txt
rename to Documentation/sound/cards/hdspm.rst
index 7ba31948dea72..5373e51ed076f 100644
--- a/Documentation/sound/alsa/hdspm.txt
+++ b/Documentation/sound/cards/hdspm.rst
@@ -1,21 +1,24 @@
+=======================================
 Software Interface ALSA-DSP MADI Driver 
+=======================================
 
 (translated from German, so no good English ;-), 
-2004 - winfried ritsch
-
 
+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.
 
+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:
 
+Hardware functionality
+======================
    
-   Audio transmission:
+Audio transmission
+------------------
 
-     number of channels --  depends on transmission mode
+* 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,
@@ -23,31 +26,34 @@ Software Interface ALSA-DSP MADI Driver
 		allocated. So also the throughput of the PCI system can be
 		scaled. (Only important for low performance boards).
 
-       Single Speed -- 1..64 channels 
+* 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
+* 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 
+* Quad Speed -- 1..16 channels 
 
-		 Note: Choosing the 56-channel mode for
+.. 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)
+* Format -- signed 32 Bit Little Endian (SNDRV_PCM_FMTBIT_S32_LE)
 
-     Sample Rates --
+* Sample Rates --
 
        Single Speed -- 32000, 44100, 48000
 
@@ -55,14 +61,13 @@ Software Interface ALSA-DSP MADI Driver
 
        Quad Speed -- 128000, 176400, 192000 (untested)
 
-     access-mode -- MMAP (memory mapped), Not interleaved
-     (PCM_NON-INTERLEAVED)
+* access-mode -- MMAP (memory mapped), Not interleaved (PCM_NON-INTERLEAVED)
 
-     buffer-sizes -- 64,128,256,512,1024,2048,8192 Samples
+* buffer-sizes -- 64,128,256,512,1024,2048,8192 Samples
 
-     fragments -- 2
+* fragments -- 2
 
-     Hardware-pointer -- 2 Modi
+* Hardware-pointer -- 2 Modi
 
 
 		 The Card supports the readout of the actual Buffer-pointer,
@@ -74,53 +79,54 @@ Software Interface ALSA-DSP MADI Driver
 		 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
+   * Precise Pointer -- off
 					interrupt used for pointer-calculation
-
-       Precise Pointer -- on
+				
+   * Precise Pointer -- on
 					hardware pointer used.
 
-   Controller:
-
+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. 
+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 !!!
+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"
+* System Clock -- suspended !!!!
 
-        Access -- Read Write
-
-        Values -- "Master" "Slave"
+  * 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
@@ -128,106 +134,107 @@ Software Interface ALSA-DSP MADI Driver
 		  a studio should have working synchronisations setup. So use
 		  Clock-source-controller instead !!!!
 
-    Clock Source  
+* Clock Source  
 
-       Name -- "Sample Clock Source"
+  * Name -- "Sample Clock Source"
 
-       Access -- Read Write
+  * 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"
+  * 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
+* Preferred Sync Ref
 
-       Name -- "Preferred Sync Reference"
+  * Name -- "Preferred Sync Reference"
 
-       Access -- Read Write
+  * Access -- Read Write
 
-       Values -- "Word" "MADI"
+  * 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 --- 
+* TX 64 channel
 
-       Name -- "TX 64 channels mode"
+  * Name -- "TX 64 channels mode"
 
-       Access -- Read Write
+  * Access -- Read Write
 
-       Values -- 0 1
+  * 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 ---
+* Clear TMS
 
-       Name -- "Clear Track Marker"
+  * Name -- "Clear Track Marker"
 
-       Access -- Read Write
+  * Access -- Read Write
 
-       Values -- 0 1
+  * Values -- 0 1
 
 
 		 Don't use to lower 5 Audio-bits on AES as additional Bits.
         
 
-    Safe Mode oder Auto Input --- 
+* Safe Mode oder Auto Input
 
-       Name -- "Safe Mode"
+  * Name -- "Safe Mode"
 
-       Access -- Read Write
+  * Access -- Read Write
 
-       Values -- 0 1
-
-       (default on)
+  * 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 --- 
+* Input
 
-       Name -- "Input Select"
+  * Name -- "Input Select"
 
-       Access -- Read Write
+  * Access -- Read Write
 
-       Values -- optical coaxial
+  * Values -- optical coaxial
 
 
 		 Choosing the Input, optical or coaxial. If Safe-mode is active,
 		 this is the preferred Input.
 
--------------- Mixer ----------------------
+Mixer
+-----
 
-    Mixer
+* Mixer
 
-       Name -- "Mixer"
+  * Name -- "Mixer"
 
-       Access -- Read Write
+  * Access -- Read Write
 
-       Values -  
+  * Values -  
 
 
 		 Here as a first value the channel-index is taken to get/set the
@@ -235,40 +242,41 @@ Software Interface ALSA-DSP MADI Driver
 		 fader and 64-127 the playback to outputs fader. Value 0
 		 is channel muted 0 and 32768 an amplification of  1.
 
-    Chn 1-64
+* Chn 1-64
 
        fast mixer for the ALSA-mixer utils. The diagonal of the
        mixer-matrix is implemented from playback to output.
        
 
-    Line Out
+* Line Out
 
-       Name  -- "Line Out"
+  * Name  -- "Line Out"
 
-       Access -- Read Write
+  * Access -- Read Write
 
-       Values -- 0 1
+  * 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):
+Information (only read access)
+------------------------------
  
-    Sample Rate
+* Sample Rate
 
-       Name -- "System Sample Rate"
+  * Name -- "System Sample Rate"
 
-       Access -- Read-only
+  * Access -- Read-only
 
 		 getting the sample rate.
 
 
-    External Rate measured
+* External Rate measured
 
-       Name -- "External Rate"
+  * Name -- "External Rate"
 
-       Access -- Read only
+  * Access -- Read only
 
 
 		 Should be "Autosync Rate", but Name used is
@@ -276,79 +284,86 @@ Software Interface ALSA-DSP MADI Driver
 		 reported.
 
 
-    MADI Sync Status
+* MADI Sync Status
 
-       Name -- "MADI Sync Lock Status"
+  * Name -- "MADI Sync Lock Status"
 
-       Access -- Read
+  * Access -- Read
 
-       Values -- 0,1,2
+  * Values -- 0,1,2
 
        MADI-Input is 0=Unlocked, 1=Locked, or 2=Synced.
 
 
-    Word Clock Sync Status
+* Word Clock Sync Status
 
-       Name -- "Word Clock Lock Status"
+  * Name -- "Word Clock Lock Status"
 
-       Access -- Read
+  * Access -- Read
 
-       Values -- 0,1,2
+  * Values -- 0,1,2
 
        Word Clock Input is 0=Unlocked, 1=Locked, or 2=Synced.
 
-    AutoSync
+* AutoSync
 
-       Name -- "AutoSync Reference"
+  * Name -- "AutoSync Reference"
 
-       Access -- Read
+  * Access -- Read
 
-       Values -- "WordClock", "MADI", "None"
+  * Values -- "WordClock", "MADI", "None"
 
 		 Sync-Reference is either "WordClock", "MADI" or none.
 
-   RX 64ch --- noch nicht implementiert
+* RX 64ch --- noch nicht implementiert
 
        MADI-Receiver is in 64 channel mode oder 56 channel mode.
 
 
-   AB_inp   --- not tested 
+* AB_inp   --- not tested 
 
 		 Used input for Auto-Input.
 
 
-   actual Buffer Position --- not implemented
+* actual Buffer Position --- not implemented
 
 	   !!! this is a ALSA internal function, so no control is used !!!
 
 
 
-Calling Parameter:
+Calling Parameter
+=================
+
+* index int array (min = 1, max = 8) 
 
-   index int array (min = 1, max = 8), 
-     "Index value for RME HDSPM interface." card-index within ALSA
+     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."
+* 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."
+* 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."
+* 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."
+* 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
@@ -356,7 +371,9 @@ Calling Parameter:
 
 
 
-   enable_monitor int array (min = 1, max = 8), 
-     "Enable Analog Out on Channel 63/64 by default."
+* 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 6c8e4141df9a2..b143eff93c87c 100644
--- a/Documentation/sound/cards/index.rst
+++ b/Documentation/sound/cards/index.rst
@@ -14,3 +14,4 @@ Card-Specific Information
    mixart
    bt87x
    maya44
+   hdspm
-- 
GitLab


From bb02859cd3448f31e00c47c1277e27be0cee7d2a Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 17:33:12 +0100
Subject: [PATCH 129/193] 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/cards/index.rst           |  1 +
 .../serial-u16550.rst}                        | 21 ++++++++++++-------
 2 files changed, 14 insertions(+), 8 deletions(-)
 rename Documentation/sound/{alsa/serial-u16550.txt => cards/serial-u16550.rst} (92%)

diff --git a/Documentation/sound/cards/index.rst b/Documentation/sound/cards/index.rst
index b143eff93c87c..976ef5eb8f894 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/alsa/serial-u16550.txt b/Documentation/sound/cards/serial-u16550.rst
similarity index 92%
rename from Documentation/sound/alsa/serial-u16550.txt
rename to Documentation/sound/cards/serial-u16550.rst
index c1919559d5091..197aeacea3da8 100644
--- a/Documentation/sound/alsa/serial-u16550.txt
+++ b/Documentation/sound/cards/serial-u16550.rst
@@ -1,14 +1,14 @@
-
-			Serial UART 16450/16550 MIDI driver
-			===================================
+===================================
+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)
+* 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.
@@ -22,11 +22,13 @@ 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
@@ -37,6 +39,7 @@ 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 \
@@ -47,6 +50,7 @@ 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
@@ -63,6 +67,7 @@ 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
-- 
GitLab


From f336c3f072216a16187b22069681d014dcb43db6 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 17:36:09 +0100
Subject: [PATCH 130/193] 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 
---
 .../img-spdif-in.rst}                         | 24 +++++++++++--------
 Documentation/sound/cards/index.rst           |  1 +
 2 files changed, 15 insertions(+), 10 deletions(-)
 rename Documentation/sound/{alsa/img,spdif-in.txt => cards/img-spdif-in.rst} (68%)

diff --git a/Documentation/sound/alsa/img,spdif-in.txt b/Documentation/sound/cards/img-spdif-in.rst
similarity index 68%
rename from Documentation/sound/alsa/img,spdif-in.txt
rename to Documentation/sound/cards/img-spdif-in.rst
index 8b7505785fa67..7df9f5ae26097 100644
--- a/Documentation/sound/alsa/img,spdif-in.txt
+++ b/Documentation/sound/cards/img-spdif-in.rst
@@ -1,21 +1,25 @@
+================================================
+Imagination Technologies SPDIF Input Controllers
+================================================
+
 The Imagination Technologies SPDIF Input controller contains the following
 controls:
 
-name='IEC958 Capture Mask',index=0
+* 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
+* 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
+* 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'
@@ -29,21 +33,21 @@ 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
+* 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
+* 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
+* 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
+* 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 976ef5eb8f894..c016f8c3b88bf 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
-- 
GitLab


From 8e5336a14476e7350b0cf78a99541de6ed51655c Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 22:11:21 +0100
Subject: [PATCH 131/193] 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/index.rst                 |  1 +
 Documentation/sound/soc/index.rst             | 10 ++++++
 .../soc/overview.txt => soc/overview.rst}     | 32 ++-----------------
 3 files changed, 14 insertions(+), 29 deletions(-)
 create mode 100644 Documentation/sound/soc/index.rst
 rename Documentation/sound/{alsa/soc/overview.txt => soc/overview.rst} (83%)

diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst
index 1f5d166f81c4c..47b89f014e694 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 0000000000000..e974fd9f38a3a
--- /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/alsa/soc/overview.txt b/Documentation/sound/soc/overview.rst
similarity index 83%
rename from Documentation/sound/alsa/soc/overview.txt
rename to Documentation/sound/soc/overview.rst
index f3f28b7ae2420..dc8370bbfff66 100644
--- a/Documentation/sound/alsa/soc/overview.txt
+++ b/Documentation/sound/soc/overview.rst
@@ -1,5 +1,6 @@
-ALSA SoC Layer
-==============
+=======================
+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.
@@ -66,30 +67,3 @@ multiple re-usable component drivers :-
     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.
-- 
GitLab


From 693ba474a39a2c22e1576995139c9bfdd8b554c8 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 22:16:04 +0100
Subject: [PATCH 132/193] 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 
---
 .../{alsa/soc/codec.txt => soc/codec.rst}     | 75 +++++++++++--------
 Documentation/sound/soc/index.rst             |  1 +
 2 files changed, 44 insertions(+), 32 deletions(-)
 rename Documentation/sound/{alsa/soc/codec.txt => soc/codec.rst} (84%)

diff --git a/Documentation/sound/alsa/soc/codec.txt b/Documentation/sound/soc/codec.rst
similarity index 84%
rename from Documentation/sound/alsa/soc/codec.txt
rename to Documentation/sound/soc/codec.rst
index db5f9c9ae1495..f87612b948120 100644
--- a/Documentation/sound/alsa/soc/codec.txt
+++ b/Documentation/sound/soc/codec.rst
@@ -1,3 +1,4 @@
+=======================
 ASoC Codec Class Driver
 =======================
 
@@ -9,16 +10,16 @@ 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.
+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.
+7. DAC Digital mute control.
 
 Its probably best to use this guide in conjunction with the existing codec
 driver code in sound/soc/codecs/
@@ -26,24 +27,25 @@ driver code in sound/soc/codecs/
 ASoC Codec driver breakdown
 ===========================
 
-1 - Codec DAI and PCM configuration
------------------------------------
+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 = {
+  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 = {
+  };
+  
+  struct snd_soc_dai_driver wm8731_dai = {
 	.name = "wm8731-hifi",
 	.playback = {
 		.stream_name = "Playback",
@@ -59,25 +61,27 @@ struct snd_soc_dai_driver wm8731_dai = {
 		.formats = WM8731_FORMATS,},
 	.ops = &wm8731_dai_ops,
 	.symmetric_rates = 1,
-};
+  };
 
 
-2 - Codec control IO
---------------------
+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
------------------------------
+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
@@ -86,18 +90,22 @@ Defines a single control as follows:-
   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
@@ -109,25 +117,26 @@ Defines an single enumerated control as follows:-
 Defines a stereo enumerated control
 
 
-4 - Codec Audio Operations
---------------------------
+Codec Audio Operations
+----------------------
 The codec driver also supports the following ALSA PCM operations:-
+::
 
-/* SoC audio ops */
-struct snd_soc_ops {
+  /* 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.
----------------------
+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.
@@ -135,13 +144,14 @@ Please read dapm.txt for details of building the description.
 Please also see the examples in other codec drivers.
 
 
-6 - DAPM event handler
-----------------------
+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 */
@@ -155,8 +165,8 @@ Power states:-
 	SNDRV_CTL_POWER_D3cold: /* Everything Off, without power */
 
 
-7 - Codec DAC digital mute control
-----------------------------------
+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.
@@ -165,9 +175,10 @@ 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)
-{
+  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;
 
@@ -176,4 +187,4 @@ static int wm8974_mute(struct snd_soc_dai *dai, int mute)
 	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 e974fd9f38a3a..a2e023c91df2a 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
-- 
GitLab


From e732d1bcd452a040a18242d555996703465c1ca7 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 22:17:40 +0100
Subject: [PATCH 133/193] 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 
---
 .../sound/{alsa/soc/DAI.txt => soc/dai.rst}   | 28 ++++++++++++-------
 Documentation/sound/soc/index.rst             |  1 +
 2 files changed, 19 insertions(+), 10 deletions(-)
 rename Documentation/sound/{alsa/soc/DAI.txt => soc/dai.rst} (71%)

diff --git a/Documentation/sound/alsa/soc/DAI.txt b/Documentation/sound/soc/dai.rst
similarity index 71%
rename from Documentation/sound/alsa/soc/DAI.txt
rename to Documentation/sound/soc/dai.rst
index c9679264c5598..55820e51708fd 100644
--- a/Documentation/sound/alsa/soc/DAI.txt
+++ b/Documentation/sound/soc/dai.rst
@@ -1,3 +1,7 @@
+==================================
+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.
 
@@ -5,21 +9,21 @@ 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
+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 :-
+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
+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
@@ -30,13 +34,15 @@ 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.
+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.
+Left Justified
+  MSB is transmitted on transition of LRC.
 
- o Right Justified - MSB is transmitted sample size BCLKs before LRC
-                     transition.
+Right Justified
+  MSB is transmitted sample size BCLKs before LRC transition.
 
 PCM
 ===
@@ -51,6 +57,8 @@ 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.
+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.
+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 a2e023c91df2a..aea7ae7e5aad3 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
-- 
GitLab


From 77190f033377634bd494b67ca5a2dbcf685bd462 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 22:19:33 +0100
Subject: [PATCH 134/193] 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 
---
 .../sound/{alsa/soc/dapm.txt => soc/dapm.rst} | 249 ++++++++++--------
 Documentation/sound/soc/index.rst             |   1 +
 2 files changed, 144 insertions(+), 106 deletions(-)
 rename Documentation/sound/{alsa/soc/dapm.txt => soc/dapm.rst} (62%)

diff --git a/Documentation/sound/alsa/soc/dapm.txt b/Documentation/sound/soc/dapm.rst
similarity index 62%
rename from Documentation/sound/alsa/soc/dapm.txt
rename to Documentation/sound/soc/dapm.rst
index c45bd79f291ea..a27f42befa4dc 100644
--- a/Documentation/sound/alsa/soc/dapm.txt
+++ b/Documentation/sound/soc/dapm.rst
@@ -1,8 +1,9 @@
+===================================================
 Dynamic Audio Power Management for Portable Devices
 ===================================================
 
-1. Description
-==============
+Description
+===========
 
 Dynamic Audio Power Management (DAPM) is designed to allow portable
 Linux devices to use the minimum amount of power within the audio
@@ -21,20 +22,28 @@ level power systems.
 
 There are 4 power domains within DAPM
 
-   1. Codec bias domain - VREF, VMID (core codec and audio power)
+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
+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
+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.
+Stream domain
+      DACs and ADCs.
+
       Enabled and disabled when stream playback/capture is started and
       stopped respectively. e.g. aplay, arecord.
 
@@ -45,34 +54,57 @@ internal codec components). All audio components that effect power are called
 widgets hereafter.
 
 
-2. DAPM Widgets
-===============
+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)
+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)
 
@@ -84,52 +116,57 @@ 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 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)
+  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),
+  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),
+  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
+-------------------
 
 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)
+  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),
-};
+  /* 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,
+  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,
@@ -137,48 +174,49 @@ 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 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
+* 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:-
+when the Mic is inserted:-::
 
-static int spitz_mic_bias(struct snd_soc_dapm_widget* w, int event)
-{
+  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),
+  SND_SOC_DAPM_MIC("Mic Jack", spitz_mic_bias),
 
 
-2.4 Codec (BIAS) Domain
------------------------
+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
--------------------
+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),
+  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.
 
@@ -186,8 +224,8 @@ 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
-====================================
+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
@@ -201,13 +239,14 @@ 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
+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"},
@@ -216,22 +255,17 @@ connect the destination widget (wrt audio signal) with its source widgets.
 
 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".
+* 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);
+  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
@@ -239,12 +273,13 @@ 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
+-------------------------------
 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"},
@@ -254,52 +289,54 @@ 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
-===================
+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
+* 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.
 
 
-5 DAPM Widget Events
-====================
+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)
-{
+  /* 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 =
+  /* 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
----------------
+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 */
+::
+
+  /* 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 aea7ae7e5aad3..0c0c38e582b42 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
-- 
GitLab


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

A simple conversion from a plain text file.

Acked-by: Mark Brown 
Signed-off-by: Takashi Iwai 
---
 Documentation/sound/soc/index.rst             |  1 +
 .../soc/platform.txt => soc/platform.rst}     | 31 ++++++++++---------
 2 files changed, 18 insertions(+), 14 deletions(-)
 rename Documentation/sound/{alsa/soc/platform.txt => soc/platform.rst} (81%)

diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
index 0c0c38e582b42..c5a55195bf4de 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/alsa/soc/platform.txt b/Documentation/sound/soc/platform.rst
similarity index 81%
rename from Documentation/sound/alsa/soc/platform.txt
rename to Documentation/sound/soc/platform.rst
index 3a08a2c9150c9..d5574904d981d 100644
--- a/Documentation/sound/alsa/soc/platform.txt
+++ b/Documentation/sound/soc/platform.rst
@@ -1,3 +1,4 @@
+====================
 ASoC Platform Driver
 ====================
 
@@ -9,21 +10,23 @@ Audio DMA
 =========
 
 The platform DMA driver optionally supports the following ALSA operations:-
+::
 
-/* SoC audio ops */
-struct snd_soc_ops {
+  /* 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 {
+  struct snd_soc_platform_driver {
 	char *name;
 
 	int (*probe)(struct platform_device *pdev);
@@ -44,7 +47,7 @@ struct snd_soc_platform_driver {
 
 	/* 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/
@@ -57,11 +60,11 @@ 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)
+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.
 
@@ -71,9 +74,9 @@ 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.
+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.
-- 
GitLab


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

A simple conversion from a plain text file.

Acked-by: Mark Brown 
Signed-off-by: Takashi Iwai 
---
 Documentation/sound/soc/index.rst             |  1 +
 .../{alsa/soc/machine.txt => soc/machine.rst} | 22 +++++++++++--------
 2 files changed, 14 insertions(+), 9 deletions(-)
 rename Documentation/sound/{alsa/soc/machine.txt => soc/machine.rst} (90%)

diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
index c5a55195bf4de..4ac3585e7dd19 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/alsa/soc/machine.txt b/Documentation/sound/soc/machine.rst
similarity index 90%
rename from Documentation/sound/alsa/soc/machine.txt
rename to Documentation/sound/soc/machine.rst
index 6bf2d2063b524..515c9444deafc 100644
--- a/Documentation/sound/alsa/soc/machine.txt
+++ b/Documentation/sound/soc/machine.rst
@@ -1,3 +1,4 @@
+===================
 ASoC Machine Driver
 ===================
 
@@ -9,9 +10,10 @@ 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 {
+  /* SoC machine */
+  struct snd_soc_card {
 	char *name;
 
 	...
@@ -33,7 +35,7 @@ struct snd_soc_card {
 	int num_links;
 
 	...
-};
+  };
 
 probe()/remove()
 ----------------
@@ -55,9 +57,10 @@ 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 = {
+  /* 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",
@@ -66,16 +69,17 @@ static struct snd_soc_dai_link corgi_dai = {
 	.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 = {
+  /* corgi audio machine driver */
+  static struct snd_soc_card snd_soc_corgi = {
 	.name = "Corgi",
 	.dai_link = &corgi_dai,
 	.num_links = 1,
-};
+  };
 
 
 Machine Power Map
-- 
GitLab


From c9746eeafca3b5286a0355b895eb48af19d54d2d Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 22:23:58 +0100
Subject: [PATCH 137/193] 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/soc/index.rst                 |  1 +
 .../soc/pops_clicks.txt => soc/pops-clicks.rst}   | 15 +++++++++------
 2 files changed, 10 insertions(+), 6 deletions(-)
 rename Documentation/sound/{alsa/soc/pops_clicks.txt => soc/pops-clicks.rst} (87%)

diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
index 4ac3585e7dd19..4dd679927a912 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/alsa/soc/pops_clicks.txt b/Documentation/sound/soc/pops-clicks.rst
similarity index 87%
rename from Documentation/sound/alsa/soc/pops_clicks.txt
rename to Documentation/sound/soc/pops-clicks.rst
index e1e74daa44972..de7eb2a6604ae 100644
--- a/Documentation/sound/alsa/soc/pops_clicks.txt
+++ b/Documentation/sound/soc/pops-clicks.rst
@@ -1,3 +1,4 @@
+=====================
 Audio Pops and Clicks
 =====================
 
@@ -20,10 +21,11 @@ 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
+   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.
@@ -36,10 +38,11 @@ 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
+   Startup Order - Input PGA --> Mixers --> ADC
+  
+   Shutdown Order - ADC --> Mixers --> Input PGA
 
 
 Zipper Noise
-- 
GitLab


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

A simple conversion from a plain text file.

Acked-by: Mark Brown 
Signed-off-by: Takashi Iwai 
---
 .../{alsa/soc/clocking.txt => soc/clocking.rst}     | 13 ++++---------
 Documentation/sound/soc/index.rst                   |  1 +
 2 files changed, 5 insertions(+), 9 deletions(-)
 rename Documentation/sound/{alsa/soc/clocking.txt => soc/clocking.rst} (94%)

diff --git a/Documentation/sound/alsa/soc/clocking.txt b/Documentation/sound/soc/clocking.rst
similarity index 94%
rename from Documentation/sound/alsa/soc/clocking.txt
rename to Documentation/sound/soc/clocking.rst
index b1300162e01ce..32122d6877a3d 100644
--- a/Documentation/sound/alsa/soc/clocking.txt
+++ b/Documentation/sound/soc/clocking.rst
@@ -1,3 +1,4 @@
+==============
 Audio Clocking
 ==============
 
@@ -30,15 +31,9 @@ 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
+- 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
diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
index 4dd679927a912..0055abe16e7e9 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
-- 
GitLab


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

A simple conversion from a plain text file.

Acked-by: Mark Brown 
Signed-off-by: Takashi Iwai 
---
 Documentation/sound/soc/index.rst                       | 1 +
 Documentation/sound/{alsa/soc/jack.txt => soc/jack.rst} | 1 +
 2 files changed, 2 insertions(+)
 rename Documentation/sound/{alsa/soc/jack.txt => soc/jack.rst} (99%)

diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
index 0055abe16e7e9..85ec51764e83f 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/alsa/soc/jack.txt b/Documentation/sound/soc/jack.rst
similarity index 99%
rename from Documentation/sound/alsa/soc/jack.txt
rename to Documentation/sound/soc/jack.rst
index fcf82a4172935..644b99ecba35e 100644
--- a/Documentation/sound/alsa/soc/jack.txt
+++ b/Documentation/sound/soc/jack.rst
@@ -1,3 +1,4 @@
+===================
 ASoC jack detection
 ===================
 
-- 
GitLab


From 40433cd34e280bd1a56f54a3898e86863814c824 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Thu, 10 Nov 2016 22:29:49 +0100
Subject: [PATCH 140/193] 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 
---
 .../sound/{alsa/soc/DPCM.txt => soc/dpcm.rst} | 280 +++++++++---------
 Documentation/sound/soc/index.rst             |   1 +
 2 files changed, 147 insertions(+), 134 deletions(-)
 rename Documentation/sound/{alsa/soc/DPCM.txt => soc/dpcm.rst} (57%)

diff --git a/Documentation/sound/alsa/soc/DPCM.txt b/Documentation/sound/soc/dpcm.rst
similarity index 57%
rename from Documentation/sound/alsa/soc/DPCM.txt
rename to Documentation/sound/soc/dpcm.rst
index 0110180b7ac63..395e5a5162820 100644
--- a/Documentation/sound/alsa/soc/DPCM.txt
+++ b/Documentation/sound/soc/dpcm.rst
@@ -1,8 +1,9 @@
+===========
 Dynamic PCM
 ===========
 
-1. Description
-==============
+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
@@ -23,22 +24,23 @@ 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
-                    *************
+::
+
+  | 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
@@ -55,50 +57,52 @@ 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
-                    *************
+::
+
+                      *************
+  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
-                    *************
+::
+
+                      *************
+  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.
+1. Machine driver receives Jack removal event.
 
- 2) Machine driver OR audio HAL disables the Headset path.
+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.
+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.
+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.
+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
@@ -112,36 +116,38 @@ 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.
+1. Define the FE and BE DAI links.
 
- 2) Define any FE/BE PCM operations.
+2. Define any FE/BE PCM operations.
 
- 3) Define widget graph connections.
+3. Define widget graph connections.
 
 
-1 FE and BE DAI links
----------------------
+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
-                    *************
+  | 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[] = {
+  static struct snd_soc_dai_link machine_dais[] = {
 	{
 		.name = "PCM0 System",
 		.stream_name = "System Playback",
@@ -154,11 +160,11 @@ static struct snd_soc_dai_link machine_dais[] = {
 		.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"
+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
@@ -168,8 +174,9 @@ 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[] = {
+  static struct snd_soc_dai_link machine_dais[] = {
 	.....< FE DAI links here >
 	{
 		.name = "Codec Headset",
@@ -186,29 +193,30 @@ static struct snd_soc_dai_link machine_dais[] = {
 		.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 ``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
-                    *************
+::
+
+                      *************
+  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.
@@ -220,10 +228,10 @@ 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
-----------------------
+FE/BE PCM operations
+--------------------
 
-The BE above also exports some PCM operations and a "fixup" callback. The fixup
+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.
 
@@ -231,10 +239,11 @@ e.g. DSP converts all FE hw params to run at fixed rate of 48k, 16bit, stereo fo
 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,
+  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,
@@ -249,21 +258,22 @@ static int dai0_fixup(struct snd_soc_pcm_runtime *rtd,
 				    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
---------------------------
+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"},
+  /* 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
@@ -273,24 +283,25 @@ 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.
+1. Front End PCM DAIs - i.e. struct snd_soc_dai_driver.
 
- 2) DAPM graph showing DSP audio routing from FE DAIs to BEs.
+2. DAPM graph showing DSP audio routing from FE DAIs to BEs.
 
- 3) DAPM widgets from DSP graph.
+3. DAPM widgets from DSP graph.
 
- 4) Mixers for gains, routing, etc.
+4. Mixers for gains, routing, etc.
 
- 5) DMA configuration.
+5. DMA configuration.
 
- 6) BE AIF widgets.
+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),
+  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).
@@ -301,33 +312,33 @@ 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
-                    *************
+::
+
+                      *************
+  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
+ 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
+ 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
@@ -339,16 +350,17 @@ 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 = {
+  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[] = {
+  static struct snd_soc_dai_link dais[] = {
 	< ... more DAI links above ... >
 	{
 		.name = "MODEM",
diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
index 85ec51764e83f..e142a0f25c5ba 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
-- 
GitLab


From c6ab9e57e84ee015bb9c5de213d9f85e5fd4e085 Mon Sep 17 00:00:00 2001
From: Takashi Iwai 
Date: Fri, 11 Nov 2016 16:55:29 +0100
Subject: [PATCH 141/193] 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 
---
 .../codec-to-codec.rst}                       | 79 ++++++++++---------
 Documentation/sound/soc/index.rst             |  1 +
 2 files changed, 43 insertions(+), 37 deletions(-)
 rename Documentation/sound/{alsa/soc/codec_to_codec.txt => soc/codec-to-codec.rst} (68%)

diff --git a/Documentation/sound/alsa/soc/codec_to_codec.txt b/Documentation/sound/soc/codec-to-codec.rst
similarity index 68%
rename from Documentation/sound/alsa/soc/codec_to_codec.txt
rename to Documentation/sound/soc/codec-to-codec.rst
index 704a6483652ca..810109d7500df 100644
--- a/Documentation/sound/alsa/soc/codec_to_codec.txt
+++ b/Documentation/sound/soc/codec-to-codec.rst
@@ -1,37 +1,41 @@
+==============================================
 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
-|         |        |         |
- ---------          ---------
+   ---------          ---------
+  |         |  dai   |         |
+      CPU    ------->    codec
+  |         |        |         |
+   ---------          ---------
 
 In case your system looks as below:
-                     ---------
-                    |         |
-                      codec-2
-                    |         |
-                     ---------
-                         |
-                       dai-2
-                         |
- ----------          ---------
-|          |  dai-1 |         |
-    CPU     ------->  codec-1
-|          |        |         |
- ----------          ---------
-                         |
-                       dai-3
-                         |
-                     ---------
-                    |         |
-                      codec-3
-                    |         |
-                     ---------
+::
+
+                       ---------
+                      |         |
+                        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:
@@ -42,20 +46,21 @@ 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 = {
+ /*
+  * 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",
@@ -66,8 +71,8 @@ static const struct snd_soc_pcm_stream dsp_codec_params = {
             | SND_SOC_DAIFMT_CBM_CFM,
     .ignore_suspend = 1,
     .params = &dsp_codec_params,
-},
-{
+ },
+ {
     .name = "DSP-CODEC",
     .stream_name = "DSP-CODEC",
     .cpu_dai_name = "wm0010-sdi2",
@@ -77,7 +82,7 @@ static const struct snd_soc_pcm_stream dsp_codec_params = {
             | SND_SOC_DAIFMT_CBM_CFM,
     .ignore_suspend = 1,
     .params = &dsp_codec_params,
-},
+ },
 
 Above code snippet is motivated from sound/soc/samsung/speyside.c.
 
diff --git a/Documentation/sound/soc/index.rst b/Documentation/sound/soc/index.rst
index e142a0f25c5ba..e57df2dab2fdf 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
-- 
GitLab


From 3080b056b3d4e38bc4beac337acadf8bd286ac58 Mon Sep 17 00:00:00 2001
From: SeongJae Park 
Date: Tue, 8 Nov 2016 21:26:07 +0900
Subject: [PATCH 142/193] 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 5d50d6733db3b..a0d65eb490550 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
-- 
GitLab


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

Signed-off-by: SeongJae Park 
Signed-off-by: Jonathan Corbet 
---
 Documentation/{ => translations}/ja_JP/HOWTO                      | 0
 Documentation/{ => translations}/ja_JP/SubmitChecklist            | 0
 Documentation/{ => translations}/ja_JP/SubmittingPatches          | 0
 Documentation/{ => translations}/ja_JP/stable_api_nonsense.txt    | 0
 Documentation/{ => translations}/ja_JP/stable_kernel_rules.txt    | 0
 Documentation/{ => translations}/ko_KR/HOWTO                      | 0
 Documentation/{ => translations}/ko_KR/memory-barriers.txt        | 0
 Documentation/{ => translations}/ko_KR/stable_api_nonsense.txt    | 0
 Documentation/{ => translations}/zh_CN/CodingStyle                | 0
 Documentation/{ => translations}/zh_CN/HOWTO                      | 0
 Documentation/{ => translations}/zh_CN/IRQ.txt                    | 0
 Documentation/{ => translations}/zh_CN/SecurityBugs               | 0
 Documentation/{ => translations}/zh_CN/SubmittingDrivers          | 0
 Documentation/{ => translations}/zh_CN/SubmittingPatches          | 0
 Documentation/{ => translations}/zh_CN/arm/Booting                | 0
 .../{ => translations}/zh_CN/arm/kernel_user_helpers.txt          | 0
 Documentation/{ => translations}/zh_CN/arm64/booting.txt          | 0
 .../{ => translations}/zh_CN/arm64/legacy_instructions.txt        | 0
 Documentation/{ => translations}/zh_CN/arm64/memory.txt           | 0
 Documentation/{ => translations}/zh_CN/arm64/silicon-errata.txt   | 0
 Documentation/{ => translations}/zh_CN/arm64/tagged-pointers.txt  | 0
 Documentation/{ => translations}/zh_CN/basic_profiling.txt        | 0
 Documentation/{ => translations}/zh_CN/email-clients.txt          | 0
 Documentation/{ => translations}/zh_CN/filesystems/sysfs.txt      | 0
 Documentation/{ => translations}/zh_CN/gpio.txt                   | 0
 Documentation/{ => translations}/zh_CN/io_ordering.txt            | 0
 Documentation/{ => translations}/zh_CN/magic-number.txt           | 0
 Documentation/{ => translations}/zh_CN/oops-tracing.txt           | 0
 Documentation/{ => translations}/zh_CN/sparse.txt                 | 0
 Documentation/{ => translations}/zh_CN/stable_api_nonsense.txt    | 0
 Documentation/{ => translations}/zh_CN/stable_kernel_rules.txt    | 0
 Documentation/{ => translations}/zh_CN/video4linux/omap3isp.txt   | 0
 .../{ => translations}/zh_CN/video4linux/v4l2-framework.txt       | 0
 .../{ => translations}/zh_CN/volatile-considered-harmful.txt      | 0
 34 files changed, 0 insertions(+), 0 deletions(-)
 rename Documentation/{ => translations}/ja_JP/HOWTO (100%)
 rename Documentation/{ => translations}/ja_JP/SubmitChecklist (100%)
 rename Documentation/{ => translations}/ja_JP/SubmittingPatches (100%)
 rename Documentation/{ => translations}/ja_JP/stable_api_nonsense.txt (100%)
 rename Documentation/{ => translations}/ja_JP/stable_kernel_rules.txt (100%)
 rename Documentation/{ => translations}/ko_KR/HOWTO (100%)
 rename Documentation/{ => translations}/ko_KR/memory-barriers.txt (100%)
 rename Documentation/{ => translations}/ko_KR/stable_api_nonsense.txt (100%)
 rename Documentation/{ => translations}/zh_CN/CodingStyle (100%)
 rename Documentation/{ => translations}/zh_CN/HOWTO (100%)
 rename Documentation/{ => translations}/zh_CN/IRQ.txt (100%)
 rename Documentation/{ => translations}/zh_CN/SecurityBugs (100%)
 rename Documentation/{ => translations}/zh_CN/SubmittingDrivers (100%)
 rename Documentation/{ => translations}/zh_CN/SubmittingPatches (100%)
 rename Documentation/{ => translations}/zh_CN/arm/Booting (100%)
 rename Documentation/{ => translations}/zh_CN/arm/kernel_user_helpers.txt (100%)
 rename Documentation/{ => translations}/zh_CN/arm64/booting.txt (100%)
 rename Documentation/{ => translations}/zh_CN/arm64/legacy_instructions.txt (100%)
 rename Documentation/{ => translations}/zh_CN/arm64/memory.txt (100%)
 rename Documentation/{ => translations}/zh_CN/arm64/silicon-errata.txt (100%)
 rename Documentation/{ => translations}/zh_CN/arm64/tagged-pointers.txt (100%)
 rename Documentation/{ => translations}/zh_CN/basic_profiling.txt (100%)
 rename Documentation/{ => translations}/zh_CN/email-clients.txt (100%)
 rename Documentation/{ => translations}/zh_CN/filesystems/sysfs.txt (100%)
 rename Documentation/{ => translations}/zh_CN/gpio.txt (100%)
 rename Documentation/{ => translations}/zh_CN/io_ordering.txt (100%)
 rename Documentation/{ => translations}/zh_CN/magic-number.txt (100%)
 rename Documentation/{ => translations}/zh_CN/oops-tracing.txt (100%)
 rename Documentation/{ => translations}/zh_CN/sparse.txt (100%)
 rename Documentation/{ => translations}/zh_CN/stable_api_nonsense.txt (100%)
 rename Documentation/{ => translations}/zh_CN/stable_kernel_rules.txt (100%)
 rename Documentation/{ => translations}/zh_CN/video4linux/omap3isp.txt (100%)
 rename Documentation/{ => translations}/zh_CN/video4linux/v4l2-framework.txt (100%)
 rename Documentation/{ => translations}/zh_CN/volatile-considered-harmful.txt (100%)

diff --git a/Documentation/ja_JP/HOWTO b/Documentation/translations/ja_JP/HOWTO
similarity index 100%
rename from Documentation/ja_JP/HOWTO
rename to Documentation/translations/ja_JP/HOWTO
diff --git a/Documentation/ja_JP/SubmitChecklist b/Documentation/translations/ja_JP/SubmitChecklist
similarity index 100%
rename from Documentation/ja_JP/SubmitChecklist
rename to Documentation/translations/ja_JP/SubmitChecklist
diff --git a/Documentation/ja_JP/SubmittingPatches b/Documentation/translations/ja_JP/SubmittingPatches
similarity index 100%
rename from Documentation/ja_JP/SubmittingPatches
rename to Documentation/translations/ja_JP/SubmittingPatches
diff --git a/Documentation/ja_JP/stable_api_nonsense.txt b/Documentation/translations/ja_JP/stable_api_nonsense.txt
similarity index 100%
rename from Documentation/ja_JP/stable_api_nonsense.txt
rename to Documentation/translations/ja_JP/stable_api_nonsense.txt
diff --git a/Documentation/ja_JP/stable_kernel_rules.txt b/Documentation/translations/ja_JP/stable_kernel_rules.txt
similarity index 100%
rename from Documentation/ja_JP/stable_kernel_rules.txt
rename to Documentation/translations/ja_JP/stable_kernel_rules.txt
diff --git a/Documentation/ko_KR/HOWTO b/Documentation/translations/ko_KR/HOWTO
similarity index 100%
rename from Documentation/ko_KR/HOWTO
rename to Documentation/translations/ko_KR/HOWTO
diff --git a/Documentation/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt
similarity index 100%
rename from Documentation/ko_KR/memory-barriers.txt
rename to Documentation/translations/ko_KR/memory-barriers.txt
diff --git a/Documentation/ko_KR/stable_api_nonsense.txt b/Documentation/translations/ko_KR/stable_api_nonsense.txt
similarity index 100%
rename from Documentation/ko_KR/stable_api_nonsense.txt
rename to Documentation/translations/ko_KR/stable_api_nonsense.txt
diff --git a/Documentation/zh_CN/CodingStyle b/Documentation/translations/zh_CN/CodingStyle
similarity index 100%
rename from Documentation/zh_CN/CodingStyle
rename to Documentation/translations/zh_CN/CodingStyle
diff --git a/Documentation/zh_CN/HOWTO b/Documentation/translations/zh_CN/HOWTO
similarity index 100%
rename from Documentation/zh_CN/HOWTO
rename to Documentation/translations/zh_CN/HOWTO
diff --git a/Documentation/zh_CN/IRQ.txt b/Documentation/translations/zh_CN/IRQ.txt
similarity index 100%
rename from Documentation/zh_CN/IRQ.txt
rename to Documentation/translations/zh_CN/IRQ.txt
diff --git a/Documentation/zh_CN/SecurityBugs b/Documentation/translations/zh_CN/SecurityBugs
similarity index 100%
rename from Documentation/zh_CN/SecurityBugs
rename to Documentation/translations/zh_CN/SecurityBugs
diff --git a/Documentation/zh_CN/SubmittingDrivers b/Documentation/translations/zh_CN/SubmittingDrivers
similarity index 100%
rename from Documentation/zh_CN/SubmittingDrivers
rename to Documentation/translations/zh_CN/SubmittingDrivers
diff --git a/Documentation/zh_CN/SubmittingPatches b/Documentation/translations/zh_CN/SubmittingPatches
similarity index 100%
rename from Documentation/zh_CN/SubmittingPatches
rename to Documentation/translations/zh_CN/SubmittingPatches
diff --git a/Documentation/zh_CN/arm/Booting b/Documentation/translations/zh_CN/arm/Booting
similarity index 100%
rename from Documentation/zh_CN/arm/Booting
rename to Documentation/translations/zh_CN/arm/Booting
diff --git a/Documentation/zh_CN/arm/kernel_user_helpers.txt b/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt
similarity index 100%
rename from Documentation/zh_CN/arm/kernel_user_helpers.txt
rename to Documentation/translations/zh_CN/arm/kernel_user_helpers.txt
diff --git a/Documentation/zh_CN/arm64/booting.txt b/Documentation/translations/zh_CN/arm64/booting.txt
similarity index 100%
rename from Documentation/zh_CN/arm64/booting.txt
rename to Documentation/translations/zh_CN/arm64/booting.txt
diff --git a/Documentation/zh_CN/arm64/legacy_instructions.txt b/Documentation/translations/zh_CN/arm64/legacy_instructions.txt
similarity index 100%
rename from Documentation/zh_CN/arm64/legacy_instructions.txt
rename to Documentation/translations/zh_CN/arm64/legacy_instructions.txt
diff --git a/Documentation/zh_CN/arm64/memory.txt b/Documentation/translations/zh_CN/arm64/memory.txt
similarity index 100%
rename from Documentation/zh_CN/arm64/memory.txt
rename to Documentation/translations/zh_CN/arm64/memory.txt
diff --git a/Documentation/zh_CN/arm64/silicon-errata.txt b/Documentation/translations/zh_CN/arm64/silicon-errata.txt
similarity index 100%
rename from Documentation/zh_CN/arm64/silicon-errata.txt
rename to Documentation/translations/zh_CN/arm64/silicon-errata.txt
diff --git a/Documentation/zh_CN/arm64/tagged-pointers.txt b/Documentation/translations/zh_CN/arm64/tagged-pointers.txt
similarity index 100%
rename from Documentation/zh_CN/arm64/tagged-pointers.txt
rename to Documentation/translations/zh_CN/arm64/tagged-pointers.txt
diff --git a/Documentation/zh_CN/basic_profiling.txt b/Documentation/translations/zh_CN/basic_profiling.txt
similarity index 100%
rename from Documentation/zh_CN/basic_profiling.txt
rename to Documentation/translations/zh_CN/basic_profiling.txt
diff --git a/Documentation/zh_CN/email-clients.txt b/Documentation/translations/zh_CN/email-clients.txt
similarity index 100%
rename from Documentation/zh_CN/email-clients.txt
rename to Documentation/translations/zh_CN/email-clients.txt
diff --git a/Documentation/zh_CN/filesystems/sysfs.txt b/Documentation/translations/zh_CN/filesystems/sysfs.txt
similarity index 100%
rename from Documentation/zh_CN/filesystems/sysfs.txt
rename to Documentation/translations/zh_CN/filesystems/sysfs.txt
diff --git a/Documentation/zh_CN/gpio.txt b/Documentation/translations/zh_CN/gpio.txt
similarity index 100%
rename from Documentation/zh_CN/gpio.txt
rename to Documentation/translations/zh_CN/gpio.txt
diff --git a/Documentation/zh_CN/io_ordering.txt b/Documentation/translations/zh_CN/io_ordering.txt
similarity index 100%
rename from Documentation/zh_CN/io_ordering.txt
rename to Documentation/translations/zh_CN/io_ordering.txt
diff --git a/Documentation/zh_CN/magic-number.txt b/Documentation/translations/zh_CN/magic-number.txt
similarity index 100%
rename from Documentation/zh_CN/magic-number.txt
rename to Documentation/translations/zh_CN/magic-number.txt
diff --git a/Documentation/zh_CN/oops-tracing.txt b/Documentation/translations/zh_CN/oops-tracing.txt
similarity index 100%
rename from Documentation/zh_CN/oops-tracing.txt
rename to Documentation/translations/zh_CN/oops-tracing.txt
diff --git a/Documentation/zh_CN/sparse.txt b/Documentation/translations/zh_CN/sparse.txt
similarity index 100%
rename from Documentation/zh_CN/sparse.txt
rename to Documentation/translations/zh_CN/sparse.txt
diff --git a/Documentation/zh_CN/stable_api_nonsense.txt b/Documentation/translations/zh_CN/stable_api_nonsense.txt
similarity index 100%
rename from Documentation/zh_CN/stable_api_nonsense.txt
rename to Documentation/translations/zh_CN/stable_api_nonsense.txt
diff --git a/Documentation/zh_CN/stable_kernel_rules.txt b/Documentation/translations/zh_CN/stable_kernel_rules.txt
similarity index 100%
rename from Documentation/zh_CN/stable_kernel_rules.txt
rename to Documentation/translations/zh_CN/stable_kernel_rules.txt
diff --git a/Documentation/zh_CN/video4linux/omap3isp.txt b/Documentation/translations/zh_CN/video4linux/omap3isp.txt
similarity index 100%
rename from Documentation/zh_CN/video4linux/omap3isp.txt
rename to Documentation/translations/zh_CN/video4linux/omap3isp.txt
diff --git a/Documentation/zh_CN/video4linux/v4l2-framework.txt b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
similarity index 100%
rename from Documentation/zh_CN/video4linux/v4l2-framework.txt
rename to Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
diff --git a/Documentation/zh_CN/volatile-considered-harmful.txt b/Documentation/translations/zh_CN/volatile-considered-harmful.txt
similarity index 100%
rename from Documentation/zh_CN/volatile-considered-harmful.txt
rename to Documentation/translations/zh_CN/volatile-considered-harmful.txt
-- 
GitLab


From ba42c574fc8b803ec206785b7b91325c05810422 Mon Sep 17 00:00:00 2001
From: SeongJae Park 
Date: Tue, 8 Nov 2016 21:26:09 +0900
Subject: [PATCH 144/193] 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 ++++++++
 .../translations/ko_KR/{HOWTO => howto.rst}          |  0
 Documentation/translations/ko_KR/index.rst           | 12 ++++++++++++
 3 files changed, 20 insertions(+)
 rename Documentation/translations/ko_KR/{HOWTO => howto.rst} (100%)
 create mode 100644 Documentation/translations/ko_KR/index.rst

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 1dff9fa106bdc..733bd9013541a 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.rst
similarity index 100%
rename from Documentation/translations/ko_KR/HOWTO
rename to Documentation/translations/ko_KR/howto.rst
diff --git a/Documentation/translations/ko_KR/index.rst b/Documentation/translations/ko_KR/index.rst
new file mode 100644
index 0000000000000..0b695345abc74
--- /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
-- 
GitLab


From f5ff9b63d494ed6fbfc96e8b4f5c2c32ad291b12 Mon Sep 17 00:00:00 2001
From: Jonathan Corbet 
Date: Sun, 13 Nov 2016 12:24:59 -0700
Subject: [PATCH 145/193] 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 489a913a0bd4b..690cfb6a53d9e 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 
-- 
GitLab


From e2a91f4f42018994d7424d405900d17eba6555d0 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 14 Nov 2016 14:32:27 -0200
Subject: [PATCH 146/193] 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 bcb1af786e78c..db78974aad266 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 e347a3e7bdef4..7f8f0af620ceb 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::
-- 
GitLab


From ce998e6fbaf77a0cc9ce5070db64db56c1d4b69a Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 14 Nov 2016 14:32:28 -0200
Subject: [PATCH 147/193] 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 e144370f62a05..282a7467a8125 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
-- 
GitLab


From 346dabfee054e5ca6cee4ab605640098e6555b6c Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 14 Nov 2016 14:32:29 -0200
Subject: [PATCH 148/193] 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 282a7467a8125..65105609374be 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:
 
-- 
GitLab


From 00e99ed2c84536055761fa5962ae4e6eb95b4090 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 14 Nov 2016 14:32:30 -0200
Subject: [PATCH 149/193] 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 +-
 .../vidioc-g-selection_files/constraints.png  | Bin 3313 -> 0 bytes
 .../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 b61081d00a9fc..11b96a19a9abd 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 9b8f372e7afd9d016854973ba705dcdfbd1bbf13..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 22655
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
I?##9S2OFAByZ`_I

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 0000000000000..c4140fb518afc
--- /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 3145a9166badc..6da359e506681 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 20228d2c5504cf3af92d916970f6bfae0e60e121..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 3313
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
+image/svg+xmlV4L2_SEL_FLAG_GE
+ORIGINAL
+V4L2_SEL_FLAG_LE
+
\ No newline at end of file
-- 
GitLab


From f3902934797b0b00ba8f10bfc377c1bb2789046c Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 14 Nov 2016 14:32:31 -0200
Subject: [PATCH 150/193] 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 
---
 .../media/uapi/v4l/crop_files/crop.gif          | Bin 5967 -> 0 bytes
 .../media/uapi/v4l/crop_files/crop.png          | Bin 0 -> 3334 bytes
 .../uapi/v4l/dev-raw-vbi_files/vbi_525.gif      | Bin 4741 -> 0 bytes
 .../uapi/v4l/dev-raw-vbi_files/vbi_525.png      | Bin 0 -> 2053 bytes
 .../uapi/v4l/dev-raw-vbi_files/vbi_625.gif      | Bin 5095 -> 0 bytes
 .../uapi/v4l/dev-raw-vbi_files/vbi_625.png      | Bin 0 -> 2352 bytes
 .../uapi/v4l/dev-raw-vbi_files/vbi_hsync.gif    | Bin 2400 -> 0 bytes
 .../uapi/v4l/dev-raw-vbi_files/vbi_hsync.png    | Bin 0 -> 906 bytes
 .../uapi/v4l/field-order_files/fieldseq_bt.gif  | Bin 25430 -> 0 bytes
 .../uapi/v4l/field-order_files/fieldseq_bt.png  | Bin 0 -> 12306 bytes
 .../uapi/v4l/field-order_files/fieldseq_tb.gif  | Bin 25323 -> 0 bytes
 .../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 3b9e7d836d4b8a685e76ec6412fc28c9f5c16f27..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

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

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 0000000000000000000000000000000000000000..225998c395dfe5e605acbf85325fdd52c78fbff4
GIT binary patch
literal 3334
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

literal 0
HcmV?d00001

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 5580b690d504f388f5c62f730c45e09999da1341..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 4741
zcmV;05_;`NNk%w1VJZX20Du4h00030|NkNR1OWg50RSuj0000g1IPdX0{)DTsmtvT
zqnxzbi?iOm`wxcVNS5Y_rs`S(Y~#L5EGu+<+_<6Ref}8Sp>qewQ)rk+
zn26C8C?Q41#k1H*dFh3z*|+Bzc{MmlS}J#@+O`_%`gbUbng$gMn#nj(_cbXt>f*QC
zhZ!6>40hUBre}lvNj3-E`v$wpYI}|SYYqB(IK8PoYZxkPY5q)+45!GKt{X=?-YKsw
zjP6hj1^oV&Os_8-H)Gidn(`J4;jwn3@Tr?8PF=2ux}*&}SE-*b{&(jL(yIsZqecji
z4BiXI?4i7gB1u+*NT*ymhw#3EBjbT#J%t?$s%+`e5l@V@euji(i)GC`oPt(two{^~
z9&VPMx)E^W#gQ(3#-u3_rctIq$9^qqcBxl^GZiUSOYR@so@lkM+-kRO*q>SX#=MeJ
zFExpPCA}StH*Lk6`Q*ra>GW@6N{9D8&1n;J=E+^1g`|trn4Wuo*^G`%k{M&fGuIk<
z0+tEv)|^$)uASnx*cZA{zm5W1u-efu5;?Sd44~{*%_U+ue
zd;bnTy!i3t%bP!sKE3+&?AyD44?n*A`Sk1CzmGq^{{8&^`}_Y7V1NP+NML~m9*AIq
z3NA>|Z`NIh9E3suC!vE6UO0qw(@jX>g=+A^NL7+8Qj%gDp12rp`BavdZ^P@TQ)U@slw(HKsH1)Y3YU+ckk(_Mg7(QHnsI(4VqCI(I4GfDQd(%FIDL7UPGqtA
zqNzn{Hq4S--o>e&V_Di0ue%bdqpeJSm=UPVHI@F6u({r0^1p+)NTsx
zo69B&qpCp`8)mh6^7x~-HefYvlT3C*Y7XlhTa-SY8cMFLbI}QFxZ<9bZmaZe%j{B*
z(xPm=7|9juUcT0pFSg@qs|>>7v~JfgV{U+nR}?ml}~sVS>~3_0&ZBoUqeP%XYQbW}nTQb7gnUw%BVk2zT6a&rNsTcHfP6-g@uNci(>h
z4S3*!4^DXDh98c2;)-)O5!fa#4teB~2mW4!#o6Tov)hwz&Uxp9D^*D5Bw+5i%buT(
zdg=nQ#Ltu1z58(5s?Sb)?E$v_DJfSGB73smm2P|R!VfQ7>!DX-eC)TP>twOO|4e-J
z(oe6Q?m7aL6YokkWo-3DK2Lr4;@b`wS;~u&yzep-Q~hY}zc2du^3N~)Kl7e1uj_g8
z1OC3}@=3n{3UGX;5doTx=Y%ov&wJ1qpaUOBz)yuBRAx{hxZVcA3~F$C8ls>-=ybl(
zZE%Dn6%w0>sv`1mh*XT5{uI-;L??+ui4VHs2T;hqDZVL)RV<@|yvT$sVs9KG
zQls@+&_gJyP=98ug~%I4
z(vXz&+a!6YNH!9zksXYq&noB0N{aG~p-f04?XgLtUD6|AFw7@IgfsZba+b8LSS@9V
zv0J_`m%6N3FX6YdU)oZbH*{Y&U}j7j?ILFsGYv6)`AkYl8D+v+Slgze&q*-mqmNN#1anNJh7mq8&)7r|H@WlKbhCmHBL<#KK`uQwo%y
zf)pe6o@cRt+GPorTP0-v+$p;-k}*l~oTo*Tf>DC>D@*&-L`OZ^PkLq)SE9KnK^@AC
zH@;J%sN`rESE|1kCUlP=EhrrQiBpkkbfh+enDQ*wt9}YKs5&JnIZT?$la{htDs4^z
zV}=N(zSOBKwGc#6(9oqyYM@CqDp7WNEuVhWC}SmSNKp|`uUbN$Ek&s&ZFWKIstKmvjM@=PE4IeE7P<@r
z?5QZbT-2slz0D1+aaAJT*AmpKR*P*|mIz+&ChfbP&8d6IJKC_4tE~53Z-Luu-tx9q
zzT-VDZ}FR5%RY^&_GK=8Cluf4COE*N4I6HgD^(DO7_l3U~EuA@R=QMkn(GT`>nfn|aW+Fk;N&v2>;|IXS
zB;wQDBU?zOe7w@>a-_=lgLCNDJH+W$(u5jJ)y5uZxxyxS;^O(zg<}|Ol&2NtL
z{+#Q4=REJZ&wmc|pbLHIL@&D0kB;=DD}CuqZ@SZ;4)v%@ed<)Ny4A0a^{i`s>s;@;
z*S`+-u#0`{WG}nf&yM!7!L+_vL)(hk&b7Ajw(W9XJKWu_Ikg|EL^C8-i97?n7H)T2
zem|MU&ilXZ_B~{={Ma%j4)`{g4DgFj)oCifGG=;E49;{V$)w3Moi#p0pC2a15D#k*
zDXZ|5FBrvF)Vz^Da)oPb(=zxaS=Zx>qJmv`^H87gs|ehu{t~{Mh{e*^&;Elgi6!uJ
z7Z1#HepJxc7bg%Q`+zkN(7N{*Xb~O!--93e#%~w?PCtB*`2v8q&$Z#7f7#LgA9rVm
zhkpWFIe$|#F~@8Qi1|tUFsXH0{Kp#Vr+ru!fJgFv)~8(zcYslra`TrynCB_}cUF2t>Q1KpVI{t9KOL6L`!LRrWVQ-j_|M_W)8u;YNl
zM7RPlN1f+;N$iGw(RfC&DH;b(~4SA9x2
zEcX|NeV7uXCyD=)F@r~dsup=P*i337eVo^L3n+^ES0`uqJ)y^nPUtb6XN!!8i^s!>
zzlee9_k*fvgiZK>#<+2_xQh~Ghsn5iLD-9u=ZdXYjLN8u%Aj{(CN*_ucX&6BhMn(gK#nD41BX~~%Q
zc|DbBgu>~G@ELGof((V;Ay(~mfUGW;yEioNt71q
zpB;K6QaKMA+87Ngo%&~@6Y7k58K2RakP3;D9@&y{C6h5~qa68?F!_%%8c`YPqcMq(
zH;JP&N~17(qb^CLFPftu@S`nyp)RVVNotZodZb8NlPr0qR+^m;-`dKZu!%jDN`3xbd1N49}E@#Y6t45eJVidA4V
zikskCAMOeZnIvX}cAYfAt}IiapoB?03a@FZk*jh_EoHC!iLbfEq@JXrgBGR#3b1-a
zuLLV;=X$V!3N7sVNdfDya3im*5V0yoGd#$uofKvK3P;ttvHa1os_?OS)~$fauPdvf
z7~5GWo3i>Lvy&!h5<9W(IjIOstCId=vLa-&H;W%Ri)X)~69*)+Ub1KC0<}-cYNd8~
zuQs){gleybPFIVyTw6|Fi%Y#Gw#qcN((-ty$W2=dw!pNu2)DK91h?h{w^m!VbK6Vm
z^i8G~wspH|qK3B}M0&OLSosQug;t^r3uyp$uhi$VmZ)fSgr%a|yP8F#xhq+=>k_l8x{7PCjQhH-+qv3xR+bBarwbLzOJT#+rP}n_S7O%*uQ`
z$$H$%sVvL4d&iLc$PPNnWSq+~oXDjd$tUc|YD~+PcFCCR%CU^h;AqBH9J00S$id9I
zZM?{&tjj+fxxZY)!ko>`Ow6yW%z1pw#r(~6T)5bLxP<)7pWM3DEWJ_8%M|R)4a~&l
zjKj%{$KYJV;vCM#Jj>fW%;s#%(A>Q1{LZ`F%k12MjV#aPY`Oqly!f2Y_I%G7lA@zi
z(WQeq?BkkPreYNx8VcN@~FHqxzD(k3mnw0LVB&CweT1Q$(1U3fw;jYBfs0yJ&3
zIjz$>&C@+@?bAOE)IlxOLrv60ZPZ7N)Jd(>OU=|x?bJ^V)ln_gQ%%)XZPize)n8N@
zG57=0oYgsPmYNF1Up>?(N5teO31>~#K%FcXB#525)SPlP)004R>004l5008;`004mK004C`008P>0026e000+ooVrmw00002
zbW%=J009A%{jLB200Lr5M??Sss*NKu00007bV*G`2jB`43=;#J%-`Dp00#d_L_t(|
z+U?riYZO-)2JmAQ?S*vPyOe?}2<@eoerUlu1uuG~{R2c|8&ILu?NVrpX`E<;P^jjj
zH>Ihy-q;JVBBHj9n@O}JS8D{pkHqXmLL(*WBy5t|&Cbl}d7rbJoMao#$Ie8mjD
zIq&@T?99&D(TDLU9_`G*a{=2x7Hw=@wPax{$NI8lDy3(&HwY$IV~cS?)dLhQjO)U<
z5nd{ZpC;^c089rM&qS#Uj2ox1zKiw?Xg^_4X{1>)h4d+6vI!~%2FA5u+@NHPk|g%|
z7>p0bm!(!Pou6QzUDO`DiS~DGDh+Oy%&;F9<2+-#GMfU%1-vASY7G0l4x>=cj62F~
z+R*NT30%o!>#B*#q!q@+Pfjv&Dx0y-w89kMv>(cu6xtmNr7p?vy)hbh&sUgkWj0%v
zXWFJ3g=s85)0&kt?cp=dv|rJ_3Z?$ynHJIKCK856@o3k~bIdq+j$$Dgz{hjTK)4G*
z_5iNXy*t8P2>5oI4Zo>gIzw0pf;5S`q`92(*+I`_J1O?2dxJZY$5Deohhga31
z7lP-CS#Fok<;Og9uoGDJuoL0
z$4p4Z!jt&07i>O;zx(IIWZZ}t>nY5_A4|kI5i#b{FwIr;+rTwOk9Nk^GxjQDYZ+V3
z*h*0nUxH1#)aBybi*de^^CNQL9>z8?_A+Cu#6a0T+(6rPq8wvuj-f>NYTWyXIlG7{
zU`~O}xzO+6rfghPapxdjnK+{2li)j?*NK}K69W@?*+ZOOcClSv=rf|6;qE1r#!za1
zv6;4LnAEaj>dTnzVD2uCk?rFKm?j$LUO;KoC^9A(dvT0xm$yzCY+Xw!X+|?qG5uh~
zWuA(0{F_M^=MOl2YtNbZTFuy+2DY-Dt>|a$8^*Sp7#PDhr2%|XDz>kY`@~j$O)iy|
z;hnT*G@}{KXeM07Oj)V$8P81d2pGQSgVU!YVD_bspNxP>rjA6x984WQ9s%=dDw1Qf
zkcVb8qZ!R;Ml+hxOeBnh=g=b~6da3B1;;wK(YTS$xEL3_-9@Dn>xuDdn#De8E10Sc
z#B|0?QOY%RB4p!WP_B)ZcXlHKWfQ||(Vi*L*uo!ZA4U6Rw2z&h9vn+zpFK3r|Iwy#XIiNAs1M8z
zdeiuhw}`R9xL^Vo?QM9^-M`R2iuR;z-&+cf83>NmQ!#zh6yvh3G%h&UN~M#%I5vH?
zbZq*Xh}qUhOt(c$-a&gkX4Cy8+8t{5o}kq7dnq_(A~=R)b3a2b$Hi=dLA;!+VEi;O
ze)>0J4yTE+!4w>{`xt8!#mObI>sIa(|?27bMi!8m0WI#E*(_XOmquD1Wd!s^=9^<@&hG4
znlr$}=M_{|*PGdc%8n9Lrr%Bc7mhQJpt3WUpz?Jks7%HTX3jz7_KH;2`UGW0%v|fWo5mYJ*ceCW*Rfspt8E&%pO!8P|h@uKmAP8LFEcC%k2ui
zM9hKk89HD)BVmFkFDes+%>*X4pNGu&l4;?Hk1CAIzpWsX77Ie&neZugEoW9_hRym4
zGPlkO=FX^J4aS;eDjZa96^r2b-LC_in6pz%g@ekLe~OP=;`WP}mdRaLI;d<0)!Z@8
zOU752%0B33&f(|zV`4nzO$&qR<|7nT4u}aQs4VX3y^Ug-8$*1Qm{5Ysf>BbcAuux9
zyR^*0A4|l@Xz#LRnybWjLP{F1XebXVBWyM;sQeORD`o_h+5ZHUUqMh=G?oRGeXBfe
zhv?k2wA~>rR@2gUd|nCS7m-P6X8ugwtU={PF>?-$GZkk>xSfzoVW`X?x6KHc;M%(V`@?7adv?vf@R{sA
zdrt(6d)Kb137_fji7(*T{0ACVH0$&|GJ`+|00000NkvXXu0mjf^Jly4

literal 0
HcmV?d00001

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 34e3251983c4918ac5457a27d524ab1eaa54626a..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 5095
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
&jXa+2yra$>%leGa2W`o$ysgAs
zUdBAhZhCIwtfte`&j}aME|X+-%W2%Ogm-%HJ?}a1InQ~X@8|iR&tK2^KIcn!w6~R)QO^u^~VTf_-496TH+E|PwhL`wju&f5O-yp)&^P)|A&0U#C%09StpfFI)4)z1JB
z2?u~_G5}yf08k0N)!<|%zSv50ws!%xY{^}(`b88wTWbKglc9|ilMD?{w2^r)w;Q4;
zk$?OINkVz8DM
zoV;?K(~|Y;bPqPz91!vIn#@QNChywP59*UdTP6Lh(svhUr_Yt#?FTQpxSt{^M=L%S
zjSLqs^CwO1n>9?k7PDZa#A
zIQG|+s)aZtf>Y)KV^q+cxIc3(dE90!36V7p=8)6K+$v~epR-rKYP=>-TeSuLCsW6M
z;Cs)g;LRI4cxKt~u6d_f&NU6{n1h0AzbWWn10i^xbWUBVb57cRJlMgs~
z$U<8>p7nP>Tc*=@9Fgqy%c0e-hTwuR@ojux&FIgYx3S!vPvR)v(u|{l6CCS-Cnook
zwkM1^=n^d!4A7t2bJ5G}(e~tHEg#q{x9Pjg=?}*jG!YvsmIfCmLxVhKj$@n1AFbilv!>h%mt
z()+EZ<6e;*3!#LHKKyvC^21aegi4QMzCpu_M1BP3m6uALOWNn$_)Wvu(%@3%xWBdv
z|J;Zj&c11H7enAoGrKYNES87Pd{bmPIMX*%sS{Kbyd`y-iNUz+tb(lCAY@+tjyHtEN43PWPycS!$puwV6>5Q(1UGORR3KZkb(~
zFZ`zJB5_k@AZ#6nn6xQrb~n=yajd4)3`%qc(j3T{vCcPE0-x^H8!IuzTEKJ`AMQoL
zn|==nFYhtW;&|*aXGF4`icBcJwT$TqTV~md5RUl?1w%FRgPmNjk|~ap4-MBS?z|3Z
zix_HjW$XD;p!z3TqfbAI33!tjG6_A@jPuG~A>L?fZkd!EMfS`w-M+=($BJbKnpNg=
zk9S^PK~#Go6N%BYx>F#X`75UOP&xNje0u{67x@nvSFf){U0K3Q@)A}mvJR5p5n2_c
zmQVZ;RLFvEudaLMyVn1s{Z~GzDwB0Ki}5CNd1f%I(5Wlt)Crg|282T6wJm!IGrG{l
zLkLCO%l(*VRrV6a^WTFZ`^)~gy9s4&wA@#>|AFejqi_d|Q`k!#-=bi~UwhAX5n3D^
z&NjuJK}?7q(edUNDmWAU*ijlzv`&`pbZ|lEIn)XsQjL`A`uJJ_=sQ*fv3FwZut)Z0
z-~oY1>9i2CQ^?dXdn+UpAnFp`VaPGEO-#o{TyFy+fyCzY8m=)^!uKML?
zns8G=OL)vJqs{Vt7Q0m~9G*MRbUjs#r=X=@d$q-SAHzs->C#zqYvT-t{noEzzGE8dC9zg!ub9n
zF6P1rVz*povhN7rdYypUikdz4mN2>j+4|&4EJrPY8TBF9j@E7Y5u^ueUAt=XvMW|m
zPJaz+95_)H?PB>+elXwB@i9f~Ye3a0`{jSwJ#q2;3$L(SpOX4CDvuVkYxFaO3eH`J
zjw+Mhk(;+kpqQ4);jscK*JQf_pR`S<%W4V>0RW-J}#jIF)W?h35P*
zWmcP=yTsCQX03YOc}`888utdZ&sSZSMqhw!!y}SqStMZ%4-oBV9a=3kHK6)
zO9i+YCLVD~DCytACmMy(O}qMI9aqCGJV-?Zxm)`WeOg#djwj+%afK~{2kNypzBfE_
zwf6Y^yh!FH-7LF3>!*%_$>guWOts?I~=NK;mULG
zHt@yr!KKeNuQ{b@K-)kXgfW4$jEoLJ-eCyaX0rFCL1A~o`Z`n1)nM20qf%oyF
z=O+ZOqNL1%;!J~V%e0J}hS}k31ecfZz-=g^R9@o~$)r9QynUQ6o##PL?93-t^bmNo
zjBPp@iWd|67$T{pKDR~tian$oVU8x^XZ6EjsTH
zttrro^v+d(vuWd^zHY3)_50+f2=mO}lwe%~?54ivo)>>4bZ9nbXx`^(K3HnFkGKFx
zI06Ghz+p%e5(0@eGRDG}H|Bo=!uXefFu}r6e+$#ff>&Yz
Nz}whcR~;uO{s&NJSeXC-

literal 0
HcmV?d00001

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 b02434d3b356c4646c47dc85dd662daf54202cdf..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

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

literal 0
HcmV?d00001

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 60e8569a76c92e7ab45068306dc736771fa3a61e..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

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

literal 0
HcmV?d00001

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 718492f1cfc703e6553c3b0e2afc4b269258412b..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 25323
zcmV)iK%&1#Nk%w1VRZtU0_Ok#00003V2Tw{$43>q3cXxL|AOIQ~RAw>&E&wTacQ`vc2LJ#!QvfLd
z0Af}~2V!Lm92{9-ZD1fb01yyO003nT6+k`!09930NMlGO3?%>nd=m#UL?9qbOG_{^
z3_evpW@ZdVQ3qjR5oTfxS~d|m9SZ;eR7EWs?(Xh8J3BWwH+Oef0FMAQH8nFcGaykQ
zH~;`bLJ)BP089-HmzMwlX#hk81tTLP7!5!=C_L_`@CTuDg)ZeUBDA0D2w_
zT2QFKpFsi0Tu5}HQGsGcZKP=vTb_Z?Mge^@3JF085~$kjI#3LN8w8sUByn}A+qZDz
zs#L2}DaEG{>E@LH3tCQudY=N|>$hQGyCq3LgVj_oLcG1iOhrrrfLCZ-7enjigy0P%
zLZLa4DzLKUfqIc(^D4Ks>({XJ%7cmbVQq(wanEMDd!XRnhJnMnEwZuj$B3a~<7kxV
z4YUK1yx}Vlt^=>0F4Yw3<=Zkf#!6t9;ZMg^=~Y8
z|5KhACpG=`6n;SI*WP7B5O~&p@!3a^SUo`~p+H0_
z$e@EC+O!je{sH(#PAd9l6D*NolT&@z@I{||P`NlCf;iRpS5RWbSRZ?^;8Wg5YX%Vo
zDWQe}&=sJ6aW`D16|TA%QT~?x31C4)?c`~OFZR{yVI(?{N2l1-$!eZi!jdayeVW?k
zSxE3%=CjX2n&fioISN!kiBu(tjma{+%??%+o
zM$eWo&hq3qkOVdFwzRRpIZa}f0S_irkpfY<>P?^F+}0c4LEEyy5EYsA+HAM&_Svw1ORqeN=qWNh@7_dh&O;{bxHFRsst6OQbDCyj{v|`
z9yKUQ38feQmztHPCIz_R6pTc(8I=!B^`}5dj#btwAO&T`z|1M^FLu(O>7YfnzAWg4
zs`8(m28cAqv_(`bbYZoI6CrGsOW(?$)Yk6&p0enMSaQ2;c
zsV{|yEJ>j}m&oY>r#?=Q3>lMEAF^mDY(hCwWgao0{CGtuNLbL6juIiKWwLPq62m1w
zi4&lZ<%y(Z5Os(WN-0U;k4XFvq&bD1i{SvngTHfsi#6P>{2g1H_2y-5*EOO
zB$T9y%Or77nk32zp=`;&BdRTIebI_BY2=;>7DRglkyPHYSHVWQQzW2zXI;c|#D$Pc
zo+$nSR6|rrwD+~<2Gqf)KnFU!d%8s)Wpju@2|AKdSg0UlLIM(Qz(Kg^lc5;RXm}P1
zCyr{gBZXPWL~8=hxP;}SC{3wKSIW|sy7Z+mjj2p$O4FL!^rkq?sZMvw)1LbDr$7y=
zP=`v?q8jz6NKL9zmx_=PNaCqbjjB|qO4X`b^{QCSs#c-OC4(Fy7+?*nSjS4%vYPd*
zXickH*BaJ@#NZTgjjLSeO4qvD^{#l$t6ujC*BB&37)uDOUd@D
z$U)oM+V-}%&8=>C%iG@i_P4ZcK|-FugyI_axX4Yea+k~8<~sMe&@Jv05|WEpSogZv
z&8~L0%iZpJ_q*T?uXS^g5Jo$E*Ul@Qts0=lk0Qgm%67&98o08(W0T
zmc9TEuz-0hT!auex(H6Nf*1VU=^~`M;*GF`Crn}Rk{2Q7-LHl>jNkSiL>})Qu!u(t
zVEZ;iv>Z;ciuo&B61(`tzAf-U4$R;h+xW)Jb?`wTT;U%3_{ZJ7@If-X;vyTl6CO4Q
zh+)j+CfC-)3_Ox
z$wdjVmgg*BC@;hgQ^>QP_sr)$`}xm+4z!>LO=vyy0U>^HgQ6GB=tevG(U6X`q$f@3
zN-Nq63GqfZHqGfyd-~I$4z;L9P3lscdeh!WNEDjE>Q=k@)v%7WtY=N@THE^8td2rL
z%uwiF`})_wCiEToM;c{IK(HOkczi_-Wear#$}Fgj|&9kA`d!)NiGnRqx|RR8XZ*0;{}u6zCKU=O?4ukH*6Afz5%NW0qC&i1yu{q1m%yWHna_p~P>
zA?E0U-uKS;zWe>}fDgRj2T%CI>)jj)Q3Vhd&-lhW{_&8HyyPcO`N~^<@v2BjE5^?G
z&U^mzV#feN7%+jloBs5uPd(l15$~qUJLdw~xzwxeb65af=(vwA(P3e9r2AgHN{0p0
zUEk)XFM0MeZ$0s!4SQI~9{F>w{q1v4{Tx&G_t;N!d6)k0a`!?%-&8+{&AH#^=0E@Y
zPL_W4*RT8QXaD`-4gT=SUu5G)9sOAjzd_1DkN*4r{{R?(0yuyKSbzq2fC$)sr62$Z
zVFGFJfDjmg5;%brSb-LJff$&98u);ekPzAM1t1uLA~=F1Sb`>af+(1RD!76mm<dhG>|EYPg1M*oJQShHw~%a(ISD
zkPz2U1$dZ;dbo#t*oS`jhkzJ}f;fnHcnt{=0sf(oh>Ey~jM#{d_=u1giIO;pl$eMS
zkPtQyhMKsEoY;wAmS-xkMcN=^jMGfc#rHj3}$x_x8Mo>
z_>TY?kODc71X+*6n3Ufbj^Q|tL#blsXp}IPjsjtgPpMzoD3ve9jY%1cOUabX=#*EvVNt1-
zBu166V3lJDZAEF8F2>mbECBYpGvl>6QbAmTGyI=#`avIbd)Zm((|xboqXE
z>6h!3mw{Pg4v`5p8JUtfnf7>S2QdRbnVFionFpBw3GoeK5SpSnnxt8prg@sEnVPD(
znyeX`-;fX@00^=3iELp6um)
z7H!qU-21W)rp=Wr=IJ1bnQu>tL2^d>09#&pnpl80}5aHsh|JGpZ$4q|7oD8
zC7=nqTWEO>kdUDox}hA}p&t67AR3|~I-(?+p?$EA2EhyBu%ay5qAvQPFdCyWI-@jN
zqc*ytpO6sgFa|u@qdxkhKpLb%I;2Eeq(*wAJem#(p#qc8q)z&zP#UFDI;B)vrB-^S
zSlXm2kPuK%qF(x?U>c?*+6tq$0ylc5Xqu*KYNNdHoD!N^(pjOswV(_NaPIe@zZaoz
zT3Qq;r?^$1d&*+=>8Jj{MW=PDZ4Qd32Dg2Is&4Q}s08Y!jY?W^3aPkdsD}z>iK?jK
zrl*bCrQtTB@chq9=+FD!Qhu+N!QPqdAHYa3BY?TC28ttGJr0y1J{p+N-|$
ztF#IS3GoNNP^`v!tjLk4G;x~K07sqreWrA4px
zimCW&WBR(UKGv^q`mclac!_mK|^jB0I7qTe2p5
zvM8IfD!Z~Q+y1g6i$Vlp4+}7}G+VPad$Ty3vpT!8JlnHAJF_s55VY_FL|e2*d$dTK
zv`V|QOxv_h`?N$$3kjhNxlpxMd$m}bwOYHiT-&u?`?X+OwaSnXdf>8Vd$wqswk=Bm
z2q6YP`?hc!w{rWl_P|tjd$)L-w|cv`eA~Bv`?r7_xPm*lgj=|Vd$@?3xQe^DjN7=5
z`?!!Bxsp4%lv}x$`%(~;J^pkb0&+-(5inH3GoTAdGExha6#X=Bf;T39u9qn7d2Am|&AwONiN%QNu+yWT+i@!?NII$x^*h@g%
zgDwZW!Ot7O#xhOT(ZC2HKqnJ0`y)G*gS{2pzZZNoH_;36#KAIbxlSMf5YkVqbixMF
zLcP#cLlMF0YfgBC75rPg(eb}!aT*{r!%Qr>k3dmals9-WMhtPkL9D|=TpG(kzR6*}
zo&g<8+{9wsxEF&BFuO$qg2W18#ag7oi18D|JHf%!Imr74%KK1boX3nSI7a+6Hjya)
zS#vT#?7BDM$2AeUH!(F9d>`U8G;OTMkQ~X9Jjs+?$(DS{G(`fvu*sZ^BqDK3oxI5b
zg~_B`%BFnEsGQ2GyvnTH%C7v%upG;>Jj=9P%eH*W8WGC6yvw}Y%f9@}z#PoN?8~Ff
zQVKH6$ehf|yv)md#wvBp%pA?qJk7~`Qw&1Q*qqJU>>(~i6WpuK;2h4#3?O*?QQj=h
z=$y{H+(tIV%`WB6EJYLLtWoj|Q}z5(xm#24%u@TTQuo}=VVqI_+*0{WQ~j(`2aQq#
z9nS%cQ476N1wB*TEDVfL(H4Et7@g4?z0n-q(H{NLAZ^iImC)v_7C5jAD4qV&D!tMy
z-O?`o(l8y9t&tDza3O3ho-5X~8sY0#S>R6nN-Prc1kEp@bDfQ26
z(3+Ng*_fT#tjPv9UDyKwla3wQqRo!SY1J`>)qG8TcAeUzmDlaO
z*R+jst1a0I4cD(7X0Z*>hMn6;me{vF5NsW&el6S|_uIhT*|I&{x&Ce2`kX3M=!w{!
z-P+xSV;I?=z{x0*JQ00nYi8V{odFOilvd(E5*(HXN35j-}+sE
z3+Ua^JrG(zhyp&~1YY2Ss0Gl?+yW7V``zFUj^9W)--=z8#J$`t1=!B5sR@4JvrXI7
zZP2()+ZN8yuASjH7Tg>z-5ze-)s5U0zT4kzdnSJ38&2XYN8BGS(W!!=*V^Mgj;bii
z+I8I6~6_sb=U34hy^%>7-ujj$YbU
zo>Hg{=>8q*flcVhh2l2u=F{EhWd7$_9_X$P>w}%=y}jprJ?5uf=66l!zn=v6-9u)qUk5bokW?&MzX=6>$zp6=?t?(81!
zW)S3+uGGDecZOH*_I~g9PI!p7?6VFFi_q=>AMgS{@a!&n&mQN|&g$6|&iqtxoMSZtc+Z@NJIh&fe{do|Z3u@%`TZ@X5~cdfx0Se(-)S5Z4XgFdy^W
zO@@>nW*IKJ`>z
z^?+!I{0{L0!Qf2a^*Z*8t+^vf9$lr@?zieWUufwf9NL9>uYc6
zD$nOEf9nZv@e5D)Y2RSJj`wY^_ixYl-wt|;zxa#~c4cSw9d8cbF!_{U`IdkAn4kHY
zzxkZs`JO-d`|k6HzIlyb`lhe=27ma&j_YPV?Ij=hYCrh$p7+6S>#N`Qtq=JrkM^*y
zTz5bFgc9T%-~KcG1Is_;13>}fU;p+m{?GqX=1)-jFHlgu`v3t;
z;6Q=}4IV_8P~k#`4H3!%AkX1MiWMzh6i5O9Mvfglb_77;<4BSvLzYCDvLZx@DqX%j
z$P(tvnKEhKOsNs)PM9Zo{sbu!=+KoBi5_)m6Y0{2Mwvb>s1xc`gaCSxz?xO-R<2#W
zegzv=?AWkAsXm1`itJjpZQZ`bI?Cx;rfK2c#hZ6+uZ?v50stIX@LY}&PL-^QI=
z_io<3eg6g?T=;O}#f=|Fo?Q8I=FOcyhaO$}bn4ZuU&o$Z`*!XW-$)=R;SE6~LLqV_
z+zZxuSn1dICCC{7wmb?4JIM@f)SLMvkh~}ChQfrBzzM*d08gO#3X&_c?jD3NLW)SZ
zfuI{kAxJ9r2ogg;0B-oNDhCB(Z?1thJP|(e>Jw2QB=-9cnm0y)1{N`#aH1d+6?AYE
zCs@qG2@Klx6b*z_1*mHCs
z5>&->%)TJSvP^YEfxKj#8gPHc>X<&8>{jI~;8k8|?BH=vyr*I?Zw;SFjP
z986fkL`qi2aotN7RD+oHRZgs^Jayb_@5Q$_1oKc;9!=j9w$nFyxfIO!evLOwEGsQo
z-GN#aBT8r={*=deMJ2Vpl;OseSm#H=o
zfKlCbGUK$_hCFh~C#Sq}%P+?~^H@pfrE|}FnHVMsKKDF9%}+-?b=6mAy>-`Lhdp-L
zXQ#b(+i%A`cine~Tpr(l2R?Y=hbO*xLFt&Kfe;*y1Cygc~BF7SV`DL}C(^xI`v4(TPta
zA}W3;K={Z520X-K7PYv=9STBM-+GQ&7C;U%meGu7L}MD&xJEX%(T#5;V+*F(9HrzU
z7I(yB9`(3KKK9X%e*|P81$oC@%#k?~l*cOIxJX7e(vfdmz!wuZkTE{el9$9J8|8Q<
zApWL~g9K$LML9}A7Lt=xJdq+Zxk^@AGLjhqV+$Qq$yV0VmYOu=1v6tuQufl9zx<;q
z-~Q7{-yl+zw?t+#$?-~9u&_C1F+m!nIZbL-)0)@BW;V6CO>TBmnv}@p2nV8uHk8wx
z=R{{Z)wxb~w$q*Ogl9R`5Y83CM*#2eW=E2SsQ?6}nJ{
zHq@aHC8!bTi5#UwAQTtHXht=D0ag1qGqOOve&SVZvi@MZD;xwq`n+q>}I#sF$)1)b^
z;xU=JRY=OTg0tjmSl#GU4C*hcRYhxB@d(ti24|>Zg=-p*8p~%o<`$m7YhLxb{#U;C
z)vtdAY+waDSiBbFs>M+X7+$eh#x~ZmkA-YxB|BNlR@SnM1;b$@2pV1
z*jsotI!cXeYU8Nc44zf3ubnDeiP@XCsy4NAouoi$XAjm%>Y3?`bFeVVhc*IlS0H9S_u0>X4l^$zJmeWe
zIhjY^AcmK$;U;&`#fGk>lMMxrN1UU5!aZQ#8}5o-U`c`s8hc`r6E;bh$6t?Gyff8{EPbw@^K;?nc6T
zIjE&~Q=6R|6u&#%`^HVH^UX+mD+k{LXC%9g({F#n8{oGQIKsPnZtk|%!57E4VCk#t
z8w(^Jmj!vqMLu%N#^d3(QEB5OP)X~`V<2+sKXOwz$aa{GIpS(6%
z|9Tm@ZXC00!WM6bd)(zdce>Zz?svy~-u3==!*U$SuuugM1V4Df7vAuPM||QHzj($s
zUht|gJ8hnghrL(c@|VZF-Zv5INyj|xQIGs=7*6)8UjF^MJOBLFIUnnEr{0WVFQLsz
z-&4~A2koCa#C>=w);JwCA2UVti@xmB0LkO4RR(&WtohI(_O_-})kz
zhVWy9NR=|*``=H#@rPp;F&NPN_R~IWlyZLdb1(g`k)ZS1KY!^>45{~4AoRog+ub}h
z>Cd@8gUdf}<3HW-Ke0P60HiC{JGK3Dzyvg|nS!4QoWKI)Hwwf+_p!i$%fJp4pX$(y
z5EQ`?%!-Cl4rn036jVXCFu@I4!54(Vui%{-q`?}r!5hTE9Mr)bU{nyhgV^H{)zV3%JR{*1l(7QUI1gm4m@i5l|>3G+dh`(P2P
zI2a4z6mq#jypbCwbVJjam4UdB3}G6B=n%jF5xaRAs5!%(d4nxHh?BV!Vwnp^L6LCz
z55UM6fN>GP$UhTlt2dOyr^uE@oRTW3!-CKfF7XmQ>_a|;o0wUM?{GrHVHrk*8H=%s
ze?i4mNfn(roJo{L%@~xifx<(PfJ`I^MhO^Lgd0%oMTSX;Jb02(uo*(k3_}bSOOX>N
zXp;@ulS&DlsENc`w8o!^L$w$PTk#f!*cDIw#f0g@Q#1%;q>?9z#hmHIP;4g0kq0M1
zmcEciSlAP=F~w`dN2I94ZOMoV>BfWpC=YQ#lX79ib3sLRyhnlfLxprlgE1e8pc^MN
z8%<#kPZ0>Lu}6c<$Bi6{ed(8f`A2~v82d;VU_3}+JP2a^n{+%yWh97EP!*>T681=(
zz}P}a+(3@hNsb^HZEPmO@SSf_8HRuwlRU(?dC4I;#~MLKgzUvgv5}D22$ZBprKHB3
z+{vt@h@_cDMkEubAN~sSMF%Ve5hDFpGDWOZhyvxkg%+2J?
z&h$(k9o%5)Xw6ZhBesE?*vcY
z92RT{&+;@+0AL66RL||K1^}pr^@PvrY|r6jllMBj1iE87lqLnmC+fc(HgbU8^zHa)lnEN7yuB_LkNZ-71ALk(jqm|BSq3A
zRnjG8QXw4(4HbwOIR1qxrP3<3(ksQ%EY;F2<I0FG8G0f#n2tK(>uk}Jl#=X7zh>BnkEI*Ko!(MZPG*VDzjjOPEgcEWz
z)JKKXNR`w{rPNAQRC>q^A8kF?TP=ZrQdoEbCJ@z8CDl?j)l)^)R8`egWz|*{)hD3S
zu>(Gwi&cSu1WU!$T-DWGt<+2CQ>9D2^+Hr$CDvj!)=94^U_|$FXR-W=!69rdzHQ0mggmQ(2b49LZUDttVSA><=aZOeQnOA!4
zRDU(mXx-P2^;m1|*MAMz;LBDFE!c@g*xOT
z_1dom+p6^jdyRr-Fx#_5+q6~NwPoA3b=$Xv+qgB`D6m&E@Y%b?+q~7=p523A9SA;v
z+Q1du!6jU%^@BrY*OXOUVy)QrxLAyR){Xtx$)((DwO4>0Szj7hlU>}-&DE6!R@_5e
zi1pn5(xueK)l|=;*T}_Cj;-9+h24gX-UuR%|pcROE@PY(Z
z;00#j26o^FhTsU6;0dPS1Wp8dHHR+H;0@;B4))*=2H_AE;Sna`64qdIu-CwIycK5Q
z7ItCAgS?U*h*l8b8n)pZ#^C_Q0KXLo2AF^f2I3$V;vuHsdeGkAb>H0mUe!%k@fH3E
z@-^Qmo>uftGW8W$+f8EJgNT}ELPkl&Nl3I;(L|iGp1H5h6U%f;_|{`F!tOn
zmS5NNVmS6(F=p2AJzg~CV^>vUHg4lUVqaL8UOSdpImTY!EeCpFWOJ?L!5C8*)g=p%hPX^^s)+TV0VS&hoFF@r~R^?S@-z~o^j=3+MHOHKwJhJ||)?3@O8a1hT=Z<
z=u!RSK-SzhzG#$16Yc_
zm=@|+yZgY4sFv!frs}G;>Z``;tafTMDByAy2)E0;uommF
zzPrBDSPV6XZ&2&CX6v?g>$isMxR&d=rt7*^YZM0NbqIjH=Ig%p>%Rultyiq&S)lX)}R*c(Jt!JHf^MCZE;m?hh^>DcGu4~USRI%*^Xk;w(U~FZQnN5
z-JajxR_<^G?j{ax;^t%HK5jrd?dJ|x=BDE#&V)z+@9-Ay@h0!`Ht+LB@AOvh^$u^K
z^=epfFP4+1!wREAFu-h
z<_lo&38(N1xA67u+sXdh`R4EjbGe`VP|ntFV~y_Eo^I+sW9z=|4NLA3*H!KgR_Atc
zUM+Dw7H$;pV-;UD)Kr&J&>J{gB{
zORe#ZPI4tzUM6qywR-X@k5noDI^R79NHFs=NAomS^EGGlHh1$khx0f$^FHWm$E7lA
z!}B}`vs|-pfk=lj0Q5i?^g$=|LO1k7NAyHj^hF2sbg)-6tFuU#^hu}mIlD7ph5|X)
z^iAjVPLK0eP-bY;^HC@DE3-BbmrxN0^GdyP-pg_=kKNkt@;>VERgZFI=Hi{Ea$Aqo
zR{uQNhV>hTNB4AB_jPCYc6ax8hxd4w_jCR?0DIK}F2MJE*Y|zr_kQ>He+T%0
z7x;n4cP+42A)tbUSNMfz_=b1*hlluxm-vaN_=Fb%dlhDJ*Z7V9_GH#@fe-*1nD>z<
z`I0wzc_)A)rsjoa`IdM2ZXRb&K4*!hdGK?-K8J;N*5{q)`JVTAeCB6h_Gf`6`l7!+
zg2s7+e)*+mdX{hKk6-5QtNE#4K8i+l1+i#thg4rrJ7A~wvDC;iel{nJPN)K~r02Yp(w
zS7m^r*q8m;r~M~V27A>5$=Che=l$M~d
zKkcv(Zz1JZ4(7jp=g)rVPY&sCG3tLN>rW2sAAjvHf9^*P@Aolfxr!Kc{}=3!_m}?>
z>;VAif%(UOy{P~D&;R~^i~R=(5&{PjENJi`!h{MJGHj?28vutACsM3vabPb1ur|U1
z;PE5KkRnHtENSv2%9JWsvTW({CCr#IXVR=`^Cr%mI(PEy=~E}iphAZdEo$^A(xgh4
zGHvSgDb%P^r&6tI^(xk^TDNlT{_6EB*sx;9k}YfYEZVec*RpNv_AT7Fa_7>mYxgeR
zyn6TY?d$h1;J|_h6E1A{Fyh3D7c*|`_%Y*I`Zes>vdbco0IL^L+(vu#BH=_#ZZW!p4!=G7IP&D1N#Mo}%}KA{LW>V=
zu9P~*;@FjQ@9y32BingMz#4B|LLOMqsQ2a#&G>C-*htKW=3BZz+py@{hb6&@6Sm=&
z2XxqMwB2_JD!8Cp(A)saD9|8bU2)@0Cl4(0i~=8pu!!;CbGHGPopDYe0Sh)0!eSy4
zZ!q{Gj4_sF-3{+q=iv?h*PBoR@pht|0vV^Gcz!isUFK=eo3$DQ3r=zU_LgfUd5|9ZCn6pl2tAMxJ
zN+@x>4N4TQ((MNzdBOq98*{jd2b~jsx(cDQLy@4LgR#PS-L&xWDqOYE=@^u^xNbD;
zf!2=L6cPq*G|K*n=^={LygkOdtF69rRO_|-a_gUzKz`ecZT#ML?kMTj$?l>4y_=M+
z81Gp!qQ&0JQNFyDN3Oxe{>xOW9KpI#%uMkrFSLmA>hMMo>qua9>HYXEa~BIc@x~l=
zOqIZ5xGIlEh~B5)jwBwe-9}mxHQc%zNkHwZP(8A2jr-oX(R0zwJTjnJj|^pX8>tw!
zfA@0T^$jN?al?@Uqv$cdhlba6)y3TaAl6!Iz4zRW6UPzWW5d_(Q#Xuwvlxj7B@el8
zrwsS#ReoLee)?GsH`uBZDmXTTvuwD2%)!05v2w>fx#M)7o?+k20)BbOO-1c$=Wv7W
zcHNKbuKt_XS;Hz%@PA{-I_0k42D|Jd%u7IfBD+J>1Psg%~i-wikz<
zde{v)q~nsF=vgj1Sr<=8LR`H8Lr`=adwL-?2p#Du>q5fKJUG6f{IF!Y3Yx9tC`Rnr
z{t6qSQwsb@ke)~6VUTQG86xSVusGgPC=kPjjYinXJ?(K6eRRqnZ`LJ
zxXAnQ#*t95;)y89%J^~7WV)GG7_k){P$qGd%_-$6rvl0c$%Aag;U5WrR=OmHX^|+b
z%Gn48i?po~N0>aH2=jMDyTQtsPNS3)aRaMzKIKEo%8)aIf`n06sfHySV*qogL>o>;
zbFlgwhlHY`Z%)&Eqgo
zvg}$+u(85Ns=}KnRc4yjTCFv2ZM`QxP1ii@
zRd0B8)!to!8kNrZYLmTq1Q-np%$@xVu#{t3UWt;Uz)nj};Ibzy2?Z^c2{Vq{ikJys
zRy5zsz1E<~{i3bJP}*MVQDV52
zqsE*A0N*+VxLM?%oa^*UQq{?f)@<+CO6e@Sbs2UjwZs^<*EgOu{L%9I}-gYF9
z;1tmy$r7cF5+sp`In+qT3kiy+=b!`$%0l@Nr;)1WE?4c(0{+D^M=Z@`E@%15Z+Mff
z4IPwV=Ni`}`1P!Zk_V4O7m#TagI0w-6kE>|*{@z%9@-3xM?A3A(snbPwM7(57yH}8
zKD4f(YZOL%WLbme2(gI`?-U>VMC5j|M^@H3GVu@D_ja{^)V*k2TRKRxKDApoYc~Ky
zH``VFH#V#U$Rx@8-4*{gx#_cRjZlqF=8pHF-#zbS3q{YX-q!;=_nwNA{5Icw#GwVg
zqI<~$&La@2Qb}^ATe@+G)@Hv=^M9r+75<)DIW1X-niXg*ZkW4@gS~^g22dI-Gzh;QJ@51$neF=(CO2DSc!qP
z2&m~^hF}9Wj352^T=e;%+OeRtIe{tRS`lKM1Q^)AIYCII$L8glZGavji5?l2o87z_
z4AR9T=$Vd;+Nb@Skt9Xz8KK#s+~`?ajuc@b%HN^+-NI$e0|DRJwVcP<4Haq^@_AbS
z0bR{eU=W&J6yhNw-l45^j<>yC7>?Y%0pW_c$|Y`-|B+qLz24}NV)*T0TeOKSDc-#a
zo>CNIBa-5-B_fu!2qT6Zx%FUntjzumJczTs$8+3F6jqzBNPvTJAt+j!yg30VhT`H`
zp7e>0%!wksdBh4<;?jkkZv+KsAS~x+~z1#owLJAs%
zFved%a-yOcqdPL9L55y>hy(+;U98kswZ)l5jRX|hS%n2pQ3Oebabuy8+8tgUMuwoE
z1zJLy;+nZ(I+i4{%?Bq&gwxewrMV#hbXp3|Vxrw6K86HG@*_|NrBDtfQ5Gd&D3>9H
z#nF_E$#ln3mdp!Yg|{%J`60$r_KZfP
zTl$0-VnzzKrCid)TV4hr&i*A{&O~Ye0FYdSU;ZUvHpD2@o@P)@Nd+ciCMIGIW?foF
zkSHc(MrK81#9mfqW>8IIRt9E@#%6{_DuTvmmPSNyCShJ?X~N}c+9fS=Mre}8Xof~-
zf<|n9#%y{eWyIzW?1FSo
zCv{e*bzUcSW~X*;CwF$IbpAkdibg7mfpV6od7dYFDrW~!&T59nZeBts#HW1DCwOHsh!>_p602Z?kS)4sh|ES
zpw_7ZOek#zn-9DIq9&@ME-Iros-r$Cq(-WwPAa1M0HN9@mN9?=1S+R?s;7P`pjyL+
zqQ-7606Cm0s-~){t}3gxs;j;#tj4OWo@xtR>X-&wF2sVa?kcbLs;~Ykum-EJ4lA)1
ztFGpPt*&YQuC2nXHmkEfE40e$0*vZulxnnIE4F4Utk!Cc255@qst@6zxRxuw_N%`J>$yg$XI3b)+N;4H?5V!1
zmc}bA_`)hYEW}2v#7->5R;$98!3c>$c`+@maNI1EXt;=%C0QS
zwyemKg2!e?DhhxFY^=@REY9Yv#`*%an#OJ-f)oU;&<-up7Ol}9Ez%~f(k?C22CWUm
zENZ4$HhclqR;|@uE!JkO)^07=cCFWbE!AcN)T$;&2mm!SE!w87+O93rB0|rK=Dmoh
zo6i32hK6ZsS_YY(sow4_gQn@-Rz@mXDBTWjhQjHVdPbKLuHv5P*y62#@-5^>Zh`tO
zl14`0Qt9GmE`1seGlIp$40s_n~?bfdC
z-Y)LuuI}zG@Aj_m&h7*>u4V>X9Rz{#9xw7HuktQ0^ER*ZJ}>k}ukqG_@KQ!9GQjU<
zul8;)_x`Rdysc~A%e*2i`L-*!3ao76>c6fp`}S+Vs_AkNZ28Xbx+-j(0;%}Yul`=^
z`NHqVerx*%umGED^-f0M7VQ2e@T}VJ;dX|#Dli1!E4mgc01vPQU+}ROuw)!?1paq$
zt1>Xdj;{xgFgf(^-#(}MVz3Ga@cW*y0n0B5lQ0OwE=S02_ueoL=kV?Z?*w~BY!SM&ict;GS{%Vlf-<@r%0gXI!owE3O#(?7aXj
z+a59^Cvwt0EfRA^Y)&oMMzSPNG9`Ph*fw(fmhIUpGADQPA-gRUk1UpNb0TPPWW?s7QYu3?v_n6%
zq*^LGlkG+@0523YMrX7}Z!|$i!yM}-83*zmBQ)tgE+3!tlalmf0J2Ea?I7E;6t^_p
z;xPrMF-qUGg8DJ0ez8ou=}U)ii1xIb(zFkoG)^CNgsQYNv#C&j=}*&fNH_JB67{X>
zF;XM7PA4%>OSP3gHAr)WI$(iVk2P7BwOOAvTBo&IuQgk@wOH@|fKoTc56=Q!*R@^W
zHD2enUhg$u_qAXDHC-Pu`u;JN@qt?(Hex5XV!O3Ee6*Yf^E@kXI_GgVyR&7#^I-3E
z*MxIq&u={gwK;b-{Z4jGuk&S}Hn4iL7jL#`>+fenHDtH;{E~K2S1@Ydb_P$hW5Td(
zlkaPPb!hkY!P0hBS2k|rwramII19ILJ2w7ugf--VbWb;RSGRRvH+E;Yc5gR#ceiw7
zLR>ROZ0bS-l(%`GH+rYHdapNox3_!0H++}3E`;}DT(5WEH-6{0etWm5{xVF%!W45g
zn9{dmlmlm=ozc`F9EhA@kac=}9S2B+0xQ=h_CDXWq!-CnyxR4LI(1P;9
zMlmda0xvH)lV_|d`}l~bSOm;6l~=iyuWSThIAY9f%{IB0fBD0Lf^)ZcY%{mP5;uk0
z0gfVZ-S%;xc5)N8x|+Gc{`P~zf-u85yP|oN8~2*Cxt1S>JllD@%DIQrIiS}op0l!P
z?>V3AHsJDhq1W%2BksN6Ge=jtrC)kLA2g$*aEdK7M1MM{hx(&RG?Z(`^LkPS(
zyvMt|&pW->yS?8#zURBXzdJL8`(VVTJ1m314?Mvayulwl!Y91KFFeCHyuiDIzn@rP
z?>og;yv1MqzN5psZ^i>Z`nn$awClN|yK|ds_HuhXq`Nw72RF*|Z^Q=%GLO7vm%LW9
zcFSk0pp!Yv-~6+JeAJ4(%x^Qz|F}GGHqSe2&ine#AN{QQ{AI*^&~x+9qxi`){j(;0
zw{OHCd;r&Xz1M#|*oVE?k3HF!z1g2V*Ms+_ul{JT$$;CxJ>18=+|NDT*S+1}J>KU%
z+`s%$W-8kMJ>Unv;G_K@Y`kXFak}@XwEz4@6g#<>JKz6>vL}9r8h&OVKIQA@;y*o!
zKfdXjJ4I&*>t=p_ayz>}JLxm-+9zq}dw%4C{%&V`>f@*BbNs!W0Sn~5?(aVD_rCA{
zKJW*>@DD%n=ROKVzFz=5GAuvyH^1{gKlDex^iMzaSHJZyKg6%T<>In76uKlq0~
z@t=X^W5#YOIhd#al0UishWtiM`IX1N{8M?BYd>Ugx%%h7E{nO!12>^tJwT8XIFMjL
zfh}Mqlm|dwLWd6_MwB>_VnvG=F
zlV(B^09>vzxRYm3pFe>H6*_Q%!<#jcCRLgg011Z+hDMb-l`2n!3K=fdx^?Tzjw`{2
z6+2dCOROBZrd12`s6w4p;l`C~u&7O(Yw_mI*!1aKzkjD*h2>Rm;k<-Bl2yEz@kz6T
zvl^DHw(a1zfH7y@Sr=C2$)DHqO^7Z;Y15}sr&hh1b!*qJVV7p+GBRk}H3_?0wwrfv
z-@kze7e1VLapSw)(MEflIorFi_{5ezoqF}y=!`yZzI~=>SeH757eAhSdGqJdr&qt8
zeRxR9xyP?a_z4sH_wnb~zn_2pfB*jh4A8zO;FHflh$@qZp7t1Q(7^}UyCk~Y%uqtRR;&@03uDYt$MrmfY&jd5
z6Y<0$i7e8;6nzAeyB2qB(n;}V>`Xf)<-_sGD|76TFe+^m(#S8tJQ2w)x%`YtEYajJ
zO3%vN&O3Fii&M@yT}!0EHa{awm*e>C)6YMR)8$S)C98}9X6Q^*Q90F_kWe?BN(d^=
zD5X>|G9Nvxw!|9i)Kjt^!!*;i61=R^Q~lzM%~2=wZc=^cCb?vpDno+hnQ5*WWHB6l
zIW6yWHo4cHV-gi;jD#NAqE(H?2Z)nP`l6+^uE^=GA-WoC
zv8yIqYOcYSGHsXuXxr_#;f`DGx#_Ok?z{2M8{4%P%G>Y10S{boxc5%`rojQa_~D5!-uUB@PhR=unQz|t=b?{Y`st~!-ummY?_CT4P)}%-
z8y?C7^@Wg%+o`Pje%mSXA%gpc?j=GW00|yq=y1Z*ce|nd0q6zi8?m)L@I3?xqj&=V
zuo0;n!L1hwaUcA`_CWr%O@T&%;M9&q5%RGwTCjLu_CT04Cp_XIZ=hd7w#N|;IwTKH
zXxk`|V4-KpPa-RHAV&)Lh8RvnemZnWZB}SQtT+S-H)tRLC33hO!U73S7)9sg@dgqi
zF(Q%4{^1fM=n!Z);fOb!$QCaGI+&18j9l4Z7ekoFl0Cu+ECj$3dl4BMLPLtM*diL+
zH^cp9P>8hZMFsN+nLqvzEkWd?cG&kbSeVd+MnR(lu;IljE@zN6)J`6>qsYzxl3p3?
zWJ0jb3#eC2u?iKlcqA5q@5WcQxWurCwgt5u?Jdqc!S3F3X^YZ
zBP{M|L9<#lA(_qMLv_m9w`w#pa=i;V0pJ97is1%t=tUf7Nxs^^lZxbvqx$|h$iBlS
zmboChK{)k!+_zOVAvbWsQxPgl%O1;*^YkJI1Ityo&ekSUg~%uxJJM4ERG2Zm=tC-5
z(5uRJz8tJAN+E(tF}xvCG9_PLVF6r!{`DcIB&=aQ*<1x52$D&yr494o!;AckhVrc+
z4h?A63u_b!2lOm?K}-Vk67dcCOh_HI`ayX(A+6Z5VumNe!2+gowLip}eIrV~a6*xL
zb%aJ7Wrh>-0km_g#ECznxIdl-7^r()=};FOW%+zGy&Hy%`tIj8Tn2K2Ek)}B-S$DO
zYG;)n?yCB#8pY1VO#%*f$S6*mLj)>NZVr5#m@Rqdj_ysjw9PS23jWwObV72@Z{Vqr
zu_;a#A6bQWA#`4m5JwXpaTHUO@})6tv`2WCD`Mzgo0sy23ucF|B`#-Iw9I)=7E9sJViKZ1PvbFe`Sfk)3R1FPquTcJ{NO9c^h(
zo7&a3_O-E{ZEf?K+uio|x4|85agUqaZH1jH$(?R>ubbWM)^+31-EMi$o8Icy9Rll}
zZ+-9kYmHk77xx`-fv4Mrg#+8a2cB?+cUzqI=5*Tn%{NV^&1_GrIMdJuyNIuC;|HI(
z#|_@KizhAPsp~k{POi0)8*Sx7YdO$L?m6#_KoT{#`OR^j{&Su0oaa6F`OkrF^X{d5
zY_*BODUhCYr7xZ7O?Ud!p&oUqPaWwoa2dsG6LhU_o$Fl>Ixuo}JMS;RYhUAZ*{N*=4@=XzT+j%Di)pCEXLXmd<*RLHdujn)9
zMM!9oD{PU94){VcEpQ6d2~ulefF
z0ZC9GAdvB1Zvs7V1xo@0Cods5kOgJ%BS5hAM6fSP@BzP%@KkUHXV3*vPk}_C7KpG2
zjqnJOFbS1#37N17o$v{ZkO34hb_k;aG~o)dFblPC3%Rfhz3>acFbu`;3M*g-B`_hf
z01DM`4cV{_pRfSbuXa-J_Wq9b)J|%=ME3NsL}-r+9ghzGF89PvfhrFW@y-tC4-eUH
z4;hg}`Ve+(&k*rW5Z8|oCGimD?*O4i%^pq#zYlaTQsy
z6)55k+B!E!3v_#Soa0{v2WhzA+x<
zaUKCC0}K?=ulARVF%QXwdXawv(iDE^J|D3LNLm2xSWGAPTS9TgERjv*(hvMR0eDsgfh
z?ooE;a1_x55h;=rJ#j4Y0~9?+6ulBlN)a0^F)hC`6H9Uv$#O2s5-K0kAxO_HuVgLp
zu`TuTNx(8LVL>eE(i6?n-~R9~orEvB(k~TrM*`C)<+3p6@-QV1E%Nd)b%ZhbP6)^0
zGeI*nMRPPsvouZfG*L4(RTDIquP1d8E$E;IWOFuYvo>w>HgPjIb#pg)vo~ea`vmee
z!*4Z-vp9|OI8`(KvL+!n@+2+rBLy=gMKV@MQZg&jIZ<*eJF_{l(*U87QTGW#**)u<>hmn`
z(?8QwJ2lWDj-Uh_^g$ssLM3!UDYQZ@^g=N-Lm!kUZBQ^3;Q>H2L`8H&Nwh>w^h8lK
zMOAb~K~xd!l4%H|2sCs?X|zUdG(+KVIW;mN3Q;q2Br@TXFe#G}Efec7(?@rNGZ&Oc
zkyJ;3G(a6fNQYDpixm74A~Ty*O%&AR95YKd9kJm^iJ_KPu=tc#IZxIGY(iGPz7~R3AIoS^-vKtQ5AJj88uMj;6;;$
zFit>EDYa59^-}ZxlnAy|<`hU9>G4xRH6Ft;7ojvE%uyXtHC4}%9fPw}VF4aPHCAP{
z9ygT$6%s-J6E4AXKt~c%S?)k_RX=N$<8C!r;ZIlLQ$BeWGYS+j3DQ_~Wk36}KcTf#
z05nW-a9PLGS6vQRtJPDawJ}$c8_2a>&GlT-HC@$pUD>r=-Su6`bsRXfA7QjM${+*q
zHDC30U-`9P{qizbW9DC
zTY&~GD;7f3lv641W4{zxT~$go*7M5r3}FFFNjC2!7Ud}RW!vLoFEe9PmPk34{}PjC
zVOB>~l1cu3)Qc511XUFDTj5f&Eim0-EHYrXbs
z1=e7bL@*V$YR&d+r8Z)Lc0FP6TR-JmF;-Hv6;_({X3f)W!8K;PCLi&ZG2qs2<8yAe
z^6ucYXJFfp<|Km2d%fQg8Qo
zk(YKg6?UgpXq&cXO*U&$7HQ#bWt*{OpO-6*vsb
zuzbTe4FNcUCAfccRBeKgS}hkW95;NGHFD#kZp{}zGq^0&7i;)-gf%#N3%7$kxGF$6
zd_@?A9ixP+=7eQ9B{mp-S-6F#;)UTihHsc8Fn3KCH;8dqg#mYmdAL|6w`3~UhJ~Ni@`XIc@sEO7e2uNi_tiZtynoNm^q#Ie$C^3S$2Bm
z7fk3kD)ADI(IbClwtMxsJmmO#>9~$(uZbmwY5%wr_;_z;_KyR(e&d&r5$}%g{?dLE
zc{~<*eH&Si9~qA)Q<4vlk_kAEFBy}i_-VX@C9!gqS-F*Kawl~caDlQZX}Okd`IeVb
zZ1-(2#kGi`*d%h8WtDh|g~Eqf7Ko3TB~F=XY&e=lBAKsunVH#J
z4EbQ5*qViSnvFY6{&Hd8M>ik@fKs*e0eb$DY~L9`l63<866mYpV6T``lA=x
z8i`qPVWCG$xsxk7l0g~tx_Mp@`HwT%gf|(EQF@d=d8OS>lq0ogOF5?gYj~#bx2AVm
zOmR9)boy71w3MMloQ-DpCitnL`UwS?A`N(ft@^65+6x=Fj9nFiqx!4Cx)v&U0J+zg
z%NZoF8Isdkoq2+tA=#ae8J?lmtj{_Y(%O>)m#yW(t??SJp;)fV8WuRRuI>7qIasgv
zx~0M8n+ZD>09$|Q`mFCdrPms<34*Uv+OLiHvHLh7mLLT{JG4c6v`M?PP5ZP_JGE7N
zwL@E!=yj+a!X9LMwrRVzZTq%yJGXUvw|Tp_Xm6Fy;wtRcIYty8*Pb-FWAcyyy+sF}
zP;l+m+r8<#z9$E`P;YVcd%yXcf|{?t0X)C~C%zR?zzzJs=SJHUe8CyK!5#d;Aw0q*
ze8MTb!Y%y5F+9UHe8V}s!#(`NK|I7oe8fq-#7+FfQ9Q*}e8pM3#a;ZxVLY)K$(G!V
ziTZ21ErfvxDsH?CgWM*cDni%}NU|y_ZnVgN=Iq$OEUNei&tm+^nS%sqOtc=NErf`-
z+NPwoY_@(zh&ZUtOe`YctaG5jh}=qxB&&18zzI%^vgT{mpbX08yfC(Bhd#>0A`HPI
z;+>G7iQ>G*66smITszn+yAr~ba7K}OfyT7T(hR+-F#c)ICH*t^r)i<~C?)eA$)y+?t1;SrQ;?+RVBUJKM;i@s<)
zw*<@A2i+pX3v`qm){z}4>U@#534CsSB80qfjC{wxY}l7{<^sUE^_4cFdHEhK>3%uOk}t?I!(?8ScU$-eB({_N2{?bUwm
z+5W-p`|aT#a@ZYgKqv0)p1$W^M317ekAL9x?@%#G)uRFUP
z-*dzp@fjby0hjU(2gk7{@->+vEkAso4`AO{2;&*5;Q66H`lWyR
zslWQI|N5~%`?df1pJDlHB|%C7`Ne!kkKd=KSb;D^sXIYSB2bWvnx!{dYtDrI
z(I1u7pZ(p#`&lIqrp
z)n9jZ?O8fDR>4K5+P;lDx77ZsudmAf?b57Q*2IgC6%9N&*3+<38-EVHlk0)7m0O2M
z8*N&*#~3|5ak8+?mVfV%xpVdO!A{Q(AAa`j-~0R59Ugx9m3Ll!
z27bk!djl>Ai+l$@Xw!YwF?ij6|6Pb-Q~^#%p>hR62;y;Njn?6S%mwmUiYl&n*D#co
zs9bj6gh6ACHr|M1jymqhV~;-mNaHsz!U&vMe6WaQk}C#+9Fg!j7-EzjNjRR9rCFF^
zmReFZq?M(8C}o%?HRLBQm1W9?<(6*#w_%lQ{sktQQ6@;@oWPxFXNYR*X<3_Z
z4%%IufLc~(pAh1C=>DEE2{aEql1@r#rIucbX{MTP%4w&P_R(ddXJwbo7p9(yYO1QP
z%4(~wz6xusre+hWs9BjMKq;Q?%4@H_b~+E4wpzyAJa-(6Y_iHO%WSjGJ_~KM(jH4p
zt-}J9ofcJW%Wb#behY56;*Lvhx#n)Gg|*lEgexJ_z6)=>@=6=*i0cyjXmg52`RBc}
zRmUHp0^??=zgQ)@uYrsj>=&O28`v+yJ_$N-#Tu$Bu|xP7r9OB7p-
zGE)VY+|tG(L+3HeKrwefJ2u~pbIv;N%yZ8^{|t1{HqU{v%z;%0ha5^T&2-aFKMi%%
zQcq2F)k?!r{iF@+O!^Nc8
zyfXwj?Dl2NH|nVqx_aoHOOKQ6&kGbi_c)pExb@e+nf>P5i(ixX--pkBP2?kP{`p&`
zPx<=skL3RI@b5p8`3bIm_RA9f9H&13f~0@EW6n7S0Ko`KaDo)9pan08!3=6}gAi;5
z_3D=X9dmSHgd{AX2~UW^6smBAENr0*M`(@@x(zeV;Ghj}h{GIi@Em*l-a-DSK#&Nq
zdH^dR$_|LQ1O~Aq44fShm)MaZg0P52tQZmnr$i`fq=~G1q82qGMYj>Kig1$Q*|PXW
zE{3jHziOi!-?%AI8EFa_EEx^Y
z3DAHFbfD(sq4N&;!+b4(91Lx!Lmvv!h)Qs@R5FUrss^z&oc$we$a3eu2@bfhFL
zsYy?Y(v+(7qq*2<#)Pv9jLLMTG_C1H7XV8iGH0PS?Ws?HN>Pofb8{VCsZo!L)TFAk
zr9;i%-C_#Vs7ke`I6Wvr8>G;wYIUm?6{>iASX8Bob*yAPDO11tJ(zNJt!!;*RSkL7
zgdT*aZLRB6y(%Eqg|)1F?WT)vkn%>RT0rQ0Dl-4UBE9V;>9I$o@)pvXrf?
zWiQKEFSt}<*@;3kJ`38=igvW5Ev;!!i`vwx_OnsgEW?b1+1SctQK~+
zHpMH4^jaN{`gOR(MJZr^D_Dy_mAA~r=wb78)txqXx?Odx!S-6*>}vP8a#G)5sSDnS
zJ~ys%6$o9!i(Yd0w!5bbu6Ey>UGDl&t?5ngc*%>^xz;zm>jkTO;S1ot$~Udw-7k3W
zOJ3&iLL3Zku!A2A;Rs83!W6Esg)hwDPgvJq*-^nHJ`Cazi+IE&F0qMEjN%ll_`@pL
z@Vzjz0u0M|#x$<+g?WKn|LNAi)a~#0up8hYCw0Kjqc4xAi{Q9Q{`bh!_3`t7EaWIJ
z)y3;FGLw0mXuhq%O6oPmStSd)f$(wpDf_5Qs;%4*SwB(1X?XBTv$JcB8E9?7F5omd(yKTcHiys|c6c?ZmzOBw+Fd}C;koafD3&7-~=zY!4Hn`ge&~t#jy6F
zvIB-!NPOZHueil8j`56ZeB&JNxWvKWa6n-u0Shm=$xn`Qh2LV?U37Q8r5bOd&YRxU
zws&&7vfP(%b>BMHugC(-gI>Ow6FtmEcPi4IK2@G?
z+UHo0D%9yG^{Gd>>IlSl*QvVnU*^l-DQ~;m-+u6hH#O>4aR4Chj`zIleeZnlyWjr~
z_`nPP?hXjKo<qD=PXalD_m(KK(9J|N4q{zUBT0=`^x`5B%Vpn$>d$`&HD?hU6=M
z`OI&=^Pdm>=u3b4)K9(|3_mAf3xE6E2fnf$&+UV-`O@SszxnID=i*cTDnjVB``-`$
z`19J)>c9O#1R&}2>wo{`&oubk{du`}QL!gRl}CH;WqZhkdjcp?yT^0^$bdnGeQN?{
z2Z(?ZSSINfffMC`Y6pQE7*PZ`Oa^Fy#g%|Fw16P!R;-sz`BD#F0E00ogEL5jHE4r3
zh=Vz(gF6U=iGYD#k{#<107FQGMQDUah=fU~giFYTP3VL}xDG#PC73Y*JZObih=p0W
zgZ03Ih_hrWD1r4Sdj~OYB?w?Act$A*hW;JcdLIae4JCrmG<#+UUudW`8u*4Q_<#In
zUU@iCacDFZNQc8^ho+>4D#(T{=!SU+h_*z6gUDBfC^LBIhl%Kg`LYG}poyEviJj<)
zp9qSfD2k&5IqcD&8sE_-|kNtR#^%#z~=Z^zPkOira
zy+Drd0{{!jkPYdO4+)VGDUlOND3KLukro+{Q*@CV$&nrDkss-h8Hs`*Ns=XLk{*d)
ODXEex$&zjp5CA*JsW6`a

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 0000000000000000000000000000000000000000..b69426270b10c039ca397da892fab9974a83e92b
GIT binary patch
literal 12247
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
LPy?-If9HPyL)X73

literal 0
HcmV?d00001

-- 
GitLab


From 15a04d4e76bd7ba755591f2369c574d8a0a7dc5d Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 14 Nov 2016 14:32:32 -0200
Subject: [PATCH 151/193] 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_api_files/typical_media_device.pdf  | Bin 52895 -> 0 bytes
 .../typical_media_device.svg                  |   0
 .../uapi/dvb/{intro_files => }/dvbstb.svg     |   0
 Documentation/media/uapi/dvb/intro.rst        |   2 +-
 .../media/uapi/dvb/intro_files/dvbstb.pdf     | Bin 1881 -> 0 bytes
 .../v4l/{subdev-formats_files => }/bayer.png  | Bin
 .../constraints.svg                           |   0
 .../media/uapi/v4l/{crop_files => }/crop.png  | Bin
 Documentation/media/uapi/v4l/crop.rst         |   4 +--
 .../media/uapi/v4l/crop_files/crop.pdf        | Bin 5846 -> 0 bytes
 Documentation/media/uapi/v4l/dev-raw-vbi.rst  |  12 ++++----
 .../uapi/v4l/dev-raw-vbi_files/vbi_525.pdf    | Bin 3706 -> 0 bytes
 .../uapi/v4l/dev-raw-vbi_files/vbi_625.pdf    | Bin 3996 -> 0 bytes
 .../uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdf  | Bin 7405 -> 0 bytes
 Documentation/media/uapi/v4l/dev-subdev.rst   |  16 +++++-----
 .../uapi/v4l/dev-subdev_files/pipeline.pdf    | Bin 20276 -> 0 bytes
 .../subdev-image-processing-crop.pdf          | Bin 20729 -> 0 bytes
 .../subdev-image-processing-full.pdf          | Bin 46311 -> 0 bytes
 ...-image-processing-scaling-multi-source.pdf | Bin 36714 -> 0 bytes
 Documentation/media/uapi/v4l/field-order.rst  |   8 ++---
 .../v4l/field-order_files/fieldseq_bt.pdf     | Bin 9185 -> 0 bytes
 .../v4l/field-order_files/fieldseq_tb.pdf     | Bin 9173 -> 0 bytes
 .../{field-order_files => }/fieldseq_bt.png   | Bin
 .../{field-order_files => }/fieldseq_tb.png   | Bin
 .../v4l/{pixfmt-nv12mt_files => }/nv12mt.png  | Bin
 .../nv12mt_example.png                        | Bin
 .../v4l/{dev-subdev_files => }/pipeline.png   | Bin
 .../media/uapi/v4l/pixfmt-nv12mt.rst          |   4 +--
 .../media/uapi/v4l/selection-api-003.rst      |   2 +-
 .../selection.png                             | Bin
 .../media/uapi/v4l/subdev-formats.rst         |   4 +--
 .../subdev-image-processing-crop.svg          |   0
 .../subdev-image-processing-full.svg          |   0
 ...-image-processing-scaling-multi-source.svg |   0
 .../v4l/{dev-raw-vbi_files => }/vbi_525.png   | Bin
 .../v4l/{dev-raw-vbi_files => }/vbi_625.png   | Bin
 .../v4l/{dev-raw-vbi_files => }/vbi_hsync.png | Bin
 .../media/uapi/v4l/vidioc-g-selection.rst     |   4 +--
 42 files changed, 60 insertions(+), 33 deletions(-)
 create mode 100644 Documentation/media/.gitignore
 delete mode 100644 Documentation/media/media_api_files/typical_media_device.pdf
 rename Documentation/media/{media_api_files => }/typical_media_device.svg (100%)
 rename Documentation/media/uapi/dvb/{intro_files => }/dvbstb.svg (100%)
 delete mode 100644 Documentation/media/uapi/dvb/intro_files/dvbstb.pdf
 rename Documentation/media/uapi/v4l/{subdev-formats_files => }/bayer.png (100%)
 rename Documentation/media/uapi/v4l/{vidioc-g-selection_files => }/constraints.svg (100%)
 rename Documentation/media/uapi/v4l/{crop_files => }/crop.png (100%)
 delete mode 100644 Documentation/media/uapi/v4l/crop_files/crop.pdf
 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_625.pdf
 delete mode 100644 Documentation/media/uapi/v4l/dev-raw-vbi_files/vbi_hsync.pdf
 delete mode 100644 Documentation/media/uapi/v4l/dev-subdev_files/pipeline.pdf
 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-full.pdf
 delete mode 100644 Documentation/media/uapi/v4l/dev-subdev_files/subdev-image-processing-scaling-multi-source.pdf
 delete mode 100644 Documentation/media/uapi/v4l/field-order_files/fieldseq_bt.pdf
 delete mode 100644 Documentation/media/uapi/v4l/field-order_files/fieldseq_tb.pdf
 rename Documentation/media/uapi/v4l/{field-order_files => }/fieldseq_bt.png (100%)
 rename Documentation/media/uapi/v4l/{field-order_files => }/fieldseq_tb.png (100%)
 rename Documentation/media/uapi/v4l/{pixfmt-nv12mt_files => }/nv12mt.png (100%)
 rename Documentation/media/uapi/v4l/{pixfmt-nv12mt_files => }/nv12mt_example.png (100%)
 rename Documentation/media/uapi/v4l/{dev-subdev_files => }/pipeline.png (100%)
 rename Documentation/media/uapi/v4l/{selection-api-003_files => }/selection.png (100%)
 rename Documentation/media/uapi/v4l/{dev-subdev_files => }/subdev-image-processing-crop.svg (100%)
 rename Documentation/media/uapi/v4l/{dev-subdev_files => }/subdev-image-processing-full.svg (100%)
 rename Documentation/media/uapi/v4l/{dev-subdev_files => }/subdev-image-processing-scaling-multi-source.svg (100%)
 rename Documentation/media/uapi/v4l/{dev-raw-vbi_files => }/vbi_525.png (100%)
 rename Documentation/media/uapi/v4l/{dev-raw-vbi_files => }/vbi_625.png (100%)
 rename Documentation/media/uapi/v4l/{dev-raw-vbi_files => }/vbi_hsync.png (100%)

diff --git a/Documentation/Makefile.sphinx b/Documentation/Makefile.sphinx
index ec0c77d028dbf..a23d3c8b4848a 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 0000000000000..a1363379944a5
--- /dev/null
+++ b/Documentation/media/.gitignore
@@ -0,0 +1 @@
+*.pdf
diff --git a/Documentation/media/Makefile b/Documentation/media/Makefile
index a7fb35291f6c6..297b85c37ab92 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 f6086c159772e..8f7490c9a8efc 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 d000d802b20f0b958a0f965ffa435cbb06a371f8..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 52895
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
bbAzSD;*!Lo5^zd1H8KL0m#V6+{%%|V+l^JL

diff --git a/Documentation/media/media_api_files/typical_media_device.svg b/Documentation/media/typical_media_device.svg
similarity index 100%
rename from Documentation/media/media_api_files/typical_media_device.svg
rename to Documentation/media/typical_media_device.svg
diff --git a/Documentation/media/uapi/dvb/intro_files/dvbstb.svg b/Documentation/media/uapi/dvb/dvbstb.svg
similarity index 100%
rename from Documentation/media/uapi/dvb/intro_files/dvbstb.svg
rename to Documentation/media/uapi/dvb/dvbstb.svg
diff --git a/Documentation/media/uapi/dvb/intro.rst b/Documentation/media/uapi/dvb/intro.rst
index 11b96a19a9abd..2ed5c23102b49 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 0fa75d90c3eba1db9d07611ec6d86b4bc22d7a39..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

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

diff --git a/Documentation/media/uapi/v4l/dev-raw-vbi.rst b/Documentation/media/uapi/v4l/dev-raw-vbi.rst
index b82d837e4ff11..f81d906137eeb 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 0bae28385dfa119b6d3718e2e6cf6dc411ad0f67..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 3706
zcmd5}Z6@(2h8
z*+SKrC=x(Ia!2~$Yc__(Tnqr~9nA*;EQ1vcs^T$N5EvnZU8)Oq0|PlM8ZQdi1DkMw
zB_0P5a5%tEHQJ6BA%uqu00grcfSe$ni2qiyGyYXpb^cy(REQNJ;3Kiv(Q2~`AcRD!
zERZ7Y;8FJAJ`NjXI?<3Jv(+&{0Z#<6K>>gu#eAzOq)-IGx7N*aF0GHP8xm$Fy;;aq
zHF=2wgepuNc~H2@Li=~+zsZHH&gC5)|1w-7=l%`7Pe%Zf
z03kbGIG-1xBI`RlaOA|3Fg>SL*Mr4a@fyLv=gS%;Us~Wt7cOdw&1C43gL_L7ca1v4
zv(LE==Uz=*N&hLN+q_ec9@BdW#aZ@X9V5QW;Hu?j?{L>~aLJ*Kl81h|4^lSmE_xa_
zWR~Mwdm=mc==O(3%A6xZR{6P7MULVx&@}m<{G-2zHcQgZo-Ld&@BT+I-x^9YZi@2^
zax1krv+=QN3H8An@1N`l)I|HqERC2Wva0BkOMW-RwEZ}z;$CY;!0>B(mmo~=Afr2_
zJjSJ2-?pF`l=aAZ2wj@=>z6~yr32l(^yvYwlBv(o7%OZ`UZ1fXiC#y1kQnP|}C
zWW$L*$n(#Zn`WN=J)ej!mA-1>$!!(*Qqf=>aH9s;#c!cs@qzo
zm5d$K`U|vgPo2Dg%1xG79F_Dn;ZQA)=gYyf*2&{d&)2>j_v((n8tfZay=S*0Enae|
zl(O0S_`>s54)l^SiN(W247W?#>b;OqKM^R$v{IGL-OW!+OKe!hzH&?%!L+bDR&-ku
zC^u5-AKuv)AToVyfX-ZA=Irz7Jh>OwaIHJ*yPrc<8QXdWR
z*AdRGd;WgY@PfoTP=;|&EeM0pNcyw%#
zXwnll+Ol&?c@#{oA+`_2b{u0u2TN;T#AEqzkwu7M54T8;jz99jl*k5LV34rUPa>^j^zTE@qm
z%+j_eTqIUzbX=o;`ruL9#1-2qKJlwNHztbm{1{MLTK#I}o7tG|d|X?A)?
zHjY)7khIYudoiKc$UU1iiBT$-zkEJil-F*!RhCaULHTUnp#8&JMz1A2f@f;VVqFu}
zoCcy!N0rqLMP~lKeInn&^4@Q2(G~kSMR%^l0DQ30bE}D6#&Vne{Z=LM
zBiaK_&W}?g3hp?4*Qpo>_w_2qr#5Xm%addKOT$jx88<0t5cBlin#5^~k~3dtqp!3k
zWl*($n6~PAPLI}a?!OyHe_eI%zH+Qk>X&pDcVKP1XI9N5X6Mswk9#yc;VWCLZEc*7
z=4y=>CL9SPjl1=s$w@v+2RDR`(WcR(LEe_Re<%2T&QFyOh@V!wJ
zS^w)VMr8-%yjyPS<@r%8YYwBc?&&0#2QJU_*%*Ts$rki?Qfd92eIAn5pY1tI5?8zc
z*3tZXuO8@I|3igd@x9Ba_VYUJW~r?uCX)oS$$+l@R_?q;cil$!AKfHuPQhQY2I`IQ
zJCoM|e|IPr!`v1tulVy%7t5MkgX^=|N7oA3((U-`kEeG?8n#rkh5G&C%Lmb#l!DV{
zHd6~j(++f29UE9oaafmnb=S$w{f7IC*Oz2&pHF9$|0oe_mwEe2lMK-l6P8E1Udw9*
zJzjbB&tem&59J&Y>{9r*SREl_+F3LS%1sYzHW@rM;G(Y9FmO3YJuTLx4BEcOlGo%_-Q>)
zOMZz9nkX3Fc3Xn7I-(g_R-zeGv*K%F7bKU~pCYx__L(ub-!K)jFGy)41^tE3Q>?$V~apK}v-=hYt~jI8alITmrZ@iaBwRNJ9C+X(QOV|Df2qkr#-qh7gb
zBrm<&&1hj9ZlxSCu+OOwMA_=Cb8Ek56^cGwkVF_X+y_-i>jPF}McTKwTHmI$r3!iy
zkZoaV8Jd%yX_eo8CV2mu`~cBCiimF2xOXH?+U@Rg{`t*6imJk1UBHh>nz~tE?el;AOGgs)a$^a?0F^LN3B5USHF6C<
zPeVhaPB!i_!uv!9zrNoNkUhTFnD-H+)cP9sZ%$C-gvcB-(d*a_dG}yss0U-|p&}4Q3mI1YJCK-OXAAmkDe1h4(f!3f4&AY?&872-r90f#a+cJOdS{R`v+eUbnG

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 bf29b95dcd0800b4f7d05389ad60cf3e82569b00..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

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

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 200b668189bf1d0761dbcd75f38e43cb4d703a33..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 7405
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
V%8y_8ZbSy1$UvHzIeI!F{{we5{PX|-

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 29a806f839b4a59511d25d48ff4619a0ed01d7ad..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 20729
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�Va2AO*LciioDn-4zB1|?^CT&M)DCx{LU`;}<`a>w>bA+^<<)e39xYL?
z!g!>vgp4EZX*z0}&!T2Tz?YG(_0-!JidLasMm|2=P{zSL*VqqP-o9vcen;>$GF7K}
zcZ6GMGDW;}zzsL>emQ?ac&bysM!*zdp}sg1$D|!+@_$GR_T?w#k5%oHNvw
z#$T#$_!|mY9do<`HOvg!sZt>5@21zor*7wAiK^!3?_ZvcNS2ne1QQU$jDt#5H!4Rm
z&z>nPH;9l62-Yytk8jkwe&0Xe^Ep?&d$M9emIV)dOLNmW5MVfIDDGedWIMcUo*RV8AN!i&c>9&a*0
z1Rp_-26Yo(9!Fxt!
zQXwqWr?5ruU`$$uX_=%*F6q_h44Y_V-`{#>UhPV^>8ZR!awR|)KU{;`H>Rl@8tWrS
zx3iE_gCafxq-hpEjc`jm)4?R=dPX1vh%(G}n)h<RomGBTUAL9Z_~|PP6^RT
z4#v2YQFh|SfvN1%Cu}x-f-?`&V=uZoGs>irhwQZ%2F*lY6Q7{>j4U|#Tl70mvXgA$
zKUVRmM<*^9mD;|MP3yAO;9qYD=+V!++a#@Hc%T)b;Fqd_`XWWVH|%LU@S(Cu+L}e?
zhWul?>CrT9n4HdGXpWMhqgP>z|3LLzV~zx55SAQ#jd6j)`qYC{)7mxC*f~8;NhbmA
zFGh4p$uPa_k@+YI9*Zsq4g|uXPR3PV!e{M`s}lOfCrTTPiFaL|?RBE~0)`ssVdbcE
z$Wuf(*Y7YGeom~U;C|{`u0L2?mcBbyaE3~_`y|3Oc5*j
zEoI~OuS@ky+ES?@XLDL}U9iH$^e@*XSSl56TlrjF8jM>mtg}$Gik_Zoc+1@01=O;^
zUEeF~zNKC~vJxi!f+5?`h|&KV{XHKRw;LOpq3;+?-wURHMuS{2%i_j79&>!3yIdA!eJ7e9z|`g8oI@e8BRP%_t{gBkWm8x0RG|N3{oQ$7a%)
z>cc1G0ODu2u92i!&hI$E%-pXcY3A4~QQNH2_fP2yDF*nH)CU;N0C3VACg
zaP{P7l71j~-=%T2Jdd{}QiRbMzsOeT?02f5}DJmnpP%@f>0bxc#~icp=ho4GsH5
z+G1B0JqzZly%dreSg@-W9knYjBiMh6ww+Dad?o0Jdc&C8u%a&lQnf*FpgN;?(bRba
z%u8Hy%>CZvQZs{xno_$~4Ba-l?xl)9dgBj^uX}VaSNq5*^$i7595H=Ced~d~Kv>WN
zp>!-H^ZFsKB>^Aj9Wh#~rj|qCPeIjx>(~RPGc)<&B+f_(nIJ^g*oilu6gYg4N<)pr}_z;@^-48tL0>`
z-IcGGTow4dID&F{Z8^35mQU=Os60>8$g16+&`rHRAu(@%$=(_6$XfnnPfcK2F%!Aza>(iv$G>iQ
zG1Xz2H}67AvL!DR(3^V17nW=`{faqU!rSJ66^0Pl$&CvAZPk-#qMrqGX+0B+&3VZI
zdj`wD6&l}P@?eGlcwZBCBj38TXLW7I;*9Rd;eZX2f5z5X5_;g)Yc>9bIlx!A7XyU3
zW9*~w6qx(buEqOb9t7Ykhyytj-#miz!!0AMN`)oxEM)PDJl^bA$*Y_1s1~=xtcnB}
z{1zdjH!ULL)Pvh$2G%*SkZpj(6~#4?*Jqp1H<2YC9MNnY?^+QQdXdqRClnBL{k%+D
znkY1GD*d20kivJ8jP$$N$yu|S^q{_y4@)t)I>OzWa)QMo=>2*^6(!Bl*Us{HM>}^l
zE#;eJf8m5I(w$Y93SuV|oH)&sbg5&oBoKKwF7ml8{&erv?l(A3>#VyE)pXUffH?!X
z>tE66rV(z0YV|h+1;`T0x0j;WUPrB?$?U5OrVJgj>9rEL{aVZ^*NWS*BxUHQlsXa!(=XgXnV
zk+}1*^E8|+i?N!REVbLwomw2%Au-L#vt9>ljZ8QYkpVgDuMVfGRhX}XumZkcW^6um
zXW-w7uay6$6fqZrnzI4Nxw}2i0M1>!=)dAb4vNm<)krB;k>)5j=%uql1wTk=th+bw
z&v2C?So60&Ok>Aa!uyo`oa?~uuGQDJ=g)o57P!0>bW3jxbSb2<0;_vheaUH4Hd&t|
zP0XiEubcbk`QaA8UcXVe5?gakZHw-%U3l^>C%2-h;DqLV@DT0yqOAN-LfpQTb|WZ)
z$4Hjrck^_omAwA;1+4Z52F*WCRp(0Fow&>N-HGcq(I&KkG67`1zKQ7;e?%Ez^h@cE
zZro!jS7S2qCEw6a+)!JV`^e&7In*bFFD>YD3@CNl!mY9ARVgqw=hEx#@b9ps2)o5o
z8_&Og!~#OH^y##XhC9Kj%_l)5c*RJpf
zmX_8=qfUF~Pw|qb5%zBW(84C0jI;3?Ld<51)l|z8$SfAIXH8{*CI9a06bc>LvQ+vO{k77IV~M5_Cf3
zR;M`9MsY@ygJ&~d7}Bpg%W?U3T~^`F#-`R8L};gZv?6U2T3P{SEKS90tz^MVNEJIP
zdKtzeu5f1i;0Tq%`4N)_Kf5V49B{~CS~l(ZF*
z1b3_;mkp+7Q`;M}746@Y-tr$_6KXA!s+?E#LjzgJL@j&oZiJ=bJ$ys;hO$`|MR5}G1Qhc9sl4ovF0~kF#n*`_1qrlyuanJdMB?3J4
zYqLmE3bnnqr^-{KiiCi+hNdif(GsM(obi}kuet&C^*heVIgLn>8@6U&ou1+*&p(JQ
zIvYs*wg|_y66Ur%L8*c33mwy*I}da?KYWaAgEPxd#_t$B{qXhEinN(P@(`+BZh-JQ
za$6|8NUh_<=C5JhK2>hL4@_P%C7EA9OmQWGgr@S5-s-}Ldv(6b!#fp2kd@4q`lPqz
zdrtLsn7jTMdd*rQg;XHIGJetZt??z5GMMVGjV9X!*|4?rX@m2hYvp*V>r*n5Z+miu
zQgSQpbj#QmdS0FBs+6%f`|jEdiC#7m%=hq70)?HPWCT_Jh!;)HOynKCEM_N&LXbs`
z;yL}R0;k?A-Z-~Wj}O<5Q{5F8E+al~k5$
zW*4!#X`Jx0NI&g6RRxJDt&A%+C;5A=oE9>!<%d+(Kbd&FDO|HUe_3I)KOZn1cW+{z
zFsW~jkLR6x@;UEHu|9DdQTuES7Pouno8ikIvSQEu43Bp%4o}zZYe(a)hvya>_`N6F
zX4rp=9TeC@^S_X&ymcKMBQSKdcA)VGgDHp&fr9_3y+*q`R&6_$YCFEt#MSadAxlmE>^>e@Wo|lO*;B
zQ3E6#OH1gu4yJ!|e|VhtzXB-zD}Xjl8V`rY03@8DNDLYvCnKjIqXdw+kHdMW0%>)o
zfi4)R$9<$TRtAl6k(B(g3px}jZuhNd+P`)8Z}
z@xfyd_t<0sU^dym2S7UhBW?a2P1k4T1TgPiThpLC`24ci9w;#sQ8K|M~Lh
gqwb*r$8Gr0S1b;S!Trb(B&z^cViOb7xueVWKjYh6dH?_b

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 b78a8e8f6b35bbd5c0b5e018c28b27f157626f17..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 46311
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
88RpRX+~5x6B<3H}-O(y5
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

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 8f7a95b6eb4d8d883ec293254be19f41edb6b746..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 36714
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
z
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
Date: Wed, 16 Nov 2016 15:38:03 -0700
Subject: [PATCH 152/193] 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 297b85c37ab92..c22a30b07821e 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}
-- 
GitLab


From 22917b992d3713157e759f23a5a090687d004331 Mon Sep 17 00:00:00 2001
From: Jonathan Corbet 
Date: Wed, 16 Nov 2016 16:07:02 -0700
Subject: [PATCH 153/193] 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 db78974aad266..ba38bcf485a9c 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 fed87ab7f4867..db1f7659f3da0 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 0000000000000..472fc9a8eb670
--- /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'),
+]
-- 
GitLab


From 47f421221029e8515b71e7e2379eba8406b7f458 Mon Sep 17 00:00:00 2001
From: Mark Rutland 
Date: Wed, 16 Nov 2016 11:13:59 +0000
Subject: [PATCH 154/193] 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 7281bf939779b..6c5e8a9d2c6ec 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.
-- 
GitLab


From 01e4644203b01fba5023784598f4d033e3bd3e28 Mon Sep 17 00:00:00 2001
From: Mark Rutland 
Date: Wed, 16 Nov 2016 11:12:49 +0000
Subject: [PATCH 155/193] 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 88951b179262a..4a824d232472d 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
-- 
GitLab


From dd0b38d8eef86308dbbba7557400e4894e55e3c8 Mon Sep 17 00:00:00 2001
From: Oliver Neukum 
Date: Mon, 14 Nov 2016 15:52:43 +0100
Subject: [PATCH 156/193] 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 263e6577de663..857b772e9da1b 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 e322691be67eb..0000000000000
--- 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 e18135b513e24..743828ead6658 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 0000000000000..851cc40b66b52
--- /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*
-- 
GitLab


From dc92726e7f8d9e400ae4fa42fde4c3a5020fcbb8 Mon Sep 17 00:00:00 2001
From: Brian Norris 
Date: Tue, 15 Nov 2016 14:42:14 -0800
Subject: [PATCH 157/193] 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 2622bc7a188b0..656cf803c0062 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:
-- 
GitLab


From 0c9aa209579d41c9b8bf1fc39ce042bea2ec422d Mon Sep 17 00:00:00 2001
From: Jani Nikula 
Date: Wed, 16 Nov 2016 17:26:16 +0200
Subject: [PATCH 158/193] 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 e10378f769f9e..030fc633acd4a 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') {
-- 
GitLab


From 38f985e3c9bb33d5422103807eb0a54f4ad39a0d Mon Sep 17 00:00:00 2001
From: Daniel Vetter 
Date: Thu, 17 Nov 2016 11:19:43 +0100
Subject: [PATCH 159/193] 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 c66ab937c2cae..3fcf0ad6e5f0f 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
-- 
GitLab


From 1dc4bbf0b268246f6202c761016735933b6f0b99 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Thu, 17 Nov 2016 08:32:33 -0200
Subject: [PATCH 160/193] 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 ++
 .../kernel-doc.rst}                           | 316 ------------------
 Documentation/doc-guide/sphinx.rst            | 219 ++++++++++++
 Documentation/index.rst                       |   2 +-
 Documentation/kernel-doc-nano-HOWTO.txt       |   2 +-
 Documentation/process/4.Coding.rst            |   4 +-
 Documentation/process/coding-style.rst        |   4 +-
 Documentation/translations/zh_CN/CodingStyle  |   2 +-
 12 files changed, 348 insertions(+), 324 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
 rename Documentation/{kernel-documentation.rst => doc-guide/kernel-doc.rst} (53%)
 create mode 100644 Documentation/doc-guide/sphinx.rst

diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX
index e2e74448d4258..c08de5574d48e 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 ba38bcf485a9c..1ac958c0333d6 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 0000000000000..fd3731182d5af
--- /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 0000000000000..d8bf04308b43d
--- /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 0000000000000..695b7b6cf6ed6
--- /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/kernel-documentation.rst b/Documentation/doc-guide/kernel-doc.rst
similarity index 53%
rename from Documentation/kernel-documentation.rst
rename to Documentation/doc-guide/kernel-doc.rst
index c66ab937c2cae..afc95c9e96261 100644
--- a/Documentation/kernel-documentation.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -1,228 +1,3 @@
-=================================
-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
 =============================
 
@@ -586,94 +361,3 @@ 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/doc-guide/sphinx.rst b/Documentation/doc-guide/sphinx.rst
new file mode 100644
index 0000000000000..96fe7ccb2c670
--- /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 286d92bad208c..bf3eb3ad6ad58 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 062e3af271b79..104740ea00412 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/process/4.Coding.rst b/Documentation/process/4.Coding.rst
index 983d628c1112d..2a728d898fc5a 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 3e7905172000c..d20d52a4d8121 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 b027380427992..dc101f48e713c 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 风格 “// ...” 注释。
 
-- 
GitLab


From 327f5a754ab14aa9dc20e9c31cf776680b1d9a4d Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Thu, 17 Nov 2016 08:32:34 -0200
Subject: [PATCH 161/193] 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 695b7b6cf6ed6..6fff4024606e3 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 0000000000000..a1867d757ff44
--- /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 db0186a7618f2..20dbdf55c71e2 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
-- 
GitLab


From 2dde123b23ceba4b6d0d780b4e9fdcfb94621747 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Thu, 17 Nov 2016 08:32:35 -0200
Subject: [PATCH 162/193] 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 a1867d757ff44..615e25ec64bb5 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
-- 
GitLab


From 9c240d757658a3ae9968dd309e674c61f07c7f48 Mon Sep 17 00:00:00 2001
From: Chao Fan 
Date: Wed, 26 Oct 2016 10:41:28 +0800
Subject: [PATCH 163/193] 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 74329fd0add22..71f5096694b40 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
-- 
GitLab


From 388f9b20f98d4792f72091acac5031a99370827d Mon Sep 17 00:00:00 2001
From: Dan Carpenter 
Date: Mon, 28 Nov 2016 17:43:15 +0300
Subject: [PATCH 164/193] 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 449ca1f199f4e..1260f60d4cb99 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.
-- 
GitLab


From 0bb33e25e5c91f69304f3799609a52354dca1af4 Mon Sep 17 00:00:00 2001
From: Jonathan Corbet 
Date: Fri, 18 Nov 2016 16:04:48 -0700
Subject: [PATCH 165/193] 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/{ => driver-api}/80211/cfg80211.rst          | 0
 Documentation/{ => driver-api}/80211/conf.py               | 0
 Documentation/{ => driver-api}/80211/index.rst             | 0
 Documentation/{ => driver-api}/80211/introduction.rst      | 0
 Documentation/{ => driver-api}/80211/mac80211-advanced.rst | 0
 Documentation/{ => driver-api}/80211/mac80211.rst          | 0
 Documentation/driver-api/index.rst                         | 2 +-
 Documentation/index.rst                                    | 1 -
 8 files changed, 1 insertion(+), 2 deletions(-)
 rename Documentation/{ => driver-api}/80211/cfg80211.rst (100%)
 rename Documentation/{ => driver-api}/80211/conf.py (100%)
 rename Documentation/{ => driver-api}/80211/index.rst (100%)
 rename Documentation/{ => driver-api}/80211/introduction.rst (100%)
 rename Documentation/{ => driver-api}/80211/mac80211-advanced.rst (100%)
 rename Documentation/{ => driver-api}/80211/mac80211.rst (100%)

diff --git a/Documentation/80211/cfg80211.rst b/Documentation/driver-api/80211/cfg80211.rst
similarity index 100%
rename from Documentation/80211/cfg80211.rst
rename to Documentation/driver-api/80211/cfg80211.rst
diff --git a/Documentation/80211/conf.py b/Documentation/driver-api/80211/conf.py
similarity index 100%
rename from Documentation/80211/conf.py
rename to Documentation/driver-api/80211/conf.py
diff --git a/Documentation/80211/index.rst b/Documentation/driver-api/80211/index.rst
similarity index 100%
rename from Documentation/80211/index.rst
rename to Documentation/driver-api/80211/index.rst
diff --git a/Documentation/80211/introduction.rst b/Documentation/driver-api/80211/introduction.rst
similarity index 100%
rename from Documentation/80211/introduction.rst
rename to Documentation/driver-api/80211/introduction.rst
diff --git a/Documentation/80211/mac80211-advanced.rst b/Documentation/driver-api/80211/mac80211-advanced.rst
similarity index 100%
rename from Documentation/80211/mac80211-advanced.rst
rename to Documentation/driver-api/80211/mac80211-advanced.rst
diff --git a/Documentation/80211/mac80211.rst b/Documentation/driver-api/80211/mac80211.rst
similarity index 100%
rename from Documentation/80211/mac80211.rst
rename to Documentation/driver-api/80211/mac80211.rst
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 743828ead6658..0dec394b9038c 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 bf3eb3ad6ad58..2bd8fdc9207c6 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
 
-- 
GitLab


From 93dc3a112bf8e5f97e3d9744595934ff31708764 Mon Sep 17 00:00:00 2001
From: Jonathan Corbet 
Date: Fri, 18 Nov 2016 17:06:13 -0700
Subject: [PATCH 166/193] 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 c8bd257660eb2..bc6278d180906 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 7e4f34fde6975..0000000000000
--- 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 0000000000000..50a9707addfed
--- /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 f7ef7fda5763f..c3a1402da0cd5 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
-- 
GitLab


From 8da3dc53347205b0d32ded4ab9c96dcf336061d8 Mon Sep 17 00:00:00 2001
From: Jonathan Corbet 
Date: Fri, 18 Nov 2016 17:17:11 -0700
Subject: [PATCH 167/193] 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 50a9707addfed..ac926fd55a64a 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.
 
-- 
GitLab


From d6ba7a9c8b5a6a42e8f7a7efd8345122611b535c Mon Sep 17 00:00:00 2001
From: Jonathan Corbet 
Date: Fri, 18 Nov 2016 17:21:32 -0700
Subject: [PATCH 168/193] 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 bc6278d180906..caab9039362f6 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 b57a9ede32249..0000000000000
--- 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 c3a1402da0cd5..91b3a010817a7 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 0000000000000..6b44bec0de432
--- /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:
-- 
GitLab


From 76cf11aa1590f51c49956f088585b2f97d531147 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:11 -0200
Subject: [PATCH 169/193] 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 c22a30b07821e..d79afe4d27e9e 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 225998c395dfe5e605acbf85325fdd52c78fbff4..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

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

diff --git a/Documentation/media/uapi/v4l/crop.rst b/Documentation/media/uapi/v4l/crop.rst
index 578c6f3d20f3c..be58894c9c89d 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 0000000000000..588bf8bd1ea70
--- /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 f81d906137eeb..baf5f24839272 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 a7e1b4dae3439..e05fb10413635 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 888ce6fed817f9ae154b7124fc01687512751673..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

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

diff --git a/Documentation/media/uapi/v4l/fieldseq_bt.svg b/Documentation/media/uapi/v4l/fieldseq_bt.svg
new file mode 100644
index 0000000000000..2de2f187f217f
--- /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 b69426270b10c039ca397da892fab9974a83e92b..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 12247
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
LPy?-If9HPyL)X73

diff --git a/Documentation/media/uapi/v4l/fieldseq_tb.svg b/Documentation/media/uapi/v4l/fieldseq_tb.svg
new file mode 100644
index 0000000000000..4e6460b28db77
--- /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 24937dbec3371468d524d54360b7ce2ec484d27c..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 2053
zcmV+g2>SPlP)004R>004l5008;`004mK004C`008P>0026e000+ooVrmw00002
zbW%=J009A%{jLB200Lr5M??Sss*NKu00007bV*G`2jB`43=;#J%-`Dp00#d_L_t(|
z+U?riYZO-)2JmAQ?S*vPyOe?}2<@eoerUlu1uuG~{R2c|8&ILu?NVrpX`E<;P^jjj
zH>Ihy-q;JVBBHj9n@O}JS8D{pkHqXmLL(*WBy5t|&Cbl}d7rbJoMao#$Ie8mjD
zIq&@T?99&D(TDLU9_`G*a{=2x7Hw=@wPax{$NI8lDy3(&HwY$IV~cS?)dLhQjO)U<
z5nd{ZpC;^c089rM&qS#Uj2ox1zKiw?Xg^_4X{1>)h4d+6vI!~%2FA5u+@NHPk|g%|
z7>p0bm!(!Pou6QzUDO`DiS~DGDh+Oy%&;F9<2+-#GMfU%1-vASY7G0l4x>=cj62F~
z+R*NT30%o!>#B*#q!q@+Pfjv&Dx0y-w89kMv>(cu6xtmNr7p?vy)hbh&sUgkWj0%v
zXWFJ3g=s85)0&kt?cp=dv|rJ_3Z?$ynHJIKCK856@o3k~bIdq+j$$Dgz{hjTK)4G*
z_5iNXy*t8P2>5oI4Zo>gIzw0pf;5S`q`92(*+I`_J1O?2dxJZY$5Deohhga31
z7lP-CS#Fok<;Og9uoGDJuoL0
z$4p4Z!jt&07i>O;zx(IIWZZ}t>nY5_A4|kI5i#b{FwIr;+rTwOk9Nk^GxjQDYZ+V3
z*h*0nUxH1#)aBybi*de^^CNQL9>z8?_A+Cu#6a0T+(6rPq8wvuj-f>NYTWyXIlG7{
zU`~O}xzO+6rfghPapxdjnK+{2li)j?*NK}K69W@?*+ZOOcClSv=rf|6;qE1r#!za1
zv6;4LnAEaj>dTnzVD2uCk?rFKm?j$LUO;KoC^9A(dvT0xm$yzCY+Xw!X+|?qG5uh~
zWuA(0{F_M^=MOl2YtNbZTFuy+2DY-Dt>|a$8^*Sp7#PDhr2%|XDz>kY`@~j$O)iy|
z;hnT*G@}{KXeM07Oj)V$8P81d2pGQSgVU!YVD_bspNxP>rjA6x984WQ9s%=dDw1Qf
zkcVb8qZ!R;Ml+hxOeBnh=g=b~6da3B1;;wK(YTS$xEL3_-9@Dn>xuDdn#De8E10Sc
z#B|0?QOY%RB4p!WP_B)ZcXlHKWfQ||(Vi*L*uo!ZA4U6Rw2z&h9vn+zpFK3r|Iwy#XIiNAs1M8z
zdeiuhw}`R9xL^Vo?QM9^-M`R2iuR;z-&+cf83>NmQ!#zh6yvh3G%h&UN~M#%I5vH?
zbZq*Xh}qUhOt(c$-a&gkX4Cy8+8t{5o}kq7dnq_(A~=R)b3a2b$Hi=dLA;!+VEi;O
ze)>0J4yTE+!4w>{`xt8!#mObI>sIa(|?27bMi!8m0WI#E*(_XOmquD1Wd!s^=9^<@&hG4
znlr$}=M_{|*PGdc%8n9Lrr%Bc7mhQJpt3WUpz?Jks7%HTX3jz7_KH;2`UGW0%v|fWo5mYJ*ceCW*Rfspt8E&%pO!8P|h@uKmAP8LFEcC%k2ui
zM9hKk89HD)BVmFkFDes+%>*X4pNGu&l4;?Hk1CAIzpWsX77Ie&neZugEoW9_hRym4
zGPlkO=FX^J4aS;eDjZa96^r2b-LC_in6pz%g@ekLe~OP=;`WP}mdRaLI;d<0)!Z@8
zOU752%0B33&f(|zV`4nzO$&qR<|7nT4u}aQs4VX3y^Ug-8$*1Qm{5Ysf>BbcAuux9
zyR^*0A4|l@Xz#LRnybWjLP{F1XebXVBWyM;sQeORD`o_h+5ZHUUqMh=G?oRGeXBfe
zhv?k2wA~>rR@2gUd|nCS7m-P6X8ugwtU={PF>?-$GZkk>xSfzoVW`X?x6KHc;M%(V`@?7adv?vf@R{sA
zdrt(6d)Kb137_fji7(*T{0ACVH0$&|GJ`+|00000NkvXXu0mjf^Jly4

diff --git a/Documentation/media/uapi/v4l/vbi_525.svg b/Documentation/media/uapi/v4l/vbi_525.svg
new file mode 100644
index 0000000000000..3aee15d57c9af
--- /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 25c671af41ad576ef8b31cb21711f43432e92beb..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 2352
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
Nz}whcR~;uO{s&NJSeXC-

diff --git a/Documentation/media/uapi/v4l/vbi_625.svg b/Documentation/media/uapi/v4l/vbi_625.svg
new file mode 100644
index 0000000000000..d96a2628f305c
--- /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 b04ae50385a71057838fac7334fa1f566da9b172..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 906
zcmeAS@N?(olHy`uVBq!ia0y~yU}OifPci}t1~%7IRX~a*-O<;Pfnj4m_n$;oAYUQb
zBgmJ5p-PQ`p`nF=;TKS-;RORjsR0ASs{{rHs~HRo;stYd1=;{5n3BBRT^JZv^(q?y
zdF&;gzOL*KxP*9wnP;E5e;X)2$fE;dYk_DHk0se^4##fD3Z
zz1A)g*Eeks61|lqXnVWaiBDMS!-S?Lk17EXuCEW4MywL;&I>hJ#J;s%K*M6Kl7>^5
zPKo)U&Ic4tQ4>N7-{`;q;iyNNYFhT#HexjLcz_QpGTP4|!oL{)R
z-M+TLC9&k$$=Q#S1l_-Jh^#yJrl!nAN5mW*|{YvJohIyz^LF68s6E^7zJO#_&Y_7kiJdn`6Pwxi0!@^Njm%
zj(E?Isw?VQzdOvM+H-cEQBE~RF-YH57O?jKfvR4-QA
zR#?5&+Bf%%+TwDh+Q;i2Ri9riyZY3Ll`Xp^bmnY4+VDuL>G1jUZO^uS+jY&+YkeWl
zyLLsc7?@yHOI#yL
zQW8s2t&)pUffR$0fuWhMp@FWEWr(4Xm5GIwfr+kxnU#ToZAW}3iiX_$l+3hBxCTQD
dkOo6bD+6PQhF79jE&(+#c)I$ztaD0e0ssucbw~gJ

diff --git a/Documentation/media/uapi/v4l/vbi_hsync.svg b/Documentation/media/uapi/v4l/vbi_hsync.svg
new file mode 100644
index 0000000000000..17ddb5bcb0710
--- /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
-- 
GitLab


From 16bc3bfb237756f6985a968a0707865abba19222 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:12 -0200
Subject: [PATCH 170/193] 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 +++-
 ...-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 588bf8bd1ea70..dc9a471bae6b6 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 2de2f187f217f..b195301771ce0 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 4e6460b28db77..6a7b10ad4ab80 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 18b0f5de9ed21..ba02e6f6214d1 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 3322cf4c00935..c82291a4493e8 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 2340c0f8bc922..e7b3786f8a9b0 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 3aee15d57c9af..b05f7777ccf86 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 d96a2628f305c..c117ddb7bf7ee 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 17ddb5bcb0710..4d5c0b4f146e3 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
-- 
GitLab


From 2bd658de409da459a4e5028010715628e7f11b52 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:13 -0200
Subject: [PATCH 171/193] 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 +++++
 .../media/uapi/v4l/nv12mt_example.png         |  Bin 5261 -> 0 bytes
 .../media/uapi/v4l/nv12mt_example.svg         | 1589 +++++++++++++++++
 .../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 d79afe4d27e9e..ec95286e556c9 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 41401860fb737739658c354c0cb7ca12313a0265..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 1920
zcmb7EX*ApU8vfCysc20nwM-SI6L*H2RD!CDUQKUQa@5*TTZ>exLB#Tpph&N!EvA&V
ziixV}W*4MJ?ORc4Ev2=UqGR7Rh+r}?^XY!L=iK|{eSXjTyw7{y^ZW3`*;tt$L?|Nw
z00&7#f*k--ijue2{ymbqnvq#3fxTXMOFRH2NwV7>FbP+`LbS64Anb1d+=u}{Bx&84
z27rkLVAdS~qci}N{5h4jCX!`_Hs{G^VzD?qJ)O;FGZ+lXuvlCNNdQ1~VleYcFC>=)z$sU{uFl=2oNQvoz2aq_uWJy=nM&Nr~9n*^+{GtH`F(~I`t*p*<4(l
zZE5)scWX-^7=HYy(Sbb9EgsFwUHdYgaoTuedb&F@yoKU6|CUb#pn`O+)`Hj(47E_)
zdt#zGm{5|T!EY~l1qA%p;o*h$c0S#EzWojMFmkf0awsF+QcbnZi~2UmKgG{4-_`l9
zKcm9NGJ(nDUbMdz67s_BQX1`AVo(t8g6%U8H)AEG=6c6Toels^o3}he(!Y@X`I>z;SvV_>B7iz*I>DJUL`=fpgtu$Uwfue$wXLV_pG`
zqp2k~`duk%u@om=bvK1x!&*pXKD^ADs}-MeF1Eo}cD#oS!1mTi%;|KVZD_cu7AzEeq)7+Fh{t;b?Y~7nmJ8kRoe2qX)|9JQ%
z)%pKuy!VjhcT6b66gIBj%Fm%GsG8%V2zBL)1g0hnee~iJon>D9!(#d`TzS*V4y-8P
zfdSr;+N9`LP+B?;B@fx9+ikQ`q|_V+xZO`Dt=<-1YqcBP?hjCW#z4-
zFQNSO`dP2C@`?ulI$3kG!Q0+6cdiM!)*1W*jaBI}PxWx>kiQxGz%O7cm77suef>^n
zm}^92aD97sxm4{^nt(N)KRTK~5dUk8*)=Ehs&gYRR0a-Al>a?$_Lz)PWtVXWmeO)*
z_Muw@Mp<~19XifrtxhKmnr!V^G7x7LkagEhi$uCLp9L`q2{P#G4fRuN>A9W@S)<6l
zEEK~`Y?`{v>p=)ePx^0lE!6K)PW
zS!iC_Vdgtal1ZDq0$H7aAYGXO0T$TAS(=t&clV>ht
zQTJ^k9XBaj#@RSpDfcu*VINEJh3=}x54@VXYcez-8WU-=%WjGTv6s8%OMgMv!PCy32GRJXN-iOq1Qa2
z7`^M|pvSjA=SkCRUQm=1ir`1FE?(r@?r(N*-?e@G388=vHPw&pkGIu`)|@h*2QC5H
z5cjvOf1eL_QBgSS7`P*}^3LZVeI{~$T+4GWQsEDVDb}=U#Ao5-V3>qG6Rk3VGV
z_PnUp)83BEq__FLQm}X3+}y_Y>d$H=?8_;095qA5tP-^KBD}kjwE}BC49e2J9@Wv*
z`ibvjY6lNbLQ$(3O=*^(WerDOl{2&SSEX2&H?8jLx;Z((W#pL7OGR=)t(i_
zbGe*ZNj-I?B4{5voV=1`nxFUddnM?6nZomF^ElpQu5ofadn_5bW}-s+}8`dwmzNmtiq^yjnah^MXOEJ
zHXRFzh=Xk&Uxl0Nu3*+)TC#};kdP-MN@}}g=Q1|rK^7b1cn06PEXY!9-?G25>#q
+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 7775f5d7cc4661b7ec082e7ed5542eddb7dc65de..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 5261
zcma)=c{r4B+s7yC7-VT=&)A7HwnD|s7-j}Bma=Bw##)Rlk!5BumMl?{>>od%VwcJog{heO~wZJ!
z(hLANmQS~5fsFL^`&GbW`isc}ei;q`)TXfSJ2BJu5Er!BWdI;d1^|d60sy=8Pf-g1
zKoArF_~8fuXk`Ha{MU1uO)mlf3=&u)3%#SGqp7K>rluw;mHPDQ)78~gV`F1EIXM^%
zCL|;j8yoBB=$Mz6cXUL>({ufK@YJIt005msJEG;FkNzxwZK!y<WU3jpwvpUd^rb__mE)Tc<+u@sEXMVhS({a^es{F~vkel7U-ko;V6ZyGl
zG+=9C;S(|DjkCj2&wCdK2YT*>_O{`aWSqVIAUQ6=+WOgLgEAtq(a3-j7Fum=^xVZM
z#MY+C>Z<=Wy9P)5QmpYyLp0UMU?d~GHwfQmYW&90e)4fq?@jz0XGgN-)mE(W&xwiU
z?(X-#UQ6BYN)yQA*$*nhZ;fW&&9X3?sj1GiFmEx(&OWPmcW@}k&Yo*&PQPNFpOfI_hiQ&L_S
z83GZkffUEOjFDiNjUp{t9A!)+B6e6C%i
z(f-u4&d;azxf(9^0HxVZYV+Cff3>u@4i
zKUn|$C3Cr{4iY=Rl3nBV>AwxwaGZAQ<-iD}CEV808xo%3+xPbQYM-6h@Rh!kBSOGD
zM`5)!%*1^Da|VfcCP0xm!*w+z;7%;Ct)KgthL8jRrOPzs84nQQ~eQUkf
zY&;3NE&c-)l^Pcn?{dp8jb1Ps(&i){OnybxCyZ3v6RaBXsykx-nr=@JH|9(I`c=!e
zzuU6c@yTfvwNjyP;ugT-NC6R{^&eAWrJ3bMPD^cQC+aNPQpIy^>axUicZe@ymr3B0
zYCHsOnGdzjE3Y|EJ1V+eZq64XsqlpksbtoCfpNp6P*YzCLr`m`^{a
zIi?*}ilwS4et+7#RQuIAdU_%*K)DQCHW}nx2NIUN2fncEs|>z3LE7^q?G>RCG838VR6qBRQ)GrmGjEiy
zHwbYFsKrBmNu3H`aAJW6t=r8yT%FKtexK$6!z(9PU9=bTU*|^OPrj0tVHIAiZ2tI^
z{_3kKY^+jhSa9p2?&u<9KAf^QU^gpGT#}9gi*HEGM&nQvsIusIY0Mh0rrb<_rh0oy
z;>Iw%mz22pE0VlI*a}eDBpE-SNUM6b`$O75{P#ZQsfsvM^v7w9ip@<9=LrcVyP+}W
zSj1dJjWbqZT?o;hmjqOdLolyizftEIl-PH{NDwr-)gB8!p<0<0lb~bGBXFDaqQ
zWbi_wo+H4EjhPV9xiC&NICRxVYcVZlU!YthA;;zUZoJIcY))zZ
ze2P{FW1g>&d`DEXo1t+{O}I7IyL)&h+Ir?tZm
z)_qO9mtPI~*KjtMpVvP8;J>{6J23F@MGlap3Zi`3P&poqJ~Rn?64!z
zW^av>sk}cIUJ&%_ZT2#p(Wz=VD0AcUfT4FcFU!s7rB`k5!y+aJG(95<1{>$(E$XQ6
z{h6Fx3O;SIRxRw`UcLs|TkF=FNqM6^q8u;M&N$!eqh#{!>4jOrCC!XIy$-waMae6b
z5j8H@3E$x_mLDyG)atqC9(ERd;Vf?%Hfellv*-9azwW}*vF0-$C#sQ(P5Nw*=k<%R%uEZ(EPAXx$Gm&_Pe>5DR;@iF;}bub!V_zTS5$$
z!d3HjpDb5XLUChUFt)xrp8MkBG1(m4iQDt!p6V`r0cIfl4ooFAY8+L5k$GCb?DEKg
ztEERc`Jd-xrWA(HHVJ8GKO2-HY)q)gMM-L?Q!_p
z8=D#}CyabAb3l%$*3oo(;Zg0{xYT8vj5#z(+(VL*pTBb<(d<_18$Y|uTaUrk4_pwl;uzLTHP;H?d*~Ni3{GjG#PcX(ZXXYltp?={3ZLR
zpoTdlpQ0dGxb20waIL$EwRy`YS0H6Qmhx`fch(?X-EHO4@606GfhCsLz3}tJEj9gF
zdBxx*0SkjXS1@HHV{_yqh`iWFZ2R^zsJ|hANYb3G?T|2#+<^N(fsf?m!1pFh
z)~;7-cwGA*T>|$`m6&12MeP%i?xf!3MlSa}ouzx#ByOMl9l^n>LabJD473NKgdGdr
zOLb0U=h(<)EG#l=eUXd2*d@^tbA_N`;-}Mtu7a>VMMq)z?=rp^b%rz$ik=D@-l=g)W((v@`r+5v
z*q@?mx#zrE(>ZLwL0sy_suXyF=y1}tu$zk6O_*H>U46j#n>pGk8YR|
z5z4O?AzD51SO{6AFmd*EODG$I(@q^E@ouSmH-eP6CEXRn=U$%yL^R7Ly2=onZdv0D
z@ad)!J@R@yhNWM=eX2vs6m$+eaSNW-wwXRu+!}|va4YmIEP+Ic8JZeuj2#57OFfYM
zyGguG#`1Jb_8JBnDAaDF3CC@Enz^1&CIcQ{I1L
z@Le<4Jr0|SYWqSkI3`&2FZxM!qkcYWXw|9+lTOB8XPCFSt
zlK6GpJT|6DyO1y!C#c7l5mTWm0Tls(Ejn`c{}=aU#l6~Rta;Lp!}l(Bxr!;1O9b|F
z1;wYip@gL0JOt13_WeOFC*R`F2l}8QK1TChwke?Aq{trhN*wx$xZ@GI
zH>0Xa!teJU9Ecrm%K|Zy9}hzJ?(o3b*
zF753Iq>I>+0P@aMbfCw%`=uMBq8l8)MY<18`&BJ(rj-xTnOC;*+L=Tno5Yz2*w*gIBbkD|g7r
zZJW*6LRAgRw`;?4YS{fqSru^ONBa-vGjG>$0XRYaS01dgwNd*kE4{z`+5>#dU#Ua}
z>gb+eHmv6Tw92SK2x|yqcETF34*xDlkprRpUbDZ-x6@u+~c
zSC3jxiB=`;oiL3zv5r#~D;(|l13GZDs=Gbg3i!-ro{z!AR!3-DP}IxH{3@ajLkbPt>%O<-<-y=LKxh
zmQBj(vf0Wm&eJQ2OVmN8NI;hck(m#G6gu?uXm(uFL4gQQ
zX1JKR&ZFc_-lGD8Pz5srop6JaF54$8^Ghh^EY=opn{8MCfxNamXJ0K3}iyE)!hVz#!`h6hF%YCct;*elte8HY2T*tFGlA-=SUq;t4`Mm4I
zC32b++wY8~tr5#vC)w9(PC7o3`zKg48v^L(5Ki8Cmlb0(X^;)MugD|#E92RbhzQS{
zcVHH!yy~AXGe7Y_=GFv6Hb%gfTDpZsh&0&sZ_+)s7&(on$&;9_$TF|Vgo|^MiSS<;
zK~fb+i^);G$p!y-74d>#c2uKryhtiT)+`|T-&d5OC=Xm3Vw1;M&X(z
zl4O(duhbWcdA!md+1h<&klM4!?cZ&OoFhx^UPp8LpezUz2mPj>~#`EoCxz3LTk|-10g47
zjN&>%4#8X(#&aA)er*0}WdoNRE8ACbS-eXEx$qowlQTRDmJhy^d>TB>#<8mHIs!2R
zXR398(luH-*b3tP3|B{RDk_jh&66)-XK_e+7>xT^aar`NVn)~*;{sq9e~$pNHvvC@
z4$z!W5#?7v_bVMddgwCE{wrPIit51Y%ELkesvI}_+^0#156h_s)^RvU(Qk}t`Bvr2
zFiZ&qBV>KyHy26~f)+|+wkGPur|S=VhBZ?b6lKm9GCHX(dr^d|+NBqnFvSMnr%qAN
znC3ggw;2khv04*B`;1c8I2%st@oV7{w&%Hz5GV^muY#iv8nLLZme!@-)dAxS(<8Fe
z68CiU07?J-*ns}4z)s2}!{Ad=$@`16W=sd3=
+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 c8a77bc79f2f1..32d0c8743460a 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
-- 
GitLab


From 394709da73bc10f0b2d91495ff2440bc0ede5652 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:14 -0200
Subject: [PATCH 172/193] 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 ec95286e556c9..fff8e3b73e259 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 c18e9c5427ee8..cd28701802086 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 0000000000000..02d7fcf12b26b
--- /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 f19b86c2c24d07d5ae437820944d25489a447d7a..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 12130
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
B;b8y(

diff --git a/Documentation/media/uapi/v4l/pipeline.svg b/Documentation/media/uapi/v4l/pipeline.svg
new file mode 100644
index 0000000000000..70f4c1b23ca1f
--- /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
+
+
+
-- 
GitLab


From 86e6808abbdf302c8e9518e9908ce333ea388351 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:15 -0200
Subject: [PATCH 173/193] 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 +
 .../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 fff8e3b73e259..d97e969c3ac03 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 207349c17ead3..21686f93c38f1 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 bfc523eae570a1edd822a23891b4a499eb9403e1..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 11716
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
VA<5u<+89y5P}lTCp|*X*{{g=L&fx$6

diff --git a/Documentation/media/uapi/v4l/selection.svg b/Documentation/media/uapi/v4l/selection.svg
new file mode 100644
index 0000000000000..d309187af967b
--- /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
+      
+
-- 
GitLab


From ffbdad94d07f89391563d59f1789deb6c9ab4876 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:16 -0200
Subject: [PATCH 174/193] 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 ++++++++++++++++++
 .../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 d97e969c3ac03..998e8dd493525 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 9b15fb22e8173c83c3da6df73cd7cdc7d8f41736..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 9725
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
+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 2f9c135dfadd4..d6152c907b8ba 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**
-- 
GitLab


From ec868e4ee2bcebb9e4c03979d90e0ac0b79fe05a Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:17 -0200
Subject: [PATCH 175/193] 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 a1363379944a5..08b21de3ef94b 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 998e8dd493525..547b4105f8269 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 70f4c1b23ca1f..0000000000000
--- 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
-
-
-
-- 
GitLab


From bf5bfe85ec1e94c58becd3e2cb3385310bc68b81 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:18 -0200
Subject: [PATCH 176/193] 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 547b4105f8269..ab05323b779b7 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 $@
-- 
GitLab


From 293fbd4fefec92f5d8e7d8256f9228a9aaf99070 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:19 -0200
Subject: [PATCH 177/193] 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 a23d3c8b4848a..707c65337ebf3 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 ab05323b779b7..4d8e2ff378c46 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 $@
-- 
GitLab


From c3396656666c2c98db306dc91c480d9fbde35cc9 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Wed, 30 Nov 2016 08:00:20 -0200
Subject: [PATCH 178/193] 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 615e25ec64bb5..96a0423d5dba9 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 20dbdf55c71e2..a958d8b5e99da 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
 
-- 
GitLab


From c3cbf1a704797bc6ba4d3b6cfd766a091081eeaa Mon Sep 17 00:00:00 2001
From: Silvio Fricke 
Date: Mon, 28 Nov 2016 18:30:53 +0100
Subject: [PATCH 179/193] 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 2f2c6cdd73c0c..0000000000000
--- 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 0000000000000..dcda7c623cec6
--- /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 f7ef7fda5763f..480d9a323b60f 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
-- 
GitLab


From c232694ec155daf5a863b25745646edc3f61ba70 Mon Sep 17 00:00:00 2001
From: Silvio Fricke 
Date: Mon, 28 Nov 2016 18:30:54 +0100
Subject: [PATCH 180/193] 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 480d9a323b60f..f53555ee49318 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 0000000000000..1062ddba62c76
--- /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 407576a233177..0000000000000
--- 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 ---
-- 
GitLab


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

... and move to core-api folder.

Signed-off-by: Silvio Fricke 
Signed-off-by: Jonathan Corbet 
---
 .../atomic_ops.rst}                           | 324 +++++++++---------
 Documentation/core-api/index.rst              |   1 +
 .../process/volatile-considered-harmful.rst   |   3 +
 3 files changed, 175 insertions(+), 153 deletions(-)
 rename Documentation/{atomic_ops.txt => core-api/atomic_ops.rst} (77%)

diff --git a/Documentation/atomic_ops.txt b/Documentation/core-api/atomic_ops.rst
similarity index 77%
rename from Documentation/atomic_ops.txt
rename to Documentation/core-api/atomic_ops.rst
index 6c5e8a9d2c6ec..55e43f1c80def 100644
--- a/Documentation/atomic_ops.txt
+++ b/Documentation/core-api/atomic_ops.rst
@@ -1,36 +1,42 @@
-		Semantics and Behavior of Atomic and
-		         Bitmask Operations
+=======================================================
+Semantics and Behavior of Atomic and Bitmask Operations
+=======================================================
 
-			  David S. Miller	 
+:Author: David S. Miller
 
-	This document is intended to serve as a guide to Linux port
+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
+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:
+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.
+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
-Documentation/local_ops.txt for the semantics of local_t.
+: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.
+plain reads. ::
 
 	#define ATOMIC_INIT(i)		{ (i) }
 	#define atomic_set(v, i)	((v)->counter = (i))
 
-The first macro is used in definitions, such as:
+The first macro is used in definitions, such as::
 
-static atomic_t my_counter = ATOMIC_INIT(1);
+	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
@@ -38,10 +44,10 @@ 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.
+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:
+The second interface can be used at runtime, as in::
 
 	struct foo { atomic_t counter; };
 	...
@@ -59,7 +65,7 @@ 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:
+Next, we have::
 
 	#define atomic_read(v)	((v)->counter)
 
@@ -73,20 +79,21 @@ 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! ***
+.. warning::
 
-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.
+	``atomic_read()`` and ``atomic_set()`` DO NOT IMPLY BARRIERS!
 
-*** YOU HAVE BEEN WARNED! ***
+	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
@@ -95,14 +102,14 @@ 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:
+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:
+the following::
 
 	tmp = a;
 	if (a > 0)
@@ -110,14 +117,14 @@ the following:
 			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:
+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:
+For another example, consider the following code::
 
 	tmp_a = a;
 	do_something_with(tmp_a);
@@ -125,7 +132,7 @@ For another example, consider the following code:
 
 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:
+additional load as follows::
 
 	tmp_a = a;
 	do_something_with(tmp_a);
@@ -139,7 +146,7 @@ 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:
+code in this manner, write the following::
 
 	tmp_a = READ_ONCE(a);
 	do_something_with(tmp_a);
@@ -147,7 +154,7 @@ code in this manner, write the following:
 
 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:
+and never changed later, so that memory barriers are not needed::
 
 	if (a)
 		b = 9;
@@ -155,7 +162,7 @@ and never changed later, so that memory barriers are not needed:
 		b = 42;
 
 The compiler is within its rights to manufacture an additional store
-by transforming the above code into the following:
+by transforming the above code into the following::
 
 	b = 42;
 	if (a)
@@ -163,7 +170,7 @@ by transforming the above code into the following:
 
 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:
+the compiler from doing this, write something like::
 
 	if (a)
 		WRITE_ONCE(b, 9);
@@ -173,10 +180,12 @@ the compiler from doing this, write something like:
 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! ***
+.. 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.
+the help of assembly code. ::
 
 	void atomic_add(int i, atomic_t *v);
 	void atomic_sub(int i, atomic_t *v);
@@ -192,7 +201,7 @@ 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:
+Next, we have::
 
 	int atomic_inc_return(atomic_t *v);
 	int atomic_dec_return(atomic_t *v);
@@ -214,7 +223,7 @@ 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:
+Let's move on::
 
 	int atomic_add_return(int i, atomic_t *v);
 	int atomic_sub_return(int i, atomic_t *v);
@@ -224,7 +233,7 @@ 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:
+Next::
 
 	int atomic_inc_and_test(atomic_t *v);
 	int atomic_dec_and_test(atomic_t *v);
@@ -234,13 +243,13 @@ 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.
+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.
+provide explicit memory barrier semantics around the operation::
 
 	int atomic_add_negative(int i, atomic_t *v);
 
@@ -249,7 +258,7 @@ is return which indicates whether the resulting counter value is negative.
 This primitive must provide explicit memory barrier semantics around
 the operation.
 
-Then:
+Then::
 
 	int atomic_xchg(atomic_t *v, int new);
 
@@ -257,14 +266,14 @@ 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.
+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.
+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
@@ -273,7 +282,7 @@ required.
 The semantics for atomic_cmpxchg are the same as those defined for 'cas'
 below.
 
-Finally:
+Finally::
 
 	int atomic_add_unless(atomic_t *v, int a, int u);
 
@@ -289,12 +298,12 @@ 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:
+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:
+For example, smp_mb__before_atomic() can be used like so::
 
 	obj->dead = 1;
 	smp_mb__before_atomic();
@@ -315,67 +324,69 @@ 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;
+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;
+	}
 
-		obj = list_entry(head->next, struct obj, list);
-		atomic_inc(&obj->refcnt);
-		return obj;
+	static void obj_destroy(struct obj *obj)
+	{
+		BUG_ON(obj->active);
+		kfree(obj);
 	}
-	return NULL;
-}
 
-void obj_poke(void)
-{
-	struct obj *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);
 
-	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 (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.)
+	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
@@ -383,7 +394,7 @@ 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:
+sequence looks like this::
 
 	cpu 0				cpu 1
 	obj_poke()			obj_timeout()
@@ -420,6 +431,10 @@ 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.
@@ -427,7 +442,7 @@ 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.
+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);
@@ -437,7 +452,7 @@ 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.
+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);
@@ -466,7 +481,7 @@ 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:
+subsequent memory operation is made visible.  For example::
 
 	obj->dead = 1;
 	if (test_and_set_bit(0, &obj->flags))
@@ -479,7 +494,7 @@ 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:
+Finally there is the basic operation::
 
 	int test_bit(unsigned long nr, __const__ volatile unsigned long *addr);
 
@@ -488,13 +503,13 @@ 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:
+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:
+brothers::
 
 	/* All memory operations before this call will
 	 * be globally visible before the clear_bit().
@@ -511,7 +526,7 @@ 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.
+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);
@@ -526,7 +541,7 @@ 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.
+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);
@@ -542,9 +557,11 @@ 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.
+.. 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:
@@ -558,7 +575,7 @@ The rule to follow is simple:
 
 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.
+but most platforms will wish to optimize this in assembler. ::
 
 	int _atomic_dec_and_lock(atomic_t *atomic, spinlock_t *lock);
 
@@ -573,7 +590,7 @@ 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:
+an abstract atomic operation::
 
 	long cas(long *mem, long old, long new);
 
@@ -584,48 +601,48 @@ an abstract atomic operation:
 3) Regardless, the current value at "mem" is returned.
 
 As an example usage, here is what an atomic counter update
-might look like:
+might look like::
 
-void example_atomic_inc(long *counter)
-{
-	long old, new, ret;
+	void example_atomic_inc(long *counter)
+	{
+		long old, new, ret;
 
-	while (1) {
-		old = *counter;
-		new = old + 1;
+		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;
+			ret = cas(counter, old, new);
+			if (ret == old)
+				break;
 		}
 	}
 
-	return went_to_zero;
-}
+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
@@ -635,6 +652,7 @@ 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.
+.. 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 f53555ee49318..25b4e4a4d0176 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 e0d042af386c4..4934e656a6f35 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
 ------------------------------------------------
 
-- 
GitLab


From 7d56f0facd6c1cb4ed2169bb8e65294bfd7783f8 Mon Sep 17 00:00:00 2001
From: Sanjeev 
Date: Thu, 1 Dec 2016 23:36:00 +0800
Subject: [PATCH 182/193] 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 4e5c3df9d55fb..7425a3351321b 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 7681835ea76de..d6eeb2708b9b2 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 b98eb3b7cb4a5..94f0f58ebe374 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 22642b3fe9032..e782ae2eef587 100644
--- a/Documentation/process/1.Intro.rst
+++ b/Documentation/process/1.Intro.rst
@@ -1,5 +1,5 @@
-Introdution
-===========
+Introduction
+============
 
 Executive summary
 -----------------
-- 
GitLab


From c3cbd075fce77cf3f8782be9f971e8257508c98e Mon Sep 17 00:00:00 2001
From: Balbir Singh 
Date: Fri, 2 Dec 2016 00:08:26 +1100
Subject: [PATCH 183/193] 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 e48c5632bd6c9..456248b272205 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
-- 
GitLab


From 2ba90ccca7758fe77f47750dc8a938a99b8bd4af Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Thu, 1 Dec 2016 10:15:11 -0200
Subject: [PATCH 184/193] 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 dcda7c623cec6..d83cfff9ea43a 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.
-- 
GitLab


From aad800403a8761073511abb93075738302983956 Mon Sep 17 00:00:00 2001
From: Lukas Wunner 
Date: Sun, 4 Dec 2016 13:10:04 +0100
Subject: [PATCH 185/193] 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 0000000000000..5f5713448703a
--- /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 0dec394b9038c..0823a6a52f43c 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
-- 
GitLab


From 20b786eb2598ac10c9743535b65611ce808c8d71 Mon Sep 17 00:00:00 2001
From: Kevin Peng 
Date: Sun, 4 Dec 2016 02:58:02 -0800
Subject: [PATCH 186/193] 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 0c0f2698ec5a4..26b60b4196527 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: [PATCH 187/193] 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 0000000000000..6ac9527aeddb5
--- /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
-- 
GitLab


From 79c87c30d0e6d02b2a7d0f1eed372d0979c03930 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 5 Dec 2016 09:41:42 -0200
Subject: [PATCH 188/193] 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 c08de5574d48e..02583a1f409c2 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/
-- 
GitLab


From 822d289f2872317d2536028d063d1e1b9d9fd76f Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 5 Dec 2016 09:41:43 -0200
Subject: [PATCH 189/193] 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 02583a1f409c2..bd532a7e03e65 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
-- 
GitLab


From a240bfedee7fe2bad1a5ac5d104c513e7fe09d30 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 5 Dec 2016 09:41:44 -0200
Subject: [PATCH 190/193] 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 bd532a7e03e65..272f5c4481f16 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.
-- 
GitLab


From 0f60724f53c2230615c7a3b2abf30a0bc7e8a8de Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Mon, 5 Dec 2016 09:41:45 -0200
Subject: [PATCH 191/193] 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 272f5c4481f16..6d488509285d0 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
-- 
GitLab


From 9e22ff439fa2e1201b168c001683f275afd46258 Mon Sep 17 00:00:00 2001
From: Mauro Carvalho Chehab 
Date: Tue, 6 Dec 2016 10:51:51 -0200
Subject: [PATCH 192/193] 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 6d488509285d0..5bd4b07c2f903 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
-- 
GitLab


From 868c97a846a73e937d835b09b8c885a69df50ec8 Mon Sep 17 00:00:00 2001
From: Daniel Vetter 
Date: Fri, 9 Dec 2016 19:53:05 +0100
Subject: [PATCH 193/193] 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 0000000000000..a9b457a4b949e
--- /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 0823a6a52f43c..a528178a54a54 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 a0d65eb490550..0bb0b5fc95123 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
 -----------------------------
 
-- 
GitLab