From 29efbb24d992564db4bbb808597719934ed9ac9f Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Tue, 24 Sep 2019 16:29:58 -0700 Subject: docs: Use make invocation's -j argument for parallelism While sphinx 1.7 and later supports "-jauto" for parallelism, this effectively ignores the "-j" flag used in the "make" invocation, which may cause confusion for build systems. Instead, extract the available parallelism from "make"'s job server (since it is not exposed in any special variables) and use that for the "sphinx-build" run. Now things work correctly for builds where -j is specified at the top-level: make -j16 htmldocs If -j is not specified, continue to fallback to "-jauto" if available. Signed-off-by: Kees Cook Signed-off-by: Jonathan Corbet --- Documentation/Makefile | 3 ++- scripts/jobserver-count | 58 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+), 1 deletion(-) create mode 100755 scripts/jobserver-count diff --git a/Documentation/Makefile b/Documentation/Makefile index e145e4db508b..c6e564656a5b 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -33,7 +33,7 @@ ifeq ($(HAVE_SPHINX),0) else # HAVE_SPHINX -export SPHINXOPTS = $(shell perl -e 'open IN,"sphinx-build --version 2>&1 |"; while () { if (m/([\d\.]+)/) { print "-jauto" if ($$1 >= "1.7") } ;} close IN') +export SPHINX_PARALLEL = $(shell perl -e 'open IN,"sphinx-build --version 2>&1 |"; while () { if (m/([\d\.]+)/) { print "auto" if ($$1 >= "1.7") } ;} close IN') # User-friendly check for pdflatex and latexmk HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi) @@ -68,6 +68,7 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) PYTHONDONTWRITEBYTECODE=1 \ BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ $(SPHINXBUILD) \ + -j $(shell python $(srctree)/scripts/jobserver-count $(SPHINX_PARALLEL)) \ -b $2 \ -c $(abspath $(srctree)/$(src)) \ -d $(abspath $(BUILDDIR)/.doctrees/$3) \ diff --git a/scripts/jobserver-count b/scripts/jobserver-count new file mode 100755 index 000000000000..0b482d6884d2 --- /dev/null +++ b/scripts/jobserver-count @@ -0,0 +1,58 @@ +#!/usr/bin/env python +# SPDX-License-Identifier: GPL-2.0+ +# +# This determines how many parallel tasks "make" is expecting, as it is +# not exposed via an special variables. +# https://www.gnu.org/software/make/manual/html_node/POSIX-Jobserver.html#POSIX-Jobserver +from __future__ import print_function +import os, sys, fcntl, errno + +# Default parallelism is "1" unless overridden on the command-line. +default="1" +if len(sys.argv) > 1: + default=sys.argv[1] + +# Set non-blocking for a given file descriptor. +def nonblock(fd): + flags = fcntl.fcntl(fd, fcntl.F_GETFL) + fcntl.fcntl(fd, fcntl.F_SETFL, flags | os.O_NONBLOCK) + return fd + +# Extract and prepare jobserver file descriptors from envirnoment. +try: + # Fetch the make environment options. + flags = os.environ['MAKEFLAGS'] + + # Look for "--jobserver=R,W" + opts = [x for x in flags.split(" ") if x.startswith("--jobserver")] + + # Parse out R,W file descriptor numbers and set them nonblocking. + fds = opts[0].split("=", 1)[1] + reader, writer = [int(x) for x in fds.split(",", 1)] + reader = nonblock(reader) +except (KeyError, IndexError, ValueError, IOError): + # Any missing environment strings or bad fds should result in just + # using the default specified parallelism. + print(default) + sys.exit(0) + +# Read out as many jobserver slots as possible. +jobs = b"" +while True: + try: + slot = os.read(reader, 1) + jobs += slot + except (OSError, IOError) as e: + if e.errno == errno.EWOULDBLOCK: + # Stop when reach the end of the jobserver queue. + break + raise e +# Return all the reserved slots. +os.write(writer, jobs) + +# If the jobserver was (impossibly) full or communication failed, use default. +if len(jobs) < 1: + print(default) + +# Report available slots (with a bump for our caller's reserveration). +print(len(jobs) + 1) -- cgit From 631604b492010c92d7ffe887fd05a9fba18f0cc7 Mon Sep 17 00:00:00 2001 From: Martin Kepplinger Date: Tue, 24 Sep 2019 08:28:02 +0200 Subject: mailmap: add new email address for Martin Kepplinger Include my new email address for tracking my contributions. Signed-off-by: Martin Kepplinger Signed-off-by: Jonathan Corbet --- .mailmap | 1 + 1 file changed, 1 insertion(+) diff --git a/.mailmap b/.mailmap index edcac87e76c8..70105bb57650 100644 --- a/.mailmap +++ b/.mailmap @@ -151,6 +151,7 @@ Mark Brown Mark Yao Martin Kepplinger Martin Kepplinger +Martin Kepplinger Mathieu Othacehe Matthew Wilcox Matthew Wilcox -- cgit From 9fde576f78740d6dfdc5395aa7f1652369bc6e3f Mon Sep 17 00:00:00 2001 From: Martin Kepplinger Date: Tue, 24 Sep 2019 08:28:03 +0200 Subject: CREDITS: update email address for Martin Kepplinger Employers change - Linux stays. Also, add my (long time valid) GPG key fingerprint to the contact details. Signed-off-by: Martin Kepplinger Signed-off-by: Jonathan Corbet --- CREDITS | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CREDITS b/CREDITS index 8b67a85844b5..53c556a0c54e 100644 --- a/CREDITS +++ b/CREDITS @@ -1871,8 +1871,9 @@ S: The Netherlands N: Martin Kepplinger E: martink@posteo.de -E: martin.kepplinger@ginzinger.com +E: martin.kepplinger@puri.sm W: http://www.martinkepplinger.com +P: 4096R/5AB387D3 F208 2B88 0F9E 4239 3468 6E3F 5003 98DF 5AB3 87D3 D: mma8452 accelerators iio driver D: pegasus_notetaker input driver D: Kernel fixes and cleanups -- cgit From 6795b29c1ca04d5779885fbb5c971f14ec722d55 Mon Sep 17 00:00:00 2001 From: Brendan Jackman Date: Wed, 25 Sep 2019 17:17:44 +0700 Subject: docs: security: fix section hyperlink The reStructuredText syntax is wrong here; not sure how it was intended but we can just use the section header as an implicit hyperlink target, with a single "outward" underscore. Signed-off-by: Brendan Jackman Signed-off-by: Jonathan Corbet --- Documentation/security/lsm.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/security/lsm.rst b/Documentation/security/lsm.rst index ad4dfd020e0d..aadf47c808c0 100644 --- a/Documentation/security/lsm.rst +++ b/Documentation/security/lsm.rst @@ -56,7 +56,7 @@ the infrastructure to support security modules. The LSM kernel patch also moves most of the capabilities logic into an optional security module, with the system defaulting to the traditional superuser logic. This capabilities module is discussed further in -`LSM Capabilities Module <#cap>`__. +`LSM Capabilities Module`_. The LSM kernel patch adds security fields to kernel data structures and inserts calls to hook functions at critical points in the kernel code to -- cgit From 2c861bf5e6ff2353239ada5535dfbbe1314ac13b Mon Sep 17 00:00:00 2001 From: Jeremy Cline Date: Wed, 25 Sep 2019 14:31:14 +0000 Subject: docs: kmemleak: DEBUG_KMEMLEAK_EARLY_LOG_SIZE changed names Commit c5665868183f ("mm: kmemleak: use the memory pool for early allocations") renamed CONFIG_DEBUG_KMEMLEAK_EARLY_LOG_SIZE to CONFIG_DEBUG_KMEMLEAK_MEM_POOL_SIZE. Update the documentation reference to reflect that. Fixes: c5665868183f ("mm: kmemleak: use the memory pool for early allocations") Signed-off-by: Jeremy Cline Acked-by: Catalin Marinas Signed-off-by: Jonathan Corbet --- Documentation/dev-tools/kmemleak.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/dev-tools/kmemleak.rst b/Documentation/dev-tools/kmemleak.rst index 3621cd5e1eef..3a289e8a1d12 100644 --- a/Documentation/dev-tools/kmemleak.rst +++ b/Documentation/dev-tools/kmemleak.rst @@ -69,7 +69,7 @@ the kernel command line. Memory may be allocated or freed before kmemleak is initialised and these actions are stored in an early log buffer. The size of this buffer -is configured via the CONFIG_DEBUG_KMEMLEAK_EARLY_LOG_SIZE option. +is configured via the CONFIG_DEBUG_KMEMLEAK_MEM_POOL_SIZE option. If CONFIG_DEBUG_KMEMLEAK_DEFAULT_OFF are enabled, the kmemleak is disabled by default. Passing ``kmemleak=on`` on the kernel command -- cgit From 6ee0fac199e108f544b0ac23b2419a03ff6dc18f Mon Sep 17 00:00:00 2001 From: Jon Haslam Date: Wed, 25 Sep 2019 12:56:04 -0700 Subject: docs: fix memory.low description in cgroup-v2.rst The current cgroup-v2.rst file contains an incorrect description of when memory is reclaimed from a cgroup that is using the 'memory.low' mechanism. This fix simply corrects the text to reflect the actual implementation. Fixes: 7854207fe954 ("mm/docs: describe memory.low refinements") Signed-off-by: Jon Haslam Acked-by: Roman Gushchin Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/cgroup-v2.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst index 0fa8c0e615c2..26d1cde6b34a 100644 --- a/Documentation/admin-guide/cgroup-v2.rst +++ b/Documentation/admin-guide/cgroup-v2.rst @@ -1117,8 +1117,8 @@ PAGE_SIZE multiple when read back. Best-effort memory protection. If the memory usage of a cgroup is within its effective low boundary, the cgroup's - memory won't be reclaimed unless memory can be reclaimed - from unprotected cgroups. + memory won't be reclaimed unless there is no reclaimable + memory available in unprotected cgroups. Effective low boundary is limited by memory.low values of all ancestor cgroups. If there is memory.low overcommitment @@ -1914,7 +1914,7 @@ Cpuset Interface Files It accepts only the following input values when written to. - "root" - a paritition root + "root" - a partition root "member" - a non-root member of a partition When set to be a partition root, the current cgroup is the -- cgit From 2730ce017fa6df49bad9ad932932b863f63a4b50 Mon Sep 17 00:00:00 2001 From: Shuah Khan Date: Wed, 18 Sep 2019 18:37:54 -0600 Subject: scripts/sphinx-pre-install: add how to exit virtualenv usage message Add usage message on how to exit the virtualenv after documentation work is done. Signed-off-by: Shuah Khan Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 3b638c0e1a4f..013099cd120d 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -645,6 +645,12 @@ sub check_distros() # Common dependencies # +sub deactivate_help() +{ + printf "\tIf you want to exit the virtualenv, you can use:\n"; + printf "\tdeactivate\n"; +} + sub check_needs() { # Check for needed programs/tools @@ -686,6 +692,7 @@ sub check_needs() if ($need_sphinx && scalar @activates > 0 && $activates[0] ge $min_activate) { printf "\nNeed to activate a compatible Sphinx version on virtualenv with:\n"; printf "\t. $activates[0]\n"; + deactivate_help(); exit (1); } else { my $rec_activate = "$virtenv_dir/bin/activate"; @@ -697,6 +704,7 @@ sub check_needs() printf "\t$virtualenv $virtenv_dir\n"; printf "\t. $rec_activate\n"; printf "\tpip install -r $requirement_file\n"; + deactivate_help(); $need++ if (!$rec_sphinx_upgrade); } -- cgit From 2b5f78e5e942d76e5497f53c2298900224b52c51 Mon Sep 17 00:00:00 2001 From: André Almeida Date: Tue, 17 Sep 2019 16:41:45 -0300 Subject: kernel-doc: fix processing nested structs with attributes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The current regular expression for strip attributes of structs (and for nested ones as well) also removes all whitespaces that may surround the attribute. After that, the code will split structs and iterate for each symbol separated by comma at the end of struct definition (e.g. "} alias1, alias2;"). However, if the nested struct does not have any alias and has an attribute, it will result in a empty string at the closing bracket (e.g "};"). This will make the split return nothing and $newmember will keep uninitialized. Fix that, by ensuring that the attribute substitution will leave at least one whitespace. Signed-off-by: André Almeida Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 81dc91760b23..baa2be7e5284 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1073,10 +1073,10 @@ sub dump_struct($$) { # strip comments: $members =~ s/\/\*.*?\*\///gos; # strip attributes - $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)//gi; - $members =~ s/\s*__aligned\s*\([^;]*\)//gos; - $members =~ s/\s*__packed\s*//gos; - $members =~ s/\s*CRYPTO_MINALIGN_ATTR//gos; + $members =~ s/\s*__attribute__\s*\(\([a-z0-9,_\*\s\(\)]*\)\)/ /gi; + $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos; + $members =~ s/\s*__packed\s*/ /gos; + $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos; # replace DECLARE_BITMAP $members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos; # replace DECLARE_HASHTABLE -- cgit From f861537d5f856f8bffc7ddd1f9c1a59bfed0012a Mon Sep 17 00:00:00 2001 From: André Almeida Date: Tue, 17 Sep 2019 16:41:46 -0300 Subject: kernel-doc: add support for ____cacheline_aligned_in_smp attribute MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Subroutine dump_struct uses type attributes to check if the struct syntax is valid. Then, it removes all attributes before using it for output. `____cacheline_aligned_in_smp` is an attribute that is not included in both steps. Add it, since it is used by kernel structs. Signed-off-by: André Almeida Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index baa2be7e5284..a529375c8536 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1062,7 +1062,7 @@ sub dump_struct($$) { my $x = shift; my $file = shift; - if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) { + if ($x =~ /(struct|union)\s+(\w+)\s*\{(.*)\}(\s*(__packed|__aligned|____cacheline_aligned_in_smp|__attribute__\s*\(\([a-z0-9,_\s\(\)]*\)\)))*/) { my $decl_type = $1; $declaration_name = $2; my $members = $3; @@ -1077,6 +1077,7 @@ sub dump_struct($$) { $members =~ s/\s*__aligned\s*\([^;]*\)/ /gos; $members =~ s/\s*__packed\s*/ /gos; $members =~ s/\s*CRYPTO_MINALIGN_ATTR/ /gos; + $members =~ s/\s*____cacheline_aligned_in_smp/ /gos; # replace DECLARE_BITMAP $members =~ s/DECLARE_BITMAP\s*\(([^,)]+),\s*([^,)]+)\)/unsigned long $1\[BITS_TO_LONGS($2)\]/gos; # replace DECLARE_HASHTABLE -- cgit From 0522e130b00a6c20fcf335f41e8b4d2ff3c0ffea Mon Sep 17 00:00:00 2001 From: Adam Zerella Date: Sun, 15 Sep 2019 18:20:10 +1000 Subject: docs: perf: Add imx-ddr to documentation index Sphinx is currently outputting a warning where the file 'imx-ddr.rst' is not included in the documentation index. Additionally, the code highlighting and doc formatting can be slightly improved. Signed-off-by: Adam Zerella Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/perf/imx-ddr.rst | 35 +++++++++++++++++++----------- Documentation/admin-guide/perf/index.rst | 1 + 2 files changed, 23 insertions(+), 13 deletions(-) diff --git a/Documentation/admin-guide/perf/imx-ddr.rst b/Documentation/admin-guide/perf/imx-ddr.rst index 517a205abad6..92900b851f5d 100644 --- a/Documentation/admin-guide/perf/imx-ddr.rst +++ b/Documentation/admin-guide/perf/imx-ddr.rst @@ -18,7 +18,9 @@ The "format" directory describes format of the config (event ID) and config1 devices/imx8_ddr0/format/. The "events" directory describes the events types hardware supported that can be used with perf tool, see /sys/bus/event_source/ devices/imx8_ddr0/events/. - e.g.:: + + .. code-block:: bash + perf stat -a -e imx8_ddr0/cycles/ cmd perf stat -a -e imx8_ddr0/read/,imx8_ddr0/write/ cmd @@ -31,22 +33,29 @@ in the driver. Filter is defined with two configuration parts: --AXI_ID defines AxID matching value. --AXI_MASKING defines which bits of AxID are meaningful for the matching. - 0：corresponding bit is masked. - 1: corresponding bit is not masked, i.e. used to do the matching. + + - 0: corresponding bit is masked. + - 1: corresponding bit is not masked, i.e. used to do the matching. AXI_ID and AXI_MASKING are mapped on DPCR1 register in performance counter. When non-masked bits are matching corresponding AXI_ID bits then counter is incremented. Perf counter is incremented if - AxID && AXI_MASKING == AXI_ID && AXI_MASKING + AxID && AXI_MASKING == AXI_ID && AXI_MASKING This filter doesn't support filter different AXI ID for axid-read and axid-write event at the same time as this filter is shared between counters. - e.g.:: - perf stat -a -e imx8_ddr0/axid-read,axi_mask=0xMMMM,axi_id=0xDDDD/ cmd - perf stat -a -e imx8_ddr0/axid-write,axi_mask=0xMMMM,axi_id=0xDDDD/ cmd - - NOTE: axi_mask is inverted in userspace(i.e. set bits are bits to mask), and - it will be reverted in driver automatically. so that the user can just specify - axi_id to monitor a specific id, rather than having to specify axi_mask. - e.g.:: - perf stat -a -e imx8_ddr0/axid-read,axi_id=0x12/ cmd, which will monitor ARID=0x12 + + .. code-block:: bash + + perf stat -a -e imx8_ddr0/axid-read,axi_mask=0xMMMM,axi_id=0xDDDD/ cmd + perf stat -a -e imx8_ddr0/axid-write,axi_mask=0xMMMM,axi_id=0xDDDD/ cmd + + .. note:: + + axi_mask is inverted in userspace(i.e. set bits are bits to mask), and + it will be reverted in driver automatically. so that the user can just specify + axi_id to monitor a specific id, rather than having to specify axi_mask. + + .. code-block:: bash + + perf stat -a -e imx8_ddr0/axid-read,axi_id=0x12/ cmd, which will monitor ARID=0x12 diff --git a/Documentation/admin-guide/perf/index.rst b/Documentation/admin-guide/perf/index.rst index ee4bfd2a740f..47c99f40cc16 100644 --- a/Documentation/admin-guide/perf/index.rst +++ b/Documentation/admin-guide/perf/index.rst @@ -8,6 +8,7 @@ Performance monitor support :maxdepth: 1 hisi-pmu + imx-ddr qcom_l2_pmu qcom_l3_pmu arm-ccn -- cgit From e18409c0589f0abf97d706781e4415f9e89dcef7 Mon Sep 17 00:00:00 2001 From: Christoph Hellwig Date: Tue, 17 Sep 2019 09:15:23 +0200 Subject: Documentation: document earlycon without options for more platforms The earlycon options without arguments is supposed to work on all device tree platforms, not just arm64. Signed-off-by: Christoph Hellwig Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/kernel-parameters.txt | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index c7ac2f3ac99f..edf65dad250b 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -983,12 +983,10 @@ earlycon= [KNL] Output early console device and options. - [ARM64] The early console is determined by the - stdout-path property in device tree's chosen node, - or determined by the ACPI SPCR table. - - [X86] When used with no options the early console is - determined by the ACPI SPCR table. + When used with no options, the early console is + determined by stdout-path property in device tree's + chosen node or the ACPI SPCR table if supported by + the platform. cdns,[,options] Start an early, polled-mode console on a Cadence -- cgit From e07f7927d52b89947fd32174a013742269cac3d8 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 1 Oct 2019 08:43:21 -0600 Subject: docs: No structured comments in kernel/dma/coherent.c Don't try to extract comments from that file, since there are none to be had and, seemingly, never have been. Signed-off-by: Jonathan Corbet --- Documentation/driver-api/infrastructure.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst index 6172f3cc3d0b..06d98c4526df 100644 --- a/Documentation/driver-api/infrastructure.rst +++ b/Documentation/driver-api/infrastructure.rst @@ -49,9 +49,6 @@ Device Drivers Base Device Drivers DMA Management ----------------------------- -.. kernel-doc:: kernel/dma/coherent.c - :export: - .. kernel-doc:: kernel/dma/mapping.c :export: -- cgit From 1b1438b5351f54d3fb8b3cc1579dea7668b03ca0 Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Tue, 1 Oct 2019 11:25:31 -0700 Subject: doc-rst: Reduce CSS padding around Field Right now any ":Field Name: Field Contents" lines end up with significant padding due to CSS from the "table" CSS which rightly needs padding to make tables readable. However, field lists don't need this as they tend to be stacked together. The future heavy use of fields in the parsed MAINTAINERS file needs this cleaned up, and existing users look better too. Note the needless white space (and misalignment of name/contents) between "Date" and "Author": https://www.kernel.org/doc/html/latest/accounting/psi.html This patch fixes this by lowering the padding with a more specific CSS. Signed-off-by: Kees Cook Signed-off-by: Jonathan Corbet --- Documentation/sphinx-static/theme_overrides.css | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css index e21e36cd6761..459ec5b29d68 100644 --- a/Documentation/sphinx-static/theme_overrides.css +++ b/Documentation/sphinx-static/theme_overrides.css @@ -53,6 +53,16 @@ div[class^="highlight"] pre { line-height: normal; } +/* Keep fields from being strangely far apart due to inheirited table CSS. */ +.rst-content table.field-list th.field-name { + padding-top: 1px; + padding-bottom: 1px; +} +.rst-content table.field-list td.field-body { + padding-top: 1px; + padding-bottom: 1px; +} + @media screen { /* content column -- cgit From aa204855281389fe25c0049190531ba67e043d99 Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Tue, 1 Oct 2019 11:25:32 -0700 Subject: doc-rst: Programmatically render MAINTAINERS into ReST In order to have the MAINTAINERS file visible in the rendered ReST output, this makes some small changes to the existing MAINTAINERS file to allow for better machine processing, and adds a new Sphinx directive "maintainers-include" to perform the rendering. Features include: - Per-subsystem reference links: subsystem maintainer entries can be trivially linked to both internally and external. For example: https://www.kernel.org/doc/html/latest/process/maintainers.html#secure-computing - Internally referenced .rst files are linked so they can be followed when browsing the resulting rendering. This allows, for example, the future addition of maintainer profiles to be automatically linked. - Field name expansion: instead of the short fields (e.g. "M", "F", "K"), use the indicated inline "full names" for the fields (which are marked with "*"s in MAINTAINERS) so that a rendered subsystem entry is more human readable. Email lists are additionally comma-separated. For example: SECURE COMPUTING Mail: Kees Cook Reviewer: Andy Lutomirski , Will Drewry SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git seccomp Status: Supported Files: kernel/seccomp.c include/uapi/linux/seccomp.h include/linux/seccomp.h tools/testing/selftests/seccomp/* tools/testing/selftests/kselftest_harness.h userspace-api/seccomp_filter Content regex: \bsecure_computing \bTIF_SECCOMP\b Signed-off-by: Kees Cook Signed-off-by: Jonathan Corbet --- Documentation/conf.py | 3 +- Documentation/process/index.rst | 1 + Documentation/process/maintainers.rst | 1 + Documentation/sphinx/maintainers_include.py | 197 ++++++++++++++++++++++++++++ MAINTAINERS | 62 ++++----- 5 files changed, 233 insertions(+), 31 deletions(-) create mode 100644 Documentation/process/maintainers.rst create mode 100755 Documentation/sphinx/maintainers_include.py diff --git a/Documentation/conf.py b/Documentation/conf.py index a8fe845832bc..3c7bdf4cd31f 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -37,7 +37,8 @@ needs_sphinx = '1.3' # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', - 'kfigure', 'sphinx.ext.ifconfig', 'automarkup'] + 'kfigure', 'sphinx.ext.ifconfig', 'automarkup', + 'maintainers_include'] # The name of the math extension changed on Sphinx 1.4 if (major == 1 and minor > 3) or (major > 1): diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index e2c9ffc682c5..e2fb0c9652ac 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -46,6 +46,7 @@ Other guides to the community that are of interest to most developers are: kernel-docs deprecated embargoed-hardware-issues + maintainers These are some overall technical guides that have been put here for now for lack of a better place. diff --git a/Documentation/process/maintainers.rst b/Documentation/process/maintainers.rst new file mode 100644 index 000000000000..6174cfb4138f --- /dev/null +++ b/Documentation/process/maintainers.rst @@ -0,0 +1 @@ +.. maintainers-include:: diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py new file mode 100755 index 000000000000..dc8fed48d3c2 --- /dev/null +++ b/Documentation/sphinx/maintainers_include.py @@ -0,0 +1,197 @@ +#!/usr/bin/env python +# SPDX-License-Identifier: GPL-2.0 +# -*- coding: utf-8; mode: python -*- +# pylint: disable=R0903, C0330, R0914, R0912, E0401 + +u""" + maintainers-include + ~~~~~~~~~~~~~~~~~~~ + + Implementation of the ``maintainers-include`` reST-directive. + + :copyright: Copyright (C) 2019 Kees Cook + :license: GPL Version 2, June 1991 see linux/COPYING for details. + + The ``maintainers-include`` reST-directive performs extensive parsing + specific to the Linux kernel's standard "MAINTAINERS" file, in an + effort to avoid needing to heavily mark up the original plain text. +""" + +import sys +import re +import os.path + +from docutils import statemachine +from docutils.utils.error_reporting import ErrorString +from docutils.parsers.rst import Directive +from docutils.parsers.rst.directives.misc import Include + +__version__ = '1.0' + +def setup(app): + app.add_directive("maintainers-include", MaintainersInclude) + return dict( + version = __version__, + parallel_read_safe = True, + parallel_write_safe = True + ) + +class MaintainersInclude(Include): + u"""MaintainersInclude (``maintainers-include``) directive""" + required_arguments = 0 + + def parse_maintainers(self, path): + """Parse all the MAINTAINERS lines into ReST for human-readability""" + + result = list() + result.append(".. _maintainers:") + result.append("") + + # Poor man's state machine. + descriptions = False + maintainers = False + subsystems = False + + # Field letter to field name mapping. + field_letter = None + fields = dict() + + prev = None + field_prev = "" + field_content = "" + + for line in open(path): + if sys.version_info.major == 2: + line = unicode(line, 'utf-8') + # Have we reached the end of the preformatted Descriptions text? + if descriptions and line.startswith('Maintainers'): + descriptions = False + # Ensure a blank line following the last "|"-prefixed line. + result.append("") + + # Start subsystem processing? This is to skip processing the text + # between the Maintainers heading and the first subsystem name. + if maintainers and not subsystems: + if re.search('^[A-Z0-9]', line): + subsystems = True + + # Drop needless input whitespace. + line = line.rstrip() + + # Linkify all non-wildcard refs to ReST files in Documentation/. + pat = '(Documentation/([^\s\?\*]*)\.rst)' + m = re.search(pat, line) + if m: + # maintainers.rst is in a subdirectory, so include "../". + line = re.sub(pat, ':doc:`%s <../%s>`' % (m.group(2), m.group(2)), line) + + # Check state machine for output rendering behavior. + output = None + if descriptions: + # Escape the escapes in preformatted text. + output = "| %s" % (line.replace("\\", "\\\\")) + # Look for and record field letter to field name mappings: + # R: Designated *reviewer*: FullName + m = re.search("\s(\S):\s", line) + if m: + field_letter = m.group(1) + if field_letter and not field_letter in fields: + m = re.search("\*([^\*]+)\*", line) + if m: + fields[field_letter] = m.group(1) + elif subsystems: + # Skip empty lines: subsystem parser adds them as needed. + if len(line) == 0: + continue + # Subsystem fields are batched into "field_content" + if line[1] != ':': + # Render a subsystem entry as: + # SUBSYSTEM NAME + # ~~~~~~~~~~~~~~ + + # Flush pending field content. + output = field_content + "\n\n" + field_content = "" + + # Collapse whitespace in subsystem name. + heading = re.sub("\s+", " ", line) + output = output + "%s\n%s" % (heading, "~" * len(heading)) + field_prev = "" + else: + # Render a subsystem field as: + # :Field: entry + # entry... + field, details = line.split(':', 1) + details = details.strip() + + # Mark paths (and regexes) as literal text for improved + # readability and to escape any escapes. + if field in ['F', 'N', 'X', 'K']: + # But only if not already marked :) + if not ':doc:' in details: + details = '``%s``' % (details) + + # Comma separate email field continuations. + if field == field_prev and field_prev in ['M', 'R', 'L']: + field_content = field_content + "," + + # Do not repeat field names, so that field entries + # will be collapsed together. + if field != field_prev: + output = field_content + "\n" + field_content = ":%s:" % (fields.get(field, field)) + field_content = field_content + "\n\t%s" % (details) + field_prev = field + else: + output = line + + # Re-split on any added newlines in any above parsing. + if output != None: + for separated in output.split('\n'): + result.append(separated) + + # Update the state machine when we find heading separators. + if line.startswith('----------'): + if prev.startswith('Descriptions'): + descriptions = True + if prev.startswith('Maintainers'): + maintainers = True + + # Retain previous line for state machine transitions. + prev = line + + # Flush pending field contents. + if field_content != "": + for separated in field_content.split('\n'): + result.append(separated) + + output = "\n".join(result) + # For debugging the pre-rendered results... + #print(output, file=open("/tmp/MAINTAINERS.rst", "w")) + + self.state_machine.insert_input( + statemachine.string2lines(output), path) + + def run(self): + """Include the MAINTAINERS file as part of this reST file.""" + if not self.state.document.settings.file_insertion_enabled: + raise self.warning('"%s" directive disabled.' % self.name) + + # Walk up source path directories to find Documentation/../ + path = self.state_machine.document.attributes['source'] + path = os.path.realpath(path) + tail = path + while tail != "Documentation" and tail != "": + (path, tail) = os.path.split(path) + + # Append "MAINTAINERS" + path = os.path.join(path, "MAINTAINERS") + + try: + self.state.document.settings.record_dependencies.add(path) + lines = self.parse_maintainers(path) + except IOError as error: + raise self.severe('Problems with "%s" directive path:\n%s.' % + (self.name, ErrorString(error))) + + return [] diff --git a/MAINTAINERS b/MAINTAINERS index 296de2b51c83..b20bc42f6a92 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1,12 +1,14 @@ - - - List of maintainers and how to submit kernel changes +List of maintainers and how to submit kernel changes +==================================================== Please try to follow the guidelines below. This will make things easier on the maintainers. Not all of these guidelines matter for every trivial patch so apply some common sense. -1. Always _test_ your changes, however small, on at least 4 or +Tips for patch submitters +------------------------- + +1. Always *test* your changes, however small, on at least 4 or 5 people, preferably many more. 2. Try to release a few ALPHA test versions to the net. Announce @@ -25,7 +27,7 @@ trivial patch so apply some common sense. testing and await feedback. 5. Make a patch available to the relevant maintainer in the list. Use - 'diff -u' to make the patch easy to merge. Be prepared to get your + ``diff -u`` to make the patch easy to merge. Be prepared to get your changes sent back with seemingly silly requests about formatting and variable names. These aren't as silly as they seem. One job the maintainers (and especially Linus) do is to keep things @@ -38,7 +40,7 @@ trivial patch so apply some common sense. 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 + 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/process/submitting-patches.rst for details. @@ -70,26 +72,27 @@ trivial patch so apply some common sense. not represent an immediate threat and are better handled publicly, and ideally, should come with a patch proposal. Please do not send automated reports to this list either. Such bugs will be handled - better and faster in the usual public places. + better and faster in the usual public places. See + Documentation/admin-guide/security-bugs.rst for details. 8. Happy hacking. -Descriptions of section entries: +Descriptions of section entries +------------------------------- - P: Person (obsolete) - M: Mail patches to: FullName - R: Designated reviewer: FullName + M: *Mail* patches to: FullName + R: Designated *Reviewer*: FullName These reviewers should be CCed on patches. - L: Mailing list that is relevant to this area - W: Web-page with status/info - B: URI for where to file bugs. A web-page with detailed bug + L: *Mailing list* that is relevant to this area + W: *Web-page* with status/info + B: URI for where to file *bugs*. A web-page with detailed bug filing info, a direct bug tracker link, or a mailto: URI. - C: URI for chat protocol, server and channel where developers + C: URI for *chat* protocol, server and channel where developers usually hang out, for example irc://server/channel. - Q: Patchwork web based patch tracking system site - T: SCM tree type and location. + Q: *Patchwork* web based patch tracking system site + T: *SCM* tree type and location. Type is one of: git, hg, quilt, stgit, topgit - S: Status, one of the following: + S: *Status*, one of the following: Supported: Someone is actually paid to look after this. Maintained: Someone actually looks after it. Odd Fixes: It has a maintainer but they don't have time to do @@ -99,13 +102,13 @@ Descriptions of section entries: Obsolete: Old code. Something tagged obsolete generally means it has been replaced by a better system and you should be using that. - F: Files and directories with wildcard patterns. + F: *Files* and directories wildcard patterns. A trailing slash includes all files and subdirectory files. F: drivers/net/ all files in and below drivers/net F: drivers/net/* all files in drivers/net, but not below F: */net/* all files in "any top level directory"/net One pattern per line. Multiple F: lines acceptable. - N: Files and directories with regex patterns. + N: Files and directories *Regex* patterns. N: [^a-z]tegra all files whose path contains the word tegra One pattern per line. Multiple N: lines acceptable. scripts/get_maintainer.pl has different behavior for files that @@ -113,14 +116,14 @@ Descriptions of section entries: get_maintainer will not look at git log history when an F: pattern match occurs. When an N: match occurs, git log history is used to also notify the people that have git commit signatures. - X: Files and directories that are NOT maintained, same rules as F: - Files exclusions are tested before file matches. + X: *Excluded* files and directories that are NOT maintained, same + rules as F:. Files exclusions are tested before file matches. Can be useful for excluding a specific subdirectory, for instance: F: net/ X: net/ipv6/ matches all files in and below net excluding net/ipv6/ - K: Keyword perl extended regex pattern to match content in a - patch or file. For instance: + K: *Content regex* (perl extended) pattern match in a patch or file. + For instance: K: of_get_profile matches patches or files that contain "of_get_profile" K: \b(printk|pr_(info|err))\b @@ -128,13 +131,12 @@ Descriptions of section entries: printk, pr_info or pr_err One regex pattern per line. Multiple K: lines acceptable. -Note: For the hard of thinking, this list is meant to remain in alphabetical -order. If you could add yourselves to it in alphabetical order that would be -so much easier [Ed] - -Maintainers List (try to look for most precise areas first) +Maintainers List +---------------- - ----------------------------------- +.. note:: When reading this list, please look for the most precise areas + first. When adding to this list, please keep the entries in + alphabetical order. 3C59X NETWORK DRIVER M: Steffen Klassert -- cgit From ba71cc5c40a7869decb15bab84a417483d15c10e Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Wed, 2 Oct 2019 17:18:39 +0200 Subject: docs: it_IT: maintainer-pgp-guide: Fix reference to "Nitrokey Pro 2" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This fixes the following Sphinx warning: Documentation/translations/it_IT/process/maintainer-pgp-guide.rst:458: WARNING: Unknown target name: "nitrokey pro". Signed-off-by: Jonathan Neuschäfer Signed-off-by: Jonathan Corbet --- Documentation/translations/it_IT/process/maintainer-pgp-guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst index 118fb4153e8f..f3c8e8d377ee 100644 --- a/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst +++ b/Documentation/translations/it_IT/process/maintainer-pgp-guide.rst @@ -455,7 +455,7 @@ soluzioni disponibili: `GnuK`_ della FSIJ. Questo è uno dei pochi dispositivi a supportare le chiavi ECC ED25519, ma offre meno funzionalità di sicurezza (come la resistenza alla manomissione o alcuni attacchi ad un canale laterale). -- `Nitrokey Pro`_: è simile alla Nitrokey Start, ma è più resistente alla +- `Nitrokey Pro 2`_: è simile alla Nitrokey Start, ma è più resistente alla manomissione e offre più funzionalità di sicurezza. La Pro 2 supporta la crittografia ECC (NISTP). - `Yubikey 5`_: l'hardware e il software sono proprietari, ma è più economica -- cgit From bdd68860a044683ea3a96a4f3a681da155fe7197 Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Wed, 2 Oct 2019 17:09:55 +0200 Subject: Documentation: networking: device drivers: Remove stray asterisks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit These asterisks were once references to a line that said: "* Other names and brands may be claimed as the property of others." But now, they serve no purpose; they can only irritate the reader. Fixes: f12a84a9f650 ("Documentation: fm10k: Add kernel documentation") Fixes: 1e06edcc2f22 ("Documentation: i40e: Prepare documentation for RST conversion") Fixes: 1fae869bcf3d ("Documentation: ice: Prepare documentation for RST conversion") Fixes: df69ba43217d ("ionic: Add basic framework for IONIC Network device driver") Signed-off-by: Jonathan Neuschäfer Acked-by: Shannon Nelson Acked-by: David S. Miller Signed-off-by: Jonathan Corbet --- Documentation/networking/device_drivers/intel/e100.rst | 14 +++++++------- Documentation/networking/device_drivers/intel/e1000.rst | 12 ++++++------ Documentation/networking/device_drivers/intel/e1000e.rst | 14 +++++++------- Documentation/networking/device_drivers/intel/fm10k.rst | 10 +++++----- Documentation/networking/device_drivers/intel/i40e.rst | 8 ++++---- Documentation/networking/device_drivers/intel/iavf.rst | 8 ++++---- Documentation/networking/device_drivers/intel/ice.rst | 6 +++--- Documentation/networking/device_drivers/intel/igb.rst | 12 ++++++------ Documentation/networking/device_drivers/intel/igbvf.rst | 6 +++--- Documentation/networking/device_drivers/intel/ixgbe.rst | 10 +++++----- Documentation/networking/device_drivers/intel/ixgbevf.rst | 6 +++--- Documentation/networking/device_drivers/pensando/ionic.rst | 6 +++--- 12 files changed, 56 insertions(+), 56 deletions(-) diff --git a/Documentation/networking/device_drivers/intel/e100.rst b/Documentation/networking/device_drivers/intel/e100.rst index 2b9f4887beda..5a26a0e326ea 100644 --- a/Documentation/networking/device_drivers/intel/e100.rst +++ b/Documentation/networking/device_drivers/intel/e100.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -============================================================== -Linux* Base Driver for the Intel(R) PRO/100 Family of Adapters -============================================================== +============================================================= +Linux Base Driver for the Intel(R) PRO/100 Family of Adapters +============================================================= June 1, 2018 @@ -21,7 +21,7 @@ Contents In This Release =============== -This file describes the Linux* Base Driver for the Intel(R) PRO/100 Family of +This file describes the Linux Base Driver for the Intel(R) PRO/100 Family of Adapters. This driver includes support for Itanium(R)2-based systems. For questions related to hardware requirements, refer to the documentation @@ -138,9 +138,9 @@ version 1.6 or later is required for this functionality. The latest release of ethtool can be found from https://www.kernel.org/pub/software/network/ethtool/ -Enabling Wake on LAN* (WoL) ---------------------------- -WoL is provided through the ethtool* utility. For instructions on +Enabling Wake on LAN (WoL) +-------------------------- +WoL is provided through the ethtool utility. For instructions on enabling WoL with ethtool, refer to the ethtool man page. WoL will be enabled on the system during the next shut down or reboot. For this driver version, in order to enable WoL, the e100 driver must be loaded diff --git a/Documentation/networking/device_drivers/intel/e1000.rst b/Documentation/networking/device_drivers/intel/e1000.rst index 956560b6e745..f146201f66a2 100644 --- a/Documentation/networking/device_drivers/intel/e1000.rst +++ b/Documentation/networking/device_drivers/intel/e1000.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -=========================================================== -Linux* Base Driver for Intel(R) Ethernet Network Connection -=========================================================== +========================================================== +Linux Base Driver for Intel(R) Ethernet Network Connection +========================================================== Intel Gigabit Linux driver. Copyright(c) 1999 - 2013 Intel Corporation. @@ -438,10 +438,10 @@ ethtool The latest release of ethtool can be found from https://www.kernel.org/pub/software/network/ethtool/ -Enabling Wake on LAN* (WoL) ---------------------------- +Enabling Wake on LAN (WoL) +-------------------------- - WoL is configured through the ethtool* utility. + WoL is configured through the ethtool utility. WoL will be enabled on the system during the next shut down or reboot. For this driver version, in order to enable WoL, the e1000 driver must be diff --git a/Documentation/networking/device_drivers/intel/e1000e.rst b/Documentation/networking/device_drivers/intel/e1000e.rst index 01999f05509c..c3205d43be56 100644 --- a/Documentation/networking/device_drivers/intel/e1000e.rst +++ b/Documentation/networking/device_drivers/intel/e1000e.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -====================================================== -Linux* Driver for Intel(R) Ethernet Network Connection -====================================================== +===================================================== +Linux Driver for Intel(R) Ethernet Network Connection +===================================================== Intel Gigabit Linux driver. Copyright(c) 2008-2018 Intel Corporation. @@ -338,7 +338,7 @@ and higher cannot be forced. Use the autonegotiation advertising setting to manually set devices for 1 Gbps and higher. Speed, duplex, and autonegotiation advertising are configured through the -ethtool* utility. +ethtool utility. Caution: Only experienced network administrators should force speed and duplex or change autonegotiation advertising manually. The settings at the switch must @@ -351,9 +351,9 @@ will not attempt to auto-negotiate with its link partner since those adapters operate only in full duplex and only at their native speed. -Enabling Wake on LAN* (WoL) ---------------------------- -WoL is configured through the ethtool* utility. +Enabling Wake on LAN (WoL) +-------------------------- +WoL is configured through the ethtool utility. WoL will be enabled on the system during the next shut down or reboot. For this driver version, in order to enable WoL, the e1000e driver must be loaded diff --git a/Documentation/networking/device_drivers/intel/fm10k.rst b/Documentation/networking/device_drivers/intel/fm10k.rst index ac3269e34f55..d165ac5c1403 100644 --- a/Documentation/networking/device_drivers/intel/fm10k.rst +++ b/Documentation/networking/device_drivers/intel/fm10k.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -============================================================== -Linux* Base Driver for Intel(R) Ethernet Multi-host Controller -============================================================== +============================================================= +Linux Base Driver for Intel(R) Ethernet Multi-host Controller +============================================================= August 20, 2018 Copyright(c) 2015-2018 Intel Corporation. @@ -120,8 +120,8 @@ rx-flow-hash tcp4|udp4|ah4|esp4|sctp4|tcp6|udp6|ah6|esp6|sctp6 m|v|t|s|d|f|n|r Known Issues/Troubleshooting ============================ -Enabling SR-IOV in a 64-bit Microsoft* Windows Server* 2012/R2 guest OS under Linux KVM ---------------------------------------------------------------------------------------- +Enabling SR-IOV in a 64-bit Microsoft Windows Server 2012/R2 guest OS under Linux KVM +------------------------------------------------------------------------------------- KVM Hypervisor/VMM supports direct assignment of a PCIe device to a VM. This includes traditional PCIe devices, as well as SR-IOV-capable devices based on the Intel Ethernet Controller XL710. diff --git a/Documentation/networking/device_drivers/intel/i40e.rst b/Documentation/networking/device_drivers/intel/i40e.rst index 848fd388fa6e..3331d8960cca 100644 --- a/Documentation/networking/device_drivers/intel/i40e.rst +++ b/Documentation/networking/device_drivers/intel/i40e.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -================================================================== -Linux* Base Driver for the Intel(R) Ethernet Controller 700 Series -================================================================== +================================================================= +Linux Base Driver for the Intel(R) Ethernet Controller 700 Series +================================================================= Intel 40 Gigabit Linux driver. Copyright(c) 1999-2018 Intel Corporation. @@ -384,7 +384,7 @@ NOTE: You cannot set the speed for devices based on the Intel(R) Ethernet Network Adapter XXV710 based devices. Speed, duplex, and autonegotiation advertising are configured through the -ethtool* utility. +ethtool utility. Caution: Only experienced network administrators should force speed and duplex or change autonegotiation advertising manually. The settings at the switch must diff --git a/Documentation/networking/device_drivers/intel/iavf.rst b/Documentation/networking/device_drivers/intel/iavf.rst index cfc08842e32c..f963598cce61 100644 --- a/Documentation/networking/device_drivers/intel/iavf.rst +++ b/Documentation/networking/device_drivers/intel/iavf.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -================================================================== -Linux* Base Driver for Intel(R) Ethernet Adaptive Virtual Function -================================================================== +================================================================= +Linux Base Driver for Intel(R) Ethernet Adaptive Virtual Function +================================================================= Intel Ethernet Adaptive Virtual Function Linux driver. Copyright(c) 2013-2018 Intel Corporation. @@ -19,7 +19,7 @@ Contents Overview ======== -This file describes the iavf Linux* Base Driver. This driver was formerly +This file describes the iavf Linux Base Driver. This driver was formerly called i40evf. The iavf driver supports the below mentioned virtual function devices and diff --git a/Documentation/networking/device_drivers/intel/ice.rst b/Documentation/networking/device_drivers/intel/ice.rst index c220aa2711c6..1b866d4d497a 100644 --- a/Documentation/networking/device_drivers/intel/ice.rst +++ b/Documentation/networking/device_drivers/intel/ice.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -=================================================================== -Linux* Base Driver for the Intel(R) Ethernet Connection E800 Series -=================================================================== +================================================================== +Linux Base Driver for the Intel(R) Ethernet Connection E800 Series +================================================================== Intel ice Linux driver. Copyright(c) 2018 Intel Corporation. diff --git a/Documentation/networking/device_drivers/intel/igb.rst b/Documentation/networking/device_drivers/intel/igb.rst index fc8cfaa5dcfa..fe914a0384b5 100644 --- a/Documentation/networking/device_drivers/intel/igb.rst +++ b/Documentation/networking/device_drivers/intel/igb.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -=========================================================== -Linux* Base Driver for Intel(R) Ethernet Network Connection -=========================================================== +========================================================== +Linux Base Driver for Intel(R) Ethernet Network Connection +========================================================== Intel Gigabit Linux driver. Copyright(c) 1999-2018 Intel Corporation. @@ -129,9 +129,9 @@ version is required for this functionality. Download it at: https://www.kernel.org/pub/software/network/ethtool/ -Enabling Wake on LAN* (WoL) ---------------------------- -WoL is configured through the ethtool* utility. +Enabling Wake on LAN (WoL) +-------------------------- +WoL is configured through the ethtool utility. WoL will be enabled on the system during the next shut down or reboot. For this driver version, in order to enable WoL, the igb driver must be loaded diff --git a/Documentation/networking/device_drivers/intel/igbvf.rst b/Documentation/networking/device_drivers/intel/igbvf.rst index 9cddabe8108e..3aae181be091 100644 --- a/Documentation/networking/device_drivers/intel/igbvf.rst +++ b/Documentation/networking/device_drivers/intel/igbvf.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -============================================================ -Linux* Base Virtual Function Driver for Intel(R) 1G Ethernet -============================================================ +=========================================================== +Linux Base Virtual Function Driver for Intel(R) 1G Ethernet +=========================================================== Intel Gigabit Virtual Function Linux driver. Copyright(c) 1999-2018 Intel Corporation. diff --git a/Documentation/networking/device_drivers/intel/ixgbe.rst b/Documentation/networking/device_drivers/intel/ixgbe.rst index c7d25483fedb..4e5a35a4f241 100644 --- a/Documentation/networking/device_drivers/intel/ixgbe.rst +++ b/Documentation/networking/device_drivers/intel/ixgbe.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -============================================================================= -Linux* Base Driver for the Intel(R) Ethernet 10 Gigabit PCI Express Adapters -============================================================================= +=========================================================================== +Linux Base Driver for the Intel(R) Ethernet 10 Gigabit PCI Express Adapters +=========================================================================== Intel 10 Gigabit Linux driver. Copyright(c) 1999-2018 Intel Corporation. @@ -519,8 +519,8 @@ The offload is also supported for ixgbe's VFs, but the VF must be set as Known Issues/Troubleshooting ============================ -Enabling SR-IOV in a 64-bit Microsoft* Windows Server* 2012/R2 guest OS ------------------------------------------------------------------------ +Enabling SR-IOV in a 64-bit Microsoft Windows Server 2012/R2 guest OS +--------------------------------------------------------------------- Linux KVM Hypervisor/VMM supports direct assignment of a PCIe device to a VM. This includes traditional PCIe devices, as well as SR-IOV-capable devices based on the Intel Ethernet Controller XL710. diff --git a/Documentation/networking/device_drivers/intel/ixgbevf.rst b/Documentation/networking/device_drivers/intel/ixgbevf.rst index 5d4977360157..69b3c2c9935c 100644 --- a/Documentation/networking/device_drivers/intel/ixgbevf.rst +++ b/Documentation/networking/device_drivers/intel/ixgbevf.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -============================================================= -Linux* Base Virtual Function Driver for Intel(R) 10G Ethernet -============================================================= +============================================================ +Linux Base Virtual Function Driver for Intel(R) 10G Ethernet +============================================================ Intel 10 Gigabit Virtual Function Linux driver. Copyright(c) 1999-2018 Intel Corporation. diff --git a/Documentation/networking/device_drivers/pensando/ionic.rst b/Documentation/networking/device_drivers/pensando/ionic.rst index 67b6839d516b..fcfb62dcd4af 100644 --- a/Documentation/networking/device_drivers/pensando/ionic.rst +++ b/Documentation/networking/device_drivers/pensando/ionic.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -========================================================== -Linux* Driver for the Pensando(R) Ethernet adapter family -========================================================== +======================================================== +Linux Driver for the Pensando(R) Ethernet adapter family +======================================================== Pensando Linux Ethernet driver. Copyright(c) 2019 Pensando Systems, Inc -- cgit From ff8fdb36ac35ee90388fb3f5fdac679b25765841 Mon Sep 17 00:00:00 2001 From: Jeremy MAURO Date: Wed, 2 Oct 2019 15:33:39 +0200 Subject: scripts/sphinx-pre-install: allow checking for multiple missing files The current implementation take a simple file as first argument, this change allows to take a list as a first argument. Some file could have a different path according distribution version Signed-off-by: Jeremy MAURO Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 013099cd120d..646b97790e1a 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -124,11 +124,13 @@ sub add_package($$) sub check_missing_file($$$) { - my $file = shift; + my $files = shift; my $package = shift; my $is_optional = shift; - return if(-e $file); + for (@$files) { + return if(-e $_); + } add_package($package, $is_optional); } @@ -343,10 +345,10 @@ sub give_debian_hints() ); if ($pdf) { - check_missing_file("/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf", + check_missing_file(["/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"], "fonts-dejavu", 2); - check_missing_file("/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc", + check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc"], "fonts-noto-cjk", 2); } @@ -413,7 +415,7 @@ sub give_redhat_hints() } if ($pdf) { - check_missing_file("/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc", + check_missing_file(["/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc"], "google-noto-sans-cjk-ttc-fonts", 2); } @@ -498,7 +500,7 @@ sub give_mageia_hints() $map{"latexmk"} = "texlive-collection-basic"; if ($pdf) { - check_missing_file("/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc", + check_missing_file(["/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc"], "google-noto-sans-cjk-ttc-fonts", 2); } @@ -528,7 +530,7 @@ sub give_arch_linux_hints() check_pacman_missing(\@archlinux_tex_pkgs, 2) if ($pdf); if ($pdf) { - check_missing_file("/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc", + check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc"], "noto-fonts-cjk", 2); } @@ -549,11 +551,11 @@ sub give_gentoo_hints() "rsvg-convert" => "gnome-base/librsvg", ); - check_missing_file("/usr/share/fonts/dejavu/DejaVuSans.ttf", + check_missing_file(["/usr/share/fonts/dejavu/DejaVuSans.ttf"], "media-fonts/dejavu", 2) if ($pdf); if ($pdf) { - check_missing_file("/usr/share/fonts/noto-cjk/NotoSansCJKsc-Regular.otf", + check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJKsc-Regular.otf"], "media-fonts/noto-cjk", 2); } -- cgit From 9692f2fdb163a4a5e79ddb9b7e0f15d30384c7c2 Mon Sep 17 00:00:00 2001 From: Jeremy MAURO Date: Wed, 2 Oct 2019 15:35:42 +0200 Subject: scripts/sphinx-pre-install: Add a new path for the debian package "fonts-noto-cjk" The latest debian version "bullseye/sid" has changed the path of the file "notoserifcjk-regular.ttc", with the previous change and this change we keep the backward compatibility and add the latest debian version Signed-off-by: Jeremy MAURO Reviewed-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 646b97790e1a..68385fa62ff4 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -348,7 +348,8 @@ sub give_debian_hints() check_missing_file(["/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"], "fonts-dejavu", 2); - check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc"], + check_missing_file(["/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc", + "/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc"], "fonts-noto-cjk", 2); } -- cgit From 185271a1fa0720110d26200b44cc36c02210604c Mon Sep 17 00:00:00 2001 From: Chester Lin Date: Mon, 16 Sep 2019 13:01:40 +0000 Subject: riscv-docs: correct the sequence of the magic number 2 since it's little endian Correct the sequence of the magic number 2 since it's little endian. Signed-off-by: Chester Lin Reviewed-by: Paul Walmsley Signed-off-by: Jonathan Corbet --- Documentation/riscv/boot-image-header.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/riscv/boot-image-header.rst b/Documentation/riscv/boot-image-header.rst index 7b4d1d747585..518d46d2389d 100644 --- a/Documentation/riscv/boot-image-header.rst +++ b/Documentation/riscv/boot-image-header.rst @@ -21,7 +21,7 @@ The following 64-byte header is present in decompressed Linux kernel image:: u32 res1 = 0; /* Reserved */ u64 res2 = 0; /* Reserved */ u64 magic = 0x5643534952; /* Magic number, little endian, "RISCV" */ - u32 magic2 = 0x56534905; /* Magic number 2, little endian, "RSC\x05" */ + u32 magic2 = 0x05435352; /* Magic number 2, little endian, "RSC\x05" */ u32 res4; /* Reserved for PE COFF offset */ This header format is compliant with PE/COFF header and largely inspired from -- cgit From 81584a6a771b971e1497d33f98019e6c0192e621 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 4 Oct 2019 10:47:46 -0600 Subject: docs: remove :c:func: from refcount-vs-atomic.rst As of 5.3, the automarkup extension will do the right thing with function() notation, so we don't need to clutter the text with :c:func: invocations. So remove them. Looking at the generated output reveals that we lack kerneldoc coverage for much of this API, but that's a separate problem. Acked-by: Paul E. McKenney Signed-off-by: Jonathan Corbet --- Documentation/core-api/refcount-vs-atomic.rst | 36 +++++++++++++-------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/Documentation/core-api/refcount-vs-atomic.rst b/Documentation/core-api/refcount-vs-atomic.rst index 976e85adffe8..79a009ce11df 100644 --- a/Documentation/core-api/refcount-vs-atomic.rst +++ b/Documentation/core-api/refcount-vs-atomic.rst @@ -35,7 +35,7 @@ atomics & refcounters only provide atomicity and program order (po) relation (on the same CPU). It guarantees that each ``atomic_*()`` and ``refcount_*()`` operation is atomic and instructions are executed in program order on a single CPU. -This is implemented using :c:func:`READ_ONCE`/:c:func:`WRITE_ONCE` and +This is implemented using READ_ONCE()/WRITE_ONCE() and compare-and-swap primitives. A strong (full) memory ordering guarantees that all prior loads and @@ -44,7 +44,7 @@ before any po-later instruction is executed on the same CPU. It also guarantees that all po-earlier stores on the same CPU and all propagated stores from other CPUs must propagate to all other CPUs before any po-later instruction is executed on the original -CPU (A-cumulative property). This is implemented using :c:func:`smp_mb`. +CPU (A-cumulative property). This is implemented using smp_mb(). A RELEASE memory ordering guarantees that all prior loads and stores (all po-earlier instructions) on the same CPU are completed @@ -52,14 +52,14 @@ before the operation. It also guarantees that all po-earlier stores on the same CPU and all propagated stores from other CPUs must propagate to all other CPUs before the release operation (A-cumulative property). This is implemented using -:c:func:`smp_store_release`. +smp_store_release(). An ACQUIRE memory ordering guarantees that all post loads and stores (all po-later instructions) on the same CPU are completed after the acquire operation. It also guarantees that all po-later stores on the same CPU must propagate to all other CPUs after the acquire operation executes. This is implemented using -:c:func:`smp_acquire__after_ctrl_dep`. +smp_acquire__after_ctrl_dep(). A control dependency (on success) for refcounters guarantees that if a reference for an object was successfully obtained (reference @@ -78,8 +78,8 @@ case 1) - non-"Read/Modify/Write" (RMW) ops Function changes: - * :c:func:`atomic_set` --> :c:func:`refcount_set` - * :c:func:`atomic_read` --> :c:func:`refcount_read` + * atomic_set() --> refcount_set() + * atomic_read() --> refcount_read() Memory ordering guarantee changes: @@ -91,8 +91,8 @@ case 2) - increment-based ops that return no value Function changes: - * :c:func:`atomic_inc` --> :c:func:`refcount_inc` - * :c:func:`atomic_add` --> :c:func:`refcount_add` + * atomic_inc() --> refcount_inc() + * atomic_add() --> refcount_add() Memory ordering guarantee changes: @@ -103,7 +103,7 @@ case 3) - decrement-based RMW ops that return no value Function changes: - * :c:func:`atomic_dec` --> :c:func:`refcount_dec` + * atomic_dec() --> refcount_dec() Memory ordering guarantee changes: @@ -115,8 +115,8 @@ case 4) - increment-based RMW ops that return a value Function changes: - * :c:func:`atomic_inc_not_zero` --> :c:func:`refcount_inc_not_zero` - * no atomic counterpart --> :c:func:`refcount_add_not_zero` + * atomic_inc_not_zero() --> refcount_inc_not_zero() + * no atomic counterpart --> refcount_add_not_zero() Memory ordering guarantees changes: @@ -131,8 +131,8 @@ case 5) - generic dec/sub decrement-based RMW ops that return a value Function changes: - * :c:func:`atomic_dec_and_test` --> :c:func:`refcount_dec_and_test` - * :c:func:`atomic_sub_and_test` --> :c:func:`refcount_sub_and_test` + * atomic_dec_and_test() --> refcount_dec_and_test() + * atomic_sub_and_test() --> refcount_sub_and_test() Memory ordering guarantees changes: @@ -144,14 +144,14 @@ case 6) other decrement-based RMW ops that return a value Function changes: - * no atomic counterpart --> :c:func:`refcount_dec_if_one` + * no atomic counterpart --> refcount_dec_if_one() * ``atomic_add_unless(&var, -1, 1)`` --> ``refcount_dec_not_one(&var)`` Memory ordering guarantees changes: * fully ordered --> RELEASE ordering + control dependency -.. note:: :c:func:`atomic_add_unless` only provides full order on success. +.. note:: atomic_add_unless() only provides full order on success. case 7) - lock-based RMW @@ -159,10 +159,10 @@ case 7) - lock-based RMW Function changes: - * :c:func:`atomic_dec_and_lock` --> :c:func:`refcount_dec_and_lock` - * :c:func:`atomic_dec_and_mutex_lock` --> :c:func:`refcount_dec_and_mutex_lock` + * atomic_dec_and_lock() --> refcount_dec_and_lock() + * atomic_dec_and_mutex_lock() --> refcount_dec_and_mutex_lock() Memory ordering guarantees changes: * fully ordered --> RELEASE ordering + control dependency + hold - :c:func:`spin_lock` on success + spin_lock() on success -- cgit From cc84ac35d9fa3131179ed0805ddbd28bc5f262d6 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 1 Oct 2019 08:47:47 -0600 Subject: docs: Catch up with the new location of get_user_pages_fast() Commit 050a9adc6438 ("mm: consolidate the get_user_pages* implementations") moved get_user_pages_fast() from mm/util.c to mm/gup.c, but didn't update the documentation, leading to this build warning: ./mm/util.c:1: warning: 'get_user_pages_fast' not found Update the docs to match the new reality. Fixes: 050a9adc6438 ("mm: consolidate the get_user_pages* implementations") Reviewed-by: Christoph Hellwig Signed-off-by: Jonathan Corbet --- Documentation/core-api/mm-api.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst index 128e8a721c1e..be726986ff75 100644 --- a/Documentation/core-api/mm-api.rst +++ b/Documentation/core-api/mm-api.rst @@ -11,7 +11,7 @@ User Space Memory Access .. kernel-doc:: arch/x86/lib/usercopy_32.c :export: -.. kernel-doc:: mm/util.c +.. kernel-doc:: mm/gup.c :functions: get_user_pages_fast .. _mm-api-gfp-flags: -- cgit From ea83df73aaa3bded80e441d05ca2873c37f84e0a Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 3 Oct 2019 12:40:30 -0600 Subject: genalloc: Fix a set of docs build warnings Commit 795ee30648c7 ("lib/genalloc: introduce chunk owners") made a number of changes to the genalloc API and implementation but did not update the documentation to match, leading to these docs build warnings: ./lib/genalloc.c:1: warning: 'gen_pool_add_virt' not found ./lib/genalloc.c:1: warning: 'gen_pool_alloc' not found ./lib/genalloc.c:1: warning: 'gen_pool_free' not found ./lib/genalloc.c:1: warning: 'gen_pool_alloc_algo' not found Fix these by updating the docs to match new function locations and names, and by completing the update of one kerneldoc comment. Fixes: 795ee30648c7 ("lib/genalloc: introduce chunk owners") Acked-by: Dan Williams Signed-off-by: Jonathan Corbet --- Documentation/core-api/genalloc.rst | 8 ++++---- lib/genalloc.c | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/core-api/genalloc.rst b/Documentation/core-api/genalloc.rst index 6b38a39fab24..2db2f79eb229 100644 --- a/Documentation/core-api/genalloc.rst +++ b/Documentation/core-api/genalloc.rst @@ -53,7 +53,7 @@ to the pool. That can be done with one of: :functions: gen_pool_add .. kernel-doc:: lib/genalloc.c - :functions: gen_pool_add_virt + :functions: gen_pool_add_owner A call to :c:func:`gen_pool_add` will place the size bytes of memory starting at addr (in the kernel's virtual address space) into the given @@ -65,14 +65,14 @@ for DMA allocations. The functions for allocating memory from the pool (and putting it back) are: -.. kernel-doc:: lib/genalloc.c +.. kernel-doc:: include/linux/genalloc.h :functions: gen_pool_alloc .. kernel-doc:: lib/genalloc.c :functions: gen_pool_dma_alloc .. kernel-doc:: lib/genalloc.c - :functions: gen_pool_free + :functions: gen_pool_free_owner As one would expect, :c:func:`gen_pool_alloc` will allocate size< bytes from the given pool. The :c:func:`gen_pool_dma_alloc` variant allocates @@ -89,7 +89,7 @@ return. If that sort of control is needed, the following functions will be of interest: .. kernel-doc:: lib/genalloc.c - :functions: gen_pool_alloc_algo + :functions: gen_pool_alloc_algo_owner .. kernel-doc:: lib/genalloc.c :functions: gen_pool_set_algo diff --git a/lib/genalloc.c b/lib/genalloc.c index 9fc31292cfa1..24d20ca7e91b 100644 --- a/lib/genalloc.c +++ b/lib/genalloc.c @@ -472,7 +472,7 @@ void *gen_pool_dma_zalloc_align(struct gen_pool *pool, size_t size, EXPORT_SYMBOL(gen_pool_dma_zalloc_align); /** - * gen_pool_free - free allocated special memory back to the pool + * gen_pool_free_owner - free allocated special memory back to the pool * @pool: pool to free to * @addr: starting address of memory to free back to pool * @size: size in bytes of memory to free -- cgit From f704985b1e7ea0f9fde1cfb1354d57593ba62fcb Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 1 Oct 2019 11:42:07 -0600 Subject: docs/driver-api: Catch up with dma_buf file-name changes drivers/dma_buf/reservation.c was renamed to dma-resv.c (and include/linux/reservation.h to dma-resv.h), but the documentation was not updated to match, leading to these build errors: Error: Cannot open file ./drivers/dma-buf/reservation.c Error: Cannot open file ./drivers/dma-buf/reservation.c Error: Cannot open file ./drivers/dma-buf/reservation.c Error: Cannot open file ./include/linux/reservation.h Error: Cannot open file ./include/linux/reservation.h Update the documentation and make the world happy again. Fixes: 52791eeec1d9 ("dma-buf: rename reservation_object to dma_resv') Signed-off-by: Jonathan Corbet --- Documentation/driver-api/dma-buf.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index b541e97c7ab1..c78db28519f7 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -118,13 +118,13 @@ Kernel Functions and Structures Reference Reservation Objects ------------------- -.. kernel-doc:: drivers/dma-buf/reservation.c +.. kernel-doc:: drivers/dma-buf/dma-resv.c :doc: Reservation Object Overview -.. kernel-doc:: drivers/dma-buf/reservation.c +.. kernel-doc:: drivers/dma-buf/dma-resv.c :export: -.. kernel-doc:: include/linux/reservation.h +.. kernel-doc:: include/linux/dma-resv.h :internal: DMA Fences -- cgit From 61d221b735e80819814dbff3f014b27a457d297b Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 7 Oct 2019 09:38:58 -0600 Subject: docs: Fix "make help" suggestion for SPHINXDIR Commit 9fc3a18a942f ("docs: remove extra conf.py files") broke the setting of _SPHINXDIRS in Documentation/Makefile. Let's just have it look for an index.rst file instead. Fixes: 9fc3a18a942f ("docs: remove extra conf.py files") Reported-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Jonathan Corbet --- Documentation/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/Makefile b/Documentation/Makefile index c6e564656a5b..ce8eb63b523a 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -13,7 +13,7 @@ endif SPHINXBUILD = sphinx-build SPHINXOPTS = SPHINXDIRS = . -_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/conf.py,%,$(wildcard $(srctree)/Documentation/*/conf.py)) +_SPHINXDIRS = $(patsubst $(srctree)/Documentation/%/index.rst,%,$(wildcard $(srctree)/Documentation/*/index.rst)) SPHINX_CONF = conf.py PAPER = BUILDDIR = $(obj)/output -- cgit From 5ecd0a06e6bb992c903f5d8a588b78852b9e80a5 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 3 Oct 2019 12:58:42 -0600 Subject: docs: move botching-up-ioctls.rst to the process guide This is overall information for kernel developers, and not part of the user-space API. Cc: Daniel Vetter Signed-off-by: Jonathan Corbet --- Documentation/ioctl/botching-up-ioctls.rst | 225 --------------------------- Documentation/ioctl/index.rst | 1 - Documentation/process/botching-up-ioctls.rst | 225 +++++++++++++++++++++++++++ Documentation/process/index.rst | 1 + 4 files changed, 226 insertions(+), 226 deletions(-) delete mode 100644 Documentation/ioctl/botching-up-ioctls.rst create mode 100644 Documentation/process/botching-up-ioctls.rst diff --git a/Documentation/ioctl/botching-up-ioctls.rst b/Documentation/ioctl/botching-up-ioctls.rst deleted file mode 100644 index ac697fef3545..000000000000 --- a/Documentation/ioctl/botching-up-ioctls.rst +++ /dev/null @@ -1,225 +0,0 @@ -================================= -(How to avoid) Botching up ioctls -================================= - -From: http://blog.ffwll.ch/2013/11/botching-up-ioctls.html - -By: Daniel Vetter, Copyright © 2013 Intel Corporation - -One clear insight kernel graphics hackers gained in the past few years is that -trying to come up with a unified interface to manage the execution units and -memory on completely different GPUs is a futile effort. So nowadays every -driver has its own set of ioctls to allocate memory and submit work to the GPU. -Which is nice, since there's no more insanity in the form of fake-generic, but -actually only used once interfaces. But the clear downside is that there's much -more potential to screw things up. - -To avoid repeating all the same mistakes again I've written up some of the -lessons learned while botching the job for the drm/i915 driver. Most of these -only cover technicalities and not the big-picture issues like what the command -submission ioctl exactly should look like. Learning these lessons is probably -something every GPU driver has to do on its own. - - -Prerequisites -------------- - -First the prerequisites. Without these you have already failed, because you -will need to add a 32-bit compat layer: - - * Only use fixed sized integers. To avoid conflicts with typedefs in userspace - the kernel has special types like __u32, __s64. Use them. - - * Align everything to the natural size and use explicit padding. 32-bit - platforms don't necessarily align 64-bit values to 64-bit boundaries, but - 64-bit platforms do. So we always need padding to the natural size to get - this right. - - * Pad the entire struct to a multiple of 64-bits if the structure contains - 64-bit types - the structure size will otherwise differ on 32-bit versus - 64-bit. Having a different structure size hurts when passing arrays of - structures to the kernel, or if the kernel checks the structure size, which - e.g. the drm core does. - - * Pointers are __u64, cast from/to a uintprt_t on the userspace side and - from/to a void __user * in the kernel. Try really hard not to delay this - conversion or worse, fiddle the raw __u64 through your code since that - diminishes the checking tools like sparse can provide. The macro - u64_to_user_ptr can be used in the kernel to avoid warnings about integers - and pointres of different sizes. - - -Basics ------- - -With the joys of writing a compat layer avoided we can take a look at the basic -fumbles. Neglecting these will make backward and forward compatibility a real -pain. And since getting things wrong on the first attempt is guaranteed you -will have a second iteration or at least an extension for any given interface. - - * Have a clear way for userspace to figure out whether your new ioctl or ioctl - extension is supported on a given kernel. If you can't rely on old kernels - rejecting the new flags/modes or ioctls (since doing that was botched in the - past) then you need a driver feature flag or revision number somewhere. - - * Have a plan for extending ioctls with new flags or new fields at the end of - the structure. The drm core checks the passed-in size for each ioctl call - and zero-extends any mismatches between kernel and userspace. That helps, - but isn't a complete solution since newer userspace on older kernels won't - notice that the newly added fields at the end get ignored. So this still - needs a new driver feature flags. - - * Check all unused fields and flags and all the padding for whether it's 0, - and reject the ioctl if that's not the case. Otherwise your nice plan for - future extensions is going right down the gutters since someone will submit - an ioctl struct with random stack garbage in the yet unused parts. Which - then bakes in the ABI that those fields can never be used for anything else - but garbage. This is also the reason why you must explicitly pad all - structures, even if you never use them in an array - the padding the compiler - might insert could contain garbage. - - * Have simple testcases for all of the above. - - -Fun with Error Paths --------------------- - -Nowadays we don't have any excuse left any more for drm drivers being neat -little root exploits. This means we both need full input validation and solid -error handling paths - GPUs will die eventually in the oddmost corner cases -anyway: - - * The ioctl must check for array overflows. Also it needs to check for - over/underflows and clamping issues of integer values in general. The usual - example is sprite positioning values fed directly into the hardware with the - hardware just having 12 bits or so. Works nicely until some odd display - server doesn't bother with clamping itself and the cursor wraps around the - screen. - - * Have simple testcases for every input validation failure case in your ioctl. - Check that the error code matches your expectations. And finally make sure - that you only test for one single error path in each subtest by submitting - otherwise perfectly valid data. Without this an earlier check might reject - the ioctl already and shadow the codepath you actually want to test, hiding - bugs and regressions. - - * Make all your ioctls restartable. First X really loves signals and second - this will allow you to test 90% of all error handling paths by just - interrupting your main test suite constantly with signals. Thanks to X's - love for signal you'll get an excellent base coverage of all your error - paths pretty much for free for graphics drivers. Also, be consistent with - how you handle ioctl restarting - e.g. drm has a tiny drmIoctl helper in its - userspace library. The i915 driver botched this with the set_tiling ioctl, - now we're stuck forever with some arcane semantics in both the kernel and - userspace. - - * If you can't make a given codepath restartable make a stuck task at least - killable. GPUs just die and your users won't like you more if you hang their - entire box (by means of an unkillable X process). If the state recovery is - still too tricky have a timeout or hangcheck safety net as a last-ditch - effort in case the hardware has gone bananas. - - * Have testcases for the really tricky corner cases in your error recovery code - - it's way too easy to create a deadlock between your hangcheck code and - waiters. - - -Time, Waiting and Missing it ----------------------------- - -GPUs do most everything asynchronously, so we have a need to time operations and -wait for outstanding ones. This is really tricky business; at the moment none of -the ioctls supported by the drm/i915 get this fully right, which means there's -still tons more lessons to learn here. - - * Use CLOCK_MONOTONIC as your reference time, always. It's what alsa, drm and - v4l use by default nowadays. But let userspace know which timestamps are - derived from different clock domains like your main system clock (provided - by the kernel) or some independent hardware counter somewhere else. Clocks - will mismatch if you look close enough, but if performance measuring tools - have this information they can at least compensate. If your userspace can - get at the raw values of some clocks (e.g. through in-command-stream - performance counter sampling instructions) consider exposing those also. - - * Use __s64 seconds plus __u64 nanoseconds to specify time. It's not the most - convenient time specification, but it's mostly the standard. - - * Check that input time values are normalized and reject them if not. Note - that the kernel native struct ktime has a signed integer for both seconds - and nanoseconds, so beware here. - - * For timeouts, use absolute times. If you're a good fellow and made your - ioctl restartable relative timeouts tend to be too coarse and can - indefinitely extend your wait time due to rounding on each restart. - Especially if your reference clock is something really slow like the display - frame counter. With a spec lawyer hat on this isn't a bug since timeouts can - always be extended - but users will surely hate you if their neat animations - starts to stutter due to this. - - * Consider ditching any synchronous wait ioctls with timeouts and just deliver - an asynchronous event on a pollable file descriptor. It fits much better - into event driven applications' main loop. - - * Have testcases for corner-cases, especially whether the return values for - already-completed events, successful waits and timed-out waits are all sane - and suiting to your needs. - - -Leaking Resources, Not ----------------------- - -A full-blown drm driver essentially implements a little OS, but specialized to -the given GPU platforms. This means a driver needs to expose tons of handles -for different objects and other resources to userspace. Doing that right -entails its own little set of pitfalls: - - * Always attach the lifetime of your dynamically created resources to the - lifetime of a file descriptor. Consider using a 1:1 mapping if your resource - needs to be shared across processes - fd-passing over unix domain sockets - also simplifies lifetime management for userspace. - - * Always have O_CLOEXEC support. - - * Ensure that you have sufficient insulation between different clients. By - default pick a private per-fd namespace which forces any sharing to be done - explicitly. Only go with a more global per-device namespace if the objects - are truly device-unique. One counterexample in the drm modeset interfaces is - that the per-device modeset objects like connectors share a namespace with - framebuffer objects, which mostly are not shared at all. A separate - namespace, private by default, for framebuffers would have been more - suitable. - - * Think about uniqueness requirements for userspace handles. E.g. for most drm - drivers it's a userspace bug to submit the same object twice in the same - command submission ioctl. But then if objects are shareable userspace needs - to know whether it has seen an imported object from a different process - already or not. I haven't tried this myself yet due to lack of a new class - of objects, but consider using inode numbers on your shared file descriptors - as unique identifiers - it's how real files are told apart, too. - Unfortunately this requires a full-blown virtual filesystem in the kernel. - - -Last, but not Least -------------------- - -Not every problem needs a new ioctl: - - * Think hard whether you really want a driver-private interface. Of course - it's much quicker to push a driver-private interface than engaging in - lengthy discussions for a more generic solution. And occasionally doing a - private interface to spearhead a new concept is what's required. But in the - end, once the generic interface comes around you'll end up maintainer two - interfaces. Indefinitely. - - * Consider other interfaces than ioctls. A sysfs attribute is much better for - per-device settings, or for child objects with fairly static lifetimes (like - output connectors in drm with all the detection override attributes). Or - maybe only your testsuite needs this interface, and then debugfs with its - disclaimer of not having a stable ABI would be better. - -Finally, the name of the game is to get it right on the first attempt, since if -your driver proves popular and your hardware platforms long-lived then you'll -be stuck with a given ioctl essentially forever. You can try to deprecate -horrible ioctls on newer iterations of your hardware, but generally it takes -years to accomplish this. And then again years until the last user able to -complain about regressions disappears, too. diff --git a/Documentation/ioctl/index.rst b/Documentation/ioctl/index.rst index 0f0a857f6615..475675eae086 100644 --- a/Documentation/ioctl/index.rst +++ b/Documentation/ioctl/index.rst @@ -9,7 +9,6 @@ IOCTLs ioctl-number - botching-up-ioctls ioctl-decoding cdrom diff --git a/Documentation/process/botching-up-ioctls.rst b/Documentation/process/botching-up-ioctls.rst new file mode 100644 index 000000000000..ac697fef3545 --- /dev/null +++ b/Documentation/process/botching-up-ioctls.rst @@ -0,0 +1,225 @@ +================================= +(How to avoid) Botching up ioctls +================================= + +From: http://blog.ffwll.ch/2013/11/botching-up-ioctls.html + +By: Daniel Vetter, Copyright © 2013 Intel Corporation + +One clear insight kernel graphics hackers gained in the past few years is that +trying to come up with a unified interface to manage the execution units and +memory on completely different GPUs is a futile effort. So nowadays every +driver has its own set of ioctls to allocate memory and submit work to the GPU. +Which is nice, since there's no more insanity in the form of fake-generic, but +actually only used once interfaces. But the clear downside is that there's much +more potential to screw things up. + +To avoid repeating all the same mistakes again I've written up some of the +lessons learned while botching the job for the drm/i915 driver. Most of these +only cover technicalities and not the big-picture issues like what the command +submission ioctl exactly should look like. Learning these lessons is probably +something every GPU driver has to do on its own. + + +Prerequisites +------------- + +First the prerequisites. Without these you have already failed, because you +will need to add a 32-bit compat layer: + + * Only use fixed sized integers. To avoid conflicts with typedefs in userspace + the kernel has special types like __u32, __s64. Use them. + + * Align everything to the natural size and use explicit padding. 32-bit + platforms don't necessarily align 64-bit values to 64-bit boundaries, but + 64-bit platforms do. So we always need padding to the natural size to get + this right. + + * Pad the entire struct to a multiple of 64-bits if the structure contains + 64-bit types - the structure size will otherwise differ on 32-bit versus + 64-bit. Having a different structure size hurts when passing arrays of + structures to the kernel, or if the kernel checks the structure size, which + e.g. the drm core does. + + * Pointers are __u64, cast from/to a uintprt_t on the userspace side and + from/to a void __user * in the kernel. Try really hard not to delay this + conversion or worse, fiddle the raw __u64 through your code since that + diminishes the checking tools like sparse can provide. The macro + u64_to_user_ptr can be used in the kernel to avoid warnings about integers + and pointres of different sizes. + + +Basics +------ + +With the joys of writing a compat layer avoided we can take a look at the basic +fumbles. Neglecting these will make backward and forward compatibility a real +pain. And since getting things wrong on the first attempt is guaranteed you +will have a second iteration or at least an extension for any given interface. + + * Have a clear way for userspace to figure out whether your new ioctl or ioctl + extension is supported on a given kernel. If you can't rely on old kernels + rejecting the new flags/modes or ioctls (since doing that was botched in the + past) then you need a driver feature flag or revision number somewhere. + + * Have a plan for extending ioctls with new flags or new fields at the end of + the structure. The drm core checks the passed-in size for each ioctl call + and zero-extends any mismatches between kernel and userspace. That helps, + but isn't a complete solution since newer userspace on older kernels won't + notice that the newly added fields at the end get ignored. So this still + needs a new driver feature flags. + + * Check all unused fields and flags and all the padding for whether it's 0, + and reject the ioctl if that's not the case. Otherwise your nice plan for + future extensions is going right down the gutters since someone will submit + an ioctl struct with random stack garbage in the yet unused parts. Which + then bakes in the ABI that those fields can never be used for anything else + but garbage. This is also the reason why you must explicitly pad all + structures, even if you never use them in an array - the padding the compiler + might insert could contain garbage. + + * Have simple testcases for all of the above. + + +Fun with Error Paths +-------------------- + +Nowadays we don't have any excuse left any more for drm drivers being neat +little root exploits. This means we both need full input validation and solid +error handling paths - GPUs will die eventually in the oddmost corner cases +anyway: + + * The ioctl must check for array overflows. Also it needs to check for + over/underflows and clamping issues of integer values in general. The usual + example is sprite positioning values fed directly into the hardware with the + hardware just having 12 bits or so. Works nicely until some odd display + server doesn't bother with clamping itself and the cursor wraps around the + screen. + + * Have simple testcases for every input validation failure case in your ioctl. + Check that the error code matches your expectations. And finally make sure + that you only test for one single error path in each subtest by submitting + otherwise perfectly valid data. Without this an earlier check might reject + the ioctl already and shadow the codepath you actually want to test, hiding + bugs and regressions. + + * Make all your ioctls restartable. First X really loves signals and second + this will allow you to test 90% of all error handling paths by just + interrupting your main test suite constantly with signals. Thanks to X's + love for signal you'll get an excellent base coverage of all your error + paths pretty much for free for graphics drivers. Also, be consistent with + how you handle ioctl restarting - e.g. drm has a tiny drmIoctl helper in its + userspace library. The i915 driver botched this with the set_tiling ioctl, + now we're stuck forever with some arcane semantics in both the kernel and + userspace. + + * If you can't make a given codepath restartable make a stuck task at least + killable. GPUs just die and your users won't like you more if you hang their + entire box (by means of an unkillable X process). If the state recovery is + still too tricky have a timeout or hangcheck safety net as a last-ditch + effort in case the hardware has gone bananas. + + * Have testcases for the really tricky corner cases in your error recovery code + - it's way too easy to create a deadlock between your hangcheck code and + waiters. + + +Time, Waiting and Missing it +---------------------------- + +GPUs do most everything asynchronously, so we have a need to time operations and +wait for outstanding ones. This is really tricky business; at the moment none of +the ioctls supported by the drm/i915 get this fully right, which means there's +still tons more lessons to learn here. + + * Use CLOCK_MONOTONIC as your reference time, always. It's what alsa, drm and + v4l use by default nowadays. But let userspace know which timestamps are + derived from different clock domains like your main system clock (provided + by the kernel) or some independent hardware counter somewhere else. Clocks + will mismatch if you look close enough, but if performance measuring tools + have this information they can at least compensate. If your userspace can + get at the raw values of some clocks (e.g. through in-command-stream + performance counter sampling instructions) consider exposing those also. + + * Use __s64 seconds plus __u64 nanoseconds to specify time. It's not the most + convenient time specification, but it's mostly the standard. + + * Check that input time values are normalized and reject them if not. Note + that the kernel native struct ktime has a signed integer for both seconds + and nanoseconds, so beware here. + + * For timeouts, use absolute times. If you're a good fellow and made your + ioctl restartable relative timeouts tend to be too coarse and can + indefinitely extend your wait time due to rounding on each restart. + Especially if your reference clock is something really slow like the display + frame counter. With a spec lawyer hat on this isn't a bug since timeouts can + always be extended - but users will surely hate you if their neat animations + starts to stutter due to this. + + * Consider ditching any synchronous wait ioctls with timeouts and just deliver + an asynchronous event on a pollable file descriptor. It fits much better + into event driven applications' main loop. + + * Have testcases for corner-cases, especially whether the return values for + already-completed events, successful waits and timed-out waits are all sane + and suiting to your needs. + + +Leaking Resources, Not +---------------------- + +A full-blown drm driver essentially implements a little OS, but specialized to +the given GPU platforms. This means a driver needs to expose tons of handles +for different objects and other resources to userspace. Doing that right +entails its own little set of pitfalls: + + * Always attach the lifetime of your dynamically created resources to the + lifetime of a file descriptor. Consider using a 1:1 mapping if your resource + needs to be shared across processes - fd-passing over unix domain sockets + also simplifies lifetime management for userspace. + + * Always have O_CLOEXEC support. + + * Ensure that you have sufficient insulation between different clients. By + default pick a private per-fd namespace which forces any sharing to be done + explicitly. Only go with a more global per-device namespace if the objects + are truly device-unique. One counterexample in the drm modeset interfaces is + that the per-device modeset objects like connectors share a namespace with + framebuffer objects, which mostly are not shared at all. A separate + namespace, private by default, for framebuffers would have been more + suitable. + + * Think about uniqueness requirements for userspace handles. E.g. for most drm + drivers it's a userspace bug to submit the same object twice in the same + command submission ioctl. But then if objects are shareable userspace needs + to know whether it has seen an imported object from a different process + already or not. I haven't tried this myself yet due to lack of a new class + of objects, but consider using inode numbers on your shared file descriptors + as unique identifiers - it's how real files are told apart, too. + Unfortunately this requires a full-blown virtual filesystem in the kernel. + + +Last, but not Least +------------------- + +Not every problem needs a new ioctl: + + * Think hard whether you really want a driver-private interface. Of course + it's much quicker to push a driver-private interface than engaging in + lengthy discussions for a more generic solution. And occasionally doing a + private interface to spearhead a new concept is what's required. But in the + end, once the generic interface comes around you'll end up maintainer two + interfaces. Indefinitely. + + * Consider other interfaces than ioctls. A sysfs attribute is much better for + per-device settings, or for child objects with fairly static lifetimes (like + output connectors in drm with all the detection override attributes). Or + maybe only your testsuite needs this interface, and then debugfs with its + disclaimer of not having a stable ABI would be better. + +Finally, the name of the game is to get it right on the first attempt, since if +your driver proves popular and your hardware platforms long-lived then you'll +be stuck with a given ioctl essentially forever. You can try to deprecate +horrible ioctls on newer iterations of your hardware, but generally it takes +years to accomplish this. And then again years until the last user able to +complain about regressions disappears, too. diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst index e2fb0c9652ac..21aa7d5358e6 100644 --- a/Documentation/process/index.rst +++ b/Documentation/process/index.rst @@ -58,6 +58,7 @@ lack of a better place. adding-syscalls magic-number volatile-considered-harmful + botching-up-ioctls clang-format .. only:: subproject and html -- cgit From 049500715e7aed436c3dfac7071d7f17c18b463b Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Thu, 3 Oct 2019 13:02:19 -0600 Subject: docs: Move the user-space ioctl() docs to userspace-api This is strictly user-space material at this point, so put it with the other user-space API documentation. Signed-off-by: Jonathan Corbet --- Documentation/index.rst | 1 - Documentation/ioctl/cdrom.rst | 1233 ------------------ Documentation/ioctl/hdio.rst | 1342 -------------------- Documentation/ioctl/index.rst | 15 - Documentation/ioctl/ioctl-decoding.rst | 31 - Documentation/ioctl/ioctl-number.rst | 362 ------ Documentation/userspace-api/index.rst | 1 + Documentation/userspace-api/ioctl/cdrom.rst | 1233 ++++++++++++++++++ Documentation/userspace-api/ioctl/hdio.rst | 1342 ++++++++++++++++++++ Documentation/userspace-api/ioctl/index.rst | 15 + .../userspace-api/ioctl/ioctl-decoding.rst | 31 + Documentation/userspace-api/ioctl/ioctl-number.rst | 362 ++++++ 12 files changed, 2984 insertions(+), 2984 deletions(-) delete mode 100644 Documentation/ioctl/cdrom.rst delete mode 100644 Documentation/ioctl/hdio.rst delete mode 100644 Documentation/ioctl/index.rst delete mode 100644 Documentation/ioctl/ioctl-decoding.rst delete mode 100644 Documentation/ioctl/ioctl-number.rst create mode 100644 Documentation/userspace-api/ioctl/cdrom.rst create mode 100644 Documentation/userspace-api/ioctl/hdio.rst create mode 100644 Documentation/userspace-api/ioctl/index.rst create mode 100644 Documentation/userspace-api/ioctl/ioctl-decoding.rst create mode 100644 Documentation/userspace-api/ioctl/ioctl-number.rst diff --git a/Documentation/index.rst b/Documentation/index.rst index b843e313d2f2..dbf0951a0abe 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -57,7 +57,6 @@ the kernel interface as seen by application developers. :maxdepth: 2 userspace-api/index - ioctl/index Introduction to kernel development diff --git a/Documentation/ioctl/cdrom.rst b/Documentation/ioctl/cdrom.rst deleted file mode 100644 index 3b4c0506de46..000000000000 --- a/Documentation/ioctl/cdrom.rst +++ /dev/null @@ -1,1233 +0,0 @@ -============================ -Summary of CDROM ioctl calls -============================ - -- Edward A. Falk - -November, 2004 - -This document attempts to describe the ioctl(2) calls supported by -the CDROM layer. These are by-and-large implemented (as of Linux 2.6) -in drivers/cdrom/cdrom.c and drivers/block/scsi_ioctl.c - -ioctl values are listed in . As of this writing, they -are as follows: - - ====================== =============================================== - CDROMPAUSE Pause Audio Operation - CDROMRESUME Resume paused Audio Operation - CDROMPLAYMSF Play Audio MSF (struct cdrom_msf) - CDROMPLAYTRKIND Play Audio Track/index (struct cdrom_ti) - CDROMREADTOCHDR Read TOC header (struct cdrom_tochdr) - CDROMREADTOCENTRY Read TOC entry (struct cdrom_tocentry) - CDROMSTOP Stop the cdrom drive - CDROMSTART Start the cdrom drive - CDROMEJECT Ejects the cdrom media - CDROMVOLCTRL Control output volume (struct cdrom_volctrl) - CDROMSUBCHNL Read subchannel data (struct cdrom_subchnl) - CDROMREADMODE2 Read CDROM mode 2 data (2336 Bytes) - (struct cdrom_read) - CDROMREADMODE1 Read CDROM mode 1 data (2048 Bytes) - (struct cdrom_read) - CDROMREADAUDIO (struct cdrom_read_audio) - CDROMEJECT_SW enable(1)/disable(0) auto-ejecting - CDROMMULTISESSION Obtain the start-of-last-session - address of multi session disks - (struct cdrom_multisession) - CDROM_GET_MCN Obtain the "Universal Product Code" - if available (struct cdrom_mcn) - CDROM_GET_UPC Deprecated, use CDROM_GET_MCN instead. - CDROMRESET hard-reset the drive - CDROMVOLREAD Get the drive's volume setting - (struct cdrom_volctrl) - CDROMREADRAW read data in raw mode (2352 Bytes) - (struct cdrom_read) - CDROMREADCOOKED read data in cooked mode - CDROMSEEK seek msf address - CDROMPLAYBLK scsi-cd only, (struct cdrom_blk) - CDROMREADALL read all 2646 bytes - CDROMGETSPINDOWN return 4-bit spindown value - CDROMSETSPINDOWN set 4-bit spindown value - CDROMCLOSETRAY pendant of CDROMEJECT - CDROM_SET_OPTIONS Set behavior options - CDROM_CLEAR_OPTIONS Clear behavior options - CDROM_SELECT_SPEED Set the CD-ROM speed - CDROM_SELECT_DISC Select disc (for juke-boxes) - CDROM_MEDIA_CHANGED Check is media changed - CDROM_DRIVE_STATUS Get tray position, etc. - CDROM_DISC_STATUS Get disc type, etc. - CDROM_CHANGER_NSLOTS Get number of slots - CDROM_LOCKDOOR lock or unlock door - CDROM_DEBUG Turn debug messages on/off - CDROM_GET_CAPABILITY get capabilities - CDROMAUDIOBUFSIZ set the audio buffer size - DVD_READ_STRUCT Read structure - DVD_WRITE_STRUCT Write structure - DVD_AUTH Authentication - CDROM_SEND_PACKET send a packet to the drive - CDROM_NEXT_WRITABLE get next writable block - CDROM_LAST_WRITTEN get last block written on disc - ====================== =============================================== - - -The information that follows was determined from reading kernel source -code. It is likely that some corrections will be made over time. - ------------------------------------------------------------------------------- - -General: - - Unless otherwise specified, all ioctl calls return 0 on success - and -1 with errno set to an appropriate value on error. (Some - ioctls return non-negative data values.) - - Unless otherwise specified, all ioctl calls return -1 and set - errno to EFAULT on a failed attempt to copy data to or from user - address space. - - Individual drivers may return error codes not listed here. - - Unless otherwise specified, all data structures and constants - are defined in - ------------------------------------------------------------------------------- - - -CDROMPAUSE - Pause Audio Operation - - - usage:: - - ioctl(fd, CDROMPAUSE, 0); - - - inputs: - none - - - outputs: - none - - - error return: - - ENOSYS cd drive not audio-capable. - - -CDROMRESUME - Resume paused Audio Operation - - - usage:: - - ioctl(fd, CDROMRESUME, 0); - - - inputs: - none - - - outputs: - none - - - error return: - - ENOSYS cd drive not audio-capable. - - -CDROMPLAYMSF - Play Audio MSF - - (struct cdrom_msf) - - - usage:: - - struct cdrom_msf msf; - - ioctl(fd, CDROMPLAYMSF, &msf); - - inputs: - cdrom_msf structure, describing a segment of music to play - - - outputs: - none - - - error return: - - ENOSYS cd drive not audio-capable. - - notes: - - MSF stands for minutes-seconds-frames - - LBA stands for logical block address - - Segment is described as start and end times, where each time - is described as minutes:seconds:frames. - A frame is 1/75 of a second. - - -CDROMPLAYTRKIND - Play Audio Track/index - - (struct cdrom_ti) - - - usage:: - - struct cdrom_ti ti; - - ioctl(fd, CDROMPLAYTRKIND, &ti); - - inputs: - cdrom_ti structure, describing a segment of music to play - - - outputs: - none - - - error return: - - ENOSYS cd drive not audio-capable. - - notes: - - Segment is described as start and end times, where each time - is described as a track and an index. - - - -CDROMREADTOCHDR - Read TOC header - - (struct cdrom_tochdr) - - - usage:: - - cdrom_tochdr header; - - ioctl(fd, CDROMREADTOCHDR, &header); - - inputs: - cdrom_tochdr structure - - - outputs: - cdrom_tochdr structure - - - error return: - - ENOSYS cd drive not audio-capable. - - - -CDROMREADTOCENTRY - Read TOC entry - - (struct cdrom_tocentry) - - - usage:: - - struct cdrom_tocentry entry; - - ioctl(fd, CDROMREADTOCENTRY, &entry); - - inputs: - cdrom_tocentry structure - - - outputs: - cdrom_tocentry structure - - - error return: - - ENOSYS cd drive not audio-capable. - - EINVAL entry.cdte_format not CDROM_MSF or CDROM_LBA - - EINVAL requested track out of bounds - - EIO I/O error reading TOC - - notes: - - TOC stands for Table Of Contents - - MSF stands for minutes-seconds-frames - - LBA stands for logical block address - - - -CDROMSTOP - Stop the cdrom drive - - - usage:: - - ioctl(fd, CDROMSTOP, 0); - - - inputs: - none - - - outputs: - none - - - error return: - - ENOSYS cd drive not audio-capable. - - notes: - - Exact interpretation of this ioctl depends on the device, - but most seem to spin the drive down. - - -CDROMSTART - Start the cdrom drive - - - usage:: - - ioctl(fd, CDROMSTART, 0); - - - inputs: - none - - - outputs: - none - - - error return: - - ENOSYS cd drive not audio-capable. - - notes: - - Exact interpretation of this ioctl depends on the device, - but most seem to spin the drive up and/or close the tray. - Other devices ignore the ioctl completely. - - -CDROMEJECT - - Ejects the cdrom media - - - usage:: - - ioctl(fd, CDROMEJECT, 0); - - - inputs: - none - - - outputs: - none - - - error returns: - - ENOSYS cd drive not capable of ejecting - - EBUSY other processes are accessing drive, or door is locked - - notes: - - See CDROM_LOCKDOOR, below. - - - - -CDROMCLOSETRAY - pendant of CDROMEJECT - - - usage:: - - ioctl(fd, CDROMCLOSETRAY, 0); - - - inputs: - none - - - outputs: - none - - - error returns: - - ENOSYS cd drive not capable of closing the tray - - EBUSY other processes are accessing drive, or door is locked - - notes: - - See CDROM_LOCKDOOR, below. - - - - -CDROMVOLCTRL - Control output volume (struct cdrom_volctrl) - - - usage:: - - struct cdrom_volctrl volume; - - ioctl(fd, CDROMVOLCTRL, &volume); - - inputs: - cdrom_volctrl structure containing volumes for up to 4 - channels. - - outputs: - none - - - error return: - - ENOSYS cd drive not audio-capable. - - - -CDROMVOLREAD - Get the drive's volume setting - - (struct cdrom_volctrl) - - - usage:: - - struct cdrom_volctrl volume; - - ioctl(fd, CDROMVOLREAD, &volume); - - inputs: - none - - - outputs: - The current volume settings. - - - error return: - - ENOSYS cd drive not audio-capable. - - - -CDROMSUBCHNL - Read subchannel data - - (struct cdrom_subchnl) - - - usage:: - - struct cdrom_subchnl q; - - ioctl(fd, CDROMSUBCHNL, &q); - - inputs: - cdrom_subchnl structure - - - outputs: - cdrom_subchnl structure - - - error return: - - ENOSYS cd drive not audio-capable. - - EINVAL format not CDROM_MSF or CDROM_LBA - - notes: - - Format is converted to CDROM_MSF or CDROM_LBA - as per user request on return - - - -CDROMREADRAW - read data in raw mode (2352 Bytes) - - (struct cdrom_read) - - usage:: - - union { - - struct cdrom_msf msf; /* input */ - char buffer[CD_FRAMESIZE_RAW]; /* return */ - } arg; - ioctl(fd, CDROMREADRAW, &arg); - - inputs: - cdrom_msf structure indicating an address to read. - - Only the start values are significant. - - outputs: - Data written to address provided by user. - - - error return: - - EINVAL address less than 0, or msf less than 0:2:0 - - ENOMEM out of memory - - notes: - - As of 2.6.8.1, comments in indicate that this - ioctl accepts a cdrom_read structure, but actual source code - reads a cdrom_msf structure and writes a buffer of data to - the same address. - - - MSF values are converted to LBA values via this formula:: - - lba = (((m * CD_SECS) + s) * CD_FRAMES + f) - CD_MSF_OFFSET; - - - - -CDROMREADMODE1 - Read CDROM mode 1 data (2048 Bytes) - - (struct cdrom_read) - - notes: - Identical to CDROMREADRAW except that block size is - CD_FRAMESIZE (2048) bytes - - - -CDROMREADMODE2 - Read CDROM mode 2 data (2336 Bytes) - - (struct cdrom_read) - - notes: - Identical to CDROMREADRAW except that block size is - CD_FRAMESIZE_RAW0 (2336) bytes - - - -CDROMREADAUDIO - (struct cdrom_read_audio) - - usage:: - - struct cdrom_read_audio ra; - - ioctl(fd, CDROMREADAUDIO, &ra); - - inputs: - cdrom_read_audio structure containing read start - point and length - - outputs: - audio data, returned to buffer indicated by ra - - - error return: - - EINVAL format not CDROM_MSF or CDROM_LBA - - EINVAL nframes not in range [1 75] - - ENXIO drive has no queue (probably means invalid fd) - - ENOMEM out of memory - - -CDROMEJECT_SW - enable(1)/disable(0) auto-ejecting - - - usage:: - - int val; - - ioctl(fd, CDROMEJECT_SW, val); - - inputs: - Flag specifying auto-eject flag. - - - outputs: - none - - - error return: - - ENOSYS Drive is not capable of ejecting. - - EBUSY Door is locked - - - - -CDROMMULTISESSION - Obtain the start-of-last-session address of multi session disks - - (struct cdrom_multisession) - - usage:: - - struct cdrom_multisession ms_info; - - ioctl(fd, CDROMMULTISESSION, &ms_info); - - inputs: - cdrom_multisession structure containing desired - - format. - - outputs: - cdrom_multisession structure is filled with last_session - information. - - error return: - - EINVAL format not CDROM_MSF or CDROM_LBA - - -CDROM_GET_MCN - Obtain the "Universal Product Code" - if available - - (struct cdrom_mcn) - - - usage:: - - struct cdrom_mcn mcn; - - ioctl(fd, CDROM_GET_MCN, &mcn); - - inputs: - none - - - outputs: - Universal Product Code - - - error return: - - ENOSYS Drive is not capable of reading MCN data. - - notes: - - Source code comments state:: - - The following function is implemented, although very few - audio discs give Universal Product Code information, which - should just be the Medium Catalog Number on the box. Note, - that the way the code is written on the CD is /not/ uniform - across all discs! - - - - -CDROM_GET_UPC - CDROM_GET_MCN (deprecated) - - - Not implemented, as of 2.6.8.1 - - - -CDROMRESET - hard-reset the drive - - - usage:: - - ioctl(fd, CDROMRESET, 0); - - - inputs: - none - - - outputs: - none - - - error return: - - EACCES Access denied: requires CAP_SYS_ADMIN - - ENOSYS Drive is not capable of resetting. - - - - -CDROMREADCOOKED - read data in cooked mode - - - usage:: - - u8 buffer[CD_FRAMESIZE] - - ioctl(fd, CDROMREADCOOKED, buffer); - - inputs: - none - - - outputs: - 2048 bytes of data, "cooked" mode. - - - notes: - Not implemented on all drives. - - - - - -CDROMREADALL - read all 2646 bytes - - - Same as CDROMREADCOOKED, but reads 2646 bytes. - - - -CDROMSEEK - seek msf address - - - usage:: - - struct cdrom_msf msf; - - ioctl(fd, CDROMSEEK, &msf); - - inputs: - MSF address to seek to. - - - outputs: - none - - - - -CDROMPLAYBLK - scsi-cd only - - (struct cdrom_blk) - - - usage:: - - struct cdrom_blk blk; - - ioctl(fd, CDROMPLAYBLK, &blk); - - inputs: - Region to play - - - outputs: - none - - - - -CDROMGETSPINDOWN - usage:: - - char spindown; - - ioctl(fd, CDROMGETSPINDOWN, &spindown); - - inputs: - none - - - outputs: - The value of the current 4-bit spindown value. - - - - - -CDROMSETSPINDOWN - usage:: - - char spindown - - ioctl(fd, CDROMSETSPINDOWN, &spindown); - - inputs: - 4-bit value used to control spindown (TODO: more detail here) - - - outputs: - none - - - - - - -CDROM_SET_OPTIONS - Set behavior options - - - usage:: - - int options; - - ioctl(fd, CDROM_SET_OPTIONS, options); - - inputs: - New values for drive options. The logical 'or' of: - - ============== ================================== - CDO_AUTO_CLOSE close tray on first open(2) - CDO_AUTO_EJECT open tray on last release - CDO_USE_FFLAGS use O_NONBLOCK information on open - CDO_LOCK lock tray on open files - CDO_CHECK_TYPE check type on open for data - ============== ================================== - - outputs: - Returns the resulting options settings in the - ioctl return value. Returns -1 on error. - - error return: - - ENOSYS selected option(s) not supported by drive. - - - - -CDROM_CLEAR_OPTIONS - Clear behavior options - - - Same as CDROM_SET_OPTIONS, except that selected options are - turned off. - - - -CDROM_SELECT_SPEED - Set the CD-ROM speed - - - usage:: - - int speed; - - ioctl(fd, CDROM_SELECT_SPEED, speed); - - inputs: - New drive speed. - - - outputs: - none - - - error return: - - ENOSYS speed selection not supported by drive. - - - -CDROM_SELECT_DISC - Select disc (for juke-boxes) - - - usage:: - - int disk; - - ioctl(fd, CDROM_SELECT_DISC, disk); - - inputs: - Disk to load into drive. - - - outputs: - none - - - error return: - - EINVAL Disk number beyond capacity of drive - - - -CDROM_MEDIA_CHANGED - Check is media changed - - - usage:: - - int slot; - - ioctl(fd, CDROM_MEDIA_CHANGED, slot); - - inputs: - Slot number to be tested, always zero except for jukeboxes. - - May also be special values CDSL_NONE or CDSL_CURRENT - - outputs: - Ioctl return value is 0 or 1 depending on whether the media - - has been changed, or -1 on error. - - error returns: - - ENOSYS Drive can't detect media change - - EINVAL Slot number beyond capacity of drive - - ENOMEM Out of memory - - - -CDROM_DRIVE_STATUS - Get tray position, etc. - - - usage:: - - int slot; - - ioctl(fd, CDROM_DRIVE_STATUS, slot); - - inputs: - Slot number to be tested, always zero except for jukeboxes. - - May also be special values CDSL_NONE or CDSL_CURRENT - - outputs: - Ioctl return value will be one of the following values - - from : - - =================== ========================== - CDS_NO_INFO Information not available. - CDS_NO_DISC - CDS_TRAY_OPEN - CDS_DRIVE_NOT_READY - CDS_DISC_OK - -1 error - =================== ========================== - - error returns: - - ENOSYS Drive can't detect drive status - - EINVAL Slot number beyond capacity of drive - - ENOMEM Out of memory - - - - -CDROM_DISC_STATUS - Get disc type, etc. - - - usage:: - - ioctl(fd, CDROM_DISC_STATUS, 0); - - - inputs: - none - - - outputs: - Ioctl return value will be one of the following values - - from : - - - CDS_NO_INFO - - CDS_AUDIO - - CDS_MIXED - - CDS_XA_2_2 - - CDS_XA_2_1 - - CDS_DATA_1 - - error returns: - none at present - - notes: - - Source code comments state:: - - - Ok, this is where problems start. The current interface for - the CDROM_DISC_STATUS ioctl is flawed. It makes the false - assumption that CDs are all CDS_DATA_1 or all CDS_AUDIO, etc. - Unfortunately, while this is often the case, it is also - very common for CDs to have some tracks with data, and some - tracks with audio. Just because I feel like it, I declare - the following to be the best way to cope. If the CD has - ANY data tracks on it, it will be returned as a data CD. - If it has any XA tracks, I will return it as that. Now I - could simplify this interface by combining these returns with - the above, but this more clearly demonstrates the problem - with the current interface. Too bad this wasn't designed - to use bitmasks... -Erik - - Well, now we have the option CDS_MIXED: a mixed-type CD. - User level programmers might feel the ioctl is not very - useful. - ---david - - - - -CDROM_CHANGER_NSLOTS - Get number of slots - - - usage:: - - ioctl(fd, CDROM_CHANGER_NSLOTS, 0); - - - inputs: - none - - - outputs: - The ioctl return value will be the number of slots in a - CD changer. Typically 1 for non-multi-disk devices. - - error returns: - none - - - -CDROM_LOCKDOOR - lock or unlock door - - - usage:: - - int lock; - - ioctl(fd, CDROM_LOCKDOOR, lock); - - inputs: - Door lock flag, 1=lock, 0=unlock - - - outputs: - none - - - error returns: - - EDRIVE_CANT_DO_THIS - - Door lock function not supported. - - EBUSY - - Attempt to unlock when multiple users - have the drive open and not CAP_SYS_ADMIN - - notes: - As of 2.6.8.1, the lock flag is a global lock, meaning that - all CD drives will be locked or unlocked together. This is - probably a bug. - - The EDRIVE_CANT_DO_THIS value is defined in - and is currently (2.6.8.1) the same as EOPNOTSUPP - - - -CDROM_DEBUG - Turn debug messages on/off - - - usage:: - - int debug; - - ioctl(fd, CDROM_DEBUG, debug); - - inputs: - Cdrom debug flag, 0=disable, 1=enable - - - outputs: - The ioctl return value will be the new debug flag. - - - error return: - - EACCES Access denied: requires CAP_SYS_ADMIN - - - -CDROM_GET_CAPABILITY - get capabilities - - - usage:: - - ioctl(fd, CDROM_GET_CAPABILITY, 0); - - - inputs: - none - - - outputs: - The ioctl return value is the current device capability - flags. See CDC_CLOSE_TRAY, CDC_OPEN_TRAY, etc. - - - -CDROMAUDIOBUFSIZ - set the audio buffer size - - - usage:: - - int arg; - - ioctl(fd, CDROMAUDIOBUFSIZ, val); - - inputs: - New audio buffer size - - - outputs: - The ioctl return value is the new audio buffer size, or -1 - on error. - - error return: - - ENOSYS Not supported by this driver. - - notes: - Not supported by all drivers. - - - - -DVD_READ_STRUCT Read structure - - usage:: - - dvd_struct s; - - ioctl(fd, DVD_READ_STRUCT, &s); - - inputs: - dvd_struct structure, containing: - - =================== ========================================== - type specifies the information desired, one of - DVD_STRUCT_PHYSICAL, DVD_STRUCT_COPYRIGHT, - DVD_STRUCT_DISCKEY, DVD_STRUCT_BCA, - DVD_STRUCT_MANUFACT - physical.layer_num desired layer, indexed from 0 - copyright.layer_num desired layer, indexed from 0 - disckey.agid - =================== ========================================== - - outputs: - dvd_struct structure, containing: - - =================== ================================ - physical for type == DVD_STRUCT_PHYSICAL - copyright for type == DVD_STRUCT_COPYRIGHT - disckey.value for type == DVD_STRUCT_DISCKEY - bca.{len,value} for type == DVD_STRUCT_BCA - manufact.{len,valu} for type == DVD_STRUCT_MANUFACT - =================== ================================ - - error returns: - - EINVAL physical.layer_num exceeds number of layers - - EIO Received invalid response from drive - - - -DVD_WRITE_STRUCT Write structure - - Not implemented, as of 2.6.8.1 - - - -DVD_AUTH Authentication - - usage:: - - dvd_authinfo ai; - - ioctl(fd, DVD_AUTH, &ai); - - inputs: - dvd_authinfo structure. See - - - outputs: - dvd_authinfo structure. - - - error return: - - ENOTTY ai.type not recognized. - - - -CDROM_SEND_PACKET - send a packet to the drive - - - usage:: - - struct cdrom_generic_command cgc; - - ioctl(fd, CDROM_SEND_PACKET, &cgc); - - inputs: - cdrom_generic_command structure containing the packet to send. - - - outputs: - none - - cdrom_generic_command structure containing results. - - error return: - - EIO - - command failed. - - EPERM - - Operation not permitted, either because a - write command was attempted on a drive which - is opened read-only, or because the command - requires CAP_SYS_RAWIO - - EINVAL - - cgc.data_direction not set - - - -CDROM_NEXT_WRITABLE - get next writable block - - - usage:: - - long next; - - ioctl(fd, CDROM_NEXT_WRITABLE, &next); - - inputs: - none - - - outputs: - The next writable block. - - - notes: - If the device does not support this ioctl directly, the - - ioctl will return CDROM_LAST_WRITTEN + 7. - - - -CDROM_LAST_WRITTEN - get last block written on disc - - - usage:: - - long last; - - ioctl(fd, CDROM_LAST_WRITTEN, &last); - - inputs: - none - - - outputs: - The last block written on disc - - - notes: - If the device does not support this ioctl directly, the - result is derived from the disc's table of contents. If the - table of contents can't be read, this ioctl returns an - error. diff --git a/Documentation/ioctl/hdio.rst b/Documentation/ioctl/hdio.rst deleted file mode 100644 index e822e3dff176..000000000000 --- a/Documentation/ioctl/hdio.rst +++ /dev/null @@ -1,1342 +0,0 @@ -============================== -Summary of `HDIO_` ioctl calls -============================== - -- Edward A. Falk - -November, 2004 - -This document attempts to describe the ioctl(2) calls supported by -the HD/IDE layer. These are by-and-large implemented (as of Linux 2.6) -in drivers/ide/ide.c and drivers/block/scsi_ioctl.c - -ioctl values are listed in . As of this writing, they -are as follows: - - ioctls that pass argument pointers to user space: - - ======================= ======================================= - HDIO_GETGEO get device geometry - HDIO_GET_UNMASKINTR get current unmask setting - HDIO_GET_MULTCOUNT get current IDE blockmode setting - HDIO_GET_QDMA get use-qdma flag - HDIO_SET_XFER set transfer rate via proc - HDIO_OBSOLETE_IDENTITY OBSOLETE, DO NOT USE - HDIO_GET_KEEPSETTINGS get keep-settings-on-reset flag - HDIO_GET_32BIT get current io_32bit setting - HDIO_GET_NOWERR get ignore-write-error flag - HDIO_GET_DMA get use-dma flag - HDIO_GET_NICE get nice flags - HDIO_GET_IDENTITY get IDE identification info - HDIO_GET_WCACHE get write cache mode on|off - HDIO_GET_ACOUSTIC get acoustic value - HDIO_GET_ADDRESS get sector addressing mode - HDIO_GET_BUSSTATE get the bus state of the hwif - HDIO_TRISTATE_HWIF execute a channel tristate - HDIO_DRIVE_RESET execute a device reset - HDIO_DRIVE_TASKFILE execute raw taskfile - HDIO_DRIVE_TASK execute task and special drive command - HDIO_DRIVE_CMD execute a special drive command - HDIO_DRIVE_CMD_AEB HDIO_DRIVE_TASK - ======================= ======================================= - - ioctls that pass non-pointer values: - - ======================= ======================================= - HDIO_SET_MULTCOUNT change IDE blockmode - HDIO_SET_UNMASKINTR permit other irqs during I/O - HDIO_SET_KEEPSETTINGS keep ioctl settings on reset - HDIO_SET_32BIT change io_32bit flags - HDIO_SET_NOWERR change ignore-write-error flag - HDIO_SET_DMA change use-dma flag - HDIO_SET_PIO_MODE reconfig interface to new speed - HDIO_SCAN_HWIF register and (re)scan interface - HDIO_SET_NICE set nice flags - HDIO_UNREGISTER_HWIF unregister interface - HDIO_SET_WCACHE change write cache enable-disable - HDIO_SET_ACOUSTIC change acoustic behavior - HDIO_SET_BUSSTATE set the bus state of the hwif - HDIO_SET_QDMA change use-qdma flag - HDIO_SET_ADDRESS change lba addressing modes - - HDIO_SET_IDE_SCSI Set scsi emulation mode on/off - HDIO_SET_SCSI_IDE not implemented yet - ======================= ======================================= - - -The information that follows was determined from reading kernel source -code. It is likely that some corrections will be made over time. - ------------------------------------------------------------------------------- - -General: - - Unless otherwise specified, all ioctl calls return 0 on success - and -1 with errno set to an appropriate value on error. - - Unless otherwise specified, all ioctl calls return -1 and set - errno to EFAULT on a failed attempt to copy data to or from user - address space. - - Unless otherwise specified, all data structures and constants - are defined in - ------------------------------------------------------------------------------- - -HDIO_GETGEO - get device geometry - - - usage:: - - struct hd_geometry geom; - - ioctl(fd, HDIO_GETGEO, &geom); - - - inputs: - none - - - - outputs: - hd_geometry structure containing: - - - ========= ================================== - heads number of heads - sectors number of sectors/track - cylinders number of cylinders, mod 65536 - start starting sector of this partition. - ========= ================================== - - - error returns: - - EINVAL - - if the device is not a disk drive or floppy drive, - or if the user passes a null pointer - - - notes: - Not particularly useful with modern disk drives, whose geometry - is a polite fiction anyway. Modern drives are addressed - purely by sector number nowadays (lba addressing), and the - drive geometry is an abstraction which is actually subject - to change. Currently (as of Nov 2004), the geometry values - are the "bios" values -- presumably the values the drive had - when Linux first booted. - - In addition, the cylinders field of the hd_geometry is an - unsigned short, meaning that on most architectures, this - ioctl will not return a meaningful value on drives with more - than 65535 tracks. - - The start field is unsigned long, meaning that it will not - contain a meaningful value for disks over 219 Gb in size. - - - - -HDIO_GET_UNMASKINTR - get current unmask setting - - - usage:: - - long val; - - ioctl(fd, HDIO_GET_UNMASKINTR, &val); - - inputs: - none - - - - outputs: - The value of the drive's current unmask setting - - - - - -HDIO_SET_UNMASKINTR - permit other irqs during I/O - - - usage:: - - unsigned long val; - - ioctl(fd, HDIO_SET_UNMASKINTR, val); - - inputs: - New value for unmask flag - - - - outputs: - none - - - - error return: - - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - - EACCES Access denied: requires CAP_SYS_ADMIN - - EINVAL value out of range [0 1] - - EBUSY Controller busy - - - - -HDIO_GET_MULTCOUNT - get current IDE blockmode setting - - - usage:: - - long val; - - ioctl(fd, HDIO_GET_MULTCOUNT, &val); - - inputs: - none - - - - outputs: - The value of the current IDE block mode setting. This - controls how many sectors the drive will transfer per - interrupt. - - - -HDIO_SET_MULTCOUNT - change IDE blockmode - - - usage:: - - int val; - - ioctl(fd, HDIO_SET_MULTCOUNT, val); - - inputs: - New value for IDE block mode setting. This controls how many - sectors the drive will transfer per interrupt. - - outputs: - none - - - - error return: - - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - - EACCES Access denied: requires CAP_SYS_ADMIN - - EINVAL value out of range supported by disk. - - EBUSY Controller busy or blockmode already set. - - EIO Drive did not accept new block mode. - - notes: - Source code comments read:: - - This is tightly woven into the driver->do_special cannot - touch. DON'T do it again until a total personality rewrite - is committed. - - If blockmode has already been set, this ioctl will fail with - -EBUSY - - - -HDIO_GET_QDMA - get use-qdma flag - - - Not implemented, as of 2.6.8.1 - - - -HDIO_SET_XFER - set transfer rate via proc - - - Not implemented, as of 2.6.8.1 - - - -HDIO_OBSOLETE_IDENTITY - OBSOLETE, DO NOT USE - - - Same as HDIO_GET_IDENTITY (see below), except that it only - returns the first 142 bytes of drive identity information. - - - -HDIO_GET_IDENTITY - get IDE identification info - - - usage:: - - unsigned char identity[512]; - - ioctl(fd, HDIO_GET_IDENTITY, identity); - - inputs: - none - - - - outputs: - ATA drive identity information. For full description, see - the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in - the ATA specification. - - error returns: - - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - - ENOMSG IDENTIFY DEVICE information not available - - notes: - Returns information that was obtained when the drive was - probed. Some of this information is subject to change, and - this ioctl does not re-probe the drive to update the - information. - - This information is also available from /proc/ide/hdX/identify - - - -HDIO_GET_KEEPSETTINGS - get keep-settings-on-reset flag - - - usage:: - - long val; - - ioctl(fd, HDIO_GET_KEEPSETTINGS, &val); - - inputs: - none - - - - outputs: - The value of the current "keep settings" flag - - - - notes: - When set, indicates that kernel should restore settings - after a drive reset. - - - -HDIO_SET_KEEPSETTINGS - keep ioctl settings on reset - - - usage:: - - long val; - - ioctl(fd, HDIO_SET_KEEPSETTINGS, val); - - inputs: - New value for keep_settings flag - - - - outputs: - none - - - - error return: - - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - - EACCES Access denied: requires CAP_SYS_ADMIN - - EINVAL value out of range [0 1] - - EBUSY Controller busy - - - -HDIO_GET_32BIT - get current io_32bit setting - - - usage:: - - long val; - - ioctl(fd, HDIO_GET_32BIT, &val); - - inputs: - none - - - - outputs: - The value of the current io_32bit setting - - - - notes: - 0=16-bit, 1=32-bit, 2,3 = 32bit+sync - - - - - -HDIO_GET_NOWERR - get ignore-write-error flag - - - usage:: - - long val; - - ioctl(fd, HDIO_GET_NOWERR, &val); - - inputs: - none - - - - outputs: - The value of the current ignore-write-error flag - - - - - -HDIO_GET_DMA - get use-dma flag - - - usage:: - - long val; - - ioctl(fd, HDIO_GET_DMA, &val); - - inputs: - none - - - - outputs: - The value of the current use-dma flag - - - - - -HDIO_GET_NICE - get nice flags - - - usage:: - - long nice; - - ioctl(fd, HDIO_GET_NICE, &nice); - - inputs: - none - - - - outputs: - The drive's "nice" values. - - - - notes: - Per-drive flags which determine when the system will give more - bandwidth to other devices sharing the same IDE bus. - - See , near symbol IDE_NICE_DSC_OVERLAP. - - - - -HDIO_SET_NICE - set nice flags - - - usage:: - - unsigned long nice; - - ... - ioctl(fd, HDIO_SET_NICE, nice); - - inputs: - bitmask of nice flags. - - - - outputs: - none - - - - error returns: - - EACCES Access denied: requires CAP_SYS_ADMIN - - EPERM Flags other than DSC_OVERLAP and NICE_1 set. - - EPERM DSC_OVERLAP specified but not supported by drive - - notes: - This ioctl sets the DSC_OVERLAP and NICE_1 flags from values - provided by the user. - - Nice flags are listed in , starting with - IDE_NICE_DSC_OVERLAP. These values represent shifts. - - - - - -HDIO_GET_WCACHE - get write cache mode on|off - - - usage:: - - long val; - - ioctl(fd, HDIO_GET_WCACHE, &val); - - inputs: - none - - - - outputs: - The value of the current write cache mode - - - - - -HDIO_GET_ACOUSTIC - get acoustic value - - - usage:: - - long val; - - ioctl(fd, HDIO_GET_ACOUSTIC, &val); - - inputs: - none - - - - outputs: - The value of the current acoustic settings - - - - notes: - See HDIO_SET_ACOUSTIC - - - - - -HDIO_GET_ADDRESS - usage:: - - - long val; - - ioctl(fd, HDIO_GET_ADDRESS, &val); - - inputs: - none - - - - outputs: - The value of the current addressing mode: - - = =================== - 0 28-bit - 1 48-bit - 2 48-bit doing 28-bit - 3 64-bit - = =================== - - - -HDIO_GET_BUSSTATE - get the bus state of the hwif - - - usage:: - - long state; - - ioctl(fd, HDIO_SCAN_HWIF, &state); - - inputs: - none - - - - outputs: - Current power state of the IDE bus. One of BUSSTATE_OFF, - BUSSTATE_ON, or BUSSTATE_TRISTATE - - error returns: - - EACCES Access denied: requires CAP_SYS_ADMIN - - - - -HDIO_SET_BUSSTATE - set the bus state of the hwif - - - usage:: - - int state; - - ... - ioctl(fd, HDIO_SCAN_HWIF, state); - - inputs: - Desired IDE power state. One of BUSSTATE_OFF, BUSSTATE_ON, - or BUSSTATE_TRISTATE - - outputs: - none - - - - error returns: - - EACCES Access denied: requires CAP_SYS_RAWIO - - EOPNOTSUPP Hardware interface does not support bus power control - - - - -HDIO_TRISTATE_HWIF - execute a channel tristate - - - Not implemented, as of 2.6.8.1. See HDIO_SET_BUSSTATE - - - -HDIO_DRIVE_RESET - execute a device reset - - - usage:: - - int args[3] - - ... - ioctl(fd, HDIO_DRIVE_RESET, args); - - inputs: - none - - - - outputs: - none - - - - error returns: - - EACCES Access denied: requires CAP_SYS_ADMIN - - ENXIO No such device: phy dead or ctl_addr == 0 - - EIO I/O error: reset timed out or hardware error - - notes: - - - Execute a reset on the device as soon as the current IO - operation has completed. - - - Executes an ATAPI soft reset if applicable, otherwise - executes an ATA soft reset on the controller. - - - -HDIO_DRIVE_TASKFILE - execute raw taskfile - - - Note: - If you don't have a copy of the ANSI ATA specification - handy, you should probably ignore this ioctl. - - - Execute an ATA disk command directly by writing the "taskfile" - registers of the drive. Requires ADMIN and RAWIO access - privileges. - - usage:: - - struct { - - ide_task_request_t req_task; - u8 outbuf[OUTPUT_SIZE]; - u8 inbuf[INPUT_SIZE]; - } task; - memset(&task.req_task, 0, sizeof(task.req_task)); - task.req_task.out_size = sizeof(task.outbuf); - task.req_task.in_size = sizeof(task.inbuf); - ... - ioctl(fd, HDIO_DRIVE_TASKFILE, &task); - ... - - inputs: - - (See below for details on memory area passed to ioctl.) - - ============ =================================================== - io_ports[8] values to be written to taskfile registers - hob_ports[8] high-order bytes, for extended commands. - out_flags flags indicating which registers are valid - in_flags flags indicating which registers should be returned - data_phase see below - req_cmd command type to be executed - out_size size of output buffer - outbuf buffer of data to be transmitted to disk - inbuf buffer of data to be received from disk (see [1]) - ============ =================================================== - - outputs: - - =========== ==================================================== - io_ports[] values returned in the taskfile registers - hob_ports[] high-order bytes, for extended commands. - out_flags flags indicating which registers are valid (see [2]) - in_flags flags indicating which registers should be returned - outbuf buffer of data to be transmitted to disk (see [1]) - inbuf buffer of data to be received from disk - =========== ==================================================== - - error returns: - - EACCES CAP_SYS_ADMIN or CAP_SYS_RAWIO privilege not set. - - ENOMSG Device is not a disk drive. - - ENOMEM Unable to allocate memory for task - - EFAULT req_cmd == TASKFILE_IN_OUT (not implemented as of 2.6.8) - - EPERM - - req_cmd == TASKFILE_MULTI_OUT and drive - multi-count not yet set. - - EIO Drive failed the command. - - notes: - - [1] READ THE FOLLOWING NOTES *CAREFULLY*. THIS IOCTL IS - FULL OF GOTCHAS. Extreme caution should be used with using - this ioctl. A mistake can easily corrupt data or hang the - system. - - [2] Both the input and output buffers are copied from the - user and written back to the user, even when not used. - - [3] If one or more bits are set in out_flags and in_flags is - zero, the following values are used for in_flags.all and - written back into in_flags on completion. - - * IDE_TASKFILE_STD_IN_FLAGS | (IDE_HOB_STD_IN_FLAGS << 8) - if LBA48 addressing is enabled for the drive - * IDE_TASKFILE_STD_IN_FLAGS - if CHS/LBA28 - - The association between in_flags.all and each enable - bitfield flips depending on endianness; fortunately, TASKFILE - only uses inflags.b.data bit and ignores all other bits. - The end result is that, on any endian machines, it has no - effect other than modifying in_flags on completion. - - [4] The default value of SELECT is (0xa0|DEV_bit|LBA_bit) - except for four drives per port chipsets. For four drives - per port chipsets, it's (0xa0|DEV_bit|LBA_bit) for the first - pair and (0x80|DEV_bit|LBA_bit) for the second pair. - - [5] The argument to the ioctl is a pointer to a region of - memory containing a ide_task_request_t structure, followed - by an optional buffer of data to be transmitted to the - drive, followed by an optional buffer to receive data from - the drive. - - Command is passed to the disk drive via the ide_task_request_t - structure, which contains these fields: - - ============ =============================================== - io_ports[8] values for the taskfile registers - hob_ports[8] high-order bytes, for extended commands - out_flags flags indicating which entries in the - io_ports[] and hob_ports[] arrays - contain valid values. Type ide_reg_valid_t. - in_flags flags indicating which entries in the - io_ports[] and hob_ports[] arrays - are expected to contain valid values - on return. - data_phase See below - req_cmd Command type, see below - out_size output (user->drive) buffer size, bytes - in_size input (drive->user) buffer size, bytes - ============ =============================================== - - When out_flags is zero, the following registers are loaded. - - ============ =============================================== - HOB_FEATURE If the drive supports LBA48 - HOB_NSECTOR If the drive supports LBA48 - HOB_SECTOR If the drive supports LBA48 - HOB_LCYL If the drive supports LBA48 - HOB_HCYL If the drive supports LBA48 - FEATURE - NSECTOR - SECTOR - LCYL - HCYL - SELECT First, masked with 0xE0 if LBA48, 0xEF - otherwise; then, or'ed with the default - value of SELECT. - ============ =============================================== - - If any bit in out_flags is set, the following registers are loaded. - - ============ =============================================== - HOB_DATA If out_flags.b.data is set. HOB_DATA will - travel on DD8-DD15 on little endian machines - and on DD0-DD7 on big endian machines. - DATA If out_flags.b.data is set. DATA will - travel on DD0-DD7 on little endian machines - and on DD8-DD15 on big endian machines. - HOB_NSECTOR If out_flags.b.nsector_hob is set - HOB_SECTOR If out_flags.b.sector_hob is set - HOB_LCYL If out_flags.b.lcyl_hob is set - HOB_HCYL If out_flags.b.hcyl_hob is set - FEATURE If out_flags.b.feature is set - NSECTOR If out_flags.b.nsector is set - SECTOR If out_flags.b.sector is set - LCYL If out_flags.b.lcyl is set - HCYL If out_flags.b.hcyl is set - SELECT Or'ed with the default value of SELECT and - loaded regardless of out_flags.b.select. - ============ =============================================== - - Taskfile registers are read back from the drive into - {io|hob}_ports[] after the command completes iff one of the - following conditions is met; otherwise, the original values - will be written back, unchanged. - - 1. The drive fails the command (EIO). - 2. One or more than one bits are set in out_flags. - 3. The requested data_phase is TASKFILE_NO_DATA. - - ============ =============================================== - HOB_DATA If in_flags.b.data is set. It will contain - DD8-DD15 on little endian machines and - DD0-DD7 on big endian machines. - DATA If in_flags.b.data is set. It will contain - DD0-DD7 on little endian machines and - DD8-DD15 on big endian machines. - HOB_FEATURE If the drive supports LBA48 - HOB_NSECTOR If the drive supports LBA48 - HOB_SECTOR If the drive supports LBA48 - HOB_LCYL If the drive supports LBA48 - HOB_HCYL If the drive supports LBA48 - NSECTOR - SECTOR - LCYL - HCYL - ============ =============================================== - - The data_phase field describes the data transfer to be - performed. Value is one of: - - =================== ======================================== - TASKFILE_IN - TASKFILE_MULTI_IN - TASKFILE_OUT - TASKFILE_MULTI_OUT - TASKFILE_IN_OUT - TASKFILE_IN_DMA - TASKFILE_IN_DMAQ == IN_DMA (queueing not supported) - TASKFILE_OUT_DMA - TASKFILE_OUT_DMAQ == OUT_DMA (queueing not supported) - TASKFILE_P_IN unimplemented - TASKFILE_P_IN_DMA unimplemented - TASKFILE_P_IN_DMAQ unimplemented - TASKFILE_P_OUT unimplemented - TASKFILE_P_OUT_DMA unimplemented - TASKFILE_P_OUT_DMAQ unimplemented - =================== ======================================== - - The req_cmd field classifies the command type. It may be - one of: - - ======================== ======================================= - IDE_DRIVE_TASK_NO_DATA - IDE_DRIVE_TASK_SET_XFER unimplemented - IDE_DRIVE_TASK_IN - IDE_DRIVE_TASK_OUT unimplemented - IDE_DRIVE_TASK_RAW_WRITE - ======================== ======================================= - - [6] Do not access {in|out}_flags->all except for resetting - all the bits. Always access individual bit fields. ->all - value will flip depending on endianness. For the same - reason, do not use IDE_{TASKFILE|HOB}_STD_{OUT|IN}_FLAGS - constants defined in hdreg.h. - - - -HDIO_DRIVE_CMD - execute a special drive command - - - Note: If you don't have a copy of the ANSI ATA specification - handy, you should probably ignore this ioctl. - - usage:: - - u8 args[4+XFER_SIZE]; - - ... - ioctl(fd, HDIO_DRIVE_CMD, args); - - inputs: - Commands other than WIN_SMART: - - ======= ======= - args[0] COMMAND - args[1] NSECTOR - args[2] FEATURE - args[3] NSECTOR - ======= ======= - - WIN_SMART: - - ======= ======= - args[0] COMMAND - args[1] SECTOR - args[2] FEATURE - args[3] NSECTOR - ======= ======= - - outputs: - args[] buffer is filled with register values followed by any - - - data returned by the disk. - - ======== ==================================================== - args[0] status - args[1] error - args[2] NSECTOR - args[3] undefined - args[4+] NSECTOR * 512 bytes of data returned by the command. - ======== ==================================================== - - error returns: - - EACCES Access denied: requires CAP_SYS_RAWIO - - ENOMEM Unable to allocate memory for task - - EIO Drive reports error - - notes: - - [1] For commands other than WIN_SMART, args[1] should equal - args[3]. SECTOR, LCYL and HCYL are undefined. For - WIN_SMART, 0x4f and 0xc2 are loaded into LCYL and HCYL - respectively. In both cases SELECT will contain the default - value for the drive. Please refer to HDIO_DRIVE_TASKFILE - notes for the default value of SELECT. - - [2] If NSECTOR value is greater than zero and the drive sets - DRQ when interrupting for the command, NSECTOR * 512 bytes - are read from the device into the area following NSECTOR. - In the above example, the area would be - args[4..4+XFER_SIZE]. 16bit PIO is used regardless of - HDIO_SET_32BIT setting. - - [3] If COMMAND == WIN_SETFEATURES && FEATURE == SETFEATURES_XFER - && NSECTOR >= XFER_SW_DMA_0 && the drive supports any DMA - mode, IDE driver will try to tune the transfer mode of the - drive accordingly. - - - -HDIO_DRIVE_TASK - execute task and special drive command - - - Note: If you don't have a copy of the ANSI ATA specification - handy, you should probably ignore this ioctl. - - usage:: - - u8 args[7]; - - ... - ioctl(fd, HDIO_DRIVE_TASK, args); - - inputs: - Taskfile register values: - - ======= ======= - args[0] COMMAND - args[1] FEATURE - args[2] NSECTOR - args[3] SECTOR - args[4] LCYL - args[5] HCYL - args[6] SELECT - ======= ======= - - outputs: - Taskfile register values: - - - ======= ======= - args[0] status - args[1] error - args[2] NSECTOR - args[3] SECTOR - args[4] LCYL - args[5] HCYL - args[6] SELECT - ======= ======= - - error returns: - - EACCES Access denied: requires CAP_SYS_RAWIO - - ENOMEM Unable to allocate memory for task - - ENOMSG Device is not a disk drive. - - EIO Drive failed the command. - - notes: - - [1] DEV bit (0x10) of SELECT register is ignored and the - appropriate value for the drive is used. All other bits - are used unaltered. - - - -HDIO_DRIVE_CMD_AEB - HDIO_DRIVE_TASK - - - Not implemented, as of 2.6.8.1 - - - -HDIO_SET_32BIT - change io_32bit flags - - - usage:: - - int val; - - ioctl(fd, HDIO_SET_32BIT, val); - - inputs: - New value for io_32bit flag - - - - outputs: - none - - - - error return: - - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - - EACCES Access denied: requires CAP_SYS_ADMIN - - EINVAL value out of range [0 3] - - EBUSY Controller busy - - - - -HDIO_SET_NOWERR - change ignore-write-error flag - - - usage:: - - int val; - - ioctl(fd, HDIO_SET_NOWERR, val); - - inputs: - New value for ignore-write-error flag. Used for ignoring - - - WRERR_STAT - - outputs: - none - - - - error return: - - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - - EACCES Access denied: requires CAP_SYS_ADMIN - - EINVAL value out of range [0 1] - - EBUSY Controller busy - - - -HDIO_SET_DMA - change use-dma flag - - - usage:: - - long val; - - ioctl(fd, HDIO_SET_DMA, val); - - inputs: - New value for use-dma flag - - - - outputs: - none - - - - error return: - - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - - EACCES Access denied: requires CAP_SYS_ADMIN - - EINVAL value out of range [0 1] - - EBUSY Controller busy - - - -HDIO_SET_PIO_MODE - reconfig interface to new speed - - - usage:: - - long val; - - ioctl(fd, HDIO_SET_PIO_MODE, val); - - inputs: - New interface speed. - - - - outputs: - none - - - - error return: - - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - - EACCES Access denied: requires CAP_SYS_ADMIN - - EINVAL value out of range [0 255] - - EBUSY Controller busy - - - -HDIO_SCAN_HWIF - register and (re)scan interface - - - usage:: - - int args[3] - - ... - ioctl(fd, HDIO_SCAN_HWIF, args); - - inputs: - - ======= ========================= - args[0] io address to probe - - - args[1] control address to probe - args[2] irq number - ======= ========================= - - outputs: - none - - - - error returns: - - EACCES Access denied: requires CAP_SYS_RAWIO - - EIO Probe failed. - - notes: - This ioctl initializes the addresses and irq for a disk - controller, probes for drives, and creates /proc/ide - interfaces as appropriate. - - - -HDIO_UNREGISTER_HWIF - unregister interface - - - usage:: - - int index; - - ioctl(fd, HDIO_UNREGISTER_HWIF, index); - - inputs: - index index of hardware interface to unregister - - - - outputs: - none - - - - error returns: - - EACCES Access denied: requires CAP_SYS_RAWIO - - notes: - This ioctl removes a hardware interface from the kernel. - - Currently (2.6.8) this ioctl silently fails if any drive on - the interface is busy. - - - -HDIO_SET_WCACHE - change write cache enable-disable - - - usage:: - - int val; - - ioctl(fd, HDIO_SET_WCACHE, val); - - inputs: - New value for write cache enable - - - - outputs: - none - - - - error return: - - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - - EACCES Access denied: requires CAP_SYS_ADMIN - - EINVAL value out of range [0 1] - - EBUSY Controller busy - - - -HDIO_SET_ACOUSTIC - change acoustic behavior - - - usage:: - - int val; - - ioctl(fd, HDIO_SET_ACOUSTIC, val); - - inputs: - New value for drive acoustic settings - - - - outputs: - none - - - - error return: - - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - - EACCES Access denied: requires CAP_SYS_ADMIN - - EINVAL value out of range [0 254] - - EBUSY Controller busy - - - -HDIO_SET_QDMA - change use-qdma flag - - - Not implemented, as of 2.6.8.1 - - - -HDIO_SET_ADDRESS - change lba addressing modes - - - usage:: - - int val; - - ioctl(fd, HDIO_SET_ADDRESS, val); - - inputs: - New value for addressing mode - - = =================== - 0 28-bit - 1 48-bit - 2 48-bit doing 28-bit - = =================== - - outputs: - none - - - - error return: - - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - - EACCES Access denied: requires CAP_SYS_ADMIN - - EINVAL value out of range [0 2] - - EBUSY Controller busy - - EIO Drive does not support lba48 mode. - - -HDIO_SET_IDE_SCSI - usage:: - - - long val; - - ioctl(fd, HDIO_SET_IDE_SCSI, val); - - inputs: - New value for scsi emulation mode (?) - - - - outputs: - none - - - - error return: - - EINVAL (bdev != bdev->bd_contains) (not sure what this means) - - EACCES Access denied: requires CAP_SYS_ADMIN - - EINVAL value out of range [0 1] - - EBUSY Controller busy - - - -HDIO_SET_SCSI_IDE - Not implemented, as of 2.6.8.1 diff --git a/Documentation/ioctl/index.rst b/Documentation/ioctl/index.rst deleted file mode 100644 index 475675eae086..000000000000 --- a/Documentation/ioctl/index.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -====== -IOCTLs -====== - -.. toctree:: - :maxdepth: 1 - - ioctl-number - - ioctl-decoding - - cdrom - hdio diff --git a/Documentation/ioctl/ioctl-decoding.rst b/Documentation/ioctl/ioctl-decoding.rst deleted file mode 100644 index 380d6bb3e3ea..000000000000 --- a/Documentation/ioctl/ioctl-decoding.rst +++ /dev/null @@ -1,31 +0,0 @@ -============================== -Decoding an IOCTL Magic Number -============================== - -To decode a hex IOCTL code: - -Most architectures use this generic format, but check -include/ARCH/ioctl.h for specifics, e.g. powerpc -uses 3 bits to encode read/write and 13 bits for size. - - ====== ================================== - bits meaning - ====== ================================== - 31-30 00 - no parameters: uses _IO macro - 10 - read: _IOR - 01 - write: _IOW - 11 - read/write: _IOWR - - 29-16 size of arguments - - 15-8 ascii character supposedly - unique to each driver - - 7-0 function # - ====== ================================== - - -So for example 0x82187201 is a read with arg length of 0x218, -character 'r' function 1. Grepping the source reveals this is:: - - #define VFAT_IOCTL_READDIR_BOTH _IOR('r', 1, struct dirent [2]) diff --git a/Documentation/ioctl/ioctl-number.rst b/Documentation/ioctl/ioctl-number.rst deleted file mode 100644 index bef79cd4c6b4..000000000000 --- a/Documentation/ioctl/ioctl-number.rst +++ /dev/null @@ -1,362 +0,0 @@ -============= -Ioctl Numbers -============= - -19 October 1999 - -Michael Elizabeth Chastain - - -If you are adding new ioctl's to the kernel, you should use the _IO -macros defined in : - - ====== == ============================================ - _IO an ioctl with no parameters - _IOW an ioctl with write parameters (copy_from_user) - _IOR an ioctl with read parameters (copy_to_user) - _IOWR an ioctl with both write and read parameters. - ====== == ============================================ - -'Write' and 'read' are from the user's point of view, just like the -system calls 'write' and 'read'. For example, a SET_FOO ioctl would -be _IOW, although the kernel would actually read data from user space; -a GET_FOO ioctl would be _IOR, although the kernel would actually write -data to user space. - -The first argument to _IO, _IOW, _IOR, or _IOWR is an identifying letter -or number from the table below. Because of the large number of drivers, -many drivers share a partial letter with other drivers. - -If you are writing a driver for a new device and need a letter, pick an -unused block with enough room for expansion: 32 to 256 ioctl commands. -You can register the block by patching this file and submitting the -patch to Linus Torvalds. Or you can e-mail me at and -I'll register one for you. - -The second argument to _IO, _IOW, _IOR, or _IOWR is a sequence number -to distinguish ioctls from each other. The third argument to _IOW, -_IOR, or _IOWR is the type of the data going into the kernel or coming -out of the kernel (e.g. 'int' or 'struct foo'). NOTE! Do NOT use -sizeof(arg) as the third argument as this results in your ioctl thinking -it passes an argument of type size_t. - -Some devices use their major number as the identifier; this is OK, as -long as it is unique. Some devices are irregular and don't follow any -convention at all. - -Following this convention is good because: - -(1) Keeping the ioctl's globally unique helps error checking: - if a program calls an ioctl on the wrong device, it will get an - error rather than some unexpected behaviour. - -(2) The 'strace' build procedure automatically finds ioctl numbers - defined with _IO, _IOW, _IOR, or _IOWR. - -(3) 'strace' can decode numbers back into useful names when the - numbers are unique. - -(4) People looking for ioctls can grep for them more easily when - this convention is used to define the ioctl numbers. - -(5) When following the convention, the driver code can use generic - code to copy the parameters between user and kernel space. - -This table lists ioctls visible from user land for Linux/x86. It contains -most drivers up to 2.6.31, but I know I am missing some. There has been -no attempt to list non-X86 architectures or ioctls from drivers/staging/. - -==== ===== ======================================================= ================================================================ -Code Seq# Include File Comments - (hex) -==== ===== ======================================================= ================================================================ -0x00 00-1F linux/fs.h conflict! -0x00 00-1F scsi/scsi_ioctl.h conflict! -0x00 00-1F linux/fb.h conflict! -0x00 00-1F linux/wavefront.h conflict! -0x02 all linux/fd.h -0x03 all linux/hdreg.h -0x04 D2-DC linux/umsdos_fs.h Dead since 2.6.11, but don't reuse these. -0x06 all linux/lp.h -0x09 all linux/raid/md_u.h -0x10 00-0F drivers/char/s390/vmcp.h -0x10 10-1F arch/s390/include/uapi/sclp_ctl.h -0x10 20-2F arch/s390/include/uapi/asm/hypfs.h -0x12 all linux/fs.h - linux/blkpg.h -0x1b all InfiniBand Subsystem - -0x20 all drivers/cdrom/cm206.h -0x22 all scsi/sg.h -'!' 00-1F uapi/linux/seccomp.h -'#' 00-3F IEEE 1394 Subsystem - Block for the entire subsystem -'$' 00-0F linux/perf_counter.h, linux/perf_event.h -'%' 00-0F include/uapi/linux/stm.h System Trace Module subsystem - -'&' 00-07 drivers/firewire/nosy-user.h -'1' 00-1F linux/timepps.h PPS kit from Ulrich Windl - -'2' 01-04 linux/i2o.h -'3' 00-0F drivers/s390/char/raw3270.h conflict! -'3' 00-1F linux/suspend_ioctls.h, conflict! - kernel/power/user.c -'8' all SNP8023 advanced NIC card - -';' 64-7F linux/vfio.h -'@' 00-0F linux/radeonfb.h conflict! -'@' 00-0F drivers/video/aty/aty128fb.c conflict! -'A' 00-1F linux/apm_bios.h conflict! -'A' 00-0F linux/agpgart.h, conflict! - drivers/char/agp/compat_ioctl.h -'A' 00-7F sound/asound.h conflict! -'B' 00-1F linux/cciss_ioctl.h conflict! -'B' 00-0F include/linux/pmu.h conflict! -'B' C0-FF advanced bbus -'C' all linux/soundcard.h conflict! -'C' 01-2F linux/capi.h conflict! -'C' F0-FF drivers/net/wan/cosa.h conflict! -'D' all arch/s390/include/asm/dasd.h -'D' 40-5F drivers/scsi/dpt/dtpi_ioctl.h -'D' 05 drivers/scsi/pmcraid.h -'E' all linux/input.h conflict! -'E' 00-0F xen/evtchn.h conflict! -'F' all linux/fb.h conflict! -'F' 01-02 drivers/scsi/pmcraid.h conflict! -'F' 20 drivers/video/fsl-diu-fb.h conflict! -'F' 20 drivers/video/intelfb/intelfb.h conflict! -'F' 20 linux/ivtvfb.h conflict! -'F' 20 linux/matroxfb.h conflict! -'F' 20 drivers/video/aty/atyfb_base.c conflict! -'F' 00-0F video/da8xx-fb.h conflict! -'F' 80-8F linux/arcfb.h conflict! -'F' DD video/sstfb.h conflict! -'G' 00-3F drivers/misc/sgi-gru/grulib.h conflict! -'G' 00-0F linux/gigaset_dev.h conflict! -'H' 00-7F linux/hiddev.h conflict! -'H' 00-0F linux/hidraw.h conflict! -'H' 01 linux/mei.h conflict! -'H' 02 linux/mei.h conflict! -'H' 03 linux/mei.h conflict! -'H' 00-0F sound/asound.h conflict! -'H' 20-40 sound/asound_fm.h conflict! -'H' 80-8F sound/sfnt_info.h conflict! -'H' 10-8F sound/emu10k1.h conflict! -'H' 10-1F sound/sb16_csp.h conflict! -'H' 10-1F sound/hda_hwdep.h conflict! -'H' 40-4F sound/hdspm.h conflict! -'H' 40-4F sound/hdsp.h conflict! -'H' 90 sound/usb/usx2y/usb_stream.h -'H' A0 uapi/linux/usb/cdc-wdm.h -'H' C0-F0 net/bluetooth/hci.h conflict! -'H' C0-DF net/bluetooth/hidp/hidp.h conflict! -'H' C0-DF net/bluetooth/cmtp/cmtp.h conflict! -'H' C0-DF net/bluetooth/bnep/bnep.h conflict! -'H' F1 linux/hid-roccat.h -'H' F8-FA sound/firewire.h -'I' all linux/isdn.h conflict! -'I' 00-0F drivers/isdn/divert/isdn_divert.h conflict! -'I' 40-4F linux/mISDNif.h conflict! -'J' 00-1F drivers/scsi/gdth_ioctl.h -'K' all linux/kd.h -'L' 00-1F linux/loop.h conflict! -'L' 10-1F drivers/scsi/mpt3sas/mpt3sas_ctl.h conflict! -'L' 20-2F linux/lightnvm.h -'L' E0-FF linux/ppdd.h encrypted disk device driver - -'M' all linux/soundcard.h conflict! -'M' 01-16 mtd/mtd-abi.h conflict! - and drivers/mtd/mtdchar.c -'M' 01-03 drivers/scsi/megaraid/megaraid_sas.h -'M' 00-0F drivers/video/fsl-diu-fb.h conflict! -'N' 00-1F drivers/usb/scanner.h -'N' 40-7F drivers/block/nvme.c -'O' 00-06 mtd/ubi-user.h UBI -'P' all linux/soundcard.h conflict! -'P' 60-6F sound/sscape_ioctl.h conflict! -'P' 00-0F drivers/usb/class/usblp.c conflict! -'P' 01-09 drivers/misc/pci_endpoint_test.c conflict! -'Q' all linux/soundcard.h -'R' 00-1F linux/random.h conflict! -'R' 01 linux/rfkill.h conflict! -'R' C0-DF net/bluetooth/rfcomm.h -'S' all linux/cdrom.h conflict! -'S' 80-81 scsi/scsi_ioctl.h conflict! -'S' 82-FF scsi/scsi.h conflict! -'S' 00-7F sound/asequencer.h conflict! -'T' all linux/soundcard.h conflict! -'T' 00-AF sound/asound.h conflict! -'T' all arch/x86/include/asm/ioctls.h conflict! -'T' C0-DF linux/if_tun.h conflict! -'U' all sound/asound.h conflict! -'U' 00-CF linux/uinput.h conflict! -'U' 00-EF linux/usbdevice_fs.h -'U' C0-CF drivers/bluetooth/hci_uart.h -'V' all linux/vt.h conflict! -'V' all linux/videodev2.h conflict! -'V' C0 linux/ivtvfb.h conflict! -'V' C0 linux/ivtv.h conflict! -'V' C0 media/davinci/vpfe_capture.h conflict! -'V' C0 media/si4713.h conflict! -'W' 00-1F linux/watchdog.h conflict! -'W' 00-1F linux/wanrouter.h conflict! (pre 3.9) -'W' 00-3F sound/asound.h conflict! -'W' 40-5F drivers/pci/switch/switchtec.c -'X' all fs/xfs/xfs_fs.h, conflict! - fs/xfs/linux-2.6/xfs_ioctl32.h, - include/linux/falloc.h, - linux/fs.h, -'X' all fs/ocfs2/ocfs_fs.h conflict! -'X' 01 linux/pktcdvd.h conflict! -'Y' all linux/cyclades.h -'Z' 14-15 drivers/message/fusion/mptctl.h -'[' 00-3F linux/usb/tmc.h USB Test and Measurement Devices - -'a' all linux/atm*.h, linux/sonet.h ATM on linux - -'a' 00-0F drivers/crypto/qat/qat_common/adf_cfg_common.h conflict! qat driver -'b' 00-FF conflict! bit3 vme host bridge - -'c' all linux/cm4000_cs.h conflict! -'c' 00-7F linux/comstats.h conflict! -'c' 00-7F linux/coda.h conflict! -'c' 00-1F linux/chio.h conflict! -'c' 80-9F arch/s390/include/asm/chsc.h conflict! -'c' A0-AF arch/x86/include/asm/msr.h conflict! -'d' 00-FF linux/char/drm/drm.h conflict! -'d' 02-40 pcmcia/ds.h conflict! -'d' F0-FF linux/digi1.h -'e' all linux/digi1.h conflict! -'f' 00-1F linux/ext2_fs.h conflict! -'f' 00-1F linux/ext3_fs.h conflict! -'f' 00-0F fs/jfs/jfs_dinode.h conflict! -'f' 00-0F fs/ext4/ext4.h conflict! -'f' 00-0F linux/fs.h conflict! -'f' 00-0F fs/ocfs2/ocfs2_fs.h conflict! -'f' 81-8F linux/fsverity.h -'g' 00-0F linux/usb/gadgetfs.h -'g' 20-2F linux/usb/g_printer.h -'h' 00-7F conflict! Charon filesystem - -'h' 00-1F linux/hpet.h conflict! -'h' 80-8F fs/hfsplus/ioctl.c -'i' 00-3F linux/i2o-dev.h conflict! -'i' 0B-1F linux/ipmi.h conflict! -'i' 80-8F linux/i8k.h -'j' 00-3F linux/joystick.h -'k' 00-0F linux/spi/spidev.h conflict! -'k' 00-05 video/kyro.h conflict! -'k' 10-17 linux/hsi/hsi_char.h HSI character device -'l' 00-3F linux/tcfs_fs.h transparent cryptographic file system - -'l' 40-7F linux/udf_fs_i.h in development: - -'m' 00-09 linux/mmtimer.h conflict! -'m' all linux/mtio.h conflict! -'m' all linux/soundcard.h conflict! -'m' all linux/synclink.h conflict! -'m' 00-19 drivers/message/fusion/mptctl.h conflict! -'m' 00 drivers/scsi/megaraid/megaraid_ioctl.h conflict! -'n' 00-7F linux/ncp_fs.h and fs/ncpfs/ioctl.c -'n' 80-8F uapi/linux/nilfs2_api.h NILFS2 -'n' E0-FF linux/matroxfb.h matroxfb -'o' 00-1F fs/ocfs2/ocfs2_fs.h OCFS2 -'o' 00-03 mtd/ubi-user.h conflict! (OCFS2 and UBI overlaps) -'o' 40-41 mtd/ubi-user.h UBI -'o' 01-A1 `linux/dvb/*.h` DVB -'p' 00-0F linux/phantom.h conflict! (OpenHaptics needs this) -'p' 00-1F linux/rtc.h conflict! -'p' 00-3F linux/mc146818rtc.h conflict! -'p' 40-7F linux/nvram.h -'p' 80-9F linux/ppdev.h user-space parport - -'p' A1-A5 linux/pps.h LinuxPPS - -'q' 00-1F linux/serio.h -'q' 80-FF linux/telephony.h Internet PhoneJACK, Internet LineJACK - linux/ixjuser.h -'r' 00-1F linux/msdos_fs.h and fs/fat/dir.c -'s' all linux/cdk.h -'t' 00-7F linux/ppp-ioctl.h -'t' 80-8F linux/isdn_ppp.h -'t' 90-91 linux/toshiba.h toshiba and toshiba_acpi SMM -'u' 00-1F linux/smb_fs.h gone -'u' 20-3F linux/uvcvideo.h USB video class host driver -'u' 40-4f linux/udmabuf.h userspace dma-buf misc device -'v' 00-1F linux/ext2_fs.h conflict! -'v' 00-1F linux/fs.h conflict! -'v' 00-0F linux/sonypi.h conflict! -'v' 00-0F media/v4l2-subdev.h conflict! -'v' C0-FF linux/meye.h conflict! -'w' all CERN SCI driver -'y' 00-1F packet based user level communications - -'z' 00-3F CAN bus card conflict! - -'z' 40-7F CAN bus card conflict! - -'z' 10-4F drivers/s390/crypto/zcrypt_api.h conflict! -'|' 00-7F linux/media.h -0x80 00-1F linux/fb.h -0x89 00-06 arch/x86/include/asm/sockios.h -0x89 0B-DF linux/sockios.h -0x89 E0-EF linux/sockios.h SIOCPROTOPRIVATE range -0x89 E0-EF linux/dn.h PROTOPRIVATE range -0x89 F0-FF linux/sockios.h SIOCDEVPRIVATE range -0x8B all linux/wireless.h -0x8C 00-3F WiNRADiO driver - -0x90 00 drivers/cdrom/sbpcd.h -0x92 00-0F drivers/usb/mon/mon_bin.c -0x93 60-7F linux/auto_fs.h -0x94 all fs/btrfs/ioctl.h Btrfs filesystem - and linux/fs.h some lifted to vfs/generic -0x97 00-7F fs/ceph/ioctl.h Ceph file system -0x99 00-0F 537-Addinboard driver - -0xA0 all linux/sdp/sdp.h Industrial Device Project - -0xA1 0 linux/vtpm_proxy.h TPM Emulator Proxy Driver -0xA3 80-8F Port ACL in development: - -0xA3 90-9F linux/dtlk.h -0xA4 00-1F uapi/linux/tee.h Generic TEE subsystem -0xAA 00-3F linux/uapi/linux/userfaultfd.h -0xAB 00-1F linux/nbd.h -0xAC 00-1F linux/raw.h -0xAD 00 Netfilter device in development: - -0xAE all linux/kvm.h Kernel-based Virtual Machine - -0xAF 00-1F linux/fsl_hypervisor.h Freescale hypervisor -0xB0 all RATIO devices in development: - -0xB1 00-1F PPPoX - -0xB3 00 linux/mmc/ioctl.h -0xB4 00-0F linux/gpio.h -0xB5 00-0F uapi/linux/rpmsg.h -0xB6 all linux/fpga-dfl.h -0xC0 00-0F linux/usb/iowarrior.h -0xCA 00-0F uapi/misc/cxl.h -0xCA 10-2F uapi/misc/ocxl.h -0xCA 80-BF uapi/scsi/cxlflash_ioctl.h -0xCB 00-1F CBM serial IEC bus in development: - -0xCC 00-0F drivers/misc/ibmvmc.h pseries VMC driver -0xCD 01 linux/reiserfs_fs.h -0xCF 02 fs/cifs/ioctl.c -0xDB 00-0F drivers/char/mwave/mwavepub.h -0xDD 00-3F ZFCP device driver see drivers/s390/scsi/ - -0xE5 00-3F linux/fuse.h -0xEC 00-01 drivers/platform/chrome/cros_ec_dev.h ChromeOS EC driver -0xF3 00-3F drivers/usb/misc/sisusbvga/sisusb.h sisfb (in development) - -0xF4 00-1F video/mbxfb.h mbxfb - -0xF6 all LTTng Linux Trace Toolkit Next Generation - -0xFD all linux/dm-ioctl.h -0xFE all linux/isst_if.h -==== ===== ======================================================= ================================================================ diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst index ad494da40009..e983488b48b1 100644 --- a/Documentation/userspace-api/index.rst +++ b/Documentation/userspace-api/index.rst @@ -21,6 +21,7 @@ place where this information is gathered. unshare spec_ctrl accelerators/ocxl + ioctl/index .. only:: subproject and html diff --git a/Documentation/userspace-api/ioctl/cdrom.rst b/Documentation/userspace-api/ioctl/cdrom.rst new file mode 100644 index 000000000000..3b4c0506de46 --- /dev/null +++ b/Documentation/userspace-api/ioctl/cdrom.rst @@ -0,0 +1,1233 @@ +============================ +Summary of CDROM ioctl calls +============================ + +- Edward A. Falk + +November, 2004 + +This document attempts to describe the ioctl(2) calls supported by +the CDROM layer. These are by-and-large implemented (as of Linux 2.6) +in drivers/cdrom/cdrom.c and drivers/block/scsi_ioctl.c + +ioctl values are listed in . As of this writing, they +are as follows: + + ====================== =============================================== + CDROMPAUSE Pause Audio Operation + CDROMRESUME Resume paused Audio Operation + CDROMPLAYMSF Play Audio MSF (struct cdrom_msf) + CDROMPLAYTRKIND Play Audio Track/index (struct cdrom_ti) + CDROMREADTOCHDR Read TOC header (struct cdrom_tochdr) + CDROMREADTOCENTRY Read TOC entry (struct cdrom_tocentry) + CDROMSTOP Stop the cdrom drive + CDROMSTART Start the cdrom drive + CDROMEJECT Ejects the cdrom media + CDROMVOLCTRL Control output volume (struct cdrom_volctrl) + CDROMSUBCHNL Read subchannel data (struct cdrom_subchnl) + CDROMREADMODE2 Read CDROM mode 2 data (2336 Bytes) + (struct cdrom_read) + CDROMREADMODE1 Read CDROM mode 1 data (2048 Bytes) + (struct cdrom_read) + CDROMREADAUDIO (struct cdrom_read_audio) + CDROMEJECT_SW enable(1)/disable(0) auto-ejecting + CDROMMULTISESSION Obtain the start-of-last-session + address of multi session disks + (struct cdrom_multisession) + CDROM_GET_MCN Obtain the "Universal Product Code" + if available (struct cdrom_mcn) + CDROM_GET_UPC Deprecated, use CDROM_GET_MCN instead. + CDROMRESET hard-reset the drive + CDROMVOLREAD Get the drive's volume setting + (struct cdrom_volctrl) + CDROMREADRAW read data in raw mode (2352 Bytes) + (struct cdrom_read) + CDROMREADCOOKED read data in cooked mode + CDROMSEEK seek msf address + CDROMPLAYBLK scsi-cd only, (struct cdrom_blk) + CDROMREADALL read all 2646 bytes + CDROMGETSPINDOWN return 4-bit spindown value + CDROMSETSPINDOWN set 4-bit spindown value + CDROMCLOSETRAY pendant of CDROMEJECT + CDROM_SET_OPTIONS Set behavior options + CDROM_CLEAR_OPTIONS Clear behavior options + CDROM_SELECT_SPEED Set the CD-ROM speed + CDROM_SELECT_DISC Select disc (for juke-boxes) + CDROM_MEDIA_CHANGED Check is media changed + CDROM_DRIVE_STATUS Get tray position, etc. + CDROM_DISC_STATUS Get disc type, etc. + CDROM_CHANGER_NSLOTS Get number of slots + CDROM_LOCKDOOR lock or unlock door + CDROM_DEBUG Turn debug messages on/off + CDROM_GET_CAPABILITY get capabilities + CDROMAUDIOBUFSIZ set the audio buffer size + DVD_READ_STRUCT Read structure + DVD_WRITE_STRUCT Write structure + DVD_AUTH Authentication + CDROM_SEND_PACKET send a packet to the drive + CDROM_NEXT_WRITABLE get next writable block + CDROM_LAST_WRITTEN get last block written on disc + ====================== =============================================== + + +The information that follows was determined from reading kernel source +code. It is likely that some corrections will be made over time. + +------------------------------------------------------------------------------ + +General: + + Unless otherwise specified, all ioctl calls return 0 on success + and -1 with errno set to an appropriate value on error. (Some + ioctls return non-negative data values.) + + Unless otherwise specified, all ioctl calls return -1 and set + errno to EFAULT on a failed attempt to copy data to or from user + address space. + + Individual drivers may return error codes not listed here. + + Unless otherwise specified, all data structures and constants + are defined in + +------------------------------------------------------------------------------ + + +CDROMPAUSE + Pause Audio Operation + + + usage:: + + ioctl(fd, CDROMPAUSE, 0); + + + inputs: + none + + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + +CDROMRESUME + Resume paused Audio Operation + + + usage:: + + ioctl(fd, CDROMRESUME, 0); + + + inputs: + none + + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + +CDROMPLAYMSF + Play Audio MSF + + (struct cdrom_msf) + + + usage:: + + struct cdrom_msf msf; + + ioctl(fd, CDROMPLAYMSF, &msf); + + inputs: + cdrom_msf structure, describing a segment of music to play + + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + notes: + - MSF stands for minutes-seconds-frames + - LBA stands for logical block address + - Segment is described as start and end times, where each time + is described as minutes:seconds:frames. + A frame is 1/75 of a second. + + +CDROMPLAYTRKIND + Play Audio Track/index + + (struct cdrom_ti) + + + usage:: + + struct cdrom_ti ti; + + ioctl(fd, CDROMPLAYTRKIND, &ti); + + inputs: + cdrom_ti structure, describing a segment of music to play + + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + notes: + - Segment is described as start and end times, where each time + is described as a track and an index. + + + +CDROMREADTOCHDR + Read TOC header + + (struct cdrom_tochdr) + + + usage:: + + cdrom_tochdr header; + + ioctl(fd, CDROMREADTOCHDR, &header); + + inputs: + cdrom_tochdr structure + + + outputs: + cdrom_tochdr structure + + + error return: + - ENOSYS cd drive not audio-capable. + + + +CDROMREADTOCENTRY + Read TOC entry + + (struct cdrom_tocentry) + + + usage:: + + struct cdrom_tocentry entry; + + ioctl(fd, CDROMREADTOCENTRY, &entry); + + inputs: + cdrom_tocentry structure + + + outputs: + cdrom_tocentry structure + + + error return: + - ENOSYS cd drive not audio-capable. + - EINVAL entry.cdte_format not CDROM_MSF or CDROM_LBA + - EINVAL requested track out of bounds + - EIO I/O error reading TOC + + notes: + - TOC stands for Table Of Contents + - MSF stands for minutes-seconds-frames + - LBA stands for logical block address + + + +CDROMSTOP + Stop the cdrom drive + + + usage:: + + ioctl(fd, CDROMSTOP, 0); + + + inputs: + none + + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + notes: + - Exact interpretation of this ioctl depends on the device, + but most seem to spin the drive down. + + +CDROMSTART + Start the cdrom drive + + + usage:: + + ioctl(fd, CDROMSTART, 0); + + + inputs: + none + + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + notes: + - Exact interpretation of this ioctl depends on the device, + but most seem to spin the drive up and/or close the tray. + Other devices ignore the ioctl completely. + + +CDROMEJECT + - Ejects the cdrom media + + + usage:: + + ioctl(fd, CDROMEJECT, 0); + + + inputs: + none + + + outputs: + none + + + error returns: + - ENOSYS cd drive not capable of ejecting + - EBUSY other processes are accessing drive, or door is locked + + notes: + - See CDROM_LOCKDOOR, below. + + + + +CDROMCLOSETRAY + pendant of CDROMEJECT + + + usage:: + + ioctl(fd, CDROMCLOSETRAY, 0); + + + inputs: + none + + + outputs: + none + + + error returns: + - ENOSYS cd drive not capable of closing the tray + - EBUSY other processes are accessing drive, or door is locked + + notes: + - See CDROM_LOCKDOOR, below. + + + + +CDROMVOLCTRL + Control output volume (struct cdrom_volctrl) + + + usage:: + + struct cdrom_volctrl volume; + + ioctl(fd, CDROMVOLCTRL, &volume); + + inputs: + cdrom_volctrl structure containing volumes for up to 4 + channels. + + outputs: + none + + + error return: + - ENOSYS cd drive not audio-capable. + + + +CDROMVOLREAD + Get the drive's volume setting + + (struct cdrom_volctrl) + + + usage:: + + struct cdrom_volctrl volume; + + ioctl(fd, CDROMVOLREAD, &volume); + + inputs: + none + + + outputs: + The current volume settings. + + + error return: + - ENOSYS cd drive not audio-capable. + + + +CDROMSUBCHNL + Read subchannel data + + (struct cdrom_subchnl) + + + usage:: + + struct cdrom_subchnl q; + + ioctl(fd, CDROMSUBCHNL, &q); + + inputs: + cdrom_subchnl structure + + + outputs: + cdrom_subchnl structure + + + error return: + - ENOSYS cd drive not audio-capable. + - EINVAL format not CDROM_MSF or CDROM_LBA + + notes: + - Format is converted to CDROM_MSF or CDROM_LBA + as per user request on return + + + +CDROMREADRAW + read data in raw mode (2352 Bytes) + + (struct cdrom_read) + + usage:: + + union { + + struct cdrom_msf msf; /* input */ + char buffer[CD_FRAMESIZE_RAW]; /* return */ + } arg; + ioctl(fd, CDROMREADRAW, &arg); + + inputs: + cdrom_msf structure indicating an address to read. + + Only the start values are significant. + + outputs: + Data written to address provided by user. + + + error return: + - EINVAL address less than 0, or msf less than 0:2:0 + - ENOMEM out of memory + + notes: + - As of 2.6.8.1, comments in indicate that this + ioctl accepts a cdrom_read structure, but actual source code + reads a cdrom_msf structure and writes a buffer of data to + the same address. + + - MSF values are converted to LBA values via this formula:: + + lba = (((m * CD_SECS) + s) * CD_FRAMES + f) - CD_MSF_OFFSET; + + + + +CDROMREADMODE1 + Read CDROM mode 1 data (2048 Bytes) + + (struct cdrom_read) + + notes: + Identical to CDROMREADRAW except that block size is + CD_FRAMESIZE (2048) bytes + + + +CDROMREADMODE2 + Read CDROM mode 2 data (2336 Bytes) + + (struct cdrom_read) + + notes: + Identical to CDROMREADRAW except that block size is + CD_FRAMESIZE_RAW0 (2336) bytes + + + +CDROMREADAUDIO + (struct cdrom_read_audio) + + usage:: + + struct cdrom_read_audio ra; + + ioctl(fd, CDROMREADAUDIO, &ra); + + inputs: + cdrom_read_audio structure containing read start + point and length + + outputs: + audio data, returned to buffer indicated by ra + + + error return: + - EINVAL format not CDROM_MSF or CDROM_LBA + - EINVAL nframes not in range [1 75] + - ENXIO drive has no queue (probably means invalid fd) + - ENOMEM out of memory + + +CDROMEJECT_SW + enable(1)/disable(0) auto-ejecting + + + usage:: + + int val; + + ioctl(fd, CDROMEJECT_SW, val); + + inputs: + Flag specifying auto-eject flag. + + + outputs: + none + + + error return: + - ENOSYS Drive is not capable of ejecting. + - EBUSY Door is locked + + + + +CDROMMULTISESSION + Obtain the start-of-last-session address of multi session disks + + (struct cdrom_multisession) + + usage:: + + struct cdrom_multisession ms_info; + + ioctl(fd, CDROMMULTISESSION, &ms_info); + + inputs: + cdrom_multisession structure containing desired + + format. + + outputs: + cdrom_multisession structure is filled with last_session + information. + + error return: + - EINVAL format not CDROM_MSF or CDROM_LBA + + +CDROM_GET_MCN + Obtain the "Universal Product Code" + if available + + (struct cdrom_mcn) + + + usage:: + + struct cdrom_mcn mcn; + + ioctl(fd, CDROM_GET_MCN, &mcn); + + inputs: + none + + + outputs: + Universal Product Code + + + error return: + - ENOSYS Drive is not capable of reading MCN data. + + notes: + - Source code comments state:: + + The following function is implemented, although very few + audio discs give Universal Product Code information, which + should just be the Medium Catalog Number on the box. Note, + that the way the code is written on the CD is /not/ uniform + across all discs! + + + + +CDROM_GET_UPC + CDROM_GET_MCN (deprecated) + + + Not implemented, as of 2.6.8.1 + + + +CDROMRESET + hard-reset the drive + + + usage:: + + ioctl(fd, CDROMRESET, 0); + + + inputs: + none + + + outputs: + none + + + error return: + - EACCES Access denied: requires CAP_SYS_ADMIN + - ENOSYS Drive is not capable of resetting. + + + + +CDROMREADCOOKED + read data in cooked mode + + + usage:: + + u8 buffer[CD_FRAMESIZE] + + ioctl(fd, CDROMREADCOOKED, buffer); + + inputs: + none + + + outputs: + 2048 bytes of data, "cooked" mode. + + + notes: + Not implemented on all drives. + + + + + +CDROMREADALL + read all 2646 bytes + + + Same as CDROMREADCOOKED, but reads 2646 bytes. + + + +CDROMSEEK + seek msf address + + + usage:: + + struct cdrom_msf msf; + + ioctl(fd, CDROMSEEK, &msf); + + inputs: + MSF address to seek to. + + + outputs: + none + + + + +CDROMPLAYBLK + scsi-cd only + + (struct cdrom_blk) + + + usage:: + + struct cdrom_blk blk; + + ioctl(fd, CDROMPLAYBLK, &blk); + + inputs: + Region to play + + + outputs: + none + + + + +CDROMGETSPINDOWN + usage:: + + char spindown; + + ioctl(fd, CDROMGETSPINDOWN, &spindown); + + inputs: + none + + + outputs: + The value of the current 4-bit spindown value. + + + + + +CDROMSETSPINDOWN + usage:: + + char spindown + + ioctl(fd, CDROMSETSPINDOWN, &spindown); + + inputs: + 4-bit value used to control spindown (TODO: more detail here) + + + outputs: + none + + + + + + +CDROM_SET_OPTIONS + Set behavior options + + + usage:: + + int options; + + ioctl(fd, CDROM_SET_OPTIONS, options); + + inputs: + New values for drive options. The logical 'or' of: + + ============== ================================== + CDO_AUTO_CLOSE close tray on first open(2) + CDO_AUTO_EJECT open tray on last release + CDO_USE_FFLAGS use O_NONBLOCK information on open + CDO_LOCK lock tray on open files + CDO_CHECK_TYPE check type on open for data + ============== ================================== + + outputs: + Returns the resulting options settings in the + ioctl return value. Returns -1 on error. + + error return: + - ENOSYS selected option(s) not supported by drive. + + + + +CDROM_CLEAR_OPTIONS + Clear behavior options + + + Same as CDROM_SET_OPTIONS, except that selected options are + turned off. + + + +CDROM_SELECT_SPEED + Set the CD-ROM speed + + + usage:: + + int speed; + + ioctl(fd, CDROM_SELECT_SPEED, speed); + + inputs: + New drive speed. + + + outputs: + none + + + error return: + - ENOSYS speed selection not supported by drive. + + + +CDROM_SELECT_DISC + Select disc (for juke-boxes) + + + usage:: + + int disk; + + ioctl(fd, CDROM_SELECT_DISC, disk); + + inputs: + Disk to load into drive. + + + outputs: + none + + + error return: + - EINVAL Disk number beyond capacity of drive + + + +CDROM_MEDIA_CHANGED + Check is media changed + + + usage:: + + int slot; + + ioctl(fd, CDROM_MEDIA_CHANGED, slot); + + inputs: + Slot number to be tested, always zero except for jukeboxes. + + May also be special values CDSL_NONE or CDSL_CURRENT + + outputs: + Ioctl return value is 0 or 1 depending on whether the media + + has been changed, or -1 on error. + + error returns: + - ENOSYS Drive can't detect media change + - EINVAL Slot number beyond capacity of drive + - ENOMEM Out of memory + + + +CDROM_DRIVE_STATUS + Get tray position, etc. + + + usage:: + + int slot; + + ioctl(fd, CDROM_DRIVE_STATUS, slot); + + inputs: + Slot number to be tested, always zero except for jukeboxes. + + May also be special values CDSL_NONE or CDSL_CURRENT + + outputs: + Ioctl return value will be one of the following values + + from : + + =================== ========================== + CDS_NO_INFO Information not available. + CDS_NO_DISC + CDS_TRAY_OPEN + CDS_DRIVE_NOT_READY + CDS_DISC_OK + -1 error + =================== ========================== + + error returns: + - ENOSYS Drive can't detect drive status + - EINVAL Slot number beyond capacity of drive + - ENOMEM Out of memory + + + + +CDROM_DISC_STATUS + Get disc type, etc. + + + usage:: + + ioctl(fd, CDROM_DISC_STATUS, 0); + + + inputs: + none + + + outputs: + Ioctl return value will be one of the following values + + from : + + - CDS_NO_INFO + - CDS_AUDIO + - CDS_MIXED + - CDS_XA_2_2 + - CDS_XA_2_1 + - CDS_DATA_1 + + error returns: + none at present + + notes: + - Source code comments state:: + + + Ok, this is where problems start. The current interface for + the CDROM_DISC_STATUS ioctl is flawed. It makes the false + assumption that CDs are all CDS_DATA_1 or all CDS_AUDIO, etc. + Unfortunately, while this is often the case, it is also + very common for CDs to have some tracks with data, and some + tracks with audio. Just because I feel like it, I declare + the following to be the best way to cope. If the CD has + ANY data tracks on it, it will be returned as a data CD. + If it has any XA tracks, I will return it as that. Now I + could simplify this interface by combining these returns with + the above, but this more clearly demonstrates the problem + with the current interface. Too bad this wasn't designed + to use bitmasks... -Erik + + Well, now we have the option CDS_MIXED: a mixed-type CD. + User level programmers might feel the ioctl is not very + useful. + ---david + + + + +CDROM_CHANGER_NSLOTS + Get number of slots + + + usage:: + + ioctl(fd, CDROM_CHANGER_NSLOTS, 0); + + + inputs: + none + + + outputs: + The ioctl return value will be the number of slots in a + CD changer. Typically 1 for non-multi-disk devices. + + error returns: + none + + + +CDROM_LOCKDOOR + lock or unlock door + + + usage:: + + int lock; + + ioctl(fd, CDROM_LOCKDOOR, lock); + + inputs: + Door lock flag, 1=lock, 0=unlock + + + outputs: + none + + + error returns: + - EDRIVE_CANT_DO_THIS + + Door lock function not supported. + - EBUSY + + Attempt to unlock when multiple users + have the drive open and not CAP_SYS_ADMIN + + notes: + As of 2.6.8.1, the lock flag is a global lock, meaning that + all CD drives will be locked or unlocked together. This is + probably a bug. + + The EDRIVE_CANT_DO_THIS value is defined in + and is currently (2.6.8.1) the same as EOPNOTSUPP + + + +CDROM_DEBUG + Turn debug messages on/off + + + usage:: + + int debug; + + ioctl(fd, CDROM_DEBUG, debug); + + inputs: + Cdrom debug flag, 0=disable, 1=enable + + + outputs: + The ioctl return value will be the new debug flag. + + + error return: + - EACCES Access denied: requires CAP_SYS_ADMIN + + + +CDROM_GET_CAPABILITY + get capabilities + + + usage:: + + ioctl(fd, CDROM_GET_CAPABILITY, 0); + + + inputs: + none + + + outputs: + The ioctl return value is the current device capability + flags. See CDC_CLOSE_TRAY, CDC_OPEN_TRAY, etc. + + + +CDROMAUDIOBUFSIZ + set the audio buffer size + + + usage:: + + int arg; + + ioctl(fd, CDROMAUDIOBUFSIZ, val); + + inputs: + New audio buffer size + + + outputs: + The ioctl return value is the new audio buffer size, or -1 + on error. + + error return: + - ENOSYS Not supported by this driver. + + notes: + Not supported by all drivers. + + + + +DVD_READ_STRUCT Read structure + + usage:: + + dvd_struct s; + + ioctl(fd, DVD_READ_STRUCT, &s); + + inputs: + dvd_struct structure, containing: + + =================== ========================================== + type specifies the information desired, one of + DVD_STRUCT_PHYSICAL, DVD_STRUCT_COPYRIGHT, + DVD_STRUCT_DISCKEY, DVD_STRUCT_BCA, + DVD_STRUCT_MANUFACT + physical.layer_num desired layer, indexed from 0 + copyright.layer_num desired layer, indexed from 0 + disckey.agid + =================== ========================================== + + outputs: + dvd_struct structure, containing: + + =================== ================================ + physical for type == DVD_STRUCT_PHYSICAL + copyright for type == DVD_STRUCT_COPYRIGHT + disckey.value for type == DVD_STRUCT_DISCKEY + bca.{len,value} for type == DVD_STRUCT_BCA + manufact.{len,valu} for type == DVD_STRUCT_MANUFACT + =================== ================================ + + error returns: + - EINVAL physical.layer_num exceeds number of layers + - EIO Received invalid response from drive + + + +DVD_WRITE_STRUCT Write structure + + Not implemented, as of 2.6.8.1 + + + +DVD_AUTH Authentication + + usage:: + + dvd_authinfo ai; + + ioctl(fd, DVD_AUTH, &ai); + + inputs: + dvd_authinfo structure. See + + + outputs: + dvd_authinfo structure. + + + error return: + - ENOTTY ai.type not recognized. + + + +CDROM_SEND_PACKET + send a packet to the drive + + + usage:: + + struct cdrom_generic_command cgc; + + ioctl(fd, CDROM_SEND_PACKET, &cgc); + + inputs: + cdrom_generic_command structure containing the packet to send. + + + outputs: + none + + cdrom_generic_command structure containing results. + + error return: + - EIO + + command failed. + - EPERM + + Operation not permitted, either because a + write command was attempted on a drive which + is opened read-only, or because the command + requires CAP_SYS_RAWIO + - EINVAL + + cgc.data_direction not set + + + +CDROM_NEXT_WRITABLE + get next writable block + + + usage:: + + long next; + + ioctl(fd, CDROM_NEXT_WRITABLE, &next); + + inputs: + none + + + outputs: + The next writable block. + + + notes: + If the device does not support this ioctl directly, the + + ioctl will return CDROM_LAST_WRITTEN + 7. + + + +CDROM_LAST_WRITTEN + get last block written on disc + + + usage:: + + long last; + + ioctl(fd, CDROM_LAST_WRITTEN, &last); + + inputs: + none + + + outputs: + The last block written on disc + + + notes: + If the device does not support this ioctl directly, the + result is derived from the disc's table of contents. If the + table of contents can't be read, this ioctl returns an + error. diff --git a/Documentation/userspace-api/ioctl/hdio.rst b/Documentation/userspace-api/ioctl/hdio.rst new file mode 100644 index 000000000000..e822e3dff176 --- /dev/null +++ b/Documentation/userspace-api/ioctl/hdio.rst @@ -0,0 +1,1342 @@ +============================== +Summary of `HDIO_` ioctl calls +============================== + +- Edward A. Falk + +November, 2004 + +This document attempts to describe the ioctl(2) calls supported by +the HD/IDE layer. These are by-and-large implemented (as of Linux 2.6) +in drivers/ide/ide.c and drivers/block/scsi_ioctl.c + +ioctl values are listed in . As of this writing, they +are as follows: + + ioctls that pass argument pointers to user space: + + ======================= ======================================= + HDIO_GETGEO get device geometry + HDIO_GET_UNMASKINTR get current unmask setting + HDIO_GET_MULTCOUNT get current IDE blockmode setting + HDIO_GET_QDMA get use-qdma flag + HDIO_SET_XFER set transfer rate via proc + HDIO_OBSOLETE_IDENTITY OBSOLETE, DO NOT USE + HDIO_GET_KEEPSETTINGS get keep-settings-on-reset flag + HDIO_GET_32BIT get current io_32bit setting + HDIO_GET_NOWERR get ignore-write-error flag + HDIO_GET_DMA get use-dma flag + HDIO_GET_NICE get nice flags + HDIO_GET_IDENTITY get IDE identification info + HDIO_GET_WCACHE get write cache mode on|off + HDIO_GET_ACOUSTIC get acoustic value + HDIO_GET_ADDRESS get sector addressing mode + HDIO_GET_BUSSTATE get the bus state of the hwif + HDIO_TRISTATE_HWIF execute a channel tristate + HDIO_DRIVE_RESET execute a device reset + HDIO_DRIVE_TASKFILE execute raw taskfile + HDIO_DRIVE_TASK execute task and special drive command + HDIO_DRIVE_CMD execute a special drive command + HDIO_DRIVE_CMD_AEB HDIO_DRIVE_TASK + ======================= ======================================= + + ioctls that pass non-pointer values: + + ======================= ======================================= + HDIO_SET_MULTCOUNT change IDE blockmode + HDIO_SET_UNMASKINTR permit other irqs during I/O + HDIO_SET_KEEPSETTINGS keep ioctl settings on reset + HDIO_SET_32BIT change io_32bit flags + HDIO_SET_NOWERR change ignore-write-error flag + HDIO_SET_DMA change use-dma flag + HDIO_SET_PIO_MODE reconfig interface to new speed + HDIO_SCAN_HWIF register and (re)scan interface + HDIO_SET_NICE set nice flags + HDIO_UNREGISTER_HWIF unregister interface + HDIO_SET_WCACHE change write cache enable-disable + HDIO_SET_ACOUSTIC change acoustic behavior + HDIO_SET_BUSSTATE set the bus state of the hwif + HDIO_SET_QDMA change use-qdma flag + HDIO_SET_ADDRESS change lba addressing modes + + HDIO_SET_IDE_SCSI Set scsi emulation mode on/off + HDIO_SET_SCSI_IDE not implemented yet + ======================= ======================================= + + +The information that follows was determined from reading kernel source +code. It is likely that some corrections will be made over time. + +------------------------------------------------------------------------------ + +General: + + Unless otherwise specified, all ioctl calls return 0 on success + and -1 with errno set to an appropriate value on error. + + Unless otherwise specified, all ioctl calls return -1 and set + errno to EFAULT on a failed attempt to copy data to or from user + address space. + + Unless otherwise specified, all data structures and constants + are defined in + +------------------------------------------------------------------------------ + +HDIO_GETGEO + get device geometry + + + usage:: + + struct hd_geometry geom; + + ioctl(fd, HDIO_GETGEO, &geom); + + + inputs: + none + + + + outputs: + hd_geometry structure containing: + + + ========= ================================== + heads number of heads + sectors number of sectors/track + cylinders number of cylinders, mod 65536 + start starting sector of this partition. + ========= ================================== + + + error returns: + - EINVAL + + if the device is not a disk drive or floppy drive, + or if the user passes a null pointer + + + notes: + Not particularly useful with modern disk drives, whose geometry + is a polite fiction anyway. Modern drives are addressed + purely by sector number nowadays (lba addressing), and the + drive geometry is an abstraction which is actually subject + to change. Currently (as of Nov 2004), the geometry values + are the "bios" values -- presumably the values the drive had + when Linux first booted. + + In addition, the cylinders field of the hd_geometry is an + unsigned short, meaning that on most architectures, this + ioctl will not return a meaningful value on drives with more + than 65535 tracks. + + The start field is unsigned long, meaning that it will not + contain a meaningful value for disks over 219 Gb in size. + + + + +HDIO_GET_UNMASKINTR + get current unmask setting + + + usage:: + + long val; + + ioctl(fd, HDIO_GET_UNMASKINTR, &val); + + inputs: + none + + + + outputs: + The value of the drive's current unmask setting + + + + + +HDIO_SET_UNMASKINTR + permit other irqs during I/O + + + usage:: + + unsigned long val; + + ioctl(fd, HDIO_SET_UNMASKINTR, val); + + inputs: + New value for unmask flag + + + + outputs: + none + + + + error return: + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 1] + - EBUSY Controller busy + + + + +HDIO_GET_MULTCOUNT + get current IDE blockmode setting + + + usage:: + + long val; + + ioctl(fd, HDIO_GET_MULTCOUNT, &val); + + inputs: + none + + + + outputs: + The value of the current IDE block mode setting. This + controls how many sectors the drive will transfer per + interrupt. + + + +HDIO_SET_MULTCOUNT + change IDE blockmode + + + usage:: + + int val; + + ioctl(fd, HDIO_SET_MULTCOUNT, val); + + inputs: + New value for IDE block mode setting. This controls how many + sectors the drive will transfer per interrupt. + + outputs: + none + + + + error return: + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range supported by disk. + - EBUSY Controller busy or blockmode already set. + - EIO Drive did not accept new block mode. + + notes: + Source code comments read:: + + This is tightly woven into the driver->do_special cannot + touch. DON'T do it again until a total personality rewrite + is committed. + + If blockmode has already been set, this ioctl will fail with + -EBUSY + + + +HDIO_GET_QDMA + get use-qdma flag + + + Not implemented, as of 2.6.8.1 + + + +HDIO_SET_XFER + set transfer rate via proc + + + Not implemented, as of 2.6.8.1 + + + +HDIO_OBSOLETE_IDENTITY + OBSOLETE, DO NOT USE + + + Same as HDIO_GET_IDENTITY (see below), except that it only + returns the first 142 bytes of drive identity information. + + + +HDIO_GET_IDENTITY + get IDE identification info + + + usage:: + + unsigned char identity[512]; + + ioctl(fd, HDIO_GET_IDENTITY, identity); + + inputs: + none + + + + outputs: + ATA drive identity information. For full description, see + the IDENTIFY DEVICE and IDENTIFY PACKET DEVICE commands in + the ATA specification. + + error returns: + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - ENOMSG IDENTIFY DEVICE information not available + + notes: + Returns information that was obtained when the drive was + probed. Some of this information is subject to change, and + this ioctl does not re-probe the drive to update the + information. + + This information is also available from /proc/ide/hdX/identify + + + +HDIO_GET_KEEPSETTINGS + get keep-settings-on-reset flag + + + usage:: + + long val; + + ioctl(fd, HDIO_GET_KEEPSETTINGS, &val); + + inputs: + none + + + + outputs: + The value of the current "keep settings" flag + + + + notes: + When set, indicates that kernel should restore settings + after a drive reset. + + + +HDIO_SET_KEEPSETTINGS + keep ioctl settings on reset + + + usage:: + + long val; + + ioctl(fd, HDIO_SET_KEEPSETTINGS, val); + + inputs: + New value for keep_settings flag + + + + outputs: + none + + + + error return: + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 1] + - EBUSY Controller busy + + + +HDIO_GET_32BIT + get current io_32bit setting + + + usage:: + + long val; + + ioctl(fd, HDIO_GET_32BIT, &val); + + inputs: + none + + + + outputs: + The value of the current io_32bit setting + + + + notes: + 0=16-bit, 1=32-bit, 2,3 = 32bit+sync + + + + + +HDIO_GET_NOWERR + get ignore-write-error flag + + + usage:: + + long val; + + ioctl(fd, HDIO_GET_NOWERR, &val); + + inputs: + none + + + + outputs: + The value of the current ignore-write-error flag + + + + + +HDIO_GET_DMA + get use-dma flag + + + usage:: + + long val; + + ioctl(fd, HDIO_GET_DMA, &val); + + inputs: + none + + + + outputs: + The value of the current use-dma flag + + + + + +HDIO_GET_NICE + get nice flags + + + usage:: + + long nice; + + ioctl(fd, HDIO_GET_NICE, &nice); + + inputs: + none + + + + outputs: + The drive's "nice" values. + + + + notes: + Per-drive flags which determine when the system will give more + bandwidth to other devices sharing the same IDE bus. + + See , near symbol IDE_NICE_DSC_OVERLAP. + + + + +HDIO_SET_NICE + set nice flags + + + usage:: + + unsigned long nice; + + ... + ioctl(fd, HDIO_SET_NICE, nice); + + inputs: + bitmask of nice flags. + + + + outputs: + none + + + + error returns: + - EACCES Access denied: requires CAP_SYS_ADMIN + - EPERM Flags other than DSC_OVERLAP and NICE_1 set. + - EPERM DSC_OVERLAP specified but not supported by drive + + notes: + This ioctl sets the DSC_OVERLAP and NICE_1 flags from values + provided by the user. + + Nice flags are listed in , starting with + IDE_NICE_DSC_OVERLAP. These values represent shifts. + + + + + +HDIO_GET_WCACHE + get write cache mode on|off + + + usage:: + + long val; + + ioctl(fd, HDIO_GET_WCACHE, &val); + + inputs: + none + + + + outputs: + The value of the current write cache mode + + + + + +HDIO_GET_ACOUSTIC + get acoustic value + + + usage:: + + long val; + + ioctl(fd, HDIO_GET_ACOUSTIC, &val); + + inputs: + none + + + + outputs: + The value of the current acoustic settings + + + + notes: + See HDIO_SET_ACOUSTIC + + + + + +HDIO_GET_ADDRESS + usage:: + + + long val; + + ioctl(fd, HDIO_GET_ADDRESS, &val); + + inputs: + none + + + + outputs: + The value of the current addressing mode: + + = =================== + 0 28-bit + 1 48-bit + 2 48-bit doing 28-bit + 3 64-bit + = =================== + + + +HDIO_GET_BUSSTATE + get the bus state of the hwif + + + usage:: + + long state; + + ioctl(fd, HDIO_SCAN_HWIF, &state); + + inputs: + none + + + + outputs: + Current power state of the IDE bus. One of BUSSTATE_OFF, + BUSSTATE_ON, or BUSSTATE_TRISTATE + + error returns: + - EACCES Access denied: requires CAP_SYS_ADMIN + + + + +HDIO_SET_BUSSTATE + set the bus state of the hwif + + + usage:: + + int state; + + ... + ioctl(fd, HDIO_SCAN_HWIF, state); + + inputs: + Desired IDE power state. One of BUSSTATE_OFF, BUSSTATE_ON, + or BUSSTATE_TRISTATE + + outputs: + none + + + + error returns: + - EACCES Access denied: requires CAP_SYS_RAWIO + - EOPNOTSUPP Hardware interface does not support bus power control + + + + +HDIO_TRISTATE_HWIF + execute a channel tristate + + + Not implemented, as of 2.6.8.1. See HDIO_SET_BUSSTATE + + + +HDIO_DRIVE_RESET + execute a device reset + + + usage:: + + int args[3] + + ... + ioctl(fd, HDIO_DRIVE_RESET, args); + + inputs: + none + + + + outputs: + none + + + + error returns: + - EACCES Access denied: requires CAP_SYS_ADMIN + - ENXIO No such device: phy dead or ctl_addr == 0 + - EIO I/O error: reset timed out or hardware error + + notes: + + - Execute a reset on the device as soon as the current IO + operation has completed. + + - Executes an ATAPI soft reset if applicable, otherwise + executes an ATA soft reset on the controller. + + + +HDIO_DRIVE_TASKFILE + execute raw taskfile + + + Note: + If you don't have a copy of the ANSI ATA specification + handy, you should probably ignore this ioctl. + + - Execute an ATA disk command directly by writing the "taskfile" + registers of the drive. Requires ADMIN and RAWIO access + privileges. + + usage:: + + struct { + + ide_task_request_t req_task; + u8 outbuf[OUTPUT_SIZE]; + u8 inbuf[INPUT_SIZE]; + } task; + memset(&task.req_task, 0, sizeof(task.req_task)); + task.req_task.out_size = sizeof(task.outbuf); + task.req_task.in_size = sizeof(task.inbuf); + ... + ioctl(fd, HDIO_DRIVE_TASKFILE, &task); + ... + + inputs: + + (See below for details on memory area passed to ioctl.) + + ============ =================================================== + io_ports[8] values to be written to taskfile registers + hob_ports[8] high-order bytes, for extended commands. + out_flags flags indicating which registers are valid + in_flags flags indicating which registers should be returned + data_phase see below + req_cmd command type to be executed + out_size size of output buffer + outbuf buffer of data to be transmitted to disk + inbuf buffer of data to be received from disk (see [1]) + ============ =================================================== + + outputs: + + =========== ==================================================== + io_ports[] values returned in the taskfile registers + hob_ports[] high-order bytes, for extended commands. + out_flags flags indicating which registers are valid (see [2]) + in_flags flags indicating which registers should be returned + outbuf buffer of data to be transmitted to disk (see [1]) + inbuf buffer of data to be received from disk + =========== ==================================================== + + error returns: + - EACCES CAP_SYS_ADMIN or CAP_SYS_RAWIO privilege not set. + - ENOMSG Device is not a disk drive. + - ENOMEM Unable to allocate memory for task + - EFAULT req_cmd == TASKFILE_IN_OUT (not implemented as of 2.6.8) + - EPERM + + req_cmd == TASKFILE_MULTI_OUT and drive + multi-count not yet set. + - EIO Drive failed the command. + + notes: + + [1] READ THE FOLLOWING NOTES *CAREFULLY*. THIS IOCTL IS + FULL OF GOTCHAS. Extreme caution should be used with using + this ioctl. A mistake can easily corrupt data or hang the + system. + + [2] Both the input and output buffers are copied from the + user and written back to the user, even when not used. + + [3] If one or more bits are set in out_flags and in_flags is + zero, the following values are used for in_flags.all and + written back into in_flags on completion. + + * IDE_TASKFILE_STD_IN_FLAGS | (IDE_HOB_STD_IN_FLAGS << 8) + if LBA48 addressing is enabled for the drive + * IDE_TASKFILE_STD_IN_FLAGS + if CHS/LBA28 + + The association between in_flags.all and each enable + bitfield flips depending on endianness; fortunately, TASKFILE + only uses inflags.b.data bit and ignores all other bits. + The end result is that, on any endian machines, it has no + effect other than modifying in_flags on completion. + + [4] The default value of SELECT is (0xa0|DEV_bit|LBA_bit) + except for four drives per port chipsets. For four drives + per port chipsets, it's (0xa0|DEV_bit|LBA_bit) for the first + pair and (0x80|DEV_bit|LBA_bit) for the second pair. + + [5] The argument to the ioctl is a pointer to a region of + memory containing a ide_task_request_t structure, followed + by an optional buffer of data to be transmitted to the + drive, followed by an optional buffer to receive data from + the drive. + + Command is passed to the disk drive via the ide_task_request_t + structure, which contains these fields: + + ============ =============================================== + io_ports[8] values for the taskfile registers + hob_ports[8] high-order bytes, for extended commands + out_flags flags indicating which entries in the + io_ports[] and hob_ports[] arrays + contain valid values. Type ide_reg_valid_t. + in_flags flags indicating which entries in the + io_ports[] and hob_ports[] arrays + are expected to contain valid values + on return. + data_phase See below + req_cmd Command type, see below + out_size output (user->drive) buffer size, bytes + in_size input (drive->user) buffer size, bytes + ============ =============================================== + + When out_flags is zero, the following registers are loaded. + + ============ =============================================== + HOB_FEATURE If the drive supports LBA48 + HOB_NSECTOR If the drive supports LBA48 + HOB_SECTOR If the drive supports LBA48 + HOB_LCYL If the drive supports LBA48 + HOB_HCYL If the drive supports LBA48 + FEATURE + NSECTOR + SECTOR + LCYL + HCYL + SELECT First, masked with 0xE0 if LBA48, 0xEF + otherwise; then, or'ed with the default + value of SELECT. + ============ =============================================== + + If any bit in out_flags is set, the following registers are loaded. + + ============ =============================================== + HOB_DATA If out_flags.b.data is set. HOB_DATA will + travel on DD8-DD15 on little endian machines + and on DD0-DD7 on big endian machines. + DATA If out_flags.b.data is set. DATA will + travel on DD0-DD7 on little endian machines + and on DD8-DD15 on big endian machines. + HOB_NSECTOR If out_flags.b.nsector_hob is set + HOB_SECTOR If out_flags.b.sector_hob is set + HOB_LCYL If out_flags.b.lcyl_hob is set + HOB_HCYL If out_flags.b.hcyl_hob is set + FEATURE If out_flags.b.feature is set + NSECTOR If out_flags.b.nsector is set + SECTOR If out_flags.b.sector is set + LCYL If out_flags.b.lcyl is set + HCYL If out_flags.b.hcyl is set + SELECT Or'ed with the default value of SELECT and + loaded regardless of out_flags.b.select. + ============ =============================================== + + Taskfile registers are read back from the drive into + {io|hob}_ports[] after the command completes iff one of the + following conditions is met; otherwise, the original values + will be written back, unchanged. + + 1. The drive fails the command (EIO). + 2. One or more than one bits are set in out_flags. + 3. The requested data_phase is TASKFILE_NO_DATA. + + ============ =============================================== + HOB_DATA If in_flags.b.data is set. It will contain + DD8-DD15 on little endian machines and + DD0-DD7 on big endian machines. + DATA If in_flags.b.data is set. It will contain + DD0-DD7 on little endian machines and + DD8-DD15 on big endian machines. + HOB_FEATURE If the drive supports LBA48 + HOB_NSECTOR If the drive supports LBA48 + HOB_SECTOR If the drive supports LBA48 + HOB_LCYL If the drive supports LBA48 + HOB_HCYL If the drive supports LBA48 + NSECTOR + SECTOR + LCYL + HCYL + ============ =============================================== + + The data_phase field describes the data transfer to be + performed. Value is one of: + + =================== ======================================== + TASKFILE_IN + TASKFILE_MULTI_IN + TASKFILE_OUT + TASKFILE_MULTI_OUT + TASKFILE_IN_OUT + TASKFILE_IN_DMA + TASKFILE_IN_DMAQ == IN_DMA (queueing not supported) + TASKFILE_OUT_DMA + TASKFILE_OUT_DMAQ == OUT_DMA (queueing not supported) + TASKFILE_P_IN unimplemented + TASKFILE_P_IN_DMA unimplemented + TASKFILE_P_IN_DMAQ unimplemented + TASKFILE_P_OUT unimplemented + TASKFILE_P_OUT_DMA unimplemented + TASKFILE_P_OUT_DMAQ unimplemented + =================== ======================================== + + The req_cmd field classifies the command type. It may be + one of: + + ======================== ======================================= + IDE_DRIVE_TASK_NO_DATA + IDE_DRIVE_TASK_SET_XFER unimplemented + IDE_DRIVE_TASK_IN + IDE_DRIVE_TASK_OUT unimplemented + IDE_DRIVE_TASK_RAW_WRITE + ======================== ======================================= + + [6] Do not access {in|out}_flags->all except for resetting + all the bits. Always access individual bit fields. ->all + value will flip depending on endianness. For the same + reason, do not use IDE_{TASKFILE|HOB}_STD_{OUT|IN}_FLAGS + constants defined in hdreg.h. + + + +HDIO_DRIVE_CMD + execute a special drive command + + + Note: If you don't have a copy of the ANSI ATA specification + handy, you should probably ignore this ioctl. + + usage:: + + u8 args[4+XFER_SIZE]; + + ... + ioctl(fd, HDIO_DRIVE_CMD, args); + + inputs: + Commands other than WIN_SMART: + + ======= ======= + args[0] COMMAND + args[1] NSECTOR + args[2] FEATURE + args[3] NSECTOR + ======= ======= + + WIN_SMART: + + ======= ======= + args[0] COMMAND + args[1] SECTOR + args[2] FEATURE + args[3] NSECTOR + ======= ======= + + outputs: + args[] buffer is filled with register values followed by any + + + data returned by the disk. + + ======== ==================================================== + args[0] status + args[1] error + args[2] NSECTOR + args[3] undefined + args[4+] NSECTOR * 512 bytes of data returned by the command. + ======== ==================================================== + + error returns: + - EACCES Access denied: requires CAP_SYS_RAWIO + - ENOMEM Unable to allocate memory for task + - EIO Drive reports error + + notes: + + [1] For commands other than WIN_SMART, args[1] should equal + args[3]. SECTOR, LCYL and HCYL are undefined. For + WIN_SMART, 0x4f and 0xc2 are loaded into LCYL and HCYL + respectively. In both cases SELECT will contain the default + value for the drive. Please refer to HDIO_DRIVE_TASKFILE + notes for the default value of SELECT. + + [2] If NSECTOR value is greater than zero and the drive sets + DRQ when interrupting for the command, NSECTOR * 512 bytes + are read from the device into the area following NSECTOR. + In the above example, the area would be + args[4..4+XFER_SIZE]. 16bit PIO is used regardless of + HDIO_SET_32BIT setting. + + [3] If COMMAND == WIN_SETFEATURES && FEATURE == SETFEATURES_XFER + && NSECTOR >= XFER_SW_DMA_0 && the drive supports any DMA + mode, IDE driver will try to tune the transfer mode of the + drive accordingly. + + + +HDIO_DRIVE_TASK + execute task and special drive command + + + Note: If you don't have a copy of the ANSI ATA specification + handy, you should probably ignore this ioctl. + + usage:: + + u8 args[7]; + + ... + ioctl(fd, HDIO_DRIVE_TASK, args); + + inputs: + Taskfile register values: + + ======= ======= + args[0] COMMAND + args[1] FEATURE + args[2] NSECTOR + args[3] SECTOR + args[4] LCYL + args[5] HCYL + args[6] SELECT + ======= ======= + + outputs: + Taskfile register values: + + + ======= ======= + args[0] status + args[1] error + args[2] NSECTOR + args[3] SECTOR + args[4] LCYL + args[5] HCYL + args[6] SELECT + ======= ======= + + error returns: + - EACCES Access denied: requires CAP_SYS_RAWIO + - ENOMEM Unable to allocate memory for task + - ENOMSG Device is not a disk drive. + - EIO Drive failed the command. + + notes: + + [1] DEV bit (0x10) of SELECT register is ignored and the + appropriate value for the drive is used. All other bits + are used unaltered. + + + +HDIO_DRIVE_CMD_AEB + HDIO_DRIVE_TASK + + + Not implemented, as of 2.6.8.1 + + + +HDIO_SET_32BIT + change io_32bit flags + + + usage:: + + int val; + + ioctl(fd, HDIO_SET_32BIT, val); + + inputs: + New value for io_32bit flag + + + + outputs: + none + + + + error return: + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 3] + - EBUSY Controller busy + + + + +HDIO_SET_NOWERR + change ignore-write-error flag + + + usage:: + + int val; + + ioctl(fd, HDIO_SET_NOWERR, val); + + inputs: + New value for ignore-write-error flag. Used for ignoring + + + WRERR_STAT + + outputs: + none + + + + error return: + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 1] + - EBUSY Controller busy + + + +HDIO_SET_DMA + change use-dma flag + + + usage:: + + long val; + + ioctl(fd, HDIO_SET_DMA, val); + + inputs: + New value for use-dma flag + + + + outputs: + none + + + + error return: + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 1] + - EBUSY Controller busy + + + +HDIO_SET_PIO_MODE + reconfig interface to new speed + + + usage:: + + long val; + + ioctl(fd, HDIO_SET_PIO_MODE, val); + + inputs: + New interface speed. + + + + outputs: + none + + + + error return: + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 255] + - EBUSY Controller busy + + + +HDIO_SCAN_HWIF + register and (re)scan interface + + + usage:: + + int args[3] + + ... + ioctl(fd, HDIO_SCAN_HWIF, args); + + inputs: + + ======= ========================= + args[0] io address to probe + + + args[1] control address to probe + args[2] irq number + ======= ========================= + + outputs: + none + + + + error returns: + - EACCES Access denied: requires CAP_SYS_RAWIO + - EIO Probe failed. + + notes: + This ioctl initializes the addresses and irq for a disk + controller, probes for drives, and creates /proc/ide + interfaces as appropriate. + + + +HDIO_UNREGISTER_HWIF + unregister interface + + + usage:: + + int index; + + ioctl(fd, HDIO_UNREGISTER_HWIF, index); + + inputs: + index index of hardware interface to unregister + + + + outputs: + none + + + + error returns: + - EACCES Access denied: requires CAP_SYS_RAWIO + + notes: + This ioctl removes a hardware interface from the kernel. + + Currently (2.6.8) this ioctl silently fails if any drive on + the interface is busy. + + + +HDIO_SET_WCACHE + change write cache enable-disable + + + usage:: + + int val; + + ioctl(fd, HDIO_SET_WCACHE, val); + + inputs: + New value for write cache enable + + + + outputs: + none + + + + error return: + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 1] + - EBUSY Controller busy + + + +HDIO_SET_ACOUSTIC + change acoustic behavior + + + usage:: + + int val; + + ioctl(fd, HDIO_SET_ACOUSTIC, val); + + inputs: + New value for drive acoustic settings + + + + outputs: + none + + + + error return: + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 254] + - EBUSY Controller busy + + + +HDIO_SET_QDMA + change use-qdma flag + + + Not implemented, as of 2.6.8.1 + + + +HDIO_SET_ADDRESS + change lba addressing modes + + + usage:: + + int val; + + ioctl(fd, HDIO_SET_ADDRESS, val); + + inputs: + New value for addressing mode + + = =================== + 0 28-bit + 1 48-bit + 2 48-bit doing 28-bit + = =================== + + outputs: + none + + + + error return: + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 2] + - EBUSY Controller busy + - EIO Drive does not support lba48 mode. + + +HDIO_SET_IDE_SCSI + usage:: + + + long val; + + ioctl(fd, HDIO_SET_IDE_SCSI, val); + + inputs: + New value for scsi emulation mode (?) + + + + outputs: + none + + + + error return: + - EINVAL (bdev != bdev->bd_contains) (not sure what this means) + - EACCES Access denied: requires CAP_SYS_ADMIN + - EINVAL value out of range [0 1] + - EBUSY Controller busy + + + +HDIO_SET_SCSI_IDE + Not implemented, as of 2.6.8.1 diff --git a/Documentation/userspace-api/ioctl/index.rst b/Documentation/userspace-api/ioctl/index.rst new file mode 100644 index 000000000000..475675eae086 --- /dev/null +++ b/Documentation/userspace-api/ioctl/index.rst @@ -0,0 +1,15 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====== +IOCTLs +====== + +.. toctree:: + :maxdepth: 1 + + ioctl-number + + ioctl-decoding + + cdrom + hdio diff --git a/Documentation/userspace-api/ioctl/ioctl-decoding.rst b/Documentation/userspace-api/ioctl/ioctl-decoding.rst new file mode 100644 index 000000000000..380d6bb3e3ea --- /dev/null +++ b/Documentation/userspace-api/ioctl/ioctl-decoding.rst @@ -0,0 +1,31 @@ +============================== +Decoding an IOCTL Magic Number +============================== + +To decode a hex IOCTL code: + +Most architectures use this generic format, but check +include/ARCH/ioctl.h for specifics, e.g. powerpc +uses 3 bits to encode read/write and 13 bits for size. + + ====== ================================== + bits meaning + ====== ================================== + 31-30 00 - no parameters: uses _IO macro + 10 - read: _IOR + 01 - write: _IOW + 11 - read/write: _IOWR + + 29-16 size of arguments + + 15-8 ascii character supposedly + unique to each driver + + 7-0 function # + ====== ================================== + + +So for example 0x82187201 is a read with arg length of 0x218, +character 'r' function 1. Grepping the source reveals this is:: + + #define VFAT_IOCTL_READDIR_BOTH _IOR('r', 1, struct dirent [2]) diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst new file mode 100644 index 000000000000..bef79cd4c6b4 --- /dev/null +++ b/Documentation/userspace-api/ioctl/ioctl-number.rst @@ -0,0 +1,362 @@ +============= +Ioctl Numbers +============= + +19 October 1999 + +Michael Elizabeth Chastain + + +If you are adding new ioctl's to the kernel, you should use the _IO +macros defined in : + + ====== == ============================================ + _IO an ioctl with no parameters + _IOW an ioctl with write parameters (copy_from_user) + _IOR an ioctl with read parameters (copy_to_user) + _IOWR an ioctl with both write and read parameters. + ====== == ============================================ + +'Write' and 'read' are from the user's point of view, just like the +system calls 'write' and 'read'. For example, a SET_FOO ioctl would +be _IOW, although the kernel would actually read data from user space; +a GET_FOO ioctl would be _IOR, although the kernel would actually write +data to user space. + +The first argument to _IO, _IOW, _IOR, or _IOWR is an identifying letter +or number from the table below. Because of the large number of drivers, +many drivers share a partial letter with other drivers. + +If you are writing a driver for a new device and need a letter, pick an +unused block with enough room for expansion: 32 to 256 ioctl commands. +You can register the block by patching this file and submitting the +patch to Linus Torvalds. Or you can e-mail me at and +I'll register one for you. + +The second argument to _IO, _IOW, _IOR, or _IOWR is a sequence number +to distinguish ioctls from each other. The third argument to _IOW, +_IOR, or _IOWR is the type of the data going into the kernel or coming +out of the kernel (e.g. 'int' or 'struct foo'). NOTE! Do NOT use +sizeof(arg) as the third argument as this results in your ioctl thinking +it passes an argument of type size_t. + +Some devices use their major number as the identifier; this is OK, as +long as it is unique. Some devices are irregular and don't follow any +convention at all. + +Following this convention is good because: + +(1) Keeping the ioctl's globally unique helps error checking: + if a program calls an ioctl on the wrong device, it will get an + error rather than some unexpected behaviour. + +(2) The 'strace' build procedure automatically finds ioctl numbers + defined with _IO, _IOW, _IOR, or _IOWR. + +(3) 'strace' can decode numbers back into useful names when the + numbers are unique. + +(4) People looking for ioctls can grep for them more easily when + this convention is used to define the ioctl numbers. + +(5) When following the convention, the driver code can use generic + code to copy the parameters between user and kernel space. + +This table lists ioctls visible from user land for Linux/x86. It contains +most drivers up to 2.6.31, but I know I am missing some. There has been +no attempt to list non-X86 architectures or ioctls from drivers/staging/. + +==== ===== ======================================================= ================================================================ +Code Seq# Include File Comments + (hex) +==== ===== ======================================================= ================================================================ +0x00 00-1F linux/fs.h conflict! +0x00 00-1F scsi/scsi_ioctl.h conflict! +0x00 00-1F linux/fb.h conflict! +0x00 00-1F linux/wavefront.h conflict! +0x02 all linux/fd.h +0x03 all linux/hdreg.h +0x04 D2-DC linux/umsdos_fs.h Dead since 2.6.11, but don't reuse these. +0x06 all linux/lp.h +0x09 all linux/raid/md_u.h +0x10 00-0F drivers/char/s390/vmcp.h +0x10 10-1F arch/s390/include/uapi/sclp_ctl.h +0x10 20-2F arch/s390/include/uapi/asm/hypfs.h +0x12 all linux/fs.h + linux/blkpg.h +0x1b all InfiniBand Subsystem + +0x20 all drivers/cdrom/cm206.h +0x22 all scsi/sg.h +'!' 00-1F uapi/linux/seccomp.h +'#' 00-3F IEEE 1394 Subsystem + Block for the entire subsystem +'$' 00-0F linux/perf_counter.h, linux/perf_event.h +'%' 00-0F include/uapi/linux/stm.h System Trace Module subsystem + +'&' 00-07 drivers/firewire/nosy-user.h +'1' 00-1F linux/timepps.h PPS kit from Ulrich Windl + +'2' 01-04 linux/i2o.h +'3' 00-0F drivers/s390/char/raw3270.h conflict! +'3' 00-1F linux/suspend_ioctls.h, conflict! + kernel/power/user.c +'8' all SNP8023 advanced NIC card + +';' 64-7F linux/vfio.h +'@' 00-0F linux/radeonfb.h conflict! +'@' 00-0F drivers/video/aty/aty128fb.c conflict! +'A' 00-1F linux/apm_bios.h conflict! +'A' 00-0F linux/agpgart.h, conflict! + drivers/char/agp/compat_ioctl.h +'A' 00-7F sound/asound.h conflict! +'B' 00-1F linux/cciss_ioctl.h conflict! +'B' 00-0F include/linux/pmu.h conflict! +'B' C0-FF advanced bbus +'C' all linux/soundcard.h conflict! +'C' 01-2F linux/capi.h conflict! +'C' F0-FF drivers/net/wan/cosa.h conflict! +'D' all arch/s390/include/asm/dasd.h +'D' 40-5F drivers/scsi/dpt/dtpi_ioctl.h +'D' 05 drivers/scsi/pmcraid.h +'E' all linux/input.h conflict! +'E' 00-0F xen/evtchn.h conflict! +'F' all linux/fb.h conflict! +'F' 01-02 drivers/scsi/pmcraid.h conflict! +'F' 20 drivers/video/fsl-diu-fb.h conflict! +'F' 20 drivers/video/intelfb/intelfb.h conflict! +'F' 20 linux/ivtvfb.h conflict! +'F' 20 linux/matroxfb.h conflict! +'F' 20 drivers/video/aty/atyfb_base.c conflict! +'F' 00-0F video/da8xx-fb.h conflict! +'F' 80-8F linux/arcfb.h conflict! +'F' DD video/sstfb.h conflict! +'G' 00-3F drivers/misc/sgi-gru/grulib.h conflict! +'G' 00-0F linux/gigaset_dev.h conflict! +'H' 00-7F linux/hiddev.h conflict! +'H' 00-0F linux/hidraw.h conflict! +'H' 01 linux/mei.h conflict! +'H' 02 linux/mei.h conflict! +'H' 03 linux/mei.h conflict! +'H' 00-0F sound/asound.h conflict! +'H' 20-40 sound/asound_fm.h conflict! +'H' 80-8F sound/sfnt_info.h conflict! +'H' 10-8F sound/emu10k1.h conflict! +'H' 10-1F sound/sb16_csp.h conflict! +'H' 10-1F sound/hda_hwdep.h conflict! +'H' 40-4F sound/hdspm.h conflict! +'H' 40-4F sound/hdsp.h conflict! +'H' 90 sound/usb/usx2y/usb_stream.h +'H' A0 uapi/linux/usb/cdc-wdm.h +'H' C0-F0 net/bluetooth/hci.h conflict! +'H' C0-DF net/bluetooth/hidp/hidp.h conflict! +'H' C0-DF net/bluetooth/cmtp/cmtp.h conflict! +'H' C0-DF net/bluetooth/bnep/bnep.h conflict! +'H' F1 linux/hid-roccat.h +'H' F8-FA sound/firewire.h +'I' all linux/isdn.h conflict! +'I' 00-0F drivers/isdn/divert/isdn_divert.h conflict! +'I' 40-4F linux/mISDNif.h conflict! +'J' 00-1F drivers/scsi/gdth_ioctl.h +'K' all linux/kd.h +'L' 00-1F linux/loop.h conflict! +'L' 10-1F drivers/scsi/mpt3sas/mpt3sas_ctl.h conflict! +'L' 20-2F linux/lightnvm.h +'L' E0-FF linux/ppdd.h encrypted disk device driver + +'M' all linux/soundcard.h conflict! +'M' 01-16 mtd/mtd-abi.h conflict! + and drivers/mtd/mtdchar.c +'M' 01-03 drivers/scsi/megaraid/megaraid_sas.h +'M' 00-0F drivers/video/fsl-diu-fb.h conflict! +'N' 00-1F drivers/usb/scanner.h +'N' 40-7F drivers/block/nvme.c +'O' 00-06 mtd/ubi-user.h UBI +'P' all linux/soundcard.h conflict! +'P' 60-6F sound/sscape_ioctl.h conflict! +'P' 00-0F drivers/usb/class/usblp.c conflict! +'P' 01-09 drivers/misc/pci_endpoint_test.c conflict! +'Q' all linux/soundcard.h +'R' 00-1F linux/random.h conflict! +'R' 01 linux/rfkill.h conflict! +'R' C0-DF net/bluetooth/rfcomm.h +'S' all linux/cdrom.h conflict! +'S' 80-81 scsi/scsi_ioctl.h conflict! +'S' 82-FF scsi/scsi.h conflict! +'S' 00-7F sound/asequencer.h conflict! +'T' all linux/soundcard.h conflict! +'T' 00-AF sound/asound.h conflict! +'T' all arch/x86/include/asm/ioctls.h conflict! +'T' C0-DF linux/if_tun.h conflict! +'U' all sound/asound.h conflict! +'U' 00-CF linux/uinput.h conflict! +'U' 00-EF linux/usbdevice_fs.h +'U' C0-CF drivers/bluetooth/hci_uart.h +'V' all linux/vt.h conflict! +'V' all linux/videodev2.h conflict! +'V' C0 linux/ivtvfb.h conflict! +'V' C0 linux/ivtv.h conflict! +'V' C0 media/davinci/vpfe_capture.h conflict! +'V' C0 media/si4713.h conflict! +'W' 00-1F linux/watchdog.h conflict! +'W' 00-1F linux/wanrouter.h conflict! (pre 3.9) +'W' 00-3F sound/asound.h conflict! +'W' 40-5F drivers/pci/switch/switchtec.c +'X' all fs/xfs/xfs_fs.h, conflict! + fs/xfs/linux-2.6/xfs_ioctl32.h, + include/linux/falloc.h, + linux/fs.h, +'X' all fs/ocfs2/ocfs_fs.h conflict! +'X' 01 linux/pktcdvd.h conflict! +'Y' all linux/cyclades.h +'Z' 14-15 drivers/message/fusion/mptctl.h +'[' 00-3F linux/usb/tmc.h USB Test and Measurement Devices + +'a' all linux/atm*.h, linux/sonet.h ATM on linux + +'a' 00-0F drivers/crypto/qat/qat_common/adf_cfg_common.h conflict! qat driver +'b' 00-FF conflict! bit3 vme host bridge + +'c' all linux/cm4000_cs.h conflict! +'c' 00-7F linux/comstats.h conflict! +'c' 00-7F linux/coda.h conflict! +'c' 00-1F linux/chio.h conflict! +'c' 80-9F arch/s390/include/asm/chsc.h conflict! +'c' A0-AF arch/x86/include/asm/msr.h conflict! +'d' 00-FF linux/char/drm/drm.h conflict! +'d' 02-40 pcmcia/ds.h conflict! +'d' F0-FF linux/digi1.h +'e' all linux/digi1.h conflict! +'f' 00-1F linux/ext2_fs.h conflict! +'f' 00-1F linux/ext3_fs.h conflict! +'f' 00-0F fs/jfs/jfs_dinode.h conflict! +'f' 00-0F fs/ext4/ext4.h conflict! +'f' 00-0F linux/fs.h conflict! +'f' 00-0F fs/ocfs2/ocfs2_fs.h conflict! +'f' 81-8F linux/fsverity.h +'g' 00-0F linux/usb/gadgetfs.h +'g' 20-2F linux/usb/g_printer.h +'h' 00-7F conflict! Charon filesystem + +'h' 00-1F linux/hpet.h conflict! +'h' 80-8F fs/hfsplus/ioctl.c +'i' 00-3F linux/i2o-dev.h conflict! +'i' 0B-1F linux/ipmi.h conflict! +'i' 80-8F linux/i8k.h +'j' 00-3F linux/joystick.h +'k' 00-0F linux/spi/spidev.h conflict! +'k' 00-05 video/kyro.h conflict! +'k' 10-17 linux/hsi/hsi_char.h HSI character device +'l' 00-3F linux/tcfs_fs.h transparent cryptographic file system + +'l' 40-7F linux/udf_fs_i.h in development: + +'m' 00-09 linux/mmtimer.h conflict! +'m' all linux/mtio.h conflict! +'m' all linux/soundcard.h conflict! +'m' all linux/synclink.h conflict! +'m' 00-19 drivers/message/fusion/mptctl.h conflict! +'m' 00 drivers/scsi/megaraid/megaraid_ioctl.h conflict! +'n' 00-7F linux/ncp_fs.h and fs/ncpfs/ioctl.c +'n' 80-8F uapi/linux/nilfs2_api.h NILFS2 +'n' E0-FF linux/matroxfb.h matroxfb +'o' 00-1F fs/ocfs2/ocfs2_fs.h OCFS2 +'o' 00-03 mtd/ubi-user.h conflict! (OCFS2 and UBI overlaps) +'o' 40-41 mtd/ubi-user.h UBI +'o' 01-A1 `linux/dvb/*.h` DVB +'p' 00-0F linux/phantom.h conflict! (OpenHaptics needs this) +'p' 00-1F linux/rtc.h conflict! +'p' 00-3F linux/mc146818rtc.h conflict! +'p' 40-7F linux/nvram.h +'p' 80-9F linux/ppdev.h user-space parport + +'p' A1-A5 linux/pps.h LinuxPPS + +'q' 00-1F linux/serio.h +'q' 80-FF linux/telephony.h Internet PhoneJACK, Internet LineJACK + linux/ixjuser.h +'r' 00-1F linux/msdos_fs.h and fs/fat/dir.c +'s' all linux/cdk.h +'t' 00-7F linux/ppp-ioctl.h +'t' 80-8F linux/isdn_ppp.h +'t' 90-91 linux/toshiba.h toshiba and toshiba_acpi SMM +'u' 00-1F linux/smb_fs.h gone +'u' 20-3F linux/uvcvideo.h USB video class host driver +'u' 40-4f linux/udmabuf.h userspace dma-buf misc device +'v' 00-1F linux/ext2_fs.h conflict! +'v' 00-1F linux/fs.h conflict! +'v' 00-0F linux/sonypi.h conflict! +'v' 00-0F media/v4l2-subdev.h conflict! +'v' C0-FF linux/meye.h conflict! +'w' all CERN SCI driver +'y' 00-1F packet based user level communications + +'z' 00-3F CAN bus card conflict! + +'z' 40-7F CAN bus card conflict! + +'z' 10-4F drivers/s390/crypto/zcrypt_api.h conflict! +'|' 00-7F linux/media.h +0x80 00-1F linux/fb.h +0x89 00-06 arch/x86/include/asm/sockios.h +0x89 0B-DF linux/sockios.h +0x89 E0-EF linux/sockios.h SIOCPROTOPRIVATE range +0x89 E0-EF linux/dn.h PROTOPRIVATE range +0x89 F0-FF linux/sockios.h SIOCDEVPRIVATE range +0x8B all linux/wireless.h +0x8C 00-3F WiNRADiO driver + +0x90 00 drivers/cdrom/sbpcd.h +0x92 00-0F drivers/usb/mon/mon_bin.c +0x93 60-7F linux/auto_fs.h +0x94 all fs/btrfs/ioctl.h Btrfs filesystem + and linux/fs.h some lifted to vfs/generic +0x97 00-7F fs/ceph/ioctl.h Ceph file system +0x99 00-0F 537-Addinboard driver + +0xA0 all linux/sdp/sdp.h Industrial Device Project + +0xA1 0 linux/vtpm_proxy.h TPM Emulator Proxy Driver +0xA3 80-8F Port ACL in development: + +0xA3 90-9F linux/dtlk.h +0xA4 00-1F uapi/linux/tee.h Generic TEE subsystem +0xAA 00-3F linux/uapi/linux/userfaultfd.h +0xAB 00-1F linux/nbd.h +0xAC 00-1F linux/raw.h +0xAD 00 Netfilter device in development: + +0xAE all linux/kvm.h Kernel-based Virtual Machine + +0xAF 00-1F linux/fsl_hypervisor.h Freescale hypervisor +0xB0 all RATIO devices in development: + +0xB1 00-1F PPPoX + +0xB3 00 linux/mmc/ioctl.h +0xB4 00-0F linux/gpio.h +0xB5 00-0F uapi/linux/rpmsg.h +0xB6 all linux/fpga-dfl.h +0xC0 00-0F linux/usb/iowarrior.h +0xCA 00-0F uapi/misc/cxl.h +0xCA 10-2F uapi/misc/ocxl.h +0xCA 80-BF uapi/scsi/cxlflash_ioctl.h +0xCB 00-1F CBM serial IEC bus in development: + +0xCC 00-0F drivers/misc/ibmvmc.h pseries VMC driver +0xCD 01 linux/reiserfs_fs.h +0xCF 02 fs/cifs/ioctl.c +0xDB 00-0F drivers/char/mwave/mwavepub.h +0xDD 00-3F ZFCP device driver see drivers/s390/scsi/ + +0xE5 00-3F linux/fuse.h +0xEC 00-01 drivers/platform/chrome/cros_ec_dev.h ChromeOS EC driver +0xF3 00-3F drivers/usb/misc/sisusbvga/sisusb.h sisfb (in development) + +0xF4 00-1F video/mbxfb.h mbxfb + +0xF6 all LTTng Linux Trace Toolkit Next Generation + +0xFD all linux/dm-ioctl.h +0xFE all linux/isst_if.h +==== ===== ======================================================= ================================================================ -- cgit From f11b46f314209c053b7756b46a50a36e36cfb85a Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 4 Oct 2019 10:14:21 -0600 Subject: docs: remove :c:func: from genalloc.rst As of 5.3, the automarkup extension will do the right thing with function() notation, so we don't need to clutter the text with :c:func: invocations. So remove them. Signed-off-by: Jonathan Corbet --- Documentation/core-api/genalloc.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/Documentation/core-api/genalloc.rst b/Documentation/core-api/genalloc.rst index 2db2f79eb229..098a46f55798 100644 --- a/Documentation/core-api/genalloc.rst +++ b/Documentation/core-api/genalloc.rst @@ -23,7 +23,7 @@ begins with the creation of a pool using one of: .. kernel-doc:: lib/genalloc.c :functions: devm_gen_pool_create -A call to :c:func:`gen_pool_create` will create a pool. The granularity of +A call to gen_pool_create() will create a pool. The granularity of allocations is set with min_alloc_order; it is a log-base-2 number like those used by the page allocator, but it refers to bytes rather than pages. So, if min_alloc_order is passed as 3, then all allocations will be a @@ -32,7 +32,7 @@ required to track the memory in the pool. The nid parameter specifies which NUMA node should be used for the allocation of the housekeeping structures; it can be -1 if the caller doesn't care. -The "managed" interface :c:func:`devm_gen_pool_create` ties the pool to a +The "managed" interface devm_gen_pool_create() ties the pool to a specific device. Among other things, it will automatically clean up the pool when the given device is destroyed. @@ -55,10 +55,10 @@ to the pool. That can be done with one of: .. kernel-doc:: lib/genalloc.c :functions: gen_pool_add_owner -A call to :c:func:`gen_pool_add` will place the size bytes of memory +A call to gen_pool_add() will place the size bytes of memory starting at addr (in the kernel's virtual address space) into the given pool, once again using nid as the node ID for ancillary memory allocations. -The :c:func:`gen_pool_add_virt` variant associates an explicit physical +The gen_pool_add_virt() variant associates an explicit physical address with the memory; this is only necessary if the pool will be used for DMA allocations. @@ -74,11 +74,11 @@ are: .. kernel-doc:: lib/genalloc.c :functions: gen_pool_free_owner -As one would expect, :c:func:`gen_pool_alloc` will allocate size< bytes -from the given pool. The :c:func:`gen_pool_dma_alloc` variant allocates +As one would expect, gen_pool_alloc() will allocate size< bytes +from the given pool. The gen_pool_dma_alloc() variant allocates memory for use with DMA operations, returning the associated physical address in the space pointed to by dma. This will only work if the memory -was added with :c:func:`gen_pool_add_virt`. Note that this function +was added with gen_pool_add_virt(). Note that this function departs from the usual genpool pattern of using unsigned long values to represent kernel addresses; it returns a void * instead. @@ -94,9 +94,9 @@ of interest: .. kernel-doc:: lib/genalloc.c :functions: gen_pool_set_algo -Allocations with :c:func:`gen_pool_alloc_algo` specify an algorithm to be +Allocations with gen_pool_alloc_algo() specify an algorithm to be used to choose the memory to be allocated; the default algorithm can be set -with :c:func:`gen_pool_set_algo`. The data value is passed to the +with gen_pool_set_algo(). The data value is passed to the algorithm; most ignore it, but it is occasionally needed. One can, naturally, write a special-purpose algorithm, but there is a fair set already available: -- cgit From 7f70ae564b807f81263326d641514c6dca88e5ef Mon Sep 17 00:00:00 2001 From: Paul Walmsley Date: Wed, 9 Oct 2019 12:53:50 -0700 Subject: Documentation: admin-guide: add earlycon documentation for RISC-V Kernels booting on RISC-V can specify "earlycon" with no options on the Linux command line, and the generic DT earlycon support will query the "chosen/stdout-path" property (if present) to determine which early console device to use. Document this appropriately in the admin-guide. Signed-off-by: Paul Walmsley Reviewed-by: Geert Uytterhoeven Cc: Christoph Hellwig Cc: Andreas Schwab Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/kernel-parameters.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index edf65dad250b..fd69e7f8ef79 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -988,6 +988,10 @@ chosen node or the ACPI SPCR table if supported by the platform. + [RISCV] When used with no options, the early + console is determined by the stdout-path + property in the device tree's chosen node. + cdns,[,options] Start an early, polled-mode console on a Cadence (xuartps) serial port at the specified address. Only -- cgit From 0ac624f47dd3474441bb56d64f97192f139b593f Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 24 Sep 2019 10:01:28 -0300 Subject: docs: fix some broken references There are a number of documentation files that got moved or renamed. update their references. Signed-off-by: Mauro Carvalho Chehab Acked-by: Shannon Nelson Acked-by: Guenter Roeck Acked-by: Rob Herring Acked-by: Paul Walmsley # RISC-V Acked-by: Bartosz Golaszewski Signed-off-by: Jonathan Corbet --- Documentation/devicetree/bindings/cpu/cpu-topology.txt | 2 +- Documentation/devicetree/bindings/timer/ingenic,tcu.txt | 2 +- Documentation/driver-api/gpio/driver.rst | 2 +- Documentation/hwmon/inspur-ipsps1.rst | 2 +- Documentation/mips/ingenic-tcu.rst | 2 +- Documentation/networking/device_drivers/mellanox/mlx5.rst | 2 +- MAINTAINERS | 2 +- drivers/net/ethernet/faraday/ftgmac100.c | 2 +- drivers/net/ethernet/pensando/ionic/ionic_if.h | 4 ++-- fs/cifs/cifsfs.c | 2 +- 10 files changed, 11 insertions(+), 11 deletions(-) diff --git a/Documentation/devicetree/bindings/cpu/cpu-topology.txt b/Documentation/devicetree/bindings/cpu/cpu-topology.txt index 99918189403c..9bd530a35d14 100644 --- a/Documentation/devicetree/bindings/cpu/cpu-topology.txt +++ b/Documentation/devicetree/bindings/cpu/cpu-topology.txt @@ -549,5 +549,5 @@ Example 3: HiFive Unleashed (RISC-V 64 bit, 4 core system) [2] Devicetree NUMA binding description Documentation/devicetree/bindings/numa.txt [3] RISC-V Linux kernel documentation - Documentation/devicetree/bindings/riscv/cpus.txt + Documentation/devicetree/bindings/riscv/cpus.yaml [4] https://www.devicetree.org/specifications/ diff --git a/Documentation/devicetree/bindings/timer/ingenic,tcu.txt b/Documentation/devicetree/bindings/timer/ingenic,tcu.txt index 5a4b9ddd9470..7f6fe20503f5 100644 --- a/Documentation/devicetree/bindings/timer/ingenic,tcu.txt +++ b/Documentation/devicetree/bindings/timer/ingenic,tcu.txt @@ -2,7 +2,7 @@ Ingenic JZ47xx SoCs Timer/Counter Unit devicetree bindings ========================================================== For a description of the TCU hardware and drivers, have a look at -Documentation/mips/ingenic-tcu.txt. +Documentation/mips/ingenic-tcu.rst. Required properties: diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst index 3fdb32422f8a..9076cc76d5bf 100644 --- a/Documentation/driver-api/gpio/driver.rst +++ b/Documentation/driver-api/gpio/driver.rst @@ -493,7 +493,7 @@ available but we try to move away from this: gpiochip. It will pass the struct gpio_chip* for the chip to all IRQ callbacks, so the callbacks need to embed the gpio_chip in its state container and obtain a pointer to the container using container_of(). - (See Documentation/driver-model/design-patterns.txt) + (See Documentation/driver-api/driver-model/design-patterns.rst) - gpiochip_irqchip_add_nested(): adds a nested cascaded irqchip to a gpiochip, as discussed above regarding different types of cascaded irqchips. The diff --git a/Documentation/hwmon/inspur-ipsps1.rst b/Documentation/hwmon/inspur-ipsps1.rst index 2b871ae3448f..ed32a65c30e1 100644 --- a/Documentation/hwmon/inspur-ipsps1.rst +++ b/Documentation/hwmon/inspur-ipsps1.rst @@ -17,7 +17,7 @@ Usage Notes ----------- This driver does not auto-detect devices. You will have to instantiate the -devices explicitly. Please see Documentation/i2c/instantiating-devices for +devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for details. Sysfs entries diff --git a/Documentation/mips/ingenic-tcu.rst b/Documentation/mips/ingenic-tcu.rst index c4ef4c45aade..c5a646b14450 100644 --- a/Documentation/mips/ingenic-tcu.rst +++ b/Documentation/mips/ingenic-tcu.rst @@ -68,4 +68,4 @@ and frameworks can be controlled from the same registers, all of these drivers access their registers through the same regmap. For more information regarding the devicetree bindings of the TCU drivers, -have a look at Documentation/devicetree/bindings/mfd/ingenic,tcu.txt. +have a look at Documentation/devicetree/bindings/timer/ingenic,tcu.txt. diff --git a/Documentation/networking/device_drivers/mellanox/mlx5.rst b/Documentation/networking/device_drivers/mellanox/mlx5.rst index d071c6b49e1f..a74422058351 100644 --- a/Documentation/networking/device_drivers/mellanox/mlx5.rst +++ b/Documentation/networking/device_drivers/mellanox/mlx5.rst @@ -258,7 +258,7 @@ mlx5 tracepoints ================ mlx5 driver provides internal trace points for tracking and debugging using -kernel tracepoints interfaces (refer to Documentation/trace/ftrase.rst). +kernel tracepoints interfaces (refer to Documentation/trace/ftrace.rst). For the list of support mlx5 events check /sys/kernel/debug/tracing/events/mlx5/ diff --git a/MAINTAINERS b/MAINTAINERS index b20bc42f6a92..7c814177e01f 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -3683,7 +3683,7 @@ M: Oleksij Rempel R: Pengutronix Kernel Team L: linux-can@vger.kernel.org S: Maintained -F: Documentation/networking/j1939.txt +F: Documentation/networking/j1939.rst F: net/can/j1939/ F: include/uapi/linux/can/j1939.h diff --git a/drivers/net/ethernet/faraday/ftgmac100.c b/drivers/net/ethernet/faraday/ftgmac100.c index 9b7af94a40bb..8abe5e90d268 100644 --- a/drivers/net/ethernet/faraday/ftgmac100.c +++ b/drivers/net/ethernet/faraday/ftgmac100.c @@ -1835,7 +1835,7 @@ static int ftgmac100_probe(struct platform_device *pdev) } /* Indicate that we support PAUSE frames (see comment in - * Documentation/networking/phy.txt) + * Documentation/networking/phy.rst) */ phy_support_asym_pause(phy); diff --git a/drivers/net/ethernet/pensando/ionic/ionic_if.h b/drivers/net/ethernet/pensando/ionic/ionic_if.h index 5bfdda19f64d..80028f781c83 100644 --- a/drivers/net/ethernet/pensando/ionic/ionic_if.h +++ b/drivers/net/ethernet/pensando/ionic/ionic_if.h @@ -596,8 +596,8 @@ enum ionic_txq_desc_opcode { * the @encap is set, the device will * offload the outer header checksums using * LCO (local checksum offload) (see - * Documentation/networking/checksum- - * offloads.txt for more info). + * Documentation/networking/checksum-offloads.rst + * for more info). * * IONIC_TXQ_DESC_OPCODE_CSUM_HW: * diff --git a/fs/cifs/cifsfs.c b/fs/cifs/cifsfs.c index 2e9c7f493f99..811f510578cb 100644 --- a/fs/cifs/cifsfs.c +++ b/fs/cifs/cifsfs.c @@ -1529,7 +1529,7 @@ init_cifs(void) /* * Consider in future setting limit!=0 maybe to min(num_of_cores - 1, 3) * so that we don't launch too many worker threads but - * Documentation/workqueue.txt recommends setting it to 0 + * Documentation/core-api/workqueue.rst recommends setting it to 0 */ /* WQ_UNBOUND allows decrypt tasks to run on any CPU */ -- cgit From 868adb544a3995328fc68c31748437433c1ff8de Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 24 Sep 2019 10:01:29 -0300 Subject: bindings: rename links to mason USB2/USB3 DT files Those files got renamed, but another DT file still points to the older places. Fixes: 87a55485f2fc ("dt-bindings: phy: meson-g12a-usb3-pcie-phy: convert to yaml") Fixes: da86d286cce8 ("dt-bindings: phy: meson-g12a-usb2-phy: convert to yaml") Signed-off-by: Mauro Carvalho Chehab Acked-by: Rob Herring Signed-off-by: Jonathan Corbet --- Documentation/devicetree/bindings/usb/amlogic,dwc3.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/devicetree/bindings/usb/amlogic,dwc3.txt b/Documentation/devicetree/bindings/usb/amlogic,dwc3.txt index b9f04e617eb7..6ffb09be7a76 100644 --- a/Documentation/devicetree/bindings/usb/amlogic,dwc3.txt +++ b/Documentation/devicetree/bindings/usb/amlogic,dwc3.txt @@ -85,8 +85,8 @@ A child node must exist to represent the core DWC2 IP block. The name of the node is not important. The content of the node is defined in dwc2.txt. PHY documentation is provided in the following places: -- Documentation/devicetree/bindings/phy/meson-g12a-usb2-phy.txt -- Documentation/devicetree/bindings/phy/meson-g12a-usb3-pcie-phy.txt +- Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb2-phy.yaml +- Documentation/devicetree/bindings/phy/amlogic,meson-g12a-usb3-pcie-phy.yaml Example device nodes: usb: usb@ffe09000 { -- cgit From 81834b918e92c60c1ec4b30ccb68094b2fde1669 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Tue, 24 Sep 2019 10:01:30 -0300 Subject: bindings: MAINTAINERS: fix references to Allwinner LRADC The file got converted to yaml, but the reference at MAINTAINERS was not updated. Fixes: 5bf2845ece35 ("dt-bindings: input: Convert Allwinner LRADC to a schema") Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet --- MAINTAINERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MAINTAINERS b/MAINTAINERS index 7c814177e01f..f23c244c461b 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -15540,7 +15540,7 @@ SUN4I LOW RES ADC ATTACHED TABLET KEYS DRIVER M: Hans de Goede L: linux-input@vger.kernel.org S: Maintained -F: Documentation/devicetree/bindings/input/sun4i-lradc-keys.txt +F: Documentation/devicetree/bindings/input/allwinner,sun4i-a10-lradc-keys.yaml F: drivers/input/keyboard/sun4i-lradc-keys.c SUNDANCE NETWORK DRIVER -- cgit From d6ce98fe11a052af081612029dc351d20fd8e6f8 Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Thu, 3 Oct 2019 21:05:36 +0200 Subject: docs: networking: devlink-trap: Fix reference to other document MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This fixes the following Sphinx warning: Documentation/networking/devlink-trap.rst:175: WARNING: unknown document: /devlink-trap-netdevsim Fixes: 9e0874570488 ("Documentation: Add description of netdevsim traps") Signed-off-by: Jonathan Neuschäfer Acked-by: David S. Miller Signed-off-by: Jonathan Corbet --- Documentation/networking/devlink-trap.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/networking/devlink-trap.rst b/Documentation/networking/devlink-trap.rst index 8e90a85f3bd5..5c04cc542bcf 100644 --- a/Documentation/networking/devlink-trap.rst +++ b/Documentation/networking/devlink-trap.rst @@ -172,7 +172,7 @@ help debug packet drops caused by these exceptions. The following list includes links to the description of driver-specific traps registered by various device drivers: - * :doc:`/devlink-trap-netdevsim` + * :doc:`devlink-trap-netdevsim` Generic Packet Trap Groups ========================== -- cgit From ea882f75766c1831720078151c9ca2fdff557e89 Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Thu, 3 Oct 2019 22:43:22 +0200 Subject: docs: networking: phy: Improve phrasing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It's not about times (multiple occurences of an event) but about the duration of a time interval. Signed-off-by: Jonathan Neuschäfer Acked-by: David S. Miller Signed-off-by: Jonathan Corbet --- Documentation/networking/phy.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/networking/phy.rst b/Documentation/networking/phy.rst index a689966bc4be..3f5bd83034df 100644 --- a/Documentation/networking/phy.rst +++ b/Documentation/networking/phy.rst @@ -73,7 +73,7 @@ The Reduced Gigabit Medium Independent Interface (RGMII) is a 12-pin electrical signal interface using a synchronous 125Mhz clock signal and several data lines. Due to this design decision, a 1.5ns to 2ns delay must be added between the clock line (RXC or TXC) and the data lines to let the PHY (clock -sink) have enough setup and hold times to sample the data lines correctly. The +sink) have a large enough setup and hold time to sample the data lines correctly. The PHY library offers different types of PHY_INTERFACE_MODE_RGMII* values to let the PHY driver and optionally the MAC driver, implement the required delay. The values of phy_interface_t must be understood from the perspective of the PHY -- cgit From ca30ad857d903a2462b85bf83357becb668f0ad7 Mon Sep 17 00:00:00 2001 From: Oleksandr Natalenko Date: Wed, 2 Oct 2019 13:46:10 +0200 Subject: docs: admin-guide: fix printk_ratelimit explanation The printk_ratelimit value accepts seconds, not jiffies (though it is converted into jiffies internally). Update documentation to reflect this. Also, remove the statement about allowing 1 message in 5 seconds since bursts up to 10 messages are allowed by default. Finally, while we are here, mention default value for printk_ratelimit_burst too. Signed-off-by: Oleksandr Natalenko Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/sysctl/kernel.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 032c7cd3cede..6e0da29e55f1 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -831,8 +831,8 @@ printk_ratelimit: ================= Some warning messages are rate limited. printk_ratelimit specifies -the minimum length of time between these messages (in jiffies), by -default we allow one every 5 seconds. +the minimum length of time between these messages (in seconds). +The default value is 5 seconds. A value of 0 will disable rate limiting. @@ -845,6 +845,8 @@ seconds, we do allow a burst of messages to pass through. printk_ratelimit_burst specifies the number of messages we can send before ratelimiting kicks in. +The default value is 10 messages. + printk_devkmsg: =============== -- cgit From 0a6f33dba4ee91f4e00f46510d94277bdd4260da Mon Sep 17 00:00:00 2001 From: Bryan Gurney Date: Mon, 7 Oct 2019 13:24:49 -0400 Subject: dm dust: convert documentation to ReST Convert the dm-dust documentation to ReST formatting, using literal blocks for all of the shell command, shell output, and log output examples. Add dm-dust to index.rst. Additionally, fix an annotation in the "querying for specific bad blocks" section, on the "queryblock ... not found in badblocklist" example, to properly state that the message appears when a given block is not found. Signed-off-by: Bryan Gurney Signed-off-by: Jonathan Corbet --- .../admin-guide/device-mapper/dm-dust.rst | 287 +++++++++++++++++++++ .../admin-guide/device-mapper/dm-dust.txt | 272 ------------------- Documentation/admin-guide/device-mapper/index.rst | 1 + 3 files changed, 288 insertions(+), 272 deletions(-) create mode 100644 Documentation/admin-guide/device-mapper/dm-dust.rst delete mode 100644 Documentation/admin-guide/device-mapper/dm-dust.txt diff --git a/Documentation/admin-guide/device-mapper/dm-dust.rst b/Documentation/admin-guide/device-mapper/dm-dust.rst new file mode 100644 index 000000000000..b6e7e7ead831 --- /dev/null +++ b/Documentation/admin-guide/device-mapper/dm-dust.rst @@ -0,0 +1,287 @@ +dm-dust +======= + +This target emulates the behavior of bad sectors at arbitrary +locations, and the ability to enable the emulation of the failures +at an arbitrary time. + +This target behaves similarly to a linear target. At a given time, +the user can send a message to the target to start failing read +requests on specific blocks (to emulate the behavior of a hard disk +drive with bad sectors). + +When the failure behavior is enabled (i.e.: when the output of +"dmsetup status" displays "fail_read_on_bad_block"), reads of blocks +in the "bad block list" will fail with EIO ("Input/output error"). + +Writes of blocks in the "bad block list will result in the following: + +1. Remove the block from the "bad block list". +2. Successfully complete the write. + +This emulates the "remapped sector" behavior of a drive with bad +sectors. + +Normally, a drive that is encountering bad sectors will most likely +encounter more bad sectors, at an unknown time or location. +With dm-dust, the user can use the "addbadblock" and "removebadblock" +messages to add arbitrary bad blocks at new locations, and the +"enable" and "disable" messages to modulate the state of whether the +configured "bad blocks" will be treated as bad, or bypassed. +This allows the pre-writing of test data and metadata prior to +simulating a "failure" event where bad sectors start to appear. + +Table parameters +---------------- + + +Mandatory parameters: + : + Path to the block device. + + : + Offset to data area from start of device_path + + : + Block size in bytes + + (minimum 512, maximum 1073741824, must be a power of 2) + +Usage instructions +------------------ + +First, find the size (in 512-byte sectors) of the device to be used:: + + $ sudo blockdev --getsz /dev/vdb1 + 33552384 + +Create the dm-dust device: +(For a device with a block size of 512 bytes) + +:: + + $ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 512' + +(For a device with a block size of 4096 bytes) + +:: + + $ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 4096' + +Check the status of the read behavior ("bypass" indicates that all I/O +will be passed through to the underlying device):: + + $ sudo dmsetup status dust1 + 0 33552384 dust 252:17 bypass + + $ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=128 iflag=direct + 128+0 records in + 128+0 records out + + $ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct + 128+0 records in + 128+0 records out + +Adding and removing bad blocks +------------------------------ + +At any time (i.e.: whether the device has the "bad block" emulation +enabled or disabled), bad blocks may be added or removed from the +device via the "addbadblock" and "removebadblock" messages:: + + $ sudo dmsetup message dust1 0 addbadblock 60 + kernel: device-mapper: dust: badblock added at block 60 + + $ sudo dmsetup message dust1 0 addbadblock 67 + kernel: device-mapper: dust: badblock added at block 67 + + $ sudo dmsetup message dust1 0 addbadblock 72 + kernel: device-mapper: dust: badblock added at block 72 + +These bad blocks will be stored in the "bad block list". +While the device is in "bypass" mode, reads and writes will succeed:: + + $ sudo dmsetup status dust1 + 0 33552384 dust 252:17 bypass + +Enabling block read failures +---------------------------- + +To enable the "fail read on bad block" behavior, send the "enable" message:: + + $ sudo dmsetup message dust1 0 enable + kernel: device-mapper: dust: enabling read failures on bad sectors + + $ sudo dmsetup status dust1 + 0 33552384 dust 252:17 fail_read_on_bad_block + +With the device in "fail read on bad block" mode, attempting to read a +block will encounter an "Input/output error":: + + $ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=1 skip=67 iflag=direct + dd: error reading '/dev/mapper/dust1': Input/output error + 0+0 records in + 0+0 records out + 0 bytes copied, 0.00040651 s, 0.0 kB/s + +...and writing to the bad blocks will remove the blocks from the list, +therefore emulating the "remap" behavior of hard disk drives:: + + $ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct + 128+0 records in + 128+0 records out + + kernel: device-mapper: dust: block 60 removed from badblocklist by write + kernel: device-mapper: dust: block 67 removed from badblocklist by write + kernel: device-mapper: dust: block 72 removed from badblocklist by write + kernel: device-mapper: dust: block 87 removed from badblocklist by write + +Bad block add/remove error handling +----------------------------------- + +Attempting to add a bad block that already exists in the list will +result in an "Invalid argument" error, as well as a helpful message:: + + $ sudo dmsetup message dust1 0 addbadblock 88 + device-mapper: message ioctl on dust1 failed: Invalid argument + kernel: device-mapper: dust: block 88 already in badblocklist + +Attempting to remove a bad block that doesn't exist in the list will +result in an "Invalid argument" error, as well as a helpful message:: + + $ sudo dmsetup message dust1 0 removebadblock 87 + device-mapper: message ioctl on dust1 failed: Invalid argument + kernel: device-mapper: dust: block 87 not found in badblocklist + +Counting the number of bad blocks in the bad block list +------------------------------------------------------- + +To count the number of bad blocks configured in the device, run the +following message command:: + + $ sudo dmsetup message dust1 0 countbadblocks + +A message will print with the number of bad blocks currently +configured on the device:: + + kernel: device-mapper: dust: countbadblocks: 895 badblock(s) found + +Querying for specific bad blocks +-------------------------------- + +To find out if a specific block is in the bad block list, run the +following message command:: + + $ sudo dmsetup message dust1 0 queryblock 72 + +The following message will print if the block is in the list:: + + device-mapper: dust: queryblock: block 72 found in badblocklist + +The following message will print if the block is not in the list:: + + device-mapper: dust: queryblock: block 72 not found in badblocklist + +The "queryblock" message command will work in both the "enabled" +and "disabled" modes, allowing the verification of whether a block +will be treated as "bad" without having to issue I/O to the device, +or having to "enable" the bad block emulation. + +Clearing the bad block list +--------------------------- + +To clear the bad block list (without needing to individually run +a "removebadblock" message command for every block), run the +following message command:: + + $ sudo dmsetup message dust1 0 clearbadblocks + +After clearing the bad block list, the following message will appear:: + + kernel: device-mapper: dust: clearbadblocks: badblocks cleared + +If there were no bad blocks to clear, the following message will +appear:: + + kernel: device-mapper: dust: clearbadblocks: no badblocks found + +Message commands list +--------------------- + +Below is a list of the messages that can be sent to a dust device: + +Operations on blocks (requires a argument):: + + addbadblock + queryblock + removebadblock + +...where is a block number within range of the device +(corresponding to the block size of the device.) + +Single argument message commands:: + + countbadblocks + clearbadblocks + disable + enable + quiet + +Device removal +-------------- + +When finished, remove the device via the "dmsetup remove" command:: + + $ sudo dmsetup remove dust1 + +Quiet mode +---------- + +On test runs with many bad blocks, it may be desirable to avoid +excessive logging (from bad blocks added, removed, or "remapped"). +This can be done by enabling "quiet mode" via the following message:: + + $ sudo dmsetup message dust1 0 quiet + +This will suppress log messages from add / remove / removed by write +operations. Log messages from "countbadblocks" or "queryblock" +message commands will still print in quiet mode. + +The status of quiet mode can be seen by running "dmsetup status":: + + $ sudo dmsetup status dust1 + 0 33552384 dust 252:17 fail_read_on_bad_block quiet + +To disable quiet mode, send the "quiet" message again:: + + $ sudo dmsetup message dust1 0 quiet + + $ sudo dmsetup status dust1 + 0 33552384 dust 252:17 fail_read_on_bad_block verbose + +(The presence of "verbose" indicates normal logging.) + +"Why not...?" +------------- + +scsi_debug has a "medium error" mode that can fail reads on one +specified sector (sector 0x1234, hardcoded in the source code), but +it uses RAM for the persistent storage, which drastically decreases +the potential device size. + +dm-flakey fails all I/O from all block locations at a specified time +frequency, and not a given point in time. + +When a bad sector occurs on a hard disk drive, reads to that sector +are failed by the device, usually resulting in an error code of EIO +("I/O error") or ENODATA ("No data available"). However, a write to +the sector may succeed, and result in the sector becoming readable +after the device controller no longer experiences errors reading the +sector (or after a reallocation of the sector). However, there may +be bad sectors that occur on the device in the future, in a different, +unpredictable location. + +This target seeks to provide a device that can exhibit the behavior +of a bad sector at a known sector location, at a known time, based +on a large storage device (at least tens of gigabytes, not occupying +system memory). diff --git a/Documentation/admin-guide/device-mapper/dm-dust.txt b/Documentation/admin-guide/device-mapper/dm-dust.txt deleted file mode 100644 index 954d402a1f6a..000000000000 --- a/Documentation/admin-guide/device-mapper/dm-dust.txt +++ /dev/null @@ -1,272 +0,0 @@ -dm-dust -======= - -This target emulates the behavior of bad sectors at arbitrary -locations, and the ability to enable the emulation of the failures -at an arbitrary time. - -This target behaves similarly to a linear target. At a given time, -the user can send a message to the target to start failing read -requests on specific blocks (to emulate the behavior of a hard disk -drive with bad sectors). - -When the failure behavior is enabled (i.e.: when the output of -"dmsetup status" displays "fail_read_on_bad_block"), reads of blocks -in the "bad block list" will fail with EIO ("Input/output error"). - -Writes of blocks in the "bad block list will result in the following: - -1. Remove the block from the "bad block list". -2. Successfully complete the write. - -This emulates the "remapped sector" behavior of a drive with bad -sectors. - -Normally, a drive that is encountering bad sectors will most likely -encounter more bad sectors, at an unknown time or location. -With dm-dust, the user can use the "addbadblock" and "removebadblock" -messages to add arbitrary bad blocks at new locations, and the -"enable" and "disable" messages to modulate the state of whether the -configured "bad blocks" will be treated as bad, or bypassed. -This allows the pre-writing of test data and metadata prior to -simulating a "failure" event where bad sectors start to appear. - -Table parameters: ------------------ - - -Mandatory parameters: - : path to the block device. - : offset to data area from start of device_path - : block size in bytes - (minimum 512, maximum 1073741824, must be a power of 2) - -Usage instructions: -------------------- - -First, find the size (in 512-byte sectors) of the device to be used: - -$ sudo blockdev --getsz /dev/vdb1 -33552384 - -Create the dm-dust device: -(For a device with a block size of 512 bytes) -$ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 512' - -(For a device with a block size of 4096 bytes) -$ sudo dmsetup create dust1 --table '0 33552384 dust /dev/vdb1 0 4096' - -Check the status of the read behavior ("bypass" indicates that all I/O -will be passed through to the underlying device): -$ sudo dmsetup status dust1 -0 33552384 dust 252:17 bypass - -$ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=128 iflag=direct -128+0 records in -128+0 records out - -$ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct -128+0 records in -128+0 records out - -Adding and removing bad blocks: -------------------------------- - -At any time (i.e.: whether the device has the "bad block" emulation -enabled or disabled), bad blocks may be added or removed from the -device via the "addbadblock" and "removebadblock" messages: - -$ sudo dmsetup message dust1 0 addbadblock 60 -kernel: device-mapper: dust: badblock added at block 60 - -$ sudo dmsetup message dust1 0 addbadblock 67 -kernel: device-mapper: dust: badblock added at block 67 - -$ sudo dmsetup message dust1 0 addbadblock 72 -kernel: device-mapper: dust: badblock added at block 72 - -These bad blocks will be stored in the "bad block list". -While the device is in "bypass" mode, reads and writes will succeed: - -$ sudo dmsetup status dust1 -0 33552384 dust 252:17 bypass - -Enabling block read failures: ------------------------------ - -To enable the "fail read on bad block" behavior, send the "enable" message: - -$ sudo dmsetup message dust1 0 enable -kernel: device-mapper: dust: enabling read failures on bad sectors - -$ sudo dmsetup status dust1 -0 33552384 dust 252:17 fail_read_on_bad_block - -With the device in "fail read on bad block" mode, attempting to read a -block will encounter an "Input/output error": - -$ sudo dd if=/dev/mapper/dust1 of=/dev/null bs=512 count=1 skip=67 iflag=direct -dd: error reading '/dev/mapper/dust1': Input/output error -0+0 records in -0+0 records out -0 bytes copied, 0.00040651 s, 0.0 kB/s - -...and writing to the bad blocks will remove the blocks from the list, -therefore emulating the "remap" behavior of hard disk drives: - -$ sudo dd if=/dev/zero of=/dev/mapper/dust1 bs=512 count=128 oflag=direct -128+0 records in -128+0 records out - -kernel: device-mapper: dust: block 60 removed from badblocklist by write -kernel: device-mapper: dust: block 67 removed from badblocklist by write -kernel: device-mapper: dust: block 72 removed from badblocklist by write -kernel: device-mapper: dust: block 87 removed from badblocklist by write - -Bad block add/remove error handling: ------------------------------------- - -Attempting to add a bad block that already exists in the list will -result in an "Invalid argument" error, as well as a helpful message: - -$ sudo dmsetup message dust1 0 addbadblock 88 -device-mapper: message ioctl on dust1 failed: Invalid argument -kernel: device-mapper: dust: block 88 already in badblocklist - -Attempting to remove a bad block that doesn't exist in the list will -result in an "Invalid argument" error, as well as a helpful message: - -$ sudo dmsetup message dust1 0 removebadblock 87 -device-mapper: message ioctl on dust1 failed: Invalid argument -kernel: device-mapper: dust: block 87 not found in badblocklist - -Counting the number of bad blocks in the bad block list: --------------------------------------------------------- - -To count the number of bad blocks configured in the device, run the -following message command: - -$ sudo dmsetup message dust1 0 countbadblocks - -A message will print with the number of bad blocks currently -configured on the device: - -kernel: device-mapper: dust: countbadblocks: 895 badblock(s) found - -Querying for specific bad blocks: ---------------------------------- - -To find out if a specific block is in the bad block list, run the -following message command: - -$ sudo dmsetup message dust1 0 queryblock 72 - -The following message will print if the block is in the list: -device-mapper: dust: queryblock: block 72 found in badblocklist - -The following message will print if the block is in the list: -device-mapper: dust: queryblock: block 72 not found in badblocklist - -The "queryblock" message command will work in both the "enabled" -and "disabled" modes, allowing the verification of whether a block -will be treated as "bad" without having to issue I/O to the device, -or having to "enable" the bad block emulation. - -Clearing the bad block list: ----------------------------- - -To clear the bad block list (without needing to individually run -a "removebadblock" message command for every block), run the -following message command: - -$ sudo dmsetup message dust1 0 clearbadblocks - -After clearing the bad block list, the following message will appear: - -kernel: device-mapper: dust: clearbadblocks: badblocks cleared - -If there were no bad blocks to clear, the following message will -appear: - -kernel: device-mapper: dust: clearbadblocks: no badblocks found - -Message commands list: ----------------------- - -Below is a list of the messages that can be sent to a dust device: - -Operations on blocks (requires a argument): - -addbadblock -queryblock -removebadblock - -...where is a block number within range of the device - (corresponding to the block size of the device.) - -Single argument message commands: - -countbadblocks -clearbadblocks -disable -enable -quiet - -Device removal: ---------------- - -When finished, remove the device via the "dmsetup remove" command: - -$ sudo dmsetup remove dust1 - -Quiet mode: ------------ - -On test runs with many bad blocks, it may be desirable to avoid -excessive logging (from bad blocks added, removed, or "remapped"). -This can be done by enabling "quiet mode" via the following message: - -$ sudo dmsetup message dust1 0 quiet - -This will suppress log messages from add / remove / removed by write -operations. Log messages from "countbadblocks" or "queryblock" -message commands will still print in quiet mode. - -The status of quiet mode can be seen by running "dmsetup status": - -$ sudo dmsetup status dust1 -0 33552384 dust 252:17 fail_read_on_bad_block quiet - -To disable quiet mode, send the "quiet" message again: - -$ sudo dmsetup message dust1 0 quiet - -$ sudo dmsetup status dust1 -0 33552384 dust 252:17 fail_read_on_bad_block verbose - -(The presence of "verbose" indicates normal logging.) - -"Why not...?" -------------- - -scsi_debug has a "medium error" mode that can fail reads on one -specified sector (sector 0x1234, hardcoded in the source code), but -it uses RAM for the persistent storage, which drastically decreases -the potential device size. - -dm-flakey fails all I/O from all block locations at a specified time -frequency, and not a given point in time. - -When a bad sector occurs on a hard disk drive, reads to that sector -are failed by the device, usually resulting in an error code of EIO -("I/O error") or ENODATA ("No data available"). However, a write to -the sector may succeed, and result in the sector becoming readable -after the device controller no longer experiences errors reading the -sector (or after a reallocation of the sector). However, there may -be bad sectors that occur on the device in the future, in a different, -unpredictable location. - -This target seeks to provide a device that can exhibit the behavior -of a bad sector at a known sector location, at a known time, based -on a large storage device (at least tens of gigabytes, not occupying -system memory). diff --git a/Documentation/admin-guide/device-mapper/index.rst b/Documentation/admin-guide/device-mapper/index.rst index c77c58b8f67b..4872fb6d2952 100644 --- a/Documentation/admin-guide/device-mapper/index.rst +++ b/Documentation/admin-guide/device-mapper/index.rst @@ -9,6 +9,7 @@ Device Mapper cache delay dm-crypt + dm-dust dm-flakey dm-init dm-integrity -- cgit From 0e3901891ab66dce0a51579035594c9b685650dd Mon Sep 17 00:00:00 2001 From: Christian Kujau Date: Thu, 10 Oct 2019 20:36:16 -0700 Subject: docs: SafeSetID.rst: Remove spurious '???' characters It appears that some smart quotes were changed to "???" by even smarter software; change them to the dumb but legible variety. Signed-off-by: Christian Kujau Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/LSM/SafeSetID.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/admin-guide/LSM/SafeSetID.rst b/Documentation/admin-guide/LSM/SafeSetID.rst index 212434ef65ad..7bff07ce4fdd 100644 --- a/Documentation/admin-guide/LSM/SafeSetID.rst +++ b/Documentation/admin-guide/LSM/SafeSetID.rst @@ -56,7 +56,7 @@ setid capabilities from the application completely and refactor the process spawning semantics in the application (e.g. by using a privileged helper program to do process spawning and UID/GID transitions). Unfortunately, there are a number of semantics around process spawning that would be affected by this, such -as fork() calls where the program doesn???t immediately call exec() after the +as fork() calls where the program doesn't immediately call exec() after the fork(), parent processes specifying custom environment variables or command line args for spawned child processes, or inheritance of file handles across a fork()/exec(). Because of this, as solution that uses a privileged helper in @@ -72,7 +72,7 @@ own user namespace, and only approved UIDs/GIDs could be mapped back to the initial system user namespace, affectively preventing privilege escalation. Unfortunately, it is not generally feasible to use user namespaces in isolation, without pairing them with other namespace types, which is not always an option. -Linux checks for capabilities based off of the user namespace that ???owns??? some +Linux checks for capabilities based off of the user namespace that "owns" some entity. For example, Linux has the notion that network namespaces are owned by the user namespace in which they were created. A consequence of this is that capability checks for access to a given network namespace are done by checking -- cgit From 0a04480d96338c9ba6ce47da101a945f1658cb21 Mon Sep 17 00:00:00 2001 From: Derek Kiernan Date: Wed, 2 Oct 2019 10:03:55 -0700 Subject: docs: misc: xilinx_sdfec: Actually add documentation Add SD-FEC driver documentation. Signed-off-by: Derek Kiernan Signed-off-by: Dragan Cvetic Link: https://lore.kernel.org/r/1560274185-264438-11-git-send-email-dragan.cvetic@xilinx.com [kees: extracted from v7 as it was missing in the commit for v8] Signed-off-by: Kees Cook Signed-off-by: Jonathan Corbet --- Documentation/misc-devices/xilinx_sdfec.rst | 291 ++++++++++++++++++++++++++++ 1 file changed, 291 insertions(+) create mode 100644 Documentation/misc-devices/xilinx_sdfec.rst diff --git a/Documentation/misc-devices/xilinx_sdfec.rst b/Documentation/misc-devices/xilinx_sdfec.rst new file mode 100644 index 000000000000..2245fcfa224d --- /dev/null +++ b/Documentation/misc-devices/xilinx_sdfec.rst @@ -0,0 +1,291 @@ +.. SPDX-License-Identifier: GPL-2.0+ +==================== +Xilinx SD-FEC Driver +==================== + +Overview +======== + +This driver supports SD-FEC Integrated Block for Zynq |Ultrascale+ (TM)| RFSoCs. + +.. |Ultrascale+ (TM)| unicode:: Ultrascale+ U+2122 + .. with trademark sign + +For a full description of SD-FEC core features, see the `SD-FEC Product Guide (PG256) `_ + +This driver supports the following features: + + - Retrieval of the Integrated Block configuration and status information + - Configuration of LDPC codes + - Configuration of Turbo decoding + - Monitoring errors + +Missing features, known issues, and limitations of the SD-FEC driver are as +follows: + + - Only allows a single open file handler to any instance of the driver at any time + - Reset of the SD-FEC Integrated Block is not controlled by this driver + - Does not support shared LDPC code table wraparound + +The device tree entry is described in: +`linux-xlnx/Documentation/devicetree/bindings/misc/xlnx,sd-fec.txt `_ + + +Modes of Operation +------------------ + +The driver works with the SD-FEC core in two modes of operation: + + - Run-time configuration + - Programmable Logic (PL) initialization + + +Run-time Configuration +~~~~~~~~~~~~~~~~~~~~~~ + +For Run-time configuration the role of driver is to allow the software application to do the following: + + - Load the configuration parameters for either Turbo decode or LDPC encode or decode + - Activate the SD-FEC core + - Monitor the SD-FEC core for errors + - Retrieve the status and configuration of the SD-FEC core + +Programmable Logic (PL) Initialization +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For PL initialization, supporting logic loads configuration parameters for either +the Turbo decode or LDPC encode or decode. The role of the driver is to allow +the software application to do the following: + + - Activate the SD-FEC core + - Monitor the SD-FEC core for errors + - Retrieve the status and configuration of the SD-FEC core + + +Driver Structure +================ + +The driver provides a platform device where the ``probe`` and ``remove`` +operations are provided. + + - probe: Updates configuration register with device-tree entries plus determines the current activate state of the core, for example, is the core bypassed or has the core been started. + + +The driver defines the following driver file operations to provide user +application interfaces: + + - open: Implements restriction that only a single file descriptor can be open per SD-FEC instance at any time + - release: Allows another file descriptor to be open, that is after current file descriptor is closed + - poll: Provides a method to monitor for SD-FEC Error events + - unlocked_ioctl: Provides the the following ioctl commands that allows the application configure the SD-FEC core: + + - :c:macro:`XSDFEC_START_DEV` + - :c:macro:`XSDFEC_STOP_DEV` + - :c:macro:`XSDFEC_GET_STATUS` + - :c:macro:`XSDFEC_SET_IRQ` + - :c:macro:`XSDFEC_SET_TURBO` + - :c:macro:`XSDFEC_ADD_LDPC_CODE_PARAMS` + - :c:macro:`XSDFEC_GET_CONFIG` + - :c:macro:`XSDFEC_SET_ORDER` + - :c:macro:`XSDFEC_SET_BYPASS` + - :c:macro:`XSDFEC_IS_ACTIVE` + - :c:macro:`XSDFEC_CLEAR_STATS` + - :c:macro:`XSDFEC_SET_DEFAULT_CONFIG` + + +Driver Usage +============ + + +Overview +-------- + +After opening the driver, the user should find out what operations need to be +performed to configure and activate the SD-FEC core and determine the +configuration of the driver. +The following outlines the flow the user should perform: + + - Determine Configuration + - Set the order, if not already configured as desired + - Set Turbo decode, LPDC encode or decode parameters, depending on how the + SD-FEC core is configured plus if the SD-FEC has not been configured for PL + initialization + - Enable interrupts, if not already enabled + - Bypass the SD-FEC core, if required + - Start the SD-FEC core if not already started + - Get the SD-FEC core status + - Monitor for interrupts + - Stop the SD-FEC core + + +Note: When monitoring for interrupts if a critical error is detected where a reset is required, the driver will be required to load the default configuration. + + +Determine Configuration +----------------------- + +Determine the configuration of the SD-FEC core by using the ioctl +:c:macro:`XSDFEC_GET_CONFIG`. + +Set the Order +------------- + +Setting the order determines how the order of Blocks can change from input to output. + +Setting the order is done by using the ioctl :c:macro:`XSDFEC_SET_ORDER` + +Setting the order can only be done if the following restrictions are met: + + - The ``state`` member of struct :c:type:`xsdfec_status ` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates the SD-FEC core has not STARTED + + +Add LDPC Codes +-------------- + +The following steps indicate how to add LDPC codes to the SD-FEC core: + + - Use the auto-generated parameters to fill the :c:type:`struct xsdfec_ldpc_params ` for the desired LDPC code. + - Set the SC, QA, and LA table offsets for the LPDC parameters and the parameters in the structure :c:type:`struct xsdfec_ldpc_params ` + - Set the desired Code Id value in the structure :c:type:`struct xsdfec_ldpc_params ` + - Add the LPDC Code Parameters using the ioctl :c:macro:`XSDFEC_ADD_LDPC_CODE_PARAMS` + - For the applied LPDC Code Parameter use the function :c:func:`xsdfec_calculate_shared_ldpc_table_entry_size` to calculate the size of shared LPDC code tables. This allows the user to determine the shared table usage so when selecting the table offsets for the next LDPC code parameters unused table areas can be selected. + - Repeat for each LDPC code parameter. + +Adding LDPC codes can only be done if the following restrictions are met: + + - The ``code`` member of :c:type:`struct xsdfec_config ` filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates the SD-FEC core is configured as LDPC + - The ``code_wr_protect`` of :c:type:`struct xsdfec_config ` filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates that write protection is not enabled + - The ``state`` member of struct :c:type:`xsdfec_status ` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates the SD-FEC core has not started + +Set Turbo Decode +---------------- + +Configuring the Turbo decode parameters is done by using the ioctl :c:macro:`XSDFEC_SET_TURBO` using auto-generated parameters to fill the :c:type:`struct xsdfec_turbo ` for the desired Turbo code. + +Adding Turbo decode can only be done if the following restrictions are met: + + - The ``code`` member of :c:type:`struct xsdfec_config ` filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates the SD-FEC core is configured as TURBO + - The ``state`` member of struct :c:type:`xsdfec_status ` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates the SD-FEC core has not STARTED + +Enable Interrupts +----------------- + +Enabling or disabling interrupts is done by using the ioctl :c:macro:`XSDFEC_SET_IRQ`. The members of the parameter passed, :c:type:`struct xsdfec_irq `, to the ioctl are used to set and clear different categories of interrupts. The category of interrupt is controlled as following: + + - ``enable_isr`` controls the ``tlast`` interrupts + - ``enable_ecc_isr`` controls the ECC interrupts + +If the ``code`` member of :c:type:`struct xsdfec_config ` filled by the ioctl :c:macro:`XSDFEC_GET_CONFIG` indicates the SD-FEC core is configured as TURBO then the enabling ECC errors is not required. + +Bypass the SD-FEC +----------------- + +Bypassing the SD-FEC is done by using the ioctl :c:macro:`XSDFEC_SET_BYPASS` + +Bypassing the SD-FEC can only be done if the following restrictions are met: + + - The ``state`` member of :c:type:`struct xsdfec_status ` filled by the ioctl :c:macro:`XSDFEC_GET_STATUS` indicates the SD-FEC core has not STARTED + +Start the SD-FEC core +--------------------- + +Start the SD-FEC core by using the ioctl :c:macro:`XSDFEC_START_DEV` + +Get SD-FEC Status +----------------- + +Get the SD-FEC status of the device by using the ioctl :c:macro:`XSDFEC_GET_STATUS`, which will fill the :c:type:`struct xsdfec_status ` + +Monitor for Interrupts +---------------------- + + - Use the poll system call to monitor for an interrupt. The poll system call waits for an interrupt to wake it up or times out if no interrupt occurs. + - On return Poll ``revents`` will indicate whether stats and/or state have been updated + - ``POLLPRI`` indicates a critical error and the user should use :c:macro:`XSDFEC_GET_STATUS` and :c:macro:`XSDFEC_GET_STATS` to confirm + - ``POLLRDNORM`` indicates a non-critical error has occurred and the user should use :c:macro:`XSDFEC_GET_STATS` to confirm + - Get stats by using the ioctl :c:macro:`XSDFEC_GET_STATS` + - For critical error the ``isr_err_count`` or ``uecc_count`` member of :c:type:`struct xsdfec_stats ` is non-zero + - For non-critical errors the ``cecc_count`` member of :c:type:`struct xsdfec_stats ` is non-zero + - Get state by using the ioctl :c:macro:`XSDFEC_GET_STATUS` + - For a critical error the ``state`` of :c:type:`xsdfec_status ` will indicate a Reset Is Required + - Clear stats by using the ioctl :c:macro:`XSDFEC_CLEAR_STATS` + +If a critical error is detected where a reset is required. The application is required to call the ioctl :c:macro:`XSDFEC_SET_DEFAULT_CONFIG`, after the reset and it is not required to call the ioctl :c:macro:`XSDFEC_STOP_DEV` + +Note: Using poll system call prevents busy looping using :c:macro:`XSDFEC_GET_STATS` and :c:macro:`XSDFEC_GET_STATUS` + +Stop the SD-FEC Core +--------------------- + +Stop the device by using the ioctl :c:macro:`XSDFEC_STOP_DEV` + +Set the Default Configuration +----------------------------- + +Load default configuration by using the ioctl :c:macro:`XSDFEC_SET_DEFAULT_CONFIG` to restore the driver. + +Limitations +----------- + +Users should not duplicate SD-FEC device file handlers, for example fork() or dup() a process that has a created an SD-FEC file handler. + +Driver IOCTLs +============== + +.. c:macro:: XSDFEC_START_DEV +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_START_DEV + +.. c:macro:: XSDFEC_STOP_DEV +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_STOP_DEV + +.. c:macro:: XSDFEC_GET_STATUS +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_GET_STATUS + +.. c:macro:: XSDFEC_SET_IRQ +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_SET_IRQ + +.. c:macro:: XSDFEC_SET_TURBO +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_SET_TURBO + +.. c:macro:: XSDFEC_ADD_LDPC_CODE_PARAMS +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_ADD_LDPC_CODE_PARAMS + +.. c:macro:: XSDFEC_GET_CONFIG +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_GET_CONFIG + +.. c:macro:: XSDFEC_SET_ORDER +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_SET_ORDER + +.. c:macro:: XSDFEC_SET_BYPASS +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_SET_BYPASS + +.. c:macro:: XSDFEC_IS_ACTIVE +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_IS_ACTIVE + +.. c:macro:: XSDFEC_CLEAR_STATS +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_CLEAR_STATS + +.. c:macro:: XSDFEC_GET_STATS +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_GET_STATS + +.. c:macro:: XSDFEC_SET_DEFAULT_CONFIG +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :doc: XSDFEC_SET_DEFAULT_CONFIG + +Driver Type Definitions +======================= + +.. kernel-doc:: include/uapi/misc/xilinx_sdfec.h + :internal: -- cgit From 2c1d7ffdf4fe34b79a373ea93584e71ae6ce62e2 Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Sat, 12 Oct 2019 19:11:09 +0200 Subject: docs: admin-guide: Sort the "unordered guides" to avoid merge conflicts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Since the "unordered guides" linked in admin-guide/index.rst are not supposed to be in any particular order, let's sort them alphabetically to avoid the risk of merge conflicts by spreading newly added lines more evenly. Signed-off-by: Jonathan Neuschäfer Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/index.rst | 64 ++++++++++++++++++------------------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 34cc20ee7f3a..545ea26364b7 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -57,60 +57,60 @@ configure specific aspects of kernel behavior to your liking. .. toctree:: :maxdepth: 1 - initrd - cgroup-v2 - cgroup-v1/index - serial-console - braille-console - parport - md - module-signing - rapidio - sysrq - unicode - vga-softcursor - binfmt-misc - mono - java - ras - bcache - blockdev/index - ext4 - binderfs - cifs/index - xfs - jfs - ufs - pm/index - thunderbolt - LSM/index - mm/index - namespaces/index - perf-security acpi/index aoe/index + auxdisplay/index + bcache + binderfs + binfmt-misc + blockdev/index + braille-console btmrvl + cgroup-v1/index + cgroup-v2 + cifs/index clearing-warn-once cpu-load cputopology device-mapper/index efi-stub + ext4 gpio/index highuid hw_random + initrd iostats + java + jfs kernel-per-CPU-kthreads laptops/index - auxdisplay/index lcd-panel-cgram ldm lockup-watchdogs + LSM/index + md + mm/index + module-signing + mono + namespaces/index numastat + parport + perf-security + pm/index pnp + rapidio + ras rtc + serial-console svga - wimax/index + sysrq + thunderbolt + ufs + unicode + vga-softcursor video-output + wimax/index + xfs .. only:: subproject and html -- cgit From d4300c4e4fd4395418aa9a8e2311702992dd18b2 Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Sat, 12 Oct 2019 19:11:10 +0200 Subject: docs: admin-guide: Move Dell RBU document from driver-api MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This document describes how an admin can use the dell_rbu driver, rather than any in-kernel API details. Signed-off-by: Jonathan Neuschäfer Acked-by: Andy Shevchenko Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/dell_rbu.rst | 128 +++++++++++++++++++++++++++++++++ Documentation/admin-guide/index.rst | 1 + Documentation/driver-api/dell_rbu.rst | 128 --------------------------------- Documentation/driver-api/index.rst | 1 - drivers/platform/x86/Kconfig | 2 +- drivers/platform/x86/dell_rbu.c | 2 +- 6 files changed, 131 insertions(+), 131 deletions(-) create mode 100644 Documentation/admin-guide/dell_rbu.rst delete mode 100644 Documentation/driver-api/dell_rbu.rst diff --git a/Documentation/admin-guide/dell_rbu.rst b/Documentation/admin-guide/dell_rbu.rst new file mode 100644 index 000000000000..5d1ce7bcd04d --- /dev/null +++ b/Documentation/admin-guide/dell_rbu.rst @@ -0,0 +1,128 @@ +============================================================= +Usage of the new open sourced rbu (Remote BIOS Update) driver +============================================================= + +Purpose +======= + +Document demonstrating the use of the Dell Remote BIOS Update driver. +for updating BIOS images on Dell servers and desktops. + +Scope +===== + +This document discusses the functionality of the rbu driver only. +It does not cover the support needed from applications to enable the BIOS to +update itself with the image downloaded in to the memory. + +Overview +======== + +This driver works with Dell OpenManage or Dell Update Packages for updating +the BIOS on Dell servers (starting from servers sold since 1999), desktops +and notebooks (starting from those sold in 2005). + +Please go to http://support.dell.com register and you can find info on +OpenManage and Dell Update packages (DUP). + +Libsmbios can also be used to update BIOS on Dell systems go to +http://linux.dell.com/libsmbios/ for details. + +Dell_RBU driver supports BIOS update using the monolithic image and packetized +image methods. In case of monolithic the driver allocates a contiguous chunk +of physical pages having the BIOS image. In case of packetized the app +using the driver breaks the image in to packets of fixed sizes and the driver +would place each packet in contiguous physical memory. The driver also +maintains a link list of packets for reading them back. + +If the dell_rbu driver is unloaded all the allocated memory is freed. + +The rbu driver needs to have an application (as mentioned above)which will +inform the BIOS to enable the update in the next system reboot. + +The user should not unload the rbu driver after downloading the BIOS image +or updating. + +The driver load creates the following directories under the /sys file system:: + + /sys/class/firmware/dell_rbu/loading + /sys/class/firmware/dell_rbu/data + /sys/devices/platform/dell_rbu/image_type + /sys/devices/platform/dell_rbu/data + /sys/devices/platform/dell_rbu/packet_size + +The driver supports two types of update mechanism; monolithic and packetized. +These update mechanism depends upon the BIOS currently running on the system. +Most of the Dell systems support a monolithic update where the BIOS image is +copied to a single contiguous block of physical memory. + +In case of packet mechanism the single memory can be broken in smaller chunks +of contiguous memory and the BIOS image is scattered in these packets. + +By default the driver uses monolithic memory for the update type. This can be +changed to packets during the driver load time by specifying the load +parameter image_type=packet. This can also be changed later as below:: + + echo packet > /sys/devices/platform/dell_rbu/image_type + +In packet update mode the packet size has to be given before any packets can +be downloaded. It is done as below:: + + echo XXXX > /sys/devices/platform/dell_rbu/packet_size + +In the packet update mechanism, the user needs to create a new file having +packets of data arranged back to back. It can be done as follows +The user creates packets header, gets the chunk of the BIOS image and +places it next to the packetheader; now, the packetheader + BIOS image chunk +added together should match the specified packet_size. This makes one +packet, the user needs to create more such packets out of the entire BIOS +image file and then arrange all these packets back to back in to one single +file. + +This file is then copied to /sys/class/firmware/dell_rbu/data. +Once this file gets to the driver, the driver extracts packet_size data from +the file and spreads it across the physical memory in contiguous packet_sized +space. + +This method makes sure that all the packets get to the driver in a single operation. + +In monolithic update the user simply get the BIOS image (.hdr file) and copies +to the data file as is without any change to the BIOS image itself. + +Do the steps below to download the BIOS image. + +1) echo 1 > /sys/class/firmware/dell_rbu/loading +2) cp bios_image.hdr /sys/class/firmware/dell_rbu/data +3) echo 0 > /sys/class/firmware/dell_rbu/loading + +The /sys/class/firmware/dell_rbu/ entries will remain till the following is +done. + +:: + + echo -1 > /sys/class/firmware/dell_rbu/loading + +Until this step is completed the driver cannot be unloaded. + +Also echoing either mono, packet or init in to image_type will free up the +memory allocated by the driver. + +If a user by accident executes steps 1 and 3 above without executing step 2; +it will make the /sys/class/firmware/dell_rbu/ entries disappear. + +The entries can be recreated by doing the following:: + + echo init > /sys/devices/platform/dell_rbu/image_type + +.. note:: echoing init in image_type does not change it original value. + +Also the driver provides /sys/devices/platform/dell_rbu/data readonly file to +read back the image downloaded. + +.. note:: + + After updating the BIOS image a user mode application needs to execute + code which sends the BIOS update request to the BIOS. So on the next reboot + the BIOS knows about the new image downloaded and it updates itself. + Also don't unload the rbu driver if the image has to be updated. + diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst index 545ea26364b7..4405b7485312 100644 --- a/Documentation/admin-guide/index.rst +++ b/Documentation/admin-guide/index.rst @@ -72,6 +72,7 @@ configure specific aspects of kernel behavior to your liking. clearing-warn-once cpu-load cputopology + dell_rbu device-mapper/index efi-stub ext4 diff --git a/Documentation/driver-api/dell_rbu.rst b/Documentation/driver-api/dell_rbu.rst deleted file mode 100644 index 5d1ce7bcd04d..000000000000 --- a/Documentation/driver-api/dell_rbu.rst +++ /dev/null @@ -1,128 +0,0 @@ -============================================================= -Usage of the new open sourced rbu (Remote BIOS Update) driver -============================================================= - -Purpose -======= - -Document demonstrating the use of the Dell Remote BIOS Update driver. -for updating BIOS images on Dell servers and desktops. - -Scope -===== - -This document discusses the functionality of the rbu driver only. -It does not cover the support needed from applications to enable the BIOS to -update itself with the image downloaded in to the memory. - -Overview -======== - -This driver works with Dell OpenManage or Dell Update Packages for updating -the BIOS on Dell servers (starting from servers sold since 1999), desktops -and notebooks (starting from those sold in 2005). - -Please go to http://support.dell.com register and you can find info on -OpenManage and Dell Update packages (DUP). - -Libsmbios can also be used to update BIOS on Dell systems go to -http://linux.dell.com/libsmbios/ for details. - -Dell_RBU driver supports BIOS update using the monolithic image and packetized -image methods. In case of monolithic the driver allocates a contiguous chunk -of physical pages having the BIOS image. In case of packetized the app -using the driver breaks the image in to packets of fixed sizes and the driver -would place each packet in contiguous physical memory. The driver also -maintains a link list of packets for reading them back. - -If the dell_rbu driver is unloaded all the allocated memory is freed. - -The rbu driver needs to have an application (as mentioned above)which will -inform the BIOS to enable the update in the next system reboot. - -The user should not unload the rbu driver after downloading the BIOS image -or updating. - -The driver load creates the following directories under the /sys file system:: - - /sys/class/firmware/dell_rbu/loading - /sys/class/firmware/dell_rbu/data - /sys/devices/platform/dell_rbu/image_type - /sys/devices/platform/dell_rbu/data - /sys/devices/platform/dell_rbu/packet_size - -The driver supports two types of update mechanism; monolithic and packetized. -These update mechanism depends upon the BIOS currently running on the system. -Most of the Dell systems support a monolithic update where the BIOS image is -copied to a single contiguous block of physical memory. - -In case of packet mechanism the single memory can be broken in smaller chunks -of contiguous memory and the BIOS image is scattered in these packets. - -By default the driver uses monolithic memory for the update type. This can be -changed to packets during the driver load time by specifying the load -parameter image_type=packet. This can also be changed later as below:: - - echo packet > /sys/devices/platform/dell_rbu/image_type - -In packet update mode the packet size has to be given before any packets can -be downloaded. It is done as below:: - - echo XXXX > /sys/devices/platform/dell_rbu/packet_size - -In the packet update mechanism, the user needs to create a new file having -packets of data arranged back to back. It can be done as follows -The user creates packets header, gets the chunk of the BIOS image and -places it next to the packetheader; now, the packetheader + BIOS image chunk -added together should match the specified packet_size. This makes one -packet, the user needs to create more such packets out of the entire BIOS -image file and then arrange all these packets back to back in to one single -file. - -This file is then copied to /sys/class/firmware/dell_rbu/data. -Once this file gets to the driver, the driver extracts packet_size data from -the file and spreads it across the physical memory in contiguous packet_sized -space. - -This method makes sure that all the packets get to the driver in a single operation. - -In monolithic update the user simply get the BIOS image (.hdr file) and copies -to the data file as is without any change to the BIOS image itself. - -Do the steps below to download the BIOS image. - -1) echo 1 > /sys/class/firmware/dell_rbu/loading -2) cp bios_image.hdr /sys/class/firmware/dell_rbu/data -3) echo 0 > /sys/class/firmware/dell_rbu/loading - -The /sys/class/firmware/dell_rbu/ entries will remain till the following is -done. - -:: - - echo -1 > /sys/class/firmware/dell_rbu/loading - -Until this step is completed the driver cannot be unloaded. - -Also echoing either mono, packet or init in to image_type will free up the -memory allocated by the driver. - -If a user by accident executes steps 1 and 3 above without executing step 2; -it will make the /sys/class/firmware/dell_rbu/ entries disappear. - -The entries can be recreated by doing the following:: - - echo init > /sys/devices/platform/dell_rbu/image_type - -.. note:: echoing init in image_type does not change it original value. - -Also the driver provides /sys/devices/platform/dell_rbu/data readonly file to -read back the image downloaded. - -.. note:: - - After updating the BIOS image a user mode application needs to execute - code which sends the BIOS update request to the BIOS. So on the next reboot - the BIOS knows about the new image downloaded and it updates itself. - Also don't unload the rbu driver if the image has to be updated. - diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 38e638abe3eb..c1e1b3f6d419 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -73,7 +73,6 @@ available subsections can be seen below. connector console dcdbas - dell_rbu edid eisa ipmb diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig index ae21d08c65e8..a890f47fbeec 100644 --- a/drivers/platform/x86/Kconfig +++ b/drivers/platform/x86/Kconfig @@ -259,7 +259,7 @@ config DELL_RBU DELL system. Note you need a Dell OpenManage or Dell Update package (DUP) supporting application to communicate with the BIOS regarding the new image for the image update to take effect. - See for more details on the driver. + See for more details on the driver. config FUJITSU_LAPTOP diff --git a/drivers/platform/x86/dell_rbu.c b/drivers/platform/x86/dell_rbu.c index 3691391fea6b..7d5453326b43 100644 --- a/drivers/platform/x86/dell_rbu.c +++ b/drivers/platform/x86/dell_rbu.c @@ -24,7 +24,7 @@ * on every time the packet data is written. This driver requires an * application to break the BIOS image in to fixed sized packet chunks. * - * See Documentation/driver-api/dell_rbu.rst for more info. + * See Documentation/admin-guide/dell_rbu.rst for more info. */ #include #include -- cgit From 80c730b564b49e994aed09f16f121168ed4deacd Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Sat, 12 Oct 2019 19:11:11 +0200 Subject: docs: admin-guide: dell_rbu: Rework the title MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Mention the driver name, which is also used in sysfs (dell_rbu) - Rewrite the title to be more concise Signed-off-by: Jonathan Neuschäfer Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/dell_rbu.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/admin-guide/dell_rbu.rst b/Documentation/admin-guide/dell_rbu.rst index 5d1ce7bcd04d..88898ca1d28d 100644 --- a/Documentation/admin-guide/dell_rbu.rst +++ b/Documentation/admin-guide/dell_rbu.rst @@ -1,6 +1,6 @@ -============================================================= -Usage of the new open sourced rbu (Remote BIOS Update) driver -============================================================= +========================================= +Dell Remote BIOS Update driver (dell_rbu) +========================================= Purpose ======= -- cgit From a016e092940f6607fb11ae07f4c90d7f9c6ad87a Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Sat, 12 Oct 2019 19:11:12 +0200 Subject: docs: admin-guide: dell_rbu: Improve formatting and spelling MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This improves readability a bit. Signed-off-by: Jonathan Neuschäfer Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/dell_rbu.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Documentation/admin-guide/dell_rbu.rst b/Documentation/admin-guide/dell_rbu.rst index 88898ca1d28d..085ea129e6ca 100644 --- a/Documentation/admin-guide/dell_rbu.rst +++ b/Documentation/admin-guide/dell_rbu.rst @@ -5,7 +5,7 @@ Dell Remote BIOS Update driver (dell_rbu) Purpose ======= -Document demonstrating the use of the Dell Remote BIOS Update driver. +Document demonstrating the use of the Dell Remote BIOS Update driver for updating BIOS images on Dell servers and desktops. Scope @@ -37,7 +37,7 @@ maintains a link list of packets for reading them back. If the dell_rbu driver is unloaded all the allocated memory is freed. -The rbu driver needs to have an application (as mentioned above)which will +The rbu driver needs to have an application (as mentioned above) which will inform the BIOS to enable the update in the next system reboot. The user should not unload the rbu driver after downloading the BIOS image @@ -71,7 +71,7 @@ be downloaded. It is done as below:: echo XXXX > /sys/devices/platform/dell_rbu/packet_size In the packet update mechanism, the user needs to create a new file having -packets of data arranged back to back. It can be done as follows +packets of data arranged back to back. It can be done as follows: The user creates packets header, gets the chunk of the BIOS image and places it next to the packetheader; now, the packetheader + BIOS image chunk added together should match the specified packet_size. This makes one @@ -114,7 +114,7 @@ The entries can be recreated by doing the following:: echo init > /sys/devices/platform/dell_rbu/image_type -.. note:: echoing init in image_type does not change it original value. +.. note:: echoing init in image_type does not change its original value. Also the driver provides /sys/devices/platform/dell_rbu/data readonly file to read back the image downloaded. -- cgit From 7867dbb4ea064a27b7d129d31c86a434f851b9df Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Fri, 4 Oct 2019 19:01:19 +0200 Subject: docs: driver-api: pti_intel_mid: Enable syntax highlighting for C code block MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This makes the code snippet more readable. Signed-off-by: Jonathan Neuschäfer Signed-off-by: Jonathan Corbet --- Documentation/driver-api/pti_intel_mid.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Documentation/driver-api/pti_intel_mid.rst b/Documentation/driver-api/pti_intel_mid.rst index 20f1cff42d5f..bacc2a4ee89f 100644 --- a/Documentation/driver-api/pti_intel_mid.rst +++ b/Documentation/driver-api/pti_intel_mid.rst @@ -49,7 +49,9 @@ but is not just blindly executing as 'root'. Keep in mind the use of ioctl(,TIOCSETD,) is not specific to the n_tracerouter and n_tracesink line discpline drivers but is a generic operation for a program to use a line discpline driver -on a tty port other than the default n_tty:: +on a tty port other than the default n_tty: + +.. code-block:: c /////////// To hook up n_tracerouter and n_tracesink ///////// -- cgit From cd15ed23d71719a86f1295af2995b10c64b99f35 Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Sat, 5 Oct 2019 22:01:22 +0200 Subject: docs: i2c: Fix SPDX-License-Identifier syntax MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ReST directives are introduced with two dots. Signed-off-by: Jonathan Neuschäfer Signed-off-by: Jonathan Corbet --- Documentation/i2c/busses/index.rst | 2 +- Documentation/i2c/index.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/i2c/busses/index.rst b/Documentation/i2c/busses/index.rst index 97ca4d510816..2a26e251a335 100644 --- a/Documentation/i2c/busses/index.rst +++ b/Documentation/i2c/busses/index.rst @@ -1,4 +1,4 @@ -. SPDX-License-Identifier: GPL-2.0 +.. SPDX-License-Identifier: GPL-2.0 =============== I2C Bus Drivers diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst index cd8d020f7ac5..a0fbaf6d0675 100644 --- a/Documentation/i2c/index.rst +++ b/Documentation/i2c/index.rst @@ -1,4 +1,4 @@ -. SPDX-License-Identifier: GPL-2.0 +.. SPDX-License-Identifier: GPL-2.0 =================== I2C/SMBus Subsystem -- cgit From d8fb03e1ea64e78b9d2af677e6614c2d88e842d2 Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Sat, 5 Oct 2019 22:01:23 +0200 Subject: docs: w1: Fix SPDX-License-Identifier syntax MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ReST directives are introduced with two dots. Signed-off-by: Jonathan Neuschäfer Signed-off-by: Jonathan Corbet --- Documentation/w1/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/w1/index.rst b/Documentation/w1/index.rst index 57cba81865e2..156279f17553 100644 --- a/Documentation/w1/index.rst +++ b/Documentation/w1/index.rst @@ -1,4 +1,4 @@ -. SPDX-License-Identifier: GPL-2.0 +.. SPDX-License-Identifier: GPL-2.0 ================ 1-Wire Subsystem -- cgit From d94cdae138d3199569e11593bf33cf8cdbb0bf84 Mon Sep 17 00:00:00 2001 From: Albert Vaca Cintora Date: Wed, 16 Oct 2019 22:13:37 +0200 Subject: Updated iostats docs Previous docs mentioned 11 unsigned long fields, when the reality is that we have 15 fields with a mix of unsigned long and unsigned int. Signed-off-by: Albert Vaca Cintora Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/iostats.rst | 47 ++++++++++++++++++----------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/Documentation/admin-guide/iostats.rst b/Documentation/admin-guide/iostats.rst index 5d63b18bd6d1..321aae8d7e10 100644 --- a/Documentation/admin-guide/iostats.rst +++ b/Documentation/admin-guide/iostats.rst @@ -46,78 +46,79 @@ each snapshot of your disk statistics. In 2.4, the statistics fields are those after the device name. In the above example, the first field of statistics would be 446216. By contrast, in 2.6+ if you look at ``/sys/block/hda/stat``, you'll -find just the eleven fields, beginning with 446216. If you look at -``/proc/diskstats``, the eleven fields will be preceded by the major and +find just the 15 fields, beginning with 446216. If you look at +``/proc/diskstats``, the 15 fields will be preceded by the major and minor device numbers, and device name. Each of these formats provides -eleven fields of statistics, each meaning exactly the same things. +15 fields of statistics, each meaning exactly the same things. All fields except field 9 are cumulative since boot. Field 9 should go to zero as I/Os complete; all others only increase (unless they -overflow and wrap). Yes, these are (32-bit or 64-bit) unsigned long -(native word size) numbers, and on a very busy or long-lived system they -may wrap. Applications should be prepared to deal with that; unless -your observations are measured in large numbers of minutes or hours, -they should not wrap twice before you notice them. +overflow and wrap). Wrapping might eventually occur on a very busy +or long-lived system; so applications should be prepared to deal with +it. Regarding wrapping, the types of the fields are either unsigned +int (32 bit) or unsigned long (32-bit or 64-bit, depending on your +machine) as noted per-field below. Unless your observations are very +spread in time, these fields should not wrap twice before you notice it. Each set of stats only applies to the indicated device; if you want system-wide stats you'll have to find all the devices and sum them all up. -Field 1 -- # of reads completed +Field 1 -- # of reads completed (unsigned long) This is the total number of reads completed successfully. -Field 2 -- # of reads merged, field 6 -- # of writes merged +Field 2 -- # of reads merged, field 6 -- # of writes merged (unsigned long) Reads and writes which are adjacent to each other may be merged for efficiency. Thus two 4K reads may become one 8K read before it is ultimately handed to the disk, and so it will be counted (and queued) as only one I/O. This field lets you know how often this was done. -Field 3 -- # of sectors read +Field 3 -- # of sectors read (unsigned long) This is the total number of sectors read successfully. -Field 4 -- # of milliseconds spent reading +Field 4 -- # of milliseconds spent reading (unsigned int) This is the total number of milliseconds spent by all reads (as measured from __make_request() to end_that_request_last()). -Field 5 -- # of writes completed +Field 5 -- # of writes completed (unsigned long) This is the total number of writes completed successfully. -Field 6 -- # of writes merged +Field 6 -- # of writes merged (unsigned long) See the description of field 2. -Field 7 -- # of sectors written +Field 7 -- # of sectors written (unsigned long) This is the total number of sectors written successfully. -Field 8 -- # of milliseconds spent writing +Field 8 -- # of milliseconds spent writing (unsigned int) This is the total number of milliseconds spent by all writes (as measured from __make_request() to end_that_request_last()). -Field 9 -- # of I/Os currently in progress +Field 9 -- # of I/Os currently in progress (unsigned int) The only field that should go to zero. Incremented as requests are given to appropriate struct request_queue and decremented as they finish. -Field 10 -- # of milliseconds spent doing I/Os +Field 10 -- # of milliseconds spent doing I/Os (unsigned int) This field increases so long as field 9 is nonzero. Since 5.0 this field counts jiffies when at least one request was started or completed. If request runs more than 2 jiffies then some I/O time will not be accounted unless there are other requests. -Field 11 -- weighted # of milliseconds spent doing I/Os +Field 11 -- weighted # of milliseconds spent doing I/Os (unsigned int) This field is incremented at each I/O start, I/O completion, I/O merge, or read of these stats by the number of I/Os in progress (field 9) times the number of milliseconds spent doing I/O since the last update of this field. This can provide an easy measure of both I/O completion time and the backlog that may be accumulating. -Field 12 -- # of discards completed +Field 12 -- # of discards completed (unsigned long) This is the total number of discards completed successfully. -Field 13 -- # of discards merged +Field 13 -- # of discards merged (unsigned long) See the description of field 2 -Field 14 -- # of sectors discarded +Field 14 -- # of sectors discarded (unsigned long) This is the total number of sectors discarded successfully. -Field 15 -- # of milliseconds spent discarding +Field 15 -- # of milliseconds spent discarding (unsigned int) This is the total number of milliseconds spent by all discards (as measured from __make_request() to end_that_request_last()). -- cgit From 85c2a0edcd5f4a029e6bad37e69b923d457e6214 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 4 Oct 2019 10:21:55 -0600 Subject: docs: remove :c:func: from genericirq.rst As of 5.3, the automarkup extension will do the right thing with function() notation, so we don't need to clutter the text with :c:func: invocations. So remove them. Signed-off-by: Jonathan Corbet --- Documentation/core-api/genericirq.rst | 50 +++++++++++++++++------------------ 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/Documentation/core-api/genericirq.rst b/Documentation/core-api/genericirq.rst index 4da67b65cecf..2e6c99e3ce3b 100644 --- a/Documentation/core-api/genericirq.rst +++ b/Documentation/core-api/genericirq.rst @@ -26,7 +26,7 @@ Rationale ========= The original implementation of interrupt handling in Linux uses the -:c:func:`__do_IRQ` super-handler, which is able to deal with every type of +__do_IRQ() super-handler, which is able to deal with every type of interrupt logic. Originally, Russell King identified different types of handlers to build @@ -43,7 +43,7 @@ During the implementation we identified another type: - Fast EOI type -In the SMP world of the :c:func:`__do_IRQ` super-handler another type was +In the SMP world of the __do_IRQ() super-handler another type was identified: - Per CPU type @@ -83,7 +83,7 @@ IRQ-flow implementation for 'level type' interrupts and add a (sub)architecture specific 'edge type' implementation. To make the transition to the new model easier and prevent the breakage -of existing implementations, the :c:func:`__do_IRQ` super-handler is still +of existing implementations, the __do_IRQ() super-handler is still available. This leads to a kind of duality for the time being. Over time the new model should be used in more and more architectures, as it enables smaller and cleaner IRQ subsystems. It's deprecated for three @@ -116,7 +116,7 @@ status information and pointers to the interrupt flow method and the interrupt chip structure which are assigned to this interrupt. Whenever an interrupt triggers, the low-level architecture code calls -into the generic interrupt code by calling :c:func:`desc->handle_irq`. This +into the generic interrupt code by calling desc->handle_irq(). This high-level IRQ handling function only uses desc->irq_data.chip primitives referenced by the assigned chip descriptor structure. @@ -125,27 +125,27 @@ High-level Driver API The high-level Driver API consists of following functions: -- :c:func:`request_irq` +- request_irq() -- :c:func:`free_irq` +- free_irq() -- :c:func:`disable_irq` +- disable_irq() -- :c:func:`enable_irq` +- enable_irq() -- :c:func:`disable_irq_nosync` (SMP only) +- disable_irq_nosync() (SMP only) -- :c:func:`synchronize_irq` (SMP only) +- synchronize_irq() (SMP only) -- :c:func:`irq_set_irq_type` +- irq_set_irq_type() -- :c:func:`irq_set_irq_wake` +- irq_set_irq_wake() -- :c:func:`irq_set_handler_data` +- irq_set_handler_data() -- :c:func:`irq_set_chip` +- irq_set_chip() -- :c:func:`irq_set_chip_data` +- irq_set_chip_data() See the autogenerated function documentation for details. @@ -154,19 +154,19 @@ High-level IRQ flow handlers The generic layer provides a set of pre-defined irq-flow methods: -- :c:func:`handle_level_irq` +- handle_level_irq() -- :c:func:`handle_edge_irq` +- handle_edge_irq() -- :c:func:`handle_fasteoi_irq` +- handle_fasteoi_irq() -- :c:func:`handle_simple_irq` +- handle_simple_irq() -- :c:func:`handle_percpu_irq` +- handle_percpu_irq() -- :c:func:`handle_edge_eoi_irq` +- handle_edge_eoi_irq() -- :c:func:`handle_bad_irq` +- handle_bad_irq() The interrupt flow handlers (either pre-defined or architecture specific) are assigned to specific interrupts by the architecture either @@ -325,14 +325,14 @@ Delayed interrupt disable This per interrupt selectable feature, which was introduced by Russell King in the ARM interrupt implementation, does not mask an interrupt at -the hardware level when :c:func:`disable_irq` is called. The interrupt is kept +the hardware level when disable_irq() is called. The interrupt is kept enabled and is masked in the flow handler when an interrupt event happens. This prevents losing edge interrupts on hardware which does not store an edge interrupt event while the interrupt is disabled at the hardware level. When an interrupt arrives while the IRQ_DISABLED flag is set, then the interrupt is masked at the hardware level and the IRQ_PENDING bit is set. When the interrupt is re-enabled by -:c:func:`enable_irq` the pending bit is checked and if it is set, the interrupt +enable_irq() the pending bit is checked and if it is set, the interrupt is resent either via hardware or by a software resend mechanism. (It's necessary to enable CONFIG_HARDIRQS_SW_RESEND when you want to use the delayed interrupt disable feature and your hardware is not capable @@ -369,7 +369,7 @@ handler(s) to use these basic units of low-level functionality. __do_IRQ entry point ==================== -The original implementation :c:func:`__do_IRQ` was an alternative entry point +The original implementation __do_IRQ() was an alternative entry point for all types of interrupts. It no longer exists. This handler turned out to be not suitable for all interrupt hardware -- cgit From dc5fcc51a5d1ab740e906decc486bfb663e74444 Mon Sep 17 00:00:00 2001 From: Harald Seiler Date: Tue, 22 Oct 2019 21:57:48 +0200 Subject: docs: driver-api: Remove reference to sgi-ioc4 Commit f7bc6e42bf12 ("drivers: remove the SGI SN2 IOC4 base support") removed support for SGI SN2 IOC4 and the relevant documentation files. Remove a leftover reference in the toctree of the driver-api documentation to fix this sphinx error: Documentation/driver-api/index.rst:14: WARNING: toctree contains reference to nonexisting document 'driver-api/sgi-ioc4' Fixes: f7bc6e42bf12 ("drivers: remove the SGI SN2 IOC4 base support") Signed-off-by: Harald Seiler Signed-off-by: Jonathan Corbet --- Documentation/driver-api/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index c1e1b3f6d419..46d6a165b5a5 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -92,7 +92,6 @@ available subsections can be seen below. pwm rfkill serial/index - sgi-ioc4 sm501 smsc_ece1099 switchtec -- cgit From 98919f4c9a3421695b182f0244b34b62045d08ff Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Mon, 21 Oct 2019 17:06:45 +0200 Subject: Documentation: debugfs: Document debugfs helper for unsigned long values When debugfs_create_ulong() was added, it was not documented. Fixes: c23fe83138ed7b11 ("debugfs: Add debugfs_create_ulong()") Signed-off-by: Geert Uytterhoeven Acked-by: Viresh Kumar Signed-off-by: Jonathan Corbet --- Documentation/filesystems/debugfs.txt | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/Documentation/filesystems/debugfs.txt b/Documentation/filesystems/debugfs.txt index 9e27c843d00e..2ca99152cb6e 100644 --- a/Documentation/filesystems/debugfs.txt +++ b/Documentation/filesystems/debugfs.txt @@ -93,8 +93,8 @@ the following functions can be used instead: These functions are useful as long as the developer knows the size of the value to be exported. Some types can have different widths on different -architectures, though, complicating the situation somewhat. There is a -function meant to help out in one special case: +architectures, though, complicating the situation somewhat. There are +functions meant to help out in such special cases: struct dentry *debugfs_create_size_t(const char *name, umode_t mode, struct dentry *parent, @@ -103,6 +103,12 @@ function meant to help out in one special case: As might be expected, this function will create a debugfs file to represent a variable of type size_t. +Similarly, there is a helper for variables of type unsigned long: + + struct dentry *debugfs_create_ulong(const char *name, umode_t mode, + struct dentry *parent, + unsigned long *value); + Boolean values can be placed in debugfs with: struct dentry *debugfs_create_bool(const char *name, umode_t mode, -- cgit From b275fb6013df5d9c17702491bf4533d559561515 Mon Sep 17 00:00:00 2001 From: Chris Packham Date: Mon, 21 Oct 2019 14:43:36 +1300 Subject: docs: ioctl: fix typo "pointres" should be "pointers". Signed-off-by: Chris Packham Signed-off-by: Jonathan Corbet --- Documentation/process/botching-up-ioctls.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/process/botching-up-ioctls.rst b/Documentation/process/botching-up-ioctls.rst index ac697fef3545..2d4829b2fb09 100644 --- a/Documentation/process/botching-up-ioctls.rst +++ b/Documentation/process/botching-up-ioctls.rst @@ -46,7 +46,7 @@ will need to add a 32-bit compat layer: conversion or worse, fiddle the raw __u64 through your code since that diminishes the checking tools like sparse can provide. The macro u64_to_user_ptr can be used in the kernel to avoid warnings about integers - and pointres of different sizes. + and pointers of different sizes. Basics -- cgit From d41abfd7ae33cd3c1d9189438937d61cb75e690a Mon Sep 17 00:00:00 2001 From: Andre Azevedo Date: Sat, 26 Oct 2019 12:55:54 -0700 Subject: Documentation/scheduler: fix links in sched-stats The rain.com domain recently moved to pdxhosts.com, making the scheduler documentation point to broken links. Fix the links in the scheduler documentation. CC: Rick Lindsley Signed-off-by: Andre Azevedo Signed-off-by: Jonathan Corbet --- Documentation/scheduler/sched-stats.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/scheduler/sched-stats.rst b/Documentation/scheduler/sched-stats.rst index 0cb0aa714545..dd9b99a025f7 100644 --- a/Documentation/scheduler/sched-stats.rst +++ b/Documentation/scheduler/sched-stats.rst @@ -28,7 +28,7 @@ of these will need to start with a baseline observation and then calculate the change in the counters at each subsequent observation. A perl script which does this for many of the fields is available at - http://eaglet.rain.com/rick/linux/schedstat/ + http://eaglet.pdxhosts.com/rick/linux/schedstat/ Note that any such script will necessarily be version-specific, as the main reason to change versions is changes in the output format. For those wishing @@ -164,4 +164,4 @@ report on how well a particular process or set of processes is faring under the scheduler's policies. A simple version of such a program is available at - http://eaglet.rain.com/rick/linux/schedstat/v12/latency.c + http://eaglet.pdxhosts.com/rick/linux/schedstat/v12/latency.c -- cgit From ef8330fe02710046d7b6ce271d821926dd2769e8 Mon Sep 17 00:00:00 2001 From: Chris Packham Date: Fri, 25 Oct 2019 08:50:14 +1300 Subject: docs/core-api: memory-allocation: fix typo "on the safe size" should be "on the safe side". Signed-off-by: Chris Packham Acked-by: Mike Rapoport Reviewed-by: Matthew Wilcox (Oracle) Signed-off-by: Jonathan Corbet --- Documentation/core-api/memory-allocation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/core-api/memory-allocation.rst b/Documentation/core-api/memory-allocation.rst index 939e3dfc86e9..dcf851b4520f 100644 --- a/Documentation/core-api/memory-allocation.rst +++ b/Documentation/core-api/memory-allocation.rst @@ -88,7 +88,7 @@ Selecting memory allocator ========================== The most straightforward way to allocate memory is to use a function -from the :c:func:`kmalloc` family. And, to be on the safe size it's +from the :c:func:`kmalloc` family. And, to be on the safe side it's best to use routines that set memory to zero, like :c:func:`kzalloc`. If you need to allocate memory for an array, there are :c:func:`kmalloc_array` and :c:func:`kcalloc` helpers. -- cgit From 094ef1c9fbeac0e4404d66a053ace6d909386507 Mon Sep 17 00:00:00 2001 From: Chris Packham Date: Fri, 25 Oct 2019 08:50:15 +1300 Subject: docs/core-api: memory-allocation: remove uses of c:func: These are no longer needed as the documentation build will automatically add the cross references. Signed-off-by: Chris Packham Acked-by: Mike Rapoport Reviewed-by: Matthew Wilcox (Oracle) Signed-off-by: Jonathan Corbet --- Documentation/core-api/memory-allocation.rst | 49 +++++++++++++--------------- 1 file changed, 23 insertions(+), 26 deletions(-) diff --git a/Documentation/core-api/memory-allocation.rst b/Documentation/core-api/memory-allocation.rst index dcf851b4520f..e47d48655085 100644 --- a/Documentation/core-api/memory-allocation.rst +++ b/Documentation/core-api/memory-allocation.rst @@ -88,10 +88,10 @@ Selecting memory allocator ========================== The most straightforward way to allocate memory is to use a function -from the :c:func:`kmalloc` family. And, to be on the safe side it's -best to use routines that set memory to zero, like -:c:func:`kzalloc`. If you need to allocate memory for an array, there -are :c:func:`kmalloc_array` and :c:func:`kcalloc` helpers. +from the kmalloc() family. And, to be on the safe side it's best to use +routines that set memory to zero, like kzalloc(). If you need to +allocate memory for an array, there are kmalloc_array() and kcalloc() +helpers. The maximal size of a chunk that can be allocated with `kmalloc` is limited. The actual limit depends on the hardware and the kernel @@ -102,29 +102,26 @@ The address of a chunk allocated with `kmalloc` is aligned to at least ARCH_KMALLOC_MINALIGN bytes. For sizes which are a power of two, the alignment is also guaranteed to be at least the respective size. -For large allocations you can use :c:func:`vmalloc` and -:c:func:`vzalloc`, or directly request pages from the page -allocator. The memory allocated by `vmalloc` and related functions is -not physically contiguous. +For large allocations you can use vmalloc() and vzalloc(), or directly +request pages from the page allocator. The memory allocated by `vmalloc` +and related functions is not physically contiguous. If you are not sure whether the allocation size is too large for -`kmalloc`, it is possible to use :c:func:`kvmalloc` and its -derivatives. It will try to allocate memory with `kmalloc` and if the -allocation fails it will be retried with `vmalloc`. There are -restrictions on which GFP flags can be used with `kvmalloc`; please -see :c:func:`kvmalloc_node` reference documentation. Note that -`kvmalloc` may return memory that is not physically contiguous. +`kmalloc`, it is possible to use kvmalloc() and its derivatives. It will +try to allocate memory with `kmalloc` and if the allocation fails it +will be retried with `vmalloc`. There are restrictions on which GFP +flags can be used with `kvmalloc`; please see kvmalloc_node() reference +documentation. Note that `kvmalloc` may return memory that is not +physically contiguous. If you need to allocate many identical objects you can use the slab -cache allocator. The cache should be set up with -:c:func:`kmem_cache_create` or :c:func:`kmem_cache_create_usercopy` -before it can be used. The second function should be used if a part of -the cache might be copied to the userspace. After the cache is -created :c:func:`kmem_cache_alloc` and its convenience wrappers can -allocate memory from that cache. - -When the allocated memory is no longer needed it must be freed. You -can use :c:func:`kvfree` for the memory allocated with `kmalloc`, -`vmalloc` and `kvmalloc`. The slab caches should be freed with -:c:func:`kmem_cache_free`. And don't forget to destroy the cache with -:c:func:`kmem_cache_destroy`. +cache allocator. The cache should be set up with kmem_cache_create() or +kmem_cache_create_usercopy() before it can be used. The second function +should be used if a part of the cache might be copied to the userspace. +After the cache is created kmem_cache_alloc() and its convenience +wrappers can allocate memory from that cache. + +When the allocated memory is no longer needed it must be freed. You can +use kvfree() for the memory allocated with `kmalloc`, `vmalloc` and +`kvmalloc`. The slab caches should be freed with kmem_cache_free(). And +don't forget to destroy the cache with kmem_cache_destroy(). -- cgit From 1c16b3d58681b583157a1b74c4c4dd96a08f5931 Mon Sep 17 00:00:00 2001 From: Chris Packham Date: Fri, 25 Oct 2019 08:50:16 +1300 Subject: docs/core-api: memory-allocation: mention size helpers Mention struct_size(), array_size() and array3_size() in the same place as kmalloc() and friends. Signed-off-by: Chris Packham Acked-by: Mike Rapoport Reviewed-by: Matthew Wilcox (Oracle) Signed-off-by: Jonathan Corbet --- Documentation/core-api/memory-allocation.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Documentation/core-api/memory-allocation.rst b/Documentation/core-api/memory-allocation.rst index e47d48655085..4aa82ddd01b8 100644 --- a/Documentation/core-api/memory-allocation.rst +++ b/Documentation/core-api/memory-allocation.rst @@ -91,7 +91,8 @@ The most straightforward way to allocate memory is to use a function from the kmalloc() family. And, to be on the safe side it's best to use routines that set memory to zero, like kzalloc(). If you need to allocate memory for an array, there are kmalloc_array() and kcalloc() -helpers. +helpers. The helpers struct_size(), array_size() and array3_size() can +be used to safely calculate object sizes without overflowing. The maximal size of a chunk that can be allocated with `kmalloc` is limited. The actual limit depends on the hardware and the kernel -- cgit From 43756e347f213b68f884c3b4082e95e7f98204f1 Mon Sep 17 00:00:00 2001 From: Jonathan Neuschäfer Date: Thu, 7 Nov 2019 14:41:33 +0100 Subject: scripts/kernel-doc: Add support for named variable macro arguments MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Currently, when kernel-doc encounters a macro with a named variable argument[1], such as this: #define hlist_for_each_entry_rcu(pos, head, member, cond...) ... it expects the variable argument to be documented as `cond...`, rather than `cond`. This is semantically wrong, because the name (as used in the macro body) is actually `cond`. With this patch, kernel-doc will accept the name without dots (`cond` in the example above) in doc comments, and warn if the name with dots (`cond...`) is used and verbose mode[2] is enabled. The support for the `cond...` syntax can be removed later, when the documentation of all such macros has been switched to the new syntax. Testing this patch on top of v5.4-rc6, `make htmldocs` shows a few changes in log output and HTML output: 1) The following warnings[3] are eliminated: ./include/linux/rculist.h:374: warning: Excess function parameter 'cond' description in 'list_for_each_entry_rcu' ./include/linux/rculist.h:651: warning: Excess function parameter 'cond' description in 'hlist_for_each_entry_rcu' 2) For list_for_each_entry_rcu and hlist_for_each_entry_rcu, the correct description is shown 3) Named variable arguments are shown without dots [1]: https://gcc.gnu.org/onlinedocs/cpp/Variadic-Macros.html [2]: scripts/kernel-doc -v [3]: See also https://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git/commit/?h=dev&id=5bc4bc0d6153617eabde275285b7b5a8137fdf3c Signed-off-by: Jonathan Neuschäfer Tested-by: Paul E. McKenney Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index a529375c8536..f2d73f04e71d 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -1450,6 +1450,10 @@ sub push_parameter($$$$) { # handles unnamed variable parameters $param = "..."; } + elsif ($param =~ /\w\.\.\.$/) { + # for named variable parameters of the form `x...`, remove the dots + $param =~ s/\.\.\.$//; + } if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") { $parameterdescs{$param} = "variable arguments"; } @@ -1937,6 +1941,18 @@ sub process_name($$) { sub process_body($$) { my $file = shift; + # Until all named variable macro parameters are + # documented using the bare name (`x`) rather than with + # dots (`x...`), strip the dots: + if ($section =~ /\w\.\.\.$/) { + $section =~ s/\.\.\.$//; + + if ($verbose) { + print STDERR "${file}:$.: warning: Variable macro arguments should be documented without dots\n"; + ++$warnings; + } + } + if (/$doc_sect/i) { # case insensitive for supported section names $newsection = $1; $newcontents = $2; -- cgit From 67dd7d87d4dde482556b2e1b31d09bf19438184f Mon Sep 17 00:00:00 2001 From: Louis Taylor Date: Fri, 1 Nov 2019 19:33:14 +0000 Subject: docs: driver-api: make interconnect title quieter This makes it consistent with the other headings in the Linux driver implementer's API guide. Signed-off-by: Louis Taylor Signed-off-by: Jonathan Corbet --- Documentation/driver-api/interconnect.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/driver-api/interconnect.rst b/Documentation/driver-api/interconnect.rst index c3e004893796..cdeb5825f314 100644 --- a/Documentation/driver-api/interconnect.rst +++ b/Documentation/driver-api/interconnect.rst @@ -1,7 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 ===================================== -GENERIC SYSTEM INTERCONNECT SUBSYSTEM +Generic System Interconnect Subsystem ===================================== Introduction -- cgit From 0d0da9aa03a178d343f64f3bd7d545b0d3bf8b7e Mon Sep 17 00:00:00 2001 From: Louis Taylor Date: Sat, 2 Nov 2019 18:45:11 +0000 Subject: scripts/sphinx-pre-install: fix Arch latexmk dependency On Arch Linux, latexmk is installed in the texlive-core package. Signed-off-by: Louis Taylor Signed-off-by: Jonathan Corbet --- scripts/sphinx-pre-install | 1 + 1 file changed, 1 insertion(+) diff --git a/scripts/sphinx-pre-install b/scripts/sphinx-pre-install index 68385fa62ff4..470ccfe678aa 100755 --- a/scripts/sphinx-pre-install +++ b/scripts/sphinx-pre-install @@ -520,6 +520,7 @@ sub give_arch_linux_hints() "dot" => "graphviz", "convert" => "imagemagick", "xelatex" => "texlive-bin", + "latexmk" => "texlive-core", "rsvg-convert" => "extra/librsvg", ); -- cgit From 73eb802ad97f814aa86d83cfd1d139cadbb4f0fb Mon Sep 17 00:00:00 2001 From: Masanari Iida Date: Fri, 1 Nov 2019 13:04:37 +0900 Subject: docs: admin-guide: Fix min value of threads-max in kernel.rst Since following patch was merged 5.4-rc3, minimum value for threads-max changed to 1. kernel/sysctl.c: do not override max_threads provided by userspace b0f53dbc4bc4c371f38b14c391095a3bb8a0bb40 Fixes: b0f53dbc4bc4 ("kernel/sysctl.c: do not override max_threads provided by userspace") Signed-off-by: Masanari Iida Acked-by: Michal Hocko Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/sysctl/kernel.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 6e0da29e55f1..17a9daf7949d 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -1103,7 +1103,7 @@ During initialization the kernel sets this value such that even if the maximum number of threads is created, the thread structures occupy only a part (1/8th) of the available RAM pages. -The minimum value that can be written to threads-max is 20. +The minimum value that can be written to threads-max is 1. The maximum value that can be written to threads-max is given by the constant FUTEX_TID_MASK (0x3fffffff). -- cgit From e80d89380c5a8553f208d002ee0f7877ed08eb6c Mon Sep 17 00:00:00 2001 From: Masanari Iida Date: Fri, 1 Nov 2019 13:04:38 +0900 Subject: docs: admin-guide: Remove threads-max auto-tuning Since following path was merged in 5.4-rc3, auto-tuning feature in threads-max does not exist any more. Fix the admin-guide document as is. kernel/sysctl.c: do not override max_threads provided by userspace b0f53dbc4bc4c371f38b14c391095a3bb8a0bb40 Fixes: b0f53dbc4bc4 ("kernel/sysctl.c: do not override max_threads provided by userspace") Signed-off-by: Masanari Iida Acked-by: Michal Hocko Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/sysctl/kernel.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Documentation/admin-guide/sysctl/kernel.rst b/Documentation/admin-guide/sysctl/kernel.rst index 17a9daf7949d..def074807cee 100644 --- a/Documentation/admin-guide/sysctl/kernel.rst +++ b/Documentation/admin-guide/sysctl/kernel.rst @@ -1111,10 +1111,6 @@ constant FUTEX_TID_MASK (0x3fffffff). If a value outside of this range is written to threads-max an error EINVAL occurs. -The value written is checked against the available RAM pages. If the -thread structures would occupy too much (more than 1/8th) of the -available RAM pages threads-max is reduced accordingly. - unknown_nmi_panic: ================== -- cgit From 36bc683dde0af61c6e677e5832ad4380771380d3 Mon Sep 17 00:00:00 2001 From: Changbin Du Date: Thu, 31 Oct 2019 21:52:45 +0800 Subject: kernel-doc: rename the kernel-doc directive 'functions' to 'identifiers' The 'functions' directive is not only for functions, but also works for structs/unions. So the name is misleading. This patch renames it to 'identifiers', which specific the functions/types to be included in documentation. We keep the old name as an alias of the new one before all documentation are updated. Signed-off-by: Changbin Du Signed-off-by: Jonathan Corbet --- Documentation/doc-guide/kernel-doc.rst | 29 ++++++++++++++++------------- Documentation/sphinx/kerneldoc.py | 17 +++++++++++------ 2 files changed, 27 insertions(+), 19 deletions(-) diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index 192c36af39e2..fff6604631ea 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -476,6 +476,22 @@ internal: *[source-pattern ...]* .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c :internal: +identifiers: *[ function/type ...]* + Include documentation for each *function* and *type* in *source*. + If no *function* is specified, the documentation for all functions + and types in the *source* will be included. + + Examples:: + + .. kernel-doc:: lib/bitmap.c + :identifiers: bitmap_parselist bitmap_parselist_user + + .. kernel-doc:: lib/idr.c + :identifiers: + +functions: *[ function/type ...]* + This is an alias of the 'identifiers' directive and deprecated. + doc: *title* Include documentation for the ``DOC:`` paragraph identified by *title* in *source*. Spaces are allowed in *title*; do not quote the *title*. The *title* @@ -488,19 +504,6 @@ doc: *title* .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c :doc: High Definition Audio over HDMI and Display Port -functions: *[ function ...]* - Include documentation for each *function* in *source*. - If no *function* is specified, the documentation for all functions - and types in the *source* will be included. - - Examples:: - - .. kernel-doc:: lib/bitmap.c - :functions: bitmap_parselist bitmap_parselist_user - - .. kernel-doc:: lib/idr.c - :functions: - Without options, the kernel-doc directive includes all documentation comments from the source file. diff --git a/Documentation/sphinx/kerneldoc.py b/Documentation/sphinx/kerneldoc.py index 1159405cb920..4bcbd6ae01cd 100644 --- a/Documentation/sphinx/kerneldoc.py +++ b/Documentation/sphinx/kerneldoc.py @@ -59,9 +59,10 @@ class KernelDocDirective(Directive): optional_arguments = 4 option_spec = { 'doc': directives.unchanged_required, - 'functions': directives.unchanged, 'export': directives.unchanged, 'internal': directives.unchanged, + 'identifiers': directives.unchanged, + 'functions': directives.unchanged, } has_content = False @@ -77,6 +78,10 @@ class KernelDocDirective(Directive): tab_width = self.options.get('tab-width', self.state.document.settings.tab_width) + # 'function' is an alias of 'identifiers' + if 'functions' in self.options: + self.options['identifiers'] = self.options.get('functions') + # FIXME: make this nicer and more robust against errors if 'export' in self.options: cmd += ['-export'] @@ -86,11 +91,11 @@ class KernelDocDirective(Directive): export_file_patterns = str(self.options.get('internal')).split() elif 'doc' in self.options: cmd += ['-function', str(self.options.get('doc'))] - elif 'functions' in self.options: - functions = self.options.get('functions').split() - if functions: - for f in functions: - cmd += ['-function', f] + elif 'identifiers' in self.options: + identifiers = self.options.get('identifiers').split() + if identifiers: + for i in identifiers: + cmd += ['-function', i] else: cmd += ['-no-doc-sections'] -- cgit From e8686a40a32aee572b87552b0835922a1e47bd87 Mon Sep 17 00:00:00 2001 From: Konstantin Ryabitsev Date: Wed, 30 Oct 2019 10:00:50 -0400 Subject: docs: process: Add base-commit trailer usage One of the recurring complaints from both maintainers and CI system operators is that performing git-am on received patches is difficult without knowing the parent object in the git history on which the patches are based. Without this information, there is a high likelihood that git-am will fail due to conflicts, which is particularly frustrating to CI operators. Git versions starting with v2.9.0 are able to automatically include base-commit information using the --base flag of git-format-patch. Document this usage in process/submitting-patches, and add the rationale for its inclusion, plus instructions for those not using git on where the "base-commit:" trailer should go. Signed-off-by: Konstantin Ryabitsev Signed-off-by: Jonathan Corbet --- Documentation/process/submitting-patches.rst | 53 +++++++++++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-) diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index fb56297f70dc..ba5e944c7a63 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -782,7 +782,58 @@ helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in the cover email text) to link to an earlier version of the patch series. -16) Sending ``git pull`` requests +16) Providing base tree information +----------------------------------- + +When other developers receive your patches and start the review process, +it is often useful for them to know where in the tree history they +should place your work. This is particularly useful for automated CI +processes that attempt to run a series of tests in order to establish +the quality of your submission before the maintainer starts the review. + +If you are using ``git format-patch`` to generate your patches, you can +automatically include the base tree information in your submission by +using the ``--base`` flag. The easiest and most convenient way to use +this option is with topical branches:: + + $ git checkout -t -b my-topical-branch master + Branch 'my-topical-branch' set up to track local branch 'master'. + Switched to a new branch 'my-topical-branch' + + [perform your edits and commits] + + $ git format-patch --base=auto --cover-letter -o outgoing/ master + outgoing/0000-cover-letter.patch + outgoing/0001-First-Commit.patch + outgoing/... + +When you open ``outgoing/0000-cover-letter.patch`` for editing, you will +notice that it will have the ``base-commit:`` trailer at the very +bottom, which provides the reviewer and the CI tools enough information +to properly perform ``git am`` without worrying about conflicts:: + + $ git checkout -b patch-review [base-commit-id] + Switched to a new branch 'patch-review' + $ git am patches.mbox + Applying: First Commit + Applying: ... + +Please see ``man git-format-patch`` for more information about this +option. + +.. note:: + + The ``--base`` feature was introduced in git version 2.9.0. + +If you are not using git to format your patches, you can still include +the same ``base-commit`` trailer to indicate the commit hash of the tree +on which your work is based. You should add it either in the cover +letter or in the first patch of the series and it should be placed +either below the ``---`` line or at the very bottom of all other +content, right before your email signature. + + +17) Sending ``git pull`` requests --------------------------------- If you have a series of patches, it may be most convenient to have the -- cgit From ff467342d3090350b3b5aa6885d6a55fbb1d0c35 Mon Sep 17 00:00:00 2001 From: Jeff Layton Date: Wed, 30 Oct 2019 06:46:54 -0400 Subject: Documentation: atomic_open called with shared lock on non-O_CREAT open The exclusive lock is only held when O_CREAT is set. Signed-off-by: Jeff Layton Signed-off-by: Jonathan Corbet --- Documentation/filesystems/locking.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/filesystems/locking.rst b/Documentation/filesystems/locking.rst index fc3a0704553c..5057e4d9dcd1 100644 --- a/Documentation/filesystems/locking.rst +++ b/Documentation/filesystems/locking.rst @@ -105,7 +105,7 @@ getattr: no listxattr: no fiemap: no update_time: no -atomic_open: exclusive +atomic_open: shared (exclusive if O_CREAT is set in open flags) tmpfile: no ============ ============================================= -- cgit From 5c8fac10c837957cd65d2c318d87c912d333dba3 Mon Sep 17 00:00:00 2001 From: Mike Leach Date: Thu, 31 Oct 2019 11:58:31 -0600 Subject: coresight: etm4x: docs: Update ABI doc for new sysfs name scheme. Recent updates to CoreSight drivers have changed the component naming schema used in sysfs. This updates the ABI document to reflect the new naming schema. Signed-off-by: Mike Leach Reviewed-by: Mathieu Poirier Signed-off-by: Jonathan Corbet --- .../ABI/testing/sysfs-bus-coresight-devices-etm4x | 136 ++++++++++----------- 1 file changed, 68 insertions(+), 68 deletions(-) diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x index 36258bc1b473..9290010e973e 100644 --- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x @@ -1,4 +1,4 @@ -What: /sys/bus/coresight/devices/.etm/enable_source +What: /sys/bus/coresight/devices/etm/enable_source Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier @@ -8,82 +8,82 @@ Description: (RW) Enable/disable tracing on this specific trace entiry. of coresight components linking the source to the sink is configured and managed automatically by the coresight framework. -What: /sys/bus/coresight/devices/.etm/cpu +What: /sys/bus/coresight/devices/etm/cpu Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) The CPU this tracing entity is associated with. -What: /sys/bus/coresight/devices/.etm/nr_pe_cmp +What: /sys/bus/coresight/devices/etm/nr_pe_cmp Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Indicates the number of PE comparator inputs that are available for tracing. -What: /sys/bus/coresight/devices/.etm/nr_addr_cmp +What: /sys/bus/coresight/devices/etm/nr_addr_cmp Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Indicates the number of address comparator pairs that are available for tracing. -What: /sys/bus/coresight/devices/.etm/nr_cntr +What: /sys/bus/coresight/devices/etm/nr_cntr Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Indicates the number of counters that are available for tracing. -What: /sys/bus/coresight/devices/.etm/nr_ext_inp +What: /sys/bus/coresight/devices/etm/nr_ext_inp Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Indicates how many external inputs are implemented. -What: /sys/bus/coresight/devices/.etm/numcidc +What: /sys/bus/coresight/devices/etm/numcidc Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Indicates the number of Context ID comparators that are available for tracing. -What: /sys/bus/coresight/devices/.etm/numvmidc +What: /sys/bus/coresight/devices/etm/numvmidc Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Indicates the number of VMID comparators that are available for tracing. -What: /sys/bus/coresight/devices/.etm/nrseqstate +What: /sys/bus/coresight/devices/etm/nrseqstate Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Indicates the number of sequencer states that are implemented. -What: /sys/bus/coresight/devices/.etm/nr_resource +What: /sys/bus/coresight/devices/etm/nr_resource Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Indicates the number of resource selection pairs that are available for tracing. -What: /sys/bus/coresight/devices/.etm/nr_ss_cmp +What: /sys/bus/coresight/devices/etm/nr_ss_cmp Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Indicates the number of single-shot comparator controls that are available for tracing. -What: /sys/bus/coresight/devices/.etm/reset +What: /sys/bus/coresight/devices/etm/reset Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (W) Cancels all configuration on a trace unit and set it back to its boot configuration. -What: /sys/bus/coresight/devices/.etm/mode +What: /sys/bus/coresight/devices/etm/mode Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier @@ -91,302 +91,302 @@ Description: (RW) Controls various modes supported by this ETM, for example P0 instruction tracing, branch broadcast, cycle counting and context ID tracing. -What: /sys/bus/coresight/devices/.etm/pe +What: /sys/bus/coresight/devices/etm/pe Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Controls which PE to trace. -What: /sys/bus/coresight/devices/.etm/event +What: /sys/bus/coresight/devices/etm/event Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Controls the tracing of arbitrary events from bank 0 to 3. -What: /sys/bus/coresight/devices/.etm/event_instren +What: /sys/bus/coresight/devices/etm/event_instren Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Controls the behavior of the events in bank 0 to 3. -What: /sys/bus/coresight/devices/.etm/event_ts +What: /sys/bus/coresight/devices/etm/event_ts Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Controls the insertion of global timestamps in the trace streams. -What: /sys/bus/coresight/devices/.etm/syncfreq +What: /sys/bus/coresight/devices/etm/syncfreq Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Controls how often trace synchronization requests occur. -What: /sys/bus/coresight/devices/.etm/cyc_threshold +What: /sys/bus/coresight/devices/etm/cyc_threshold Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Sets the threshold value for cycle counting. -What: /sys/bus/coresight/devices/.etm/bb_ctrl +What: /sys/bus/coresight/devices/etm/bb_ctrl Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Controls which regions in the memory map are enabled to use branch broadcasting. -What: /sys/bus/coresight/devices/.etm/event_vinst +What: /sys/bus/coresight/devices/etm/event_vinst Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Controls instruction trace filtering. -What: /sys/bus/coresight/devices/.etm/s_exlevel_vinst +What: /sys/bus/coresight/devices/etm/s_exlevel_vinst Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) In Secure state, each bit controls whether instruction tracing is enabled for the corresponding exception level. -What: /sys/bus/coresight/devices/.etm/ns_exlevel_vinst +What: /sys/bus/coresight/devices/etm/ns_exlevel_vinst Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) In non-secure state, each bit controls whether instruction tracing is enabled for the corresponding exception level. -What: /sys/bus/coresight/devices/.etm/addr_idx +What: /sys/bus/coresight/devices/etm/addr_idx Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Select which address comparator or pair (of comparators) to work with. -What: /sys/bus/coresight/devices/.etm/addr_instdatatype +What: /sys/bus/coresight/devices/etm/addr_instdatatype Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Controls what type of comparison the trace unit performs. -What: /sys/bus/coresight/devices/.etm/addr_single +What: /sys/bus/coresight/devices/etm/addr_single Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Used to setup single address comparator values. -What: /sys/bus/coresight/devices/.etm/addr_range +What: /sys/bus/coresight/devices/etm/addr_range Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Used to setup address range comparator values. -What: /sys/bus/coresight/devices/.etm/seq_idx +What: /sys/bus/coresight/devices/etm/seq_idx Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Select which sequensor. -What: /sys/bus/coresight/devices/.etm/seq_state +What: /sys/bus/coresight/devices/etm/seq_state Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Use this to set, or read, the sequencer state. -What: /sys/bus/coresight/devices/.etm/seq_event +What: /sys/bus/coresight/devices/etm/seq_event Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Moves the sequencer state to a specific state. -What: /sys/bus/coresight/devices/.etm/seq_reset_event +What: /sys/bus/coresight/devices/etm/seq_reset_event Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Moves the sequencer to state 0 when a programmed event occurs. -What: /sys/bus/coresight/devices/.etm/cntr_idx +What: /sys/bus/coresight/devices/etm/cntr_idx Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Select which counter unit to work with. -What: /sys/bus/coresight/devices/.etm/cntrldvr +What: /sys/bus/coresight/devices/etm/cntrldvr Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) This sets or returns the reload count value of the specific counter. -What: /sys/bus/coresight/devices/.etm/cntr_val +What: /sys/bus/coresight/devices/etm/cntr_val Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) This sets or returns the current count value of the specific counter. -What: /sys/bus/coresight/devices/.etm/cntr_ctrl +What: /sys/bus/coresight/devices/etm/cntr_ctrl Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Controls the operation of the selected counter. -What: /sys/bus/coresight/devices/.etm/res_idx +What: /sys/bus/coresight/devices/etm/res_idx Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Select which resource selection unit to work with. -What: /sys/bus/coresight/devices/.etm/res_ctrl +What: /sys/bus/coresight/devices/etm/res_ctrl Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Controls the selection of the resources in the trace unit. -What: /sys/bus/coresight/devices/.etm/ctxid_idx +What: /sys/bus/coresight/devices/etm/ctxid_idx Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Select which context ID comparator to work with. -What: /sys/bus/coresight/devices/.etm/ctxid_pid +What: /sys/bus/coresight/devices/etm/ctxid_pid Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Get/Set the context ID comparator value to trigger on. -What: /sys/bus/coresight/devices/.etm/ctxid_masks +What: /sys/bus/coresight/devices/etm/ctxid_masks Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Mask for all 8 context ID comparator value registers (if implemented). -What: /sys/bus/coresight/devices/.etm/vmid_idx +What: /sys/bus/coresight/devices/etm/vmid_idx Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Select which virtual machine ID comparator to work with. -What: /sys/bus/coresight/devices/.etm/vmid_val +What: /sys/bus/coresight/devices/etm/vmid_val Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Get/Set the virtual machine ID comparator value to trigger on. -What: /sys/bus/coresight/devices/.etm/vmid_masks +What: /sys/bus/coresight/devices/etm/vmid_masks Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (RW) Mask for all 8 virtual machine ID comparator value registers (if implemented). -What: /sys/bus/coresight/devices/.etm/mgmt/trcoslsr +What: /sys/bus/coresight/devices/etm/mgmt/trcoslsr Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Print the content of the OS Lock Status Register (0x304). The value it taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/mgmt/trcpdcr +What: /sys/bus/coresight/devices/etm/mgmt/trcpdcr Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Print the content of the Power Down Control Register (0x310). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/mgmt/trcpdsr +What: /sys/bus/coresight/devices/etm/mgmt/trcpdsr Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Print the content of the Power Down Status Register (0x314). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/mgmt/trclsr +What: /sys/bus/coresight/devices/etm/mgmt/trclsr Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Print the content of the SW Lock Status Register (0xFB4). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/mgmt/trcauthstatus +What: /sys/bus/coresight/devices/etm/mgmt/trcauthstatus Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Print the content of the Authentication Status Register (0xFB8). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/mgmt/trcdevid +What: /sys/bus/coresight/devices/etm/mgmt/trcdevid Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Print the content of the Device ID Register (0xFC8). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/mgmt/trcdevtype +What: /sys/bus/coresight/devices/etm/mgmt/trcdevtype Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Print the content of the Device Type Register (0xFCC). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/mgmt/trcpidr0 +What: /sys/bus/coresight/devices/etm/mgmt/trcpidr0 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Print the content of the Peripheral ID0 Register (0xFE0). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/mgmt/trcpidr1 +What: /sys/bus/coresight/devices/etm/mgmt/trcpidr1 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Print the content of the Peripheral ID1 Register (0xFE4). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/mgmt/trcpidr2 +What: /sys/bus/coresight/devices/etm/mgmt/trcpidr2 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Print the content of the Peripheral ID2 Register (0xFE8). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/mgmt/trcpidr3 +What: /sys/bus/coresight/devices/etm/mgmt/trcpidr3 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Print the content of the Peripheral ID3 Register (0xFEC). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/mgmt/trcconfig +What: /sys/bus/coresight/devices/etm/mgmt/trcconfig Date: February 2016 KernelVersion: 4.07 Contact: Mathieu Poirier Description: (R) Print the content of the trace configuration register (0x010) as currently set by SW. -What: /sys/bus/coresight/devices/.etm/mgmt/trctraceid +What: /sys/bus/coresight/devices/etm/mgmt/trctraceid Date: February 2016 KernelVersion: 4.07 Contact: Mathieu Poirier Description: (R) Print the content of the trace ID register (0x040). -What: /sys/bus/coresight/devices/.etm/trcidr/trcidr0 +What: /sys/bus/coresight/devices/etm/trcidr/trcidr0 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Returns the tracing capabilities of the trace unit (0x1E0). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/trcidr/trcidr1 +What: /sys/bus/coresight/devices/etm/trcidr/trcidr1 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Returns the tracing capabilities of the trace unit (0x1E4). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/trcidr/trcidr2 +What: /sys/bus/coresight/devices/etm/trcidr/trcidr2 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier @@ -394,7 +394,7 @@ Description: (R) Returns the maximum size of the data value, data address, VMID, context ID and instuction address in the trace unit (0x1E8). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/trcidr/trcidr3 +What: /sys/bus/coresight/devices/etm/trcidr/trcidr3 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier @@ -403,42 +403,42 @@ Description: (R) Returns the value associated with various resources architecture specification for more details (0x1E8). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/trcidr/trcidr4 +What: /sys/bus/coresight/devices/etm/trcidr/trcidr4 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Returns how many resources the trace unit supports (0x1F0). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/trcidr/trcidr5 +What: /sys/bus/coresight/devices/etm/trcidr/trcidr5 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Returns how many resources the trace unit supports (0x1F4). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/trcidr/trcidr8 +What: /sys/bus/coresight/devices/etm/trcidr/trcidr8 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Returns the maximum speculation depth of the instruction trace stream. (0x180). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/trcidr/trcidr9 +What: /sys/bus/coresight/devices/etm/trcidr/trcidr9 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Returns the number of P0 right-hand keys that the trace unit can use (0x184). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/trcidr/trcidr10 +What: /sys/bus/coresight/devices/etm/trcidr/trcidr10 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier Description: (R) Returns the number of P1 right-hand keys that the trace unit can use (0x188). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/trcidr/trcidr11 +What: /sys/bus/coresight/devices/etm/trcidr/trcidr11 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier @@ -446,7 +446,7 @@ Description: (R) Returns the number of special P1 right-hand keys that the trace unit can use (0x18C). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/trcidr/trcidr12 +What: /sys/bus/coresight/devices/etm/trcidr/trcidr12 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier @@ -454,7 +454,7 @@ Description: (R) Returns the number of conditional P1 right-hand keys that the trace unit can use (0x190). The value is taken directly from the HW. -What: /sys/bus/coresight/devices/.etm/trcidr/trcidr13 +What: /sys/bus/coresight/devices/etm/trcidr/trcidr13 Date: April 2015 KernelVersion: 4.01 Contact: Mathieu Poirier -- cgit From b3ef0df18132324b5cca436d004c1ee65fb288af Mon Sep 17 00:00:00 2001 From: Mike Leach Date: Thu, 31 Oct 2019 11:58:32 -0600 Subject: coresight: etm4x: docs: Update ABI doc for new sysfs etm4 attributes This updates the ABI document to reflect recent additions to the ETM4.X driver sysfs interface. Signed-off-by: Mike Leach [Updated Date and KernelVersion fields] Reviewed-by: Mathieu Poirier Signed-off-by: Jonathan Corbet --- .../ABI/testing/sysfs-bus-coresight-devices-etm4x | 47 ++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x index 9290010e973e..614874e2cf53 100644 --- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x +++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x @@ -282,6 +282,53 @@ Contact: Mathieu Poirier Description: (RW) Mask for all 8 virtual machine ID comparator value registers (if implemented). +What: /sys/bus/coresight/devices/etm/addr_exlevel_s_ns +Date: December 2019 +KernelVersion: 5.5 +Contact: Mathieu Poirier +Description: (RW) Set the Exception Level matching bits for secure and + non-secure exception levels. + +What: /sys/bus/coresight/devices/etm/vinst_pe_cmp_start_stop +Date: December 2019 +KernelVersion: 5.5 +Contact: Mathieu Poirier +Description: (RW) Access the start stop control register for PE input + comparators. + +What: /sys/bus/coresight/devices/etm/addr_cmp_view +Date: December 2019 +KernelVersion: 5.5 +Contact: Mathieu Poirier +Description: (R) Print the current settings for the selected address + comparator. + +What: /sys/bus/coresight/devices/etm/sshot_idx +Date: December 2019 +KernelVersion: 5.5 +Contact: Mathieu Poirier +Description: (RW) Select the single shot control register to access. + +What: /sys/bus/coresight/devices/etm/sshot_ctrl +Date: December 2019 +KernelVersion: 5.5 +Contact: Mathieu Poirier +Description: (RW) Access the selected single shot control register. + +What: /sys/bus/coresight/devices/etm/sshot_status +Date: December 2019 +KernelVersion: 5.5 +Contact: Mathieu Poirier +Description: (R) Print the current value of the selected single shot + status register. + +What: /sys/bus/coresight/devices/etm/sshot_pe_ctrl +Date: December 2019 +KernelVersion: 5.5 +Contact: Mathieu Poirier +Description: (RW) Access the selected single show PE comparator control + register. + What: /sys/bus/coresight/devices/etm/mgmt/trcoslsr Date: April 2015 KernelVersion: 4.01 -- cgit From 8adf42e293921e2ebbcfcadd89f6d4d25db04ddc Mon Sep 17 00:00:00 2001 From: Mike Leach Date: Thu, 31 Oct 2019 11:58:33 -0600 Subject: coresight: docs: Create common sub-directory for coresight trace. There are two files in the Documentation/trace directory relating to coresight, with more to follow, so create a Documentation/trace/coresight directory and move existing files there. Fixup index to reference new location. Update MAINTAINERS to reference this sub-directory rather than the individual files. Signed-off-by: Mike Leach Reviewed-by: Mathieu Poirier Signed-off-by: Jonathan Corbet --- Documentation/trace/coresight-cpu-debug.rst | 192 -------- Documentation/trace/coresight.rst | 498 --------------------- .../trace/coresight/coresight-cpu-debug.rst | 192 ++++++++ Documentation/trace/coresight/coresight.rst | 498 +++++++++++++++++++++ Documentation/trace/coresight/index.rst | 9 + Documentation/trace/index.rst | 3 +- MAINTAINERS | 3 +- 7 files changed, 701 insertions(+), 694 deletions(-) delete mode 100644 Documentation/trace/coresight-cpu-debug.rst delete mode 100644 Documentation/trace/coresight.rst create mode 100644 Documentation/trace/coresight/coresight-cpu-debug.rst create mode 100644 Documentation/trace/coresight/coresight.rst create mode 100644 Documentation/trace/coresight/index.rst diff --git a/Documentation/trace/coresight-cpu-debug.rst b/Documentation/trace/coresight-cpu-debug.rst deleted file mode 100644 index 993dd294b81b..000000000000 --- a/Documentation/trace/coresight-cpu-debug.rst +++ /dev/null @@ -1,192 +0,0 @@ -========================== -Coresight CPU Debug Module -========================== - - :Author: Leo Yan - :Date: April 5th, 2017 - -Introduction ------------- - -Coresight CPU debug module is defined in ARMv8-a architecture reference manual -(ARM DDI 0487A.k) Chapter 'Part H: External debug', the CPU can integrate -debug module and it is mainly used for two modes: self-hosted debug and -external debug. Usually the external debug mode is well known as the external -debugger connects with SoC from JTAG port; on the other hand the program can -explore debugging method which rely on self-hosted debug mode, this document -is to focus on this part. - -The debug module provides sample-based profiling extension, which can be used -to sample CPU program counter, secure state and exception level, etc; usually -every CPU has one dedicated debug module to be connected. Based on self-hosted -debug mechanism, Linux kernel can access these related registers from mmio -region when the kernel panic happens. The callback notifier for kernel panic -will dump related registers for every CPU; finally this is good for assistant -analysis for panic. - - -Implementation --------------- - -- During driver registration, it uses EDDEVID and EDDEVID1 - two device ID - registers to decide if sample-based profiling is implemented or not. On some - platforms this hardware feature is fully or partially implemented; and if - this feature is not supported then registration will fail. - -- At the time this documentation was written, the debug driver mainly relies on - information gathered by the kernel panic callback notifier from three - sampling registers: EDPCSR, EDVIDSR and EDCIDSR: from EDPCSR we can get - program counter; EDVIDSR has information for secure state, exception level, - bit width, etc; EDCIDSR is context ID value which contains the sampled value - of CONTEXTIDR_EL1. - -- The driver supports a CPU running in either AArch64 or AArch32 mode. The - registers naming convention is a bit different between them, AArch64 uses - 'ED' for register prefix (ARM DDI 0487A.k, chapter H9.1) and AArch32 uses - 'DBG' as prefix (ARM DDI 0487A.k, chapter G5.1). The driver is unified to - use AArch64 naming convention. - -- ARMv8-a (ARM DDI 0487A.k) and ARMv7-a (ARM DDI 0406C.b) have different - register bits definition. So the driver consolidates two difference: - - If PCSROffset=0b0000, on ARMv8-a the feature of EDPCSR is not implemented; - but ARMv7-a defines "PCSR samples are offset by a value that depends on the - instruction set state". For ARMv7-a, the driver checks furthermore if CPU - runs with ARM or thumb instruction set and calibrate PCSR value, the - detailed description for offset is in ARMv7-a ARM (ARM DDI 0406C.b) chapter - C11.11.34 "DBGPCSR, Program Counter Sampling Register". - - If PCSROffset=0b0010, ARMv8-a defines "EDPCSR implemented, and samples have - no offset applied and do not sample the instruction set state in AArch32 - state". So on ARMv8 if EDDEVID1.PCSROffset is 0b0010 and the CPU operates - in AArch32 state, EDPCSR is not sampled; when the CPU operates in AArch64 - state EDPCSR is sampled and no offset are applied. - - -Clock and power domain ----------------------- - -Before accessing debug registers, we should ensure the clock and power domain -have been enabled properly. In ARMv8-a ARM (ARM DDI 0487A.k) chapter 'H9.1 -Debug registers', the debug registers are spread into two domains: the debug -domain and the CPU domain. -:: - - +---------------+ - | | - | | - +----------+--+ | - dbg_clock -->| |**| |<-- cpu_clock - | Debug |**| CPU | - dbg_power_domain -->| |**| |<-- cpu_power_domain - +----------+--+ | - | | - | | - +---------------+ - -For debug domain, the user uses DT binding "clocks" and "power-domains" to -specify the corresponding clock source and power supply for the debug logic. -The driver calls the pm_runtime_{put|get} operations as needed to handle the -debug power domain. - -For CPU domain, the different SoC designs have different power management -schemes and finally this heavily impacts external debug module. So we can -divide into below cases: - -- On systems with a sane power controller which can behave correctly with - respect to CPU power domain, the CPU power domain can be controlled by - register EDPRCR in driver. The driver firstly writes bit EDPRCR.COREPURQ - to power up the CPU, and then writes bit EDPRCR.CORENPDRQ for emulation - of CPU power down. As result, this can ensure the CPU power domain is - powered on properly during the period when access debug related registers; - -- Some designs will power down an entire cluster if all CPUs on the cluster - are powered down - including the parts of the debug registers that should - remain powered in the debug power domain. The bits in EDPRCR are not - respected in these cases, so these designs do not support debug over - power down in the way that the CoreSight / Debug designers anticipated. - This means that even checking EDPRSR has the potential to cause a bus hang - if the target register is unpowered. - - In this case, accessing to the debug registers while they are not powered - is a recipe for disaster; so we need preventing CPU low power states at boot - time or when user enable module at the run time. Please see chapter - "How to use the module" for detailed usage info for this. - - -Device Tree Bindings --------------------- - -See Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt for details. - - -How to use the module ---------------------- - -If you want to enable debugging functionality at boot time, you can add -"coresight_cpu_debug.enable=1" to the kernel command line parameter. - -The driver also can work as module, so can enable the debugging when insmod -module:: - - # insmod coresight_cpu_debug.ko debug=1 - -When boot time or insmod module you have not enabled the debugging, the driver -uses the debugfs file system to provide a knob to dynamically enable or disable -debugging: - -To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable:: - - # echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable - -To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable:: - - # echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable - -As explained in chapter "Clock and power domain", if you are working on one -platform which has idle states to power off debug logic and the power -controller cannot work well for the request from EDPRCR, then you should -firstly constraint CPU idle states before enable CPU debugging feature; so can -ensure the accessing to debug logic. - -If you want to limit idle states at boot time, you can use "nohlt" or -"cpuidle.off=1" in the kernel command line. - -At the runtime you can disable idle states with below methods: - -It is possible to disable CPU idle states by way of the PM QoS -subsystem, more specifically by using the "/dev/cpu_dma_latency" -interface (see Documentation/power/pm_qos_interface.rst for more -details). As specified in the PM QoS documentation the requested -parameter will stay in effect until the file descriptor is released. -For example:: - - # exec 3<> /dev/cpu_dma_latency; echo 0 >&3 - ... - Do some work... - ... - # exec 3<>- - -The same can also be done from an application program. - -Disable specific CPU's specific idle state from cpuidle sysfs (see -Documentation/admin-guide/pm/cpuidle.rst):: - - # echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable - -Output format -------------- - -Here is an example of the debugging output format:: - - ARM external debug module: - coresight-cpu-debug 850000.debug: CPU[0]: - coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock) - coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8 - coresight-cpu-debug 850000.debug: EDCIDSR: 00000000 - coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0) - coresight-cpu-debug 852000.debug: CPU[1]: - coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock) - coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358 - coresight-cpu-debug 852000.debug: EDCIDSR: 00000000 - coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0) diff --git a/Documentation/trace/coresight.rst b/Documentation/trace/coresight.rst deleted file mode 100644 index 72f4b7ef1bad..000000000000 --- a/Documentation/trace/coresight.rst +++ /dev/null @@ -1,498 +0,0 @@ -====================================== -Coresight - HW Assisted Tracing on ARM -====================================== - - :Author: Mathieu Poirier - :Date: September 11th, 2014 - -Introduction ------------- - -Coresight is an umbrella of technologies allowing for the debugging of ARM -based SoC. It includes solutions for JTAG and HW assisted tracing. This -document is concerned with the latter. - -HW assisted tracing is becoming increasingly useful when dealing with systems -that have many SoCs and other components like GPU and DMA engines. ARM has -developed a HW assisted tracing solution by means of different components, each -being added to a design at synthesis time to cater to specific tracing needs. -Components are generally categorised as source, link and sinks and are -(usually) discovered using the AMBA bus. - -"Sources" generate a compressed stream representing the processor instruction -path based on tracing scenarios as configured by users. From there the stream -flows through the coresight system (via ATB bus) using links that are connecting -the emanating source to a sink(s). Sinks serve as endpoints to the coresight -implementation, either storing the compressed stream in a memory buffer or -creating an interface to the outside world where data can be transferred to a -host without fear of filling up the onboard coresight memory buffer. - -At typical coresight system would look like this:: - - ***************************************************************** - **************************** AMBA AXI ****************************===|| - ***************************************************************** || - ^ ^ | || - | | * ** - 0000000 ::::: 0000000 ::::: ::::: @@@@@@@ |||||||||||| - 0 CPU 0<-->: C : 0 CPU 0<-->: C : : C : @ STM @ || System || - |->0000000 : T : |->0000000 : T : : T :<--->@@@@@ || Memory || - | #######<-->: I : | #######<-->: I : : I : @@@<-| |||||||||||| - | # ETM # ::::: | # PTM # ::::: ::::: @ | - | ##### ^ ^ | ##### ^ ! ^ ! . | ||||||||| - | |->### | ! | |->### | ! | ! . | || DAP || - | | # | ! | | # | ! | ! . | ||||||||| - | | . | ! | | . | ! | ! . | | | - | | . | ! | | . | ! | ! . | | * - | | . | ! | | . | ! | ! . | | SWD/ - | | . | ! | | . | ! | ! . | | JTAG - *****************************************************************<-| - *************************** AMBA Debug APB ************************ - ***************************************************************** - | . ! . ! ! . | - | . * . * * . | - ***************************************************************** - ******************** Cross Trigger Matrix (CTM) ******************* - ***************************************************************** - | . ^ . . | - | * ! * * | - ***************************************************************** - ****************** AMBA Advanced Trace Bus (ATB) ****************** - ***************************************************************** - | ! =============== | - | * ===== F =====<---------| - | ::::::::: ==== U ==== - |-->:: CTI ::&& ETB &&<......II I ======= - | ! &&&&&&&&& II I . - | ! I I . - | ! I REP I<.......... - | ! I I - | !!>&&&&&&&&& II I *Source: ARM ltd. - |------>& TPIU &<......II I DAP = Debug Access Port - &&&&&&&&& IIIIIII ETM = Embedded Trace Macrocell - ; PTM = Program Trace Macrocell - ; CTI = Cross Trigger Interface - * ETB = Embedded Trace Buffer - To trace port TPIU= Trace Port Interface Unit - SWD = Serial Wire Debug - -While on target configuration of the components is done via the APB bus, -all trace data are carried out-of-band on the ATB bus. The CTM provides -a way to aggregate and distribute signals between CoreSight components. - -The coresight framework provides a central point to represent, configure and -manage coresight devices on a platform. This first implementation centers on -the basic tracing functionality, enabling components such ETM/PTM, funnel, -replicator, TMC, TPIU and ETB. Future work will enable more -intricate IP blocks such as STM and CTI. - - -Acronyms and Classification ---------------------------- - -Acronyms: - -PTM: - Program Trace Macrocell -ETM: - Embedded Trace Macrocell -STM: - System trace Macrocell -ETB: - Embedded Trace Buffer -ITM: - Instrumentation Trace Macrocell -TPIU: - Trace Port Interface Unit -TMC-ETR: - Trace Memory Controller, configured as Embedded Trace Router -TMC-ETF: - Trace Memory Controller, configured as Embedded Trace FIFO -CTI: - Cross Trigger Interface - -Classification: - -Source: - ETMv3.x ETMv4, PTMv1.0, PTMv1.1, STM, STM500, ITM -Link: - Funnel, replicator (intelligent or not), TMC-ETR -Sinks: - ETBv1.0, ETB1.1, TPIU, TMC-ETF -Misc: - CTI - - -Device Tree Bindings --------------------- - -See Documentation/devicetree/bindings/arm/coresight.txt for details. - -As of this writing drivers for ITM, STMs and CTIs are not provided but are -expected to be added as the solution matures. - - -Framework and implementation ----------------------------- - -The coresight framework provides a central point to represent, configure and -manage coresight devices on a platform. Any coresight compliant device can -register with the framework for as long as they use the right APIs: - -.. c:function:: struct coresight_device *coresight_register(struct coresight_desc *desc); -.. c:function:: void coresight_unregister(struct coresight_device *csdev); - -The registering function is taking a ``struct coresight_desc *desc`` and -register the device with the core framework. The unregister function takes -a reference to a ``struct coresight_device *csdev`` obtained at registration time. - -If everything goes well during the registration process the new devices will -show up under /sys/bus/coresight/devices, as showns here for a TC2 platform:: - - root:~# ls /sys/bus/coresight/devices/ - replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm - 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm - root:~# - -The functions take a ``struct coresight_device``, which looks like this:: - - struct coresight_desc { - enum coresight_dev_type type; - struct coresight_dev_subtype subtype; - const struct coresight_ops *ops; - struct coresight_platform_data *pdata; - struct device *dev; - const struct attribute_group **groups; - }; - - -The "coresight_dev_type" identifies what the device is, i.e, source link or -sink while the "coresight_dev_subtype" will characterise that type further. - -The ``struct coresight_ops`` is mandatory and will tell the framework how to -perform base operations related to the components, each component having -a different set of requirement. For that ``struct coresight_ops_sink``, -``struct coresight_ops_link`` and ``struct coresight_ops_source`` have been -provided. - -The next field ``struct coresight_platform_data *pdata`` is acquired by calling -``of_get_coresight_platform_data()``, as part of the driver's _probe routine and -``struct device *dev`` gets the device reference embedded in the ``amba_device``:: - - static int etm_probe(struct amba_device *adev, const struct amba_id *id) - { - ... - ... - drvdata->dev = &adev->dev; - ... - } - -Specific class of device (source, link, or sink) have generic operations -that can be performed on them (see ``struct coresight_ops``). The ``**groups`` -is a list of sysfs entries pertaining to operations -specific to that component only. "Implementation defined" customisations are -expected to be accessed and controlled using those entries. - -Device Naming scheme --------------------- - -The devices that appear on the "coresight" bus were named the same as their -parent devices, i.e, the real devices that appears on AMBA bus or the platform bus. -Thus the names were based on the Linux Open Firmware layer naming convention, -which follows the base physical address of the device followed by the device -type. e.g:: - - root:~# ls /sys/bus/coresight/devices/ - 20010000.etf 20040000.funnel 20100000.stm 22040000.etm - 22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu - 20070000.etr 20120000.replicator 220c0000.funnel - 23040000.etm 23140000.etm 23340000.etm - -However, with the introduction of ACPI support, the names of the real -devices are a bit cryptic and non-obvious. Thus, a new naming scheme was -introduced to use more generic names based on the type of the device. The -following rules apply:: - - 1) Devices that are bound to CPUs, are named based on the CPU logical - number. - - e.g, ETM bound to CPU0 is named "etm0" - - 2) All other devices follow a pattern, "N", where : - - - A prefix specific to the type of the device - N - a sequential number assigned based on the order - of probing. - - e.g, tmc_etf0, tmc_etr0, funnel0, funnel1 - -Thus, with the new scheme the devices could appear as :: - - root:~# ls /sys/bus/coresight/devices/ - etm0 etm1 etm2 etm3 etm4 etm5 funnel0 - funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0 - -Some of the examples below might refer to old naming scheme and some -to the newer scheme, to give a confirmation that what you see on your -system is not unexpected. One must use the "names" as they appear on -the system under specified locations. - -How to use the tracer modules ------------------------------ - -There are two ways to use the Coresight framework: - -1. using the perf cmd line tools. -2. interacting directly with the Coresight devices using the sysFS interface. - -Preference is given to the former as using the sysFS interface -requires a deep understanding of the Coresight HW. The following sections -provide details on using both methods. - -1) Using the sysFS interface: - -Before trace collection can start, a coresight sink needs to be identified. -There is no limit on the amount of sinks (nor sources) that can be enabled at -any given moment. As a generic operation, all device pertaining to the sink -class will have an "active" entry in sysfs:: - - root:/sys/bus/coresight/devices# ls - replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm - 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm - root:/sys/bus/coresight/devices# ls 20010000.etb - enable_sink status trigger_cntr - root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink - root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink - 1 - root:/sys/bus/coresight/devices# - -At boot time the current etm3x driver will configure the first address -comparator with "_stext" and "_etext", essentially tracing any instruction -that falls within that range. As such "enabling" a source will immediately -trigger a trace capture:: - - root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source - root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source - 1 - root:/sys/bus/coresight/devices# cat 20010000.etb/status - Depth: 0x2000 - Status: 0x1 - RAM read ptr: 0x0 - RAM wrt ptr: 0x19d3 <----- The write pointer is moving - Trigger cnt: 0x0 - Control: 0x1 - Flush status: 0x0 - Flush ctrl: 0x2001 - root:/sys/bus/coresight/devices# - -Trace collection is stopped the same way:: - - root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source - root:/sys/bus/coresight/devices# - -The content of the ETB buffer can be harvested directly from /dev:: - - root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \ - of=~/cstrace.bin - 64+0 records in - 64+0 records out - 32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s - root:/sys/bus/coresight/devices# - -The file cstrace.bin can be decompressed using "ptm2human", DS-5 or Trace32. - -Following is a DS-5 output of an experimental loop that increments a variable up -to a certain value. The example is simple and yet provides a glimpse of the -wealth of possibilities that coresight provides. -:: - - Info Tracing enabled - Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr} - Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc - Instruction 0 0x8026B544 E3A03000 false MOV r3,#0 - Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4] - Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4] - Instruction 0 0x8026B550 E3530004 false CMP r3,#4 - Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 - Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] - Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c - Timestamp Timestamp: 17106715833 - Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4] - Instruction 0 0x8026B550 E3530004 false CMP r3,#4 - Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 - Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] - Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c - Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4] - Instruction 0 0x8026B550 E3530004 false CMP r3,#4 - Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 - Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] - Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c - Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4] - Instruction 0 0x8026B550 E3530004 false CMP r3,#4 - Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 - Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] - Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c - Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4] - Instruction 0 0x8026B550 E3530004 false CMP r3,#4 - Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 - Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] - Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c - Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4] - Instruction 0 0x8026B550 E3530004 false CMP r3,#4 - Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 - Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] - Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c - Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1 - Instruction 0 0x8026B564 E1A0100D false MOV r1,sp - Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0 - Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f - Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4] - Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368 - Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc] - Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0] - Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4 - Info Tracing enabled - Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc - Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc} - Timestamp Timestamp: 17107041535 - -2) Using perf framework: - -Coresight tracers are represented using the Perf framework's Performance -Monitoring Unit (PMU) abstraction. As such the perf framework takes charge of -controlling when tracing gets enabled based on when the process of interest is -scheduled. When configured in a system, Coresight PMUs will be listed when -queried by the perf command line tool: - - linaro@linaro-nano:~$ ./perf list pmu - - List of pre-defined events (to be used in -e): - - cs_etm// [Kernel PMU event] - - linaro@linaro-nano:~$ - -Regardless of the number of tracers available in a system (usually equal to the -amount of processor cores), the "cs_etm" PMU will be listed only once. - -A Coresight PMU works the same way as any other PMU, i.e the name of the PMU is -listed along with configuration options within forward slashes '/'. Since a -Coresight system will typically have more than one sink, the name of the sink to -work with needs to be specified as an event option. -On newer kernels the available sinks are listed in sysFS under -($SYSFS)/bus/event_source/devices/cs_etm/sinks/:: - - root@localhost:/sys/bus/event_source/devices/cs_etm/sinks# ls - tmc_etf0 tmc_etr0 tpiu0 - -On older kernels, this may need to be found from the list of coresight devices, -available under ($SYSFS)/bus/coresight/devices/:: - - root:~# ls /sys/bus/coresight/devices/ - etm0 etm1 etm2 etm3 etm4 etm5 funnel0 - funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0 - root@linaro-nano:~# perf record -e cs_etm/@tmc_etr0/u --per-thread program - -As mentioned above in section "Device Naming scheme", the names of the devices could -look different from what is used in the example above. One must use the device names -as it appears under the sysFS. - -The syntax within the forward slashes '/' is important. The '@' character -tells the parser that a sink is about to be specified and that this is the sink -to use for the trace session. - -More information on the above and other example on how to use Coresight with -the perf tools can be found in the "HOWTO.md" file of the openCSD gitHub -repository [#third]_. - -2.1) AutoFDO analysis using the perf tools: - -perf can be used to record and analyze trace of programs. - -Execution can be recorded using 'perf record' with the cs_etm event, -specifying the name of the sink to record to, e.g:: - - perf record -e cs_etm/@tmc_etr0/u --per-thread - -The 'perf report' and 'perf script' commands can be used to analyze execution, -synthesizing instruction and branch events from the instruction trace. -'perf inject' can be used to replace the trace data with the synthesized events. -The --itrace option controls the type and frequency of synthesized events -(see perf documentation). - -Note that only 64-bit programs are currently supported - further work is -required to support instruction decode of 32-bit Arm programs. - - -Generating coverage files for Feedback Directed Optimization: AutoFDO ---------------------------------------------------------------------- - -'perf inject' accepts the --itrace option in which case tracing data is -removed and replaced with the synthesized events. e.g. -:: - - perf inject --itrace --strip -i perf.data -o perf.data.new - -Below is an example of using ARM ETM for autoFDO. It requires autofdo -(https://github.com/google/autofdo) and gcc version 5. The bubble -sort example is from the AutoFDO tutorial (https://gcc.gnu.org/wiki/AutoFDO/Tutorial). -:: - - $ gcc-5 -O3 sort.c -o sort - $ taskset -c 2 ./sort - Bubble sorting array of 30000 elements - 5910 ms - - $ perf record -e cs_etm/@tmc_etr0/u --per-thread taskset -c 2 ./sort - Bubble sorting array of 30000 elements - 12543 ms - [ perf record: Woken up 35 times to write data ] - [ perf record: Captured and wrote 69.640 MB perf.data ] - - $ perf inject -i perf.data -o inj.data --itrace=il64 --strip - $ create_gcov --binary=./sort --profile=inj.data --gcov=sort.gcov -gcov_version=1 - $ gcc-5 -O3 -fauto-profile=sort.gcov sort.c -o sort_autofdo - $ taskset -c 2 ./sort_autofdo - Bubble sorting array of 30000 elements - 5806 ms - - -How to use the STM module -------------------------- - -Using the System Trace Macrocell module is the same as the tracers - the only -difference is that clients are driving the trace capture rather -than the program flow through the code. - -As with any other CoreSight component, specifics about the STM tracer can be -found in sysfs with more information on each entry being found in [#first]_:: - - root@genericarmv8:~# ls /sys/bus/coresight/devices/stm0 - enable_source hwevent_select port_enable subsystem uevent - hwevent_enable mgmt port_select traceid - root@genericarmv8:~# - -Like any other source a sink needs to be identified and the STM enabled before -being used:: - - root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/tmc_etf0/enable_sink - root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/stm0/enable_source - -From there user space applications can request and use channels using the devfs -interface provided for that purpose by the generic STM API:: - - root@genericarmv8:~# ls -l /dev/stm0 - crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0 - root@genericarmv8:~# - -Details on how to use the generic STM API can be found here [#second]_. - -.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm - -.. [#second] Documentation/trace/stm.rst - -.. [#third] https://github.com/Linaro/perf-opencsd diff --git a/Documentation/trace/coresight/coresight-cpu-debug.rst b/Documentation/trace/coresight/coresight-cpu-debug.rst new file mode 100644 index 000000000000..993dd294b81b --- /dev/null +++ b/Documentation/trace/coresight/coresight-cpu-debug.rst @@ -0,0 +1,192 @@ +========================== +Coresight CPU Debug Module +========================== + + :Author: Leo Yan + :Date: April 5th, 2017 + +Introduction +------------ + +Coresight CPU debug module is defined in ARMv8-a architecture reference manual +(ARM DDI 0487A.k) Chapter 'Part H: External debug', the CPU can integrate +debug module and it is mainly used for two modes: self-hosted debug and +external debug. Usually the external debug mode is well known as the external +debugger connects with SoC from JTAG port; on the other hand the program can +explore debugging method which rely on self-hosted debug mode, this document +is to focus on this part. + +The debug module provides sample-based profiling extension, which can be used +to sample CPU program counter, secure state and exception level, etc; usually +every CPU has one dedicated debug module to be connected. Based on self-hosted +debug mechanism, Linux kernel can access these related registers from mmio +region when the kernel panic happens. The callback notifier for kernel panic +will dump related registers for every CPU; finally this is good for assistant +analysis for panic. + + +Implementation +-------------- + +- During driver registration, it uses EDDEVID and EDDEVID1 - two device ID + registers to decide if sample-based profiling is implemented or not. On some + platforms this hardware feature is fully or partially implemented; and if + this feature is not supported then registration will fail. + +- At the time this documentation was written, the debug driver mainly relies on + information gathered by the kernel panic callback notifier from three + sampling registers: EDPCSR, EDVIDSR and EDCIDSR: from EDPCSR we can get + program counter; EDVIDSR has information for secure state, exception level, + bit width, etc; EDCIDSR is context ID value which contains the sampled value + of CONTEXTIDR_EL1. + +- The driver supports a CPU running in either AArch64 or AArch32 mode. The + registers naming convention is a bit different between them, AArch64 uses + 'ED' for register prefix (ARM DDI 0487A.k, chapter H9.1) and AArch32 uses + 'DBG' as prefix (ARM DDI 0487A.k, chapter G5.1). The driver is unified to + use AArch64 naming convention. + +- ARMv8-a (ARM DDI 0487A.k) and ARMv7-a (ARM DDI 0406C.b) have different + register bits definition. So the driver consolidates two difference: + + If PCSROffset=0b0000, on ARMv8-a the feature of EDPCSR is not implemented; + but ARMv7-a defines "PCSR samples are offset by a value that depends on the + instruction set state". For ARMv7-a, the driver checks furthermore if CPU + runs with ARM or thumb instruction set and calibrate PCSR value, the + detailed description for offset is in ARMv7-a ARM (ARM DDI 0406C.b) chapter + C11.11.34 "DBGPCSR, Program Counter Sampling Register". + + If PCSROffset=0b0010, ARMv8-a defines "EDPCSR implemented, and samples have + no offset applied and do not sample the instruction set state in AArch32 + state". So on ARMv8 if EDDEVID1.PCSROffset is 0b0010 and the CPU operates + in AArch32 state, EDPCSR is not sampled; when the CPU operates in AArch64 + state EDPCSR is sampled and no offset are applied. + + +Clock and power domain +---------------------- + +Before accessing debug registers, we should ensure the clock and power domain +have been enabled properly. In ARMv8-a ARM (ARM DDI 0487A.k) chapter 'H9.1 +Debug registers', the debug registers are spread into two domains: the debug +domain and the CPU domain. +:: + + +---------------+ + | | + | | + +----------+--+ | + dbg_clock -->| |**| |<-- cpu_clock + | Debug |**| CPU | + dbg_power_domain -->| |**| |<-- cpu_power_domain + +----------+--+ | + | | + | | + +---------------+ + +For debug domain, the user uses DT binding "clocks" and "power-domains" to +specify the corresponding clock source and power supply for the debug logic. +The driver calls the pm_runtime_{put|get} operations as needed to handle the +debug power domain. + +For CPU domain, the different SoC designs have different power management +schemes and finally this heavily impacts external debug module. So we can +divide into below cases: + +- On systems with a sane power controller which can behave correctly with + respect to CPU power domain, the CPU power domain can be controlled by + register EDPRCR in driver. The driver firstly writes bit EDPRCR.COREPURQ + to power up the CPU, and then writes bit EDPRCR.CORENPDRQ for emulation + of CPU power down. As result, this can ensure the CPU power domain is + powered on properly during the period when access debug related registers; + +- Some designs will power down an entire cluster if all CPUs on the cluster + are powered down - including the parts of the debug registers that should + remain powered in the debug power domain. The bits in EDPRCR are not + respected in these cases, so these designs do not support debug over + power down in the way that the CoreSight / Debug designers anticipated. + This means that even checking EDPRSR has the potential to cause a bus hang + if the target register is unpowered. + + In this case, accessing to the debug registers while they are not powered + is a recipe for disaster; so we need preventing CPU low power states at boot + time or when user enable module at the run time. Please see chapter + "How to use the module" for detailed usage info for this. + + +Device Tree Bindings +-------------------- + +See Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt for details. + + +How to use the module +--------------------- + +If you want to enable debugging functionality at boot time, you can add +"coresight_cpu_debug.enable=1" to the kernel command line parameter. + +The driver also can work as module, so can enable the debugging when insmod +module:: + + # insmod coresight_cpu_debug.ko debug=1 + +When boot time or insmod module you have not enabled the debugging, the driver +uses the debugfs file system to provide a knob to dynamically enable or disable +debugging: + +To enable it, write a '1' into /sys/kernel/debug/coresight_cpu_debug/enable:: + + # echo 1 > /sys/kernel/debug/coresight_cpu_debug/enable + +To disable it, write a '0' into /sys/kernel/debug/coresight_cpu_debug/enable:: + + # echo 0 > /sys/kernel/debug/coresight_cpu_debug/enable + +As explained in chapter "Clock and power domain", if you are working on one +platform which has idle states to power off debug logic and the power +controller cannot work well for the request from EDPRCR, then you should +firstly constraint CPU idle states before enable CPU debugging feature; so can +ensure the accessing to debug logic. + +If you want to limit idle states at boot time, you can use "nohlt" or +"cpuidle.off=1" in the kernel command line. + +At the runtime you can disable idle states with below methods: + +It is possible to disable CPU idle states by way of the PM QoS +subsystem, more specifically by using the "/dev/cpu_dma_latency" +interface (see Documentation/power/pm_qos_interface.rst for more +details). As specified in the PM QoS documentation the requested +parameter will stay in effect until the file descriptor is released. +For example:: + + # exec 3<> /dev/cpu_dma_latency; echo 0 >&3 + ... + Do some work... + ... + # exec 3<>- + +The same can also be done from an application program. + +Disable specific CPU's specific idle state from cpuidle sysfs (see +Documentation/admin-guide/pm/cpuidle.rst):: + + # echo 1 > /sys/devices/system/cpu/cpu$cpu/cpuidle/state$state/disable + +Output format +------------- + +Here is an example of the debugging output format:: + + ARM external debug module: + coresight-cpu-debug 850000.debug: CPU[0]: + coresight-cpu-debug 850000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock) + coresight-cpu-debug 850000.debug: EDPCSR: handle_IPI+0x174/0x1d8 + coresight-cpu-debug 850000.debug: EDCIDSR: 00000000 + coresight-cpu-debug 850000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0) + coresight-cpu-debug 852000.debug: CPU[1]: + coresight-cpu-debug 852000.debug: EDPRSR: 00000001 (Power:On DLK:Unlock) + coresight-cpu-debug 852000.debug: EDPCSR: debug_notifier_call+0x23c/0x358 + coresight-cpu-debug 852000.debug: EDCIDSR: 00000000 + coresight-cpu-debug 852000.debug: EDVIDSR: 90000000 (State:Non-secure Mode:EL1/0 Width:64bits VMID:0) diff --git a/Documentation/trace/coresight/coresight.rst b/Documentation/trace/coresight/coresight.rst new file mode 100644 index 000000000000..a566719f8e7e --- /dev/null +++ b/Documentation/trace/coresight/coresight.rst @@ -0,0 +1,498 @@ +====================================== +Coresight - HW Assisted Tracing on ARM +====================================== + + :Author: Mathieu Poirier + :Date: September 11th, 2014 + +Introduction +------------ + +Coresight is an umbrella of technologies allowing for the debugging of ARM +based SoC. It includes solutions for JTAG and HW assisted tracing. This +document is concerned with the latter. + +HW assisted tracing is becoming increasingly useful when dealing with systems +that have many SoCs and other components like GPU and DMA engines. ARM has +developed a HW assisted tracing solution by means of different components, each +being added to a design at synthesis time to cater to specific tracing needs. +Components are generally categorised as source, link and sinks and are +(usually) discovered using the AMBA bus. + +"Sources" generate a compressed stream representing the processor instruction +path based on tracing scenarios as configured by users. From there the stream +flows through the coresight system (via ATB bus) using links that are connecting +the emanating source to a sink(s). Sinks serve as endpoints to the coresight +implementation, either storing the compressed stream in a memory buffer or +creating an interface to the outside world where data can be transferred to a +host without fear of filling up the onboard coresight memory buffer. + +At typical coresight system would look like this:: + + ***************************************************************** + **************************** AMBA AXI ****************************===|| + ***************************************************************** || + ^ ^ | || + | | * ** + 0000000 ::::: 0000000 ::::: ::::: @@@@@@@ |||||||||||| + 0 CPU 0<-->: C : 0 CPU 0<-->: C : : C : @ STM @ || System || + |->0000000 : T : |->0000000 : T : : T :<--->@@@@@ || Memory || + | #######<-->: I : | #######<-->: I : : I : @@@<-| |||||||||||| + | # ETM # ::::: | # PTM # ::::: ::::: @ | + | ##### ^ ^ | ##### ^ ! ^ ! . | ||||||||| + | |->### | ! | |->### | ! | ! . | || DAP || + | | # | ! | | # | ! | ! . | ||||||||| + | | . | ! | | . | ! | ! . | | | + | | . | ! | | . | ! | ! . | | * + | | . | ! | | . | ! | ! . | | SWD/ + | | . | ! | | . | ! | ! . | | JTAG + *****************************************************************<-| + *************************** AMBA Debug APB ************************ + ***************************************************************** + | . ! . ! ! . | + | . * . * * . | + ***************************************************************** + ******************** Cross Trigger Matrix (CTM) ******************* + ***************************************************************** + | . ^ . . | + | * ! * * | + ***************************************************************** + ****************** AMBA Advanced Trace Bus (ATB) ****************** + ***************************************************************** + | ! =============== | + | * ===== F =====<---------| + | ::::::::: ==== U ==== + |-->:: CTI ::&& ETB &&<......II I ======= + | ! &&&&&&&&& II I . + | ! I I . + | ! I REP I<.......... + | ! I I + | !!>&&&&&&&&& II I *Source: ARM ltd. + |------>& TPIU &<......II I DAP = Debug Access Port + &&&&&&&&& IIIIIII ETM = Embedded Trace Macrocell + ; PTM = Program Trace Macrocell + ; CTI = Cross Trigger Interface + * ETB = Embedded Trace Buffer + To trace port TPIU= Trace Port Interface Unit + SWD = Serial Wire Debug + +While on target configuration of the components is done via the APB bus, +all trace data are carried out-of-band on the ATB bus. The CTM provides +a way to aggregate and distribute signals between CoreSight components. + +The coresight framework provides a central point to represent, configure and +manage coresight devices on a platform. This first implementation centers on +the basic tracing functionality, enabling components such ETM/PTM, funnel, +replicator, TMC, TPIU and ETB. Future work will enable more +intricate IP blocks such as STM and CTI. + + +Acronyms and Classification +--------------------------- + +Acronyms: + +PTM: + Program Trace Macrocell +ETM: + Embedded Trace Macrocell +STM: + System trace Macrocell +ETB: + Embedded Trace Buffer +ITM: + Instrumentation Trace Macrocell +TPIU: + Trace Port Interface Unit +TMC-ETR: + Trace Memory Controller, configured as Embedded Trace Router +TMC-ETF: + Trace Memory Controller, configured as Embedded Trace FIFO +CTI: + Cross Trigger Interface + +Classification: + +Source: + ETMv3.x ETMv4, PTMv1.0, PTMv1.1, STM, STM500, ITM +Link: + Funnel, replicator (intelligent or not), TMC-ETR +Sinks: + ETBv1.0, ETB1.1, TPIU, TMC-ETF +Misc: + CTI + + +Device Tree Bindings +-------------------- + +See Documentation/devicetree/bindings/arm/coresight.txt for details. + +As of this writing drivers for ITM, STMs and CTIs are not provided but are +expected to be added as the solution matures. + + +Framework and implementation +---------------------------- + +The coresight framework provides a central point to represent, configure and +manage coresight devices on a platform. Any coresight compliant device can +register with the framework for as long as they use the right APIs: + +.. c:function:: struct coresight_device *coresight_register(struct coresight_desc *desc); +.. c:function:: void coresight_unregister(struct coresight_device *csdev); + +The registering function is taking a ``struct coresight_desc *desc`` and +register the device with the core framework. The unregister function takes +a reference to a ``struct coresight_device *csdev`` obtained at registration time. + +If everything goes well during the registration process the new devices will +show up under /sys/bus/coresight/devices, as showns here for a TC2 platform:: + + root:~# ls /sys/bus/coresight/devices/ + replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm + 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm + root:~# + +The functions take a ``struct coresight_device``, which looks like this:: + + struct coresight_desc { + enum coresight_dev_type type; + struct coresight_dev_subtype subtype; + const struct coresight_ops *ops; + struct coresight_platform_data *pdata; + struct device *dev; + const struct attribute_group **groups; + }; + + +The "coresight_dev_type" identifies what the device is, i.e, source link or +sink while the "coresight_dev_subtype" will characterise that type further. + +The ``struct coresight_ops`` is mandatory and will tell the framework how to +perform base operations related to the components, each component having +a different set of requirement. For that ``struct coresight_ops_sink``, +``struct coresight_ops_link`` and ``struct coresight_ops_source`` have been +provided. + +The next field ``struct coresight_platform_data *pdata`` is acquired by calling +``of_get_coresight_platform_data()``, as part of the driver's _probe routine and +``struct device *dev`` gets the device reference embedded in the ``amba_device``:: + + static int etm_probe(struct amba_device *adev, const struct amba_id *id) + { + ... + ... + drvdata->dev = &adev->dev; + ... + } + +Specific class of device (source, link, or sink) have generic operations +that can be performed on them (see ``struct coresight_ops``). The ``**groups`` +is a list of sysfs entries pertaining to operations +specific to that component only. "Implementation defined" customisations are +expected to be accessed and controlled using those entries. + +Device Naming scheme +-------------------- + +The devices that appear on the "coresight" bus were named the same as their +parent devices, i.e, the real devices that appears on AMBA bus or the platform bus. +Thus the names were based on the Linux Open Firmware layer naming convention, +which follows the base physical address of the device followed by the device +type. e.g:: + + root:~# ls /sys/bus/coresight/devices/ + 20010000.etf 20040000.funnel 20100000.stm 22040000.etm + 22140000.etm 230c0000.funnel 23240000.etm 20030000.tpiu + 20070000.etr 20120000.replicator 220c0000.funnel + 23040000.etm 23140000.etm 23340000.etm + +However, with the introduction of ACPI support, the names of the real +devices are a bit cryptic and non-obvious. Thus, a new naming scheme was +introduced to use more generic names based on the type of the device. The +following rules apply:: + + 1) Devices that are bound to CPUs, are named based on the CPU logical + number. + + e.g, ETM bound to CPU0 is named "etm0" + + 2) All other devices follow a pattern, "N", where : + + - A prefix specific to the type of the device + N - a sequential number assigned based on the order + of probing. + + e.g, tmc_etf0, tmc_etr0, funnel0, funnel1 + +Thus, with the new scheme the devices could appear as :: + + root:~# ls /sys/bus/coresight/devices/ + etm0 etm1 etm2 etm3 etm4 etm5 funnel0 + funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0 + +Some of the examples below might refer to old naming scheme and some +to the newer scheme, to give a confirmation that what you see on your +system is not unexpected. One must use the "names" as they appear on +the system under specified locations. + +How to use the tracer modules +----------------------------- + +There are two ways to use the Coresight framework: + +1. using the perf cmd line tools. +2. interacting directly with the Coresight devices using the sysFS interface. + +Preference is given to the former as using the sysFS interface +requires a deep understanding of the Coresight HW. The following sections +provide details on using both methods. + +1) Using the sysFS interface: + +Before trace collection can start, a coresight sink needs to be identified. +There is no limit on the amount of sinks (nor sources) that can be enabled at +any given moment. As a generic operation, all device pertaining to the sink +class will have an "active" entry in sysfs:: + + root:/sys/bus/coresight/devices# ls + replicator 20030000.tpiu 2201c000.ptm 2203c000.etm 2203e000.etm + 20010000.etb 20040000.funnel 2201d000.ptm 2203d000.etm + root:/sys/bus/coresight/devices# ls 20010000.etb + enable_sink status trigger_cntr + root:/sys/bus/coresight/devices# echo 1 > 20010000.etb/enable_sink + root:/sys/bus/coresight/devices# cat 20010000.etb/enable_sink + 1 + root:/sys/bus/coresight/devices# + +At boot time the current etm3x driver will configure the first address +comparator with "_stext" and "_etext", essentially tracing any instruction +that falls within that range. As such "enabling" a source will immediately +trigger a trace capture:: + + root:/sys/bus/coresight/devices# echo 1 > 2201c000.ptm/enable_source + root:/sys/bus/coresight/devices# cat 2201c000.ptm/enable_source + 1 + root:/sys/bus/coresight/devices# cat 20010000.etb/status + Depth: 0x2000 + Status: 0x1 + RAM read ptr: 0x0 + RAM wrt ptr: 0x19d3 <----- The write pointer is moving + Trigger cnt: 0x0 + Control: 0x1 + Flush status: 0x0 + Flush ctrl: 0x2001 + root:/sys/bus/coresight/devices# + +Trace collection is stopped the same way:: + + root:/sys/bus/coresight/devices# echo 0 > 2201c000.ptm/enable_source + root:/sys/bus/coresight/devices# + +The content of the ETB buffer can be harvested directly from /dev:: + + root:/sys/bus/coresight/devices# dd if=/dev/20010000.etb \ + of=~/cstrace.bin + 64+0 records in + 64+0 records out + 32768 bytes (33 kB) copied, 0.00125258 s, 26.2 MB/s + root:/sys/bus/coresight/devices# + +The file cstrace.bin can be decompressed using "ptm2human", DS-5 or Trace32. + +Following is a DS-5 output of an experimental loop that increments a variable up +to a certain value. The example is simple and yet provides a glimpse of the +wealth of possibilities that coresight provides. +:: + + Info Tracing enabled + Instruction 106378866 0x8026B53C E52DE004 false PUSH {lr} + Instruction 0 0x8026B540 E24DD00C false SUB sp,sp,#0xc + Instruction 0 0x8026B544 E3A03000 false MOV r3,#0 + Instruction 0 0x8026B548 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B54C E59D3004 false LDR r3,[sp,#4] + Instruction 0 0x8026B550 E3530004 false CMP r3,#4 + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c + Timestamp Timestamp: 17106715833 + Instruction 319 0x8026B54C E59D3004 false LDR r3,[sp,#4] + Instruction 0 0x8026B550 E3530004 false CMP r3,#4 + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c + Instruction 9 0x8026B54C E59D3004 false LDR r3,[sp,#4] + Instruction 0 0x8026B550 E3530004 false CMP r3,#4 + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c + Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4] + Instruction 0 0x8026B550 E3530004 false CMP r3,#4 + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c + Instruction 7 0x8026B54C E59D3004 false LDR r3,[sp,#4] + Instruction 0 0x8026B550 E3530004 false CMP r3,#4 + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c + Instruction 10 0x8026B54C E59D3004 false LDR r3,[sp,#4] + Instruction 0 0x8026B550 E3530004 false CMP r3,#4 + Instruction 0 0x8026B554 E2833001 false ADD r3,r3,#1 + Instruction 0 0x8026B558 E58D3004 false STR r3,[sp,#4] + Instruction 0 0x8026B55C DAFFFFFA true BLE {pc}-0x10 ; 0x8026b54c + Instruction 6 0x8026B560 EE1D3F30 false MRC p15,#0x0,r3,c13,c0,#1 + Instruction 0 0x8026B564 E1A0100D false MOV r1,sp + Instruction 0 0x8026B568 E3C12D7F false BIC r2,r1,#0x1fc0 + Instruction 0 0x8026B56C E3C2203F false BIC r2,r2,#0x3f + Instruction 0 0x8026B570 E59D1004 false LDR r1,[sp,#4] + Instruction 0 0x8026B574 E59F0010 false LDR r0,[pc,#16] ; [0x8026B58C] = 0x80550368 + Instruction 0 0x8026B578 E592200C false LDR r2,[r2,#0xc] + Instruction 0 0x8026B57C E59221D0 false LDR r2,[r2,#0x1d0] + Instruction 0 0x8026B580 EB07A4CF true BL {pc}+0x1e9344 ; 0x804548c4 + Info Tracing enabled + Instruction 13570831 0x8026B584 E28DD00C false ADD sp,sp,#0xc + Instruction 0 0x8026B588 E8BD8000 true LDM sp!,{pc} + Timestamp Timestamp: 17107041535 + +2) Using perf framework: + +Coresight tracers are represented using the Perf framework's Performance +Monitoring Unit (PMU) abstraction. As such the perf framework takes charge of +controlling when tracing gets enabled based on when the process of interest is +scheduled. When configured in a system, Coresight PMUs will be listed when +queried by the perf command line tool: + + linaro@linaro-nano:~$ ./perf list pmu + + List of pre-defined events (to be used in -e): + + cs_etm// [Kernel PMU event] + + linaro@linaro-nano:~$ + +Regardless of the number of tracers available in a system (usually equal to the +amount of processor cores), the "cs_etm" PMU will be listed only once. + +A Coresight PMU works the same way as any other PMU, i.e the name of the PMU is +listed along with configuration options within forward slashes '/'. Since a +Coresight system will typically have more than one sink, the name of the sink to +work with needs to be specified as an event option. +On newer kernels the available sinks are listed in sysFS under +($SYSFS)/bus/event_source/devices/cs_etm/sinks/:: + + root@localhost:/sys/bus/event_source/devices/cs_etm/sinks# ls + tmc_etf0 tmc_etr0 tpiu0 + +On older kernels, this may need to be found from the list of coresight devices, +available under ($SYSFS)/bus/coresight/devices/:: + + root:~# ls /sys/bus/coresight/devices/ + etm0 etm1 etm2 etm3 etm4 etm5 funnel0 + funnel1 funnel2 replicator0 stm0 tmc_etf0 tmc_etr0 tpiu0 + root@linaro-nano:~# perf record -e cs_etm/@tmc_etr0/u --per-thread program + +As mentioned above in section "Device Naming scheme", the names of the devices could +look different from what is used in the example above. One must use the device names +as it appears under the sysFS. + +The syntax within the forward slashes '/' is important. The '@' character +tells the parser that a sink is about to be specified and that this is the sink +to use for the trace session. + +More information on the above and other example on how to use Coresight with +the perf tools can be found in the "HOWTO.md" file of the openCSD gitHub +repository [#third]_. + +2.1) AutoFDO analysis using the perf tools: + +perf can be used to record and analyze trace of programs. + +Execution can be recorded using 'perf record' with the cs_etm event, +specifying the name of the sink to record to, e.g:: + + perf record -e cs_etm/@tmc_etr0/u --per-thread + +The 'perf report' and 'perf script' commands can be used to analyze execution, +synthesizing instruction and branch events from the instruction trace. +'perf inject' can be used to replace the trace data with the synthesized events. +The --itrace option controls the type and frequency of synthesized events +(see perf documentation). + +Note that only 64-bit programs are currently supported - further work is +required to support instruction decode of 32-bit Arm programs. + + +Generating coverage files for Feedback Directed Optimization: AutoFDO +--------------------------------------------------------------------- + +'perf inject' accepts the --itrace option in which case tracing data is +removed and replaced with the synthesized events. e.g. +:: + + perf inject --itrace --strip -i perf.data -o perf.data.new + +Below is an example of using ARM ETM for autoFDO. It requires autofdo +(https://github.com/google/autofdo) and gcc version 5. The bubble +sort example is from the AutoFDO tutorial (https://gcc.gnu.org/wiki/AutoFDO/Tutorial). +:: + + $ gcc-5 -O3 sort.c -o sort + $ taskset -c 2 ./sort + Bubble sorting array of 30000 elements + 5910 ms + + $ perf record -e cs_etm/@tmc_etr0/u --per-thread taskset -c 2 ./sort + Bubble sorting array of 30000 elements + 12543 ms + [ perf record: Woken up 35 times to write data ] + [ perf record: Captured and wrote 69.640 MB perf.data ] + + $ perf inject -i perf.data -o inj.data --itrace=il64 --strip + $ create_gcov --binary=./sort --profile=inj.data --gcov=sort.gcov -gcov_version=1 + $ gcc-5 -O3 -fauto-profile=sort.gcov sort.c -o sort_autofdo + $ taskset -c 2 ./sort_autofdo + Bubble sorting array of 30000 elements + 5806 ms + + +How to use the STM module +------------------------- + +Using the System Trace Macrocell module is the same as the tracers - the only +difference is that clients are driving the trace capture rather +than the program flow through the code. + +As with any other CoreSight component, specifics about the STM tracer can be +found in sysfs with more information on each entry being found in [#first]_:: + + root@genericarmv8:~# ls /sys/bus/coresight/devices/stm0 + enable_source hwevent_select port_enable subsystem uevent + hwevent_enable mgmt port_select traceid + root@genericarmv8:~# + +Like any other source a sink needs to be identified and the STM enabled before +being used:: + + root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/tmc_etf0/enable_sink + root@genericarmv8:~# echo 1 > /sys/bus/coresight/devices/stm0/enable_source + +From there user space applications can request and use channels using the devfs +interface provided for that purpose by the generic STM API:: + + root@genericarmv8:~# ls -l /dev/stm0 + crw------- 1 root root 10, 61 Jan 3 18:11 /dev/stm0 + root@genericarmv8:~# + +Details on how to use the generic STM API can be found here:- :doc:`../stm` [#second]_. + +.. [#first] Documentation/ABI/testing/sysfs-bus-coresight-devices-stm + +.. [#second] Documentation/trace/stm.rst + +.. [#third] https://github.com/Linaro/perf-opencsd diff --git a/Documentation/trace/coresight/index.rst b/Documentation/trace/coresight/index.rst new file mode 100644 index 000000000000..8d31b155a87c --- /dev/null +++ b/Documentation/trace/coresight/index.rst @@ -0,0 +1,9 @@ +============================== +CoreSight - ARM Hardware Trace +============================== + +.. toctree:: + :maxdepth: 2 + :glob: + + * diff --git a/Documentation/trace/index.rst b/Documentation/trace/index.rst index b7891cb1ab4d..04acd277c5f6 100644 --- a/Documentation/trace/index.rst +++ b/Documentation/trace/index.rst @@ -23,5 +23,4 @@ Linux Tracing Technologies intel_th stm sys-t - coresight - coresight-cpu-debug + coresight/index diff --git a/MAINTAINERS b/MAINTAINERS index dada80b45d4c..2904dacba8fe 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -1610,8 +1610,7 @@ R: Suzuki K Poulose L: linux-arm-kernel@lists.infradead.org (moderated for non-subscribers) S: Maintained F: drivers/hwtracing/coresight/* -F: Documentation/trace/coresight.rst -F: Documentation/trace/coresight-cpu-debug.rst +F: Documentation/trace/coresight/* F: Documentation/devicetree/bindings/arm/coresight.txt F: Documentation/devicetree/bindings/arm/coresight-cpu-debug.txt F: Documentation/ABI/testing/sysfs-bus-coresight-devices-* -- cgit From f0ae2cfae53b8057380801a7549f388adee59a8e Mon Sep 17 00:00:00 2001 From: Mike Leach Date: Thu, 31 Oct 2019 11:58:34 -0600 Subject: coresight: etm4x: docs: Adds detailed document for programming etm4x. Add in detailed programmers reference for users wanting to program the CoreSight ETM 4.x driver using sysfs. Signed-off-by: Mike Leach Reviewed-by: Mathieu Poirier Signed-off-by: Jonathan Corbet --- .../trace/coresight/coresight-etm4x-reference.rst | 798 +++++++++++++++++++++ 1 file changed, 798 insertions(+) create mode 100644 Documentation/trace/coresight/coresight-etm4x-reference.rst diff --git a/Documentation/trace/coresight/coresight-etm4x-reference.rst b/Documentation/trace/coresight/coresight-etm4x-reference.rst new file mode 100644 index 000000000000..b64d9a9c79df --- /dev/null +++ b/Documentation/trace/coresight/coresight-etm4x-reference.rst @@ -0,0 +1,798 @@ +=============================================== +ETMv4 sysfs linux driver programming reference. +=============================================== + + :Author: Mike Leach + :Date: October 11th, 2019 + +Supplement to existing ETMv4 driver documentation. + +Sysfs files and directories +--------------------------- + +Root: ``/sys/bus/coresight/devices/etm`` + + +The following paragraphs explain the association between sysfs files and the +ETMv4 registers that they effect. Note the register names are given without +the ‘TRC’ prefix. + +---- + +:File: ``mode`` (rw) +:Trace Registers: {CONFIGR + others} +:Notes: + Bit select trace features. See ‘mode’ section below. Bits + in this will cause equivalent programming of trace config and + other registers to enable the features requested. + +:Syntax & eg: + ``echo bitfield > mode`` + + bitfield up to 32 bits setting trace features. + +:Example: + ``$> echo 0x012 > mode`` + +---- + +:File: ``reset`` (wo) +:Trace Registers: All +:Notes: + Reset all programming to trace nothing / no logic programmed. + +:Syntax: + ``echo 1 > reset`` + +---- + +:File: ``enable_source`` (wo) +:Trace Registers: PRGCTLR, All hardware regs. +:Notes: + - > 0 : Programs up the hardware with the current values held in the driver + and enables trace. + + - = 0 : disable trace hardware. + +:Syntax: + ``echo 1 > enable_source`` + +---- + +:File: ``cpu`` (ro) +:Trace Registers: None. +:Notes: + CPU ID that this ETM is attached to. + +:Example: + ``$> cat cpu`` + + ``$> 0`` + +---- + +:File: ``addr_idx`` (rw) +:Trace Registers: None. +:Notes: + Virtual register to index address comparator and range + features. Set index for first of the pair in a range. + +:Syntax: + ``echo idx > addr_idx`` + + Where idx < nr_addr_cmp x 2 + +---- + +:File: ``addr_range`` (rw) +:Trace Registers: ACVR[idx, idx+1], VIIECTLR +:Notes: + Pair of addresses for a range selected by addr_idx. Include + / exclude according to the optional parameter, or if omitted + uses the current ‘mode’ setting. Select comparator range in + control register. Error if index is odd value. + +:Depends: ``mode, addr_idx`` +:Syntax: + ``echo addr1 addr2 [exclude] > addr_range`` + + Where addr1 and addr2 define the range and addr1 < addr2. + + Optional exclude value:- + + - 0 for include + - 1 for exclude. +:Example: + ``$> echo 0x0000 0x2000 0 > addr_range`` + +---- + +:File: ``addr_single`` (rw) +:Trace Registers: ACVR[idx] +:Notes: + Set a single address comparator according to addr_idx. This + is used if the address comparator is used as part of event + generation logic etc. + +:Depends: ``addr_idx`` +:Syntax: + ``echo addr1 > addr_single`` + +---- + +:File: ``addr_start`` (rw) +:Trace Registers: ACVR[idx], VISSCTLR +:Notes: + Set a trace start address comparator according to addr_idx. + Select comparator in control register. + +:Depends: ``addr_idx`` +:Syntax: + ``echo addr1 > addr_start`` + +---- + +:File: ``addr_stop`` (rw) +:Trace Registers: ACVR[idx], VISSCTLR +:Notes: + Set a trace stop address comparator according to addr_idx. + Select comparator in control register. + +:Depends: ``addr_idx`` +:Syntax: + ``echo addr1 > addr_stop`` + +---- + +:File: ``addr_context`` (rw) +:Trace Registers: ACATR[idx,{6:4}] +:Notes: + Link context ID comparator to address comparator addr_idx + +:Depends: ``addr_idx`` +:Syntax: + ``echo ctxt_idx > addr_context`` + + Where ctxt_idx is the index of the linked context id / vmid + comparator. + +---- + +:File: ``addr_ctxtype`` (rw) +:Trace Registers: ACATR[idx,{3:2}] +:Notes: + Input value string. Set type for linked context ID comparator + +:Depends: ``addr_idx`` +:Syntax: + ``echo type > addr_ctxtype`` + + Type one of {all, vmid, ctxid, none} +:Example: + ``$> echo ctxid > addr_ctxtype`` + +---- + +:File: ``addr_exlevel_s_ns`` (rw) +:Trace Registers: ACATR[idx,{14:8}] +:Notes: + Set the ELx secure and non-secure matching bits for the + selected address comparator + +:Depends: ``addr_idx`` +:Syntax: + ``echo val > addr_exlevel_s_ns`` + + val is a 7 bit value for exception levels to exclude. Input + value shifted to correct bits in register. +:Example: + ``$> echo 0x4F > addr_exlevel_s_ns`` + +---- + +:File: ``addr_instdatatype`` (rw) +:Trace Registers: ACATR[idx,{1:0}] +:Notes: + Set the comparator address type for matching. Driver only + supports setting instruction address type. + +:Depends: ``addr_idx`` + +---- + +:File: ``addr_cmp_view`` (ro) +:Trace Registers: ACVR[idx, idx+1], ACATR[idx], VIIECTLR +:Notes: + Read the currently selected address comparator. If part of + address range then display both addresses. + +:Depends: ``addr_idx`` +:Syntax: + ``cat addr_cmp_view`` +:Example: + ``$> cat addr_cmp_view`` + + ``addr_cmp[0] range 0x0 0xffffffffffffffff include ctrl(0x4b00)`` + +---- + +:File: ``nr_addr_cmp`` (ro) +:Trace Registers: From IDR4 +:Notes: + Number of address comparator pairs + +---- + +:File: ``sshot_idx`` (rw) +:Trace Registers: None +:Notes: + Select single shot register set. + +---- + +:File: ``sshot_ctrl`` (rw) +:Trace Registers: SSCCR[idx] +:Notes: + Access a single shot comparator control register. + +:Depends: ``sshot_idx`` +:Syntax: + ``echo val > sshot_ctrl`` + + Writes val into the selected control register. + +---- + +:File: ``sshot_status`` (ro) +:Trace Registers: SSCSR[idx] +:Notes: + Read a single shot comparator status register + +:Depends: ``sshot_idx`` +:Syntax: + ``cat sshot_status`` + + Read status. +:Example: + ``$> cat sshot_status`` + + ``0x1`` + +---- + +:File: ``sshot_pe_ctrl`` (rw) +:Trace Registers: SSPCICR[idx] +:Notes: + Access a single shot PE comparator input control register. + +:Depends: ``sshot_idx`` +:Syntax: + ``echo val > sshot_pe_ctrl`` + + Writes val into the selected control register. + +---- + +:File: ``ns_exlevel_vinst`` (rw) +:Trace Registers: VICTLR{23:20} +:Notes: + Program non-secure exception level filters. Set / clear NS + exception filter bits. Setting ‘1’ excludes trace from the + exception level. + +:Syntax: + ``echo bitfield > ns_exlevel_viinst`` + + Where bitfield contains bits to set clear for EL0 to EL2 +:Example: + ``%> echo 0x4 > ns_exlevel_viinst`` + + Excludes EL2 NS trace. + +---- + +:File: ``vinst_pe_cmp_start_stop`` (rw) +:Trace Registers: VIPCSSCTLR +:Notes: + Access PE start stop comparator input control registers + +---- + +:File: ``bb_ctrl`` (rw) +:Trace Registers: BBCTLR +:Notes: + Define ranges that Branch Broadcast will operate in. + Default (0x0) is all addresses. + +:Depends: BB enabled. + +---- + +:File: ``cyc_threshold`` (rw) +:Trace Registers: CCCTLR +:Notes: + Set the threshold for which cycle counts will be emitted. + Error if attempt to set below minimum defined in IDR3, masked + to width of valid bits. + +:Depends: CC enabled. + +---- + +:File: ``syncfreq`` (rw) +:Trace Registers: SYNCPR +:Notes: + Set trace synchronisation period. Power of 2 value, 0 (off) + or 8-20. Driver defaults to 12 (every 4096 bytes). + +---- + +:File: ``cntr_idx`` (rw) +:Trace Registers: none +:Notes: + Select the counter to access + +:Syntax: + ``echo idx > cntr_idx`` + + Where idx < nr_cntr + +---- + +:File: ``cntr_ctrl`` (rw) +:Trace Registers: CNTCTLR[idx] +:Notes: + Set counter control value. + +:Depends: ``cntr_idx`` +:Syntax: + ``echo val > cntr_ctrl`` + + Where val is per ETMv4 spec. + +---- + +:File: ``cntrldvr`` (rw) +:Trace Registers: CNTRLDVR[idx] +:Notes: + Set counter reload value. + +:Depends: ``cntr_idx`` +:Syntax: + ``echo val > cntrldvr`` + + Where val is per ETMv4 spec. + +---- + +:File: ``nr_cntr`` (ro) +:Trace Registers: From IDR5 + +:Notes: + Number of counters implemented. + +---- + +:File: ``ctxid_idx`` (rw) +:Trace Registers: None +:Notes: + Select the context ID comparator to access + +:Syntax: + ``echo idx > ctxid_idx`` + + Where idx < numcidc + +---- + +:File: ``ctxid_pid`` (rw) +:Trace Registers: CIDCVR[idx] +:Notes: + Set the context ID comparator value + +:Depends: ``ctxid_idx`` + +---- + +:File: ``ctxid_masks`` (rw) +:Trace Registers: CIDCCTLR0, CIDCCTLR1, CIDCVR<0-7> +:Notes: + Pair of values to set the byte masks for 1-8 context ID + comparators. Automatically clears masked bytes to 0 in CID + value registers. + +:Syntax: + ``echo m3m2m1m0 [m7m6m5m4] > ctxid_masks`` + + 32 bit values made up of mask bytes, where mN represents a + byte mask value for Context ID comparator N. + + Second value not required on systems that have fewer than 4 + context ID comparators + +---- + +:File: ``numcidc`` (ro) +:Trace Registers: From IDR4 +:Notes: + Number of Context ID comparators + +---- + +:File: ``vmid_idx`` (rw) +:Trace Registers: None +:Notes: + Select the VM ID comparator to access. + +:Syntax: + ``echo idx > vmid_idx`` + + Where idx <  numvmidc + +---- + +:File: ``vmid_val`` (rw) +:Trace Registers: VMIDCVR[idx] +:Notes: + Set the VM ID comparator value + +:Depends: ``vmid_idx`` + +---- + +:File: ``vmid_masks`` (rw) +:Trace Registers: VMIDCCTLR0, VMIDCCTLR1, VMIDCVR<0-7> +:Notes: + Pair of values to set the byte masks for 1-8 VM ID comparators. + Automatically clears masked bytes to 0 in VMID value registers. + +:Syntax: + ``echo m3m2m1m0 [m7m6m5m4] > vmid_masks`` + + Where mN represents a byte mask value for VMID comparator N. + Second value not required on systems that have fewer than 4 + VMID comparators. + +---- + +:File: ``numvmidc`` (ro) +:Trace Registers: From IDR4 +:Notes: + Number of VMID comparators + +---- + +:File: ``res_idx`` (rw) +:Trace Registers: None. +:Notes: + Select the resource selector control to access. Must be 2 or + higher as selectors 0 and 1 are hardwired. + +:Syntax: + ``echo idx > res_idx`` + + Where 2 <= idx < nr_resource x 2 + +---- + +:File: ``res_ctrl`` (rw) +:Trace Registers: RSCTLR[idx] +:Notes: + Set resource selector control value. Value per ETMv4 spec. + +:Depends: ``res_idx`` +:Syntax: + ``echo val > res_cntr`` + + Where val is per ETMv4 spec. + +---- + +:File: ``nr_resource`` (ro) +:Trace Registers: From IDR4 +:Notes: + Number of resource selector pairs + +---- + +:File: ``event`` (rw) +:Trace Registers: EVENTCTRL0R +:Notes: + Set up to 4 implemented event fields. + +:Syntax: + ``echo ev3ev2ev1ev0 > event`` + + Where evN is an 8 bit event field. Up to 4 event fields make up the + 32-bit input value. Number of valid fields is implementation dependent, + defined in IDR0. + +---- + +:File: ``event_instren`` (rw) +:Trace Registers: EVENTCTRL1R +:Notes: + Choose events which insert event packets into trace stream. + +:Depends: EVENTCTRL0R +:Syntax: + ``echo bitfield > event_instren`` + + Where bitfield is up to 4 bits according to number of event fields. + +---- + +:File: ``event_ts`` (rw) +:Trace Registers: TSCTLR +:Notes: + Set the event that will generate timestamp requests. + +:Depends: ``TS activated`` +:Syntax: + ``echo evfield > event_ts`` + + Where evfield is an 8 bit event selector. + +---- + +:File: ``seq_idx`` (rw) +:Trace Registers: None +:Notes: + Sequencer event register select - 0 to 2 + +---- + +:File: ``seq_state`` (rw) +:Trace Registers: SEQSTR +:Notes: + Sequencer current state - 0 to 3. + +---- + +:File: ``seq_event`` (rw) +:Trace Registers: SEQEVR[idx] +:Notes: + State transition event registers + +:Depends: ``seq_idx`` +:Syntax: + ``echo evBevF > seq_event`` + + Where evBevF is a 16 bit value made up of two event selectors, + + - evB : back + - evF : forwards. + +---- + +:File: ``seq_reset_event`` (rw) +:Trace Registers: SEQRSTEVR +:Notes: + Sequencer reset event + +:Syntax: + ``echo evfield > seq_reset_event`` + + Where evfield is an 8 bit event selector. + +---- + +:File: ``nrseqstate`` (ro) +:Trace Registers: From IDR5 +:Notes: + Number of sequencer states (0 or 4) + +---- + +:File: ``nr_pe_cmp`` (ro) +:Trace Registers: From IDR4 +:Notes: + Number of PE comparator inputs + +---- + +:File: ``nr_ext_inp`` (ro) +:Trace Registers: From IDR5 +:Notes: + Number of external inputs + +---- + +:File: ``nr_ss_cmp`` (ro) +:Trace Registers: From IDR4 +:Notes: + Number of Single Shot control registers + +---- + +*Note:* When programming any address comparator the driver will tag the +comparator with a type used - i.e. RANGE, SINGLE, START, STOP. Once this tag +is set, then only the values can be changed using the same sysfs file / type +used to program it. + +Thus:: + + % echo 0 > addr_idx ; select address comparator 0 + % echo 0x1000 0x5000 0 > addr_range ; set address range on comparators 0, 1. + % echo 0x2000 > addr_start ; error as comparator 0 is a range comparator + % echo 2 > addr_idx ; select address comparator 2 + % echo 0x2000 > addr_start ; this is OK as comparator 2 is unused. + % echo 0x3000 > addr_stop ; error as comparator 2 set as start address. + % echo 2 > addr_idx ; select address comparator 3 + % echo 0x3000 > addr_stop ; this is OK + +To remove programming on all the comparators (and all the other hardware) use +the reset parameter:: + + % echo 1 > reset + + + +The ‘mode’ sysfs parameter. +--------------------------- + +This is a bitfield selection parameter that sets the overall trace mode for the +ETM. The table below describes the bits, using the defines from the driver +source file, along with a description of the feature these represent. Many +features are optional and therefore dependent on implementation in the +hardware. + +Bit assignments shown below:- + +---- + +**bit (0):** + ETM_MODE_EXCLUDE + +**description:** + This is the default value for the include / exclude function when + setting address ranges. Set 1 for exclude range. When the mode + parameter is set this value is applied to the currently indexed + address range. + + +**bit (4):** + ETM_MODE_BB + +**description:** + Set to enable branch broadcast if supported in hardware [IDR0]. + + +**bit (5):** + ETMv4_MODE_CYCACC + +**description:** + Set to enable cycle accurate trace if supported [IDR0]. + + +**bit (6):** + ETMv4_MODE_CTXID + +**description:** + Set to enable context ID tracing if supported in hardware [IDR2]. + + +**bit (7):** + ETM_MODE_VMID + +**description:** + Set to enable virtual machine ID tracing if supported [IDR2]. + + +**bit (11):** + ETMv4_MODE_TIMESTAMP + +**description:** + Set to enable timestamp generation if supported [IDR0]. + + +**bit (12):** + ETM_MODE_RETURNSTACK +**description:** + Set to enable trace return stack use if supported [IDR0]. + + +**bit (13-14):** + ETM_MODE_QELEM(val) + +**description:** + ‘val’ determines level of Q element support enabled if + implemented by the ETM [IDR0] + + +**bit (19):** + ETM_MODE_ATB_TRIGGER + +**description:** + Set to enable the ATBTRIGGER bit in the event control register + [EVENTCTLR1] if supported [IDR5]. + + +**bit (20):** + ETM_MODE_LPOVERRIDE + +**description:** + Set to enable the LPOVERRIDE bit in the event control register + [EVENTCTLR1], if supported [IDR5]. + + +**bit (21):** + ETM_MODE_ISTALL_EN + +**description:** + Set to enable the ISTALL bit in the stall control register + [STALLCTLR] + + +**bit (23):** + ETM_MODE_INSTPRIO + +**description:** + Set to enable the INSTPRIORITY bit in the stall control register + [STALLCTLR] , if supported [IDR0]. + + +**bit (24):** + ETM_MODE_NOOVERFLOW + +**description:** + Set to enable the NOOVERFLOW bit in the stall control register + [STALLCTLR], if supported [IDR3]. + + +**bit (25):** + ETM_MODE_TRACE_RESET + +**description:** + Set to enable the TRCRESET bit in the viewinst control register + [VICTLR] , if supported [IDR3]. + + +**bit (26):** + ETM_MODE_TRACE_ERR + +**description:** + Set to enable the TRCCTRL bit in the viewinst control register + [VICTLR]. + + +**bit (27):** + ETM_MODE_VIEWINST_STARTSTOP + +**description:** + Set the initial state value of the ViewInst start / stop logic + in the viewinst control register [VICTLR] + + +**bit (30):** + ETM_MODE_EXCL_KERN + +**description:** + Set default trace setup to exclude kernel mode trace (see note a) + + +**bit (31):** + ETM_MODE_EXCL_USER + +**description:** + Set default trace setup to exclude user space trace (see note a) + +---- + +*Note a)* On startup the ETM is programmed to trace the complete address space +using address range comparator 0. ‘mode’ bits 30 / 31 modify this setting to +set EL exclude bits for NS state in either user space (EL0) or kernel space +(EL1) in the address range comparator. (the default setting excludes all +secure EL, and NS EL2) + +Once the reset parameter has been used, and/or custom programming has been +implemented - using these bits will result in the EL bits for address +comparator 0 being set in the same way. + +*Note b)* Bits 2-3, 8-10, 15-16, 18, 22, control features that only work with +data trace. As A-profile data trace is architecturally prohibited in ETMv4, +these have been omitted here. Possible uses could be where a kernel has +support for control of R or M profile infrastructure as part of a heterogeneous +system. + +Bits 17, 28-29 are unused. -- cgit From 88288ed050adb5a96f6063d2d0e3e35bac8e84c2 Mon Sep 17 00:00:00 2001 From: Miles Chen Date: Tue, 1 Oct 2019 18:04:49 +0800 Subject: docs: printk-formats: add ptrdiff_t type to printk-formats When print the difference between two pointers, we should use the ptrdiff_t modifier %t. Signed-off-by: Miles Chen Signed-off-by: Jonathan Corbet --- Documentation/core-api/printk-formats.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/Documentation/core-api/printk-formats.rst b/Documentation/core-api/printk-formats.rst index ecbebf4ca8e7..8a0f49cd158b 100644 --- a/Documentation/core-api/printk-formats.rst +++ b/Documentation/core-api/printk-formats.rst @@ -135,6 +135,20 @@ equivalent to %lx (or %lu). %px is preferred because it is more uniquely grep'able. If in the future we need to modify the way the kernel handles printing pointers we will be better equipped to find the call sites. +Pointer Differences +------------------- + +:: + + %td 2560 + %tx a00 + +For printing the pointer differences, use the %t modifier for ptrdiff_t. + +Example:: + + printk("test: difference between pointers: %td\n", ptr2 - ptr1); + Struct Resources ---------------- -- cgit From 4a9acb6de0f260ff54d45e163fdd1cb17a01beed Mon Sep 17 00:00:00 2001 From: Tom Lendacky Date: Mon, 11 Nov 2019 13:34:37 -0600 Subject: Documentation/process: Add AMD contact for embargoed hardware issues Add myself as the AMD ambassador to the embargoed hardware issues document. Signed-off-by: Tom Lendacky Signed-off-by: Jonathan Corbet --- Documentation/process/embargoed-hardware-issues.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/process/embargoed-hardware-issues.rst b/Documentation/process/embargoed-hardware-issues.rst index a3c3349046c4..799580acc8de 100644 --- a/Documentation/process/embargoed-hardware-issues.rst +++ b/Documentation/process/embargoed-hardware-issues.rst @@ -240,7 +240,7 @@ an involved disclosed party. The current ambassadors list: ============= ======================================================== ARM - AMD + AMD Tom Lendacky IBM Intel Tony Luck Qualcomm Trilok Soni -- cgit From 14d3fe428be5d332b33a3ad04bcc818641c197a8 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Tue, 12 Nov 2019 09:43:15 -0700 Subject: Revert "Documentation: admin-guide: add earlycon documentation for RISC-V" This reverts commit 7f70ae564b807f81263326d641514c6dca88e5ef. Christoph H. notes that the information is redundant, and Paul W. agrees with reverting. Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/kernel-parameters.txt | 4 ---- 1 file changed, 4 deletions(-) diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index dfad762f89b7..3e24f0a93ae9 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -988,10 +988,6 @@ chosen node or the ACPI SPCR table if supported by the platform. - [RISCV] When used with no options, the early - console is determined by the stdout-path - property in the device tree's chosen node. - cdns,[,options] Start an early, polled-mode console on a Cadence (xuartps) serial port at the specified address. Only -- cgit From f11f2a3c543557d7f8ae8bb884c4b705b3b516cd Mon Sep 17 00:00:00 2001 From: Jaskaran Singh Date: Sun, 17 Nov 2019 22:54:34 +0530 Subject: docs: filesystems: convert autofs.txt to reST Convert autofs.txt to reST. The following changes abound: - Introduce reST formatting for headings, lists et al. - Add an indentation of an 8 space tab wherever suitable, so as to maintain consistency. - Remove indentation of the description of the ioctls which are similar to the AUTOFS_IOC ioctls, as it does not come out quite right in HTML. - Add an entry for autofs in the index. Signed-off-by: Jaskaran Singh Signed-off-by: Jonathan Corbet --- Documentation/filesystems/autofs.rst | 574 +++++++++++++++++++++++++++++++++++ Documentation/filesystems/autofs.txt | 559 ---------------------------------- Documentation/filesystems/index.rst | 1 + 3 files changed, 575 insertions(+), 559 deletions(-) create mode 100644 Documentation/filesystems/autofs.rst delete mode 100644 Documentation/filesystems/autofs.txt diff --git a/Documentation/filesystems/autofs.rst b/Documentation/filesystems/autofs.rst new file mode 100644 index 000000000000..6702a5f61f50 --- /dev/null +++ b/Documentation/filesystems/autofs.rst @@ -0,0 +1,574 @@ +===================== +autofs - how it works +===================== + +Purpose +======= + +The goal of autofs is to provide on-demand mounting and race free +automatic unmounting of various other filesystems. This provides two +key advantages: + +1. There is no need to delay boot until all filesystems that + might be needed are mounted. Processes that try to access those + slow filesystems might be delayed but other processes can + continue freely. This is particularly important for + network filesystems (e.g. NFS) or filesystems stored on + media with a media-changing robot. + +2. The names and locations of filesystems can be stored in + a remote database and can change at any time. The content + in that data base at the time of access will be used to provide + a target for the access. The interpretation of names in the + filesystem can even be programmatic rather than database-backed, + allowing wildcards for example, and can vary based on the user who + first accessed a name. + +Context +======= + +The "autofs" filesystem module is only one part of an autofs system. +There also needs to be a user-space program which looks up names +and mounts filesystems. This will often be the "automount" program, +though other tools including "systemd" can make use of "autofs". +This document describes only the kernel module and the interactions +required with any user-space program. Subsequent text refers to this +as the "automount daemon" or simply "the daemon". + +"autofs" is a Linux kernel module with provides the "autofs" +filesystem type. Several "autofs" filesystems can be mounted and they +can each be managed separately, or all managed by the same daemon. + +Content +======= + +An autofs filesystem can contain 3 sorts of objects: directories, +symbolic links and mount traps. Mount traps are directories with +extra properties as described in the next section. + +Objects can only be created by the automount daemon: symlinks are +created with a regular `symlink` system call, while directories and +mount traps are created with `mkdir`. The determination of whether a +directory should be a mount trap or not is quite ad hoc, largely for +historical reasons, and is determined in part by the +*direct*/*indirect*/*offset* mount options, and the *maxproto* mount option. + +If neither the *direct* or *offset* mount options are given (so the +mount is considered to be *indirect*), then the root directory is +always a regular directory, otherwise it is a mount trap when it is +empty and a regular directory when not empty. Note that *direct* and +*offset* are treated identically so a concise summary is that the root +directory is a mount trap only if the filesystem is mounted *direct* +and the root is empty. + +Directories created in the root directory are mount traps only if the +filesystem is mounted *indirect* and they are empty. + +Directories further down the tree depend on the *maxproto* mount +option and particularly whether it is less than five or not. +When *maxproto* is five, no directories further down the +tree are ever mount traps, they are always regular directories. When +the *maxproto* is four (or three), these directories are mount traps +precisely when they are empty. + +So: non-empty (i.e. non-leaf) directories are never mount traps. Empty +directories are sometimes mount traps, and sometimes not depending on +where in the tree they are (root, top level, or lower), the *maxproto*, +and whether the mount was *indirect* or not. + +Mount Traps +=========== + +A core element of the implementation of autofs is the Mount Traps +which are provided by the Linux VFS. Any directory provided by a +filesystem can be designated as a trap. This involves two separate +features that work together to allow autofs to do its job. + +**DCACHE_NEED_AUTOMOUNT** + +If a dentry has the DCACHE_NEED_AUTOMOUNT flag set (which gets set if +the inode has S_AUTOMOUNT set, or can be set directly) then it is +(potentially) a mount trap. Any access to this directory beyond a +"`stat`" will (normally) cause the `d_op->d_automount()` dentry operation +to be called. The task of this method is to find the filesystem that +should be mounted on the directory and to return it. The VFS is +responsible for actually mounting the root of this filesystem on the +directory. + +autofs doesn't find the filesystem itself but sends a message to the +automount daemon asking it to find and mount the filesystem. The +autofs `d_automount` method then waits for the daemon to report that +everything is ready. It will then return "`NULL`" indicating that the +mount has already happened. The VFS doesn't try to mount anything but +follows down the mount that is already there. + +This functionality is sufficient for some users of mount traps such +as NFS which creates traps so that mountpoints on the server can be +reflected on the client. However it is not sufficient for autofs. As +mounting onto a directory is considered to be "beyond a `stat`", the +automount daemon would not be able to mount a filesystem on the 'trap' +directory without some way to avoid getting caught in the trap. For +that purpose there is another flag. + +**DCACHE_MANAGE_TRANSIT** + +If a dentry has DCACHE_MANAGE_TRANSIT set then two very different but +related behaviours are invoked, both using the `d_op->d_manage()` +dentry operation. + +Firstly, before checking to see if any filesystem is mounted on the +directory, d_manage() will be called with the `rcu_walk` parameter set +to `false`. It may return one of three things: + +- A return value of zero indicates that there is nothing special + about this dentry and normal checks for mounts and automounts + should proceed. + + autofs normally returns zero, but first waits for any + expiry (automatic unmounting of the mounted filesystem) to + complete. This avoids races. + +- A return value of `-EISDIR` tells the VFS to ignore any mounts + on the directory and to not consider calling `->d_automount()`. + This effectively disables the **DCACHE_NEED_AUTOMOUNT** flag + causing the directory not be a mount trap after all. + + autofs returns this if it detects that the process performing the + lookup is the automount daemon and that the mount has been + requested but has not yet completed. How it determines this is + discussed later. This allows the automount daemon not to get + caught in the mount trap. + + There is a subtlety here. It is possible that a second autofs + filesystem can be mounted below the first and for both of them to + be managed by the same daemon. For the daemon to be able to mount + something on the second it must be able to "walk" down past the + first. This means that d_manage cannot *always* return -EISDIR for + the automount daemon. It must only return it when a mount has + been requested, but has not yet completed. + + `d_manage` also returns `-EISDIR` if the dentry shouldn't be a + mount trap, either because it is a symbolic link or because it is + not empty. + +- Any other negative value is treated as an error and returned + to the caller. + + autofs can return + + - -ENOENT if the automount daemon failed to mount anything, + - -ENOMEM if it ran out of memory, + - -EINTR if a signal arrived while waiting for expiry to + complete + - or any other error sent down by the automount daemon. + + +The second use case only occurs during an "RCU-walk" and so `rcu_walk` +will be set. + +An RCU-walk is a fast and lightweight process for walking down a +filename path (i.e. it is like running on tip-toes). RCU-walk cannot +cope with all situations so when it finds a difficulty it falls back +to "REF-walk", which is slower but more robust. + +RCU-walk will never call `->d_automount`; the filesystems must already +be mounted or RCU-walk cannot handle the path. +To determine if a mount-trap is safe for RCU-walk mode it calls +`->d_manage()` with `rcu_walk` set to `true`. + +In this case `d_manage()` must avoid blocking and should avoid taking +spinlocks if at all possible. Its sole purpose is to determine if it +would be safe to follow down into any mounted directory and the only +reason that it might not be is if an expiry of the mount is +underway. + +In the `rcu_walk` case, `d_manage()` cannot return -EISDIR to tell the +VFS that this is a directory that doesn't require d_automount. If +`rcu_walk` sees a dentry with DCACHE_NEED_AUTOMOUNT set but nothing +mounted, it *will* fall back to REF-walk. `d_manage()` cannot make the +VFS remain in RCU-walk mode, but can only tell it to get out of +RCU-walk mode by returning `-ECHILD`. + +So `d_manage()`, when called with `rcu_walk` set, should either return +-ECHILD if there is any reason to believe it is unsafe to enter the +mounted filesystem, otherwise it should return 0. + +autofs will return `-ECHILD` if an expiry of the filesystem has been +initiated or is being considered, otherwise it returns 0. + + +Mountpoint expiry +================= + +The VFS has a mechanism for automatically expiring unused mounts, +much as it can expire any unused dentry information from the dcache. +This is guided by the MNT_SHRINKABLE flag. This only applies to +mounts that were created by `d_automount()` returning a filesystem to be +mounted. As autofs doesn't return such a filesystem but leaves the +mounting to the automount daemon, it must involve the automount daemon +in unmounting as well. This also means that autofs has more control +over expiry. + +The VFS also supports "expiry" of mounts using the MNT_EXPIRE flag to +the `umount` system call. Unmounting with MNT_EXPIRE will fail unless +a previous attempt had been made, and the filesystem has been inactive +and untouched since that previous attempt. autofs does not depend on +this but has its own internal tracking of whether filesystems were +recently used. This allows individual names in the autofs directory +to expire separately. + +With version 4 of the protocol, the automount daemon can try to +unmount any filesystems mounted on the autofs filesystem or remove any +symbolic links or empty directories any time it likes. If the unmount +or removal is successful the filesystem will be returned to the state +it was before the mount or creation, so that any access of the name +will trigger normal auto-mount processing. In particular, `rmdir` and +`unlink` do not leave negative entries in the dcache as a normal +filesystem would, so an attempt to access a recently-removed object is +passed to autofs for handling. + +With version 5, this is not safe except for unmounting from top-level +directories. As lower-level directories are never mount traps, other +processes will see an empty directory as soon as the filesystem is +unmounted. So it is generally safest to use the autofs expiry +protocol described below. + +Normally the daemon only wants to remove entries which haven't been +used for a while. For this purpose autofs maintains a "`last_used`" +time stamp on each directory or symlink. For symlinks it genuinely +does record the last time the symlink was "used" or followed to find +out where it points to. For directories the field is used slightly +differently. The field is updated at mount time and during expire +checks if it is found to be in use (ie. open file descriptor or +process working directory) and during path walks. The update done +during path walks prevents frequent expire and immediate mount of +frequently accessed automounts. But in the case where a GUI continually +access or an application frequently scans an autofs directory tree +there can be an accumulation of mounts that aren't actually being +used. To cater for this case the "`strictexpire`" autofs mount option +can be used to avoid the "`last_used`" update on path walk thereby +preventing this apparent inability to expire mounts that aren't +really in use. + +The daemon is able to ask autofs if anything is due to be expired, +using an `ioctl` as discussed later. For a *direct* mount, autofs +considers if the entire mount-tree can be unmounted or not. For an +*indirect* mount, autofs considers each of the names in the top level +directory to determine if any of those can be unmounted and cleaned +up. + +There is an option with indirect mounts to consider each of the leaves +that has been mounted on instead of considering the top-level names. +This was originally intended for compatibility with version 4 of autofs +and should be considered as deprecated for Sun Format automount maps. +However, it may be used again for amd format mount maps (which are +generally indirect maps) because the amd automounter allows for the +setting of an expire timeout for individual mounts. But there are +some difficulties in making the needed changes for this. + +When autofs considers a directory it checks the `last_used` time and +compares it with the "timeout" value set when the filesystem was +mounted, though this check is ignored in some cases. It also checks if +the directory or anything below it is in use. For symbolic links, +only the `last_used` time is ever considered. + +If both appear to support expiring the directory or symlink, an action +is taken. + +There are two ways to ask autofs to consider expiry. The first is to +use the **AUTOFS_IOC_EXPIRE** ioctl. This only works for indirect +mounts. If it finds something in the root directory to expire it will +return the name of that thing. Once a name has been returned the +automount daemon needs to unmount any filesystems mounted below the +name normally. As described above, this is unsafe for non-toplevel +mounts in a version-5 autofs. For this reason the current `automount(8)` +does not use this ioctl. + +The second mechanism uses either the **AUTOFS_DEV_IOCTL_EXPIRE_CMD** or +the **AUTOFS_IOC_EXPIRE_MULTI** ioctl. This will work for both direct and +indirect mounts. If it selects an object to expire, it will notify +the daemon using the notification mechanism described below. This +will block until the daemon acknowledges the expiry notification. +This implies that the "`EXPIRE`" ioctl must be sent from a different +thread than the one which handles notification. + +While the ioctl is blocking, the entry is marked as "expiring" and +`d_manage` will block until the daemon affirms that the unmount has +completed (together with removing any directories that might have been +necessary), or has been aborted. + +Communicating with autofs: detecting the daemon +=============================================== + +There are several forms of communication between the automount daemon +and the filesystem. As we have already seen, the daemon can create and +remove directories and symlinks using normal filesystem operations. +autofs knows whether a process requesting some operation is the daemon +or not based on its process-group id number (see getpgid(1)). + +When an autofs filesystem is mounted the pgid of the mounting +processes is recorded unless the "pgrp=" option is given, in which +case that number is recorded instead. Any request arriving from a +process in that process group is considered to come from the daemon. +If the daemon ever has to be stopped and restarted a new pgid can be +provided through an ioctl as will be described below. + +Communicating with autofs: the event pipe +========================================= + +When an autofs filesystem is mounted, the 'write' end of a pipe must +be passed using the 'fd=' mount option. autofs will write +notification messages to this pipe for the daemon to respond to. +For version 5, the format of the message is:: + + struct autofs_v5_packet { + int proto_version; /* Protocol version */ + int type; /* Type of packet */ + autofs_wqt_t wait_queue_token; + __u32 dev; + __u64 ino; + __u32 uid; + __u32 gid; + __u32 pid; + __u32 tgid; + __u32 len; + char name[NAME_MAX+1]; + }; + +where the type is one of :: + + autofs_ptype_missing_indirect + autofs_ptype_expire_indirect + autofs_ptype_missing_direct + autofs_ptype_expire_direct + +so messages can indicate that a name is missing (something tried to +access it but it isn't there) or that it has been selected for expiry. + +The pipe will be set to "packet mode" (equivalent to passing +`O_DIRECT`) to _pipe2(2)_ so that a read from the pipe will return at +most one packet, and any unread portion of a packet will be discarded. + +The `wait_queue_token` is a unique number which can identify a +particular request to be acknowledged. When a message is sent over +the pipe the affected dentry is marked as either "active" or +"expiring" and other accesses to it block until the message is +acknowledged using one of the ioctls below with the relevant +`wait_queue_token`. + +Communicating with autofs: root directory ioctls +================================================ + +The root directory of an autofs filesystem will respond to a number of +ioctls. The process issuing the ioctl must have the CAP_SYS_ADMIN +capability, or must be the automount daemon. + +The available ioctl commands are: + +- **AUTOFS_IOC_READY**: + a notification has been handled. The argument + to the ioctl command is the "wait_queue_token" number + corresponding to the notification being acknowledged. +- **AUTOFS_IOC_FAIL**: + similar to above, but indicates failure with + the error code `ENOENT`. +- **AUTOFS_IOC_CATATONIC**: + Causes the autofs to enter "catatonic" + mode meaning that it stops sending notifications to the daemon. + This mode is also entered if a write to the pipe fails. +- **AUTOFS_IOC_PROTOVER**: + This returns the protocol version in use. +- **AUTOFS_IOC_PROTOSUBVER**: + Returns the protocol sub-version which + is really a version number for the implementation. +- **AUTOFS_IOC_SETTIMEOUT**: + This passes a pointer to an unsigned + long. The value is used to set the timeout for expiry, and + the current timeout value is stored back through the pointer. +- **AUTOFS_IOC_ASKUMOUNT**: + Returns, in the pointed-to `int`, 1 if + the filesystem could be unmounted. This is only a hint as + the situation could change at any instant. This call can be + used to avoid a more expensive full unmount attempt. +- **AUTOFS_IOC_EXPIRE**: + as described above, this asks if there is + anything suitable to expire. A pointer to a packet:: + + struct autofs_packet_expire_multi { + int proto_version; /* Protocol version */ + int type; /* Type of packet */ + autofs_wqt_t wait_queue_token; + int len; + char name[NAME_MAX+1]; + }; + + is required. This is filled in with the name of something + that can be unmounted or removed. If nothing can be expired, + `errno` is set to `EAGAIN`. Even though a `wait_queue_token` + is present in the structure, no "wait queue" is established + and no acknowledgment is needed. +- **AUTOFS_IOC_EXPIRE_MULTI**: + This is similar to + **AUTOFS_IOC_EXPIRE** except that it causes notification to be + sent to the daemon, and it blocks until the daemon acknowledges. + The argument is an integer which can contain two different flags. + + **AUTOFS_EXP_IMMEDIATE** causes `last_used` time to be ignored + and objects are expired if the are not in use. + + **AUTOFS_EXP_FORCED** causes the in use status to be ignored + and objects are expired ieven if they are in use. This assumes + that the daemon has requested this because it is capable of + performing the umount. + + **AUTOFS_EXP_LEAVES** will select a leaf rather than a top-level + name to expire. This is only safe when *maxproto* is 4. + +Communicating with autofs: char-device ioctls +============================================= + +It is not always possible to open the root of an autofs filesystem, +particularly a *direct* mounted filesystem. If the automount daemon +is restarted there is no way for it to regain control of existing +mounts using any of the above communication channels. To address this +need there is a "miscellaneous" character device (major 10, minor 235) +which can be used to communicate directly with the autofs filesystem. +It requires CAP_SYS_ADMIN for access. + +The 'ioctl's that can be used on this device are described in a separate +document `autofs-mount-control.txt`, and are summarised briefly here. +Each ioctl is passed a pointer to an `autofs_dev_ioctl` structure:: + + struct autofs_dev_ioctl { + __u32 ver_major; + __u32 ver_minor; + __u32 size; /* total size of data passed in + * including this struct */ + __s32 ioctlfd; /* automount command fd */ + + /* Command parameters */ + union { + struct args_protover protover; + struct args_protosubver protosubver; + struct args_openmount openmount; + struct args_ready ready; + struct args_fail fail; + struct args_setpipefd setpipefd; + struct args_timeout timeout; + struct args_requester requester; + struct args_expire expire; + struct args_askumount askumount; + struct args_ismountpoint ismountpoint; + }; + + char path[0]; + }; + +For the **OPEN_MOUNT** and **IS_MOUNTPOINT** commands, the target +filesystem is identified by the `path`. All other commands identify +the filesystem by the `ioctlfd` which is a file descriptor open on the +root, and which can be returned by **OPEN_MOUNT**. + +The `ver_major` and `ver_minor` are in/out parameters which check that +the requested version is supported, and report the maximum version +that the kernel module can support. + +Commands are: + +- **AUTOFS_DEV_IOCTL_VERSION_CMD**: + does nothing, except validate and + set version numbers. +- **AUTOFS_DEV_IOCTL_OPENMOUNT_CMD**: + return an open file descriptor + on the root of an autofs filesystem. The filesystem is identified + by name and device number, which is stored in `openmount.devid`. + Device numbers for existing filesystems can be found in + `/proc/self/mountinfo`. +- **AUTOFS_DEV_IOCTL_CLOSEMOUNT_CMD**: + same as `close(ioctlfd)`. +- **AUTOFS_DEV_IOCTL_SETPIPEFD_CMD**: + if the filesystem is in + catatonic mode, this can provide the write end of a new pipe + in `setpipefd.pipefd` to re-establish communication with a daemon. + The process group of the calling process is used to identify the + daemon. +- **AUTOFS_DEV_IOCTL_REQUESTER_CMD**: + `path` should be a + name within the filesystem that has been auto-mounted on. + On successful return, `requester.uid` and `requester.gid` will be + the UID and GID of the process which triggered that mount. +- **AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD**: + Check if path is a + mountpoint of a particular type - see separate documentation for + details. + +- **AUTOFS_DEV_IOCTL_PROTOVER_CMD** +- **AUTOFS_DEV_IOCTL_PROTOSUBVER_CMD** +- **AUTOFS_DEV_IOCTL_READY_CMD** +- **AUTOFS_DEV_IOCTL_FAIL_CMD** +- **AUTOFS_DEV_IOCTL_CATATONIC_CMD** +- **AUTOFS_DEV_IOCTL_TIMEOUT_CMD** +- **AUTOFS_DEV_IOCTL_EXPIRE_CMD** +- **AUTOFS_DEV_IOCTL_ASKUMOUNT_CMD** + +These all have the same +function as the similarly named **AUTOFS_IOC** ioctls, except +that **FAIL** can be given an explicit error number in `fail.status` +instead of assuming `ENOENT`, and this **EXPIRE** command +corresponds to **AUTOFS_IOC_EXPIRE_MULTI**. + +Catatonic mode +============== + +As mentioned, an autofs mount can enter "catatonic" mode. This +happens if a write to the notification pipe fails, or if it is +explicitly requested by an `ioctl`. + +When entering catatonic mode, the pipe is closed and any pending +notifications are acknowledged with the error `ENOENT`. + +Once in catatonic mode attempts to access non-existing names will +result in `ENOENT` while attempts to access existing directories will +be treated in the same way as if they came from the daemon, so mount +traps will not fire. + +When the filesystem is mounted a _uid_ and _gid_ can be given which +set the ownership of directories and symbolic links. When the +filesystem is in catatonic mode, any process with a matching UID can +create directories or symlinks in the root directory, but not in other +directories. + +Catatonic mode can only be left via the +**AUTOFS_DEV_IOCTL_OPENMOUNT_CMD** ioctl on the `/dev/autofs`. + +The "ignore" mount option +========================= + +The "ignore" mount option can be used to provide a generic indicator +to applications that the mount entry should be ignored when displaying +mount information. + +In other OSes that provide autofs and that provide a mount list to user +space based on the kernel mount list a no-op mount option ("ignore" is +the one use on the most common OSes) is allowed so that autofs file +system users can optionally use it. + +This is intended to be used by user space programs to exclude autofs +mounts from consideration when reading the mounts list. + +autofs, name spaces, and shared mounts +====================================== + +With bind mounts and name spaces it is possible for an autofs +filesystem to appear at multiple places in one or more filesystem +name spaces. For this to work sensibly, the autofs filesystem should +always be mounted "shared". e.g. :: + + mount --make-shared /autofs/mount/point + +The automount daemon is only able to manage a single mount location for +an autofs filesystem and if mounts on that are not 'shared', other +locations will not behave as expected. In particular access to those +other locations will likely result in the `ELOOP` error :: + + Too many levels of symbolic links diff --git a/Documentation/filesystems/autofs.txt b/Documentation/filesystems/autofs.txt deleted file mode 100644 index 3af38c7fd26d..000000000000 --- a/Documentation/filesystems/autofs.txt +++ /dev/null @@ -1,559 +0,0 @@ - - - - -autofs - how it works -===================== - -Purpose -------- - -The goal of autofs is to provide on-demand mounting and race free -automatic unmounting of various other filesystems. This provides two -key advantages: - -1. There is no need to delay boot until all filesystems that - might be needed are mounted. Processes that try to access those - slow filesystems might be delayed but other processes can - continue freely. This is particularly important for - network filesystems (e.g. NFS) or filesystems stored on - media with a media-changing robot. - -2. The names and locations of filesystems can be stored in - a remote database and can change at any time. The content - in that data base at the time of access will be used to provide - a target for the access. The interpretation of names in the - filesystem can even be programmatic rather than database-backed, - allowing wildcards for example, and can vary based on the user who - first accessed a name. - -Context -------- - -The "autofs" filesystem module is only one part of an autofs system. -There also needs to be a user-space program which looks up names -and mounts filesystems. This will often be the "automount" program, -though other tools including "systemd" can make use of "autofs". -This document describes only the kernel module and the interactions -required with any user-space program. Subsequent text refers to this -as the "automount daemon" or simply "the daemon". - -"autofs" is a Linux kernel module with provides the "autofs" -filesystem type. Several "autofs" filesystems can be mounted and they -can each be managed separately, or all managed by the same daemon. - -Content -------- - -An autofs filesystem can contain 3 sorts of objects: directories, -symbolic links and mount traps. Mount traps are directories with -extra properties as described in the next section. - -Objects can only be created by the automount daemon: symlinks are -created with a regular `symlink` system call, while directories and -mount traps are created with `mkdir`. The determination of whether a -directory should be a mount trap or not is quite _ad hoc_, largely for -historical reasons, and is determined in part by the -*direct*/*indirect*/*offset* mount options, and the *maxproto* mount option. - -If neither the *direct* or *offset* mount options are given (so the -mount is considered to be *indirect*), then the root directory is -always a regular directory, otherwise it is a mount trap when it is -empty and a regular directory when not empty. Note that *direct* and -*offset* are treated identically so a concise summary is that the root -directory is a mount trap only if the filesystem is mounted *direct* -and the root is empty. - -Directories created in the root directory are mount traps only if the -filesystem is mounted *indirect* and they are empty. - -Directories further down the tree depend on the *maxproto* mount -option and particularly whether it is less than five or not. -When *maxproto* is five, no directories further down the -tree are ever mount traps, they are always regular directories. When -the *maxproto* is four (or three), these directories are mount traps -precisely when they are empty. - -So: non-empty (i.e. non-leaf) directories are never mount traps. Empty -directories are sometimes mount traps, and sometimes not depending on -where in the tree they are (root, top level, or lower), the *maxproto*, -and whether the mount was *indirect* or not. - -Mount Traps ---------------- - -A core element of the implementation of autofs is the Mount Traps -which are provided by the Linux VFS. Any directory provided by a -filesystem can be designated as a trap. This involves two separate -features that work together to allow autofs to do its job. - -**DCACHE_NEED_AUTOMOUNT** - -If a dentry has the DCACHE_NEED_AUTOMOUNT flag set (which gets set if -the inode has S_AUTOMOUNT set, or can be set directly) then it is -(potentially) a mount trap. Any access to this directory beyond a -"`stat`" will (normally) cause the `d_op->d_automount()` dentry operation -to be called. The task of this method is to find the filesystem that -should be mounted on the directory and to return it. The VFS is -responsible for actually mounting the root of this filesystem on the -directory. - -autofs doesn't find the filesystem itself but sends a message to the -automount daemon asking it to find and mount the filesystem. The -autofs `d_automount` method then waits for the daemon to report that -everything is ready. It will then return "`NULL`" indicating that the -mount has already happened. The VFS doesn't try to mount anything but -follows down the mount that is already there. - -This functionality is sufficient for some users of mount traps such -as NFS which creates traps so that mountpoints on the server can be -reflected on the client. However it is not sufficient for autofs. As -mounting onto a directory is considered to be "beyond a `stat`", the -automount daemon would not be able to mount a filesystem on the 'trap' -directory without some way to avoid getting caught in the trap. For -that purpose there is another flag. - -**DCACHE_MANAGE_TRANSIT** - -If a dentry has DCACHE_MANAGE_TRANSIT set then two very different but -related behaviours are invoked, both using the `d_op->d_manage()` -dentry operation. - -Firstly, before checking to see if any filesystem is mounted on the -directory, d_manage() will be called with the `rcu_walk` parameter set -to `false`. It may return one of three things: - -- A return value of zero indicates that there is nothing special - about this dentry and normal checks for mounts and automounts - should proceed. - - autofs normally returns zero, but first waits for any - expiry (automatic unmounting of the mounted filesystem) to - complete. This avoids races. - -- A return value of `-EISDIR` tells the VFS to ignore any mounts - on the directory and to not consider calling `->d_automount()`. - This effectively disables the **DCACHE_NEED_AUTOMOUNT** flag - causing the directory not be a mount trap after all. - - autofs returns this if it detects that the process performing the - lookup is the automount daemon and that the mount has been - requested but has not yet completed. How it determines this is - discussed later. This allows the automount daemon not to get - caught in the mount trap. - - There is a subtlety here. It is possible that a second autofs - filesystem can be mounted below the first and for both of them to - be managed by the same daemon. For the daemon to be able to mount - something on the second it must be able to "walk" down past the - first. This means that d_manage cannot *always* return -EISDIR for - the automount daemon. It must only return it when a mount has - been requested, but has not yet completed. - - `d_manage` also returns `-EISDIR` if the dentry shouldn't be a - mount trap, either because it is a symbolic link or because it is - not empty. - -- Any other negative value is treated as an error and returned - to the caller. - - autofs can return - - - -ENOENT if the automount daemon failed to mount anything, - - -ENOMEM if it ran out of memory, - - -EINTR if a signal arrived while waiting for expiry to - complete - - or any other error sent down by the automount daemon. - - -The second use case only occurs during an "RCU-walk" and so `rcu_walk` -will be set. - -An RCU-walk is a fast and lightweight process for walking down a -filename path (i.e. it is like running on tip-toes). RCU-walk cannot -cope with all situations so when it finds a difficulty it falls back -to "REF-walk", which is slower but more robust. - -RCU-walk will never call `->d_automount`; the filesystems must already -be mounted or RCU-walk cannot handle the path. -To determine if a mount-trap is safe for RCU-walk mode it calls -`->d_manage()` with `rcu_walk` set to `true`. - -In this case `d_manage()` must avoid blocking and should avoid taking -spinlocks if at all possible. Its sole purpose is to determine if it -would be safe to follow down into any mounted directory and the only -reason that it might not be is if an expiry of the mount is -underway. - -In the `rcu_walk` case, `d_manage()` cannot return -EISDIR to tell the -VFS that this is a directory that doesn't require d_automount. If -`rcu_walk` sees a dentry with DCACHE_NEED_AUTOMOUNT set but nothing -mounted, it *will* fall back to REF-walk. `d_manage()` cannot make the -VFS remain in RCU-walk mode, but can only tell it to get out of -RCU-walk mode by returning `-ECHILD`. - -So `d_manage()`, when called with `rcu_walk` set, should either return --ECHILD if there is any reason to believe it is unsafe to enter the -mounted filesystem, otherwise it should return 0. - -autofs will return `-ECHILD` if an expiry of the filesystem has been -initiated or is being considered, otherwise it returns 0. - - -Mountpoint expiry ------------------ - -The VFS has a mechanism for automatically expiring unused mounts, -much as it can expire any unused dentry information from the dcache. -This is guided by the MNT_SHRINKABLE flag. This only applies to -mounts that were created by `d_automount()` returning a filesystem to be -mounted. As autofs doesn't return such a filesystem but leaves the -mounting to the automount daemon, it must involve the automount daemon -in unmounting as well. This also means that autofs has more control -over expiry. - -The VFS also supports "expiry" of mounts using the MNT_EXPIRE flag to -the `umount` system call. Unmounting with MNT_EXPIRE will fail unless -a previous attempt had been made, and the filesystem has been inactive -and untouched since that previous attempt. autofs does not depend on -this but has its own internal tracking of whether filesystems were -recently used. This allows individual names in the autofs directory -to expire separately. - -With version 4 of the protocol, the automount daemon can try to -unmount any filesystems mounted on the autofs filesystem or remove any -symbolic links or empty directories any time it likes. If the unmount -or removal is successful the filesystem will be returned to the state -it was before the mount or creation, so that any access of the name -will trigger normal auto-mount processing. In particular, `rmdir` and -`unlink` do not leave negative entries in the dcache as a normal -filesystem would, so an attempt to access a recently-removed object is -passed to autofs for handling. - -With version 5, this is not safe except for unmounting from top-level -directories. As lower-level directories are never mount traps, other -processes will see an empty directory as soon as the filesystem is -unmounted. So it is generally safest to use the autofs expiry -protocol described below. - -Normally the daemon only wants to remove entries which haven't been -used for a while. For this purpose autofs maintains a "`last_used`" -time stamp on each directory or symlink. For symlinks it genuinely -does record the last time the symlink was "used" or followed to find -out where it points to. For directories the field is used slightly -differently. The field is updated at mount time and during expire -checks if it is found to be in use (ie. open file descriptor or -process working directory) and during path walks. The update done -during path walks prevents frequent expire and immediate mount of -frequently accessed automounts. But in the case where a GUI continually -access or an application frequently scans an autofs directory tree -there can be an accumulation of mounts that aren't actually being -used. To cater for this case the "`strictexpire`" autofs mount option -can be used to avoid the "`last_used`" update on path walk thereby -preventing this apparent inability to expire mounts that aren't -really in use. - -The daemon is able to ask autofs if anything is due to be expired, -using an `ioctl` as discussed later. For a *direct* mount, autofs -considers if the entire mount-tree can be unmounted or not. For an -*indirect* mount, autofs considers each of the names in the top level -directory to determine if any of those can be unmounted and cleaned -up. - -There is an option with indirect mounts to consider each of the leaves -that has been mounted on instead of considering the top-level names. -This was originally intended for compatibility with version 4 of autofs -and should be considered as deprecated for Sun Format automount maps. -However, it may be used again for amd format mount maps (which are -generally indirect maps) because the amd automounter allows for the -setting of an expire timeout for individual mounts. But there are -some difficulties in making the needed changes for this. - -When autofs considers a directory it checks the `last_used` time and -compares it with the "timeout" value set when the filesystem was -mounted, though this check is ignored in some cases. It also checks if -the directory or anything below it is in use. For symbolic links, -only the `last_used` time is ever considered. - -If both appear to support expiring the directory or symlink, an action -is taken. - -There are two ways to ask autofs to consider expiry. The first is to -use the **AUTOFS_IOC_EXPIRE** ioctl. This only works for indirect -mounts. If it finds something in the root directory to expire it will -return the name of that thing. Once a name has been returned the -automount daemon needs to unmount any filesystems mounted below the -name normally. As described above, this is unsafe for non-toplevel -mounts in a version-5 autofs. For this reason the current `automount(8)` -does not use this ioctl. - -The second mechanism uses either the **AUTOFS_DEV_IOCTL_EXPIRE_CMD** or -the **AUTOFS_IOC_EXPIRE_MULTI** ioctl. This will work for both direct and -indirect mounts. If it selects an object to expire, it will notify -the daemon using the notification mechanism described below. This -will block until the daemon acknowledges the expiry notification. -This implies that the "`EXPIRE`" ioctl must be sent from a different -thread than the one which handles notification. - -While the ioctl is blocking, the entry is marked as "expiring" and -`d_manage` will block until the daemon affirms that the unmount has -completed (together with removing any directories that might have been -necessary), or has been aborted. - -Communicating with autofs: detecting the daemon ------------------------------------------------ - -There are several forms of communication between the automount daemon -and the filesystem. As we have already seen, the daemon can create and -remove directories and symlinks using normal filesystem operations. -autofs knows whether a process requesting some operation is the daemon -or not based on its process-group id number (see getpgid(1)). - -When an autofs filesystem is mounted the pgid of the mounting -processes is recorded unless the "pgrp=" option is given, in which -case that number is recorded instead. Any request arriving from a -process in that process group is considered to come from the daemon. -If the daemon ever has to be stopped and restarted a new pgid can be -provided through an ioctl as will be described below. - -Communicating with autofs: the event pipe ------------------------------------------ - -When an autofs filesystem is mounted, the 'write' end of a pipe must -be passed using the 'fd=' mount option. autofs will write -notification messages to this pipe for the daemon to respond to. -For version 5, the format of the message is: - - struct autofs_v5_packet { - int proto_version; /* Protocol version */ - int type; /* Type of packet */ - autofs_wqt_t wait_queue_token; - __u32 dev; - __u64 ino; - __u32 uid; - __u32 gid; - __u32 pid; - __u32 tgid; - __u32 len; - char name[NAME_MAX+1]; - }; - -where the type is one of - - autofs_ptype_missing_indirect - autofs_ptype_expire_indirect - autofs_ptype_missing_direct - autofs_ptype_expire_direct - -so messages can indicate that a name is missing (something tried to -access it but it isn't there) or that it has been selected for expiry. - -The pipe will be set to "packet mode" (equivalent to passing -`O_DIRECT`) to _pipe2(2)_ so that a read from the pipe will return at -most one packet, and any unread portion of a packet will be discarded. - -The `wait_queue_token` is a unique number which can identify a -particular request to be acknowledged. When a message is sent over -the pipe the affected dentry is marked as either "active" or -"expiring" and other accesses to it block until the message is -acknowledged using one of the ioctls below with the relevant -`wait_queue_token`. - -Communicating with autofs: root directory ioctls ------------------------------------------------- - -The root directory of an autofs filesystem will respond to a number of -ioctls. The process issuing the ioctl must have the CAP_SYS_ADMIN -capability, or must be the automount daemon. - -The available ioctl commands are: - -- **AUTOFS_IOC_READY**: a notification has been handled. The argument - to the ioctl command is the "wait_queue_token" number - corresponding to the notification being acknowledged. -- **AUTOFS_IOC_FAIL**: similar to above, but indicates failure with - the error code `ENOENT`. -- **AUTOFS_IOC_CATATONIC**: Causes the autofs to enter "catatonic" - mode meaning that it stops sending notifications to the daemon. - This mode is also entered if a write to the pipe fails. -- **AUTOFS_IOC_PROTOVER**: This returns the protocol version in use. -- **AUTOFS_IOC_PROTOSUBVER**: Returns the protocol sub-version which - is really a version number for the implementation. -- **AUTOFS_IOC_SETTIMEOUT**: This passes a pointer to an unsigned - long. The value is used to set the timeout for expiry, and - the current timeout value is stored back through the pointer. -- **AUTOFS_IOC_ASKUMOUNT**: Returns, in the pointed-to `int`, 1 if - the filesystem could be unmounted. This is only a hint as - the situation could change at any instant. This call can be - used to avoid a more expensive full unmount attempt. -- **AUTOFS_IOC_EXPIRE**: as described above, this asks if there is - anything suitable to expire. A pointer to a packet: - - struct autofs_packet_expire_multi { - int proto_version; /* Protocol version */ - int type; /* Type of packet */ - autofs_wqt_t wait_queue_token; - int len; - char name[NAME_MAX+1]; - }; - - is required. This is filled in with the name of something - that can be unmounted or removed. If nothing can be expired, - `errno` is set to `EAGAIN`. Even though a `wait_queue_token` - is present in the structure, no "wait queue" is established - and no acknowledgment is needed. -- **AUTOFS_IOC_EXPIRE_MULTI**: This is similar to - **AUTOFS_IOC_EXPIRE** except that it causes notification to be - sent to the daemon, and it blocks until the daemon acknowledges. - The argument is an integer which can contain two different flags. - - **AUTOFS_EXP_IMMEDIATE** causes `last_used` time to be ignored - and objects are expired if the are not in use. - - **AUTOFS_EXP_FORCED** causes the in use status to be ignored - and objects are expired ieven if they are in use. This assumes - that the daemon has requested this because it is capable of - performing the umount. - - **AUTOFS_EXP_LEAVES** will select a leaf rather than a top-level - name to expire. This is only safe when *maxproto* is 4. - -Communicating with autofs: char-device ioctls ---------------------------------------------- - -It is not always possible to open the root of an autofs filesystem, -particularly a *direct* mounted filesystem. If the automount daemon -is restarted there is no way for it to regain control of existing -mounts using any of the above communication channels. To address this -need there is a "miscellaneous" character device (major 10, minor 235) -which can be used to communicate directly with the autofs filesystem. -It requires CAP_SYS_ADMIN for access. - -The `ioctl`s that can be used on this device are described in a separate -document `autofs-mount-control.txt`, and are summarised briefly here. -Each ioctl is passed a pointer to an `autofs_dev_ioctl` structure: - - struct autofs_dev_ioctl { - __u32 ver_major; - __u32 ver_minor; - __u32 size; /* total size of data passed in - * including this struct */ - __s32 ioctlfd; /* automount command fd */ - - /* Command parameters */ - union { - struct args_protover protover; - struct args_protosubver protosubver; - struct args_openmount openmount; - struct args_ready ready; - struct args_fail fail; - struct args_setpipefd setpipefd; - struct args_timeout timeout; - struct args_requester requester; - struct args_expire expire; - struct args_askumount askumount; - struct args_ismountpoint ismountpoint; - }; - - char path[0]; - }; - -For the **OPEN_MOUNT** and **IS_MOUNTPOINT** commands, the target -filesystem is identified by the `path`. All other commands identify -the filesystem by the `ioctlfd` which is a file descriptor open on the -root, and which can be returned by **OPEN_MOUNT**. - -The `ver_major` and `ver_minor` are in/out parameters which check that -the requested version is supported, and report the maximum version -that the kernel module can support. - -Commands are: - -- **AUTOFS_DEV_IOCTL_VERSION_CMD**: does nothing, except validate and - set version numbers. -- **AUTOFS_DEV_IOCTL_OPENMOUNT_CMD**: return an open file descriptor - on the root of an autofs filesystem. The filesystem is identified - by name and device number, which is stored in `openmount.devid`. - Device numbers for existing filesystems can be found in - `/proc/self/mountinfo`. -- **AUTOFS_DEV_IOCTL_CLOSEMOUNT_CMD**: same as `close(ioctlfd)`. -- **AUTOFS_DEV_IOCTL_SETPIPEFD_CMD**: if the filesystem is in - catatonic mode, this can provide the write end of a new pipe - in `setpipefd.pipefd` to re-establish communication with a daemon. - The process group of the calling process is used to identify the - daemon. -- **AUTOFS_DEV_IOCTL_REQUESTER_CMD**: `path` should be a - name within the filesystem that has been auto-mounted on. - On successful return, `requester.uid` and `requester.gid` will be - the UID and GID of the process which triggered that mount. -- **AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD**: Check if path is a - mountpoint of a particular type - see separate documentation for - details. -- **AUTOFS_DEV_IOCTL_PROTOVER_CMD**: -- **AUTOFS_DEV_IOCTL_PROTOSUBVER_CMD**: -- **AUTOFS_DEV_IOCTL_READY_CMD**: -- **AUTOFS_DEV_IOCTL_FAIL_CMD**: -- **AUTOFS_DEV_IOCTL_CATATONIC_CMD**: -- **AUTOFS_DEV_IOCTL_TIMEOUT_CMD**: -- **AUTOFS_DEV_IOCTL_EXPIRE_CMD**: -- **AUTOFS_DEV_IOCTL_ASKUMOUNT_CMD**: These all have the same - function as the similarly named **AUTOFS_IOC** ioctls, except - that **FAIL** can be given an explicit error number in `fail.status` - instead of assuming `ENOENT`, and this **EXPIRE** command - corresponds to **AUTOFS_IOC_EXPIRE_MULTI**. - -Catatonic mode --------------- - -As mentioned, an autofs mount can enter "catatonic" mode. This -happens if a write to the notification pipe fails, or if it is -explicitly requested by an `ioctl`. - -When entering catatonic mode, the pipe is closed and any pending -notifications are acknowledged with the error `ENOENT`. - -Once in catatonic mode attempts to access non-existing names will -result in `ENOENT` while attempts to access existing directories will -be treated in the same way as if they came from the daemon, so mount -traps will not fire. - -When the filesystem is mounted a _uid_ and _gid_ can be given which -set the ownership of directories and symbolic links. When the -filesystem is in catatonic mode, any process with a matching UID can -create directories or symlinks in the root directory, but not in other -directories. - -Catatonic mode can only be left via the -**AUTOFS_DEV_IOCTL_OPENMOUNT_CMD** ioctl on the `/dev/autofs`. - -The "ignore" mount option -------------------------- - -The "ignore" mount option can be used to provide a generic indicator -to applications that the mount entry should be ignored when displaying -mount information. - -In other OSes that provide autofs and that provide a mount list to user -space based on the kernel mount list a no-op mount option ("ignore" is -the one use on the most common OSes) is allowed so that autofs file -system users can optionally use it. - -This is intended to be used by user space programs to exclude autofs -mounts from consideration when reading the mounts list. - -autofs, name spaces, and shared mounts --------------------------------------- - -With bind mounts and name spaces it is possible for an autofs -filesystem to appear at multiple places in one or more filesystem -name spaces. For this to work sensibly, the autofs filesystem should -always be mounted "shared". e.g. - -> `mount --make-shared /autofs/mount/point` - -The automount daemon is only able to manage a single mount location for -an autofs filesystem and if mounts on that are not 'shared', other -locations will not behave as expected. In particular access to those -other locations will likely result in the `ELOOP` error - -> Too many levels of symbolic links diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst index 2c3a9f761205..ad6315a48d14 100644 --- a/Documentation/filesystems/index.rst +++ b/Documentation/filesystems/index.rst @@ -46,4 +46,5 @@ Documentation for filesystem implementations. .. toctree:: :maxdepth: 2 + autofs virtiofs -- cgit From c11565e88790517647c675a91745478492310e79 Mon Sep 17 00:00:00 2001 From: Jaskaran Singh Date: Sun, 17 Nov 2019 22:54:35 +0530 Subject: docs: filesystems: Update code snippets in autofs.rst Some of the struct definitions now have an autofs packet header. Reflect these changes by adding a definition of this header and place it wherever suitable. Signed-off-by: Jaskaran Singh Signed-off-by: Jonathan Corbet --- Documentation/filesystems/autofs.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/Documentation/filesystems/autofs.rst b/Documentation/filesystems/autofs.rst index 6702a5f61f50..73a404070f0d 100644 --- a/Documentation/filesystems/autofs.rst +++ b/Documentation/filesystems/autofs.rst @@ -322,8 +322,7 @@ notification messages to this pipe for the daemon to respond to. For version 5, the format of the message is:: struct autofs_v5_packet { - int proto_version; /* Protocol version */ - int type; /* Type of packet */ + struct autofs_packet_hdr hdr; autofs_wqt_t wait_queue_token; __u32 dev; __u64 ino; @@ -335,6 +334,13 @@ For version 5, the format of the message is:: char name[NAME_MAX+1]; }; +And the format of the header is:: + + struct autofs_packet_hdr { + int proto_version; /* Protocol version */ + int type; /* Type of packet */ + }; + where the type is one of :: autofs_ptype_missing_indirect @@ -395,8 +401,7 @@ The available ioctl commands are: anything suitable to expire. A pointer to a packet:: struct autofs_packet_expire_multi { - int proto_version; /* Protocol version */ - int type; /* Type of packet */ + struct autofs_packet_hdr hdr; autofs_wqt_t wait_queue_token; int len; char name[NAME_MAX+1]; -- cgit From e8a9e30d721196951e1c82bae208296d066ac272 Mon Sep 17 00:00:00 2001 From: Jaskaran Singh Date: Sun, 17 Nov 2019 22:54:36 +0530 Subject: docs: filesystems: Add mount map description in Content The second paragraph of the content section does not properly describe how mount points are determined by autofs. Replace the lines detailing how the determination of these mount points is "ad hoc" by a short description of the mount map syntax used by autofs. Signed-off-by: Jaskaran Singh Signed-off-by: Jonathan Corbet --- Documentation/filesystems/autofs.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/Documentation/filesystems/autofs.rst b/Documentation/filesystems/autofs.rst index 73a404070f0d..681c6a492bc0 100644 --- a/Documentation/filesystems/autofs.rst +++ b/Documentation/filesystems/autofs.rst @@ -49,9 +49,10 @@ extra properties as described in the next section. Objects can only be created by the automount daemon: symlinks are created with a regular `symlink` system call, while directories and mount traps are created with `mkdir`. The determination of whether a -directory should be a mount trap or not is quite ad hoc, largely for -historical reasons, and is determined in part by the -*direct*/*indirect*/*offset* mount options, and the *maxproto* mount option. +directory should be a mount trap is based on a master map. This master +map is consulted by autofs to determine which directories are mount +points. Mount points can be *direct*/*indirect*/*offset*. +On most systems, the default master map is located at */etc/auto.master*. If neither the *direct* or *offset* mount options are given (so the mount is considered to be *indirect*), then the root directory is -- cgit From 5ca470a0c3886b80ec13c3a19e9aae4c2f469202 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 4 Oct 2019 10:39:55 -0600 Subject: docs: Add request_irq() documentation While checking the results of the :c:func: removal, I noticed that there was no documentation for request_irq(), and request_threaded_irq() was not mentioned at all. Add a kerneldoc comment for request_irq() and add request_threaded_irq() to the list of functions. Reviewed-by: Thomas Gleixner Signed-off-by: Jonathan Corbet --- Documentation/core-api/genericirq.rst | 2 ++ include/linux/interrupt.h | 13 +++++++++++++ 2 files changed, 15 insertions(+) diff --git a/Documentation/core-api/genericirq.rst b/Documentation/core-api/genericirq.rst index 2e6c99e3ce3b..8f06d885c310 100644 --- a/Documentation/core-api/genericirq.rst +++ b/Documentation/core-api/genericirq.rst @@ -127,6 +127,8 @@ The high-level Driver API consists of following functions: - request_irq() +- request_threaded_irq() + - free_irq() - disable_irq() diff --git a/include/linux/interrupt.h b/include/linux/interrupt.h index 89fc59dab57d..ba873ec7e09d 100644 --- a/include/linux/interrupt.h +++ b/include/linux/interrupt.h @@ -140,6 +140,19 @@ request_threaded_irq(unsigned int irq, irq_handler_t handler, irq_handler_t thread_fn, unsigned long flags, const char *name, void *dev); +/** + * request_irq - Add a handler for an interrupt line + * @irq: The interrupt line to allocate + * @handler: Function to be called when the IRQ occurs. + * Primary handler for threaded interrupts + * If NULL, the default primary handler is installed + * @flags: Handling flags + * @name: Name of the device generating this interrupt + * @dev: A cookie passed to the handler function + * + * This call allocates an interrupt and establishes a handler; see + * the documentation for request_threaded_irq() for details. + */ static inline int __must_check request_irq(unsigned int irq, irq_handler_t handler, unsigned long flags, const char *name, void *dev) -- cgit From 291084904eb0d0e9dd15d7204b62bf809ea800ea Mon Sep 17 00:00:00 2001 From: Linus Walleij Date: Mon, 18 Nov 2019 23:30:19 +0100 Subject: Documentation: Document how to get links with git am This adds Kees' clever apply hook to the kernel documentation so it can be easily references when needed. Cc: Kees Cook Link: https://lists.linuxfoundation.org/pipermail/ksummit-discuss/2019-July/006608.html Signed-off-by: Linus Walleij Link: https://lore.kernel.org/r/20191118223019.81708-1-linus.walleij@linaro.org Signed-off-by: Jonathan Corbet --- Documentation/maintainer/configure-git.rst | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/Documentation/maintainer/configure-git.rst b/Documentation/maintainer/configure-git.rst index 78bbbb0d2c84..80ae5030a590 100644 --- a/Documentation/maintainer/configure-git.rst +++ b/Documentation/maintainer/configure-git.rst @@ -32,3 +32,33 @@ You may also like to tell ``gpg`` which ``tty`` to use (add to your shell rc fil :: export GPG_TTY=$(tty) + + +Creating commit links to lore.kernel.org +---------------------------------------- + +The web site http://lore.kernel.org is meant as a grand archive of all mail +list traffic concerning or influencing the kernel development. Storing archives +of patches here is a recommended practice, and when a maintainer applies a +patch to a subsystem tree, it is a good idea to provide a Link: tag with a +reference back to the lore archive so that people that browse the commit +history can find related discussions and rationale behind a certain change. +The link tag will look like this: + + Link: https://lore.kernel.org/r/ + +This can be configured to happen automatically any time you issue ``git am`` +by adding the following hook into your git: + +.. code-block:: none + + $ git config am.messageid true + $ cat >.git/hooks/applypatch-msg <<'EOF' + #!/bin/sh + . git-sh-setup + perl -pi -e 's|^Message-Id:\s*]+)>?$|Link: https://lore.kernel.org/r/$1|g;' "$1" + test -x "$GIT_DIR/hooks/commit-msg" && + exec "$GIT_DIR/hooks/commit-msg" ${1+"$@"} + : + EOF + $ chmod a+x .git/hooks/applypatch-msg -- cgit From 83ededdb72ca125ddb9a6270b966ef0c26b5cf5a Mon Sep 17 00:00:00 2001 From: Leonard Crestez Date: Tue, 19 Nov 2019 18:38:56 +0200 Subject: docs: Add initial documentation for devfreq The devfreq subsystem has plenty of kernel-doc comments but they're not currently included in sphinx documentation. Add a minimal devfreq.rst file which mostly just includes kernel-doc comments from devfreq source. This also exposes a number of kernel-doc warnings on `make htmldocs` Signed-off-by: Leonard Crestez Link: https://lore.kernel.org/r/e32fa9de8a60060a6ee5fc42f163111034f9a550.1574181341.git.leonard.crestez@nxp.com Signed-off-by: Jonathan Corbet --- Documentation/driver-api/devfreq.rst | 30 ++++++++++++++++++++++++++++++ Documentation/driver-api/index.rst | 1 + 2 files changed, 31 insertions(+) create mode 100644 Documentation/driver-api/devfreq.rst diff --git a/Documentation/driver-api/devfreq.rst b/Documentation/driver-api/devfreq.rst new file mode 100644 index 000000000000..4a0bf87a3b13 --- /dev/null +++ b/Documentation/driver-api/devfreq.rst @@ -0,0 +1,30 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================== +Device Frequency Scaling +======================== + +Introduction +------------ + +This framework provides a standard kernel interface for Dynamic Voltage and +Frequency Switching on arbitrary devices. + +It exposes controls for adjusting frequency through sysfs files which are +similar to the cpufreq subsystem. + +Devices for which current usage can be measured can have their frequency +automatically adjusted by governors. + +API +--- + +Device drivers need to initialize a :c:type:`devfreq_profile` and call the +:c:func:`devfreq_add_device` function to create a :c:type:`devfreq` instance. + +.. kernel-doc:: include/linux/devfreq.h +.. kernel-doc:: include/linux/devfreq-event.h +.. kernel-doc:: drivers/devfreq/devfreq.c + :export: +.. kernel-doc:: drivers/devfreq/devfreq-event.c + :export: diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 46d6a165b5a5..e66ebf5bfc89 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -39,6 +39,7 @@ available subsections can be seen below. ipmb i3c/index interconnect + devfreq hsi edac scsi -- cgit From 2ece3e00ac9581e67d3b7316a6bf36d64fed61df Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Fri, 22 Nov 2019 00:41:19 +0100 Subject: docs/memory-barriers.txt/kokr: Rewrite "KERNEL I/O BARRIER EFFECTS" section Translate this commit to Korean: 4614bbdee357 ("docs/memory-barriers.txt: Rewrite "KERNEL I/O BARRIER EFFECTS" section") Signed-off-by: SeongJae Park Link: https://lore.kernel.org/r/20191121234125.28032-2-sj38.park@gmail.com Signed-off-by: Jonathan Corbet --- .../translations/ko_KR/memory-barriers.txt | 105 +++++++++++++-------- 1 file changed, 64 insertions(+), 41 deletions(-) diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt index 2774624ee843..a83e63cffe03 100644 --- a/Documentation/translations/ko_KR/memory-barriers.txt +++ b/Documentation/translations/ko_KR/memory-barriers.txt @@ -2560,68 +2560,91 @@ mmiowb() 가 명시적으로 사용될 필요가 있습니다. 커널 I/O 배리어의 효과 ====================== -I/O 메모리에 액세스할 때, 드라이버는 적절한 액세스 함수를 사용해야 합니다: +I/O 액세스를 통한 주변장치와의 통신은 아키텍쳐와 기기에 매우 종속적입니다. +따라서, 본질적으로 이식성이 없는 드라이버는 가능한 가장 적은 오버헤드로 +동기화를 하기 위해 각자의 타겟 시스템의 특정 동작에 의존할 겁니다. 다양한 +아키텍쳐와 버스 구현에 이식성을 가지려 하는 드라이버를 위해, 커널은 다양한 +정도의 순서 보장을 제공하는 일련의 액세스 함수를 제공합니다. - (*) inX(), outX(): + (*) readX(), writeX(): - 이것들은 메모리 공간보다는 I/O 공간에 이야기를 하려는 의도로 - 만들어졌습니다만, 그건 기본적으로 CPU 마다 다른 컨셉입니다. i386 과 - x86_64 프로세서들은 특별한 I/O 공간 액세스 사이클과 명령어를 실제로 가지고 - 있지만, 다른 많은 CPU 들에는 그런 컨셉이 존재하지 않습니다. + readX() 와 writeX() MMIO 액세스 함수는 접근되는 주변장치로의 포인터를 + __iomem * 패러미터로 받습니다. 디폴트 I/O 기능으로 매핑되는 포인터 (예: + ioremap() 으로 반환되는 것) 의 순서 보장은 다음과 같습니다: - 다른 것들 중에서도 PCI 버스가 I/O 공간 컨셉을 정의하는데, 이는 - i386 과 - x86_64 같은 CPU 에서 - CPU 의 I/O 공간 컨셉으로 쉽게 매치됩니다. 하지만, - 대체할 I/O 공간이 없는 CPU 에서는 CPU 의 메모리 맵의 가상 I/O 공간으로 - 매핑될 수도 있습니다. + 1. 같은 주변장치로의 모든 readX() 와 writeX() 액세스는 각자에 대해 + 순서지어집니다. 예를 들어, CPU 의 특정 디바이스로의 MMIO 레지스터 + 쓰기는 프로그램 순서대로 도착할 것이 보장됩니다. - 이 공간으로의 액세스는 (i386 등에서는) 완전하게 동기화 됩니다만, 중간의 - (PCI 호스트 브리지와 같은) 브리지들은 이를 완전히 보장하진 않을수도 - 있습니다. + 2. CPU 에 의한 특정 주변장치로의 writeX() 는 모든 앞선 CPU 의 메모리 + 쓰기가 완료되기를 먼저 기다립니다. 예를 들어, dma_alloc_coherent() 를 + 통해 할당된 전송용 DMA 버퍼로의 CPU 의 쓰기는 이 전송을 시작시키기 위해 + CPU 가 MMIO 컨트롤 레지스터에 쓰기를 할 때 DMA 엔진에 보일 것이 + 보장됩니다. - 이것들의 상호간의 순서는 완전하게 보장됩니다. + 3. CPU 에 의한 주변장치로의 readX() 는 모든 뒤따르는 CPU 의 메모리 + 읽기가 시작되기 전에 완료됩니다. 예를 들어, dma_alloc_coherent() 를 + 통해 할당된 수신용 DMA 버퍼로부터의 CPU 의 읽기는 이 DMA 수신의 완료를 + 표시하는 DMA 엔진의 MMIO 상태 레지스터 읽기 후에는 오염된 데이터를 읽지 + 않을 것이 보장됩니다. - 다른 타입의 메모리 오퍼레이션, I/O 오퍼레이션에 대한 순서는 완전하게 - 보장되지는 않습니다. + 4. CPU 에 의한 주변장치로의 readX() 는 모든 뒤따르는 delay() 루프가 수행을 + 시작하기 전에 완료됩니다. 예를 들어, CPU 의 특정 주변장치로의 두개의 + MMIO 레지스터 쓰기가 행해지는데 첫번째 쓰기가 readX() 를 통해 곧바로 + 읽어졌고 이어 두번째 writeX() 전에 udelay(1) 이 호출되었다면 이 두개의 + 쓰기는 최소 1us 의 간격을 두고 행해질 것이 보장됩니다. - (*) readX(), writeX(): + 디폴트가 아닌 기능을 통해 얻어지는 __iomem 포인터 (예: ioremap_wc() 를 + 통해 리턴되는 것) 는 이런 보장사항들 중 다수를 제공하지 않을 수 있습니다. + + (*) readX_relaxed(), writeX_relaxed() + + 이것들은 readX() 와 writeX() 랑 비슷하지만, 더 완화된 메모리 순서 보장을 + 제공합니다. 구체적으로, 이것들은 일반적 메모리 액세스나 delay() 루프 + (예:앞의 2-4 항목) 에 대해 순서를 보장하지 않습니다만 디폴트 I/O 기능으로 + 매핑된 __iomem 포인터에 대해 동작할 때 같은 주변장치로의 액세스에는 순서가 + 맞춰질 것이 보장됩니다. - 이것들이 수행 요청되는 CPU 에서 서로에게 완전히 순서가 맞춰지고 독립적으로 - 수행되는지에 대한 보장 여부는 이들이 액세스 하는 메모리 윈도우에 정의된 - 특성에 의해 결정됩니다. 예를 들어, 최신의 i386 아키텍쳐 머신에서는 MTRR - 레지스터로 이 특성이 조정됩니다. + (*) readsX(), writesX(): - 일반적으로는, 프리페치 (prefetch) 가능한 디바이스를 액세스 하는게 - 아니라면, 이것들은 완전히 순서가 맞춰지고 결합되지 않게 보장될 겁니다. + readsX() 와 writesX() MMIO 액세스 함수는 DMA 를 수행하는데 적절치 않은, + 주변장치 내의 메모리 매핑된 레지스터 기반 FIFO 로의 액세스를 위해 + 설계되었습니다. 따라서, 이 기능들은 앞서 설명된 readX_relaxed() 와 + writeX_relaxed() 의 순서 보장만을 제공합니다. - 하지만, (PCI 브리지와 같은) 중간의 하드웨어는 자신이 원한다면 집행을 - 연기시킬 수 있습니다; 스토어 명령을 실제로 하드웨어로 내려보내기(flush) - 위해서는 같은 위치로부터 로드를 하는 방법이 있습니다만[*], PCI 의 경우는 - 같은 디바이스나 환경 구성 영역에서의 로드만으로도 충분할 겁니다. + (*) inX(), outX(): - [*] 주의! 쓰여진 것과 같은 위치로부터의 로드를 시도하는 것은 오동작을 - 일으킬 수도 있습니다 - 예로 16650 Rx/Tx 시리얼 레지스터를 생각해 - 보세요. + inX() 와 outX() 액세스 함수는 일부 아키텍쳐 (특히 x86) 에서는 특수한 + 명령어를 필요로 하며 포트에 매핑되는, 과거의 유산인 I/O 주변장치로의 + 접근을 위해 만들어졌습니다. - 프리페치 가능한 I/O 메모리가 사용되면, 스토어 명령들이 순서를 지키도록 - 하기 위해 mmiowb() 배리어가 필요할 수 있습니다. + 많은 CPU 아키텍쳐가 결국은 이런 주변장치를 내부의 가상 메모리 매핑을 통해 + 접근하기 때문에, inX() 와 outX() 가 제공하는 이식성 있는 순서 보장은 + 디폴트 I/O 기능을 통한 매핑을 접근할 때의 readX() 와 writeX() 에 의해 + 제공되는 것과 각각 동일합니다. - PCI 트랜잭션 사이의 상호작용에 대해 더 많은 정보를 위해선 PCI 명세서를 - 참고하시기 바랍니다. + 디바이스 드라이버는 outX() 가 리턴하기 전에 해당 I/O 주변장치로부터의 완료 + 응답을 기다리는 쓰기 트랜잭션을 만들어 낸다고 기대할 수도 있습니다. 이는 + 모든 아키텍쳐에서 보장되지는 않고, 따라서 이식성 있는 순서 규칙의 일부분이 + 아닙니다. - (*) readX_relaxed(), writeX_relaxed() + (*) insX(), outsX(): - 이것들은 readX() 와 writeX() 랑 비슷하지만, 더 완화된 메모리 순서 보장을 - 제공합니다. 구체적으로, 이것들은 일반적 메모리 액세스 (예: DMA 버퍼) 에도 - LOCK 이나 UNLOCK 오퍼레이션들에도 순서를 보장하지 않습니다. LOCK 이나 - UNLOCK 오퍼레이션들에 맞춰지는 순서가 필요하다면, mmiowb() 배리어가 사용될 - 수 있습니다. 같은 주변 장치에의 완화된 액세스끼리는 순서가 지켜짐을 알아 - 두시기 바랍니다. + 앞에서와 같이, insX() 와 outsX() 액세스 함수는 디폴트 I/O 기능을 통한 + 매핑을 접근할 때 각각 readX() 와 writeX() 와 같은 순서 보장을 제공합니다. (*) ioreadX(), iowriteX() 이것들은 inX()/outX() 나 readX()/writeX() 처럼 실제로 수행하는 액세스의 종류에 따라 적절하게 수행될 것입니다. +이 모든 액세스 함수들은 아랫단의 주변장치가 little-endian 이라 가정하며, 따라서 +big-endian 아키텍쳐에서는 byte-swapping 오퍼레이션을 수행합니다. + +I/O 순서 배리어를 SMP 순서 배리어와 LOCK/UNLOCK 오퍼레이션과 섞는 건 mmiowb() +를 필요로 할 수도 있는 위험한 행위입니다. 더 많은 내용을 위해선 "Acquire vs +I/O 액세스" 서브섹션을 참고하시기 바랍니다. + =================================== 가정되는 가장 완화된 실행 순서 모델 -- cgit From bf3b965bc45c87c0bb49d834d1bfff263e522d59 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Fri, 22 Nov 2019 00:41:20 +0100 Subject: Documentation/kokr: Kill all references to mmiowb() Translate this commit to Korean: 915530396c78 ("Documentation: Kill all references to mmiowb()") Signed-off-by: SeongJae Park Link: https://lore.kernel.org/r/20191121234125.28032-3-sj38.park@gmail.com Signed-off-by: Jonathan Corbet --- .../translations/ko_KR/memory-barriers.txt | 104 ++------------------- 1 file changed, 6 insertions(+), 98 deletions(-) diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt index a83e63cffe03..aeb0e58ec7ce 100644 --- a/Documentation/translations/ko_KR/memory-barriers.txt +++ b/Documentation/translations/ko_KR/memory-barriers.txt @@ -1907,21 +1907,6 @@ Mandatory 배리어들은 SMP 시스템에서도 UP 시스템에서도 SMP 효 위해선 Documentation/DMA-API.txt 문서를 참고하세요. -MMIO 쓰기 배리어 ----------------- - -리눅스 커널은 또한 memory-mapped I/O 쓰기를 위한 특별한 배리어도 가지고 -있습니다: - - mmiowb(); - -이것은 mandatory 쓰기 배리어의 변종으로, 완화된 순서 규칙의 I/O 영역에으로의 -쓰기가 부분적으로 순서를 맞추도록 해줍니다. 이 함수는 CPU->하드웨어 사이를 -넘어서 실제 하드웨어에까지 일부 수준의 영향을 끼칩니다. - -더 많은 정보를 위해선 "Acquire vs I/O 액세스" 서브섹션을 참고하세요. - - ========================= 암묵적 커널 메모리 배리어 ========================= @@ -2283,73 +2268,6 @@ ACQUIRE VS 메모리 액세스 *E, *F or *G following RELEASE Q - -ACQUIRE VS I/O 액세스 ----------------------- - -특정한 (특히 NUMA 가 관련된) 환경 하에서 두개의 CPU 에서 동일한 스핀락으로 -보호되는 두개의 크리티컬 섹션 안의 I/O 액세스는 PCI 브릿지에 겹쳐진 I/O -액세스로 보일 수 있는데, PCI 브릿지는 캐시 일관성 프로토콜과 합을 맞춰야 할 -의무가 없으므로, 필요한 읽기 메모리 배리어가 요청되지 않기 때문입니다. - -예를 들어서: - - CPU 1 CPU 2 - =============================== =============================== - spin_lock(Q) - writel(0, ADDR) - writel(1, DATA); - spin_unlock(Q); - spin_lock(Q); - writel(4, ADDR); - writel(5, DATA); - spin_unlock(Q); - -는 PCI 브릿지에 다음과 같이 보일 수 있습니다: - - STORE *ADDR = 0, STORE *ADDR = 4, STORE *DATA = 1, STORE *DATA = 5 - -이렇게 되면 하드웨어의 오동작을 일으킬 수 있습니다. - - -이런 경우엔 잡아둔 스핀락을 내려놓기 전에 mmiowb() 를 수행해야 하는데, 예를 -들면 다음과 같습니다: - - CPU 1 CPU 2 - =============================== =============================== - spin_lock(Q) - writel(0, ADDR) - writel(1, DATA); - mmiowb(); - spin_unlock(Q); - spin_lock(Q); - writel(4, ADDR); - writel(5, DATA); - mmiowb(); - spin_unlock(Q); - -이 코드는 CPU 1 에서 요청된 두개의 스토어가 PCI 브릿지에 CPU 2 에서 요청된 -스토어들보다 먼저 보여짐을 보장합니다. - - -또한, 같은 디바이스에서 스토어를 이어 로드가 수행되면 이 로드는 로드가 수행되기 -전에 스토어가 완료되기를 강제하므로 mmiowb() 의 필요가 없어집니다: - - CPU 1 CPU 2 - =============================== =============================== - spin_lock(Q) - writel(0, ADDR) - a = readl(DATA); - spin_unlock(Q); - spin_lock(Q); - writel(4, ADDR); - b = readl(DATA); - spin_unlock(Q); - - -더 많은 정보를 위해선 Documentation/driver-api/device-io.rst 를 참고하세요. - - ========================= 메모리 배리어가 필요한 곳 ========================= @@ -2494,14 +2412,9 @@ _않습니다_. 리눅스 커널 내부에서, I/O 는 어떻게 액세스들을 적절히 순차적이게 만들 수 있는지 알고 있는, - inb() 나 writel() 과 같은 - 적절한 액세스 루틴을 통해 이루어져야만 합니다. 이것들은 대부분의 경우에는 명시적 메모리 배리어 와 함께 사용될 필요가 -없습니다만, 다음의 두가지 상황에서는 명시적 메모리 배리어가 필요할 수 있습니다: - - (1) 일부 시스템에서 I/O 스토어는 모든 CPU 에 일관되게 순서 맞춰지지 않는데, - 따라서 _모든_ 일반적인 드라이버들에 락이 사용되어야만 하고 이 크리티컬 - 섹션을 빠져나오기 전에 mmiowb() 가 꼭 호출되어야 합니다. - - (2) 만약 액세스 함수들이 완화된 메모리 액세스 속성을 갖는 I/O 메모리 윈도우를 - 사용한다면, 순서를 강제하기 위해선 _mandatory_ 메모리 배리어가 필요합니다. +없습니다만, 완화된 메모리 액세스 속성으로 I/O 메모리 윈도우로의 참조를 위해 +액세스 함수가 사용된다면 순서를 강제하기 위해 _madatory_ 메모리 배리어가 +필요합니다. 더 많은 정보를 위해선 Documentation/driver-api/device-io.rst 를 참고하십시오. @@ -2545,10 +2458,9 @@ _않습니다_. 인터럽트 내에서 일어난 액세스와 섞일 수 있다고 - 그리고 그 반대도 - 가정해야만 합니다. -그런 영역 안에서 일어나는 I/O 액세스들은 엄격한 순서 규칙의 I/O 레지스터에 -묵시적 I/O 배리어를 형성하는 동기적 (synchronous) 로드 오퍼레이션을 포함하기 -때문에 일반적으로는 이런게 문제가 되지 않습니다. 만약 이걸로는 충분치 않다면 -mmiowb() 가 명시적으로 사용될 필요가 있습니다. +그런 영역 안에서 일어나는 I/O 액세스는 묵시적 I/O 배리어를 형성하는, 엄격한 +순서 규칙의 I/O 레지스터로의 로드 오퍼레이션을 포함하기 때문에 일반적으로는 +문제가 되지 않습니다. 하나의 인터럽트 루틴과 별도의 CPU 에서 수행중이며 서로 통신을 하는 두 루틴 @@ -2641,10 +2553,6 @@ I/O 액세스를 통한 주변장치와의 통신은 아키텍쳐와 기기에 이 모든 액세스 함수들은 아랫단의 주변장치가 little-endian 이라 가정하며, 따라서 big-endian 아키텍쳐에서는 byte-swapping 오퍼레이션을 수행합니다. -I/O 순서 배리어를 SMP 순서 배리어와 LOCK/UNLOCK 오퍼레이션과 섞는 건 mmiowb() -를 필요로 할 수도 있는 위험한 행위입니다. 더 많은 내용을 위해선 "Acquire vs -I/O 액세스" 서브섹션을 참고하시기 바랍니다. - =================================== 가정되는 가장 완화된 실행 순서 모델 -- cgit From 18b68475c5ef2a7bde2e151729f0c10c17e05fa6 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Fri, 22 Nov 2019 00:41:21 +0100 Subject: docs/memory-barriers.txt/kokr: Fix style, spacing and grammar in I/O section Translate this commit to Korean: 0cde62a46e88 ("docs/memory-barriers.txt: Fix style, spacing and grammar in I/O section") Signed-off-by: SeongJae Park Link: https://lore.kernel.org/r/20191121234125.28032-4-sj38.park@gmail.com Signed-off-by: Jonathan Corbet --- .../translations/ko_KR/memory-barriers.txt | 112 +++++++++++---------- 1 file changed, 60 insertions(+), 52 deletions(-) diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt index aeb0e58ec7ce..6ae6d24ba60e 100644 --- a/Documentation/translations/ko_KR/memory-barriers.txt +++ b/Documentation/translations/ko_KR/memory-barriers.txt @@ -2480,75 +2480,83 @@ I/O 액세스를 통한 주변장치와의 통신은 아키텍쳐와 기기에 (*) readX(), writeX(): - readX() 와 writeX() MMIO 액세스 함수는 접근되는 주변장치로의 포인터를 - __iomem * 패러미터로 받습니다. 디폴트 I/O 기능으로 매핑되는 포인터 (예: - ioremap() 으로 반환되는 것) 의 순서 보장은 다음과 같습니다: - - 1. 같은 주변장치로의 모든 readX() 와 writeX() 액세스는 각자에 대해 - 순서지어집니다. 예를 들어, CPU 의 특정 디바이스로의 MMIO 레지스터 - 쓰기는 프로그램 순서대로 도착할 것이 보장됩니다. - - 2. CPU 에 의한 특정 주변장치로의 writeX() 는 모든 앞선 CPU 의 메모리 - 쓰기가 완료되기를 먼저 기다립니다. 예를 들어, dma_alloc_coherent() 를 - 통해 할당된 전송용 DMA 버퍼로의 CPU 의 쓰기는 이 전송을 시작시키기 위해 - CPU 가 MMIO 컨트롤 레지스터에 쓰기를 할 때 DMA 엔진에 보일 것이 - 보장됩니다. - - 3. CPU 에 의한 주변장치로의 readX() 는 모든 뒤따르는 CPU 의 메모리 - 읽기가 시작되기 전에 완료됩니다. 예를 들어, dma_alloc_coherent() 를 - 통해 할당된 수신용 DMA 버퍼로부터의 CPU 의 읽기는 이 DMA 수신의 완료를 - 표시하는 DMA 엔진의 MMIO 상태 레지스터 읽기 후에는 오염된 데이터를 읽지 - 않을 것이 보장됩니다. - - 4. CPU 에 의한 주변장치로의 readX() 는 모든 뒤따르는 delay() 루프가 수행을 - 시작하기 전에 완료됩니다. 예를 들어, CPU 의 특정 주변장치로의 두개의 - MMIO 레지스터 쓰기가 행해지는데 첫번째 쓰기가 readX() 를 통해 곧바로 - 읽어졌고 이어 두번째 writeX() 전에 udelay(1) 이 호출되었다면 이 두개의 - 쓰기는 최소 1us 의 간격을 두고 행해질 것이 보장됩니다. - - 디폴트가 아닌 기능을 통해 얻어지는 __iomem 포인터 (예: ioremap_wc() 를 - 통해 리턴되는 것) 는 이런 보장사항들 중 다수를 제공하지 않을 수 있습니다. + readX() 와 writeX() MMIO 액세스 함수는 접근되는 주변장치로의 포인터를 + __iomem * 패러미터로 받습니다. 디폴트 I/O 기능으로 매핑되는 포인터 + (예: ioremap() 으로 반환되는 것) 의 순서 보장은 다음과 같습니다: + + 1. 같은 주변장치로의 모든 readX() 와 writeX() 액세스는 각자에 대해 + 순서지어집니다. 예를 들어, CPU 의 특정 디바이스로의 MMIO 레지스터 + 쓰기는 프로그램 순서대로 도착할 것이 보장됩니다. + + 2. CPU 에 의한 특정 주변장치로의 writeX() 는 모든 앞선 CPU 의 메모리 + 쓰기가 완료되기를 먼저 기다립니다. 예를 들어, dma_alloc_coherent() + 를 통해 할당된 전송용 DMA 버퍼로의 CPU 의 쓰기는 이 전송을 + 시작시키기 위해 CPU 가 MMIO 컨트롤 레지스터에 쓰기를 할 때 DMA + 엔진에 보일 것이 보장됩니다. + + 3. CPU 에 의한 주변장치로의 readX() 는 모든 뒤따르는 CPU 의 메모리 + 읽기가 시작되기 전에 완료됩니다. 예를 들어, dma_alloc_coherent() 를 + 통해 할당된 수신용 DMA 버퍼로부터의 CPU 의 읽기는 이 DMA 수신의 + 완료를 표시하는 DMA 엔진의 MMIO 상태 레지스터 읽기 후에는 오염된 + 데이터를 읽지 않을 것이 보장됩니다. + + 4. CPU 에 의한 주변장치로의 readX() 는 모든 뒤따르는 delay() 루프가 + 수행을 시작하기 전에 완료됩니다. 예를 들어, CPU 의 특정 + 주변장치로의 두개의 MMIO 레지스터 쓰기가 행해지는데 첫번째 쓰기가 + readX() 를 통해 곧바로 읽어졌고 이어 두번째 writeX() 전에 udelay(1) + 이 호출되었다면 이 두개의 쓰기는 최소 1us 의 간격을 두고 행해질 것이 + 보장됩니다: + + writel(42, DEVICE_REGISTER_0); // 디바이스에 도착함... + readl(DEVICE_REGISTER_0); + udelay(1); + writel(42, DEVICE_REGISTER_1); // ...이것보다 최소 1us 전에. + + 디폴트가 아닌 기능을 통해 얻어지는 __iomem 포인터 (예: ioremap_wc() 를 + 통해 리턴되는 것) 의 순서 속성은 실제 아키텍쳐에 의존적이어서 이런 + 종류의 매핑으로의 액세스는 앞서 설명된 보장사항에 의존할 수 없습니다. (*) readX_relaxed(), writeX_relaxed() - 이것들은 readX() 와 writeX() 랑 비슷하지만, 더 완화된 메모리 순서 보장을 - 제공합니다. 구체적으로, 이것들은 일반적 메모리 액세스나 delay() 루프 - (예:앞의 2-4 항목) 에 대해 순서를 보장하지 않습니다만 디폴트 I/O 기능으로 - 매핑된 __iomem 포인터에 대해 동작할 때 같은 주변장치로의 액세스에는 순서가 - 맞춰질 것이 보장됩니다. + 이것들은 readX() 와 writeX() 랑 비슷하지만, 더 완화된 메모리 순서 + 보장을 제공합니다. 구체적으로, 이것들은 일반적 메모리 액세스나 delay() + 루프 (예:앞의 2-4 항목) 에 대해 순서를 보장하지 않습니다만 디폴트 I/O + 기능으로 매핑된 __iomem 포인터에 대해 동작할 때 같은 주변장치로의 + 액세스에는 순서가 맞춰질 것이 보장됩니다. (*) readsX(), writesX(): - readsX() 와 writesX() MMIO 액세스 함수는 DMA 를 수행하는데 적절치 않은, - 주변장치 내의 메모리 매핑된 레지스터 기반 FIFO 로의 액세스를 위해 - 설계되었습니다. 따라서, 이 기능들은 앞서 설명된 readX_relaxed() 와 - writeX_relaxed() 의 순서 보장만을 제공합니다. + readsX() 와 writesX() MMIO 액세스 함수는 DMA 를 수행하는데 적절치 않은, + 주변장치 내의 메모리 매핑된 레지스터 기반 FIFO 로의 액세스를 위해 + 설계되었습니다. 따라서, 이 기능들은 앞서 설명된 readX_relaxed() 와 + writeX_relaxed() 의 순서 보장만을 제공합니다. (*) inX(), outX(): - inX() 와 outX() 액세스 함수는 일부 아키텍쳐 (특히 x86) 에서는 특수한 - 명령어를 필요로 하며 포트에 매핑되는, 과거의 유산인 I/O 주변장치로의 - 접근을 위해 만들어졌습니다. + inX() 와 outX() 액세스 함수는 일부 아키텍쳐 (특히 x86) 에서는 특수한 + 명령어를 필요로 하며 포트에 매핑되는, 과거의 유산인 I/O 주변장치로의 + 접근을 위해 만들어졌습니다. - 많은 CPU 아키텍쳐가 결국은 이런 주변장치를 내부의 가상 메모리 매핑을 통해 - 접근하기 때문에, inX() 와 outX() 가 제공하는 이식성 있는 순서 보장은 - 디폴트 I/O 기능을 통한 매핑을 접근할 때의 readX() 와 writeX() 에 의해 - 제공되는 것과 각각 동일합니다. + 많은 CPU 아키텍쳐가 결국은 이런 주변장치를 내부의 가상 메모리 매핑을 + 통해 접근하기 때문에, inX() 와 outX() 가 제공하는 이식성 있는 순서 + 보장은 디폴트 I/O 기능을 통한 매핑을 접근할 때의 readX() 와 writeX() 에 + 의해 제공되는 것과 각각 동일합니다. - 디바이스 드라이버는 outX() 가 리턴하기 전에 해당 I/O 주변장치로부터의 완료 - 응답을 기다리는 쓰기 트랜잭션을 만들어 낸다고 기대할 수도 있습니다. 이는 - 모든 아키텍쳐에서 보장되지는 않고, 따라서 이식성 있는 순서 규칙의 일부분이 - 아닙니다. + 디바이스 드라이버는 outX() 가 리턴하기 전에 해당 I/O 주변장치로부터의 + 완료 응답을 기다리는 쓰기 트랜잭션을 만들어 낸다고 기대할 수도 + 있습니다. 이는 모든 아키텍쳐에서 보장되지는 않고, 따라서 이식성 있는 + 순서 규칙의 일부분이 아닙니다. (*) insX(), outsX(): - 앞에서와 같이, insX() 와 outsX() 액세스 함수는 디폴트 I/O 기능을 통한 - 매핑을 접근할 때 각각 readX() 와 writeX() 와 같은 순서 보장을 제공합니다. + 앞에서와 같이, insX() 와 outsX() 액세스 함수는 디폴트 I/O 기능을 통한 + 매핑을 접근할 때 각각 readX() 와 writeX() 와 같은 순서 보장을 + 제공합니다. (*) ioreadX(), iowriteX() - 이것들은 inX()/outX() 나 readX()/writeX() 처럼 실제로 수행하는 액세스의 - 종류에 따라 적절하게 수행될 것입니다. + 이것들은 inX()/outX() 나 readX()/writeX() 처럼 실제로 수행하는 액세스의 + 종류에 따라 적절하게 수행될 것입니다. 이 모든 액세스 함수들은 아랫단의 주변장치가 little-endian 이라 가정하며, 따라서 big-endian 아키텍쳐에서는 byte-swapping 오퍼레이션을 수행합니다. -- cgit From 3ef2f6aca51d305251fa90ff3bf9738f5af7f63e Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Fri, 22 Nov 2019 00:41:22 +0100 Subject: docs/memory-barriers.txt/kokr: Update I/O section to be clearer about CPU vs thread Translate this commit to Korean: 9726840d9cf0 ("docs/memory-barriers.txt: Update I/O section to be clearer about CPU vs thread") Signed-off-by: SeongJae Park Link: https://lore.kernel.org/r/20191121234125.28032-5-sj38.park@gmail.com Signed-off-by: Jonathan Corbet --- .../translations/ko_KR/memory-barriers.txt | 56 ++++++++++++---------- 1 file changed, 32 insertions(+), 24 deletions(-) diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt index 6ae6d24ba60e..f07c40a068b5 100644 --- a/Documentation/translations/ko_KR/memory-barriers.txt +++ b/Documentation/translations/ko_KR/memory-barriers.txt @@ -2485,27 +2485,34 @@ I/O 액세스를 통한 주변장치와의 통신은 아키텍쳐와 기기에 (예: ioremap() 으로 반환되는 것) 의 순서 보장은 다음과 같습니다: 1. 같은 주변장치로의 모든 readX() 와 writeX() 액세스는 각자에 대해 - 순서지어집니다. 예를 들어, CPU 의 특정 디바이스로의 MMIO 레지스터 - 쓰기는 프로그램 순서대로 도착할 것이 보장됩니다. - - 2. CPU 에 의한 특정 주변장치로의 writeX() 는 모든 앞선 CPU 의 메모리 - 쓰기가 완료되기를 먼저 기다립니다. 예를 들어, dma_alloc_coherent() - 를 통해 할당된 전송용 DMA 버퍼로의 CPU 의 쓰기는 이 전송을 - 시작시키기 위해 CPU 가 MMIO 컨트롤 레지스터에 쓰기를 할 때 DMA - 엔진에 보일 것이 보장됩니다. - - 3. CPU 에 의한 주변장치로의 readX() 는 모든 뒤따르는 CPU 의 메모리 - 읽기가 시작되기 전에 완료됩니다. 예를 들어, dma_alloc_coherent() 를 - 통해 할당된 수신용 DMA 버퍼로부터의 CPU 의 읽기는 이 DMA 수신의 - 완료를 표시하는 DMA 엔진의 MMIO 상태 레지스터 읽기 후에는 오염된 - 데이터를 읽지 않을 것이 보장됩니다. - - 4. CPU 에 의한 주변장치로의 readX() 는 모든 뒤따르는 delay() 루프가 - 수행을 시작하기 전에 완료됩니다. 예를 들어, CPU 의 특정 + 순서지어집니다. 이는 같은 CPU 쓰레드에 의한 특정 디바이스로의 MMIO + 레지스터 액세스가 프로그램 순서대로 도착할 것을 보장합니다. + + 2. 한 스핀락을 잡은 CPU 쓰레드에 의한 writeX() 는 같은 스핀락을 나중에 + 잡은 다른 CPU 쓰레드에 의해 같은 주변장치를 향해 호출된 writeX() + 앞으로 순서지어집니다. 이는 스핀락을 잡은 채 특정 디바이스를 향해 + 호출된 MMIO 레지스터 쓰기는 해당 락의 획득에 일관적인 순서로 도달할 + 것을 보장합니다. + + 3. 특정 주변장치를 향한 특정 CPU 쓰레드의 writeX() 는 먼저 해당 + 쓰레드로 전파되는, 또는 해당 쓰레드에 의해 요청된 모든 앞선 메모리 + 쓰기가 완료되기 전까지 먼저 기다립니다. 이는 dma_alloc_coherent() + 를 통해 할당된 전송용 DMA 버퍼로의 해당 CPU 의 쓰기가 이 CPU 가 이 + 전송을 시작시키기 위해 MMIO 컨트롤 레지스터에 쓰기를 할 때 DMA + 엔진에 보여질 것을 보장합니다. + + 4. 특정 CPU 쓰레드에 의한 주변장치로의 readX() 는 같은 쓰레드에 의한 + 모든 뒤따르는 메모리 읽기가 시작되기 전에 완료됩니다. 이는 + dma_alloc_coherent() 를 통해 할당된 수신용 DMA 버퍼로부터의 CPU 의 + 읽기는 이 DMA 수신의 완료를 표시하는 DMA 엔진의 MMIO 상태 레지스터 + 읽기 후에는 오염된 데이터를 읽지 않을 것을 보장합니다. + + 5. CPU 에 의한 주변장치로의 readX() 는 모든 뒤따르는 delay() 루프가 + 수행을 시작하기 전에 완료됩니다. 이는 CPU 의 특정 주변장치로의 두개의 MMIO 레지스터 쓰기가 행해지는데 첫번째 쓰기가 readX() 를 통해 곧바로 읽어졌고 이어 두번째 writeX() 전에 udelay(1) - 이 호출되었다면 이 두개의 쓰기는 최소 1us 의 간격을 두고 행해질 것이 - 보장됩니다: + 이 호출되었다면 이 두개의 쓰기는 최소 1us 의 간격을 두고 행해질 것을 + 보장합니다: writel(42, DEVICE_REGISTER_0); // 디바이스에 도착함... readl(DEVICE_REGISTER_0); @@ -2520,9 +2527,9 @@ I/O 액세스를 통한 주변장치와의 통신은 아키텍쳐와 기기에 이것들은 readX() 와 writeX() 랑 비슷하지만, 더 완화된 메모리 순서 보장을 제공합니다. 구체적으로, 이것들은 일반적 메모리 액세스나 delay() - 루프 (예:앞의 2-4 항목) 에 대해 순서를 보장하지 않습니다만 디폴트 I/O - 기능으로 매핑된 __iomem 포인터에 대해 동작할 때 같은 주변장치로의 - 액세스에는 순서가 맞춰질 것이 보장됩니다. + 루프 (예:앞의 2-5 항목) 에 대해 순서를 보장하지 않습니다만 디폴트 I/O + 기능으로 매핑된 __iomem 포인터에 대해 동작할 때, 같은 CPU 쓰레드에 의해 + 같은 주변장치로의 액세스에는 순서가 맞춰질 것이 보장됩니다. (*) readsX(), writesX(): @@ -2558,8 +2565,9 @@ I/O 액세스를 통한 주변장치와의 통신은 아키텍쳐와 기기에 이것들은 inX()/outX() 나 readX()/writeX() 처럼 실제로 수행하는 액세스의 종류에 따라 적절하게 수행될 것입니다. -이 모든 액세스 함수들은 아랫단의 주변장치가 little-endian 이라 가정하며, 따라서 -big-endian 아키텍쳐에서는 byte-swapping 오퍼레이션을 수행합니다. +String 액세스 함수 (insX(), outsX(), readsX() 그리고 writesX()) 의 예외를 +제외하고는, 앞의 모든 것이 아랫단의 주변장치가 little-endian 이라 가정하며, +따라서 big-endian 아키텍쳐에서는 byte-swapping 오퍼레이션을 수행합니다. =================================== -- cgit From a897b13d1b77c8bd532a239adfd48c286a1b39ab Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Fri, 22 Nov 2019 00:41:23 +0100 Subject: docs/memory-barriers.txt: Remove remaining references to mmiowb() This commit removes references to sections erased by Commit 915530396c78 ("Documentation: Kill all references to mmiowb()"). Signed-off-by: SeongJae Park Link: https://lore.kernel.org/r/20191121234125.28032-6-sj38.park@gmail.com Signed-off-by: Jonathan Corbet --- Documentation/memory-barriers.txt | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt index 1adbb8a371c7..ec3b5865c1be 100644 --- a/Documentation/memory-barriers.txt +++ b/Documentation/memory-barriers.txt @@ -63,7 +63,6 @@ CONTENTS - Compiler barrier. - CPU memory barriers. - - MMIO write barrier. (*) Implicit kernel memory barriers. @@ -75,7 +74,6 @@ CONTENTS (*) Inter-CPU acquiring barrier effects. - Acquires vs memory accesses. - - Acquires vs I/O accesses. (*) Where are memory barriers needed? @@ -492,10 +490,9 @@ And a couple of implicit varieties: happen before it completes. The use of ACQUIRE and RELEASE operations generally precludes the need - for other sorts of memory barrier (but note the exceptions mentioned in - the subsection "MMIO write barrier"). In addition, a RELEASE+ACQUIRE - pair is -not- guaranteed to act as a full memory barrier. However, after - an ACQUIRE on a given variable, all memory accesses preceding any prior + for other sorts of memory barrier. In addition, a RELEASE+ACQUIRE pair is + -not- guaranteed to act as a full memory barrier. However, after an + ACQUIRE on a given variable, all memory accesses preceding any prior RELEASE on that same variable are guaranteed to be visible. In other words, within a given variable's critical section, all accesses of all previous critical sections for that variable are guaranteed to have @@ -1512,8 +1509,6 @@ levels: (*) CPU memory barriers. - (*) MMIO write barrier. - COMPILER BARRIER ---------------- -- cgit From bf23a48edbe331f834eb49d1bd6484ae98cf4dc7 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Fri, 22 Nov 2019 00:41:24 +0100 Subject: Documentation/translation: Use Korean for Korean translation title Signed-off-by: SeongJae Park Link: https://lore.kernel.org/r/20191121234125.28032-7-sj38.park@gmail.com Signed-off-by: Jonathan Corbet --- Documentation/translations/ko_KR/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/translations/ko_KR/index.rst b/Documentation/translations/ko_KR/index.rst index 0b695345abc7..27995c4233de 100644 --- a/Documentation/translations/ko_KR/index.rst +++ b/Documentation/translations/ko_KR/index.rst @@ -3,8 +3,8 @@ \renewcommand\thesection* \renewcommand\thesubsection* -Korean translations -=================== +한국어 번역 +=========== .. toctree:: :maxdepth: 1 -- cgit From 605b0f53a126467aa24424690500ba1e6d8fbba2 Mon Sep 17 00:00:00 2001 From: SeongJae Park Date: Fri, 22 Nov 2019 00:41:25 +0100 Subject: Documentation/process/howto/kokr: Update for 4.x -> 5.x versioning Translate this commit to Korean: d2b008f134b7 ("Documentation/process/howto: Update for 4.x -> 5.x versioning") Signed-off-by: SeongJae Park Link: https://lore.kernel.org/r/20191121234125.28032-8-sj38.park@gmail.com Signed-off-by: Jonathan Corbet --- Documentation/translations/ko_KR/howto.rst | 56 ++++++++++++++---------------- 1 file changed, 27 insertions(+), 29 deletions(-) diff --git a/Documentation/translations/ko_KR/howto.rst b/Documentation/translations/ko_KR/howto.rst index b3f51b19de7c..ae3ad897d2ae 100644 --- a/Documentation/translations/ko_KR/howto.rst +++ b/Documentation/translations/ko_KR/howto.rst @@ -240,21 +240,21 @@ ReST 마크업을 사용하는 문서들은 Documentation/output 에 생성된 서브시스템에 특화된 커널 브랜치들로 구성된다. 몇몇 다른 메인 브랜치들은 다음과 같다. - - main 4.x 커널 트리 - - 4.x.y - 안정된 커널 트리 - - 서브시스템을 위한 커널 트리들과 패치들 - - 4.x - 통합 테스트를 위한 next 커널 트리 + - 리누스의 메인라인 트리 + - 여러 메이저 넘버를 갖는 다양한 안정된 커널 트리들 + - 서브시스템을 위한 커널 트리들 + - 통합 테스트를 위한 linux-next 커널 트리 -4.x 커널 트리 +메인라인 트리 ~~~~~~~~~~~~~ -4.x 커널들은 Linus Torvalds가 관리하며 https://kernel.org 의 -pub/linux/kernel/v4.x/ 디렉토리에서 참조될 수 있다.개발 프로세스는 다음과 같다. +메인라인 트리는 Linus Torvalds가 관리하며 https://kernel.org 또는 소스 +저장소에서 참조될 수 있다.개발 프로세스는 다음과 같다. - 새로운 커널이 배포되자마자 2주의 시간이 주어진다. 이 기간동은 메인테이너들은 큰 diff들을 Linus에게 제출할 수 있다. 대개 이 패치들은 - 몇 주 동안 -next 커널내에 이미 있었던 것들이다. 큰 변경들을 제출하는 데 - 선호되는 방법은 git(커널의 소스 관리 툴, 더 많은 정보들은 + 몇 주 동안 linux-next 커널내에 이미 있었던 것들이다. 큰 변경들을 제출하는 + 데 선호되는 방법은 git(커널의 소스 관리 툴, 더 많은 정보들은 https://git-scm.com/ 에서 참조할 수 있다)를 사용하는 것이지만 순수한 패치파일의 형식으로 보내는 것도 무관하다. - 2주 후에 -rc1 커널이 릴리즈되며 여기서부터의 주안점은 새로운 커널을 @@ -281,28 +281,25 @@ Andrew Morton의 글이 있다. 버그의 상황에 따라 배포되는 것이지 미리정해 놓은 시간에 따라 배포되는 것은 아니기 때문이다."* -4.x.y - 안정 커널 트리 -~~~~~~~~~~~~~~~~~~~~~~ +여러 메이저 넘버를 갖는 다양한 안정된 커널 트리들 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -3 자리 숫자로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 4.x -커널에서 발견된 큰 회귀들이나 보안 문제들 중 비교적 작고 중요한 수정들을 -포함한다. +3 자리 숫자로 이루어진 버젼의 커널들은 -stable 커널들이다. 그것들은 해당 메이저 +메인라인 릴리즈에서 발견된 큰 회귀들이나 보안 문제들 중 비교적 작고 중요한 +수정들을 포함하며, 앞의 두 버전 넘버는 같은 기반 버전을 의미한다. 이것은 가장 최근의 안정적인 커널을 원하는 사용자에게 추천되는 브랜치이며, 개발/실험적 버젼을 테스트하는 것을 돕고자 하는 사용자들과는 별로 관련이 없다. -어떤 4.x.y 커널도 사용할 수 없다면 그때는 가장 높은 숫자의 4.x -커널이 현재의 안정 커널이다. - -4.x.y는 "stable" 팀에 의해 관리되며 거의 매번 격주로 -배포된다. +-stable 트리들은 "stable" 팀에 의해 관리되며 거의 매번 +격주로 배포된다. 커널 트리 문서들 내의 :ref:`Documentation/process/stable-kernel-rules.rst ` 파일은 어떤 종류의 변경들이 -stable 트리로 들어왔는지와 배포 프로세스가 어떻게 진행되는지를 설명한다. -서브시스템 커널 트리들과 패치들 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +서브시스템 커널 트리들 +~~~~~~~~~~~~~~~~~~~~~~ 다양한 커널 서브시스템의 메인테이너들 --- 그리고 많은 커널 서브시스템 개발자들 --- 은 그들의 현재 개발 상태를 소스 저장소로 노출한다. 이를 통해 다른 사람들도 @@ -324,17 +321,18 @@ Andrew Morton의 글이 있다. 대부분의 이러한 patchwork 사이트는 https://patchwork.kernel.org/ 또는 http://patchwork.ozlabs.org/ 에 나열되어 있다. -4.x - 통합 테스트를 위한 next 커널 트리 ---------------------------------------- -서브시스템 트리들의 변경사항들은 mainline 4.x 트리로 들어오기 전에 통합 -테스트를 거쳐야 한다. 이런 목적으로, 모든 서브시스템 트리의 변경사항을 거의 -매일 받아가는 특수한 테스트 저장소가 존재한다: +통합 테스트를 위한 linux-next 커널 트리 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +서브시스템 트리들의 변경사항들은 mainline 트리로 들어오기 전에 통합 테스트를 +거쳐야 한다. 이런 목적으로, 모든 서브시스템 트리의 변경사항을 거의 매일 +받아가는 특수한 테스트 저장소가 존재한다: https://git.kernel.org/?p=linux/kernel/git/sfr/linux-next.git -이런 식으로, -next 커널을 통해 다음 머지 기간에 메인라인 커널에 어떤 변경이 -가해질 것인지 간략히 알 수 있다. 모험심 강한 테스터라면 -next 커널에서 테스트를 -수행하는 것도 좋을 것이다. +이런 식으로, linux-next 커널을 통해 다음 머지 기간에 메인라인 커널에 어떤 +변경이 가해질 것인지 간략히 알 수 있다. 모험심 강한 테스터라면 linux-next +커널에서 테스트를 수행하는 것도 좋을 것이다. 버그 보고 -- cgit From 402613f3ef4bdac0406d710c7b9dabac76a43679 Mon Sep 17 00:00:00 2001 From: "Daniel W. S. Almeida" Date: Fri, 22 Nov 2019 01:18:06 -0300 Subject: Documentation: security: core.rst: fix warnings Fix warnings due to missing markup, no change in content otherwise. Signed-off-by: Daniel W. S. Almeida Link: https://lore.kernel.org/r/20191122041806.68650-1-dwlsalmeida@gmail.com Signed-off-by: Jonathan Corbet --- Documentation/security/keys/core.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/security/keys/core.rst b/Documentation/security/keys/core.rst index d6d8b0b756b6..d9b0b859018b 100644 --- a/Documentation/security/keys/core.rst +++ b/Documentation/security/keys/core.rst @@ -1102,7 +1102,7 @@ payload contents" for more information. See also Documentation/security/keys/request-key.rst. - * To search for a key in a specific domain, call: + * To search for a key in a specific domain, call:: struct key *request_key_tag(const struct key_type *type, const char *description, -- cgit From e3fedd570dedc0cde6240aff7a2bf62043b67ce9 Mon Sep 17 00:00:00 2001 From: Masami Hiramatsu Date: Fri, 22 Nov 2019 22:50:17 +0900 Subject: Documentation: Remove bootmem_debug from kernel-parameters.txt Remove bootmem_debug kernel paramenter because it has been replaced by memblock=debug. Signed-off-by: Masami Hiramatsu Cc: Mike Rapoport Cc: Andrew Morton Cc: Jonathan Corbet Link: https://lore.kernel.org/r/157443061745.20995.9432492850513217966.stgit@devnote2 Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/kernel-parameters.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 3e24f0a93ae9..0445f98f0eb6 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -437,8 +437,6 @@ no delay (0). Format: integer - bootmem_debug [KNL] Enable bootmem allocator debug messages. - bert_disable [ACPI] Disable BERT OS support on buggy BIOSes. -- cgit From 4920323cffc0fe10ac107ab3e94d1bd218a678d9 Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Thu, 21 Nov 2019 12:59:27 -0800 Subject: docs, parallelism: Fix failure path and add comment Rasmus noted that the failure path didn't correctly exit. Fix this and add another comment about GNU Make's job server environment variable names over time. Reported-by: Rasmus Villemoes Link: https://lore.kernel.org/lkml/eb25959a-9ec4-3530-2031-d9d716b40b20@rasmusvillemoes.dk Signed-off-by: Kees Cook Link: https://lore.kernel.org/r/20191121205929.40371-2-keescook@chromium.org Signed-off-by: Jonathan Corbet --- scripts/jobserver-count | 3 +++ 1 file changed, 3 insertions(+) diff --git a/scripts/jobserver-count b/scripts/jobserver-count index 0b482d6884d2..6e15b38df3d0 100755 --- a/scripts/jobserver-count +++ b/scripts/jobserver-count @@ -24,6 +24,8 @@ try: flags = os.environ['MAKEFLAGS'] # Look for "--jobserver=R,W" + # Note that GNU Make has used --jobserver-fds and --jobserver-auth + # so this handles all of them. opts = [x for x in flags.split(" ") if x.startswith("--jobserver")] # Parse out R,W file descriptor numbers and set them nonblocking. @@ -53,6 +55,7 @@ os.write(writer, jobs) # If the jobserver was (impossibly) full or communication failed, use default. if len(jobs) < 1: print(default) + sys.exit(0) # Report available slots (with a bump for our caller's reserveration). print(len(jobs) + 1) -- cgit From dffd011480d727a819c537edf3b90ef063731725 Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Thu, 21 Nov 2019 12:59:28 -0800 Subject: docs, parallelism: Do not leak blocking mode to other readers Setting non-blocking via a local copy of the jobserver file descriptor is safer than just assuming other reader processes with the same fd open are prepared for it to be non-blocking. Suggested-by: Rasmus Villemoes Link: https://lore.kernel.org/lkml/44c01043-ab24-b4de-6544-e8efd153e27a@rasmusvillemoes.dk Signed-off-by: Kees Cook Link: https://lore.kernel.org/r/20191121205929.40371-3-keescook@chromium.org Signed-off-by: Jonathan Corbet --- scripts/jobserver-count | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/scripts/jobserver-count b/scripts/jobserver-count index 6e15b38df3d0..7807bfa7dafa 100755 --- a/scripts/jobserver-count +++ b/scripts/jobserver-count @@ -12,12 +12,6 @@ default="1" if len(sys.argv) > 1: default=sys.argv[1] -# Set non-blocking for a given file descriptor. -def nonblock(fd): - flags = fcntl.fcntl(fd, fcntl.F_GETFL) - fcntl.fcntl(fd, fcntl.F_SETFL, flags | os.O_NONBLOCK) - return fd - # Extract and prepare jobserver file descriptors from envirnoment. try: # Fetch the make environment options. @@ -31,8 +25,12 @@ try: # Parse out R,W file descriptor numbers and set them nonblocking. fds = opts[0].split("=", 1)[1] reader, writer = [int(x) for x in fds.split(",", 1)] - reader = nonblock(reader) -except (KeyError, IndexError, ValueError, IOError): + # Open a private copy of reader to avoid setting nonblocking + # on an unexpecting process with the same reader fd. + reader = os.open("/proc/self/fd/%d" % (reader), + os.O_RDONLY | os.O_NONBLOCK) +except (KeyError, IndexError, ValueError, IOError, OSError) as e: + print(e, file=sys.stderr) # Any missing environment strings or bad fds should result in just # using the default specified parallelism. print(default) -- cgit From 51e46c7a4007d271b2d42dbc2df953ab968577a7 Mon Sep 17 00:00:00 2001 From: Kees Cook Date: Thu, 21 Nov 2019 12:59:29 -0800 Subject: docs, parallelism: Rearrange how jobserver reservations are made Rasmus correctly observed that the existing jobserver reservation only worked if no other build targets were specified. The correct approach is to hold the jobserver slots until sphinx has finished. To fix this, the following changes are made: - refactor (and rename) scripts/jobserver-exec to set an environment variable for the maximally reserved jobserver slots and exec a child, to release the slots on exit. - create Documentation/scripts/parallel-wrapper.sh which examines both $PARALLELISM and the detected "-jauto" logic from Documentation/Makefile to decide sphinx's final -j argument. - chain these together in Documentation/Makefile Suggested-by: Rasmus Villemoes Link: https://lore.kernel.org/lkml/eb25959a-9ec4-3530-2031-d9d716b40b20@rasmusvillemoes.dk Signed-off-by: Kees Cook Link: https://lore.kernel.org/r/20191121205929.40371-4-keescook@chromium.org Signed-off-by: Jonathan Corbet --- Documentation/Makefile | 5 +-- Documentation/sphinx/parallel-wrapper.sh | 33 ++++++++++++++++ scripts/jobserver-count | 59 ---------------------------- scripts/jobserver-exec | 66 ++++++++++++++++++++++++++++++++ 4 files changed, 101 insertions(+), 62 deletions(-) create mode 100644 Documentation/sphinx/parallel-wrapper.sh delete mode 100755 scripts/jobserver-count create mode 100755 scripts/jobserver-exec diff --git a/Documentation/Makefile b/Documentation/Makefile index ce8eb63b523a..30554a2fbdd7 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -33,8 +33,6 @@ ifeq ($(HAVE_SPHINX),0) else # HAVE_SPHINX -export SPHINX_PARALLEL = $(shell perl -e 'open IN,"sphinx-build --version 2>&1 |"; while () { if (m/([\d\.]+)/) { print "auto" if ($$1 >= "1.7") } ;} close IN') - # User-friendly check for pdflatex and latexmk HAVE_PDFLATEX := $(shell if which $(PDFLATEX) >/dev/null 2>&1; then echo 1; else echo 0; fi) HAVE_LATEXMK := $(shell if which latexmk >/dev/null 2>&1; then echo 1; else echo 0; fi) @@ -67,8 +65,9 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4) cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2 && \ PYTHONDONTWRITEBYTECODE=1 \ BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \ + $(PYTHON) $(srctree)/scripts/jobserver-exec \ + $(SHELL) $(srctree)/Documentation/sphinx/parallel-wrapper.sh \ $(SPHINXBUILD) \ - -j $(shell python $(srctree)/scripts/jobserver-count $(SPHINX_PARALLEL)) \ -b $2 \ -c $(abspath $(srctree)/$(src)) \ -d $(abspath $(BUILDDIR)/.doctrees/$3) \ diff --git a/Documentation/sphinx/parallel-wrapper.sh b/Documentation/sphinx/parallel-wrapper.sh new file mode 100644 index 000000000000..7daf5133bdd3 --- /dev/null +++ b/Documentation/sphinx/parallel-wrapper.sh @@ -0,0 +1,33 @@ +#!/bin/sh +# SPDX-License-Identifier: GPL-2.0+ +# +# Figure out if we should follow a specific parallelism from the make +# environment (as exported by scripts/jobserver-exec), or fall back to +# the "auto" parallelism when "-jN" is not specified at the top-level +# "make" invocation. + +sphinx="$1" +shift || true + +parallel="$PARALLELISM" +if [ -z "$parallel" ] ; then + # If no parallelism is specified at the top-level make, then + # fall back to the expected "-jauto" mode that the "htmldocs" + # target has had. + auto=$(perl -e 'open IN,"'"$sphinx"' --version 2>&1 |"; + while () { + if (m/([\d\.]+)/) { + print "auto" if ($1 >= "1.7") + } + } + close IN') + if [ -n "$auto" ] ; then + parallel="$auto" + fi +fi +# Only if some parallelism has been determined do we add the -jN option. +if [ -n "$parallel" ] ; then + parallel="-j$parallel" +fi + +exec "$sphinx" "$parallel" "$@" diff --git a/scripts/jobserver-count b/scripts/jobserver-count deleted file mode 100755 index 7807bfa7dafa..000000000000 --- a/scripts/jobserver-count +++ /dev/null @@ -1,59 +0,0 @@ -#!/usr/bin/env python -# SPDX-License-Identifier: GPL-2.0+ -# -# This determines how many parallel tasks "make" is expecting, as it is -# not exposed via an special variables. -# https://www.gnu.org/software/make/manual/html_node/POSIX-Jobserver.html#POSIX-Jobserver -from __future__ import print_function -import os, sys, fcntl, errno - -# Default parallelism is "1" unless overridden on the command-line. -default="1" -if len(sys.argv) > 1: - default=sys.argv[1] - -# Extract and prepare jobserver file descriptors from envirnoment. -try: - # Fetch the make environment options. - flags = os.environ['MAKEFLAGS'] - - # Look for "--jobserver=R,W" - # Note that GNU Make has used --jobserver-fds and --jobserver-auth - # so this handles all of them. - opts = [x for x in flags.split(" ") if x.startswith("--jobserver")] - - # Parse out R,W file descriptor numbers and set them nonblocking. - fds = opts[0].split("=", 1)[1] - reader, writer = [int(x) for x in fds.split(",", 1)] - # Open a private copy of reader to avoid setting nonblocking - # on an unexpecting process with the same reader fd. - reader = os.open("/proc/self/fd/%d" % (reader), - os.O_RDONLY | os.O_NONBLOCK) -except (KeyError, IndexError, ValueError, IOError, OSError) as e: - print(e, file=sys.stderr) - # Any missing environment strings or bad fds should result in just - # using the default specified parallelism. - print(default) - sys.exit(0) - -# Read out as many jobserver slots as possible. -jobs = b"" -while True: - try: - slot = os.read(reader, 1) - jobs += slot - except (OSError, IOError) as e: - if e.errno == errno.EWOULDBLOCK: - # Stop when reach the end of the jobserver queue. - break - raise e -# Return all the reserved slots. -os.write(writer, jobs) - -# If the jobserver was (impossibly) full or communication failed, use default. -if len(jobs) < 1: - print(default) - sys.exit(0) - -# Report available slots (with a bump for our caller's reserveration). -print(len(jobs) + 1) diff --git a/scripts/jobserver-exec b/scripts/jobserver-exec new file mode 100755 index 000000000000..0fdb31a790a8 --- /dev/null +++ b/scripts/jobserver-exec @@ -0,0 +1,66 @@ +#!/usr/bin/env python +# SPDX-License-Identifier: GPL-2.0+ +# +# This determines how many parallel tasks "make" is expecting, as it is +# not exposed via an special variables, reserves them all, runs a subprocess +# with PARALLELISM environment variable set, and releases the jobs back again. +# +# https://www.gnu.org/software/make/manual/html_node/POSIX-Jobserver.html#POSIX-Jobserver +from __future__ import print_function +import os, sys, errno +import subprocess + +# Extract and prepare jobserver file descriptors from envirnoment. +claim = 0 +jobs = b"" +try: + # Fetch the make environment options. + flags = os.environ['MAKEFLAGS'] + + # Look for "--jobserver=R,W" + # Note that GNU Make has used --jobserver-fds and --jobserver-auth + # so this handles all of them. + opts = [x for x in flags.split(" ") if x.startswith("--jobserver")] + + # Parse out R,W file descriptor numbers and set them nonblocking. + fds = opts[0].split("=", 1)[1] + reader, writer = [int(x) for x in fds.split(",", 1)] + # Open a private copy of reader to avoid setting nonblocking + # on an unexpecting process with the same reader fd. + reader = os.open("/proc/self/fd/%d" % (reader), + os.O_RDONLY | os.O_NONBLOCK) + + # Read out as many jobserver slots as possible. + while True: + try: + slot = os.read(reader, 8) + jobs += slot + except (OSError, IOError) as e: + if e.errno == errno.EWOULDBLOCK: + # Stop at the end of the jobserver queue. + break + # If something went wrong, give back the jobs. + if len(jobs): + os.write(writer, jobs) + raise e + # Add a bump for our caller's reserveration, since we're just going + # to sit here blocked on our child. + claim = len(jobs) + 1 +except (KeyError, IndexError, ValueError, OSError, IOError) as e: + # Any missing environment strings or bad fds should result in just + # not being parallel. + pass + +# We can only claim parallelism if there was a jobserver (i.e. a top-level +# "-jN" argument) and there were no other failures. Otherwise leave out the +# environment variable and let the child figure out what is best. +if claim > 0: + os.environ['PARALLELISM'] = '%d' % (claim) + +rc = subprocess.call(sys.argv[1:]) + +# Return all the reserved slots. +if len(jobs): + os.write(writer, jobs) + +sys.exit(rc) -- cgit From 1ca84ed6425f55aac68e3600122d04cd23c86d38 Mon Sep 17 00:00:00 2001 From: Dan Williams Date: Sun, 24 Nov 2019 12:59:48 -0800 Subject: MAINTAINERS: Reclaim the P: tag for Maintainer Entry Profile Fixup some P: entries to be M: and delete the others that do not include an email address. The P: tag will be used to indicate the location of a Profile for a given MAINTAINERS entry. Cc: Joe Perches Signed-off-by: Dan Williams Link: https://lore.kernel.org/r/157462918794.1729495.10838545318307341653.stgit@dwillia2-desk3.amr.corp.intel.com Signed-off-by: Jonathan Corbet --- MAINTAINERS | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/MAINTAINERS b/MAINTAINERS index 2904dacba8fe..9611ea6493b3 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -819,7 +819,7 @@ S: Orphan F: drivers/usb/gadget/udc/amd5536udc.* AMD GEODE PROCESSOR/CHIPSET SUPPORT -P: Andres Salomon +M: Andres Salomon L: linux-geode@lists.infradead.org (moderated for non-subscribers) W: http://www.amd.com/us-en/ConnectivitySolutions/TechnicalResources/0,,50_2334_2452_11363,00.html S: Supported @@ -10204,7 +10204,6 @@ F: drivers/staging/media/tegra-vde/ MEDIA INPUT INFRASTRUCTURE (V4L/DVB) M: Mauro Carvalho Chehab -P: LinuxTV.org Project L: linux-media@vger.kernel.org W: https://linuxtv.org Q: http://patchwork.kernel.org/project/linux-media/list/ @@ -13609,7 +13608,6 @@ S: Maintained F: arch/mips/ralink RALINK RT2X00 WIRELESS LAN DRIVER -P: rt2x00 project M: Stanislaw Gruszka M: Helmut Schaa L: linux-wireless@vger.kernel.org @@ -13945,7 +13943,6 @@ S: Supported F: drivers/net/ethernet/rocker/ ROCKETPORT DRIVER -P: Comtrol Corp. W: http://www.comtrol.com S: Maintained F: Documentation/driver-api/serial/rocket.rst @@ -14836,15 +14833,13 @@ F: drivers/video/fbdev/simplefb.c F: include/linux/platform_data/simplefb.h SIMTEC EB110ATX (Chalice CATS) -P: Ben Dooks -P: Vincent Sanders +M: Vincent Sanders M: Simtec Linux Team W: http://www.simtec.co.uk/products/EB110ATX/ S: Supported SIMTEC EB2410ITX (BAST) -P: Ben Dooks -P: Vincent Sanders +M: Vincent Sanders M: Simtec Linux Team W: http://www.simtec.co.uk/products/EB2410ITX/ S: Supported -- cgit From 4699c504e603e2b4e6217a81839d06c26cb2dad7 Mon Sep 17 00:00:00 2001 From: Dan Williams Date: Sun, 24 Nov 2019 12:59:53 -0800 Subject: Maintainer Handbook: Maintainer Entry Profile As presented at the 2018 Linux Plumbers conference [1], the Maintainer Entry Profile (formerly Subsystem Profile) is proposed as a way to reduce friction between committers and maintainers and encourage conversations amongst maintainers about common best practices. While coding-style, submit-checklist, and submitting-drivers lay out some common expectations there remain local customs and maintainer preferences that vary by subsystem. The profile contains documentation of some of the common policy questions a contributor might have that are local to the subsystem / device-driver, special considerations for the subsystem, or other guidelines that are otherwise not covered by the top-level process documents. The initial and hopefully non-controversial headings in the profile are: Overview: General introduction to how the subsystem operates Submit Checklist Addendum: Mechanical items that gate submission staging, or other requirements that gate patch acceptance. Key Cycle Dates: - Last -rc for new feature submissions: Expected lead time for submissions - Last -rc to merge features: Deadline for merge decisions Resubmit Cadence: When and preferred method to follow up with the maintainer Note that coding style guidelines are explicitly left out of this list. See Documentation/maintainer/maintainer-entry-profile.rst for more details, and a follow-on example profile for the libnvdimm subsystem. [1]: https://linuxplumbersconf.org/event/2/contributions/59/ Cc: Jonathan Corbet Cc: Thomas Gleixner Cc: Mauro Carvalho Chehab Cc: Steve French Cc: Greg Kroah-Hartman Cc: Linus Torvalds Cc: Tobin C. Harding Cc: Olof Johansson Cc: Martin K. Petersen Cc: Daniel Vetter Cc: Joe Perches Cc: Dmitry Vyukov Cc: Alexandre Belloni Cc: Paul Walmsley Signed-off-by: Dan Williams Link: https://lore.kernel.org/r/157462919309.1729495.10585699280061787229.stgit@dwillia2-desk3.amr.corp.intel.com Signed-off-by: Jonathan Corbet --- Documentation/maintainer/index.rst | 1 + .../maintainer/maintainer-entry-profile.rst | 87 ++++++++++++++++++++++ MAINTAINERS | 4 + 3 files changed, 92 insertions(+) create mode 100644 Documentation/maintainer/maintainer-entry-profile.rst diff --git a/Documentation/maintainer/index.rst b/Documentation/maintainer/index.rst index 56e2c09dfa39..d904e74e1159 100644 --- a/Documentation/maintainer/index.rst +++ b/Documentation/maintainer/index.rst @@ -12,4 +12,5 @@ additions to this manual. configure-git rebasing-and-merging pull-requests + maintainer-entry-profile diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst new file mode 100644 index 000000000000..51de3b9e606d --- /dev/null +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -0,0 +1,87 @@ +.. _maintainerentryprofile: + +Maintainer Entry Profile +======================== + +The Maintainer Entry Profile supplements the top-level process documents +(submitting-patches, submitting drivers...) with +subsystem/device-driver-local customs as well as details about the patch +submission life-cycle. A contributor uses this document to level set +their expectations and avoid common mistakes, maintainers may use these +profiles to look across subsystems for opportunities to converge on +common practices. + + +Overview +-------- +Provide an introduction to how the subsystem operates. While MAINTAINERS +tells the contributor where to send patches for which files, it does not +convey other subsystem-local infrastructure and mechanisms that aid +development. +Example questions to consider: +- Are there notifications when patches are applied to the local tree, or + merged upstream? +- Does the subsystem have a patchwork instance? Are patchwork state + changes notified? +- Any bots or CI infrastructure that watches the list, or automated + testing feedback that the subsystem gates acceptance? +- Git branches that are pulled into -next? +- What branch should contributors submit against? +- Links to any other Maintainer Entry Profiles? For example a + device-driver may point to an entry for its parent subsystem. This makes + the contributor aware of obligations a maintainer may have have for + other maintainers in the submission chain. + + +Submit Checklist Addendum +------------------------- +List mandatory and advisory criteria, beyond the common "submit-checklist", +for a patch to be considered healthy enough for maintainer attention. +For example: "pass checkpatch.pl with no errors, or warning. Pass the +unit test detailed at $URI". + +The Submit Checklist Addendum can also include details about the status +of related hardware specifications. For example, does the subsystem +require published specifications at a certain revision before patches +will be considered. + + +Key Cycle Dates +--------------- +One of the common misunderstandings of submitters is that patches can be +sent at any time before the merge window closes and can still be +considered for the next -rc1. The reality is that most patches need to +be settled in soaking in linux-next in advance of the merge window +opening. Clarify for the submitter the key dates (in terms rc release +week) that patches might considered for merging and when patches need to +wait for the next -rc. At a minimum: +- Last -rc for new feature submissions: + New feature submissions targeting the next merge window should have + their first posting for consideration before this point. Patches that + are submitted after this point should be clear that they are targeting + the NEXT+1 merge window, or should come with sufficient justification + why they should be considered on an expedited schedule. A general + guideline is to set expectation with contributors that new feature + submissions should appear before -rc5. + +- Last -rc to merge features: Deadline for merge decisions + Indicate to contributors the point at which an as yet un-applied patch + set will need to wait for the NEXT+1 merge window. Of course there is no + obligation to ever except any given patchset, but if the review has not + concluded by this point the expectation the contributor should wait and + resubmit for the following merge window. + +Optional: +- First -rc at which the development baseline branch, listed in the + overview section, should be considered ready for new submissions. + + +Review Cadence +-------------- +One of the largest sources of contributor angst is how soon to ping +after a patchset has been posted without receiving any feedback. In +addition to specifying how long to wait before a resubmission this +section can also indicate a preferred style of update like, resend the +full series, or privately send a reminder email. This section might also +list how review works for this code area and methods to get feedback +that are not directly from the maintainer. diff --git a/MAINTAINERS b/MAINTAINERS index 9611ea6493b3..9d3a2464e173 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -102,6 +102,10 @@ Descriptions of section entries Obsolete: Old code. Something tagged obsolete generally means it has been replaced by a better system and you should be using that. + P: Subsystem Profile document for more details submitting + patches to the given subsystem. This is either an in-tree file, + or a URI. See Documentation/maintainer/maintainer-entry-profile.rst + for details. F: *Files* and directories wildcard patterns. A trailing slash includes all files and subdirectory files. F: drivers/net/ all files in and below drivers/net -- cgit From 47843401e3a0f4f668927b77e713c876bb423d4f Mon Sep 17 00:00:00 2001 From: Dan Williams Date: Sun, 24 Nov 2019 12:59:58 -0800 Subject: libnvdimm, MAINTAINERS: Maintainer Entry Profile Document the basic policies of the libnvdimm subsystem and provide a first example of a Maintainer Entry Profile for others to duplicate and edit. Cc: Vishal Verma Cc: Dave Jiang Signed-off-by: Dan Williams Link: https://lore.kernel.org/r/157462919825.1729495.5877405723948988416.stgit@dwillia2-desk3.amr.corp.intel.com Signed-off-by: Jonathan Corbet --- Documentation/nvdimm/maintainer-entry-profile.rst | 59 +++++++++++++++++++++++ MAINTAINERS | 4 ++ 2 files changed, 63 insertions(+) create mode 100644 Documentation/nvdimm/maintainer-entry-profile.rst diff --git a/Documentation/nvdimm/maintainer-entry-profile.rst b/Documentation/nvdimm/maintainer-entry-profile.rst new file mode 100644 index 000000000000..77081fd9be95 --- /dev/null +++ b/Documentation/nvdimm/maintainer-entry-profile.rst @@ -0,0 +1,59 @@ +LIBNVDIMM Maintainer Entry Profile +================================== + +Overview +-------- +The libnvdimm subsystem manages persistent memory across multiple +architectures. The mailing list, is tracked by patchwork here: +https://patchwork.kernel.org/project/linux-nvdimm/list/ +...and that instance is configured to give feedback to submitters on +patch acceptance and upstream merge. Patches are merged to either the +'libnvdimm-fixes', or 'libnvdimm-for-next' branch. Those branches are +available here: +https://git.kernel.org/pub/scm/linux/kernel/git/nvdimm/nvdimm.git/ + +In general patches can be submitted against the latest -rc, however if +the incoming code change is dependent on other pending changes then the +patch should be based on the libnvdimm-for-next branch. However, since +persistent memory sits at the intersection of storage and memory there +are cases where patches are more suitable to be merged through a +Filesystem or the Memory Management tree. When in doubt copy the nvdimm +list and the maintainers will help route. + +Submissions will be exposed to the kbuild robot for compile regression +testing. It helps to get a success notification from that infrastructure +before submitting, but it is not required. + + +Submit Checklist Addendum +------------------------- +There are unit tests for the subsystem via the ndctl utility: +https://github.com/pmem/ndctl +Those tests need to be passed before the patches go upstream, but not +necessarily before initial posting. Contact the list if you need help +getting the test environment set up. + +### ACPI Device Specific Methods (_DSM) +Before patches enabling for a new _DSM family will be considered it must +be assigned a format-interface-code from the NVDIMM Sub-team of the ACPI +Specification Working Group. In general, the stance of the subsystem is +to push back on the proliferation of NVDIMM command sets, do strongly +consider implementing support for an existing command set. See +drivers/acpi/nfit/nfit.h for the set of support command sets. + + +Key Cycle Dates +--------------- +New submissions can be sent at any time, but if they intend to hit the +next merge window they should be sent before -rc4, and ideally +stabilized in the libnvdimm-for-next branch by -rc6. Of course if a +patch set requires more than 2 weeks of review -rc4 is already too late +and some patches may require multiple development cycles to review. + + +Review Cadence +-------------- +In general, please wait up to one week before pinging for feedback. A +private mail reminder is preferred. Alternatively ask for other +developers that have Reviewed-by tags for libnvdimm changes to take a +look and offer their opinion. diff --git a/MAINTAINERS b/MAINTAINERS index 9d3a2464e173..0093d236a63f 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -9305,6 +9305,7 @@ M: Dan Williams M: Vishal Verma M: Dave Jiang L: linux-nvdimm@lists.01.org +P: Documentation/nvdimm/maintainer-entry-profile.rst Q: https://patchwork.kernel.org/project/linux-nvdimm/list/ S: Supported F: drivers/nvdimm/blk.c @@ -9315,6 +9316,7 @@ M: Vishal Verma M: Dan Williams M: Dave Jiang L: linux-nvdimm@lists.01.org +P: Documentation/nvdimm/maintainer-entry-profile.rst Q: https://patchwork.kernel.org/project/linux-nvdimm/list/ S: Supported F: drivers/nvdimm/btt* @@ -9324,6 +9326,7 @@ M: Dan Williams M: Vishal Verma M: Dave Jiang L: linux-nvdimm@lists.01.org +P: Documentation/nvdimm/maintainer-entry-profile.rst Q: https://patchwork.kernel.org/project/linux-nvdimm/list/ S: Supported F: drivers/nvdimm/pmem* @@ -9343,6 +9346,7 @@ M: Dave Jiang M: Keith Busch M: Ira Weiny L: linux-nvdimm@lists.01.org +P: Documentation/nvdimm/maintainer-entry-profile.rst Q: https://patchwork.kernel.org/project/linux-nvdimm/list/ T: git git://git.kernel.org/pub/scm/linux/kernel/git/nvdimm/nvdimm.git S: Supported -- cgit From 0bfa52a43ec085c2f5eb2c35fcc6cf73bb802eae Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Mon, 25 Nov 2019 08:42:12 -0700 Subject: docs: fix up the maintainer profile document Add blank lines where needed to get the document to render properly. Also add a TOC of existing profiles just so that the nvdimm profile is linked into the toctree, is discoverable, and doesn't generate a warning. Signed-off-by: Jonathan Corbet --- Documentation/maintainer/maintainer-entry-profile.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst index 51de3b9e606d..3eaddc8ac56d 100644 --- a/Documentation/maintainer/maintainer-entry-profile.rst +++ b/Documentation/maintainer/maintainer-entry-profile.rst @@ -18,7 +18,9 @@ Provide an introduction to how the subsystem operates. While MAINTAINERS tells the contributor where to send patches for which files, it does not convey other subsystem-local infrastructure and mechanisms that aid development. + Example questions to consider: + - Are there notifications when patches are applied to the local tree, or merged upstream? - Does the subsystem have a patchwork instance? Are patchwork state @@ -55,6 +57,7 @@ be settled in soaking in linux-next in advance of the merge window opening. Clarify for the submitter the key dates (in terms rc release week) that patches might considered for merging and when patches need to wait for the next -rc. At a minimum: + - Last -rc for new feature submissions: New feature submissions targeting the next merge window should have their first posting for consideration before this point. Patches that @@ -72,6 +75,7 @@ wait for the next -rc. At a minimum: resubmit for the following merge window. Optional: + - First -rc at which the development baseline branch, listed in the overview section, should be considered ready for new submissions. @@ -85,3 +89,14 @@ section can also indicate a preferred style of update like, resend the full series, or privately send a reminder email. This section might also list how review works for this code area and methods to get feedback that are not directly from the maintainer. + +Existing profiles +----------------- + +For now, existing maintainer profiles are listed here; we will likely want +to do something different in the near future. + +.. toctree:: + :maxdepth: 1 + + ../nvdimm/maintainer-entry-profile -- cgit From 36bb9778fd11173f2dd1484e4f6797365e18c1d8 Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Sun, 1 Dec 2019 08:45:54 -0700 Subject: docs: remove a bunch of stray CRs A pair of documentation patches introduced a bunch of unwanted carriage-return characters into the docs. Remove them, and chase away the ghost of DOS for another day. Fixes: a016e092940f ("docs: admin-guide: dell_rbu: Improve formatting and spelling") Fixes: bdd68860a044 ("Documentation: networking: device drivers: Remove stray asterisks") Signed-off-by: Jonathan Corbet --- Documentation/admin-guide/dell_rbu.rst | 6 +++--- Documentation/networking/device_drivers/intel/e100.rst | 14 +++++++------- Documentation/networking/device_drivers/intel/e1000.rst | 12 ++++++------ Documentation/networking/device_drivers/intel/e1000e.rst | 14 +++++++------- Documentation/networking/device_drivers/intel/fm10k.rst | 10 +++++----- Documentation/networking/device_drivers/intel/i40e.rst | 8 ++++---- Documentation/networking/device_drivers/intel/iavf.rst | 8 ++++---- Documentation/networking/device_drivers/intel/ice.rst | 6 +++--- Documentation/networking/device_drivers/intel/igb.rst | 12 ++++++------ Documentation/networking/device_drivers/intel/igbvf.rst | 6 +++--- Documentation/networking/device_drivers/intel/ixgbe.rst | 10 +++++----- Documentation/networking/device_drivers/intel/ixgbevf.rst | 6 +++--- Documentation/networking/device_drivers/pensando/ionic.rst | 6 +++--- 13 files changed, 59 insertions(+), 59 deletions(-) diff --git a/Documentation/admin-guide/dell_rbu.rst b/Documentation/admin-guide/dell_rbu.rst index 085ea129e6ca..8d70e1fc9f9d 100644 --- a/Documentation/admin-guide/dell_rbu.rst +++ b/Documentation/admin-guide/dell_rbu.rst @@ -1,6 +1,6 @@ -========================================= -Dell Remote BIOS Update driver (dell_rbu) -========================================= +========================================= +Dell Remote BIOS Update driver (dell_rbu) +========================================= Purpose ======= diff --git a/Documentation/networking/device_drivers/intel/e100.rst b/Documentation/networking/device_drivers/intel/e100.rst index 5a26a0e326ea..caf023cc88de 100644 --- a/Documentation/networking/device_drivers/intel/e100.rst +++ b/Documentation/networking/device_drivers/intel/e100.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -============================================================= -Linux Base Driver for the Intel(R) PRO/100 Family of Adapters -============================================================= +============================================================= +Linux Base Driver for the Intel(R) PRO/100 Family of Adapters +============================================================= June 1, 2018 @@ -21,7 +21,7 @@ Contents In This Release =============== -This file describes the Linux Base Driver for the Intel(R) PRO/100 Family of +This file describes the Linux Base Driver for the Intel(R) PRO/100 Family of Adapters. This driver includes support for Itanium(R)2-based systems. For questions related to hardware requirements, refer to the documentation @@ -138,9 +138,9 @@ version 1.6 or later is required for this functionality. The latest release of ethtool can be found from https://www.kernel.org/pub/software/network/ethtool/ -Enabling Wake on LAN (WoL) --------------------------- -WoL is provided through the ethtool utility. For instructions on +Enabling Wake on LAN (WoL) +-------------------------- +WoL is provided through the ethtool utility. For instructions on enabling WoL with ethtool, refer to the ethtool man page. WoL will be enabled on the system during the next shut down or reboot. For this driver version, in order to enable WoL, the e100 driver must be loaded diff --git a/Documentation/networking/device_drivers/intel/e1000.rst b/Documentation/networking/device_drivers/intel/e1000.rst index f146201f66a2..4aaae0f7d6ba 100644 --- a/Documentation/networking/device_drivers/intel/e1000.rst +++ b/Documentation/networking/device_drivers/intel/e1000.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -========================================================== -Linux Base Driver for Intel(R) Ethernet Network Connection -========================================================== +========================================================== +Linux Base Driver for Intel(R) Ethernet Network Connection +========================================================== Intel Gigabit Linux driver. Copyright(c) 1999 - 2013 Intel Corporation. @@ -438,10 +438,10 @@ ethtool The latest release of ethtool can be found from https://www.kernel.org/pub/software/network/ethtool/ -Enabling Wake on LAN (WoL) --------------------------- +Enabling Wake on LAN (WoL) +-------------------------- - WoL is configured through the ethtool utility. + WoL is configured through the ethtool utility. WoL will be enabled on the system during the next shut down or reboot. For this driver version, in order to enable WoL, the e1000 driver must be diff --git a/Documentation/networking/device_drivers/intel/e1000e.rst b/Documentation/networking/device_drivers/intel/e1000e.rst index c3205d43be56..f49cd370e7bf 100644 --- a/Documentation/networking/device_drivers/intel/e1000e.rst +++ b/Documentation/networking/device_drivers/intel/e1000e.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -===================================================== -Linux Driver for Intel(R) Ethernet Network Connection -===================================================== +===================================================== +Linux Driver for Intel(R) Ethernet Network Connection +===================================================== Intel Gigabit Linux driver. Copyright(c) 2008-2018 Intel Corporation. @@ -338,7 +338,7 @@ and higher cannot be forced. Use the autonegotiation advertising setting to manually set devices for 1 Gbps and higher. Speed, duplex, and autonegotiation advertising are configured through the -ethtool utility. +ethtool utility. Caution: Only experienced network administrators should force speed and duplex or change autonegotiation advertising manually. The settings at the switch must @@ -351,9 +351,9 @@ will not attempt to auto-negotiate with its link partner since those adapters operate only in full duplex and only at their native speed. -Enabling Wake on LAN (WoL) --------------------------- -WoL is configured through the ethtool utility. +Enabling Wake on LAN (WoL) +-------------------------- +WoL is configured through the ethtool utility. WoL will be enabled on the system during the next shut down or reboot. For this driver version, in order to enable WoL, the e1000e driver must be loaded diff --git a/Documentation/networking/device_drivers/intel/fm10k.rst b/Documentation/networking/device_drivers/intel/fm10k.rst index d165ac5c1403..4d279e64e221 100644 --- a/Documentation/networking/device_drivers/intel/fm10k.rst +++ b/Documentation/networking/device_drivers/intel/fm10k.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -============================================================= -Linux Base Driver for Intel(R) Ethernet Multi-host Controller -============================================================= +============================================================= +Linux Base Driver for Intel(R) Ethernet Multi-host Controller +============================================================= August 20, 2018 Copyright(c) 2015-2018 Intel Corporation. @@ -120,8 +120,8 @@ rx-flow-hash tcp4|udp4|ah4|esp4|sctp4|tcp6|udp6|ah6|esp6|sctp6 m|v|t|s|d|f|n|r Known Issues/Troubleshooting ============================ -Enabling SR-IOV in a 64-bit Microsoft Windows Server 2012/R2 guest OS under Linux KVM -------------------------------------------------------------------------------------- +Enabling SR-IOV in a 64-bit Microsoft Windows Server 2012/R2 guest OS under Linux KVM +------------------------------------------------------------------------------------- KVM Hypervisor/VMM supports direct assignment of a PCIe device to a VM. This includes traditional PCIe devices, as well as SR-IOV-capable devices based on the Intel Ethernet Controller XL710. diff --git a/Documentation/networking/device_drivers/intel/i40e.rst b/Documentation/networking/device_drivers/intel/i40e.rst index 3331d8960cca..8a9b18573688 100644 --- a/Documentation/networking/device_drivers/intel/i40e.rst +++ b/Documentation/networking/device_drivers/intel/i40e.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -================================================================= -Linux Base Driver for the Intel(R) Ethernet Controller 700 Series -================================================================= +================================================================= +Linux Base Driver for the Intel(R) Ethernet Controller 700 Series +================================================================= Intel 40 Gigabit Linux driver. Copyright(c) 1999-2018 Intel Corporation. @@ -384,7 +384,7 @@ NOTE: You cannot set the speed for devices based on the Intel(R) Ethernet Network Adapter XXV710 based devices. Speed, duplex, and autonegotiation advertising are configured through the -ethtool utility. +ethtool utility. Caution: Only experienced network administrators should force speed and duplex or change autonegotiation advertising manually. The settings at the switch must diff --git a/Documentation/networking/device_drivers/intel/iavf.rst b/Documentation/networking/device_drivers/intel/iavf.rst index f963598cce61..84ac7e75f363 100644 --- a/Documentation/networking/device_drivers/intel/iavf.rst +++ b/Documentation/networking/device_drivers/intel/iavf.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -================================================================= -Linux Base Driver for Intel(R) Ethernet Adaptive Virtual Function -================================================================= +================================================================= +Linux Base Driver for Intel(R) Ethernet Adaptive Virtual Function +================================================================= Intel Ethernet Adaptive Virtual Function Linux driver. Copyright(c) 2013-2018 Intel Corporation. @@ -19,7 +19,7 @@ Contents Overview ======== -This file describes the iavf Linux Base Driver. This driver was formerly +This file describes the iavf Linux Base Driver. This driver was formerly called i40evf. The iavf driver supports the below mentioned virtual function devices and diff --git a/Documentation/networking/device_drivers/intel/ice.rst b/Documentation/networking/device_drivers/intel/ice.rst index 1b866d4d497a..ee43ea57d443 100644 --- a/Documentation/networking/device_drivers/intel/ice.rst +++ b/Documentation/networking/device_drivers/intel/ice.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -================================================================== -Linux Base Driver for the Intel(R) Ethernet Connection E800 Series -================================================================== +================================================================== +Linux Base Driver for the Intel(R) Ethernet Connection E800 Series +================================================================== Intel ice Linux driver. Copyright(c) 2018 Intel Corporation. diff --git a/Documentation/networking/device_drivers/intel/igb.rst b/Documentation/networking/device_drivers/intel/igb.rst index fe914a0384b5..87e560fe5eaa 100644 --- a/Documentation/networking/device_drivers/intel/igb.rst +++ b/Documentation/networking/device_drivers/intel/igb.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -========================================================== -Linux Base Driver for Intel(R) Ethernet Network Connection -========================================================== +========================================================== +Linux Base Driver for Intel(R) Ethernet Network Connection +========================================================== Intel Gigabit Linux driver. Copyright(c) 1999-2018 Intel Corporation. @@ -129,9 +129,9 @@ version is required for this functionality. Download it at: https://www.kernel.org/pub/software/network/ethtool/ -Enabling Wake on LAN (WoL) --------------------------- -WoL is configured through the ethtool utility. +Enabling Wake on LAN (WoL) +-------------------------- +WoL is configured through the ethtool utility. WoL will be enabled on the system during the next shut down or reboot. For this driver version, in order to enable WoL, the igb driver must be loaded diff --git a/Documentation/networking/device_drivers/intel/igbvf.rst b/Documentation/networking/device_drivers/intel/igbvf.rst index 3aae181be091..557fc020ef31 100644 --- a/Documentation/networking/device_drivers/intel/igbvf.rst +++ b/Documentation/networking/device_drivers/intel/igbvf.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -=========================================================== -Linux Base Virtual Function Driver for Intel(R) 1G Ethernet -=========================================================== +=========================================================== +Linux Base Virtual Function Driver for Intel(R) 1G Ethernet +=========================================================== Intel Gigabit Virtual Function Linux driver. Copyright(c) 1999-2018 Intel Corporation. diff --git a/Documentation/networking/device_drivers/intel/ixgbe.rst b/Documentation/networking/device_drivers/intel/ixgbe.rst index 4e5a35a4f241..f1d5233e5e51 100644 --- a/Documentation/networking/device_drivers/intel/ixgbe.rst +++ b/Documentation/networking/device_drivers/intel/ixgbe.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -=========================================================================== -Linux Base Driver for the Intel(R) Ethernet 10 Gigabit PCI Express Adapters -=========================================================================== +=========================================================================== +Linux Base Driver for the Intel(R) Ethernet 10 Gigabit PCI Express Adapters +=========================================================================== Intel 10 Gigabit Linux driver. Copyright(c) 1999-2018 Intel Corporation. @@ -519,8 +519,8 @@ The offload is also supported for ixgbe's VFs, but the VF must be set as Known Issues/Troubleshooting ============================ -Enabling SR-IOV in a 64-bit Microsoft Windows Server 2012/R2 guest OS ---------------------------------------------------------------------- +Enabling SR-IOV in a 64-bit Microsoft Windows Server 2012/R2 guest OS +--------------------------------------------------------------------- Linux KVM Hypervisor/VMM supports direct assignment of a PCIe device to a VM. This includes traditional PCIe devices, as well as SR-IOV-capable devices based on the Intel Ethernet Controller XL710. diff --git a/Documentation/networking/device_drivers/intel/ixgbevf.rst b/Documentation/networking/device_drivers/intel/ixgbevf.rst index 69b3c2c9935c..76bbde736f21 100644 --- a/Documentation/networking/device_drivers/intel/ixgbevf.rst +++ b/Documentation/networking/device_drivers/intel/ixgbevf.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -============================================================ -Linux Base Virtual Function Driver for Intel(R) 10G Ethernet -============================================================ +============================================================ +Linux Base Virtual Function Driver for Intel(R) 10G Ethernet +============================================================ Intel 10 Gigabit Virtual Function Linux driver. Copyright(c) 1999-2018 Intel Corporation. diff --git a/Documentation/networking/device_drivers/pensando/ionic.rst b/Documentation/networking/device_drivers/pensando/ionic.rst index ec3c981124ea..c17d680cf334 100644 --- a/Documentation/networking/device_drivers/pensando/ionic.rst +++ b/Documentation/networking/device_drivers/pensando/ionic.rst @@ -1,8 +1,8 @@ .. SPDX-License-Identifier: GPL-2.0+ -======================================================== -Linux Driver for the Pensando(R) Ethernet adapter family -======================================================== +======================================================== +Linux Driver for the Pensando(R) Ethernet adapter family +======================================================== Pensando Linux Ethernet driver. Copyright(c) 2019 Pensando Systems, Inc -- cgit