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

2f9ef055 · Linus Torvalds <[email protected]> · 2021-04-26 13:22:43 -07:00

Pull documentation updates from Jonathan Corbet:
 "It's been a relatively busy cycle in docsland, though more than
  usually well contained to Documentation/ itself. Highlights include:

   - The Chinese translators have been busy and show no signs of
     stopping anytime soon. Italian has also caught up.

   - Aditya Srivastava has been working on improvements to the
     kernel-doc script.

   - Thorsten continues his work on reporting-issues.rst and related
     documentation around regression reporting.

   - Lots of documentation updates, typo fixes, etc. as usual"

* tag 'docs-5.13' of git://git.lwn.net/linux: (139 commits)
  docs/zh_CN: add openrisc translation to zh_CN index
  docs/zh_CN: add openrisc index.rst translation
  docs/zh_CN: add openrisc todo.rst translation
  docs/zh_CN: add openrisc openrisc_port.rst translation
  docs/zh_CN: add core api translation to zh_CN index
  docs/zh_CN: add core-api index.rst translation
  docs/zh_CN: add core-api irq index.rst translation
  docs/zh_CN: add core-api irq irqflags-tracing.rst translation
  docs/zh_CN: add core-api irq irq-domain.rst translation
  docs/zh_CN: add core-api irq irq-affinity.rst translation
  docs/zh_CN: add core-api irq concepts.rst translation
  docs: sphinx-pre-install: don't barf on beta Sphinx releases
  scripts: kernel-doc: improve parsing for kernel-doc comments syntax
  docs/zh_CN: two minor fixes in zh_CN/doc-guide/
  Documentation: dev-tools: Add Testing Overview
  docs/zh_CN: add translations in zh_CN/dev-tools/gcov
  docs: reporting-issues: make people CC the regressions list
  MAINTAINERS: add regressions mailing list
  doc:it_IT: align Italian documentation
  docs/zh_CN: sync reporting-issues.rst
  ...

Commit: 2f9ef0559efbee18a10a3ca26eefe57f69918693
Parents: 0c855563 · 441ca977

Merge commit. Changes below are compared with the first parent: 0c855563.

Changes

133 files changed · +9868 −2059

File	Status	Add	Del	Content
.mailmap	modified	+3	−2	View file
CREDITS	modified	+1	−1	View file
Documentation/admin-guide/LSM/LoadPin.rst	modified	+3	−3	View file
Documentation/admin-guide/cgroup-v1/memory.rst	modified	+5	−2	View file
Documentation/admin-guide/dynamic-debug-howto.rst	modified	+1	−1	View file
Documentation/admin-guide/index.rst	modified	+0	−1	View file
Documentation/admin-guide/kernel-parameters.rst	modified	+1	−0	View file
Documentation/admin-guide/kernel-parameters.txt	modified	+2	−1	View file
Documentation/admin-guide/kernel-per-CPU-kthreads.rst	modified	+0	−20	View file
Documentation/admin-guide/mm/numaperf.rst	modified	+1	−1	View file
Documentation/admin-guide/reporting-bugs.rst	deleted	+0	−187	View before deletion
Documentation/admin-guide/reporting-issues.rst	modified	+620	−497	View file
Documentation/admin-guide/sysrq.rst	modified	+2	−2	View file
Documentation/arch.rst	added	+26	−0	View file
Documentation/arm/marvell.rst	modified	+80	−79	View file
Documentation/arm/uefi.rst	modified	+7	−0	View file
Documentation/conf.py	modified	+19	−12	View file
Documentation/core-api/rbtree.rst	modified	+1	−1	View file
Documentation/dev-tools/checkpatch.rst	added	+755	−0	View file
Documentation/dev-tools/gcov.rst	modified	+6	−2	View file
Documentation/dev-tools/index.rst	modified	+5	−0	View file
Documentation/dev-tools/testing-overview.rst	added	+117	−0	View file
Documentation/devicetree/bindings/submitting-patches.rst	modified	+2	−2	View file
Documentation/driver-api/driver-model/class.rst	deleted	+0	−149	View before deletion
Documentation/driver-api/driver-model/device.rst	modified	+17	−6	View file
Documentation/driver-api/driver-model/index.rst	modified	+0	−1	View file
Documentation/driver-api/gpio/intro.rst	modified	+1	−1	View file
Documentation/fb/fbcon.rst	modified	+2	−2	View file
Documentation/features/arch-support.txt	modified	+1	−0	View file
Documentation/features/vm/TLB/arch-support.txt	modified	+1	−1	View file
Documentation/filesystems/api-summary.rst	modified	+9	−0	View file
Documentation/filesystems/proc.rst	modified	+4	−0	View file
Documentation/filesystems/vfat.rst	modified	+1	−1	View file
Documentation/hid/intel-ish-hid.rst	modified	+1	−1	View file
Documentation/index.rst	modified	+2	−18	View file
Documentation/input/event-codes.rst	modified	+5	−5	View file
Documentation/input/ff.rst	modified	+3	−3	View file
Documentation/input/gameport-programming.rst	modified	+23	−12	View file
Documentation/input/input-programming.rst	modified	+10	−10	View file
Documentation/input/input.rst	modified	+4	−4	View file
Documentation/input/multi-touch-protocol.rst	modified	+4	−4	View file
Documentation/input/notifier.rst	modified	+2	−1	View file
Documentation/input/uinput.rst	modified	+1	−1	View file
Documentation/leds/leds-lm3556.rst	modified	+14	−14	View file
Documentation/livepatch/shadow-vars.rst	modified	+2	−2	View file
Documentation/powerpc/booting.rst	modified	+1	−1	View file
Documentation/powerpc/dawr-power9.rst	modified	+1	−1	View file
Documentation/powerpc/eeh-pci-error-recovery.rst	modified	+1	−1	View file
Documentation/powerpc/elfnote.rst	modified	+1	−1	View file
Documentation/powerpc/firmware-assisted-dump.rst	modified	+2	−2	View file
Documentation/powerpc/kaslr-booke32.rst	modified	+1	−1	View file
Documentation/powerpc/mpc52xx.rst	modified	+1	−1	View file
Documentation/powerpc/papr_hcalls.rst	modified	+2	−2	View file
Documentation/powerpc/transactional_memory.rst	modified	+2	−2	View file
Documentation/process/submitting-patches.rst	modified	+67	−34	View file
Documentation/scsi/ChangeLog.megaraid	modified	+1	−1	View file
Documentation/sphinx/rstFlatTable.py	modified	+2	−2	View file
Documentation/spi/butterfly.rst	modified	+1	−1	View file
Documentation/translations/it_IT/doc-guide/sphinx.rst	modified	+28	−19	View file
Documentation/translations/it_IT/kernel-hacking/hacking.rst	modified	+1	−1	View file
Documentation/translations/it_IT/kernel-hacking/locking.rst	modified	+4	−8	View file
Documentation/translations/it_IT/process/4.Coding.rst	modified	+4	−5	View file
Documentation/translations/it_IT/process/adding-syscalls.rst	modified	+1	−1	View file
Documentation/translations/it_IT/process/coding-style.rst	modified	+19	−3	View file
Documentation/translations/it_IT/process/howto.rst	modified	+12	−13	View file
Documentation/translations/it_IT/process/magic-number.rst	modified	+0	−2	View file
Documentation/translations/it_IT/process/submit-checklist.rst	modified	+11	−10	View file
Documentation/translations/it_IT/process/submitting-patches.rst	modified	+80	−18	View file
Documentation/translations/ja_JP/SubmitChecklist	modified	+3	−5	View file
Documentation/translations/ko_KR/howto.rst	modified	+9	−9	View file
Documentation/translations/zh_CN/admin-guide/README.rst	added	+347	−0	View file
Documentation/translations/zh_CN/admin-guide/bug-bisect.rst	added	+81	−0	View file
Documentation/translations/zh_CN/admin-guide/bug-hunting.rst	added	+340	−0	View file
Documentation/translations/zh_CN/admin-guide/index.rst	modified	+14	−5	View file
Documentation/translations/zh_CN/admin-guide/init.rst	added	+54	−0	View file
Documentation/translations/zh_CN/admin-guide/reporting-issues.rst	added	+1335	−0	View file
Documentation/translations/zh_CN/admin-guide/security-bugs.rst	added	+74	−0	View file
Documentation/translations/zh_CN/admin-guide/tainted-kernels.rst	added	+157	−0	View file
Documentation/translations/zh_CN/admin-guide/unicode.rst	added	+170	−0	View file
Documentation/translations/zh_CN/core-api/index.rst	added	+126	−0	View file
Documentation/translations/zh_CN/core-api/irq/concepts.rst	added	+24	−0	View file
Documentation/translations/zh_CN/core-api/irq/index.rst	added	+19	−0	View file
Documentation/translations/zh_CN/core-api/irq/irq-affinity.rst	added	+76	−0	View file
Documentation/translations/zh_CN/core-api/irq/irq-domain.rst	added	+227	−0	View file
Documentation/translations/zh_CN/core-api/irq/irqflags-tracing.rst	added	+45	−0	View file
Documentation/translations/zh_CN/cpu-freq/core.rst	added	+105	−0	View file
Documentation/translations/zh_CN/cpu-freq/cpu-drivers.rst	added	+259	−0	View file
Documentation/translations/zh_CN/cpu-freq/cpufreq-stats.rst	added	+130	−0	View file
Documentation/translations/zh_CN/cpu-freq/index.rst	added	+45	−0	View file
Documentation/translations/zh_CN/dev-tools/gcov.rst	added	+264	−0	View file
Documentation/translations/zh_CN/dev-tools/index.rst	added	+35	−0	View file
Documentation/translations/zh_CN/disclaimer-zh_CN.rst	modified	+1	−1	View file
Documentation/translations/zh_CN/doc-guide/contributing.rst	added	+238	−0	View file
Documentation/translations/zh_CN/doc-guide/index.rst	added	+27	−0	View file
Documentation/translations/zh_CN/doc-guide/kernel-doc.rst	added	+499	−0	View file
Documentation/translations/zh_CN/doc-guide/maintainer-profile.rst	added	+43	−0	View file
Documentation/translations/zh_CN/doc-guide/parse-headers.rst	added	+187	−0	View file
Documentation/translations/zh_CN/doc-guide/sphinx.rst	added	+415	−0	View file
Documentation/translations/zh_CN/index.rst	modified	+10	−0	View file
Documentation/translations/zh_CN/kernel-hacking/hacking.rst	added	+708	−0	View file
Documentation/translations/zh_CN/kernel-hacking/index.rst	added	+22	−0	View file
Documentation/translations/zh_CN/openrisc/index.rst	added	+30	−0	View file
Documentation/translations/zh_CN/openrisc/openrisc_port.rst	added	+124	−0	View file
Documentation/translations/zh_CN/openrisc/todo.rst	added	+20	−0	View file
Documentation/translations/zh_CN/process/1.Intro.rst	modified	+102	−93	View file
Documentation/translations/zh_CN/process/2.Process.rst	modified	+175	−170	View file
Documentation/translations/zh_CN/process/3.Early-stage.rst	modified	+73	−66	View file
Documentation/translations/zh_CN/process/4.Coding.rst	modified	+141	−138	View file
Documentation/translations/zh_CN/process/5.Posting.rst	modified	+125	−118	View file
Documentation/translations/zh_CN/process/6.Followthrough.rst	modified	+86	−79	View file
Documentation/translations/zh_CN/process/7.AdvancedTopics.rst	modified	+75	−66	View file
Documentation/translations/zh_CN/process/8.Conclusion.rst	modified	+33	−27	View file
Documentation/translations/zh_CN/process/index.rst	modified	+5	−5	View file
Documentation/translations/zh_CN/process/submit-checklist.rst	modified	+6	−8	View file
Documentation/translations/zh_CN/riscv/boot-image-header.rst	added	+67	−0	View file
Documentation/translations/zh_CN/riscv/index.rst	added	+28	−0	View file
Documentation/translations/zh_CN/riscv/patch-acceptance.rst	added	+31	−0	View file
Documentation/translations/zh_CN/riscv/pmu.rst	added	+233	−0	View file
Documentation/translations/zh_CN/sound/hd-audio/controls.rst	added	+102	−0	View file
Documentation/translations/zh_CN/sound/hd-audio/index.rst	added	+14	−0	View file
Documentation/translations/zh_CN/sound/index.rst	added	+22	−0	View file
Documentation/userspace-api/ioctl/ioctl-number.rst	modified	+1	−0	View file
Documentation/virt/kvm/api.rst	modified	+1	−1	View file
Documentation/watchdog/pcwd-watchdog.rst	modified	+1	−1	View file
MAINTAINERS	modified	+21	−3	View file
fs/eventpoll.c	modified	+26	−26	View file
fs/namespace.c	modified	+8	−6	View file
scripts/checkpatch.pl	modified	+113	−20	View file
scripts/get_abi.pl	modified	+53	−21	View file
scripts/kernel-doc	modified	+52	−8	View file
scripts/sphinx-pre-install	modified	+1	−1	View file
tools/debugging/kernel-chktaint	modified	+1	−1	View file
tools/scripts/Makefile.include	modified	+2	−1	View file

Only the first 600 diff lines are shown. Download the complete patch.

.mailmap

View file

diff --git a/.mailmap b/.mailmap
index b44be83..3e2bff9 100644
--- a/.mailmap
+++ b/.mailmap
@@ -25,8 +25,9 @@ Alexandre Belloni <[email protected]> <alexandre.belloni@free-electr
 Alexei Starovoitov <[email protected]> <[email protected]>
 Alexei Starovoitov <[email protected]> <[email protected]>
 Alexei Starovoitov <[email protected]> <[email protected]>
-Alex Shi <[email protected]> <[email protected]>
-Alex Shi <[email protected]> <[email protected]>
+Alex Shi <[email protected]> <[email protected]>
+Alex Shi <[email protected]> <[email protected]>
+Alex Shi <[email protected]> <[email protected]>
 Al Viro <[email protected]>
 Al Viro <[email protected]>
 Andi Kleen <[email protected]> <[email protected]>

CREDITS

View file

diff --git a/CREDITS b/CREDITS
index 91ea9b7..b8f9641 100644
--- a/CREDITS
+++ b/CREDITS
@@ -550,7 +550,7 @@ D: gadget layers, SPI subsystem, GPIO subsystem, and more than a few
 D: device drivers.  His encouragement also helped many engineers get
 D: started working on the Linux kernel.  David passed away in early
 D: 2011, and will be greatly missed.
-W: https://lkml.org/lkml/2011/4/5/36
+W: https://lore.kernel.org/lkml/[email protected]
 
 N: Gary Brubaker
 E: [email protected]

Documentation/admin-guide/LSM/LoadPin.rst

View file

diff --git a/Documentation/admin-guide/LSM/LoadPin.rst b/Documentation/admin-guide/LSM/LoadPin.rst
index 716ad9b..dd3ca68 100644
--- a/Documentation/admin-guide/LSM/LoadPin.rst
+++ b/Documentation/admin-guide/LSM/LoadPin.rst
@@ -11,8 +11,8 @@ restrictions without needing to sign the files individually.
 
 The LSM is selectable at build-time with ``CONFIG_SECURITY_LOADPIN``, and
 can be controlled at boot-time with the kernel command line option
-"``loadpin.enabled``". By default, it is enabled, but can be disabled at
-boot ("``loadpin.enabled=0``").
+"``loadpin.enforce``". By default, it is enabled, but can be disabled at
+boot ("``loadpin.enforce=0``").
 
 LoadPin starts pinning when it sees the first file loaded. If the
 block device backing the filesystem is not read-only, a sysctl is
@@ -28,4 +28,4 @@ different mechanisms such as ``CONFIG_MODULE_SIG`` and
 ``CONFIG_KEXEC_VERIFY_SIG`` to verify kernel module and kernel image while
 still use LoadPin to protect the integrity of other files kernel loads. The
 full list of valid file types can be found in ``kernel_read_file_str``
-defined in ``include/linux/fs.h``.
+defined in ``include/linux/kernel_read_file.h``.

Documentation/admin-guide/cgroup-v1/memory.rst

View file

diff --git a/Documentation/admin-guide/cgroup-v1/memory.rst b/Documentation/admin-guide/cgroup-v1/memory.rst
index 0936412..41191b5 100644
--- a/Documentation/admin-guide/cgroup-v1/memory.rst
+++ b/Documentation/admin-guide/cgroup-v1/memory.rst
@@ -360,8 +360,8 @@ U != 0, K = unlimited:
 
 U != 0, K < U:
     Kernel memory is a subset of the user memory. This setup is useful in
-    deployments where the total amount of memory per-cgroup is overcommited.
-    Overcommiting kernel memory limits is definitely not recommended, since the
+    deployments where the total amount of memory per-cgroup is overcommitted.
+    Overcommitting kernel memory limits is definitely not recommended, since the
     box can still run out of non-reclaimable memory.
     In this case, the admin could set up K so that the sum of all groups is
     never greater than the total memory, and freely set U at the cost of his
@@ -851,6 +851,9 @@ At reading, current status of OOM is shown.
 	  (if 1, oom-killer is disabled)
 	- under_oom	   0 or 1
 	  (if 1, the memory cgroup is under OOM, tasks may be stopped.)
+        - oom_kill         integer counter
+          The number of processes belonging to this cgroup killed by any
+          kind of OOM killer.
 
 11. Memory Pressure
 ===================

Documentation/admin-guide/dynamic-debug-howto.rst

View file

diff --git a/Documentation/admin-guide/dynamic-debug-howto.rst b/Documentation/admin-guide/dynamic-debug-howto.rst
index 6c04aea..b119b82 100644
--- a/Documentation/admin-guide/dynamic-debug-howto.rst
+++ b/Documentation/admin-guide/dynamic-debug-howto.rst
@@ -347,7 +347,7 @@ Examples
 				<debugfs>/dynamic_debug/control
 
   // enable messages in files of which the paths include string "usb"
-  nullarbor:~ # echo -n '*usb* +p' > <debugfs>/dynamic_debug/control
+  nullarbor:~ # echo -n 'file *usb* +p' > <debugfs>/dynamic_debug/control
 
   // enable all messages
   nullarbor:~ # echo -n '+p' > <debugfs>/dynamic_debug/control

Documentation/admin-guide/index.rst

View file

diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 423116c..dc00afc 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -35,7 +35,6 @@ problems and bugs in particular.
    :maxdepth: 1
 
    reporting-issues
-   Reporting bugs (obsolete) <reporting-bugs>
    security-bugs
    bug-hunting
    bug-bisect

Documentation/admin-guide/kernel-parameters.rst

View file

diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst
index 1132796..24302ca 100644
--- a/Documentation/admin-guide/kernel-parameters.rst
+++ b/Documentation/admin-guide/kernel-parameters.rst
@@ -140,6 +140,7 @@ parameter is applicable::
 	PPT	Parallel port support is enabled.
 	PS2	Appropriate PS/2 support is enabled.
 	RAM	RAM disk support is enabled.
+	RISCV	RISCV architecture is enabled.
 	RDT	Intel Resource Director Technology.
 	S390	S390 architecture is enabled.
 	SCSI	Appropriate SCSI support is enabled.

Documentation/admin-guide/kernel-parameters.txt

View file

diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 9b3c086..550cf2b 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -3471,7 +3471,8 @@
 
 	nr_uarts=	[SERIAL] maximum number of UARTs to be registered.
 
-	numa_balancing=	[KNL,X86] Enable or disable automatic NUMA balancing.
+	numa_balancing=	[KNL,ARM64,PPC,RISCV,S390,X86] Enable or disable automatic
+			NUMA balancing.
 			Allowed values are enable and disable
 
 	numa_zonelist_order= [KNL, BOOT] Select zonelist order for NUMA.

Documentation/admin-guide/kernel-per-CPU-kthreads.rst

View file

diff --git a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst
index 531f689..5e51ee5 100644
--- a/Documentation/admin-guide/kernel-per-CPU-kthreads.rst
+++ b/Documentation/admin-guide/kernel-per-CPU-kthreads.rst
@@ -332,23 +332,3 @@ To reduce its OS jitter, do at least one of the following:
 	kthreads from being created in the first place.  However, please
 	note that this will not eliminate OS jitter, but will instead
 	shift it to RCU_SOFTIRQ.
-
-Name:
-  watchdog/%u
-
-Purpose:
-  Detect software lockups on each CPU.
-
-To reduce its OS jitter, do at least one of the following:
-
-1.	Build with CONFIG_LOCKUP_DETECTOR=n, which will prevent these
-	kthreads from being created in the first place.
-2.	Boot with "nosoftlockup=0", which will also prevent these kthreads
-	from being created.  Other related watchdog and softlockup boot
-	parameters may be found in Documentation/admin-guide/kernel-parameters.rst
-	and Documentation/watchdog/watchdog-parameters.rst.
-3.	Echo a zero to /proc/sys/kernel/watchdog to disable the
-	watchdog timer.
-4.	Echo a large number of /proc/sys/kernel/watchdog_thresh in
-	order to reduce the frequency of OS jitter due to the watchdog
-	timer down to a level that is acceptable for your workload.

Documentation/admin-guide/mm/numaperf.rst

View file

diff --git a/Documentation/admin-guide/mm/numaperf.rst b/Documentation/admin-guide/mm/numaperf.rst
index c2f8264..1666973 100644
--- a/Documentation/admin-guide/mm/numaperf.rst
+++ b/Documentation/admin-guide/mm/numaperf.rst
@@ -151,7 +151,7 @@ Each cache level's directory provides its attributes. For example, the
 following shows a single cache level and the attributes available for
 software to query::
 
-	# tree sys/devices/system/node/node0/memory_side_cache/
+	# tree /sys/devices/system/node/node0/memory_side_cache/
 	/sys/devices/system/node/node0/memory_side_cache/
 	|-- index1
 	|   |-- indexing

Documentation/admin-guide/reporting-bugs.rst

View before deletion

diff --git a/Documentation/admin-guide/reporting-bugs.rst b/Documentation/admin-guide/reporting-bugs.rst
deleted file mode 100644
index 409fa91..0000000
--- a/Documentation/admin-guide/reporting-bugs.rst
+++ /dev/null
@@ -1,187 +0,0 @@
-.. _reportingbugs:
-
-.. note::
-
-   This document is obsolete, and will be replaced by
-   'Documentation/admin-guide/reporting-issues.rst' in the near future.
-
-Reporting bugs
-++++++++++++++
-
-Background
-==========
-
-The upstream Linux kernel maintainers only fix bugs for specific kernel
-versions.  Those versions include the current "release candidate" (or -rc)
-kernel, any "stable" kernel versions, and any "long term" kernels.
-
-Please see https://www.kernel.org/ for a list of supported kernels.  Any
-kernel marked with [EOL] is "end of life" and will not have any fixes
-backported to it.
-
-If you've found a bug on a kernel version that isn't listed on kernel.org,
-contact your Linux distribution or embedded vendor for support.
-Alternatively, you can attempt to run one of the supported stable or -rc
-kernels, and see if you can reproduce the bug on that.  It's preferable
-to reproduce the bug on the latest -rc kernel.
-
-
-How to report Linux kernel bugs
-===============================
-
-
-Identify the problematic subsystem
-----------------------------------
-
-Identifying which part of the Linux kernel might be causing your issue
-increases your chances of getting your bug fixed. Simply posting to the
-generic linux-kernel mailing list (LKML) may cause your bug report to be
-lost in the noise of a mailing list that gets 1000+ emails a day.
-
-Instead, try to figure out which kernel subsystem is causing the issue,
-and email that subsystem's maintainer and mailing list.  If the subsystem
-maintainer doesn't answer, then expand your scope to mailing lists like
-LKML.
-
-
-Identify who to notify
-----------------------
-
-Once you know the subsystem that is causing the issue, you should send a
-bug report.  Some maintainers prefer bugs to be reported via bugzilla
-(https://bugzilla.kernel.org), while others prefer that bugs be reported
-via the subsystem mailing list.
-
-To find out where to send an emailed bug report, find your subsystem or
-device driver in the MAINTAINERS file.  Search in the file for relevant
-entries, and send your bug report to the person(s) listed in the "M:"
-lines, making sure to Cc the mailing list(s) in the "L:" lines.  When the
-maintainer replies to you, make sure to 'Reply-all' in order to keep the
-public mailing list(s) in the email thread.
-
-If you know which driver is causing issues, you can pass one of the driver
-files to the get_maintainer.pl script::
-
-     perl scripts/get_maintainer.pl -f <filename>
-
-If it is a security bug, please copy the Security Contact listed in the
-MAINTAINERS file.  They can help coordinate bugfix and disclosure.  See
-:ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>` for more information.
-
-If you can't figure out which subsystem caused the issue, you should file
-a bug in kernel.org bugzilla and send email to
[email protected], referencing the bugzilla URL.  (For more
-information on the linux-kernel mailing list see
-http://vger.kernel.org/lkml/).
-
-
-Tips for reporting bugs
------------------------
-
-If you haven't reported a bug before, please read:
-
-	https://www.chiark.greenend.org.uk/~sgtatham/bugs.html
-
-	http://www.catb.org/esr/faqs/smart-questions.html
-
-It's REALLY important to report bugs that seem unrelated as separate email
-threads or separate bugzilla entries.  If you report several unrelated
-bugs at once, it's difficult for maintainers to tease apart the relevant
-data.
-
-
-Gather information
-------------------
-
-The most important information in a bug report is how to reproduce the
-bug.  This includes system information, and (most importantly)
-step-by-step instructions for how a user can trigger the bug.
-
-If the failure includes an "OOPS:", take a picture of the screen, capture
-a netconsole trace, or type the message from your screen into the bug
-report.  Please read "Documentation/admin-guide/bug-hunting.rst" before posting your
-bug report. This explains what you should do with the "Oops" information
-to make it useful to the recipient.
-
-This is a suggested format for a bug report sent via email or bugzilla.
-Having a standardized bug report form makes it easier for you not to
-overlook things, and easier for the developers to find the pieces of
-information they're really interested in.  If some information is not
-relevant to your bug, feel free to exclude it.
-
-First run the ver_linux script included as scripts/ver_linux, which
-reports the version of some important subsystems.  Run this script with
-the command ``awk -f scripts/ver_linux``.
-
-Use that information to fill in all fields of the bug report form, and
-post it to the mailing list with a subject of "PROBLEM: <one line
-summary from [1.]>" for easy identification by the developers::
-
-  [1.] One line summary of the problem:
-  [2.] Full description of the problem/report:
-  [3.] Keywords (i.e., modules, networking, kernel):
-  [4.] Kernel information
-  [4.1.] Kernel version (from /proc/version):
-  [4.2.] Kernel .config file:
-  [5.] Most recent kernel version which did not have the bug:
-  [6.] Output of Oops.. message (if applicable) with symbolic information
-       resolved (see Documentation/admin-guide/bug-hunting.rst)
-  [7.] A small shell script or example program which triggers the
-       problem (if possible)
-  [8.] Environment
-  [8.1.] Software (add the output of the ver_linux script here)
-  [8.2.] Processor information (from /proc/cpuinfo):
-  [8.3.] Module information (from /proc/modules):
-  [8.4.] Loaded driver and hardware information (/proc/ioports, /proc/iomem)
-  [8.5.] PCI information ('lspci -vvv' as root)
-  [8.6.] SCSI information (from /proc/scsi/scsi)
-  [8.7.] Other information that might be relevant to the problem
-         (please look in /proc and include all information that you
-         think to be relevant):
-  [X.] Other notes, patches, fixes, workarounds:
-
-
-Follow up
-=========
-
-Expectations for bug reporters
-------------------------------
-
-Linux kernel maintainers expect bug reporters to be able to follow up on
-bug reports.  That may include running new tests, applying patches,
-recompiling your kernel, and/or re-triggering your bug.  The most
-frustrating thing for maintainers is for someone to report a bug, and then
-never follow up on a request to try out a fix.
-
-That said, it's still useful for a kernel maintainer to know a bug exists
-on a supported kernel, even if you can't follow up with retests.  Follow
-up reports, such as replying to the email thread with "I tried the latest
-kernel and I can't reproduce my bug anymore" are also helpful, because
-maintainers have to assume silence means things are still broken.
-
-Expectations for kernel maintainers
------------------------------------
-
-Linux kernel maintainers are busy, overworked human beings.  Some times
-they may not be able to address your bug in a day, a week, or two weeks.
-If they don't answer your email, they may be on vacation, or at a Linux
-conference.  Check the conference schedule at https://LWN.net for more info:
-
-	https://lwn.net/Calendar/
-
-In general, kernel maintainers take 1 to 5 business days to respond to
-bugs.  The majority of kernel maintainers are employed to work on the
-kernel, and they may not work on the weekends.  Maintainers are scattered
-around the world, and they may not work in your time zone.  Unless you
-have a high priority bug, please wait at least a week after the first bug
-report before sending the maintainer a reminder email.
-
-The exceptions to this rule are regressions, kernel crashes, security holes,
-or userspace breakage caused by new kernel behavior.  Those bugs should be
-addressed by the maintainers ASAP.  If you suspect a maintainer is not
-responding to these types of bugs in a timely manner (especially during a
-merge window), escalate the bug to LKML and Linus Torvalds.
-
-Thank you!
-
-[Some of this is taken from Frohwalt Egerer's original linux-kernel FAQ]

Documentation/admin-guide/reporting-issues.rst

View file

diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
index 07879d0..48b4d0e 100644
--- a/Documentation/admin-guide/reporting-issues.rst
+++ b/Documentation/admin-guide/reporting-issues.rst
@@ -9,25 +9,6 @@
    (for example by the kernel's build system) might contain content taken from
    files which use a more restrictive license.
 
-.. important::
-
-   This document is being prepared to replace
-   'Documentation/admin-guide/reporting-bugs.rst'. The main work is done and
-   you are already free to follow its instructions when reporting issues to the
-   Linux kernel developers. But keep in mind, below text still needs a few
-   finishing touches and review. It was merged to the Linux kernel sources at
-   this stage to make this process easier and increase the text's visibility.
-
-   Any improvements for the text or other feedback is thus very much welcome.
-   Please send it to 'Thorsten Leemhuis <[email protected]>' and 'Jonathan
-   Corbet <[email protected]>', ideally with 'Linux kernel mailing list (LKML)
-   <[email protected]>' and the 'Linux Kernel Documentation List
-   <[email protected]>' in CC.
-
-   Areas in the text that still need work or discussion contain a hint like this
-   which point out the remaining issues; all of them start with the word "FIXME"
-   to make them easy to find.
-
 
 Reporting issues
 ++++++++++++++++
@@ -36,46 +17,43 @@ Reporting issues
 The short guide (aka TL;DR)
 ===========================
 
-If you're facing multiple issues with the Linux kernel at once, report each
-separately to its developers. Try your best guess which kernel part might be
-causing the issue. Check the :ref:`MAINTAINERS <maintainers>` file for how its
-developers expect to be told about issues. Note, it's rarely
-`bugzilla.kernel.org <https://bugzilla.kernel.org/>`_, as in almost all cases
-the report needs to be sent by email!
-
-Check the destination thoroughly for existing reports; also search the LKML
-archives and the web. Join existing discussion if you find matches. If you
-don't find any, install `the latest Linux mainline kernel
-<https://kernel.org/>`_. Make sure it's vanilla, thus is not patched or using
-add-on kernel modules. Also ensure the kernel is running in a healthy
-environment and is not already tainted before the issue occurs.
-
-If you can reproduce your issue with the mainline kernel, send a report to the
-destination you determined earlier. Make sure it includes all relevant
-information, which in case of a regression should mention the change that's
-causing it which can often can be found with a bisection. Also ensure the
-report reaches all people that need to know about it, for example the security
-team, the stable maintainers or the developers of the patch that causes a
-regression. Once the report is out, answer any questions that might be raised
-and help where you can. That includes keeping the ball rolling: every time a
-new rc1 mainline kernel is released, check if the issue is still happening
-there and attach a status update to your initial report.
-
-If you can not reproduce the issue with the mainline kernel, consider sticking
-with it; if you'd like to use an older version line and want to see it fixed
-there, first make sure it's still supported. Install its latest release as
-vanilla kernel. If you cannot reproduce the issue there, try to find the commit
-that fixed it in mainline or any discussion preceding it: those will often
-mention if backporting is planed or considered too complex. If backporting was
-not discussed, ask if it's in the cards. In case you don't find any commits or
-a preceding discussion, see the Linux-stable mailing list archives for existing
-reports, as it might be a regression specific to the version line. If it is,
-report it like you would report a problem in mainline (including the
-bisection).
-
-If you reached this point without a solution, ask for advice one the
-subsystem's mailing list.
-
+Are you facing a regression with vanilla kernels from the same stable or
+longterm series? One still supported? Then search the `LKML
+<https://lore.kernel.org/lkml/>`_ and the `Linux stable mailing list
+<https://lore.kernel.org/stable/>`_ archives for matching reports to join. If
+you don't find any, install `the latest release from that series
+<https://kernel.org/>`_. If it still shows the issue, report it to the stable
+mailing list ([email protected]) and CC the regressions list
+([email protected]).
+
+In all other cases try your best guess which kernel part might be causing the
+issue. Check the :ref:`MAINTAINERS <maintainers>` file for how its developers
+expect to be told about problems, which most of the time will be by email with a
+mailing list in CC. Check the destination's archives for matching reports;
+search the `LKML <https://lore.kernel.org/lkml/>`_ and the web, too. If you
+don't find any to join, install `the latest mainline kernel
+<https://kernel.org/>`_. If the issue is present there, send a report.
+
+The issue was fixed there, but you would like to see it resolved in a still
+supported stable or longterm series as well? Then install its latest release.
+If it shows the problem, search for the change that fixed it in mainline and
+check if backporting is in the works or was discarded; if it's neither, ask
+those who handled the change for it.
+
+**General remarks**: When installing and testing a kernel as outlined above,
+ensure it's vanilla (IOW: not patched and not using add-on modules). Also make
+sure it's built and running in a healthy environment and not already tainted
+before the issue occurs.
+
+If you are facing multiple issues with the Linux kernel at once, report each
+separately. While writing your report, include all information relevant to the
+issue, like the kernel and the distro used. In case of a regression, CC the
+regressions mailing list ([email protected]) to your report; also try
+to include the commit-id of the change causing it, which a bisection can find.
+
+Once the report is out, answer any questions that come up and help where you
+can. That includes keeping the ball rolling by occasionally retesting with newer
+releases and sending a status update afterwards.
 
 Step-by-step guide how to report issues to the kernel maintainers
 =================================================================
@@ -94,28 +72,23 @@ early if an issue that looks like a Linux kernel problem is actually caused by
 something else. These steps thus help to ensure the time you invest in this
 process won't feel wasted in the end:
 
- * Stop reading this document and report the problem to your vendor instead,
-   unless you are running the latest mainline kernel already or are willing to
-   install it. This kernel must not be modified or enhanced in any way, and
-   thus be considered 'vanilla'.
+ * Are you facing an issue with a Linux kernel a hardware or software vendor
+   provided? Then in almost all cases you are better off to stop reading this
+   document and reporting the issue to your vendor instead, unless you are
+   willing to install the latest Linux version yourself. Be aware the latter
+   will often be needed anyway to hunt down and fix issues.
+
+ * Perform a rough search for existing reports with your favorite internet
+   search engine; additionally, check the archives of the `Linux Kernel Mailing
+   List (LKML) <https://lore.kernel.org/lkml/>`_. If you find matching reports,
+   join the discussion instead of sending a new one.
 
  * See if the issue you are dealing with qualifies as regression, security
    issue, or a really severe problem: those are 'issues of high priority' that
    need special handling in some steps that are about to follow.
 
- * Check if your kernel was 'tainted' when the issue occurred, as the event
-   that made the kernel set this flag might be causing the issue you face.
-
- * Locate the driver or kernel subsystem that seems to be causing the issue.
-   Find out how and where its developers expect reports. Note: most of the
-   time this won't be bugzilla.kernel.org, as issues typically need to be sent
-   by mail to a maintainer and a public mailing list.
-
- * Search the archives of the bug tracker or mailing list in question
-   thoroughly for reports that might match your issue. Also check if you find
-   something with your favorite internet search engine or in the Linux Kernel
-   Mailing List (LKML) archives. If you find anything, join the discussion
-   instead of sending a new report.
+ * Make sure it's not the kernel's surroundings that are causing the issue
+   you face.
 
  * Create a fresh backup and put system repair and restore tools at hand.
 
@@ -123,8 +96,8 @@ process won't feel wasted in the end:
    kernel modules on-the-fly, which solutions like DKMS might be doing locally
    without your knowledge.
 
- * Make sure it's not the kernel's surroundings that are causing the issue
-   you face.
+ * Check if your kernel was 'tainted' when the issue occurred, as the event
+   that made the kernel set this flag might be causing the issue you face.
 
  * Write down coarsely how to reproduce the issue. If you deal with multiple
    issues at once, create separate notes for each of them and make sure they
@@ -132,20 +105,35 @@ process won't feel wasted in the end:
    needs to get reported to the kernel developers separately, unless they are
    strongly entangled.
 
+ * If you are facing a regression within a stable or longterm version line
+   (say something broke when updating from 5.10.4 to 5.10.5), scroll down to
+   'Dealing with regressions within a stable and longterm kernel line'.
+
+ * Locate the driver or kernel subsystem that seems to be causing the issue.
+   Find out how and where its developers expect reports. Note: most of the
+   time this won't be bugzilla.kernel.org, as issues typically need to be sent
+   by mail to a maintainer and a public mailing list.
+
+ * Search the archives of the bug tracker or mailing list in question
+   thoroughly for reports that might match your issue. If you find anything,
+   join the discussion instead of sending a new report.
+
 After these preparations you'll now enter the main part:
 
- * Install the latest Linux mainline kernel: that's where all issues get
-   fixed first, because it's the version line the kernel developers mainly
-   care about. Testing and reporting with the latest Linux stable kernel can
-   be an acceptable alternative in some situations, for example during the
-   merge window; but during that period you might want to suspend your efforts
-   till its end anyway.
+ * Unless you are already running the latest 'mainline' Linux kernel, better
+   go and install it for the reporting process. Testing and reporting with
+   the latest 'stable' Linux can be an acceptable alternative in some
+   situations; during the merge window that actually might be even the best
+   approach, but in that development phase it can be an even better idea to
+   suspend your efforts for a few days anyway. Whatever version you choose,
+   ideally use a 'vanilla' build. Ignoring these advices will dramatically
+   increase the risk your report will be rejected or ignored.
 
  * Ensure the kernel you just installed does not 'taint' itself when
    running.
 
  * Reproduce the issue with the kernel you just installed. If it doesn't show
-   up there, head over to the instructions for issues only happening with
+   up there, scroll down to the instructions for issues only happening with
    stable and longterm kernels.
 
  * Optimize your notes: try to find and write the most straightforward way to
@@ -154,8 +142,8 @@ After these preparations you'll now enter the main part:
    that hear about it for the first time. And if you learned something in this
    process, consider searching again for existing reports about the issue.
 
- * If the failure includes a stack dump, like an Oops does, consider decoding
-   it to find the offending line of code.
+ * If your failure involves a 'panic', 'Oops', 'warning', or 'BUG', consider
+   decoding the kernel log to find the line of code that triggered the error.
 
  * If your problem is a regression, try to narrow down when the issue was
    introduced as much as possible.
@@ -184,28 +172,54 @@ After these preparations you'll now enter the main part:
    help yourself, if you don't get any help or if it's unsatisfying.
 
 
+Reporting regressions within a stable and longterm kernel line
+--------------------------------------------------------------
+
+This subsection is for you, if you followed above process and got sent here at
+the point about regression within a stable or longterm kernel version line. You
+face one of those if something breaks when updating from 5.10.4 to 5.10.5 (a
+switch from 5.9.15 to 5.10.5 does not qualify). The developers want to fix such
+regressions as quickly as possible, hence there is a streamlined process to
+report them:
+
+ * Check if the kernel developers still maintain the Linux kernel version
+   line you care about: go to the  `front page of kernel.org
+   <https://kernel.org/>`_ and make sure it mentions
+   the latest release of the particular version line without an '[EOL]' tag.
+
+ * Check the archives of the `Linux stable mailing list